Import Upstream version 2.11
Fabian Wolff
6 years ago
| 0 | # All known problems with the manual pages in a full Fedora Core installation | |
| 1 | # | |
| 2 | # Send 1 was on 09 Dec 2003 | |
| 3 | # Send 2 was on 17 Feb 2004 | |
| 4 | # Send 3 was on 11 Jul 2004 | |
| 5 | # Send 4 was on 20 Nov 2004 | |
| 6 | # Send 5 was on 14 Jan 2005 | |
| 7 | # Send 6 was on 01 Jan 2007 | |
| 8 | # | |
| 9 | # * means there is no patch corresponding to this bug | |
| 10 | # | |
| 11 | & This patch adds new material to a patch previously acknowledged by you. | |
| 12 | The new bands will correct a problem previous versions of my validator | |
| 13 | did not catch, very likely relating to an error in or abuse of the | |
| 14 | .TP tag. | |
| 15 | A Dot or single-quote at start of line turns it into a garbage command. | |
| 16 | This is a serious error; some lines of your page get silently lost | |
| 17 | when it is formatted. | |
| 18 | B -[0-9] cannot be rendered in Docbook command-syntax markup. | |
| 19 | This is not technically an error, but it makes the page impossible | |
| 20 | to translate to DocBook. | |
| 21 | C Broken command synopsis syntax. This may mean you're using a | |
| 22 | construction in the command synopsis other than the standard | |
| 23 | [ ] | { }, or it may mean you have running text in the command synopsis | |
| 24 | section (the latter is not technically an error, but it's impossible | |
| 25 | to translate into DocBook markup). | |
| 26 | D Section or macro out of place; this confuses translators. | |
| 27 | E My translator trips over a useless command in list markup. | |
| 28 | F List structure can be better expressed with .IP. | |
| 29 | G Since this page was generated from db2man, I understand that | |
| 30 | some of its problems may be due to db2man bugs that need to be reported | |
| 31 | upstream. I am sending this heads-up nevertheless because at least | |
| 32 | some of the problems can be fixed or worked around in your sources. | |
| 33 | H Illegal metavariable in a Synopsis description. | |
| 34 | I .it or .ti macro use is impossible to translate structurally. | |
| 35 | J Ambiguous or invalid backslash. This doesn't cause groff a problem. | |
| 36 | but it confuses doclifter and may confuse older troff implementations. | |
| 37 | K You seem to be distributing a formatted manual page or some sort of | |
| 38 | plain-text rather than source. This may be a packaging error. | |
| 39 | L List syntax error. This means .IP, .TP or .RS/.RE markup is garbled. | |
| 40 | This confuses doclifter, and may also mess up stricter troff | |
| 41 | interpreters like Xman and Rosetta. | |
| 42 | M Macro definition is in a location (such as the Synopsis section) | |
| 43 | that confuses translation tools. | |
| 44 | N Unbalanced or superfluous quotes may screw up argument parsing. | |
| 45 | O Running text in what should be a Unix command synopsis. | |
| 46 | The right fix for this is to change the section name. | |
| 47 | P Bogus eqn directive embedded in TBL option header. | |
| 48 | Q You used .UN where .UR is needed. | |
| 49 | R English spelling or usage errors, apparently the writer is not a | |
| 50 | native speaker. | |
| 51 | S DEPRECATED: in function syntax connot be translated. Also, the | |
| 52 | code and examples need to be marked up better. | |
| 53 | T There are multiple description lines. This makes it impossible to | |
| 54 | translate the page to DocBook. It may also confuse some | |
| 55 | implementations of man -k. | |
| 56 | U Unbalanced group in command synopis. You probably forgot | |
| 57 | to open or close a [ ] or { } group properly. | |
| 58 | V .DS and .DE input macros are swapped. | |
| 59 | W Missing or garbled name section. The most common form of garbling | |
| 60 | is a missing - or extra -. Or your manual page may have been generated | |
| 61 | by a tool that doesn't emit a NAME section as it should. Or your page | |
| 62 | may add running text such as a version or authorship banner. These | |
| 63 | problems make it impossible to lift the page to DocBook. They | |
| 64 | can also confuse third-party manpage browsers and some implementations | |
| 65 | of man -k. | |
| 66 | X Unknown or invalid macro. That is, one that does not fit in the | |
| 67 | macro set that the man page seems to be using. This is a serious | |
| 68 | error; it often means part of your text is being lost or rendered | |
| 69 | incorrectly. | |
| 70 | Y Missing or garbled section header. | |
| 71 | Z Garbage character at beginning of file. | |
| 72 | a .EX/.EE macros are missing or misplaced. | |
| 73 | b Attempt to interpolate unknown string. | |
| 74 | c SYNOPSIS must come before DESCRIPTION or other sections. Otherwise | |
| 75 | correctness-checking library pages that may have multiple Synopsis | |
| 76 | subheadings becomes too difficult. | |
| 77 | d This old-style C prototype is too hard to parse, best to fix it. | |
| 78 | e Garbage generated by docbook2man | |
| 79 | f Presentational use of .SH or .SS messes up section parsing. | |
| 80 | g Run-on .B or .I macro. | |
| 81 | h Unnecessary and unused .ta call may cause converters to error out. | |
| 82 | i Macro invocation in conditional confuses the doclifter parser. | |
| 83 | j Parenthesized comments in command synopsis. This is impossible | |
| 84 | to translate to DocBook. | |
| 85 | k It is not necessary, and bad style, to specify the absolute pathname | |
| 86 | of a command in its synopsis. | |
| 87 | l Page consists solely of NAME and SYNOPSIS. | |
| 88 | m Contains a request or escape that is outside the portable subset that | |
| 89 | can be rendered by non-groff viewers such as the KDE and GNOME help | |
| 90 | browsers. | |
| 91 | n Unbalanced .RS or .RE macro | |
| 92 | o TBL markup not used where it should be. Tables stitched together | |
| 93 | with .ta requests can't be lifted to DocBook and will often | |
| 94 | choke third-party viewers such as TKMan, XMan, Rosetta, etc. | |
| 95 | p It is unnecessary to explain basic shell redirects on a man page. | |
| 96 | It is also bad style, especially when doing so produces an | |
| 97 | unparseable SYNOPSIS section. | |
| 98 | q Formatting file lists as tables in a Synopsis is impossible to | |
| 99 | translate into DocBook. | |
| 100 | r .Ss within a Synopsis confuses my section parser. | |
| 101 | s Example URLs which should *not* be turned into hyperlinks need | |
| 102 | an invisible stopper so tools which try to lift URLs from the page | |
| 103 | source will pass over them. | |
| 104 | t Unclosed .RS, appears to be a broken attempt to express list structure. | |
| 105 | u Use local definitions of .EX/.EE or .DS/.DE to avoid low-level troff | |
| 106 | requests in the page body. There are plans to add these to groff man; | |
| 107 | in the interim, this patch adds a compatible definition to your page. | |
| 108 | v Doubled dot before macro command. | |
| 109 | w You wrote .br where you meant .sp -- as written, the markup will | |
| 110 | fail to produce a blank line where one was clearly intended. | |
| 111 | x Unclosed .nf needs a .fi | |
| 112 | y Page is empty. This probably means there is some sort of glitch in | |
| 113 | your build machinery. | |
| 114 | z .TP or other markup used where .SS is needed, or the reverse. | |
| 115 | 0 This problem reflects a serious bug in db2man. | |
| 116 | 1 Improper line wrap in .ds text. | |
| 117 | 2 Description as well as name is required in a name section. | |
| 118 | 3 Garbled escape sequence | |
| 119 | 4 SYNTAX section is actually a Unix SYNOPSIS and should be so marked. | |
| 120 | 5 Unescaped \d looks like a troff down-motion. This probably messes | |
| 121 | up the rendering of the page in some environments, and certainly | |
| 122 | confuses automated translation to XML. | |
| 123 | 6 The extended macros from the *roff pages screw up third-party readers | |
| 124 | like Xman and the KDE help browser as well as doclifter. The hot | |
| 125 | topic on the groff mailing list is how to get rid of them. | |
| 126 | 7 Unbalanced highlights. This is not technically an error, but | |
| 127 | it makes display programs and translators to other formats | |
| 128 | much more likely to break. | |
| 129 | 8 Use of low-level troff hackery to set special indents or breaks can't | |
| 130 | be translated. The page will have rendering faults in HTML, and | |
| 131 | probably also under third-party man page browsers such as Xman, | |
| 132 | Rosetta, and the KDE help browser. This patch eliminates .br, .ta, .ti | |
| 133 | and .in in favor of requests like .nf/.fi, and .RS/.RE that have | |
| 134 | structural translations. | |
| 135 | 9 Macro call is run on to the end of a line. | |
| 136 | @ SYNOPSIS section is not a Unix command synopsis and should be renamed. | |
| 137 | ! BSD .Oo/.Oc is not handled correctly by some viewers, so is not portable. | |
| 138 | %% | |
| 139 | b|ac.1 | |sgk@sgk.tiac.net | |
| 140 | bn|acl_from_text.3,acl_to_text.3 |X | | |
| 141 | bn|adjtimex.8 |X |jrv@voyager.mv.com | |
| 142 | 6n|read-expenses.1 |O8 |pilot-link-devel@pilot-link.org | |
| 143 | 1p|aconnect.1 |u |tiwai@suse.de,alsa-devel@lists.sourceforge.net | |
| 144 | 6n|addresses.1 |p |pilot-link-devel@pilot-link.org | |
| 145 | b|aecho.1 | |netatalk-devel@lists.sourceforge.net | |
| 146 | y|afmtodit.1 |M |bug-groff@gnu.org | |
| 147 | 1n|afm2tfm.1 |8 |rokicki@cs.stanford.edu | |
| 148 | 1n|aimk.1 |8 |gst@ornl.gov | |
| 149 | y|amidi.1,amixer.1,aplay.1,arecord.1 | |Clemens Ladisch <clemens@ladisch.de> | |
| 150 | bn|amrecover.8 |9 | | |
| 151 | n|analog.1 |C |analog-author@lists.meer.net | |
| 152 | b|apple_cp.1,apple_mv.1 |Ck |netatalk-devel@lists.sourceforge.net | |
| 153 | n|apport-retrace.1 |g |martin.pitt@ubuntu.com | |
| 154 | 1n|awk.1 |u |bug-gawk@gnu.org | |
| 155 | 1n|pgawk.1,gawk.1 |u |bug-gawk@gnu.org | |
| 156 | y|animate.1,compare.1,conjure.1,composite.1,convert.1,display.1,identify.1,import.1,mogrify.1,montage.1 | |magick-bugs@imagemagick.org | |
| 157 | 1n|amanda.8,amanda.conf.5,amrestore.8 |A0 |sgw@amanda.org | |
| 158 | y|apple_cp.1,apple_mv.1,apple_rm.1| |netatalk-devel@lists.sourceforge.net | |
| 159 | 6n|arp.8 |A |Bernd Eckenfels <net-tools@lina.inka.de> | |
| 160 | 1n|ApplicationShell.3 |E |lesstif-discuss@lists.sourceforge.net | |
| 161 | 1p|appres.1x |U |xorg@lists.freedesktop.org | |
| 162 | 1n|aspell.1 |X |pyro@debian.org | |
| 163 | bn|atmsigd.conf.4 |A |Werner.Almesberger@epfl.ch | |
| 164 | 1n|auditd.8 |J |linux-audit@redhat.com | |
| 165 | p|authconfig.8 |C |Nalin Dahyabhai <nalin@redhat.com> | |
| 166 | y|bash.1 | |bug-bash@gnu.org | |
| 167 | y|bgpd.8 | |bug-zebra@gnu.org | |
| 168 | n|biof.1 |X |hk@dgmr.nl | |
| 169 | 1p|bitmap.1x |XJ |xorg@lists.freedesktop.org | |
| 170 | 1n|bounce.5,aliases.postfix.5,relocated.5,virtual.8|8 |wietse@porcupine.org | |
| 171 | 1n|header_checks.5|8J |wietse@porcupine.org | |
| 172 | 1n|builtins.1 |W |bug-bash@gnu.org | |
| 173 | y|bzadmin.6 | |bzflag-dev@lists.sourceforge.net | |
| 174 | 1n|bzw.5 |8 |bzflag-dev@lists.sourceforge.net | |
| 175 | 3n*|bzfquery.6 |l |bzflag-dev@lists.sourceforge.net | |
| 176 | y|bzfs.6 | |bzflag-dev@lists.sourceforge.net | |
| 177 | 5y|cadaver.1 | |Joe Orton <cadaver@webdav.org> | |
| 178 | 1p|calcomp.4 | |xorg@lists.freedesktop.org | |
| 179 | y|cancel-cups.1,cancel.1,lp.1,lp-cups.1 | | | |
| 180 | 6n|cannastat.1 |C |Canna@nec.co.jp | |
| 181 | 1n|cman.5 |8 | | |
| 182 | 1n|compress.1,uncompress.1 |J |peter@ncs.nl | |
| 183 | y|CrtImgType.3,Tk_InitImageArgs.3| |tcl-core@lists.sourceforge.net | |
| 184 | 1n|ctangle.1,cweave.1,cweb.1|L | | |
| 185 | 6n|lpr.1,lpr-cups.1 |U |papowell@lprng.com | |
| 186 | y|lpstat.1,lpstat-cups.1| |papowell@lprng.com | |
| 187 | 1n|cdda2wav.1 |A8 |schilling@fokus.fraunhofer.de | |
| 188 | n|cdparanoia.1 |8 |monty@xiph.org | |
| 189 | 6n|cdrdao.1 |E |cdrdao-devel@lists.sourceforge.net | |
| 190 | bn|chat.8 |XJ7 |paulus@samba.org | |
| 191 | 1n|chcat.8 |C |dwalsh@redhat.com | |
| 192 | bn|chkconfig.8 |X | | |
| 193 | 6n|chmoddic.1 |C |Canna@nec.co.jp | |
| 194 | 1n|citron.4 |@Ln |support@citron.de | |
| 195 | 1b|co.1 |o |rcs-bugs@gnu.org | |
| 196 | n|codepage.1 |C |mckinstry@computer.org | |
| 197 | 1n|cpufreq-info.1,cpufreq-set.1 |8 |linux@brodo.de,malattia@gmail.com | |
| 198 | y|crash.8 | |fenlason@redhat.com | |
| 199 | 6n|cshost.1 |C |Canna@nec.co.jp | |
| 200 | 3p|cscope.1 |B |broeker@users.sourceforge.net | |
| 201 | b|curl.1 |J | | |
| 202 | 1n|cvs.1 |JL |cvs-dev@nongnu.org | |
| 203 | bn|cxpm.1x |W |lehors@sophia.inria.fr | |
| 204 | 3b|dasher.1 |g | | |
| 205 | 1n|DBM_Filter::compress.3pm,DBM_Filter::encode.3pm,DBM_Filter::int32.3pm,DBM_Filter::null.3pm,DBM_Filter::utf8.3pm|W |perl-documentation@perl.org | |
| 206 | y|dbz.3 | |inn-bugs@isc.org | |
| 207 | y|ddd.1 | |ddd@gnu.org | |
| 208 | 6n|default.session.5 |W |miguel@gnu.org | |
| 209 | b|dhclient.8 |J8u |dhcp-client@isc.org | |
| 210 | 2n|dhcp6r.8 |f |bug@dhcpv6.org | |
| 211 | 1n|dicar.1 |X8 |Canna@nec.co.jp | |
| 212 | b|dictionary.5 |L |freeradius-devel@lists.freeradius.org | |
| 213 | 3n|dictfmt.1 |A |faith@cs.unc.edu | |
| 214 | 1n|dictl.1 |W |hilliard@debian.org, vle@gmx.net | |
| 215 | y|diffstat.1 | | | |
| 216 | n|dh_movefiles.1 |U |joeyh@debian.org | |
| 217 | y|dislocate.1 | |Don Libes <libes@nist.gov> | |
| 218 | 6n|dlpsh.1 |W |pilot-link-devel@pilot-link.org | |
| 219 | y|dmraid.8 | |Heinz Mauelshagen <Mauelshagen@RedHat.com> | |
| 220 | 1n|doxytag.1 |L |doxygen-users@lists.sourceforge.net | |
| 221 | bn|dpromdic.1 |X | | |
| 222 | 1b|dvgrab.1 |h |nn4lyahoode@thyrsus.com | |
| 223 | 1n|dvipdf.1,font2c.1 |u |epm@easysw.com | |
| 224 | 6n|dvdrecord.1 |v |dvdrtools-devel@nongnu.org | |
| 225 | y|dvipdfm.1 | |mwicks@kettering.edu | |
| 226 | 1n|editres.1x |8o |xorg@lists.freedesktop.org | |
| 227 | 1n|e2fsck.8 |o |tytso@thunk.org | |
| 228 | 1n|efax.1 |J |edc@cce.com | |
| 229 | 1n|enscript.1 |8 |mtr@iki.fi | |
| 230 | 6n|epic.1 |X |Jeremy Nelson <jnelson@acronet.net> | |
| 231 | 1n|elinkskeys.5 |GOJ |elinks-dev@linuxfromscratch.org | |
| 232 | 1n|emacs.1 |o |bug-gnu-emacs@prep.ai.mit.edu | |
| 233 | y|epoll_ctl.2 | |aeb@cwi.nl, davidel@xmailserver.org | |
| 234 | y|epoll.4 | |aeb@cwi.nl, davidel@xmailserver.org | |
| 235 | y|eqn.1,geqn.1 |n |bug-groff@gnu.org | |
| 236 | 1n|error.3 |7 |mtk-manpages@gmx.net | |
| 237 | 1n|openais_overview.8,evs_overview.8,cpg_overview.8|W |scd@broked.com | |
| 238 | 1n|expect.1 |u |Don Libes <libes@nist.gov> | |
| 239 | 1n|extractres.1 |u |angus@harlequin.co.uk | |
| 240 | 6p|fbset.8 |L |Geert.Uytterhoeven@cs.kuleuven.ac.be, zippel@fh-brandenburg.de | |
| 241 | n|fence_drac.8 |J | | |
| 242 | 1n|fence.8,gfs.8,gnbd.8 |W |linux-cluster@redhat.com | |
| 243 | 1n|fig2dev.1x |X |bvsmith@lbl.gov | |
| 244 | 1n|fig2ps2tex.1x |u |bvsmith@lbl.gov | |
| 245 | y|File::Basename.3pm | |perl-documentation@perl.org | |
| 246 | 3n|findchip.8,irdadump.8,irdaping.8,irpsion5.8,irattach.8|e |wehe@tuxmobil.org | |
| 247 | b*|firefox.1 |L |https://bugzilla.mozilla.org/show_bug.cgi?id=368356 | |
| 248 | y|flock.1 | |adam@yggdrasil.com | |
| 249 | n|flocks.1,lattice.1 |A |tugrul@galatali.com | |
| 250 | p|foomatic-ppdfile.1 |X |till.kamppeter@gmail.com | |
| 251 | 1n|foomatic-rip.1 |o6 |till.kamppeter@gmail.com | |
| 252 | 1n|free.1 |8 |albert@users.sf.net | |
| 253 | y|fsinfo.8 | |ezk@cs.columbia.edu | |
| 254 | y|gaim.1 | |Rob Flynn <gaim@robflynn.com> | |
| 255 | 3n|gda-config.5 | |gonzalo@gnome-db.org | |
| 256 | 1n|getafm.1 |o |rj@rainbow.in-berlin.de | |
| 257 | y|getcon.3,getexeccon.3 | |russell@coker.com.au | |
| 258 | 1n|gettimeofday.2 |u |mtk-manpages@gmx.net | |
| 259 | y|GetUid.3 | |tcl-core@lists.sourceforge.net | |
| 260 | 4n|getcontext.2 |C |mtk-manpages@gmx.net | |
| 261 | bn|getrpcport.3 |d | | |
| 262 | 1n|gfdl.1 |W | | |
| 263 | 1n|gfs_jadd.8 |X |linux-cluster@redhat.com | |
| 264 | bn|gftodvi.1 |8 | | |
| 265 | y|ghostscript.1 | |giles@snow.thaumas.net | |
| 266 | y|gij.1 | | | |
| 267 | 1n|gkrellmd.1 |L |bill@gkrellm.net | |
| 268 | 1n|glBegin.3gl,glBitmap.3gl,glBlendFunc.3gl,glCopyPixels.3gl,glDepthFunc.3gl,glDrawBuffer.3gl,glDrawPixels.3gl,glEnableClientState.3gl,glGetString.3gl,glGetTexGen.3gl,glGetTexImage.3gl,glGetTexParameter.3gl,glLight.3gl,glMatrixMode.3gl,glOrtho.3gl,glPixelTransfer.3gl,glRect.3gl,glTexCoord.3gl,glTexEnv.3gl,glTexImage1D.3gl,glTexImage2D.3gl,glTexImage3D.3gl,glXChooseVisual.3gl,glXGetConfig.3gl|X |mesa3d-dev@lists.sourceforge.net | |
| 269 | 1n|glPixelMap.3gl,glPixelStore.3gl|P |mesa3d-dev@lists.sourceforge.net | |
| 270 | 6n|gnome-session.1 |Y |Miguel de Icaza <miguel@gnu.org> | |
| 271 | 6n|gnome-wm.1 |W |Miguel de Icaza <miguel@gnu.org> | |
| 272 | 1p|gnuplot.1 |J |gnuplot-info@lists.sourceforge.net | |
| 273 | 1n|gnutls_psk_set_client_credentials.3,gnutls_x509_crt_get_key_purpose_oid.3,gnutls_x509_rdn_get_oid.3|L |gnutls-dev@gnupg.org | |
| 274 | y|gob2.1 | |George Lebl <jirka@5z.com> | |
| 275 | y|gpic.1,pic.1 |L |bug-groff@gnu.org | |
| 276 | 5p|gpm-types.7 |W |Nico Schottelius <nico-gpm@schottelius.org> | |
| 277 | y|groff.1 | |bug-groff@gnu.org | |
| 278 | y|groff_diff.7 |A |wl@gnu.org | |
| 279 | 1n|gthumb.1 |L |paolo.bacch@tin.it | |
| 280 | 1n|gulm_tool.8 |8 | | |
| 281 | n|hexdump.1 |! |bunk@stusta.de | |
| 282 | 6n|hformat.1,hfs.1,hfssh.1,hfsutils.1,hmount.1,xhfs.1 |X |Robert Leslie <rob@mars.org> | |
| 283 | 1n|hinotes.1 |JW |pilot-link-devel@pilot-link.org | |
| 284 | y|hidd.1 | |bluez-devel@lists.sourceforge.net | |
| 285 | y|hostname.1 | |Bernd Eckenfels <net-tools@lina.inka.de> | |
| 286 | 3n|htfuzzy.1 |A |htdig-dev@htdig.org | |
| 287 | 1n|hwclock.8 |C |bunk@stusta.de | |
| 288 | 1n|ibod.1 |X |Bjoern Smith <bjorn@Compound.SE> | |
| 289 | 1n|ibod.cf.4 |8 |Bjoern Smith <bjorn@Compound.SE> | |
| 290 | 1n|icc2ps.1,icclink.1,jpegicc.1,tifficc.1 |XRL |shiju.p@gmail.com | |
| 291 | y|idna_strerror.3,idna_to_ascii_4i.3,idna_to_ascii_4z.3,idna_to_ascii_8z.3,idna_to_ascii_lz.3,idna_to_unicode_44i.3,idna_to_unicode_4z4z.3,idna_to_unicode_8z4z.3,idna_to_unicode_8z8z.3,idna_to_unicode_8zlz.3,idna_to_unicode_lzlz.3,pr29_4.3,pr29_4z.3,pr29_8z.3,pr29_strerror.3,punycode_decode.3,punycode_strerror.3,stringprep.3,stringprep_4i.3,stringprep_4zi.3,stringprep_check_version.3,stringprep_convert.3,stringprep_locale_charset.3,stringprep_locale_to_utf8.3,stringprep_profile.3,stringprep_strerror.3,stringprep_ucs4_nfkc_normalize.3,stringprep_ucs4_to_utf8.3,stringprep_unichar_to_utf8.3,stringprep_utf8_nfkc_normalize.3,stringprep_utf8_to_locale.3,stringprep_utf8_to_ucs4.3,stringprep_utf8_to_unichar.3,tld_check_4.3,tld_check_4t.3,tld_check_4tz.3,tld_check_4z.3,tld_check_8z.3,tld_check_lz.3,tld_default_table.3,tld_get_4.3,tld_get_4z.3,tld_get_table.3,tld_get_z.3,tld_strerror.3 | |bug-libidn@gnu.org | |
| 292 | y|punycode_encode.3 | |bug-libidn@gnu.org | |
| 293 | n*|ifenslave.8 |K | | |
| 294 | 1n|iftab.5 |8u |jt@hpl.hp.com | |
| 295 | 1n|includeres.1 |8u |giles@artifex.com | |
| 296 | 1n|ImageMagick.1 |D |magick-bugs-owner@imagemagick.org | |
| 297 | 1n|imake.1x |u8 |xorg@lists.freedesktop.org | |
| 298 | n|inet.3 |u |mtk-manpages@gmx.net | |
| 299 | y|inews.1 | |inn-bugs@isc.org | |
| 300 | 1p|initlog.1 |J |notting@redhat.com | |
| 301 | n|innfeed.1 |L |inn-bugs@isc.org | |
| 302 | y|install.1 | |bug-coreutils@gnu.org | |
| 303 | 1n|ipppd.8 |L |keil@isdn4linux.de | |
| 304 | 3n|ipsec_mailkey.8 |H |hugh@mimosa.com | |
| 305 | 3n|ipsec_newhostkey.8,ipsec_rsasigkey.8 |C |hugh@mimosa.com | |
| 306 | 1n|ip6tables.8 |L |netfilter-devel@lists.netfilter.org | |
| 307 | 1n|iptables.8 |@JL |netfilter-devel@lists.netfilter.org | |
| 308 | 6n|iptraf.8 |X |riker@seul.org | |
| 309 | 1n|ipv6calc.8 |@uwL |pb@bieringer.de | |
| 310 | 6n|irb.1 |W |ruby-doc@ruby-lang.org | |
| 311 | 1n|irnet.4 |u8 |jt@hpl.hp.com | |
| 312 | 1n|irsend.1 |L |lirc@bartelmus.de | |
| 313 | y|isadump.8,isaset.8 | |phil@philedelbrock.com | |
| 314 | 1n|isdnrep.1 |J8m |paul@isdn4linux.de | |
| 315 | 1n|jng.5 |8 |png-implement@ccrc.wustl.edu | |
| 316 | 1n|kdesvn-build.1 |s |carlos.woelz@kdemail.net | |
| 317 | 1n|kermit.1 |W |kermit@columbia.edu | |
| 318 | 6n|klogd.8 |X |greg@wind.enjellic.com | |
| 319 | 1n|ksh.1 |@iL |dgk@research.att.com | |
| 320 | 6n|kwordtrans.1,wordtrans.1|K |rvm@escomposlinux.org | |
| 321 | 1p|lam-helpfile.5 |h |lam-devel@lam-mpi.org | |
| 322 | 1p|lamboot.1,lamexec.1 |X4 |lam-devel@lam-mpi.org | |
| 323 | 1p|lammsg.1 |8oC4 |lam-devel@lam-mpi.org | |
| 324 | 1p|lamrun.1 |4 |lam-devel@lam-mpi.org | |
| 325 | 1p|lamtask.1 |4o |lam-devel@lam-mpi.org | |
| 326 | 1p|lamshrink.1 |C4 |lam-devel@lam-mpi.org | |
| 327 | bn|lame.1 |X |lam-devel@lam-mpi.org | |
| 328 | 1n|lastcomm.1 |uo |bug-gnu-utils@gnu.org | |
| 329 | 1p|LAM.7,MPI.7 |@8L |lam-devel@lam-mpi.org | |
| 330 | b|lastlog.8 |L | | |
| 331 | y|latex.1 | |te@dbs.uni-hannover.de | |
| 332 | 1n|latex2html.1 |Q |Manoj Srivastava <srivasta@debian.org> | |
| 333 | n|lattice.1 |A |tugrul@galatali.com | |
| 334 | y|LDP.7 | | | |
| 335 | 1n|ld.so.8 |L |mtk-manpages@gmx.net | |
| 336 | 6n|less.1 |C |bug-less@gnu.org | |
| 337 | 1n|lesstif.1 |WO8 |lesstif-discuss@lists.sourceforge.net | |
| 338 | 1n|libbind-getipnodebyname.3|T |bind9-bugs@isc.org | |
| 339 | 1n|libbind-resolver.3 |r |bind9-bugs@isc.org | |
| 340 | 4n|libpng.3 |S |png-implement@ccrc.wustl.edu | |
| 341 | y|libpngpf.3 | |png-implement@ccrc.wustl.edu | |
| 342 | 1n|libexpect.3 |O |Don Libes <libes@nist.gov> | |
| 343 | 1n|libmng.3 |7 |gerard@libmng.com | |
| 344 | 6n|linuxdoc.1 |j |Taketoshi Sano <sano@debian.org> | |
| 345 | 1n|ln.1 |j |bug-coreutils@gnu.org | |
| 346 | p|locate.1 |J |mitr@redhat.com | |
| 347 | 1n|lock_gulmd.5 |8 |dwalsh@redhat.com | |
| 348 | 1n|lock_gulmd.8 |@8 |dwalsh@redhat.com | |
| 349 | y|logrotate.8 | | | |
| 350 | 1p|lsof.8 |J |abe@purdue.edu | |
| 351 | 6n|lv.1 |C |nrt@ff.iij4u.or.jp | |
| 352 | 1n|lvm.8 |L |lvm-devel@lists.sistina.com | |
| 353 | y|lvreduce.8 | |lvm-devel@lists.sistina.com | |
| 354 | y|mag.1 | |te@dbs.uni-hannover.de | |
| 355 | p|magma_tool.8 |8 | | |
| 356 | 1n|Mail::SpamAssassin::Client.3pm,Mail::SpamAssassin::Plugin::ReplaceTags.3pm,XML::LibXML::DocumentFragment.3pm|W |perl-documentation@perl.org | |
| 357 | 1n|mailto.1 |uJo |nsb@guppylake.com | |
| 358 | 1p|makestrs.1x |A |xorg@lists.freedesktop.org | |
| 359 | y|man.1,manpath.1 | |mtk-manpages@gmx.net | |
| 360 | bn|mcs.8 |X | | |
| 361 | bn|mdadm.conf.5 |X | | |
| 362 | bn|mdadm.8 |X | | |
| 363 | 6n|mdel.1 |T |mtools@mtools.linux.lu | |
| 364 | 1n|mdoc.7 |N |mtk-manpages@gmx.net | |
| 365 | 1n|merge.1 |bL |bug-rcs@gnu.org | |
| 366 | 1n|mev.1 |J |gpm@lists.linux.it | |
| 367 | y|mf.1,inimf.1,virmf.1 | |te@dbs.uni-hannover.de | |
| 368 | 1n|mkdtemp.3 |L |mtk-manpages@gmx.net | |
| 369 | y|mkoctfile.1 | |jwe@bevo.che.wisc.edu>, edd@debian.org | |
| 370 | 1n|mkxauth.1x |u |xorg@lists.freedesktop.org | |
| 371 | y|mkzftree.1 | |hpa@zytor.com | |
| 372 | 2n|ModPerl::Code.3pm |D |perl-documentation@perl.org | |
| 373 | y|motd.news.5 | |inn-bugs@isc.org | |
| 374 | y|mozplugger.7 | |louis@bavoil.net | |
| 375 | 1n|mpage.1 |8 |Marcel Mol <marcel@mesa.nl> | |
| 376 | 1n|mpcd.8 | |Heikki Vatiainen <hessu@cs.tut.fi>, Sampo Saaristo <s156953@cs.tut.fi> | |
| 377 | 6bn|MPI_Group_free.3 |C | | |
| 378 | 1n|mpiexec.1 |X |lam-devel@lam-mpi.org | |
| 379 | p|mpirun.1 |4u |lam-devel@lam-mpi.org | |
| 380 | 1n|mpost.1 |8 | | |
| 381 | 1n|mtx.1 |J |eric@badtux.org | |
| 382 | y|mysqld.1,mysqld_multi.1,mysqldump.1,mysql_zap.1,mysqladmin.1,mysqlshow.1| |monty@tcx.se | |
| 383 | 1n|mysqlmanager.1 |I |monty@tcx.se | |
| 384 | 1n|mysqld_safe.1 |T |monty@tcx.se | |
| 385 | y|named.conf.5 | |bind9-bugs@isc.org | |
| 386 | y|nasm.1,ndisasm.1 | |nasm-devel@lists.sourceforge.net | |
| 387 | y|nbp_name.3 | |netatalk-devel@lists.sourceforge.net | |
| 388 | n|nc.1 |! |ericj@monkey.org | |
| 389 | 3n|netsnmp_iterator_info_s.3|s |net-snmp-coders@lists.sourceforge.net | |
| 390 | 3n|netsnmp_table.3 |X |net-snmp-coders@lists.sourceforge.net | |
| 391 | 1n|netdump.8 |L |tgraf@redhat.com | |
| 392 | 3n|netdump-server.8 |C |anderson@redhat.com | |
| 393 | 1n|netstat.8 |Cz |ecki@linux.de | |
| 394 | y|newgrp.1 | |Julianne Frances Haugh <jockgrrl@ix.netcom.com> | |
| 395 | y|nfsd.7 | |neilb@cse.unsw.edu.au | |
| 396 | 1n|nisplus_table.5 |C |wietse@porcupine.org | |
| 397 | 1n|NetworkManager.1,NetworkManagerDispatcher.1,nm-tool.1 |W |networkmanager-list@gnome.org | |
| 398 | 1n|nfs4_uid_to_name.3 |W |nfsv4@linux-nfs.org | |
| 399 | 1n|nmap.1 |As |nmap-hackers@insecure.org | |
| 400 | 1n|nslookup.1 |J | | |
| 401 | 1n|ntlm_auth.1 |RX |samba-docs@lists.samba.org | |
| 402 | y|ntpdate.1 | |mills@udel.edu | |
| 403 | y|ntpq.1 | |mills@udel.edu | |
| 404 | y|octave-config.1 | |jwe@bevo.che.wisc.edu, edd@debian.org | |
| 405 | y|on_ac_power.1 | |Richard Hughes <richard@hughsie.com> | |
| 406 | 1n|ogonkify.1 |Lu |jec@dcs.ed.ac.uk | |
| 407 | 1n|openvt.1 |Lu |aeb@cwi.nl | |
| 408 | 3r|operator.7 |o |mtk-manpages@gmx.net | |
| 409 | y|parted.8 | |bug-parted@gnu.org | |
| 410 | 1n|pcre.3,pcrebuild.3 |8 |ph10@cam.ac.uk | |
| 411 | 1p|pcreprecompile.3|X |ph10@cam.ac.uk | |
| 412 | 1p|pcrepattern.3,pcrecallout.3,pcretest.1,pcrepartial.3|J |ph10@cam.ac.uk | |
| 413 | 1n|pdftk.1 |L |ssteward@accesspdf.com | |
| 414 | 4n*|PDL::BAD2_demo.3pm,PDL::BAD_demo.3pm,PDL::Config.3pm,PDL::Doc::Config|y |perl-documentation@perl.org | |
| 415 | 3n|PDL::GSL::INTEG.3pm |D |pdl-porters@jach.hawaii.edu | |
| 416 | 4n|PDL::MatrixOps.3pm |W |pdl-porters@jach.hawaii.edu | |
| 417 | y|pdl.1 | |pdl-porters@jach.hawaii.edu | |
| 418 | 2p|perl-nocem.8 |O |inn-bugs@isc.org | |
| 419 | 1n|perlop.1,perlre.1 |J |perl-documentation@perl.org | |
| 420 | 1n|pflogsumm.1 |W |wietse@porcupine.org | |
| 421 | y|pgmabel.1,pgmtopgm.1,pnmstitch.1,pgmmorphconv.1,pnmtoddif.1,ppmtopj.1 | |Bryan Henderson <bryanh@giraffe-data.com> | |
| 422 | y|php.1 |W |phpdoc@lists.php.net | |
| 423 | 1n|php-config.1,phpize.1 |L |phpdoc@lists.php.net | |
| 424 | 6n|pilot-addresses.1 |j |Robert Wittig <bob.wittig@gt.org> | |
| 425 | 6n|pilot-foto.1 |U |pilot-link-devel@pilot-link.org | |
| 426 | 5n|pilot-xfer.1 |j |pilot-link-devel@pilot-link.org | |
| 427 | 1n|pipe.8 |8 |wietse@porcupine.org | |
| 428 | 3y|pipethrough.3 | |mc-devel@gnome.org | |
| 429 | 1n|pkg-config.1 |JX | | |
| 430 | y|play.1 | | | |
| 431 | y|postconf.5 | |wietse@porcupine.org | |
| 432 | 1n|postmap.1,postsuper.1|8 |wietse@porcupine.org | |
| 433 | 1p|powermust.8 |W |Carlos Rodrigues <carlos.efr@mail.telepac.pt> | |
| 434 | y|ps.1 |D |acahalan@cs.uml.edu | |
| 435 | 5p|privoxy.1 |j |developers@privoxy.org | |
| 436 | 1n|proxymap.8 |8 |wietse@porcupine.org | |
| 437 | 6n|ps2epsi.1 |j |giles@artifex.com | |
| 438 | 6n|ps2pdf.1,ps2pdf12.1,ps2pdf13.1,ps2pdfwr.1,pstops.1| |giles@artifex.com | |
| 439 | 1n|psnup.1 |J |giles@artifex.com | |
| 440 | 1n|pthreads.7 |u |mtk-manpages@gmx.net | |
| 441 | 6n|ptx.1 |j |bug-gnu-utils@gnu.org | |
| 442 | 1p|PVM.1 |w |gst@ornl.gov | |
| 443 | y|pvmd.1,pvm_shmd.1,pvmd3.1 | |gst@ornl.gov | |
| 444 | y|pvm_addmhf.3 | |gst@ornl.gov | |
| 445 | 1n|pvm_advise.3 |Wo |gst@ornl.gov | |
| 446 | 1n|pvm_delete.3,pvm_insert.3,pvm_lookup.3,pvm_serror.3,pvm_setmwid.3 |W |gst@ornl.gov | |
| 447 | 1n|pvm_intro.1 |8 |gst@ornl.gov | |
| 448 | 1n|pxeos.8,pxeboot.8 |84 |dwalsh@redhat.com | |
| 449 | y|quantize.5 | |magick-bugs@imagemagick.org | |
| 450 | 1n|quotactl.2 |L |jkar8572@sers.sourceforge.net | |
| 451 | 1n|qos.7 |L |linux-atm-general@lists.sourceforge.net | |
| 452 | y|racoon.conf.5 | |bugs@lists.freeswan.org | |
| 453 | 1n|random.4 |8 |mtk-manpages@gmx.net | |
| 454 | 1n|ram.4 |8u |mtk-manpages@gmx.net | |
| 455 | 1p|rate.conf.5 |8 |tobiasb@isdn4linux.de | |
| 456 | 1n|raw2tiff.1,tiffcmp.1,TIFFClose.3tiff |X |tiff@lists.maptools.org | |
| 457 | 1n|rcsfile.5 |X |bug-rcs@gnu.org | |
| 458 | 1n|rcsintro.1 |u |bug-rcs@gnu.org | |
| 459 | y|replace.1,isamchk.1,isamlog.1| |monty@tcx.se | |
| 460 | 1n|revnetgroup.8 |L |kukuk@suse.de | |
| 461 | 1n|rexec.3 |X | | |
| 462 | 1n|rdist.1 |8o |rdist-dev@usc.edu | |
| 463 | y|rdump.8,dump.8,restore.8,rrestore.8 | |Stelian Pop <stelian@popies.net> | |
| 464 | 3n|rlm_expr.5 |X |dwalsh@redhat.com | |
| 465 | 3n|rlm_attr_filter.5 |XF |dwalsh@redhat.com | |
| 466 | y|roff.7 |A |wl@gnu.org | |
| 467 | 1n|ftpd_selinux.8 |u |dwalsh@redhat.com | |
| 468 | 1p|httpd_selinux.8,kerberos_selinux.8,named_selinux.8|8 |dwalsh@redhat.com | |
| 469 | 1n|rsync_selinux.8 |@u8 |dwalsh@redhat.com | |
| 470 | 1n|rz.1 |8 |Uwe Ohse <uwe@ohse.de> | |
| 471 | 1n|samba_selinux.8 |8& |dwalsh@redhat.com | |
| 472 | b|sane-apple.5 |L | | |
| 473 | b|sane-mustek_pp.5 |Loz | | |
| 474 | 1n|SDL_Init.3 |L |sdl@lists.libsdl.org | |
| 475 | n|security.7 |@ |xorg@lists.freedesktop.org | |
| 476 | 1n|selinux.8 |8 |dwalsh@redhat.com | |
| 477 | y|send-uucp.8 | |inn-bugs@isc.org | |
| 478 | 4n|sftp.1 |C |Damien Miller <djm@mindrot.org> | |
| 479 | 1p|sg_senddiag.8,sg_wr_mode.8 |C |dgilbert@interlog.com | |
| 480 | 6n|sgml2lyx.1 |Z |Taketoshi Sano <sano@debian.org> | |
| 481 | 5p|sgmlpre.1 |E |Taketoshi Sano <sano@debian.org> | |
| 482 | y|sk98lin.4 | |linux@syskonnect.de | |
| 483 | 1n|slapo-ppolicy.5 |X |OpenLDAP-devel@OpenLDAP.org | |
| 484 | y|slapd.8 | |OpenLDAP-devel@OpenLDAP.org | |
| 485 | 1n|slapdn.8,slapacl.8,slapadd.8 |u |OpenLDAP-devel@OpenLDAP.org | |
| 486 | 1n|slapd.conf.5,slapo-auditlog.5 |Lu |OpenLDAP-devel@OpenLDAP.org | |
| 487 | 1n|smartctl.8 |z |smartmontools-support@lists.sourceforge.net | |
| 488 | y|smartd.8,smartctl.8,smartd.conf.5| |smartmontools-support@lists.sourceforge.net | |
| 489 | 1n|snmp_api.3,snmp_sess_api.3|o |net-snmp-coders@lists.sourceforge.net | |
| 490 | y|snmpvacm.1 | |net-snmp-coders@lists.sourceforge.net | |
| 491 | y|snmpd.conf.5 | |net-snmp-coders@lists.sourceforge.net | |
| 492 | y|snmp.conf.5 | |net-snmp-coders@lists.sourceforge.net | |
| 493 | b|sntp.1 |C | | |
| 494 | 1n|solterm.1 |C |dariusd@users.sourceforge.net | |
| 495 | 1p|sox.1,libst.3 |Wu |chris@cnpbagwell.com | |
| 496 | p|spax.1 | |schilling@fokus.fraunhofer.de | |
| 497 | n|spufs.2 |f |mtk-manpages@gmx.net | |
| 498 | y|squid_ldap_auth.8,squid_ldap_group.8 | |squid-bugs@squid-cache.org | |
| 499 | y|ssh-keyscan.1 | |brad@openbsd.org | |
| 500 | 3p|sshd_config.5,ssh_config.5 |q |brad@openbsd.org | |
| 501 | 1n|states.1 |hJ |mtr@iki.fi | |
| 502 | 4n|stationlist.xml.5 |XR |batchall@mordor.ch | |
| 503 | 1n|system-config-httpd.1 |8 |pknirsch@redhat.com | |
| 504 | 1n|system-config-netboot.8 |8 |harald@redhat.com | |
| 505 | 1n|system-config-services.8 |84 |nphilipp@redhat.com | |
| 506 | 4n|tvtime.xml.5 |X |vektor@dumbterm.net | |
| 507 | 1n|synclient.1 |4 |xorg@lists.freedesktop.org | |
| 508 | 6n|sysklogd.8 |X |greg@wind.enjellic.com | |
| 509 | 6n|sz.1 |g8 |Uwe Ohse <uwe@ohse.de> | |
| 510 | b|t1libconfig.8 |U |dhd@debian.org | |
| 511 | y|tar.1 | |vapier@gentoo.org | |
| 512 | 3n|tc-pbfifo.8 |T |ahu@ds9a.nl, uznet@ms2.inr.ac.ru | |
| 513 | 1n|tcpd.8 |8 |wietse@porcupine.org | |
| 514 | 1n|terminfo.5 |x | | |
| 515 | y|texdoctk.1 | |bunk@fs.tum.de, ruedas@geophysik.uni-frankfurt.de | |
| 516 | 1n|tidy.1 |Wm |tidy-develop@lists.sourceforge.net,html-tidy@w3.org | |
| 517 | 1n|timidity.1 |L |breeze.nagano@nifty.ne.jp, mo@goice.co.jp | |
| 518 | y|timidity.cfg.5 | |breeze.nagano@nifty.ne.jp, mo@goice.co.jp | |
| 519 | y|Tk_Uid.3 | |tcl-core@lists.sourceforge.net | |
| 520 | 5n|transfig.1x |XU |bvsmith@lbl.gov | |
| 521 | 1n|tree.1 |J |Steve Baker <ice@mama.indstate.edu> | |
| 522 | 6n|tsclient.1 |W |Miguel de Icaza <miguel@gnu.org> | |
| 523 | bn|ttcp.1 |XD | | |
| 524 | 6n|tune2fs.8 |C |tytso@thunk.org | |
| 525 | 1n|tzfile.5 |u |mtk-manpages@gmx.net | |
| 526 | y|udevd.8,udevsend.8 | |Kay Sievers <kay.sievers@vrfy.org> | |
| 527 | 1n|units.1 |o |adrian@cam.cornell.edu | |
| 528 | 1n|unzip.1,unzipsfx.1 |J |roelofs@pobox.com | |
| 529 | y|uuencode.1 | |bug-gnu-utils@gnu.org | |
| 530 | 4n|vacuumdb.1 |C |pgsql-docs@postgresql.org | |
| 531 | 6n|vgsplit.8 |C |lvm-devel@lists.sistina.com | |
| 532 | 1n|vgchange.8 |8u |lvm-devel@lists.sistina.com | |
| 533 | 6n|vorbiscomment.1 |C |Christopher L Cheney <ccheney@debian.org> | |
| 534 | y|vsftpd.conf.5 | |chris@scary.beasts.org | |
| 535 | 1n|wall.1 |J |miquels@cistron.nl | |
| 536 | 1n|webalizer.1 |8 |brad@mrunix.net | |
| 537 | 5r|wget.1 |s |mtortonesi@ing.unife.it | |
| 538 | 1n|whereis.1 |L |bunk@stusta.de | |
| 539 | bn|which.1 |u | | |
| 540 | 1n|wvdial.1 |X |wvdial-list@nit.ca | |
| 541 | 1n|xcscope.1 |ouL |broeker@users.sourceforge.net | |
| 542 | b|xdvi.1,oxdvi.1 |L | | |
| 543 | 1n|XAllocWMHints.3x |1 |xorg@lists.freedesktop.org | |
| 544 | 1n|Xaw.3x |J8u |xorg@lists.freedesktop.org | |
| 545 | 1n|XcmsColor.3x |u8 |xorg@lists.freedesktop.org | |
| 546 | 1p|XDrawArc.3x|8o |xorg@lists.freedesktop.org | |
| 547 | 1n|XQueryColor.3x |8o|xorg@lists.freedesktop.org | |
| 548 | 1n|XLoadFont.3x |Ju |xorg@lists.freedesktop.org | |
| 549 | 1n|XrmGetFileDatabase.3x |u |xorg@lists.freedesktop.org | |
| 550 | 1n|XrmUniqueQuark.3x |u |xorg@lists.freedesktop.org | |
| 551 | 1p|XvSelectVideoNotify.3x|A |xorg@lists.freedesktop.org | |
| 552 | 1n|XmArrowButton.3,XmScrollBar.3,XmArrowButtonGadget.3,XmBulletinBoard.3,XmCascadeButton.3,XmCascadeButtonGadget.3,XmClipboard.3,XmComboBox.3,XmCommand.3,XmDesktop.3,XmDialogShell.3,XmDialogShellExt.3,XmDisplay.3,XmDragContext.3,XmDragIcon.3,XmDragOverShell.3,XmDrawingArea.3,XmDrawnButton.3,XmDropSiteManager.3,XmDropTransfer.3,XmFileSelectionBox.3,XmForm.3,XmFrame.3,XmGadget.3,XmGrabShell.3,XmIconGadget.3,XmSelectionBox.3,XmSeparator.3,XmSeparatorGadget.3,XmSpinBox.3,XmString.3,XmTearOffButton.3,XmText.3,XmTextField.3,XmToggleButton.3,XmToggleButtonGadget.3,XmVendorShell.3,XmWorld.3,XmFrame.3,XmLabel.3,XmLabelGadget.3,XmList.3,XmMainWindow.3,XmManager.3,XmMenuShell.3,XmMessageBox.3,XmPanedWindow.3,XmPrimitive.3,XmProtocol.3,XmPushButton.3,XmPushButtonGadget.3,XmRowColumn.3,XmSash.3,XmScale.3,XmScreen.3,XmScrolledWindow.3,Object.3,Rect.3,OverrideShell.3,LessTifInternals.3,Composite.3,Constraint.3,Core.3,TopLevelShell.3,TransientShell.3,UnNamedObj.3,VendorShell.3,WmShell.3,VirtualBindings.5,Shell.3|2 |lesstif-discuss@lists.sourceforge.net | |
| 553 | 1n|Xnest.1x |J |xorg@lists.freedesktop.org | |
| 554 | 1n|XGrabDeviceKey.3x,XIfEvent.3x|X |xorg@lists.freedesktop.org | |
| 555 | 1p|XListInputDevices.3x |V |xorg@lists.freedesktop.org | |
| 556 | 1n|XML::DOM-ecmascript.3pm|W |perl-documentation@perl.org | |
| 557 | 4n|XML::DOM::Element.3pm|n |perl-documentation@perl.org | |
| 558 | 4n|XML::Parser::Style::Objects.3pm|W |perl-documentation@perl.org,coopercc@netheaven.com | |
| 559 | 4n|XML::Parser::Style::Tree.3pm|W |perl-documentation@perl.org,coopercc@netheaven.com | |
| 560 | 4n|XML::Parser::Style::Subs.3pm|W |perl-documentation@perl.org,coopercc@netheaven.com | |
| 561 | 1n|x11perf.1x,x11perfcomp.1x|8 |xorg@lists.freedesktop.org | |
| 562 | 1p|xdpr.1x |X5 |xorg@lists.freedesktop.org | |
| 563 | 1n|xfd.1x |u |xorg@lists.freedesktop.org | |
| 564 | y|xfs_bmap.8,xfs_check.8| |linux-xfs@oss.sgi.com | |
| 565 | 6n|xinetd.conf.5 |@Lu |bbraun@synack.net | |
| 566 | 1n|xkbevd.1x |J |xorg@lists.freedesktop.org | |
| 567 | 1p|xfontsel.1x,xlsfonts.1x |8 |xorg@lists.freedesktop.org | |
| 568 | 1n|Xmark.1x |8 |xorg@lists.freedesktop.org | |
| 569 | 1n|xminicom.1 |W |miquels@cistron.nl | |
| 570 | y|xml_pp.1 | |Michel Rodriguez <mirod@xmltwig.com> | |
| 571 | y|xml_spellcheck.1 | |Michel Rodriguez <mirod@xmltwig.com> | |
| 572 | 1n|xmlto.1 |A |tim@cyberelk.net | |
| 573 | 1p|xrdb.1x |g |xorg@lists.freedesktop.org | |
| 574 | n|xclipboard.1x |u |xorg@lists.freedesktop.org | |
| 575 | 1n|xterm.1 |u8 |xorg@lists.freedesktop.org | |
| 576 | 1n|xtrap.1x |X4a |xorg@lists.freedesktop.org | |
| 577 | 1n|XQueryExtension.3x |X |xorg@lists.freedesktop.org | |
| 578 | 1n|xscreensaver-text.1 |X |jwz@jwz.org | |
| 579 | 1n|Xserver.1x |8m |xorg@lists.freedesktop.org | |
| 580 | 1p|xset.1x |C |xorg@lists.freedesktop.org | |
| 581 | y|xsltproc.1 | |xslt@gnome.org | |
| 582 | 1n|ypcat.1 |R |kukuk@suse.de | |
| 583 | 1n|ypmatch.1,ypwhich.1 |R |kukuk@suse.de | |
| 584 | bn|zone2ldap.1 |W | | |
| 585 | 1n|zshcompctl.1,zshcontrib.1|L |zsh-workers@sunsite.dk | |
| 586 | 1n|zshmodules.1 |nt |zsh-workers@sunsite.dk |
| 0 | 0 | # Makefile for the doclifter project |
| 1 | VERS=2.7 | |
| 1 | VERSION=$(shell sed <doclifter -n -e '/^version *= *\(.*\)/s//\1/p') | |
| 2 | 2 | |
| 3 | 3 | MANDIR=/usr/share/man/man1 |
| 4 | 4 | BINDIR=/usr/bin |
| 5 | 5 | |
| 6 | DOCS = README COPYING TODO BUGS \ | |
| 6 | DOCS = README COPYING TODO PATCHES \ | |
| 7 | 7 | doclifter.xml doclifter.1 manlifter.xml manlifter.1 |
| 8 | TEST = docliftertest1.man test.troff | |
| 9 | SOURCES = doclifter manlifter Makefile $(DOCS) $(TEST) doclifter-logo.png | |
| 8 | SOURCES = doclifter manlifter Makefile $(DOCS) tests/ doclifter-logo.png | |
| 10 | 9 | |
| 11 | all: doclifter-$(VERS).tar.gz | |
| 10 | all: doclifter-$(VERSION).tar.gz | |
| 12 | 11 | |
| 13 | 12 | install: doclifter.1 |
| 14 | 13 | cp doclifter $(BINDIR) |
| 27 | 26 | manlifter.html: manlifter.xml |
| 28 | 27 | xmlto xhtml-nochunks manlifter.xml |
| 29 | 28 | |
| 30 | doclifter-$(VERS).tar.gz: $(SOURCES) | |
| 31 | mkdir doclifter-$(VERS) | |
| 32 | cp $(SOURCES) doclifter-$(VERS) | |
| 33 | tar -czf doclifter-$(VERS).tar.gz doclifter-$(VERS) | |
| 34 | rm -fr doclifter-$(VERS) | |
| 35 | ls -l doclifter-$(VERS).tar.gz | |
| 29 | doclifter-$(VERSION).tar.gz: $(SOURCES) | |
| 30 | mkdir doclifter-$(VERSION) | |
| 31 | cp -r $(SOURCES) doclifter-$(VERSION) | |
| 32 | tar -czf doclifter-$(VERSION).tar.gz doclifter-$(VERSION) | |
| 33 | rm -fr doclifter-$(VERSION) | |
| 34 | ls -l doclifter-$(VERSION).tar.gz | |
| 36 | 35 | |
| 37 | test: | |
| 38 | doclifter -v docliftertest1.man | |
| 36 | doclifter-$(VERSION).md5: doclifter-$(VERSION).tar.gz | |
| 37 | @md5sum doclifter-$(VERSION).tar.gz >doclifter-$(VERSION).md5 | |
| 38 | ||
| 39 | check: | |
| 40 | @cd tests >/dev/null; make --quiet | |
| 41 | ||
| 42 | PYLINTOPTS = --rcfile=/dev/null --reports=n --include-ids=y --disable="C0103,C0111,C0301,C0302,C0322,C0321,C0324,W0402,W0511,W0141,W0231,W0333,W0631,R0201,R0911,R0912,R0914,R0902,R0903,R0904,R0913,R0914,R0915" | |
| 43 | pylint: | |
| 44 | @pylint --output-format=parseable $(PYLINTOPTS) doclifter | |
| 39 | 45 | |
| 40 | 46 | pychecker: |
| 41 | @echo "Expect: Local variable (lst) not used" | |
| 47 | @echo "Expect 4 warnings." | |
| 42 | 48 | @ln -f doclifter doclifter.py |
| 43 | 49 | @-pychecker --only --quiet --limit 50 doclifter.py |
| 44 | 50 | @rm -f doclifter.py doclifter.pyc |
| 45 | 51 | |
| 46 | dist: doclifter-$(VERS).tar.gz | |
| 52 | dist: doclifter-$(VERSION).tar.gz | |
| 47 | 53 | |
| 48 | 54 | clean: |
| 49 | rm -f doclifter.html manlifter.html doclifter.1 manlifter.1 *.tar.gz | |
| 50 | rm -f *.pyc docliftertest.xml | |
| 51 | rm -f SHIPPER.* index.html | |
| 55 | rm -f doclifter.html manlifter.html doclifter.1 manlifter.1 | |
| 56 | rm -f *.pyc docliftertest.xml foobar* fixed* *~ bugs.html | |
| 57 | rm -f SHIPPER.* index.html *.tar.gz *.md5 | |
| 52 | 58 | |
| 53 | release: doclifter-$(VERS).tar.gz doclifter.html manlifter.html | |
| 59 | release: doclifter-$(VERSION).tar.gz doclifter-$(VERSION).md5 doclifter.html manlifter.html | |
| 54 | 60 | shipper -u -m -t; make clean |
| 61 | ||
| 62 | # This is used only for updating the bugs page on my website. | |
| 63 | # It won't work for anyone else. | |
| 64 | update: | |
| 65 | problemgen.py >bugs.html | |
| 66 | scp -r bugs.html prepatch/ login.ibiblio.org:/public/html/catb/esr/doclifter | |
| 0 | # All known problems with the manual pages in a desktop Ubuntu installation | |
| 1 | # | |
| 2 | # Send 1 was on 09 Dec 2003 | |
| 3 | # Send 2 was on 17 Feb 2004 | |
| 4 | # Send 3 was on 11 Jul 2004 | |
| 5 | # Send 4 was on 20 Nov 2004 | |
| 6 | # Send 5 was on 14 Jan 2005 | |
| 7 | # Send 6 was on 01 Jan 2007 | |
| 8 | # | |
| 9 | A Dot or single-quote at start of line turns it into a garbage command. | |
| 10 | This is a serious error; some lines of your page get silently lost | |
| 11 | when it is formatted. | |
| 12 | B Bogus macro definition. | |
| 13 | C Broken command synopsis syntax. This may mean you're using a | |
| 14 | construction in the command synopsis other than the standard | |
| 15 | [ ] | { }, or it may mean you have running text in the command synopsis | |
| 16 | section (the latter is not technically an error, but most cases of it | |
| 17 | are impossible to translate into DocBook markup), or it may mean the | |
| 18 | command syntax fails to match the description. | |
| 19 | D Non-break space prevents doclifter from incorrectly interpreting | |
| 20 | "Feature Test" as end of function synopsis. | |
| 21 | E My translator trips over a useless command in list markup. | |
| 22 | F Non-English-language page incorrectly installed. | |
| 23 | G Spurious trailing .CE | |
| 24 | H Renaming SYNOPSIS because either (a) third-party viewers and | |
| 25 | translators will try to interpret it as a command synopsis and become | |
| 26 | confused, or (b) it actually needs to be named "SYNOPSIS" with no | |
| 27 | modifier for function protoypes to be properly recognized. | |
| 28 | I Use of low-level troff hackery to set special indents or breaks can't | |
| 29 | be translated. The page will have rendering faults in HTML, and | |
| 30 | probably also under third-party man page browsers such as Xman, | |
| 31 | Rosetta, and the KDE help browser. This patch eliminates .br, .ta, .ti, | |
| 32 | .ce, .in, and \h in favor of requests like .RS/.RE that have | |
| 33 | structural translations. | |
| 34 | J Ambiguous or invalid backslash. This doesn't cause groff a problem. | |
| 35 | but it confuses doclifter and may confuse older troff implementations. | |
| 36 | K Renaming stock man macros throws warnings in doclifter and is likely | |
| 37 | to cause failures on third-party manual browsers. Please redo this | |
| 38 | page so it uses distinct names for the custom macros. | |
| 39 | L List syntax error. This means .IP, .TP or .RS/.RE markup is garbled. | |
| 40 | Common causes include .TP just before a section header, .TP entries | |
| 41 | with tags but no bodies, and mandoc lists with no trailing .El. | |
| 42 | These confuse doclifter, and may also mess up stricter man-page | |
| 43 | browsers like Xman and Rosetta. | |
| 44 | M Feature test macros (running text) included in a function | |
| 45 | synopsis prevents translation to DocBook. | |
| 46 | N Extraneous . at start of line. | |
| 47 | O Wrong order of arguments in .Dd macro. | |
| 48 | Q Spelling error or typo. | |
| 49 | R .ce markup can't be structurally translated, and is likely | |
| 50 | to cause rendering flaws in generated HTML. | |
| 51 | S DEPRECATED: in function syntax cannot be translated. Also, the | |
| 52 | code and examples need to be marked up better. | |
| 53 | T Junk at the beginning of the manual page. | |
| 54 | U Unbalanced group in command synopis. You probably forgot | |
| 55 | to open or close a [ ] or { } group properly. | |
| 56 | V Missing body content in list trips up doclifter and is likely to | |
| 57 | cause rendering problems in other viewers. I have been able to fill | |
| 58 | in what was missing except for what should be under TAR_LONGLINK_100. | |
| 59 | W Missing or garbled name section. The most common form of garbling | |
| 60 | is a missing - or extra -. Or your manual page may have been generated | |
| 61 | by a tool that doesn't emit a NAME section as it should. Or your page | |
| 62 | may add running text such as a version or authorship banner. These | |
| 63 | problems make it impossible to lift the page to DocBook. They | |
| 64 | can also confuse third-party manpage browsers and some implementations | |
| 65 | of man -k. | |
| 66 | X Unknown or invalid macro. That is, one that does not fit in the | |
| 67 | macro set that the man page seems to be using. This is a serious | |
| 68 | error; it often means part of your text is being lost or rendered | |
| 69 | incorrectly. | |
| 70 | Y I have been unable to identify an upstream maintainer for this | |
| 71 | Ubuntu/Debian package, and am notifying the generic "Maintainer" | |
| 72 | address in the package. Please forward appropriately. Also | |
| 73 | fix the package metadata so it identifies the upstream maintainers. | |
| 74 | Z Your Synopsis is exceptionally creative. Unfortunately, that means | |
| 75 | it cannot be translated to structural markup even when things like | |
| 76 | running-text inclusions have been moved elswhere. | |
| 77 | a ".fi" request was omitted or typoed as ".if". | |
| 78 | b Attempt to interpolate unknown string. | |
| 79 | c The composer of this man page misunderstood and seriously overused | |
| 80 | the \c escape. Some uses were broken; others (notably the sequence | |
| 81 | "\\c\n\\&") are bad style. | |
| 82 | d .eo/.ec and complex tab-stop hackery can't be translated to XML/HTML | |
| 83 | and are almost certain to confuse third-party readers such as | |
| 84 | Rosetta and Xman. | |
| 85 | e Macro definitions in the NAME section confuse doclifter and are | |
| 86 | likely to screw up third-party man viewers with their own parsers. | |
| 87 | f Absence of trailing \fRs makes synopsis unparseable. | |
| 88 | g Use of a double quote for inch measurements often confuses people | |
| 89 | who aren't from the Anglosphere. | |
| 90 | i Non-ASCII character in document synopsis can't be parsed. | |
| 91 | j Parenthesized comments in command synopsis. This is impossible | |
| 92 | to translate to DocBook. | |
| 93 | k kdemangen.pl stuttered two copies of a page. Also, .SS markup | |
| 94 | is garbled. | |
| 95 | l Incorrect formation of plural - beware the exiguous apostrophe! | |
| 96 | m Contains a request or escape that is outside the portable subset that | |
| 97 | can be rendered by non-groff viewers such as the KDE and GNOME help | |
| 98 | browsers. | |
| 99 | n Invalid Sx reference - not a section on this page. | |
| 100 | o TBL markup not used where it should be. Tables stitched together | |
| 101 | with .ta or list requests can't be lifted to DocBook and will often | |
| 102 | choke third-party viewers such as TKMan, XMan, Rosetta, etc. | |
| 103 | p Synopsis was incomplete and somewhat garbled. | |
| 104 | q Unused macro causes parsing problems. | |
| 105 | r I supplied a missing mail address. Without it, the .TP at the end of the | |
| 106 | authors list was ill-formed. | |
| 107 | s Changed page to use the .URL macro now preferred on man(7). | |
| 108 | t Synopsis has to be immediately after NAME section for DocBook | |
| 109 | translation to work. | |
| 110 | u Use local definitions of .EX/.EE or .DS/.DE to avoid low-level troff | |
| 111 | requests in the page body. There are plans to add these to groff man; | |
| 112 | in the interim, this patch adds a compatible definition to your page. | |
| 113 | v Missing DESCRIPTION section. | |
| 114 | w .SS markup in name section seriously confuses parsing, and sections | |
| 115 | don't follow standard naming conventions. | |
| 116 | x Syntax had to be rearranged because of an options callout. | |
| 117 | This is still excessively complicated; third-party man-page | |
| 118 | viewers are likely to choke on it. | |
| 119 | y I realize this man page is generated from POD, HTML, or some other | |
| 120 | non-man markup. Please fix the upstream markup so that it generates | |
| 121 | a well-formed manual page with the indicated corrections. | |
| 122 | z Garbled or missing text near .SS tags. It's not clear to me what's | |
| 123 | going on here, but .SS tags on adjacent lines defeat any attempt | |
| 124 | to parse the markup. I have inserted text lines indicating that | |
| 125 | something needs to be written here. | |
| 126 | 1 Garbled comment leader is likely to confuse third-party readers. | |
| 127 | 2 Use of man or mandoc lists to simulate literal displays defeats any | |
| 128 | attempt at structural translation. | |
| 129 | 3 Use of .RS/RE or list markup to produce indentation in examples | |
| 130 | and screenshots makes structural translation impossible. | |
| 131 | 4 \c is an obscure feature; third-party viewers sometimes don't | |
| 132 | intepret it. Plain \ is safer. | |
| 133 | 5 Two-digit year in .Dd macro. | |
| 134 | 6 Presentation-level use of SS could not be structurally | |
| 135 | translated. I changed lower-level instances to .TP. | |
| 136 | 7 This page wins an award for exceptionally creative and perverse | |
| 137 | abuse of list syntax. | |
| 138 | 8 C function syntax has extra paren. | |
| 139 | 9 I replaced '-->' with a troff right arrow, which doclifter will | |
| 140 | translate properly to an XML/HTML arrow glyph. | |
| 141 | 0 Function declarations had to be modified in order to fit into | |
| 142 | the DocBook DTD. This is not an error in troff usage, but it | |
| 143 | reduces the quality of the HTML that can be generated from this page | |
| 144 | through the DocBook toolchain. | |
| 145 | %% | |
| 146 | y|ac.1 | |sgk@sgk.tiac.net | |
| 147 | y|acl.5 |I |https://savannah.nongnu.org/bugs/index.php?39096 | |
| 148 | y|aconnect.1 | |tiwai@suse.de,alsa-devel@lists.sourceforge.net | |
| 149 | nA|admin.1posix |C |Francesco Paolo Lovergine <frankie@debian.org> | |
| 150 | nA|afm2pl.1 |I |tex-live@tug.org | |
| 151 | nA|aio.7 |I |mtk-manpages@gmx.net | |
| 152 | nA|american.5,english.5 |I9 |geoff@cs.hmc.edu | |
| 153 | y|amidi.1,amixer.1,aplay.1,arecord.1 | |Clemens Ladisch <clemens@ladisch.de> | |
| 154 | nA|amf.conf.5 |Y2 |Ubuntu Developers <ubuntu-devel-discuss@lists.ubuntu.com> | |
| 155 | y|amrecover.8 | | | |
| 156 | nA|analog.1 |CZ |analog-author@lists.meer.net | |
| 157 | y|animate.1,compare.1,conjure.1,composite.1,convert.1,display.1,identify.1,import.1,mogrify.1,montage.1 | |magick-bugs@imagemagick.org | |
| 158 | y|apport-retrace.1 | |martin.pitt@ubuntu.com | |
| 159 | y|appres.1x | |xorg@lists.freedesktop.org | |
| 160 | 6nA|arp.7 |p |Bernd Eckenfels <net-tools@lina.inka.de> | |
| 161 | nA|as.1 |Zy |bug-binutils@gnu.org | |
| 162 | n|asn1_der_coding.3 |Ly |help-libtasn1@gnu.org | |
| 163 | n|asn1_write_value.3 |Jy |help-libtasn1@gnu.org | |
| 164 | y|aspell.1 | |pyro@debian.org | |
| 165 | y|atmsigd.conf.4 | |Werner.Almesberger@epfl.ch | |
| 166 | y|auditd.8 | |linux-audit@redhat.com | |
| 167 | nA|audit.rules.7 |a |linux-audit@redhat.com | |
| 168 | nA|auth_destroy.3 |I |mtk-manpages@gmx.net | |
| 169 | nA|authnone_create.3 |I |mtk-manpages@gmx.net | |
| 170 | nA|authunix_create.3 |I |mtk-manpages@gmx.net | |
| 171 | nA|authunix_create_default.3 |I |mtk-manpages@gmx.net | |
| 172 | y|awk.1 | |bug-gawk@gnu.org | |
| 173 | y|pgawk.1,gawk.1 | |bug-gawk@gnu.org | |
| 174 | n|barchart.3blt,stripchart.3blt |JG |gah@siliconmetrics.com | |
| 175 | n|graph.3blt |G |gah@siliconmetrics.com | |
| 176 | y|bash.1 | |bug-bash@gnu.org | |
| 177 | nA|bc.1 |J |bug-bc@gnu.org | |
| 178 | y|bgpd.8 | |bug-zebra@gnu.org | |
| 179 | 1p|bitmap.1 |oJ |xorg@lists.freedesktop.org | |
| 180 | p|BitmapBitOrder.3,BitmapPad.3,BitmapUnit.3,DisplayHeight.3,DisplayHeightMM.3,DisplayWidth.3,DisplayWidthMM.3,ImageByteOrder.3,XAddHosts.3|I |xorg@lists.freedesktop.org | |
| 181 | y|bounce.5,aliases.5,relocated.5,virtual.8| |wietse@porcupine.org | |
| 182 | 1nA|header_checks.5 |m |wietse@porcupine.org | |
| 183 | nA|bootparam.7 |Iu7 |mtk-manpages@gmx.net | |
| 184 | n|bridge.8 |C |netdev@vger.kernel.org | |
| 185 | nA|brltty.1 |J |BRLTTY@mielke.cc | |
| 186 | nA|btcflash.8 |J |Daniel Baumann <daniel@debian.org> | |
| 187 | y|bzadmin.6 | |bzflag-dev@lists.sourceforge.net | |
| 188 | y|bzfquery.6 | |bzflag-dev@lists.sourceforge.net | |
| 189 | n|bzfs.6 |o |bzflag-dev@lists.sourceforge.net | |
| 190 | n|bzr.1 |Js |bazaar@lists.canonical.com | |
| 191 | y|cadaver.1 | |Joe Orton <cadaver@webdav.org> | |
| 192 | nA|capabilities.7 |L |mtk-manpages@gmx.net | |
| 193 | nA|callrpc.3 |I |mtk-manpages@gmx.net | |
| 194 | y|cancel-cups.1,cancel.1,lp.1,lp-cups.1 | | | |
| 195 | y|cannastat.1 | |Canna@nec.co.jp | |
| 196 | y|cbrt.3,cbrtf.3,cbrtl.3| |mtk-manpages@gmx.net | |
| 197 | nA|cdparanoia.1 |L |monty@xiph.org | |
| 198 | y|cdrdao.1 | |cdrdao-devel@lists.sourceforge.net | |
| 199 | bnA|chat.8 |J |paulus@samba.org | |
| 200 | y|chcat.8 | |dwalsh@redhat.com | |
| 201 | 6nA|chmoddic.1 |C |Canna@nec.co.jp | |
| 202 | nA|chroot.2 |EL |bug-coreutils@gnu.org | |
| 203 | nA|clnt_broadcast.3 |I |mtk-manpages@gmx.net | |
| 204 | nA|clnt_call.3 |I |mtk-manpages@gmx.net | |
| 205 | nA|clnt_control.3 |I |mtk-manpages@gmx.net | |
| 206 | nA|clnt_create.3 |I |mtk-manpages@gmx.net | |
| 207 | nA|clnt_destroy.3 |I |mtk-manpages@gmx.net | |
| 208 | nA|clnt_freeres.3 |I |mtk-manpages@gmx.net | |
| 209 | nA|clnt_geterr.3 |I |mtk-manpages@gmx.net | |
| 210 | nA|clnt_pcreateerror.3 |I |mtk-manpages@gmx.net | |
| 211 | nA|clnt_perrno.3 |I |mtk-manpages@gmx.net | |
| 212 | nA|clnt_perror.3 |I |mtk-manpages@gmx.net | |
| 213 | nA|clnt_spcreateerror.3 |I |mtk-manpages@gmx.net | |
| 214 | nA|clnt_sperrno.3 |I |mtk-manpages@gmx.net | |
| 215 | nA|clnt_sperror.3 |I |mtk-manpages@gmx.net | |
| 216 | nA|clntraw_create.3 |I |mtk-manpages@gmx.net | |
| 217 | nA|clnttcp_create.3 |I |mtk-manpages@gmx.net | |
| 218 | nA|clntudp_bufcreate.3 |I |mtk-manpages@gmx.net | |
| 219 | nA|clntudp_create.3 |I |mtk-manpages@gmx.net | |
| 220 | 1nA|co.1 |o |rcs-bugs@gnu.org | |
| 221 | nA|codepage.1 |C |mckinstry@computer.org | |
| 222 | nA|compose.1,edit.1 |u |Brian White <bcwhite@pobox.com> | |
| 223 | y|compress.1,uncompress.1 | |peter@ncs.nl | |
| 224 | nA|console_codes.4 |I |mtk-manpages@gmx.net | |
| 225 | nA|console_ioctl.4 |Iol |mtk-manpages@gmx.net | |
| 226 | nA|core.5 |I |mtk-manpages@gmx.net | |
| 227 | nA|corosync.conf.5 |LIY |Ubuntu Developers <ubuntu-devel-discuss@lists.ubuntu.com> | |
| 228 | y|cpufreq-info.1,cpufreq-set.1 |I |linux@brodo.de,malattia@gmail.com | |
| 229 | nA|cpuset.7 |R |mtk-manpages@gmx.net | |
| 230 | y|crash.8 | |fenlason@redhat.com | |
| 231 | y|CrtImgType.3,Tk_InitImageArgs.3| |tcl-core@lists.sourceforge.net | |
| 232 | y|cshost.1 | |Canna@nec.co.jp | |
| 233 | y|cscope.1 | |broeker@users.sourceforge.net | |
| 234 | y|ctangle.1,cweave.1,cweb.1| | | |
| 235 | n|ctanify.1 |y |tex-live@tug.org | |
| 236 | y|curl.1 | | | |
| 237 | y|curl_formadd.3 |J |https://sourceforge.net/p/curl/bugs/1233 | |
| 238 | y|libcurl_tutorial.3 |J |https://sourceforge.net/p/curl/bugs/1234 | |
| 239 | 1nA|cvs.1 |L |cvs-dev@nongnu.org | |
| 240 | bnA|cxpm.1 |W |lehors@sophia.inria.fr | |
| 241 | nA|dash.1,sh.1 |J |herbert@gondor.apana.org.au | |
| 242 | y|dasher.1 | | | |
| 243 | nA|DBD::Gofer.3pm |Jy | | |
| 244 | y|dbz.3 | |inn-bugs@isc.org | |
| 245 | nA|dcut.1 |R |Thomas Viehmann <tv@beamnet.de> | |
| 246 | y|ddd.1 | |ddd@gnu.org | |
| 247 | nA|Parse::DebControl::Error.3pm|Wy |Jay Bonci <jaybonci@cpan.org> | |
| 248 | nA|devnag.1 |J |Zdenek Wagner <wagner@cesnet.cz>, tex-live@tug.org | |
| 249 | nA|dh_install.1 |iy |joeyh@debian.org | |
| 250 | nA|dh_movefiles.1 |Uy |joeyh@debian.org | |
| 251 | y|dhclient.8 | |dhcp-client@isc.org | |
| 252 | n|dhcp-eval.5 |J |Ubuntu Developers <ubuntu-devel-discuss@lists.ubuntu.com> | |
| 253 | y|dicar.1 | |Canna@nec.co.jp | |
| 254 | y|dictfmt.1 | |faith@cs.unc.edu | |
| 255 | y|dictl.1 | |hilliard@debian.org, vle@gmx.net | |
| 256 | y|diffstat.1 | | | |
| 257 | nA|directomatic.1 |oG |till.kamppeter@gmail.com | |
| 258 | y|dislocate.1 | |Don Libes <libes@nist.gov> | |
| 259 | nA|dkms.8 |XJ |dkms-devel@dell.com | |
| 260 | y|dmraid.8 | |Heinz Mauelshagen <Mauelshagen@RedHat.com> | |
| 261 | nA|dpkg.1,dpkg-source.1 |L |debian-dpkg@lists.debian.org | |
| 262 | nA|dosbox.1 |L |dosbox-crew@gmail.com | |
| 263 | y|doxytag.1 | |doxygen-users@lists.sourceforge.net | |
| 264 | y|dpromdic.1 | | | |
| 265 | n|dragdrop.3blt |f |gah@siliconmetrics.com | |
| 266 | nA|dump-acct.8 |U |Daniel Baumann <daniel@debian.org>, Mathieu Trudel <mathieu.tl@gmail.com> | |
| 267 | nA|duplicity.1 |t |Kenneth Loafman <kenneth@loafman.com> | |
| 268 | nA|dv2dt.1 |C |tex-live@tug.org | |
| 269 | y|dvgrab.1 | |nn4lyahoode@thyrsus.com | |
| 270 | 1nA|dvipdf.1,font2c.1 |R |epm@easysw.com | |
| 271 | nA|dvitodvi.1 |R |tex-live@tug.org | |
| 272 | y|dvipdfm.1 | |mwicks@kettering.edu | |
| 273 | 1n|editres.1 |I |xorg@lists.freedesktop.org | |
| 274 | 1nA|e2fsck.8 |o |tytso@thunk.org | |
| 275 | n|e2image.8 |J |tytso@thunk.org | |
| 276 | 1nA|efax.1 |Jug |edc@cce.com | |
| 277 | y|egrep.1,fgrep.1,grep.1| |bug-grep@gnu.org | |
| 278 | y|enscript.1 | |mtr@iki.fi | |
| 279 | y|elinkskeys.5 | |elinks-dev@linuxfromscratch.org | |
| 280 | y|emacs.1 | |bug-gnu-emacs@prep.ai.mit.edu | |
| 281 | y|epoll_ctl.2 | |aeb@cwi.nl, davidel@xmailserver.org | |
| 282 | y|epoll.4 | |aeb@cwi.nl, davidel@xmailserver.org | |
| 283 | y|eqn.1,geqn.1 | |bug-groff@gnu.org | |
| 284 | y|error.3 | |mtk-manpages@gmx.net | |
| 285 | nA|expire.ctl.5 |oY |Ubuntu Developers <ubuntu-devel-discuss@lists.ubuntu.com> | |
| 286 | 1nA|openais_overview.8 |W |scd@broked.com | |
| 287 | y|cpg_overview.8,evs_overview | | | |
| 288 | nA|exiv2.1 |L |Andreas Huggel <ahuggel@gmx.net>, KELEMEN Peter <fuji@debian.org> | |
| 289 | y|expect.1 | |Don Libes <libes@nist.gov> | |
| 290 | 1nA|extractres.1 |R |angus@harlequin.co.uk | |
| 291 | nA|f2py.1,f2py2.7.1 |C |f2py-users@cens.ioc.ee | |
| 292 | nA|faked-sysv.1,faked-tcp.1,faked.1,fakeroot-sysv.1,fakeroot-tcp.1,fakeroot.1|r |schizo@debian.org | |
| 293 | y|fbset.8 | |Geert.Uytterhoeven@cs.kuleuven.ac.be, zippel@fh-brandenburg.de | |
| 294 | nA|fence_drac.8 |J |cluster-devel@redhat.com | |
| 295 | nA|fence_na.8 |Wy |cluster-devel@redhat.com | |
| 296 | nA|fence_drac5.8 |J |cluster-devel@redhat.com | |
| 297 | y|fig2dev.1x | |bvsmith@lbl.gov | |
| 298 | 1nA|fig2ps2tex.1 |R |bvsmith@lbl.gov | |
| 299 | y|findchip.8,irdadump.8,irdaping.8,irpsion5.8,irattach.8| |wehe@tuxmobil.org | |
| 300 | nA|findhyph.1 |C |tex-live@tug.org | |
| 301 | y|firefox.1 | | | |
| 302 | y|flock.1 | |adam@yggdrasil.com | |
| 303 | nA|foo2hbpl2.1,foo2hbpl2-wrapper.1|1 |Rick Richardson <rick.richardson@comcast.net> | |
| 304 | y|foomatic-ppdfile.1 | |till.kamppeter@gmail.com | |
| 305 | 1nA|foomatic-rip.1,lpdomatic.8|oG |till.kamppeter@gmail.com | |
| 306 | nA|formail.1,lockfile.1,procmail.1,procmailex.5,procmailrc.5,procmailsc.5|K |srb@cuci.nl, guenther@sendmail.com | |
| 307 | y|forsort.1 | |Canna@nec.co.jp | |
| 308 | y|free.1 | |albert@users.sf.net | |
| 309 | nA|fsck.8,fsck.ext2.8,fsck.ext3.8,fsck.ext4.8,fsck.ext4dev.8|o |util-linux@vger.kernel.org | |
| 310 | nA|fsck.msdos.8,fsck.vfat.8,dosfsck.8|C |Daniel Baumann <daniel@debian.org> | |
| 311 | y|fsinfo.8 | |ezk@cs.columbia.edu | |
| 312 | nA|ftm.7 |D |mtk-manpages@gmx.net | |
| 313 | nA|fuser.1 |J |Werner Almesberger <werner@almesberger.net>, Craig Small <csmall@enc.com.au> | |
| 314 | nA|fuzzyflakes.6x |C |Barry Dmytro <badcherry@mailc.net> | |
| 315 | nA|gacutil.1,cli-gacutil.1,gacutil2.1|N |mono-docs-list@lists.ximian.com | |
| 316 | y|gaim.1 | |Rob Flynn <gaim@robflynn.com> | |
| 317 | nA|gdb.1 |cJ |gdb-patches@sourceware.org | |
| 318 | nA|genisoimage.1 |o |debburn-devel@lists.alioth.debian.org | |
| 319 | 1nA|getafm.1 |R |rj@rainbow.in-berlin.de | |
| 320 | y|getcon.3,getexeccon.3 | |russell@coker.com.au | |
| 321 | y|getent.1 | |util-linux@vger.kernel.org | |
| 322 | nA|getpass.3 |L |mtk-manpages@gmx.net | |
| 323 | y|GetUid.3 | |tcl-core@lists.sourceforge.net | |
| 324 | nA|get_myaddress.3 |I |mtk-manpages@gmx.net | |
| 325 | y|getcontext.2 | |mtk-manpages@gmx.net | |
| 326 | y|getrpcport.3 | | | |
| 327 | nA|getty.8 |I |util-linux@vger.kernel.org | |
| 328 | y|gfdl.7 | | | |
| 329 | bnA|gftodvi.1 |I | | |
| 330 | y|ghostscript.1 | |giles@snow.thaumas.net | |
| 331 | y|gij.1 | | | |
| 332 | nA|gipddecode.1,hbpldecode.1|1 |Rick Richardson <rick.richardson@comcast.net> | |
| 333 | nA|gmcs.1 |L |mono-docs-list@lists.ximian.com | |
| 334 | y|gnome-session.1 | |Miguel de Icaza <miguel@gnu.org> | |
| 335 | y|gnome-control-center.1| |Ubuntu Desktop Team <ubuntu-desktop@lists.ubuntu.com> | |
| 336 | nA|gnumeric.1 |L |gnumeric-list@gnome.org, Jan Schaumann <jschauma@netmeister.org>, Adrian Custer <acuster@gnome.org> | |
| 337 | y|gnuplot.1 | |gnuplot-info@lists.sourceforge.net | |
| 338 | y|gob2.1 | |George Lebl <jirka@5z.com> | |
| 339 | y|gpic.1,pic.1 | |bug-groff@gnu.org | |
| 340 | nA|gpm-types.7 |JC |gpm@lists.linux.it | |
| 341 | nA|grap.1 |Q |faber@lunabase.org | |
| 342 | y|grn.1 |C |bug-groff@gnu.org | |
| 343 | y|groff.1 | |bug-groff@gnu.org | |
| 344 | y|groff_diff.7 | |bug-groff@gnu.org | |
| 345 | y|groff_char.7 | |bug-groff@gnu.org | |
| 346 | y|groff_mdoc.7 | |bug-groff@gnu.org | |
| 347 | y|groff_me.7 |Io |bug-groff@gnu.org | |
| 348 | n|groff_mom.7 |s |bug-groff@gnu.org | |
| 349 | y|groffer.1 | |bug-groff@gnu.org | |
| 350 | y|grolj4.1,grops.1 | |bug-groff@gnu.org | |
| 351 | p|grodvi.1 |C7 |bug-groff@gnu.org | |
| 352 | nA|gs.1,ghostscript.1 |CY |Ubuntu Developers <ubuntu-devel-discuss@lists.ubuntu.com> | |
| 353 | n|gthumb.1 |L |paolo.bacch@tin.it | |
| 354 | nA|gvcolor.1 |C |Stephen C. North <north@research.att.com>, Emden R. Gansner <erg@research.att.com> | |
| 355 | nA|gvpr.1 |WI |Emden R. Gansner <erg@research.att.com> | |
| 356 | y|hformat.1,hmount.1 | |Robert Leslie <rob@mars.org> | |
| 357 | 6nA|hfsutils.1 |HJ |Robert Leslie <rob@mars.org> | |
| 358 | nA|hgrc.5 |H |mercurial-devel@selenic.com | |
| 359 | y|hidd.1 | |bluez-devel@lists.sourceforge.net | |
| 360 | y|hostname.1 | |Bernd Eckenfels <net-tools@lina.inka.de> | |
| 361 | nA|hosts_access.5,hosts.allow.5,hosts.deny.5,hosts_options.5|IY |Ubuntu Developers <ubuntu-devel-discuss@lists.ubuntu.com> | |
| 362 | bA|hp-plugin.1 |v | | |
| 363 | nA|html2text.1 |C |Martin Bayer <mail@mbayer.de>, Eugene V. Lyubimkin <jackyf.devel@gmail.com> | |
| 364 | nA|html2textrc.5 |X |Martin Bayer <mbayer@zedat.fu-berlin.de> | |
| 365 | y|htfuzzy.1 | |htdig-dev@htdig.org | |
| 366 | y|hwclock.8 | |bunk@stusta.de | |
| 367 | nA|hypertorus.6x |C |Carsten Steger <carsten@mirsanmir.org> | |
| 368 | y|ibod.1 | |Bjoern Smith <bjorn@Compound.SE> | |
| 369 | y|ibod_cf.4 | |Bjoern Smith <bjorn@Compound.SE> | |
| 370 | y|icc2ps.1,jpegicc.1 | |shiju.p@gmail.com | |
| 371 | 1nA|icclink.1 |E |shiju.p@gmail.com | |
| 372 | nA|icctrans.1 |L |shiju.p@gmail.com | |
| 373 | 1nA|tifficc.1 |E |shiju.p@gmail.com | |
| 374 | nA|icmp.7 |o |mtk-manpages@gmx.net | |
| 375 | nA|idmapd.conf.5 |XW |linux-nfs@vger.kernel.org | |
| 376 | y|idna_strerror.3,idna_to_ascii_4i.3,idna_to_ascii_4z.3,idna_to_ascii_8z.3,idna_to_ascii_lz.3,idna_to_unicode_44i.3,idna_to_unicode_4z4z.3,idna_to_unicode_8z4z.3,idna_to_unicode_8z8z.3,idna_to_unicode_8zlz.3,idna_to_unicode_lzlz.3,pr29_4.3,pr29_4z.3,pr29_8z.3,pr29_strerror.3,punycode_decode.3,punycode_strerror.3,stringprep.3,stringprep_4i.3,stringprep_4zi.3,stringprep_check_version.3,stringprep_convert.3,stringprep_locale_charset.3,stringprep_locale_to_utf8.3,stringprep_profile.3,stringprep_strerror.3,stringprep_ucs4_nfkc_normalize.3,stringprep_ucs4_to_utf8.3,stringprep_unichar_to_utf8.3,stringprep_utf8_nfkc_normalize.3,stringprep_utf8_to_locale.3,stringprep_utf8_to_ucs4.3,stringprep_utf8_to_unichar.3,tld_check_4.3,tld_check_4t.3,tld_check_4tz.3,tld_check_4z.3,tld_check_8z.3,tld_check_lz.3,tld_default_table.3,tld_get_4.3,tld_get_4z.3,tld_get_table.3,tld_get_z.3,tld_strerror.3 | |bug-libidn@gnu.org | |
| 377 | y|punycode_encode.3 | |bug-libidn@gnu.org | |
| 378 | nA|icedax.1 |AI |Heiko Eissfeldt <heiko@colossus.escape.de>, debburn-devel@lists.alioth.debian.org | |
| 379 | nA|ilbmtoppm.1 |L |bryanh@giraffe-data.com | |
| 380 | 1nA|includeres.1 |R |giles@artifex.com | |
| 381 | y|ImageMagick.1 | |magick-bugs-owner@imagemagick.org | |
| 382 | 1n|imake.1 |I |xorg@lists.freedesktop.org | |
| 383 | nA|inet.3 |IM |mtk-manpages@gmx.net | |
| 384 | y|inews.1 | |inn-bugs@isc.org | |
| 385 | y|init.5 |I |https://bugs.launchpad.net/upstart/+bug/1185108 | |
| 386 | nA|innfeed.8 |B |inn-bugs@isc.org | |
| 387 | nA|inotify.7 |I |mtk-manpages@gmx.net | |
| 388 | y|install.1 | |bug-coreutils@gnu.org | |
| 389 | y|intel.4 | |xorg@lists.freedesktop.org | |
| 390 | n|intel_panel_fitter.1 |E |intel-gfx@lists.freedesktop.org | |
| 391 | nA|IO::WrapTie.3pm |WC |David F. Skoll <dfs@roaringpenguin.com> | |
| 392 | n|ip-netns.8,ip-maddress.8,ip-tunnel.8,ip-route.8|6 |netdev@vger.kernel.org | |
| 393 | n|ip-neighbour.8 |6QI |netdev@vger.kernel.org | |
| 394 | n|ip-rule.8 |6I |netdev@vger.kernel.org | |
| 395 | nA|ipcrm.1 |C |util-linux@vger.kernel.org | |
| 396 | 1nA|ipppd.8 |L |keil@isdn4linux.de | |
| 397 | y|ip6tables.8 | |netfilter-devel@lists.netfilter.org | |
| 398 | 1nA|iptables.8 |CJL |netfilter-devel@lists.netfilter.org | |
| 399 | nA|ip6tables-save.8 |U |netfilter-devel@lists.netfilter.org | |
| 400 | nA|ipptoolfile.5 |J |cups-dev@easysw.com | |
| 401 | y|iptraf.8 | |riker@seul.org | |
| 402 | 1nA|ipv6calc.8 |Lo |pb@bieringer.de | |
| 403 | y|irb.1 | |ruby-doc@ruby-lang.org | |
| 404 | nA|irda.7 |0 |Jean Tourrilhes <jt@hpl.hp.com> | |
| 405 | y|irnet.4 | |jt@hpl.hp.com | |
| 406 | y|irsend.1 | |lirc@bartelmus.de | |
| 407 | y|isadump.8,isaset.8 | |phil@philedelbrock.com | |
| 408 | nA|ispell.1,buildhash.1,munchlist.1,findaffix.1,tryaffix.1,icombine.1,ijoin.1|C |ispell-bugs@itcorp.com | |
| 409 | nA|ispell-wrapper.1 |CY |Ubuntu Developers <ubuntu-devel-discuss@lists.ubuntu.com> | |
| 410 | nA|kioclient.1 |k |Kubuntu Developers <kubuntu-devel@lists.ubuntu.com> | |
| 411 | y|lamboot.1 | |lam-devel@lam-mpi.org | |
| 412 | n|lamd.1 | |lam-devel@lam-mpi.org | |
| 413 | nA|lam.7,LAM.7 |L |lam-devel@lam-mpi.org | |
| 414 | nA|lam-helpfile.5 |I |lam-devel@lam-mpi.org | |
| 415 | b|lastcomm.1 |I |https://savannah.gnu.org/bugs/index.php?39134 | |
| 416 | y|lastlog.8 | | | |
| 417 | y|latex.1 | |te@dbs.uni-hannover.de | |
| 418 | nA|latin2.7,iso_8859-2.7,iso_8859_2.7,iso-8859-2.7|* |mtk-manpages@gmx.net | |
| 419 | y|LDP.7 | | | |
| 420 | nA|ld-linux.8,ld-linux.so.8|L |mtk-manpages@gmx.net | |
| 421 | 1nA|ld.so.8 |L |mtk-manpages@gmx.net | |
| 422 | 6nA|less.1,pager.1 |J |bug-less@gnu.org | |
| 423 | nA|lftp.1 |I |lav@yars.free.net, | |
| 424 | nA|libcaca-authors.3caca|W |Sam Hocevar <sam@hocevar.net> | |
| 425 | nA|libcaca-canvas.3caca |WJ |Sam Hocevar <sam@hocevar.net> | |
| 426 | nA|libcaca-env.3caca |WL |Sam Hocevar <sam@hocevar.net> | |
| 427 | nA|libcaca-font.3caca |WJ |Sam Hocevar <sam@hocevar.net> | |
| 428 | nA|libcaca-ruby.3caca |W |Sam Hocevar <sam@hocevar.net> | |
| 429 | nA|libcaca-tutorial.3caca|W |Sam Hocevar <sam@hocevar.net> | |
| 430 | 4nA|libpng.3 |SJ |png-mng-implement@lists.sourceforge.net | |
| 431 | y|libpngpf.3 | |png-mng-implement@lists.sourceforge.net | |
| 432 | b|libreoffice.1,loffice.1,lofromtemplate.1|J |https://bugs.freedesktop.org/show_bug.cgi?id=65243 | |
| 433 | nA|libtiff.3tiff |I |tiff@lists.maptools.org | |
| 434 | y|licensecheck.1 | |Ubuntu Developers <ubuntu-devel-discuss@lists.ubuntu.com> | |
| 435 | nA|list_audio_tracks.1 |W |Heiko Eissfeldt <heiko@colossus.escape.de>, debburn-devel@lists.alioth.debian.org | |
| 436 | 1nA|ln.1 |j |bug-coreutils@gnu.org | |
| 437 | y|locate.1 | |mitr@redhat.com | |
| 438 | n|locate.findutils.1 |U |bug-findutils@gnu.org | |
| 439 | nA|logger.1 |O |util-linux@vger.kernel.org | |
| 440 | y|logrotate.8 | | | |
| 441 | nA|logsys_overview.8 |JY |Ubuntu Developers <ubuntu-devel-discuss@lists.ubuntu.com> | |
| 442 | y|indxbib.1 | |bug-groff@gnu.org | |
| 443 | n|lkbib.1 |C |bug-groff@gnu.org | |
| 444 | y|lookbib.1 | |bug-groff@gnu.org | |
| 445 | 6nA|lpr.1 |U |papowell@lprng.com | |
| 446 | y|lpstat.1,lpstat-cups.1| |papowell@lprng.com | |
| 447 | y|lsof.8 | |abe@purdue.edu | |
| 448 | nA|lynx.1,www-browser.1 |C |lynx-dev@nongnu.org | |
| 449 | y|mag.1 | |te@dbs.uni-hannover.de | |
| 450 | nA|makeindex.1 |J |tex-live@tug.org | |
| 451 | y|man.1,manpath.1 | |mtk-manpages@gmx.net | |
| 452 | nA|mawk.1 |R |http://code.google.com/p/original-mawk/issues/detail?id=21&thanks=21&ts=1369758804 | |
| 453 | y|mcs.8 | | | |
| 454 | y|mdel.1 | |mtools@mtools.linux.lu | |
| 455 | nA|mdoc.7 |J |mtk-manpages@gmx.net | |
| 456 | y|merge.1 | |bug-rcs@gnu.org | |
| 457 | y|mev.1 | |gpm@lists.linux.it | |
| 458 | y|mf.1,inimf.1,virmf.1 | |te@dbs.uni-hannover.de | |
| 459 | nA|mkdosfs.8,mkfs.msdos.8,mkfs.vfat.8|C |Daniel Baumann <daniel@debian.org> | |
| 460 | y|mkdtemp.3 | |mtk-manpages@gmx.net | |
| 461 | nA|mkjobtexmf.1 |Ly |tex-live@tug.org | |
| 462 | y|mkzftree.1 | |hpa@zytor.com | |
| 463 | nA|mlocate.db.5 |J |Miloslav Trmac <mitr@redhat.com> | |
| 464 | nA|mono.1,cli.1 |JX |mono-docs-list@lists.ximian.com | |
| 465 | nA|mono-config.5 |X |mono-docs-list@lists.ximian.com | |
| 466 | nA|more.1 |O |util-linux@vger.kernel.org | |
| 467 | y|motd.news.5 | |inn-bugs@isc.org | |
| 468 | y|mount.fuse.8 | |fuse-devel@lists.sourceforge.net | |
| 469 | y|mozplugger.7 | |louis@bavoil.net | |
| 470 | y|mpcd.8 | |Heikki Vatiainen <hessu@cs.tut.fi>, Sampo Saaristo <s156953@cs.tut.fi> | |
| 471 | y|mpiexec.1 | |lam-devel@lam-mpi.org | |
| 472 | y|mpiexec.lam.1 | |lam-devel@lam-mpi.org | |
| 473 | y|mpimsg.1,mpitask.1 | |lam-devel@lam-mpi.org | |
| 474 | n|mpirun.1,mpirun.lam.1 |L |lam-devel@lam-mpi.org | |
| 475 | y|mpost.1 | | | |
| 476 | nA|mq_overview.7 |I |mtk-manpages@gmx.net | |
| 477 | n|mtools.5,mtools.conf.5|X |mtools@mtools.linux.lu | |
| 478 | nA|mtr.8 |J |mtr@lists.xmission.com | |
| 479 | y|mtx.1 | |eric@badtux.org | |
| 480 | nA|mutt.1 |JQ |mutt-dev@mutt.org | |
| 481 | nA|muttrc.5 |JXu |mutt-dev@mutt.org | |
| 482 | y|mysqld.1,mysqld_multi.1,mysqldump.1,mysql_zap.1,mysqladmin.1,mysqlshow.1| |monty@tcx.se | |
| 483 | y|named.conf.5 | |bind9-bugs@isc.org | |
| 484 | y|nasm.1,ndisasm.1 | |nasm-devel@lists.sourceforge.net | |
| 485 | n|nautilus.1 |L |Ubuntu Desktop Team <ubuntu-desktop@lists.ubuntu.com> | |
| 486 | nA|nautilus-connect-server.1|L|nautilus-list@gnome.org | |
| 487 | y|nbp_name.3 | |netatalk-devel@lists.sourceforge.net | |
| 488 | nA|netpbm.1 |J |bryanh@giraffe-data.com | |
| 489 | nA|netstat.8 |Cz |ecki@linux.de | |
| 490 | y|newgrp.1 | |Julianne Frances Haugh <jockgrrl@ix.netcom.com> | |
| 491 | y|nfsd.7 | |neilb@cse.unsw.edu.au | |
| 492 | nA|nfsmount.conf.5 |CY |ubuntu-devel-discuss@lists.ubuntu.com | |
| 493 | y|NetworkManager.1,nm-tool.1 | |networkmanager-list@gnome.org | |
| 494 | n|nmcli.1,nm-connection-editor.1|WX |networkmanager-list@gnome.org | |
| 495 | nA|nsgmls.1 |CI |James Clark <jjc@jclark.com> | |
| 496 | y|nslookup.1 | | | |
| 497 | nA|ntfs-3g.secaudit.8 |CY |Ubuntu Developers <ubuntu-devel-discuss@lists.ubuntu.com> | |
| 498 | nA|ntfs-3g.usermap.8 |C |ntfs-3g-devel@lists.sf.net | |
| 499 | y|ntpdate.1 | |mills@udel.edu | |
| 500 | y|ntpq.1 | |mills@udel.edu | |
| 501 | nA|nvidia-settings.1 |IxY |ubuntu-devel-discuss@lists.ubuntu.com | |
| 502 | nA|nvidia-smi.1 |I6Y |ubuntu-devel-discuss@lists.ubuntu.com | |
| 503 | y|octave-config.1 | |jwe@bevo.che.wisc.edu, edd@debian.org | |
| 504 | nA|ode.1 |e |bug-gnu-utils@gnu.org | |
| 505 | nA|oldfind.1,find.1 |J |findutils-patches@gnu.org | |
| 506 | nA|omfonts.1 |W |tex-live@tug.org | |
| 507 | y|on_ac_power.1 | |Richard Hughes <richard@hughsie.com> | |
| 508 | 1nA|openvt.1,open.1 |L |aeb@cwi.nl | |
| 509 | y|operator.7 | |mtk-manpages@gmx.net | |
| 510 | nA|orbd.1 |WyY |ubuntu-devel-discuss@lists.ubuntu.com | |
| 511 | nA|orca.1 |s |orca-list@gnome.org | |
| 512 | nA|osage.1,mm2gv.1 |J |Emden R. Gansner <erg@research.att.com> | |
| 513 | y|parted.8 | |bug-parted@gnu.org | |
| 514 | nA|patch.1 |It |bug-patch@gnu.org | |
| 515 | nA|pax.1posix |WJL |Francesco Paolo Lovergine <frankie@debian.org> | |
| 516 | nA|pbmclean.1,pnmcomp.1,pnmnorm.1,pnmpad.1,pnmquant.1,pnmremap.1,pnmtotiff.1,pgmnorm.1,ppmcolors.1,ppmnorm.1,ppmntsc.1,ppmquant.1,ppmrainbow.1,ppmtogif.1,ppmtoxpm.1,tifftopnm.1|C |bryanh@giraffe-data.com | |
| 517 | nA|pbget.1,pbput.1,pbputs.1 |W |Dustin Kirkland <kirkland@ubuntu.com> | |
| 518 | nA|pbmtextps.1 |C |Bryan Henderson <bryanh@giraffe-data.com> | |
| 519 | nA|pcap-filter.7 |I |tcpdump-workers@lists.tcpdump.org | |
| 520 | y|pcre.3,pcrebuild.3 | |ph10@cam.ac.uk | |
| 521 | nA|pcreapi.3 |I |http://bugs.exim.org/show_bug.cgi?id=1359 | |
| 522 | nA|pcreposix.3 |H |http://bugs.exim.org/show_bug.cgi?id=1360 | |
| 523 | y|pcreprecompile.3 | |ph10@cam.ac.uk | |
| 524 | y|pcrepattern.3,pcrecallout.3,pcrepartial.3| |ph10@cam.ac.uk | |
| 525 | y|pdfseparate.1 ` | |poppler@lists.freedesktop.org | |
| 526 | y|pgmabel.1,pgmtopgm.1,pnmstitch.1,pgmmorphconv.1,pnmtoddif.1,ppmtopj.1 | |Bryan Henderson <bryanh@giraffe-data.com> | |
| 527 | y|php.1 | |phpdoc@lists.php.net | |
| 528 | nA|pidgin.1 |T |Sean Egan <seanegan@gmail.com>, Ben Tegarden <tegarden@uclink.berkeley.edu>, John Bailey <rekkanoryo@pidgin.im> | |
| 529 | y|pipe.8 | |wietse@porcupine.org | |
| 530 | nA|pkg-config.1 |q |pkg-config@lists.freedesktop.org | |
| 531 | y|play.1 | | | |
| 532 | nA|plot.1,plotfont.1 |W |bug-gnu-utils@gnu.org | |
| 533 | nA|pmap_getmaps.3 |I |mtk-manpages@gmx.net | |
| 534 | nA|pmap_getport.3 |I |mtk-manpages@gmx.net | |
| 535 | nA|pmap_rmtcall.3 |I |mtk-manpages@gmx.net | |
| 536 | nA|pmap_set.3 |I |mtk-manpages@gmx.net | |
| 537 | nA|pmap_unset.3 |I |mtk-manpages@gmx.net | |
| 538 | nA|pnmhisteq.1,ppmcie.1,ppmlabel.1,sbigtopgm.1|R |Bryan Henderson <bryanh@giraffe-data.com> | |
| 539 | nA|pnmpaste.1 |X |Bryan Henderson <bryanh@giraffe-data.com> | |
| 540 | nA|pnmtotiffcmyk.1 |C |Bryan Henderson <bryanh@giraffe-data.com> | |
| 541 | nA|pnmtofiasco.1 |e |Bryan Henderson <bryanh@giraffe-data.com> | |
| 542 | nA|policytool.1 |Wy |openjdk@lists.launchpad.net | |
| 543 | y|servertool.1 | |openjdk@lists.launchpad.net | |
| 544 | y|postconf.5 | |wietse@porcupine.org | |
| 545 | y|postmap.1,postsuper.1 | |wietse@porcupine.org | |
| 546 | nA|proc.5 |Io |mtk-manpages@gmx.net | |
| 547 | y|ps.1 | |acahalan@cs.uml.edu | |
| 548 | n|pstree.1,pstree.x11.1 |C |Craig Small <csmall@small.dropbear.id.au> | |
| 549 | bA|pstops.1 |R | | |
| 550 | y|proxymap.8 | |wietse@porcupine.org | |
| 551 | 6nA|ps2epsi.1 |j |giles@artifex.com | |
| 552 | y|ps2pdf.1,ps2pdf12.1,ps2pdf13.1| |giles@artifex.com | |
| 553 | nA|ps2pdfwr.1 |R |giles@artifex.com | |
| 554 | 1nA|psnup.1 |J |giles@artifex.com | |
| 555 | 1nA|pthreads.7 |I |mtk-manpages@gmx.net | |
| 556 | 6nA|ptx.1 |j |bug-gnu-utils@gnu.org | |
| 557 | nA|pytest.1 |C |doc-sig@python.org | |
| 558 | y|quotactl.2 | |jkar8572@sers.sourceforge.net | |
| 559 | 1nA|qos.7 |L |linux-atm-general@lists.sourceforge.net | |
| 560 | nA|qsub.1posix |I |Francesco Paolo Lovergine <frankie@debian.org> | |
| 561 | y|racoon.conf.5 | |bugs@lists.freeswan.org | |
| 562 | n|radeon.4 |L |xorg@lists.freedesktop.org | |
| 563 | y|random.4 | |mtk-manpages@gmx.net | |
| 564 | n|rcsfile.5 |d |rcs-bugs@gnu.org | |
| 565 | y|ram.4 | |mtk-manpages@gmx.net | |
| 566 | y|raw2tiff.1,tiffcmp.1 | |tiff@lists.maptools.org | |
| 567 | bA|rc-alert.1 |u |Julian Gilbey <jdg@debian.org>, Adam D. Barratt <adam@adam-barratt.org.uk> | |
| 568 | y|rcsintro.1 |u |bug-rcs@gnu.org | |
| 569 | y|refer.1 | |bug-groff@gnu.org | |
| 570 | nA|registerrpc.3 |I |mtk-manpages@gmx.net | |
| 571 | nA|regulatory.bin.5 |w |linux-wireless@vger.kernel.org | |
| 572 | bA|renice.1 |O |http://userweb.kernel.org/~kzak/util-linux/ | |
| 573 | y|replace.1,isamchk.1,isamlog.1| |monty@tcx.se | |
| 574 | y|resize2fs.8 | |tytso@thunk.org | |
| 575 | y|rexec.3 | | | |
| 576 | bA|rev.1 |OL |http://userweb.kernel.org/~kzak/util-linux/ | |
| 577 | y|rdump.8,dump.8,restore.8,rrestore.8 | |Stelian Pop <stelian@popies.net> | |
| 578 | nA|rhythmbox-client.1 |L |Sven Arvidsson <sa@whiz.se>, gnome-doc-list@gnome.org | |
| 579 | nA|rlog.1 |L |rcs-bugs@gnu.org | |
| 580 | nA|rlogin.1 |nY |Ubuntu Developers <ubuntu-devel-discuss@lists.ubuntu.com> | |
| 581 | nA|rlwrap.1,readline-editor.1|J |Chet Ramey <chet.ramey@case.edu> | |
| 582 | nA|rmid.1 |Wy |openjdk@lists.launchpad.net | |
| 583 | nA|rmiregistry.1 |Wy |openjdk@lists.launchpad.net | |
| 584 | y|roff.7 | |bug-groff@gnu.org | |
| 585 | nA|rotatelogs.8 |* |docs@httpd.apache.org | |
| 586 | nA|rpc.3 |I |mtk-manpages@gmx.net | |
| 587 | nA|rpc.5 |c |mtk-manpages@gmx.net | |
| 588 | nA|rsh.1,ssh.1,authorized_keys.5,sshd.8|nY |Ubuntu Developers <ubuntu-devel-discuss@lists.ubuntu.com> | |
| 589 | p|rstartd.1 |I |xorg@lists.freedesktop.org | |
| 590 | nA|rsyslog.conf.5 |J |rsyslog@lists.adiscon.com | |
| 591 | n|ruby.1,ruby1.9.1.1 |L |ruby-doc@ruby-lang.org | |
| 592 | p|s3.4 |I |xorg@lists.freedesktop.org | |
| 593 | nA|sane-apple.5 |L |https://alioth.debian.org/tracker/index.php?func=detail&aid=314280&group_id=30186&atid=410366 | |
| 594 | nA|sane-lexmark.5 |Lo |https://alioth.debian.org/tracker/index.php?func=detail&aid=314281&group_id=30186&atid=410366 | |
| 595 | nA|sane-mustek_pp.5 |Lo |https://alioth.debian.org/tracker/index.php?func=detail&aid=314282&group_id=30186&atid=410366 | |
| 596 | y|sane-pixma.5 |W |https://alioth.debian.org/tracker/index.php?func=detail&aid=314283&group_id=30186&atid=410366 | |
| 597 | y|scons.1 | |scons-dev@scons.org | |
| 598 | nA|scons-time.1 |LZ |scons-dev@scons.org | |
| 599 | nA|script.1 |O |util-linux@vger.kernel.org | |
| 600 | 1nA|SDL_Init.3 |L |sdl@lists.libsdl.org | |
| 601 | nA|SDL_CDPlayTracks.3 |8 |docs@lists.libsdl.org | |
| 602 | y|security.3 | |xorg@lists.freedesktop.org | |
| 603 | nA|see.1,run-mailcap.1,print.1 |C |Brian White <bcwhite@pobox.com> | |
| 604 | y|send-uucp.8 | |inn-bugs@isc.org | |
| 605 | nA|setcap.8 |C |Andrew G. Morgan <morgan@kernel.org> | |
| 606 | y|setpci.8 | |Martin Mares <mj@ucw.cz> | |
| 607 | y|sg_senddiag.8,sg_wr_mode.8 | |dgilbert@interlog.com | |
| 608 | nA|sg_sat_phy_event.8 |C |dgilbert@interlog.com | |
| 609 | nA|sgmlspl.1 |L |Ardo van Rangelrooij <ardo@debian.org> | |
| 610 | nA|signal.7 |I |mtk-manpages@gmx.net | |
| 611 | y|sk98lin.4 | |linux@syskonnect.de | |
| 612 | y|slapd.8 | |OpenLDAP-devel@OpenLDAP.org | |
| 613 | y|slapdn.8,slapacl.8,slapadd.8 |u |OpenLDAP-devel@OpenLDAP.org | |
| 614 | nA|slapd.conf.5 |LI |OpenLDAP-devel@OpenLDAP.org | |
| 615 | nA|slapd-config.5 |LI |OpenLDAP-devel@OpenLDAP.org | |
| 616 | nA|slapo-constraint.5 |L |OpenLDAP-devel@OpenLDAP.org | |
| 617 | nA|slogin.1 |n |openssh-unix-dev@mindrot.org | |
| 618 | y|snmpvacm.1 | |net-snmp-coders@lists.sourceforge.net | |
| 619 | y|snmpd.conf.5 | |net-snmp-coders@lists.sourceforge.net | |
| 620 | y|snmp.conf.5 | |net-snmp-coders@lists.sourceforge.net | |
| 621 | nA|snmpd.examples.5snmp |J |net-snmp-coders@lists.sourceforge.net | |
| 622 | y|socket-event.7 | |https://bugs.launchpad.net/upstart/+bug/1018925 | |
| 623 | bA|software-properties-gtk.1 |W | | |
| 624 | nA|spam.1 |C | | |
| 625 | nA|spufs.7 |I |mtk-manpages@gmx.net | |
| 626 | y|squid_ldap_auth.8,squid_ldap_group.8 | |squid-bugs@squid-cache.org | |
| 627 | 3pA|sshd_config.5,ssh_config.5 |n |brad@openbsd.org | |
| 628 | nA|ssh-keygen.1 |Rn |Colin Watson <cjwatson@ubuntu.com> | |
| 629 | y|states.1 | |mtr@iki.fi | |
| 630 | n|sudoers.5 |n |Todd C. Miller <Todd.Miller@courtesan.com> | |
| 631 | nA|svc_destroy.3 |I |mtk-manpages@gmx.net | |
| 632 | nA|svc_freeargs.3 |I |mtk-manpages@gmx.net | |
| 633 | nA|svc_getargs.3 |I |mtk-manpages@gmx.net | |
| 634 | nA|svc_getcaller.3 |I |mtk-manpages@gmx.net | |
| 635 | nA|svc_getreq.3 |I |mtk-manpages@gmx.net | |
| 636 | nA|svc_getreqset.3 |I |mtk-manpages@gmx.net | |
| 637 | nA|svc_register.3 |I |mtk-manpages@gmx.net | |
| 638 | nA|svc_run.3 |I |mtk-manpages@gmx.net | |
| 639 | nA|svc_sendreply.3 |I |mtk-manpages@gmx.net | |
| 640 | nA|svc_unregister.3 |I |mtk-manpages@gmx.net | |
| 641 | nA|svcerr_auth.3 |I |mtk-manpages@gmx.net | |
| 642 | nA|svcerr_decode.3 |I |mtk-manpages@gmx.net | |
| 643 | nA|svcerr_noprog.3 |I |mtk-manpages@gmx.net | |
| 644 | nA|svcerr_noproc.3 |I |mtk-manpages@gmx.net | |
| 645 | nA|svcerr_progvers.3 |I |mtk-manpages@gmx.net | |
| 646 | nA|svcerr_systemerr.3 |I |mtk-manpages@gmx.net | |
| 647 | nA|svcerr_weakauth.3 |I |mtk-manpages@gmx.net | |
| 648 | nA|svcfd_create.3 |I |mtk-manpages@gmx.net | |
| 649 | nA|svcraw_create.3 |I |mtk-manpages@gmx.net | |
| 650 | nA|svctcp_create.3 |I |mtk-manpages@gmx.net | |
| 651 | nA|svcudp_bufcreate.3 |I |mtk-manpages@gmx.net | |
| 652 | nA|svcudp_create.3 |I |mtk-manpages@gmx.net | |
| 653 | y|synclient.1 | |mtk-manpages@gmx.net | |
| 654 | nA|synctex.1 |5 |tex-live@tug.org | |
| 655 | 6nA|rb.1,rx.1,rz.1,sb.1,sx.1,sz.1|e |Uwe Ohse <uwe@ohse.de> | |
| 656 | nA|tar.1 |CV |bug-tar@gnu.org | |
| 657 | nA|tc-prio.8,tc-htb.8,tc-cbq.8,tc-cbq-details.8 |C |net@vger.kernel.org | |
| 658 | nA|tc-stab.8 |IJ |net@vger.kernel.org | |
| 659 | 1nA|tcpd.8 |I |wietse@porcupine.org | |
| 660 | nA|tcpdmatch.8 |I |wietse@porcupine.org | |
| 661 | nA|tek2plot.1 |W |bug-gnu-utils@gnu.org | |
| 662 | nA|telnet.1,telnet.netkit.1|XY |Ubuntu Developers <ubuntu-devel-discuss@lists.ubuntu.com> | |
| 663 | nA|test.1,[.1 | |bug-coreutils@gnu.org | |
| 664 | y|texdoctk.1 | |bunk@fs.tum.de, ruedas@geophysik.uni-frankfurt.de | |
| 665 | bA|terminfo.5 |Ia |bug-ncurses@gnu.org | |
| 666 | y|tfmtodit.1 | |bug-groff@gnu.org | |
| 667 | nA|TIFFGetField.3tiff |I |tiff@lists.maptools.org | |
| 668 | nA|TIFFmemory.3tiff |4 |tiff@lists.maptools.org | |
| 669 | nA|Tk::Internals.3pm |WY |Ubuntu Developers <ubuntu-devel-discuss@lists.ubuntu.com> | |
| 670 | nA|tnameserv.1 |Wy |openjdk@lists.launchpad.net | |
| 671 | nA|tgatoppm.1 |A |bryanh@giraffe-data.com | |
| 672 | 1nA|tidy.1 |Wm |tidy-develop@lists.sourceforge.net,html-tidy@w3.org | |
| 673 | y|time.1 | |bug-gnu-utils@prep.ai.mit.edu | |
| 674 | n|top.1 |XoQ |Jim Warner <james.warner@comcast.net> | |
| 675 | y|transfig.1x | |bvsmith@lbl.gov | |
| 676 | 1nA|tree.1 |b |Steve Baker <ice@mama.indstate.edu> | |
| 677 | nA|ttf2tfm.1 |Io |tex-live@tug.org | |
| 678 | nA|tty_ioctl.4 |L |mtk-manpages@gmx.net | |
| 679 | 6nA|tune2fs.8 |C |tytso@thunk.org | |
| 680 | n|tzfile.5 |I |mtk-manpages@gmx.net | |
| 681 | y|udevd.8,udevsend.8 | |Kay Sievers <kay.sievers@vrfy.org> | |
| 682 | y|units.1 | |adrian@cam.cornell.edu | |
| 683 | nA|unity-2d-shell.1 |CJY |Ubuntu Developers <ubuntu-devel-discuss@lists.ubuntu.com> | |
| 684 | nA|unity-2d-spread.1 |CY |Ubuntu Developers <ubuntu-devel-discuss@lists.ubuntu.com> | |
| 685 | nA|upstart-events.7 |I |James Hunt <james.hunt@ubuntu.com> | |
| 686 | n|uscan.1 |J |Julian Gilbey <jdg@debian.org> | |
| 687 | nA|usb-creator-gtk.8 |W |Evan Dandrea <evand@ubuntu.com>, Roderick B. Greening <roderick.greening@gmail.com> | |
| 688 | nA|xz.1,xzcat.1,unxz.1,unlzma.1,lzcat.1,lzma.1|C |lasse.collin@tukaani.org | |
| 689 | nA|unshare.1 |L |util-linux@vger.kernel.org | |
| 690 | y|unzip.1,unzipsfx.1 | |roelofs@pobox.com | |
| 691 | nA|updatedb.conf.5 |J |Miloslav Trmac <mitr@redhat.com> | |
| 692 | y|uuencode.1 | |bug-gnu-utils@gnu.org | |
| 693 | nA|uuencode.1posix |I |Francesco Paolo Lovergine <frankie@debian.org> | |
| 694 | n|vector.3blt |LIG3 |gah@siliconmetrics.com | |
| 695 | p|viewres.1 |I |xorg@lists.freedesktop.org | |
| 696 | n*A|vlna.1 |F |tex-live@tug.org | |
| 697 | y|vmstat.8 | |Henry Ware <al172@yfn.ysu.edu>, Fabian Frédérick <ffrederick@users.sourceforge.net> | |
| 698 | 1nA|wall.1 |LO |util-linux@vger.kernel.org | |
| 699 | n|weechat-curses.1 |s |Sebastien Helleu <flashcode@flashtux.org> | |
| 700 | y|wget.1 | |mtortonesi@ing.unife.it | |
| 701 | 1nA|whereis.1 |L |bunk@stusta.de | |
| 702 | y|which.1 | | | |
| 703 | nA|whois.1 |LY |Ubuntu Developers <ubuntu-devel-discuss@lists.ubuntu.com> | |
| 704 | p|XAddHost.3 |I |xorg@lists.freedesktop.org | |
| 705 | 1n|XAllocWMHints.3 |I |xorg@lists.freedesktop.org | |
| 706 | y|Xaw.3x | |xorg@lists.freedesktop.org | |
| 707 | y|XcmsColor.3x | |xorg@lists.freedesktop.org | |
| 708 | y|XDrawArc.3x | |xorg@lists.freedesktop.org | |
| 709 | nA|xdr.3,xdr_array.3 |I |mtk-manpages@gmx.net | |
| 710 | p|X.7 |ILo |xorg@lists.freedesktop.org | |
| 711 | y|XQueryColor.3x | |xorg@lists.freedesktop.org | |
| 712 | y|XLoadFont.3x | |xorg@lists.freedesktop.org | |
| 713 | y|XrmGetFileDatabase.3x | |xorg@lists.freedesktop.org | |
| 714 | p|XSizeHints.3 |I |xorg@lists.freedesktop.org | |
| 715 | p|XAllocClassHint.3 |I |xorg@lists.freedesktop.org | |
| 716 | p|XAllocIconSize.3 |I |xorg@lists.freedesktop.org | |
| 717 | p|XAllocSizeHints.3 |I |xorg@lists.freedesktop.org | |
| 718 | p|XAllocStandardColormap.3 |I |xorg@lists.freedesktop.org | |
| 719 | p|XAnyEvent.3 |I |xorg@lists.freedesktop.org | |
| 720 | p|XAutoRepeatOn.3 |I |xorg@lists.freedesktop.org | |
| 721 | p|XAutoRepeatOff.3 |I |xorg@lists.freedesktop.org | |
| 722 | p|XBell.3 |I |xorg@lists.freedesktop.org | |
| 723 | p|XButtonEvent.3 |I |xorg@lists.freedesktop.org | |
| 724 | p|XChangeGC.3 |I |xorg@lists.freedesktop.org | |
| 725 | p|XChangeKeyboardControl.3|I |xorg@lists.freedesktop.org | |
| 726 | p|XChangeKeyboardMapping.3|I |xorg@lists.freedesktop.org | |
| 727 | p|XCirculateEvent.3 |I |xorg@lists.freedesktop.org | |
| 728 | p|XCirculateRequestEvent.3 |I |xorg@lists.freedesktop.org | |
| 729 | p|XClassHint.3 |I |xorg@lists.freedesktop.org | |
| 730 | p|XClientMessageEvent.3 |I |xorg@lists.freedesktop.org | |
| 731 | p|XColor.3 |I |xorg@lists.freedesktop.org | |
| 732 | p|XColormapEvent.3 |I |xorg@lists.freedesktop.org | |
| 733 | p|XConfigureEvent.3 |I |xorg@lists.freedesktop.org | |
| 734 | p|XConfigureRequestEvent.3 |I |xorg@lists.freedesktop.org | |
| 735 | p|XConfigureWindow.3 |I |xorg@lists.freedesktop.org | |
| 736 | p|XCopyColormapAndFree.3|I |xorg@lists.freedesktop.org | |
| 737 | p|XCopyGC.3 |I |xorg@lists.freedesktop.org | |
| 738 | p|XCreateColormap.3 |I |xorg@lists.freedesktop.org | |
| 739 | p|XCreateGC.3 |I |xorg@lists.freedesktop.org | |
| 740 | p|XCreateSimpleWindow.3 |I |xorg@lists.freedesktop.org | |
| 741 | p|XCreateWindow.3 |I |xorg@lists.freedesktop.org | |
| 742 | p|XCreateWindowEvent.3 |I |xorg@lists.freedesktop.org | |
| 743 | p|XCrossingEvent.3 |I |xorg@lists.freedesktop.org | |
| 744 | p|XDefaultString.3 |I |xorg@lists.freedesktop.org | |
| 745 | p|XDeleteModifiermapEntry.3 |I |xorg@lists.freedesktop.org | |
| 746 | p|XDestroyWindowEvent.3 |I |xorg@lists.freedesktop.org | |
| 747 | p|XDisableAccessControl.3 |I |xorg@lists.freedesktop.org | |
| 748 | p|XDisplayKeycodes.3 |I |xorg@lists.freedesktop.org | |
| 749 | p|XDisplayMotionBufferSize.3 |I |xorg@lists.freedesktop.org | |
| 750 | p|XDrawLine.3 |I |xorg@lists.freedesktop.org | |
| 751 | p|XDrawLines.3 |I |xorg@lists.freedesktop.org | |
| 752 | p|XDrawPoint.3 |I |xorg@lists.freedesktop.org | |
| 753 | p|XDrawPoints.3 |I |xorg@lists.freedesktop.org | |
| 754 | p|XDrawRectangle.3 |I |xorg@lists.freedesktop.org | |
| 755 | p|XDrawRectangles.3 |I |xorg@lists.freedesktop.org | |
| 756 | p|XDrawSegments.3 |I |xorg@lists.freedesktop.org | |
| 757 | p|XDrawText.3 |I |xorg@lists.freedesktop.org | |
| 758 | p|XDrawText16.3 |I |xorg@lists.freedesktop.org | |
| 759 | p|XEnableAccessControl.3|I |xorg@lists.freedesktop.org | |
| 760 | p|XErrorEvent.3 |I |xorg@lists.freedesktop.org | |
| 761 | p|XEvent.3 |I |xorg@lists.freedesktop.org | |
| 762 | p|XExposeEvent.3 |I |xorg@lists.freedesktop.org | |
| 763 | p|XFocusChangeEvent.3 |I |xorg@lists.freedesktop.org | |
| 764 | p|XFontSetExtents.3 |I |xorg@lists.freedesktop.org | |
| 765 | p|XFreeColormap.3 |I |xorg@lists.freedesktop.org | |
| 766 | p|XFreeEventData.3 |I |xorg@lists.freedesktop.org | |
| 767 | p|XFreeGC.3 |I |xorg@lists.freedesktop.org | |
| 768 | p|XFreeModifiermap.3 |I |xorg@lists.freedesktop.org | |
| 769 | p|XFreeStringList.3 |I |xorg@lists.freedesktop.org | |
| 770 | n|XF86VM.3 |I |xorg@lists.freedesktop.org | |
| 771 | p|XGCValues.3 |I |xorg@lists.freedesktop.org | |
| 772 | p|XGContextFromGC.3 |I |xorg@lists.freedesktop.org | |
| 773 | p|XGenericEventCookie.3 |I |xorg@lists.freedesktop.org | |
| 774 | p|XGetClassHint.3 |I |xorg@lists.freedesktop.org | |
| 775 | p|XGetEventData.3 |I |xorg@lists.freedesktop.org | |
| 776 | p|XGetGCValues.3 |I |xorg@lists.freedesktop.org | |
| 777 | p|XGetGeometry.3 |I |xorg@lists.freedesktop.org | |
| 778 | p|XGetIconSizes.3 |I |xorg@lists.freedesktop.org | |
| 779 | p|XGetKeyboardControl.3 |I |xorg@lists.freedesktop.org | |
| 780 | p|XGetKeyboardMapping.3 |I |xorg@lists.freedesktop.org | |
| 781 | p|XGetModifierMapping.3 |I |xorg@lists.freedesktop.org | |
| 782 | p|XGetMotionEvents.3 |I |xorg@lists.freedesktop.org | |
| 783 | p|XGetRGBColormaps.3 |I |xorg@lists.freedesktop.org | |
| 784 | p|XGetVisualInfo.3 |I |xorg@lists.freedesktop.org | |
| 785 | p|XGetWMHints.3 |I |xorg@lists.freedesktop.org | |
| 786 | p|XGetWMNormalHints.3 |I |xorg@lists.freedesktop.org | |
| 787 | p|XGetWMSizeHints.3 |I |xorg@lists.freedesktop.org | |
| 788 | p|XGetWindowAttributes.3|I |xorg@lists.freedesktop.org | |
| 789 | n|XGetXCBConnection.3,XSetEventQueueOwner.3 |X |xcb@lists.freedesktop.org | |
| 790 | p|XGraphicsExposeEvent.3|I |xorg@lists.freedesktop.org | |
| 791 | p|XGravityEvent.3 |I |xorg@lists.freedesktop.org | |
| 792 | p|XHostAddress.3 |I |xorg@lists.freedesktop.org | |
| 793 | p|XIconSize.3 |I |xorg@lists.freedesktop.org | |
| 794 | p|XInsertModifiermapEntry.3 |I |xorg@lists.freedesktop.org | |
| 795 | p|XKeyEvent.3 |I |xorg@lists.freedesktop.org | |
| 796 | p|XKeyboardControl.3 |I |xorg@lists.freedesktop.org | |
| 797 | p|XKeymapEvent.3 |I |xorg@lists.freedesktop.org | |
| 798 | p|XListHosts.3 |I |xorg@lists.freedesktop.org | |
| 799 | p|XListPixmapFormats.3 |I |xorg@lists.freedesktop.org | |
| 800 | p|XMapEvent.3 |I |xorg@lists.freedesktop.org | |
| 801 | p|XMapRequestEvent.3 |I |xorg@lists.freedesktop.org | |
| 802 | p|XMappingEvent.3 |I |xorg@lists.freedesktop.org | |
| 803 | p|XMatchVisualInfo.3 |I |xorg@lists.freedesktop.org | |
| 804 | p|XModifierKeymap.3 |I |xorg@lists.freedesktop.org | |
| 805 | p|XMotionEvent.3 |I |xorg@lists.freedesktop.org | |
| 806 | p|XMoveResizeWindow.3 |I |xorg@lists.freedesktop.org | |
| 807 | p|XMoveWindow.3 |I |xorg@lists.freedesktop.org | |
| 808 | p|XNewModifiermap.3 |I |xorg@lists.freedesktop.org | |
| 809 | p|XNoExposeEvent.3 |I |xorg@lists.freedesktop.org | |
| 810 | p|XPixmapFormatValues.3 |I |xorg@lists.freedesktop.org | |
| 811 | p|XPoint.3 |I |xorg@lists.freedesktop.org | |
| 812 | p|XPropertyEvent.3 |I |xorg@lists.freedesktop.org | |
| 813 | p|XQueryKeymap.3 |I |xorg@lists.freedesktop.org | |
| 814 | p|XRectangle.3 |I |xorg@lists.freedesktop.org | |
| 815 | p|XRemoveHost.3 |I |xorg@lists.freedesktop.org | |
| 816 | p|XRemoveHosts.3 |I |xorg@lists.freedesktop.org | |
| 817 | p|XReparentEvent.3 |I |xorg@lists.freedesktop.org | |
| 818 | p|XResizeRequestEvent.3 |I |xorg@lists.freedesktop.org | |
| 819 | p|XResizeWindow.3 |I |xorg@lists.freedesktop.org | |
| 820 | p|XSegment.3 |I |xorg@lists.freedesktop.org | |
| 821 | p|XSelectionClearEvent.3|I |xorg@lists.freedesktop.org | |
| 822 | p|XSelectionEvent.3 |I |xorg@lists.freedesktop.org | |
| 823 | p|XSelectionRequestEvent.3 |I |xorg@lists.freedesktop.org | |
| 824 | p|XSendEvent.3 |I |xorg@lists.freedesktop.org | |
| 825 | p|XSetAccessControl.3 |I |xorg@lists.freedesktop.org | |
| 826 | p|XSetClassHint.3 |I |xorg@lists.freedesktop.org | |
| 827 | p|XSetIconSizes.3 |I |xorg@lists.freedesktop.org | |
| 828 | p|XSetModifierMapping.3 |I |xorg@lists.freedesktop.org | |
| 829 | p|XSetRGBColormaps.3 |I |xorg@lists.freedesktop.org | |
| 830 | p|XSetWMHints.3 |I |xorg@lists.freedesktop.org | |
| 831 | p|XSetWMNormalHints.3 |I |xorg@lists.freedesktop.org | |
| 832 | p|XSetWMSizeHints.3 |I |xorg@lists.freedesktop.org | |
| 833 | p|XSetWindowAttributes.3 |I |xorg@lists.freedesktop.org | |
| 834 | p|XSetWindowBorderWidth.3 |I |xorg@lists.freedesktop.org | |
| 835 | p|XShape.3 |Iu |xorg@lists.freedesktop.org | |
| 836 | p|XShapeCombineMask.3 |Iu |xorg@lists.freedesktop.org | |
| 837 | p|XShapeCombineRectangles.3 |Iu |xorg@lists.freedesktop.org | |
| 838 | p|XShapeCombineRegion.3 |Iu |xorg@lists.freedesktop.org | |
| 839 | p|XShapeCombineShape.3 |Iu |xorg@lists.freedesktop.org | |
| 840 | p|XShapeGetRectangles.3 |Iu |xorg@lists.freedesktop.org | |
| 841 | p|XShapeInputSelected.3 |Iu |xorg@lists.freedesktop.org | |
| 842 | p|XShapeOffsetShape.3 |Iu |xorg@lists.freedesktop.org | |
| 843 | p|XShapeQueryExtension.3|Iu |xorg@lists.freedesktop.org | |
| 844 | p|XShapeQueryExtents.3 |Iu |xorg@lists.freedesktop.org | |
| 845 | p|XShapeQueryVersion.3 |Iu |xorg@lists.freedesktop.org | |
| 846 | p|XShapeSelectInput.3 |Iu |xorg@lists.freedesktop.org | |
| 847 | p|XStandardColormap.3 |I |xorg@lists.freedesktop.org | |
| 848 | p|XStringListToTextProperty.3 |I |xorg@lists.freedesktop.org | |
| 849 | p|XTextItem.3 |I |xorg@lists.freedesktop.org | |
| 850 | p|XTextItem16.3 |I |xorg@lists.freedesktop.org | |
| 851 | p|XTextProperty.3 |I |xorg@lists.freedesktop.org | |
| 852 | p|XTextPropertyToStringList.3 |I |xorg@lists.freedesktop.org | |
| 853 | p|XTimeCoord.3 |I |xorg@lists.freedesktop.org | |
| 854 | p|XUnmapEvent.3 |I |xorg@lists.freedesktop.org | |
| 855 | p|XVisibilityEvent.3 |I |xorg@lists.freedesktop.org | |
| 856 | p|XVisualIDFromVisual.3 |I |xorg@lists.freedesktop.org | |
| 857 | p|XVisualInfo.3 |I |xorg@lists.freedesktop.org | |
| 858 | p|XWMHints.3 |I |xorg@lists.freedesktop.org | |
| 859 | p|XWindowAttributes.3 |I |xorg@lists.freedesktop.org | |
| 860 | p|XWindowChanges.3 |I |xorg@lists.freedesktop.org | |
| 861 | p|Xau.3 |I |xorg@lists.freedesktop.org | |
| 862 | p|XkbGetNamedGeometry.3 |I |xorg@lists.freedesktop.org | |
| 863 | p|XkbSASetGroup.3 |I |xorg@lists.freedesktop.org | |
| 864 | p|XkbSetDetectableAutoRepeat.3 |I |xorg@lists.freedesktop.org | |
| 865 | p|XkbSetDeviceButtonActions.3 |I |xorg@lists.freedesktop.org | |
| 866 | p|XmbDrawText.3 |I |xorg@lists.freedesktop.org | |
| 867 | p|XmbTextListToTextProperty.3 |I |xorg@lists.freedesktop.org | |
| 868 | p|XmbTextPropertyToTextList.3 |I |xorg@lists.freedesktop.org | |
| 869 | p|Xmbuf.3 |I |xorg@lists.freedesktop.org | |
| 870 | p|XmbufChangeBufferAttributes.3 |I |xorg@lists.freedesktop.org | |
| 871 | p|XmbufChangeWindowAttributes.3 |I |xorg@lists.freedesktop.org | |
| 872 | p|XmbufCreateBuffers.3 |I |xorg@lists.freedesktop.org | |
| 873 | p|XmbufCreateStereoWindow.3 |I |xorg@lists.freedesktop.org | |
| 874 | p|XmbufDestroyBuffers.3 |I |xorg@lists.freedesktop.org | |
| 875 | p|XmbufDisplayBuffers.3 |I |xorg@lists.freedesktop.org | |
| 876 | p|XmbufGetBufferAttributes.3 |I |xorg@lists.freedesktop.org | |
| 877 | p|XmbufGetScreenInfo.3 |I |xorg@lists.freedesktop.org | |
| 878 | p|XmbufGetVersion.3 |I |xorg@lists.freedesktop.org | |
| 879 | p|XmbufGetWindowAttributes.3 |I |xorg@lists.freedesktop.org | |
| 880 | p|XmbufQueryExtension.3 |I |xorg@lists.freedesktop.org | |
| 881 | p|XrmEnumerateDatabase.3 |I |xorg@lists.freedesktop.org | |
| 882 | p|XrmInitialize.3 |I |xorg@lists.freedesktop.org | |
| 883 | p|XrmOptionDescRec.3 |I |xorg@lists.freedesktop.org | |
| 884 | p|XrmOptionKind.3 |I |xorg@lists.freedesktop.org | |
| 885 | p|XrmParseCommand.3 |I |xorg@lists.freedesktop.org | |
| 886 | p|XrmValue.3 |I |xorg@lists.freedesktop.org | |
| 887 | p|XtPopdown.3,XtCallbackPopdown.3,MenuPopdown.3 |I |xorg@lists.freedesktop.org | |
| 888 | p|XtSetArg.3,XtMergeArgLists.3 |I |xorg@lists.freedesktop.org | |
| 889 | p|Xutf8DrawText.3 |I |xorg@lists.freedesktop.org | |
| 890 | p|Xutf8TextListToTextProperty.3 |I |xorg@lists.freedesktop.org | |
| 891 | p|Xutf8TextPropertyToTextList.3 |I |xorg@lists.freedesktop.org | |
| 892 | p|XwcDrawText.3 |I |xorg@lists.freedesktop.org | |
| 893 | p|XwcFreeStringList.3 |I |xorg@lists.freedesktop.org | |
| 894 | p|XwcTextListToTextProperty.3 |I |xorg@lists.freedesktop.org | |
| 895 | p|XwcTextPropertyToTextList.3 |I |xorg@lists.freedesktop.org | |
| 896 | y|XrmUniqueQuark.3x | |xorg@lists.freedesktop.org | |
| 897 | y|Xnest.1x | |xorg@lists.freedesktop.org | |
| 898 | y|x11perf.1x,x11perfcomp.1x| |xorg@lists.freedesktop.org | |
| 899 | p|xcalc.1 |Io |xorg@lists.freedesktop.org | |
| 900 | p|xclipboard.1 |I |xorg@lists.freedesktop.org | |
| 901 | p|xclock.1 |I |xorg@lists.freedesktop.org | |
| 902 | p|xconsole.1 |I |xorg@lists.freedesktop.org | |
| 903 | nA|xdr.3 |I |mtk-manpages@gmx.net | |
| 904 | nA|xdr_accepted_reply.3 |I |mtk-manpages@gmx.net | |
| 905 | nA|xdr_array.3 |I |mtk-manpages@gmx.net | |
| 906 | nA|xdr_authunix_parms.3 |I |mtk-manpages@gmx.net | |
| 907 | nA|xdr_bool.3 |I |mtk-manpages@gmx.net | |
| 908 | nA|xdr_bytes.3 |I |mtk-manpages@gmx.net | |
| 909 | nA|xdr_callhdr.3 |I |mtk-manpages@gmx.net | |
| 910 | nA|xdr_callmsg.3 |I |mtk-manpages@gmx.net | |
| 911 | nA|xdr_char.3 |I |mtk-manpages@gmx.net | |
| 912 | nA|xdr_destroy.3 |I |mtk-manpages@gmx.net | |
| 913 | nA|xdr_double.3 |I |mtk-manpages@gmx.net | |
| 914 | nA|xdr_enum.3 |I |mtk-manpages@gmx.net | |
| 915 | nA|xdr_float.3 |I |mtk-manpages@gmx.net | |
| 916 | nA|xdr_free.3 |I |mtk-manpages@gmx.net | |
| 917 | nA|xdr_getpos.3 |I |mtk-manpages@gmx.net | |
| 918 | nA|xdr_inline.3 |I |mtk-manpages@gmx.net | |
| 919 | nA|xdr_int.3 |I |mtk-manpages@gmx.net | |
| 920 | nA|xdr_long.3 |I |mtk-manpages@gmx.net | |
| 921 | nA|xdr_opaque.3 |I |mtk-manpages@gmx.net | |
| 922 | nA|xdr_opaque_auth.3 |I |mtk-manpages@gmx.net | |
| 923 | nA|xdr_pmap.3 |I |mtk-manpages@gmx.net | |
| 924 | nA|xdr_pmaplist.3 |I |mtk-manpages@gmx.net | |
| 925 | nA|xdr_pointer.3 |I |mtk-manpages@gmx.net | |
| 926 | nA|xdr_reference.3 |I |mtk-manpages@gmx.net | |
| 927 | nA|xdr_rejected_reply.3 |I |mtk-manpages@gmx.net | |
| 928 | nA|xdr_replymsg.3 |I |mtk-manpages@gmx.net | |
| 929 | nA|xdr_setpos.3 |I |mtk-manpages@gmx.net | |
| 930 | nA|xdr_short.3 |I |mtk-manpages@gmx.net | |
| 931 | nA|xdr_string.3 |I |mtk-manpages@gmx.net | |
| 932 | nA|xdr_u_char.3 |I |mtk-manpages@gmx.net | |
| 933 | nA|xdr_u_int.3 |I |mtk-manpages@gmx.net | |
| 934 | nA|xdr_u_long.3 |I |mtk-manpages@gmx.net | |
| 935 | nA|xdr_u_short.3 |I |mtk-manpages@gmx.net | |
| 936 | nA|xdr_union.3 |I |mtk-manpages@gmx.net | |
| 937 | nA|xdr_vector.3 |I |mtk-manpages@gmx.net | |
| 938 | nA|xdr_void.3 |I |mtk-manpages@gmx.net | |
| 939 | nA|xdr_wrapstring.3 |I |mtk-manpages@gmx.net | |
| 940 | nA|xdrmem_create.3 |I |mtk-manpages@gmx.net | |
| 941 | nA|xdrrec_create.3 |I |mtk-manpages@gmx.net | |
| 942 | nA|xdrrec_endofrecord.3 |I |mtk-manpages@gmx.net | |
| 943 | nA|xdrrec_eof.3 |I |mtk-manpages@gmx.net | |
| 944 | nA|xdrrec_skiprecord.3 |I |mtk-manpages@gmx.net | |
| 945 | nA|xdrstdio_create.3 |I |mtk-manpages@gmx.net | |
| 946 | p|xedit.1 |Io |xorg@lists.freedesktop.org | |
| 947 | 1n|xfd.1 |o |xorg@lists.freedesktop.org | |
| 948 | y|xfontsel.1x,xlsfonts.1x | |xorg@lists.freedesktop.org | |
| 949 | 1n|xkbevd.1 |J |xorg@lists.freedesktop.org | |
| 950 | p|xload.1 |I |xorg@lists.freedesktop.org | |
| 951 | p|xlogo.1 |I |xorg@lists.freedesktop.org | |
| 952 | p|xman.1 |Io |xorg@lists.freedesktop.org | |
| 953 | y|Xmark.1x | |xorg@lists.freedesktop.org | |
| 954 | y|xminicom.1 | |miquels@cistron.nl | |
| 955 | y|xml_pp.1 | |Michel Rodriguez <mirod@xmltwig.com> | |
| 956 | y|xml_spellcheck.1 | |Michel Rodriguez <mirod@xmltwig.com> | |
| 957 | gA|xmlto.1 |I |tim@cyberelk.net | |
| 958 | 1p|xorg.conf.5,xorg.conf.d.5|Lu |xorg@lists.freedesktop.org | |
| 959 | nA|xprt_register.3 |I |mtk-manpages@gmx.net | |
| 960 | nA|xprt_unregister.3 |I |mtk-manpages@gmx.net | |
| 961 | y|xrdb.1x | |xorg@lists.freedesktop.org | |
| 962 | y|xrandr.1 | |xorg@lists.freedesktop.org | |
| 963 | p|Xsecurity.7 |W |xorg@lists.freedesktop.org | |
| 964 | n|Xserver.1 |J |xorg@lists.freedesktop.org | |
| 965 | p|XStandards.7 |H |xorg@lists.freedesktop.org | |
| 966 | 1n|xterm.1 |LI |xorg@lists.freedesktop.org | |
| 967 | y|XQueryExtension.3x | |xorg@lists.freedesktop.org | |
| 968 | y|xscreensaver-text.1 | |jwz@jwz.org | |
| 969 | y|xset.1x | |xorg@lists.freedesktop.org | |
| 970 | y|xsltproc.1 | |xslt@gnome.org | |
| 971 | y|xtotroff.1 | |bug-groff@gnu.org | |
| 972 | nA|zic.8 |I |patches@eglibc.org | |
| 973 | pA|zip.1 |J |Info-ZIP-Dev@goatley.com | |
| 974 | nA|zipinfo.1 |* |newt@pobox.com | |
| 975 | pA|zipcloak.1,zipnote.1,zipsplit.1|I |Info-ZIP-Dev@goatley.com | |
| 976 | nA|zlib.3 |C |zlib@gzip.org |
| 10 | 10 | table markup, PIC into SVG, and EQN into MathML (relying on pic2svg |
| 11 | 11 | and GNU eqn for the last two). |
| 12 | 12 | |
| 13 | Test loads are included in the distribution. The code has been tested | |
| 14 | in about the most brutal possible way; it has been run against every | |
| 15 | single man page in all sections of a full Fedora Core installation. | |
| 16 | It lifts over 95% of these pages without requiring any hand-hacking. | |
| 13 | Test loads are included in the distribution; do "make check" to run | |
| 14 | the regression tests. The code has been live tested in about the most | |
| 15 | brutal possible way; it has been run against every single man page in | |
| 16 | all sections of a desktop Ubuntu installation. It lifts over 93% of | |
| 17 | these pages without requiring any hand-hacking. | |
| 17 | 18 | |
| 18 | 19 | There is a detailed change log in the NEWS file. |
| 2 | 2 | * Docbook 5 translation is incomplete; inclusions won't work, |
| 3 | 3 | entities are untested. |
| 4 | 4 | |
| 5 | * I haven't come up with a reliable way to distinguish command synopses | |
| 6 | from stuff that should be treated as plain text. This has a couple | |
| 7 | of consequences: | |
| 5 | See the PATCHES file for other, more minor problems mainly due to bad markup. | |
| 8 | 6 | |
| 9 | 1. doclifter doesn't recognize command synopses in displays, only in | |
| 10 | Synopsis sections. | |
| 11 | ||
| 12 | 2. When command synopses have a trailing text section (explanatory | |
| 13 | paragraph) doclifter doesn't always detect that and cope well. | |
| 14 | ||
| 15 | * .Xo/.Xc Berkeley macro needs work. See elf.5. | |
| 16 | ||
| 17 | * Look at lwres_getaddrinfo.3 -- good type case for resuming function parse | |
| 18 | after text. sox(1) and soxmix(1) show the same problem with command syntax. | |
| 19 | ||
| 20 | * CA.pl.1ssl -- CA.pl is not properly tagged as a command. | |
| 21 | ||
| 22 | See the BUGS file for other, more minor problems mainly due to bad markup. | |
| 23 |
| 0 | 0 | #!/usr/bin/env python |
| 1 | """ | |
| 1 | r""" | |
| 2 | 2 | doclifter: translate man/mdoc/ms/me/mm sources to DocBook. |
| 3 | 3 | |
| 4 | 4 | By Eric S. Raymond, copyright 2002, 2006, 2007. |
| 30 | 30 | The interpreter stack always includes TroffInterpreter at the bottom. This |
| 31 | 31 | request interpreter handles the small set of troff requests that we translate, |
| 32 | 32 | including .so, .nf, .fi, .if, etc. It also handles macro and string expansion. |
| 33 | ||
| 34 | Note that commands are looked up in reverse order of class activation, e.g | |
| 35 | most rescent extension set first. This means that definitions in a later | |
| 36 | class override definitions in earlier ones. | |
| 33 | 37 | |
| 34 | 38 | Each request interpreter is a class that provides methods and members to be |
| 35 | 39 | used by the framework. Here they are: |
| 117 | 121 | |
| 118 | 122 | Warning: much of this code is grubby. Alas, the grubbiness is |
| 119 | 123 | intrinsic, because the troff request language is grubby. |
| 120 | ||
| 121 | $Id$ | |
| 122 | 124 | """ |
| 123 | 125 | import sys, os, glob, re, string, exceptions, tempfile, time, pprint, commands |
| 126 | ||
| 127 | version = "2.11" | |
| 124 | 128 | |
| 125 | 129 | # This is a speed hack recommended by Armin Rigo. It cuts runtime by about 33% |
| 126 | 130 | # and makes it possible for psyco 1.2 to reduce runtime another 33%. |
| 127 | 131 | re_cache = {} |
| 128 | def re_compile(str): | |
| 132 | def re_compile(st, flags=0): | |
| 129 | 133 | try: |
| 130 | return re_cache[str] | |
| 134 | return re_cache[st] | |
| 131 | 135 | except KeyError: |
| 132 | r = re_cache[str] = re.compile(str) | |
| 136 | r = re_cache[st] = re.compile(st, flags) | |
| 133 | 137 | return r |
| 134 | 138 | |
| 135 | 139 | # In order: Dutch, English/German, French, Italian, Norwegian/Danish, Polish, |
| 137 | 141 | name_synonyms = re.compile("^(naam|name|nom|nome|navn|nazwa|nombre|namn)$", re.I) |
| 138 | 142 | |
| 139 | 143 | # How to detect synopses |
| 140 | synopsis_label = re.compile("SYNOPSIS", re.I) | |
| 141 | synopsis_header = re.compile(r'\.S[Hh]\s*"?(?:' + synopsis_label.pattern + ")", re.I) | |
| 144 | synopsis_label = re.compile("SYNOPSIS$", re.I) | |
| 145 | synopsis_header = re.compile(r'\.S[Hh]\s*"?(?:SYNOPSIS)', re.I) | |
| 142 | 146 | |
| 143 | 147 | # Qt part descriptions. It's OK to see these in function synopses, we just |
| 144 | 148 | # turn them into an info section. |
| 172 | 176 | # Match an RFC822 email address, possibly with surrounding <>. |
| 173 | 177 | # This is the right thing because the XSL stylesheets surround |
| 174 | 178 | # <email> content with <> on output. |
| 175 | email_re = re.compile("\b(?:<)?(?P<email>[-\w_.]+@[-\w_.]+)(?:>)?\b") | |
| 179 | email_re = re.compile(r"\b(?:<)?(?P<email>[-\w_.]+@[-\w_.]+)(?:>)?\b") | |
| 176 | 180 | |
| 177 | 181 | # Match an URL. This pattern is carefully constructed not to eat |
| 178 | 182 | # a following period if (as is often the case) it occurs at the |
| 179 | 183 | # end of a sentence. |
| 180 | url_re=re.compile(r"(?P<url>\b(http|ftp|telnet|mailto)://[-_%\w/.~]+[-_%\w/])") | |
| 184 | url_re=re.compile(r"(?P<url>\b(http|ftp|telnet|mailto)://[-_%\w/&;.~]+[-_%\w/&;])") | |
| 181 | 185 | |
| 182 | 186 | # Match a xmlns URL in the top level tag, so that the url_re does not try to ulink-ize it. |
| 183 | xmlns_re=re.compile("\w xmlns='http://docbook.org/ns/docbook'") | |
| 187 | xmlns_re=re.compile(r"\w xmlns='http://docbook.org/ns/docbook'") | |
| 184 | 188 | |
| 185 | 189 | # Match a troff highlight |
| 186 | 190 | troff_highlight = re.compile(r"(\\[fF]\([A-Z][A-Z])|(\\f\[[A-Z]*\])|(\\[fF][A-Z0-9])|(\\F\[\])") |
| 194 | 198 | id_re = re.compile("^[_a-zA-Z][_a-zA-Z0-9]*$") |
| 195 | 199 | |
| 196 | 200 | # List how troff specials that can appear as list tags map into |
| 197 | # DocBook mark types. According to Norm Walsh's DSSL and XSL stylesheets, | |
| 198 | # both toolchains have two styles available; bullet and box. | |
| 201 | # DocBook mark types. According to Norm Walsh's DSSL and XSL | |
| 202 | # stylesheets, both toolchains have two styles available; bullet and | |
| 203 | # box. An older version of the DocBook documentation said that in | |
| 204 | # itemizedlists the attributes can be the three names HTML supports: "disc", | |
| 205 | # "circle", and "square", with "bullet" as a synonym for "disc" and | |
| 206 | # "box" as a synonym for "square". We map dash to box here for consistency | |
| 207 | # with the -dash/-bullet distinction in mdoc, where -dash can only | |
| 208 | # reasonably be mapped to box rather than disc. | |
| 199 | 209 | ip_tag_mapping = { |
| 200 | "\(bu":"bullet", | |
| 201 | "\(sq":"box", | |
| 210 | r"\(bu":"bullet", | |
| 211 | r"\(sq":"box", | |
| 212 | "*" : "bullet", | |
| 213 | "-" : "box", | |
| 202 | 214 | } |
| 203 | 215 | |
| 204 | 216 | # Add this to the V4 preamble when we have MathML elements |
| 208 | 220 | <!ENTITY % inlineequation.content |
| 209 | 221 | "(alt?, (graphic+|inlinemediaobject+|mml:math))"> |
| 210 | 222 | <!ENTITY % mathml PUBLIC "-//W3C//DTD MathML 2.0//EN" |
| 211 | "http://www.w3.org/TR/MathML2/dtd/mathml2.dtd"> | |
| 223 | "http://www.w3.org/Math/DTD/mathml2/mathml2.dtd"> | |
| 212 | 224 | %mathml; |
| 213 | 225 | ''' |
| 214 | 226 | |
| 241 | 253 | bsd_verbosity = 'b' # BSD macroexpansion |
| 242 | 254 | tokenizer_verbosity = 'x' # Tokenizer verbosity |
| 243 | 255 | timing_verbosity = 't' # Execution profiling |
| 244 | ||
| 245 | def deemphasize(str): | |
| 256 | supersub_verbosity = 'u' # Super/subscript recognition velocity. | |
| 257 | ||
| 258 | def deemphasize(st): | |
| 246 | 259 | "Throw out highlighting info from a string." |
| 247 | return troff_highlight.sub("", str) | |
| 260 | return troff_highlight.sub("", st) | |
| 248 | 261 | |
| 249 | 262 | def is_command(line): |
| 250 | 263 | # This works around a common bug -- string-enclosing ' at the left margin |
| 301 | 314 | return istr[:take+1] |
| 302 | 315 | |
| 303 | 316 | def make_comment(istr): |
| 304 | istr = istr.replace(r'.\"', "").replace(r'.\\"', "").replace(r'\(co', "(C)") | |
| 317 | if istr.startswith("."): | |
| 318 | istr = istr[1:] | |
| 319 | istr = istr.replace(r'\"', "").replace(r'\\"', "").replace(r'\(co', "(C)") | |
| 320 | istr = istr.strip() | |
| 305 | 321 | return "<!-- " + istr.replace("-", r"\\-") + " -->" |
| 306 | 322 | |
| 307 | 323 | def lineparse(line): |
| 327 | 343 | else: |
| 328 | 344 | tokens[-1] += c |
| 329 | 345 | elif state == 'tokencont': # accumulating a token |
| 346 | if c in (" ", "\t", "\n"): | |
| 347 | tokens[-1] = tokens[-1][:-1] | |
| 330 | 348 | tokens[-1] += c |
| 331 | 349 | state = 'token' |
| 332 | 350 | elif state == 'ws': # in whitespace |
| 357 | 375 | elif state == 'leader?': # possible comment leader |
| 358 | 376 | if c == '"': |
| 359 | 377 | break |
| 378 | elif c in (" ", "\t", "\n"): | |
| 379 | tokens.append(c) | |
| 380 | state = 'token' | |
| 360 | 381 | else: |
| 361 | 382 | tokens.append("\\" + c) |
| 362 | 383 | state = 'token' |
| 391 | 412 | "Represent all the semantic information gathered during a run." |
| 392 | 413 | def __init__(self): |
| 393 | 414 | self.dictionary = {} |
| 394 | def post(self, token, type): | |
| 415 | def post(self, token, ptype): | |
| 395 | 416 | "Post an association of a string with a semantic markup type." |
| 396 | #stdout.write("Markup %s as %s\n" % (token, type)) | |
| 397 | self.dictionary[token] = type | |
| 417 | #stdout.write("Markup %s as %s\n" % (token, ptype)) | |
| 418 | self.dictionary[token] = ptype | |
| 398 | 419 | def get(self, token): |
| 399 | 420 | return self.dictionary.get(token) |
| 400 | 421 | def apply(self, text): |
| 401 | 422 | "Apply all known hints to lift tokens in a text string." |
| 402 | 423 | # stderr.write("Marked tokens:" + `self.dictionary` + "\n") |
| 403 | 424 | for (token, tag) in self.dictionary.items(): |
| 404 | with_hi = "<emphasis\s+remap='[A-Z]+'>(%s)</emphasis>" % token | |
| 425 | with_hi = r"<emphasis\s+remap='[A-Z]+'>(%s)</emphasis>" % token | |
| 405 | 426 | #stdout.write("marking %s as %s via %s\n" % (token, tag, with_hi)) |
| 406 | 427 | try: |
| 407 | 428 | ender = tag.split()[0] # discard attributes |
| 408 | 429 | text = re_compile(with_hi).sub(r"<%s>\1</%s>"%(tag,ender),text) |
| 409 | 430 | text = re_compile(r"\b("+token+")\b").sub(r"<%s>\1</%s>" % (tag, ender), text) |
| 410 | pass | |
| 411 | 431 | except re.sre_compile.error: |
| 412 | 432 | pass |
| 413 | 433 | return text |
| 414 | def read(self, input): | |
| 434 | def read(self, rinput): | |
| 415 | 435 | "Read in a hints string or file as dumped by __str__" |
| 416 | if hasattr(input, "read"): | |
| 417 | fp = open(input) | |
| 436 | if hasattr(rinput, "read"): | |
| 437 | fp = open(rinput) | |
| 418 | 438 | data = fp.readlines() |
| 419 | 439 | fp.close() |
| 420 | 440 | else: |
| 421 | data = input.split('\n') | |
| 441 | data = rinput.split('\n') | |
| 422 | 442 | for line in data: |
| 423 | 443 | if line.startswith('.\\" | '): |
| 424 | 444 | # Someday we'll have more declarations |
| 425 | (mark, token, as_word, markup) = line[5:].split() | |
| 426 | if mark != "mark" or as_word != "as": | |
| 445 | try: | |
| 446 | (mark, token, as_word, markup) = line[5:].split() | |
| 447 | if mark != "mark" or as_word != "as": | |
| 448 | continue | |
| 449 | self.post(token, markup) | |
| 450 | except ValueError: | |
| 427 | 451 | continue |
| 428 | self.post(token, markup) | |
| 429 | 452 | def __repr__(self): |
| 430 | 453 | "Dump a representation of hint info." |
| 431 | 454 | out = '.\\" Begin doclifter hints.\n' |
| 436 | 459 | |
| 437 | 460 | class Frame: |
| 438 | 461 | "Frame state for the list-markup stack." |
| 439 | def __init__(self, command, type, explicit=False): | |
| 462 | def __init__(self, command, ftype): | |
| 440 | 463 | self.command = command |
| 441 | self.type = type | |
| 442 | self.explicit = explicit | |
| 464 | self.type = ftype | |
| 443 | 465 | self.count = 0 |
| 444 | 466 | def __repr__(self): |
| 445 | 467 | return "<Frame: " + `self.__dict__` + ">" |
| 450 | 472 | # The second element is a regexp to match to the tag content. |
| 451 | 473 | # If the regexp matches, the bracketing emphasis tags are replaced |
| 452 | 474 | # with the semantic tag in the third column. |
| 453 | lift_highlights = map(lambda x: (re_compile("<emphasis\s+remap='%s'>(%s)</emphasis>" % (x[0], x[1])), x[2]), ( | |
| 475 | lift_highlights = map(lambda x: (re_compile(r"<emphasis\s+remap='%s'>(%s)</emphasis>" % (x[0], x[1])), x[2]), ( | |
| 454 | 476 | ("SM", r"[A-Z.]*", "acronym"), # Historical -- SM is rare |
| 455 | 477 | ("SM", r"[A-Z]+_[A-Z_]+", "envar"), # In bison.1, cvs.1 |
| 456 | 478 | ("[BI]",r"-[^<]+", "option"), # likely command option man(7) |
| 570 | 592 | (r"T\h'-.1667m'\v'.224m'E\v'-.224m'\h'-.125m'X", r"TeX"), # geqn.1 |
| 571 | 593 | (r"\h'-\w' 'u' ", r""), # procmail.1 |
| 572 | 594 | (r"\l'\n(.lu'", ".DOCLIFTER-HR"), # spax.1 |
| 595 | (r"L\h'-0.36'\v'-0.15'\s-2A\s+2\v'0.15'\h'-0.15'T\h'-0.1667'\v'0.2'E\v'-0.2'\h'-0.125'X", "LATEX"), # ctanify.1 | |
| 596 | (r"T\h'-0.1667'\v'0.2'E\v'-0.2'\h'-0.125'X", "TeX"), # ctanify.1 | |
| 597 | # Ugh. These string definitions from inifile.1 and | |
| 598 | # elsewhere aren't used in the nroff mode we're emulating. | |
| 599 | # They have to be removed early because of the way they | |
| 600 | # interact with other transformations. | |
| 601 | (r"\*(T<", ""), | |
| 602 | (r"\*(T>", ""), | |
| 573 | 603 | ) |
| 574 | 604 | |
| 575 | 605 | # In each tuple, the first element is an emphasis remap attribute. |
| 606 | 636 | ("rf", "⎦"), # Right square bracket lower corner |
| 607 | 637 | ("rk", "⎬"), # Right curly bracket middle piece |
| 608 | 638 | ("rt", "⎫"), # Right curly bracket upper hook |
| 609 | # These are from groff | |
| 639 | # These are characters with diacriticals from groff | |
| 610 | 640 | ("yogh", "ȝ"), # Small letter yogh |
| 611 | 641 | ("ohook", "ơ"), # Small letter o with hook or ogonek |
| 612 | ("udot", "Ń"), # Combining underdot. | |
| 642 | ("udot", "̣"), # Combining underdot. | |
| 643 | ("braceex", "⎪"), | |
| 644 | # These are groff pile brackets | |
| 645 | ("bracketlefttp", "⎡"), | |
| 646 | ("bracketleftbt", "㊣"), | |
| 647 | ("bracketleftex", "⎢"), | |
| 648 | ("bracketrighttp", "⎤"), | |
| 649 | ("bracketrightbt", "㊦"), | |
| 650 | ("bracketrightex", "⎥"), | |
| 651 | ("braceleftex", "⎪"), | |
| 652 | ("bracerightmid", "⎬"), | |
| 653 | ("bracerightex", "⎪"), | |
| 654 | ("parenlefttp", "⎛"), | |
| 655 | ("parenleftbt", "⎝"), | |
| 656 | ("parenleftex", "⎜"), | |
| 657 | ("parenrighttp", "⎞"), | |
| 658 | ("parenrightbt", "⎠"), | |
| 659 | ("parenrightex", "⎟"), | |
| 660 | # These are groff radical extentions. What we're doing here | |
| 661 | # is just mapping them to the Unicode macron. This is not | |
| 662 | # going to be great typesetting.... | |
| 663 | ("radicalex", "‾"), | |
| 664 | ("sqrtex", "‾"), | |
| 665 | # jnodot exists in Unicode, but the DocBook stylesheets don't know it. | |
| 666 | # Someday we should be able to remove this. | |
| 667 | ("jnodot", "í"), | |
| 668 | # Bug:   should be included by the v4 DocBook DTD, | |
| 669 | # but apparently it isn't. | |
| 670 | ("numsp", " "), | |
| 613 | 671 | ) |
| 614 | 672 | |
| 615 | 673 | def __init__(self, verbose="", |
| 625 | 683 | self.includepath = includepath |
| 626 | 684 | self.encoding = encoding |
| 627 | 685 | self.docbook5 = docbook5 |
| 628 | self.ignore_set = {} | |
| 629 | self.listbreak_set = {} | |
| 630 | self.complain_set = {} | |
| 686 | self.ignore_set = set([]) | |
| 687 | self.listbreak_set = set([]) | |
| 688 | self.complain_set = set([]) | |
| 631 | 689 | self.outsubst = [] |
| 632 | 690 | self.sectname = None |
| 633 | 691 | self.nonblanks = 0 |
| 647 | 705 | self.stash_id = None |
| 648 | 706 | self.displaystack = [] |
| 649 | 707 | self.pic_seen = self.eqn_seen = False |
| 708 | self.localentities = [] | |
| 709 | self.pic_processed = False | |
| 710 | self.lines = None | |
| 711 | self.eqnsub = None | |
| 712 | self.file = None | |
| 713 | self.pushdown = [] # Stack of input sources | |
| 714 | self.physlines = 0 | |
| 715 | self.highlight = "R" | |
| 716 | self.oldhighlight = "R" | |
| 717 | self.in_preamble = True | |
| 718 | self.eqn_processed = False | |
| 719 | self.body_start = 0 | |
| 720 | self.lineno = 0 | |
| 721 | self.need_para = False | |
| 722 | self.sectiondepth = 0 | |
| 723 | self.output = [] | |
| 724 | self.inclusions = [] | |
| 725 | self.multiarg = False | |
| 726 | self.troff = None | |
| 727 | self.interpreters = [] | |
| 728 | self.diversion = None | |
| 729 | self.name = None | |
| 730 | self.localhints = None | |
| 731 | self.basetime = None | |
| 732 | self.starttime = None | |
| 650 | 733 | |
| 651 | 734 | def body_section(self): |
| 652 | 735 | "Are we in a section that corresponds to a real refentry section?" |
| 769 | 852 | else: |
| 770 | 853 | break |
| 771 | 854 | # Interpolate numeric registers |
| 772 | for key in self.troff.registers: | |
| 773 | value = self.troff.eval_register(key) | |
| 774 | line = line.replace(r"\n["+key+"]", value) | |
| 775 | if len(key) == 1: | |
| 776 | line = line.replace(r"\n"+key, value) | |
| 777 | elif len(key) == 2: | |
| 778 | line = line.replace(r"\n("+key, value) | |
| 855 | while '\\n' in line: | |
| 856 | before = line[:line.find('\\n')] | |
| 857 | after = line[line.find('\\n'):] | |
| 858 | (head, tail) = self.troff.eval_term(after) | |
| 859 | line = before + head + tail | |
| 779 | 860 | # Check to see if output translation is enabled. |
| 780 | 861 | if trans and self.outsubst: |
| 781 | 862 | do_xlate = True |
| 803 | 884 | self.diversion.append(line) |
| 804 | 885 | if line and not line.startswith("<!--"): |
| 805 | 886 | self.nonblanks += 1 |
| 887 | def endswith(self, trailer): | |
| 888 | "Check for a match with the end of what we've emitted." | |
| 889 | return self.diversion and self.diversion[-1].strip().endswith(trailer) | |
| 806 | 890 | |
| 807 | 891 | # Synopsis handling |
| 808 | 892 | def flush_transplant(self): |
| 851 | 935 | "Pop to new section level." |
| 852 | 936 | if section_verbosity in self.verbose: |
| 853 | 937 | self.notify("pop_section(%d)" % depth) |
| 854 | self.poplist('section-end') # Terminate all list structure | |
| 938 | self.poplist() # Terminate all list structure | |
| 855 | 939 | toplevel = (depth == 1) and (self.sectiondepth == 1) |
| 856 | 940 | self.troff.nf = False |
| 857 | 941 | self.end_paragraph(label="pop_section") |
| 951 | 1035 | self.troff.nf = True |
| 952 | 1036 | if io_verbosity in self.verbose: |
| 953 | 1037 | self.warning("begin display collection") |
| 954 | self.displaystack.append((markup, remap, DisplayParser(self,True,{}))) | |
| 1038 | self.displaystack.append((markup, remap, DisplayParser(self, | |
| 1039 | True, | |
| 1040 | True, | |
| 1041 | {}))) | |
| 955 | 1042 | else: |
| 956 | 1043 | self.emit(self.indent() + "<" + markup + remap + ">") |
| 957 | 1044 | if markup != "inlineequation": |
| 958 | 1045 | self.need_paragraph() |
| 959 | 1046 | |
| 960 | def end_block(self, markup, remap="", ends_unused=None): | |
| 1047 | def end_block(self, markup, remap=""): | |
| 961 | 1048 | "End a block-context markup section." |
| 962 | 1049 | # FIXME: use ends to ignore stray things that look like terminators |
| 963 | 1050 | if io_verbosity in self.verbose: |
| 964 | self.notify("end_block(%s)" % markup) | |
| 1051 | self.notify("end_block(markup='%s', remap='%s')" % (markup, remap)) | |
| 965 | 1052 | if remap and not self.quiet: |
| 966 | 1053 | remap = " <!-- remap='" + remap + "' -->" |
| 967 | 1054 | self.troff.nf = False |
| 971 | 1058 | # taken care of by close_tags() later on. |
| 972 | 1059 | if self.displaystack: |
| 973 | 1060 | (beginmarkup, beginremap, display) = self.displaystack.pop() |
| 974 | (parsed, userwarning) = display.transform() | |
| 1061 | (parsed, _) = display.transform() | |
| 975 | 1062 | self.emit("<" + beginmarkup + beginremap + ">") |
| 976 | 1063 | self.emit(parsed + (r"\fR</%s>" % markup + remap)) |
| 977 | 1064 | else: |
| 979 | 1066 | if markup != "inlineequation": |
| 980 | 1067 | self.need_paragraph() |
| 981 | 1068 | |
| 982 | def pushlist(self, cmd, type=None, explicit=False): | |
| 983 | if io_verbosity in self.verbose: | |
| 984 | self.notify("pushlist(%s, %s)" % (cmd, type)) | |
| 985 | self.stash_indents.append(Frame(cmd, type, explicit)) | |
| 986 | ||
| 987 | def poplist(self, cmd, backto=None): | |
| 1069 | def pushlist(self, cmd, ltype=None): | |
| 1070 | if section_verbosity in self.verbose: | |
| 1071 | self.notify("pushlist(%s, %s)" % (cmd, ltype)) | |
| 1072 | self.stash_indents.append(Frame(cmd, ltype)) | |
| 1073 | ||
| 1074 | def poplist(self, backto=None, remap=""): | |
| 988 | 1075 | "Pop levels off the list stack until we've removed specified command." |
| 989 | if io_verbosity in self.verbose: | |
| 990 | self.notify("poplist(%s, %s) %s" % (cmd, backto, self.stash_indents)) | |
| 1076 | if section_verbosity in self.verbose: | |
| 1077 | self.notify("poplist(%s) %s" % (backto, self.stash_indents)) | |
| 991 | 1078 | while self.stash_indents: |
| 992 | 1079 | frame = self.stash_indents[-1] |
| 993 | 1080 | if frame.type == "variablelist": |
| 995 | 1082 | elif frame.type == "itemizedlist": |
| 996 | 1083 | self.emit_itemizedlist("end") |
| 997 | 1084 | elif frame.type == "blockquote": |
| 998 | self.end_block("blockquote", remap='RE') | |
| 1085 | self.end_block("blockquote", remap=remap) | |
| 999 | 1086 | self.stash_indents.pop() |
| 1000 | 1087 | else: |
| 1001 | 1088 | self.stash_indents.pop() |
| 1002 | 1089 | if frame.command == backto: |
| 1003 | 1090 | break |
| 1004 | if io_verbosity in self.verbose: | |
| 1091 | if section_verbosity in self.verbose: | |
| 1005 | 1092 | self.notify("after popping %s" % (self.stash_indents,)) |
| 1006 | 1093 | |
| 1007 | 1094 | def last_tag(self, lookfor): |
| 1030 | 1117 | # Empty item with a bunch of .TP lines before it. |
| 1031 | 1118 | # Retroactively hack this into an itemized list. |
| 1032 | 1119 | if self.last_tag("<listitem"): |
| 1120 | if self.verbose: | |
| 1121 | self.warning("variable-list header just before section break") | |
| 1122 | if section_verbosity in self.verbose: | |
| 1123 | self.notify("remaking as itemized") | |
| 1033 | 1124 | backup = -1 |
| 1034 | 1125 | while True: |
| 1035 | 1126 | line = self.diversion[backup] |
| 1058 | 1149 | else: |
| 1059 | 1150 | remap = " remap='%s'" % cmd |
| 1060 | 1151 | self.emit("%s<variablelist%s>" % (self.indent(), remap)) |
| 1061 | self.stash_indents.append(Frame(cmd, "variablelist")) | |
| 1152 | self.pushlist(cmd, "variablelist") | |
| 1062 | 1153 | indent = self.indent() |
| 1063 | 1154 | back = self.last_tag("<listitem") |
| 1064 | 1155 | if back: |
| 1068 | 1159 | self.emit("%s</listitem>" % indent) |
| 1069 | 1160 | self.emit("%s</varlistentry>" % indent) |
| 1070 | 1161 | self.emit("%s<varlistentry>" % indent) |
| 1071 | self.emit("%s<term>%s</term>" % (indent, fontclose(term))) | |
| 1162 | if type(term) == type(""): | |
| 1163 | self.emit("%s<term>%s</term>" % (indent, fontclose(term))) | |
| 1164 | elif type(term) == type([]): | |
| 1165 | for item in term: | |
| 1166 | self.emit("%s<term>%s</term>" % (indent, fontclose(item))) | |
| 1072 | 1167 | self.emit("%s<listitem>" % indent) |
| 1073 | 1168 | self.stash_indents[-1].count += 1 |
| 1074 | 1169 | self.need_paragraph() |
| 1095 | 1190 | else: |
| 1096 | 1191 | remap = " remap='%s'" % cmd |
| 1097 | 1192 | self.emit("%s<itemizedlist%s>" % (self.indent(), remap)) |
| 1098 | self.stash_indents.append(Frame(cmd, "itemizedlist")) | |
| 1193 | self.pushlist(cmd, "itemizedlist") | |
| 1099 | 1194 | indent = self.indent() |
| 1100 | 1195 | back = self.last_tag("<listitem") |
| 1101 | 1196 | if back: |
| 1194 | 1289 | self.pushline(nextl) |
| 1195 | 1290 | return make_comment("bogus %s elided" % highlight) |
| 1196 | 1291 | else: |
| 1197 | words = next.split() | |
| 1292 | words = nextl.split() | |
| 1198 | 1293 | if not trailer and words[-1][-2:] == "\\c": |
| 1199 | 1294 | trailer = "\\c" |
| 1200 | 1295 | words[-1] = words[-1][:-2] |
| 1236 | 1331 | # Smash out all characters that aren't legal in SGML ids, except spaces |
| 1237 | 1332 | squashed = "" |
| 1238 | 1333 | for c in istr: |
| 1239 | if c in "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789_ ": | |
| 1240 | squashed += c | |
| 1334 | if c in "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789_ ": | |
| 1335 | squashed += c | |
| 1241 | 1336 | squashed = squashed.strip() |
| 1242 | 1337 | if squashed: |
| 1243 | 1338 | # IDs cannot begin with whitespace, a dash or digits |
| 1252 | 1347 | return self.name + "-" + newid |
| 1253 | 1348 | else: |
| 1254 | 1349 | return newid |
| 1255 | def make_id_from_title(self, str): | |
| 1256 | sid = self.id_from_title(str) | |
| 1350 | def make_id_from_title(self, st): | |
| 1351 | sid = self.id_from_title(st) | |
| 1257 | 1352 | # We allow duplicate sections, but warn about them |
| 1258 | 1353 | if not self.idlist.has_key(sid): |
| 1259 | 1354 | self.idlist[sid] = 1 |
| 1260 | 1355 | return sid |
| 1261 | 1356 | else: |
| 1262 | 1357 | self.idlist[sid] += 1 |
| 1263 | #self.error("more than one section is named %s" % str) | |
| 1358 | #self.error("more than one section is named %s" % st) | |
| 1264 | 1359 | return sid + `self.idlist[sid]` |
| 1265 | 1360 | |
| 1266 | 1361 | def id_exists(self, sid): |
| 1327 | 1422 | data = [] |
| 1328 | 1423 | rowsep = [] |
| 1329 | 1424 | datawidth = 0 |
| 1425 | comments = [] | |
| 1330 | 1426 | while self.lines: |
| 1331 | 1427 | tline = self.lines.pop(0) |
| 1332 | 1428 | if tline.strip() == enddelim: |
| 1339 | 1435 | tline += "\n" + continuation |
| 1340 | 1436 | if continuation[:2] == "T}" and continuation[-2:] != "T{": |
| 1341 | 1437 | break |
| 1438 | comments.append(None) | |
| 1342 | 1439 | if not tline in ("_", "="): |
| 1440 | if '\\"' in tline: | |
| 1441 | cstart = tline.find('\\"') | |
| 1442 | comments[-1] = tline[cstart:] | |
| 1443 | tline = tline[:cstart].strip() | |
| 1343 | 1444 | fields = tline.split(tab) |
| 1344 | 1445 | if len(fields) > datawidth: |
| 1345 | 1446 | datawidth = len(fields) |
| 1358 | 1459 | # ^. DocBook vertical spans can't cross the |
| 1359 | 1460 | # table-header/table-body boundary, so there has to be at |
| 1360 | 1461 | # least one table body format line not containing ^. |
| 1361 | lastheaderline = len(tbl) - 2; | |
| 1462 | lastheaderline = len(tbl) - 2 | |
| 1362 | 1463 | try: |
| 1363 | 1464 | for tbli in range(len(tbl)): |
| 1364 | 1465 | for j in range(len(tbl[tbli])): |
| 1365 | 1466 | if tbl[tbli][j][0] == '^': |
| 1366 | lastheaderline = tbli - 2; | |
| 1467 | lastheaderline = tbli - 2 | |
| 1367 | 1468 | raise Dropout |
| 1368 | 1469 | except Dropout: |
| 1369 | 1470 | pass |
| 1473 | 1574 | if troff_highlight.search(line) is not None: |
| 1474 | 1575 | line += r"\fR" |
| 1475 | 1576 | self.emit(self.troff.expand_strings(line) + "</entry>") |
| 1476 | self.emit(" </row>") | |
| 1577 | comment = comments.pop(0) | |
| 1578 | if comment is None: | |
| 1579 | trailer = "" | |
| 1580 | else: | |
| 1581 | trailer = " " + make_comment(comment) | |
| 1582 | self.emit(" </row>" + trailer) | |
| 1477 | 1583 | if i == lastheaderline: |
| 1478 | 1584 | if lastheaderline > -1: |
| 1479 | 1585 | self.emit(" </thead>") |
| 1562 | 1668 | |
| 1563 | 1669 | def ignore(self, cmd): |
| 1564 | 1670 | "Declare that we want to ignore a command." |
| 1565 | self.ignore_set[cmd] = True | |
| 1671 | self.ignore_set.add(cmd) | |
| 1566 | 1672 | |
| 1567 | 1673 | def unignore(self, cmd): |
| 1568 | 1674 | "Declare that we want to stop ignoring a command." |
| 1569 | 1675 | if cmd in self.ignore_set: |
| 1570 | del self.ignore_set[cmd] | |
| 1676 | self.ignore_set.remove(cmd) | |
| 1571 | 1677 | |
| 1572 | 1678 | def ignorable(self, command, nocomplaints=0): |
| 1573 | 1679 | "Can this command be safely ignored?" |
| 1602 | 1708 | enclosing = self.stash_indents[-1].command |
| 1603 | 1709 | if enclosing in self.listbreak_set and enclosing != command: |
| 1604 | 1710 | while len(self.stash_indents): |
| 1605 | # Implicit list closers should not pop us all the way | |
| 1606 | # out of explicit list structure. | |
| 1607 | if self.stash_indents[-1].explicit == 'RS': | |
| 1608 | break | |
| 1609 | self.poplist(TroffInterpreter.ctrl + "end", self.stash_indents[-1].command) | |
| 1610 | # Here is where string expansion gets done: | |
| 1711 | self.poplist(self.stash_indents[-1].command) | |
| 1712 | # Here is where string expansion in command arguments gets done: | |
| 1611 | 1713 | stripped = [] |
| 1612 | 1714 | for arg in stripquotes(tokens): |
| 1613 | 1715 | if arg in self.troff.strings: |
| 1682 | 1784 | # who forget that the closing bracket of a conditional is |
| 1683 | 1785 | # a command. It's probably going to bite us someday. |
| 1684 | 1786 | if line == r"\}": |
| 1685 | self.pushline(TroffInterpreter.ctrl + "\}") | |
| 1787 | self.pushline(TroffInterpreter.ctrl + r"\}") | |
| 1686 | 1788 | if macro_verbosity in self.verbose: |
| 1687 | 1789 | self.warning(r"adventitious \} should probably be .\}") |
| 1688 | 1790 | continue |
| 1737 | 1839 | if divert is not None: |
| 1738 | 1840 | self.diversion = self.output |
| 1739 | 1841 | |
| 1740 | def find(self, str, backwards=False): | |
| 1842 | def find(self, st, backwards=False): | |
| 1741 | 1843 | "Does the string occur in text we haven't seen yet?" |
| 1742 | 1844 | if backwards: |
| 1743 | 1845 | lines = self.output + self.lines |
| 1745 | 1847 | lines = self.lines |
| 1746 | 1848 | for line in lines: |
| 1747 | 1849 | if type(line) == type(""): |
| 1748 | if type(str) == type(""): | |
| 1749 | if str in line: | |
| 1850 | if type(st) == type(""): | |
| 1851 | if st in line: | |
| 1750 | 1852 | return True |
| 1751 | 1853 | else: |
| 1752 | if str.search(line): | |
| 1854 | if st.search(line): | |
| 1753 | 1855 | return True |
| 1754 | 1856 | return False |
| 1755 | 1857 | |
| 1756 | 1858 | def expand_entities(self, line): |
| 1859 | "Expand character entities." | |
| 1860 | # Specials associated with troff and various macro sets | |
| 1757 | 1861 | for interpreter in self.interpreters: |
| 1758 | 1862 | for prefix in interpreter.translations: |
| 1759 | 1863 | if prefix in line: |
| 1760 | 1864 | for (special, trans) in interpreter.translations[prefix]: |
| 1761 | 1865 | line = line.replace(special, trans) |
| 1866 | # groff-style ASCII and Unicode escapes. Have to use a little | |
| 1867 | # state machine here, trying to do this with regexps gives | |
| 1868 | # the regexp compiler fits. | |
| 1869 | oldstart = 0 | |
| 1870 | while oldstart < len(line): | |
| 1871 | start = oldstart + line[oldstart:].find('\\') | |
| 1872 | if start == -1: | |
| 1873 | break | |
| 1874 | elif line[start:].startswith("\\[char"): | |
| 1875 | m = re.match(r"[0-9]+(?=\135)", line[start+6:]) | |
| 1876 | if m: | |
| 1877 | line = line[:start] + "&#" + m.group(0) + ";" + line[start + 6 + len(m.group(0)) + 1:] | |
| 1878 | oldstart = start + 2 | |
| 1879 | elif line[start:].startswith("\\[u"): | |
| 1880 | m = re.match(r"[0-9]+(?=\135)", line[start+3:]) | |
| 1881 | if m: | |
| 1882 | line = line[:start] + "&#" + m.group(0) + ";" + line[start + 3 + len(m.group(0)) + 1:] | |
| 1883 | oldstart = start + 2 | |
| 1884 | else: | |
| 1885 | oldstart += 1 | |
| 1762 | 1886 | return line |
| 1763 | 1887 | |
| 1764 | 1888 | def hack_translations(self, line): |
| 1770 | 1894 | while True: |
| 1771 | 1895 | esc = troff_highlight.search(line) |
| 1772 | 1896 | if not esc: |
| 1773 | break; | |
| 1897 | break | |
| 1774 | 1898 | else: |
| 1775 | 1899 | esc = esc.start() |
| 1776 | 1900 | if line[esc+2:esc+4] == "[]": |
| 1788 | 1912 | "Checks highlighted content to see if it's an XML id which exists" |
| 1789 | 1913 | # Currently, matches only <emphasis> highlights |
| 1790 | 1914 | if not re_compile("<emphasis").match(line): |
| 1791 | return line; | |
| 1915 | return line | |
| 1792 | 1916 | for (link_highlight, re_content) in self.lift_links: |
| 1793 | lift = re_compile("<emphasis\s+remap='%s'>(%s)</emphasis>" % (link_highlight, re_content)) | |
| 1917 | lift = re_compile(r"<emphasis\s+remap='%s'>(%s)</emphasis>" % (link_highlight, re_content)) | |
| 1794 | 1918 | if lift.match(line): |
| 1795 | 1919 | content = lift.sub(r"\1", line) |
| 1920 | trailer = "" | |
| 1921 | if content.endswith("</para>"): | |
| 1922 | content = content[:-7] | |
| 1923 | trailer = "</para>" | |
| 1796 | 1924 | sid = self.id_from_title(content) |
| 1797 | 1925 | if self.id_exists(sid): |
| 1798 | return '<link linkend="%s">%s</link>' % (sid, content) | |
| 1926 | return '<link linkend="%s">%s</link>%s' % (sid, content, trailer) | |
| 1799 | 1927 | return line |
| 1800 | 1928 | |
| 1801 | 1929 | def is_active(self, macro_set): |
| 1810 | 1938 | for ancestor in macro_set.requires: |
| 1811 | 1939 | self.activate(ancestor) |
| 1812 | 1940 | newinstance = macro_set(self, self.verbose) |
| 1813 | self.interpreters.append(newinstance) | |
| 1941 | self.interpreters = [newinstance] + self.interpreters | |
| 1814 | 1942 | if general_verbosity in self.verbose: |
| 1815 | 1943 | stderr.write("%s uses %s macros...\n" % (self.file, macro_set.name)) |
| 1816 | 1944 | |
| 1924 | 2052 | continue |
| 1925 | 2053 | return after |
| 1926 | 2054 | |
| 1927 | def lynxprep(self, text, file): | |
| 2055 | @staticmethod | |
| 2056 | def lynxprep(text, lfile): | |
| 1928 | 2057 | "Turn a text lynx dump into a manual page." |
| 1929 | 2058 | lines = text.split("\n") |
| 1930 | 2059 | # Drop everything before the NAME section header, this gets rid of |
| 1953 | 2082 | elif lines[i][0] == TroffInterpreter.ctrl: |
| 1954 | 2083 | lines[i] = "\\&" + lines[i] |
| 1955 | 2084 | name = section = "" |
| 1956 | if "." in os.path.basename(file): | |
| 1957 | (name, section) = os.path.basename(file).split(".") | |
| 2085 | if "." in os.path.basename(lfile): | |
| 2086 | (name, section) = os.path.basename(lfile).split(".") | |
| 1958 | 2087 | name = os.path.basename(name) |
| 1959 | 2088 | th = '.TH "%s" "%s" "%s" "" ""\n' % (name, section, date) |
| 1960 | 2089 | return th + "\n".join(lines) + "\n" |
| 1961 | 2090 | |
| 1962 | def __call__(self, name, file, text, multiarg): | |
| 2091 | def __call__(self, name, cfile, text, multiarg): | |
| 1963 | 2092 | "Translate a string containing troff source to DocBook markup." |
| 1964 | 2093 | self.name = name |
| 1965 | self.file = file | |
| 2094 | self.file = cfile | |
| 1966 | 2095 | self.multiarg = multiarg |
| 1967 | self.eqnsub = None | |
| 1968 | self.in_preamble = True | |
| 1969 | self.body_start = 0 | |
| 1970 | self.highlight = "R" | |
| 1971 | self.oldhighlight = "R" | |
| 1972 | self.lines = None | |
| 1973 | self.lineno = 0 | |
| 1974 | self.need_para = False | |
| 1975 | self.sectiondepth = 0 | |
| 1976 | self.output = [] | |
| 1977 | self.inclusions = [] | |
| 1978 | self.pushdown = [] # Stack of input sources | |
| 1979 | 2096 | self.diversion = self.output |
| 1980 | 2097 | self.starttime = self.basetime = time.time() |
| 1981 | self.localentities = [] | |
| 1982 | self.eqn_processed = False | |
| 1983 | self.pic_processed = False | |
| 1984 | 2098 | # Set up the base troff interpreter |
| 1985 | 2099 | self.troff = TroffInterpreter(self, self.verbose) |
| 1986 | 2100 | self.interpreters = [self.troff] |
| 1988 | 2102 | # Empty files pass through trivially. |
| 1989 | 2103 | # (This is not a terribly uncommon defect...) |
| 1990 | 2104 | if len(text) == 0: |
| 1991 | raise LiftException("%s is empty" % file, 1) | |
| 2105 | raise LiftException("%s is empty" % cfile, 1) | |
| 1992 | 2106 | # Parse semantic hints from the text, if present. |
| 1993 | 2107 | # Yes, they should go to the global registry. |
| 1994 | global globalhints | |
| 1995 | 2108 | globalhints.read(text) |
| 1996 | 2109 | if timing_verbosity in self.verbose: |
| 1997 | 2110 | now = time.time() |
| 2005 | 2118 | # Find uses of each trigger, sort by position of first occurrence |
| 2006 | 2119 | for (pattern, consumer) in interpreter_dispatch.items(): |
| 2007 | 2120 | # If the file has an extension, we can exclude some possibilities |
| 2008 | if "." in file: | |
| 2121 | if "." in cfile: | |
| 2009 | 2122 | required = required_extensions.get(consumer) |
| 2010 | if required and not file.endswith(required): | |
| 2123 | if required and not cfile.endswith(required): | |
| 2011 | 2124 | continue |
| 2012 | 2125 | # Otherwise look for first uses of trigger patterns |
| 2013 | 2126 | if len(pattern) <= 5: |
| 2042 | 2155 | elif text.find("Table Of Contents") > -1 or text.find(" Updated: ") > -1: |
| 2043 | 2156 | if self.verbose: |
| 2044 | 2157 | stderr.write("Looks like a lynx dump...\n") |
| 2045 | text = self.lynxprep(text, file) | |
| 2158 | text = DocLifter.lynxprep(text, cfile) | |
| 2046 | 2159 | self.activate(ManInterpreter) |
| 2047 | 2160 | # Default to a lynx dump even if unsure. |
| 2048 | 2161 | else: |
| 2049 | 2162 | if self.verbose: |
| 2050 | 2163 | stderr.write("Unknown format so defaulting to a lynx dump...\n") |
| 2051 | text = self.lynxprep(text, file) | |
| 2164 | text = DocLifter.lynxprep(text, cfile) | |
| 2052 | 2165 | self.activate(ManInterpreter) |
| 2053 | 2166 | if timing_verbosity in self.verbose: |
| 2054 | 2167 | now = time.time() |
| 2064 | 2177 | text = text.replace(ugly, entity) |
| 2065 | 2178 | # Allow the interpreters to preprocess the output. |
| 2066 | 2179 | for interpreter in self.interpreters: |
| 2067 | self.listbreak_set.update(interpreter.listbreak_set) | |
| 2068 | self.ignore_set.update(interpreter.ignore_set) | |
| 2069 | self.complain_set.update(interpreter.complain_set) | |
| 2180 | self.listbreak_set |= interpreter.listbreak_set | |
| 2181 | self.ignore_set |= interpreter.ignore_set | |
| 2182 | self.complain_set |= interpreter.complain_set | |
| 2070 | 2183 | text = interpreter.preprocess(text) |
| 2071 | 2184 | if timing_verbosity in self.verbose: |
| 2072 | 2185 | now = time.time() |
| 2081 | 2194 | if len(nonempty) == 1 and is_inclusion(nonempty[0]): |
| 2082 | 2195 | raise LiftException("see " + nonempty[0].strip()[4:], 2) |
| 2083 | 2196 | elif len(nonempty) > 1 and len(filter(is_inclusion, nonempty)) == len(nonempty): |
| 2084 | raise LiftException("%s consists entirely of inclusions" % file, 2) | |
| 2197 | raise LiftException("%s consists entirely of inclusions" % cfile, 2) | |
| 2085 | 2198 | # If it's not a pure inclusion, warn if we don't have a macro set. |
| 2086 | 2199 | if len(self.interpreters) == 1: |
| 2087 | 2200 | raise LiftException("no macro set recognized", 1) |
| 2093 | 2206 | # that stop after .TH, without even a name section. |
| 2094 | 2207 | if len(toplevel) <= 1: |
| 2095 | 2208 | self.filewarn("%s has no content" % self.file) |
| 2096 | (stem, ext) = os.path.splitext(self.file) | |
| 2209 | (stem, _) = os.path.splitext(self.file) | |
| 2097 | 2210 | toplevel.append(".SH NAME") |
| 2098 | 2211 | toplevel.append("%s \\- bogus empty manual page" % os.path.basename(stem)) |
| 2099 | 2212 | toplevel.append(".SH DESCRIPTION") |
| 2115 | 2228 | if self.toptag: |
| 2116 | 2229 | if self.file != "stdin": |
| 2117 | 2230 | if self.docbook5: |
| 2118 | self.emit("<%s xmlns='http://docbook.org/ns/docbook' version='5.0' xml:lang='en' xml:id='%s'>" % (self.toptag, self.make_id_from_title(os.path.basename(file)))) | |
| 2231 | self.emit("<%s xmlns='http://docbook.org/ns/docbook' version='5.0' xml:lang='en' xml:id='%s'>" % (self.toptag, self.make_id_from_title(os.path.basename(cfile)))) | |
| 2119 | 2232 | else: |
| 2120 | self.emit("<%s id='%s'>" % (self.toptag, self.make_id_from_title(os.path.basename(file)))) | |
| 2233 | self.emit("<%s id='%s'>" % (self.toptag, self.make_id_from_title(os.path.basename(cfile)))) | |
| 2121 | 2234 | else: |
| 2122 | 2235 | self.emit("<%s>" % self.toptag) |
| 2123 | 2236 | if timing_verbosity in self.verbose: |
| 2275 | 2388 | # FIXME: if docbook5 is on, inclusions won't work. |
| 2276 | 2389 | if self.docbook5: |
| 2277 | 2390 | if entities: |
| 2278 | preamble += allent; | |
| 2391 | preamble += allent | |
| 2279 | 2392 | else: |
| 2280 | 2393 | preamble += "<!DOCTYPE %s PUBLIC \"-//OASIS//DTD DocBook " % self.toptag |
| 2281 | 2394 | preamble += "XML V4.4//EN\"\n \"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd\"" |
| 2288 | 2401 | preamble += entities |
| 2289 | 2402 | preamble += "]" |
| 2290 | 2403 | preamble += ">\n" |
| 2291 | preamble += "<!-- lifted from %s by doclifter -->\n" % "+".join(map(lambda x: x.__class__.name, self.interpreters)) | |
| 2404 | macros = map(lambda x: x.__class__.name, self.interpreters) | |
| 2405 | #macros.reverse() | |
| 2406 | preamble += "<!-- lifted from %s by doclifter -->\n" % "+".join(macros) | |
| 2292 | 2407 | # If there were accumulated errors during processing, time to bail. |
| 2293 | 2408 | if self.errorcount: |
| 2294 | 2409 | raise LiftException("there were %d errors during translation" % self.errorcount) |
| 2315 | 2430 | name = "troff" |
| 2316 | 2431 | exclusive = False |
| 2317 | 2432 | toptag = "" |
| 2318 | immutable_set = {} | |
| 2319 | ignore_set = { | |
| 2433 | immutable_set = set([]) | |
| 2434 | ignore_set = set([ | |
| 2320 | 2435 | # Ignore .. outside macro context, some people use it as a no-op. |
| 2321 | ".":1, | |
| 2436 | ".", | |
| 2322 | 2437 | # Just ignore most font/character-size/page controls |
| 2323 | "ps":1,"ss":1,"cs":1,"bd":1,"fp":1,"pl":1,"pn":1,"po":1,"ne":1, | |
| 2438 | "ps","ss","cs","bd","fp","pl","pn","po","ne", | |
| 2324 | 2439 | # Ignore most text filling and vertical spacing controls. |
| 2325 | "ad":1,"na":1,"vs":1,"ls":1,"sv":1,"os":1,"ns":1,"rs":1, | |
| 2440 | "ad","na","vs","ls","sv","os","ns","rs", | |
| 2326 | 2441 | # Line length, tabs,leaders, fields, ligature mode, hyphenation. |
| 2327 | "ll":1,"tc":1,"lc":1,"fc":1,"lg":1,"nh":1,"hy":1,"hc":1,"hw":1, | |
| 2442 | "ll","tc","lc","fc","lg","nh","hy","hc","hw", | |
| 2328 | 2443 | # Ignore commands for page titles, exit, miscellanea |
| 2329 | "tl":1,"pc":1,"lt":1,"ex":1,"mc":1,"fl":1, | |
| 2444 | "tl","pc","lt","ex","mc","fl", | |
| 2330 | 2445 | # Also ignore diversions and register operations. |
| 2331 | "di":1,"da":1,"wh":1,"ch":1,"dt":1,"lt":1,"af":1, | |
| 2446 | "di","da","wh","ch","dt","af", | |
| 2332 | 2447 | # This is some nonstandard extension (see access.1) safe to ignore |
| 2333 | "rb":1, | |
| 2448 | "rb", | |
| 2334 | 2449 | # Ignore groff debugging stuff |
| 2335 | "lf":1, | |
| 2450 | "lf", | |
| 2336 | 2451 | # Weird groff extensions. |
| 2337 | "hcode":1, "hym":1, "hys":1, "hla":1, "shc":1, "cp":1,"fam":1, | |
| 2452 | "hcode", "hym", "hys", "hla", "shc", "cp","fam", | |
| 2338 | 2453 | # Better to pass through glyphs defined by char than try to expand |
| 2339 | 2454 | # them; we'll translate most into entities and flag the rest as |
| 2340 | 2455 | # errors. |
| 2341 | "char":1, | |
| 2456 | "char", | |
| 2342 | 2457 | # Policy decision; don't do font remapping, on the theory that |
| 2343 | 2458 | # passing through the font names the user specified into remap |
| 2344 | 2459 | # attributes probably carries forward more information. |
| 2345 | "ftr":1, | |
| 2346 | } | |
| 2347 | complain_set = { | |
| 2460 | "ftr", | |
| 2461 | # We can't do anything with the groff defcolor request, alas. | |
| 2462 | "defcolor", | |
| 2463 | ]) | |
| 2464 | complain_set = set([ | |
| 2348 | 2465 | # Complain about stuff that produces gross motions. |
| 2349 | "ne":1,"mk":1,"rt":1,"ce":1,"rj":1, | |
| 2466 | "ne","mk","rt","ce", | |
| 2350 | 2467 | # We could do much of section 10, but these are a sign of trouble. |
| 2351 | "ec":1,"eo":1,"uf":1, | |
| 2468 | "ec","eo","uf", | |
| 2352 | 2469 | # We can't handle environments, insertions, or next file. |
| 2353 | "ev":1,"rd":1,"nx":1,"pi":1, | |
| 2354 | } | |
| 2355 | parabreak_set = {"bp":1,"ti":1} | |
| 2356 | sectionbreak_set = {} | |
| 2357 | listbreak_set = {} | |
| 2470 | "ev","rd","nx","pi", | |
| 2471 | ]) | |
| 2472 | parabreak_set = set(["bp","ti"]) | |
| 2473 | sectionbreak_set = set([]) | |
| 2474 | listbreak_set = set([]) | |
| 2358 | 2475 | entity_translations = ( |
| 2359 | # The entire list of characters described in the troff/nroff reference | |
| 2476 | # The entire list of characters described in the groff/troff reference | |
| 2360 | 2477 | # is included here. Where there is no ISO equivalent, the second |
| 2361 | 2478 | # member will be an alias for a Unicode literal. This transformation |
| 2362 | 2479 | # is done late, at output-emission time. |
| 2366 | 2483 | (r"&", "&zerosp;"), |
| 2367 | 2484 | (r"<", "<"), # Prevent spurious messages about \& |
| 2368 | 2485 | (r">", ">"), # Prevent spurious messages about \& |
| 2369 | (r";",";"), | |
| 2486 | (r"'", "'"), # Prevent spurious messages about \& | |
| 2487 | (r";",";"), # Prevent spurious messages about \& | |
| 2370 | 2488 | (r")", "&zerosp;"), # groff extension |
| 2371 | 2489 | (r"~", " "), # This isn't quite right, alas. |
| 2372 | 2490 | (r" ", " "), |
| 2374 | 2492 | (r"^", " "), # ISOpub |
| 2375 | 2493 | (r"`", "`"), # ISOdia |
| 2376 | 2494 | (r"e", "\"), # ISOnum |
| 2495 | (r"\\", "\"), # ISOnum | |
| 2377 | 2496 | (r"|", " "), # ISOpub |
| 2378 | 2497 | (r":", ""), # No hyphenation in XML |
| 2379 | 2498 | (r"/", ""), # No kerning in XML |
| 2385 | 2504 | (r"=", "="), |
| 2386 | 2505 | (r"_", "_"), |
| 2387 | 2506 | (r"t", "\t"), |
| 2388 | # Classic troff special characters | |
| 2389 | (r"%", "­"), # ISOnum | |
| 2390 | (r"'", "´"), # ISOdia | |
| 2391 | (r"!=", "≠"), # ISOtech | |
| 2392 | (r"**", "∗"), # ISOtech | |
| 2393 | (r"*a", "&agr;"), # ISOgrk1 | |
| 2394 | (r"*A", "&Agr;"), # ISOgrk1 | |
| 2395 | (r"*b", "&bgr;"), # ISOgrk1 | |
| 2396 | (r"*B", "&Bgr;"), # ISOgrk1 | |
| 2397 | (r"*d", "&dgr;"), # ISOgrk1 | |
| 2398 | (r"*D", "&Dgr;"), # ISOgrk1 | |
| 2399 | (r"*e", "&egr;"), # ISOgrk1 | |
| 2400 | (r"*E", "&Egr;"), # ISOgrk1 | |
| 2401 | (r"*f", "&phgr;"), # ISOgrk1 | |
| 2402 | (r"*F", "&PHgr;"), # ISOgrk1 | |
| 2403 | (r"*g", "&ggr;"), # ISOgrk1 | |
| 2404 | (r"*G", "&Ggr;"), # ISOgrk1 | |
| 2405 | (r"*h", "&thgr;"), # ISOgrk1 | |
| 2406 | (r"*H", "&THgr;"), # ISOgrk1 | |
| 2407 | (r"*i", "&igr;"), # ISOgrk1 | |
| 2408 | (r"*I", "&Igr;"), # ISOgrk1 | |
| 2409 | (r"*k", "&kgr;"), # ISOgrk1 | |
| 2410 | (r"*K", "&Kgr;"), # ISOgrk1 | |
| 2411 | (r"*l", "&lgr;"), # ISOgrk1 | |
| 2412 | (r"*L", "&Lgr;"), # ISOgrk1 | |
| 2413 | (r"*m", "&mgr;"), # ISOgrk1 | |
| 2414 | (r"*M", "&Mgr;"), # ISOgrk1 | |
| 2415 | (r"*n", "&ngr;"), # ISOgrk1 | |
| 2416 | (r"*N", "&Ngr;"), # ISOgrk1 | |
| 2417 | (r"*o", "&ogr;"), # ISOgrk1 | |
| 2418 | (r"*O", "&Ogr;"), # ISOgrk1 | |
| 2419 | (r"*p", "&pgr;"), # ISOgrk1 | |
| 2420 | (r"*P", "&Pgr;"), # ISOgrk1 | |
| 2421 | (r"*q", "&psgr;"), # ISOgrk1 | |
| 2422 | (r"*Q", "&PSgr;"), # ISOgrk1 | |
| 2423 | (r"*r", "&rgr;"), # ISOgrk1 | |
| 2424 | (r"*R", "&Rgr;"), # ISOgrk1 | |
| 2425 | (r"*s", "&sgr;"), # ISOgrk1 | |
| 2426 | (r"*S", "&Sgr;"), # ISOgrk1 | |
| 2427 | (r"*t", "&tgr;"), # ISOgrk1 | |
| 2428 | (r"*T", "&Tgr;"), # ISOgrk1 | |
| 2429 | (r"*u", "&ugr;"), # ISOgrk1 | |
| 2430 | (r"*U", "&Ugr;"), # ISOgrk1 | |
| 2431 | (r"*w", "&ohgr;"), # ISOgrk1 | |
| 2432 | (r"*W", "&OHgr;"), # ISOgrk1 | |
| 2433 | (r"*x", "&khgr;"), # ISOgrk1 | |
| 2434 | (r"*X", "&KHgr;"), # ISOgrk1 | |
| 2435 | (r"*y", "&eegr;"), # ISOgrk1 | |
| 2436 | (r"*Y", "&EEgr;"), # ISOgrk1 | |
| 2437 | (r"*z", "&zgr;"), # ISOgrk1 | |
| 2438 | (r"*Z", "&Zgr;"), # ISOgrk1 | |
| 2439 | (r"+-", "±"), # ISOnum | |
| 2440 | (r"->", "→"), # ISOnum (XMLified) | |
| 2441 | (r"12", "½"), # ISOnum | |
| 2442 | (r"14", "¼"), # ISOnum | |
| 2443 | (r"34", "¾"), # ISOnum | |
| 2444 | (r"<-", "←"), # ISOnum (XMLified) | |
| 2445 | (r"==", "≡"), # ISOtech | |
| 2446 | (r"Fi", "ffi"), # ISOpub | |
| 2447 | (r"Fl", "ffl"), # ISOpub | |
| 2448 | (r"aa", "´"), # ISOdia | |
| 2449 | (r"ap", "∼"), # ISOtech | |
| 2450 | (r"bl", "&phonexb;"), # ISOpub | |
| 2451 | (r"br", "│"), # ISObox | |
| 2452 | (r"bs", "☎"), # ISOpub (for the Bell logo) | |
| 2453 | (r"bu", "•"), # ISOpub | |
| 2454 | (r"bv", "|"), # ISOnum | |
| 2455 | (r"ca", "∩"), # ISOtech | |
| 2456 | (r"ci", "○"), # ISOpub | |
| 2457 | (r"co", "©"), # ISOnum | |
| 2458 | (r"ct", "¢"), # ISOnum | |
| 2459 | (r"cu", "∪"), # ISOtech | |
| 2460 | (r"da", "↓"), # ISOnum | |
| 2461 | (r"de", "°"), # ISOnum | |
| 2462 | (r"dg", "†"), # ISOpub | |
| 2463 | (r"dd", "‡"), # ISOpub | |
| 2464 | (r"di", "÷"), # ISOnum | |
| 2465 | (r"em", "—"), # ISOpub | |
| 2466 | (r"eq", "="), # ISOnum | |
| 2467 | (r"es", "∅"), # ISOamso | |
| 2468 | (r"ff", "ff"), # ISOpub | |
| 2469 | (r"fi", "fi"), # ISOpub | |
| 2470 | (r"fl", "fl"), # ISOpub | |
| 2471 | (r"fm", "′"), # ISOtech | |
| 2472 | (r"ge", "≥"), # ISOtech | |
| 2473 | (r"gr", "∇"), # ISOtech | |
| 2474 | (r"hy", "‐"), # ISOnum | |
| 2475 | (r"ib", "⊆"), # ISOtech | |
| 2476 | (r"if", "∞"), # ISOtech | |
| 2477 | (r"ip", "⊇"), # ISOtech | |
| 2478 | (r"is", "∫"), # ISOtech | |
| 2479 | (r"le", "≤"), # ISOtech | |
| 2480 | (r"lb", "&lb;"), # Internal pseudo-entity | |
| 2481 | (r"lc", "&lc;"), # Internal pseudo-entity | |
| 2482 | (r"lf", "&lf;"), # Internal pseudo-entity | |
| 2483 | (r"lh", "&lh;"), # Internal pseudo-entity | |
| 2484 | (r"lk", "&lk;"), # Internal pseudo-entity | |
| 2485 | (r"lt", "&tlt;"), # Internal pseudo-entity (avoid clash w/ <) | |
| 2486 | (r"mi", "−"), # ISOtech | |
| 2487 | (r"mo", "∈"), # ISOtech | |
| 2488 | (r"mu", "×"), # ISOnum | |
| 2489 | (r"no", "¬"), # ISOnum | |
| 2490 | (r"or", "|"), # ISOnum | |
| 2491 | (r"pl", "+"), # ISOnum | |
| 2492 | (r"pt", "∝"), # ISOtech | |
| 2493 | (r"rg", "™"), # ISOnum | |
| 2494 | (r"rb", "&rb;"), # Internal pseudo-entity | |
| 2495 | (r"rc", "&rc;"), # Internal pseudo-entity | |
| 2496 | (r"rf", "&rf;"), # Internal pseudo-entity | |
| 2497 | (r"rh", "&rh;"), # Internal pseudo-entity | |
| 2498 | (r"rk", "&rk;"), # Internal pseudo-entity | |
| 2499 | (r"rt", "&rt;"), # Internal pseudo-entity | |
| 2500 | (r"rn", "¯"), # ISOdia | |
| 2501 | (r"ru", "_"), # ISOnum | |
| 2502 | (r"sb", "⊂"), # ISOtech | |
| 2503 | (r"sc", "§"), # ISOnum | |
| 2504 | (r"sl", "/"), | |
| 2505 | (r"sp", "⊃"), # ISOtech | |
| 2506 | (r"sq", "▪"), # ISOpub | |
| 2507 | (r"sr", "√"), # ISOtech | |
| 2508 | (r"ts", "&sfgr;"), # ISOgrk1 | |
| 2509 | (r"ua", "↑"), # ISOnum | |
| 2510 | (r"ul", "_"), | |
| 2511 | (r"~=", "≅"), # ISOtech | |
| 2512 | ### Extended specials supported by groff; see groff_char(7). | |
| 2513 | # These are listed in the order they occur on that man page. | |
| 2507 | # groff/troff special characters. Listed in the order given on the | |
| 2508 | # groff_char(7) manual page. Characters from old troff are marked with | |
| 2509 | # a + in the comment. | |
| 2514 | 2510 | (r"-D", "Ð"), # ISOlat: Icelandic uppercase eth |
| 2515 | 2511 | (r"Sd", "ð"), # ISOlat1: Icelandic lowercase eth |
| 2516 | 2512 | (r"TP", "Þ"), # ISOlat1: Icelandic uppercase thorn |
| 2517 | 2513 | (r"Tp", "þ"), # ISOlat1: Icelandic lowercase thorn |
| 2518 | 2514 | (r"ss", "ß"), # ISOlat1 |
| 2519 | 2515 | ## Ligatures |
| 2520 | # ff, fi, fl, ffi, ffl from old troff go here | |
| 2516 | (r"ff", "ff"), # ISOpub + | |
| 2517 | (r"fi", "fi"), # ISOpub + | |
| 2518 | (r"fl", "fl"), # ISOpub + | |
| 2519 | (r"Fi", "ffi"), # ISOpub + | |
| 2520 | (r"Fl", "ffl"), # ISOpub + | |
| 2521 | 2521 | (r"AE", "Æ"), # ISOlat1 |
| 2522 | 2522 | (r"ae", "æ"), # ISOlat1 |
| 2523 | 2523 | (r"OE", "Œ"), # ISOlat2 |
| 2525 | 2525 | (r"IJ", "ij"), # ISOlat2: Dutch IJ ligature |
| 2526 | 2526 | (r"ij", "IJ"), # ISOlat2: Dutch ij ligature |
| 2527 | 2527 | (r".i", "ı"), # ISOlat2,ISOamso |
| 2528 | (r".j", "&jnodot;"), # ISOamso (undocumented but in 1.19) | |
| 2528 | (r".j", "&jnodot;"), # ISOamso | |
| 2529 | 2529 | ## Accented characters |
| 2530 | 2530 | (r"'A", "Á"), # ISOlat1 |
| 2531 | 2531 | (r"'C", "Ć"), # ISOlat2 |
| 2592 | 2592 | (r"oA", "Å"), # ISOlat1 |
| 2593 | 2593 | (r"oa", "å"), # ISOlat1 |
| 2594 | 2594 | # Accents |
| 2595 | (r"a\"","˝"), # ISOdia: double acute accent (Hungarian umlaut) | |
| 2595 | (r'a"', "˝"), # ISOdia: double acute accent (Hungarian umlaut) | |
| 2596 | 2596 | (r"a-", "¯"), # ISOdia: macron or bar accent |
| 2597 | 2597 | (r"a.", "˙"), # ISOdia: dot above |
| 2598 | 2598 | (r"a^", "ˆ"), # ISOdia: circumflex accent |
| 2599 | (r"aa", "´"), # ISOdia: acute accent | |
| 2600 | (r"ga", "`"), # ISOdia: grave accent | |
| 2599 | (r"aa", "´"), # ISOdia: acute accent + | |
| 2600 | (r"ga", "`"), # ISOdia: grave accent + | |
| 2601 | 2601 | (r"ab", "˘"), # ISOdia: breve accent |
| 2602 | 2602 | (r"ac", "¸"), # ISOdia: cedilla accent |
| 2603 | 2603 | (r"ad", "¨"), # ISOdia: umlaut or dieresis |
| 2614 | 2614 | (r"rq", "”"), # ISOpub |
| 2615 | 2615 | (r"oq", "‘"), # ISOnum: single open quote |
| 2616 | 2616 | (r"cq", "’"), # ISOnum: single closing quote (ASCII 39) |
| 2617 | (r"aq", "&zerosp;'"), # apostrophe quote | |
| 2617 | (r"aq", "''"), # apostrophe quote | |
| 2618 | 2618 | (r"dq", "\""), # double quote (ASCII 34) |
| 2619 | 2619 | (r"Fo", "«"), # ISOnum |
| 2620 | 2620 | (r"Fc", "»"), # ISOnum |
| 2623 | 2623 | ## Punctuation |
| 2624 | 2624 | (r"r!", "¡"), # ISOnum |
| 2625 | 2625 | (r"r?", "¿"), # ISOnum |
| 2626 | # Old troff \(em goes here | |
| 2626 | (r"em", "—"), # ISOpub + | |
| 2627 | 2627 | (r"en", "–"), # ISOpub: en dash |
| 2628 | # Old troff \(hy goes here | |
| 2628 | (r"hy", "‐"), # ISOnum + | |
| 2629 | 2629 | ## Brackets |
| 2630 | 2630 | (r"lB", "["), # ISOnum: left (square) bracket |
| 2631 | 2631 | (r"rB", "]"), # ISOnum: right (square) bracket |
| 2633 | 2633 | (r"rC", "}"), # ISOnum: right (curly) brace |
| 2634 | 2634 | (r"la", "⟨"), # ISOtech: left angle bracket |
| 2635 | 2635 | (r"ra", "⟩"), # ISOtech: right angle bracket |
| 2636 | # Old troff \(bv goes here | |
| 2637 | # FIXME: Bracket-pile characters from groff_char(7) in 1.19 go here. | |
| 2636 | (r"bv", "|"), # ISOnum + | |
| 2637 | # Bracket-piles. These are all | |
| 2638 | # internal pseudo-entities that we map to Unicode literals | |
| 2639 | # rather than ISO entities. | |
| 2640 | (r"braceex", "&braceex;"), | |
| 2641 | (r"bracketlefttp", "&bracketlefttp;"), | |
| 2642 | (r"bracketleftbt", "&bracketleftbt;"), | |
| 2643 | (r"bracketleftex", "&bracketleftex;"), | |
| 2644 | (r"bracketrighttp", "&bracketrighttp;"), | |
| 2645 | (r"bracketrightbt", "&bracketrightbt;"), | |
| 2646 | (r"bracketrightex", "&bracketrightex;"), | |
| 2647 | (r"lt", "&tlt;"), | |
| 2648 | (r"bracelefttp", "&tlt;"), | |
| 2649 | (r"lk", "&lk;"), | |
| 2650 | (r"braceleftmid", "&lk;"), | |
| 2651 | (r"lb", "&lb;"), | |
| 2652 | (r"braceleftbt", "&lb;"), | |
| 2653 | (r"braceleftex", "&braceleftex;"), | |
| 2654 | (r"rt", "&rt;"), | |
| 2655 | (r"bracerighttp", "&rt;"), | |
| 2656 | (r"rk", "&rk;"), | |
| 2657 | (r"bracerightmid", "&bracerightmid;"), | |
| 2658 | (r"rb", "&rb;"), | |
| 2659 | (r"bracerightbt", "&rb;"), | |
| 2660 | (r"bracerightex", "&bracerightex;"), | |
| 2661 | (r"parenlefttp", "&parenlefttp;"), | |
| 2662 | (r"parenleftbt", "&parenleftbt;"), | |
| 2663 | (r"parenleftex", "&parenleftex;"), | |
| 2664 | (r"parenrighttp", "&parenrighttp;"), | |
| 2665 | (r"parenrightbt", "&parenrightbt;"), | |
| 2666 | (r"parenrightex", "&parenrightex;"), | |
| 2638 | 2667 | ## Arrows |
| 2639 | # Old troff \(<- and \(-> go here | |
| 2668 | (r"<-", "←"), # ISOnum (XMLified) + | |
| 2669 | (r"->", "→"), # ISOnum (XMLified) + | |
| 2640 | 2670 | (r"<>", "↔"), # ISOamsa (XMLified) |
| 2641 | (r"da", "↓"), # ISOnum | |
| 2642 | (r"ua", "↑"), # ISOnum | |
| 2671 | (r"da", "↓"), # ISOnum + | |
| 2672 | (r"ua", "↑"), # ISOnum + | |
| 2673 | (r"va", "↕"), # ISOamsa | |
| 2643 | 2674 | (r"lA", "⇐"), # ISOtech |
| 2644 | 2675 | (r"rA", "⇒"), # ISOtech |
| 2645 | 2676 | (r"hA", "⇔"), # ISOtech: horizontal double-headed arrow |
| 2647 | 2678 | (r"uA", "⇑"), # ISOamsa |
| 2648 | 2679 | (r"vA", "⇕"), # ISOamsa: vertical double-headed double arrow |
| 2649 | 2680 | (r"an", "&an;"), # Internal pseudo-entity |
| 2650 | ## Lines | |
| 2651 | (r"-h", "ℏ"), # ISOamso: h-bar (Planck's constant) | |
| 2652 | # Old troff \(or goes here | |
| 2681 | # Lines | |
| 2653 | 2682 | (r"ba", "|"), # ISOnum |
| 2654 | # Old troff \(br, \(ru, \(ul, \(bv go here | |
| 2683 | (r"br", "│"), # ISObox + | |
| 2684 | (r"ul", "_"), # + | |
| 2685 | (r"rn", "¯"), # ISOdia + | |
| 2686 | (r"ru", "_"), # ISOnum + | |
| 2655 | 2687 | (r"bb", "¦"), # ISOnum |
| 2656 | (r"sl", "/"), | |
| 2688 | (r"sl", "/"), # + | |
| 2657 | 2689 | (r"rs", "\"), # ISOnum |
| 2658 | 2690 | ## Text markers |
| 2659 | 2691 | # Old troff \(ci, \(bu, \(dd, \(dg go here |
| 2692 | (r"ci", "○"), # ISOpub + | |
| 2693 | (r"bu", "•"), # ISOpub + | |
| 2694 | (r"dd", "‡"), # ISOpub + | |
| 2695 | (r"dg", "†"), # ISOpub + | |
| 2660 | 2696 | (r"lz", "◊"), # ISOpub |
| 2661 | # Old troff sq goes here | |
| 2697 | (r"sq", "▪"), # ISOpub + | |
| 2662 | 2698 | (r"ps", "¶"), # ISOnum: paragraph or pilcrow sign |
| 2663 | (r"sc", "§"), # ISOnum (in old troff) | |
| 2664 | # Old troff \(lh, \(rh go here | |
| 2699 | (r"sc", "§"), # ISOnum + | |
| 2700 | (r"lh", "&lh;"), # Internal pseudo-entity + | |
| 2701 | (r"rh", "&rh;"), # Internal pseudo-entity + | |
| 2665 | 2702 | (r"at", "@"), # ISOnum |
| 2666 | 2703 | (r"sh", "#"), # ISOnum |
| 2667 | 2704 | (r"CR", "&CR;"), # Internal pseudo-entity |
| 2668 | 2705 | (r"OK", "✓"), # ISOpub |
| 2669 | # Legalize | |
| 2670 | # Old troff \(co, \(rg go here | |
| 2706 | # Legal symbols | |
| 2707 | (r"co", "©"), # ISOnum + | |
| 2708 | (r"rg", "™"), # ISOnum + | |
| 2671 | 2709 | (r"tm", "™"), # ISOnum |
| 2710 | (r"bs", "☎"), # ISOpub (for the Bell logo) + | |
| 2672 | 2711 | # Currency symbols |
| 2673 | 2712 | (r"Do", "$"), # ISOnum |
| 2674 | (r"ct", "¢"), # ISOnum | |
| 2713 | (r"ct", "¢"), # ISOnum + | |
| 2675 | 2714 | (r"eu", "€"), |
| 2676 | 2715 | (r"Eu", "€"), |
| 2677 | 2716 | (r"Ye", "¥"), # ISOnum |
| 2678 | 2717 | (r"Po", "£"), # ISOnum |
| 2679 | 2718 | (r"Cs", "¤"), # ISOnum: currency sign |
| 2680 | (r"Fn", "&fnof"), # ISOtech | |
| 2719 | (r"Fn", "ƒ"), # ISOtech | |
| 2681 | 2720 | # Units |
| 2682 | # Old troff de goes here | |
| 2721 | (r"de", "°"), # ISOnum + | |
| 2683 | 2722 | (r"%0", "‰"), # ISOtech: per thousand, per mille sign |
| 2684 | # Old troff \(fm goes here | |
| 2723 | (r"fm", "′"), # ISOtech + | |
| 2685 | 2724 | (r"sd", "″"), # ISOtech |
| 2686 | 2725 | (r"mc", "µ"), # ISOnum |
| 2687 | 2726 | (r"Of", "ª"), # ISOnum |
| 2689 | 2728 | # Logical symbols |
| 2690 | 2729 | (r"AN", "∧"), # ISOtech |
| 2691 | 2730 | (r"OR", "∨"), # ISOtech |
| 2692 | # Old troff \(no goes here | |
| 2731 | (r"no", "¬"), # ISOnum + | |
| 2732 | (r"tno","¬"), # ISOnum | |
| 2693 | 2733 | (r"te", "∃"), # ISOtech: there exists, existential quantifier |
| 2694 | 2734 | (r"fa", "∀"), # ISOtech: for all, universal quantifier |
| 2695 | (r"st", "&bepsi"), # ISOamsr: such that | |
| 2735 | (r"st", "϶"), # ISOamsr: such that | |
| 2696 | 2736 | (r"3d", "∴"), # ISOtech |
| 2697 | 2737 | (r"tf", "∴"), # ISOtech |
| 2738 | (r"or", "|"), # ISOnum + | |
| 2698 | 2739 | # Mathematical symbols |
| 2699 | # Old troff "12", "14", "34" goes here | |
| 2740 | (r"12", "½"), # ISOnum + | |
| 2741 | (r"14", "¼"), # ISOnum + | |
| 2742 | (r"34", "¾"), # ISOnum + | |
| 2743 | (r"18", "⅛"), # ISOnum | |
| 2744 | (r"38", "⅜"), # ISOnum | |
| 2745 | (r"58", "⅝"), # ISOnum | |
| 2746 | (r"78", "⅞"), # ISOnum | |
| 2700 | 2747 | (r"S1", "¹"), # ISOnum |
| 2701 | 2748 | (r"S2", "²"), # ISOnum |
| 2702 | 2749 | (r"S3", "³"), # ISOnum |
| 2703 | # Old troff \(pl", \-, \(+- go here | |
| 2750 | (r"pl", "+"), # ISOnum + | |
| 2751 | (r"mi", "−"), # ISOtech + | |
| 2752 | (r"-+", "∓"), # ISOtech | |
| 2753 | (r"+-", "±"), # ISOnum + | |
| 2704 | 2754 | (r"t+-", "±"), # ISOnum |
| 2705 | (r"-+", "∓"), # ISOtech | |
| 2706 | 2755 | (r"pc", "·"), # ISOnum |
| 2707 | 2756 | (r"md", "·"), # ISOnum |
| 2708 | # Old troff \(mu goes here | |
| 2757 | (r"mu", "×"), # ISOnum + | |
| 2709 | 2758 | (r"tmu", "×"), # ISOnum |
| 2710 | 2759 | (r"c*", "⊗"), # ISOamsb: multiply sign in a circle |
| 2711 | 2760 | (r"c+", "⊕"), # ISOamsb: plus sign in a circle |
| 2712 | # Old troff \(di goes here | |
| 2761 | (r"di", "÷"), # ISOnum + | |
| 2713 | 2762 | (r"tdi", "÷"), # ISOnum |
| 2714 | 2763 | (r"f/", "―"), # ISOnum: horizintal bar for fractions |
| 2715 | # Old troff \(** goes here | |
| 2716 | (r"<=", "≤"), # ISOtech (XMLified) | |
| 2717 | (r">=", "≥"), # ISOtech (XMLified) | |
| 2764 | (r"**", "∗"), # ISOtech + | |
| 2765 | (r"<=", "≤"), # ISOtech (XMLified) + | |
| 2766 | (r">=", "≥"), # ISOtech (XMLified) + | |
| 2718 | 2767 | (r"<<", "≪"), # ISOamsr (XMLified) |
| 2719 | 2768 | (r">>", "≫"), # ISOamsr (XMLified) |
| 2720 | (r"!=", "≠"), # ISOtech | |
| 2721 | # Old troff \(eq and \(== go here | |
| 2769 | (r"!=", "≠"), # ISOtech + | |
| 2770 | (r"==", "≡"), # ISOtech + | |
| 2771 | (r"ne", "≢"), # ISOamsn | |
| 2722 | 2772 | (r"=~", "≅"), # ISOamsr |
| 2723 | # Old troff \(ap goes here | |
| 2773 | (r"|=", "≈"), # ISOamsr + | |
| 2774 | (r"ap", "∼"), # ISOtech + | |
| 2724 | 2775 | (r"~~", "≈"), # ISOtech |
| 2725 | # This appears to be an error in the groff table. | |
| 2726 | # It clashes with the Bell Labs use of ~= for a congruence sign | |
| 2727 | # (r"~=", "≈"), # ISOamsr | |
| 2728 | # Old troff \(pt, \(es, \(mo go here | |
| 2776 | (r"pt", "∝"), # ISOtech + | |
| 2777 | (r"es", "∅"), # ISOamso + | |
| 2778 | (r"mo", "∈"), # ISOtech + | |
| 2729 | 2779 | (r"nm", "∉"), # ISOtech |
| 2780 | (r"sb", "⊂"), # ISOtech + | |
| 2730 | 2781 | (r"nb", "⊄"), # ISOamsr |
| 2782 | (r"sp", "⊃"), # ISOtech + | |
| 2731 | 2783 | (r"nc", "⊅"), # ISOamsn |
| 2732 | (r"ne", "≢"), # ISOamsn | |
| 2733 | # Old troff \(sb, \(sp, \(ib, \(ip, \(ca, \(cu go here | |
| 2784 | (r"ib", "⊆"), # ISOtech + | |
| 2785 | (r"ip", "⊇"), # ISOtech + | |
| 2786 | (r"ca", "∩"), # ISOtech + | |
| 2787 | (r"cu", "∪"), # ISOtech + | |
| 2734 | 2788 | (r"/_", "∠"), # ISOamso |
| 2735 | 2789 | (r"pp", "⊥"), # ISOtech |
| 2736 | # Old troff \(is goes here | |
| 2790 | (r"is", "∫"), # ISOtech | |
| 2791 | (r"integral", "∫"), # ISOtech | |
| 2737 | 2792 | (r"sum", "∑"), # ISOamsb |
| 2738 | 2793 | (r"product", "∏"), # ISOamsb |
| 2739 | (r"gr", "∇"), # ISOtech | |
| 2740 | # Old troff \(sr. \(rn, \(if go here | |
| 2794 | (r"coproduct", "∐"), # ISOamsb | |
| 2795 | (r"gr", "∇"), # ISOtech + | |
| 2796 | (r"sr", "√"), # ISOtech + | |
| 2797 | (r"sqrt", "√"), # ISOtech | |
| 2798 | (r"radicalex", "&radicalex;"), # Internal pseudo-entity | |
| 2799 | (r"sqrtex", "&sqrtex;"), # Internal pseudo-entity | |
| 2800 | (r"lc", "&lc;"), # Internal pseudo-entity + | |
| 2801 | (r"rc", "&rc;"), # Internal pseudo-entity + | |
| 2802 | (r"lf", "&lf;"), # Internal pseudo-entity + | |
| 2803 | (r"rf", "&rf;"), # Internal pseudo-entity + | |
| 2804 | (r"if", "∞"), # ISOtech + | |
| 2741 | 2805 | (r"Ah", "ℵ"), # ISOtech |
| 2742 | 2806 | (r"Im", "ℑ"), # ISOamso: Fraktur I, imaginary |
| 2743 | 2807 | (r"Re", "ℜ"), # ISOamso: Fraktur R, real |
| 2744 | 2808 | (r"wp", "℘"), # ISOamso |
| 2745 | 2809 | (r"pd", "∂"), # ISOtech: partial differentiation sign |
| 2746 | # Their table duplicates the Greek letters here. | |
| 2747 | # We list only the variant forms here, mapping them into | |
| 2748 | # the ISO Greek 4 variants (which may or may not be correct :-() | |
| 2810 | (r"-h", "ℏ"), # ISOamso: h-bar (Planck's constant) + | |
| 2811 | (r"hbar","ℏ"), # ISOamso: h-bar (Planck's constant) | |
| 2812 | # Greek glyphs | |
| 2813 | (r"*A", "&Agr;"), # ISOgrk1 + | |
| 2814 | (r"*B", "&Bgr;"), # ISOgrk1 + | |
| 2815 | (r"*G", "&Ggr;"), # ISOgrk1 + | |
| 2816 | (r"*D", "&Dgr;"), # ISOgrk1 + | |
| 2817 | (r"*E", "&Egr;"), # ISOgrk1 + | |
| 2818 | (r"*Z", "&Zgr;"), # ISOgrk1 + | |
| 2819 | (r"*Y", "&EEgr;"), # ISOgrk1 + | |
| 2820 | (r"*H", "&THgr;"), # ISOgrk1 + | |
| 2821 | (r"*I", "&Igr;"), # ISOgrk1 + | |
| 2822 | (r"*K", "&Kgr;"), # ISOgrk1 + | |
| 2823 | (r"*L", "&Lgr;"), # ISOgrk1 + | |
| 2824 | (r"*M", "&Mgr;"), # ISOgrk1 + | |
| 2825 | (r"*N", "&Ngr;"), # ISOgrk1 + | |
| 2826 | (r"*C", "Ξ"), # ISOgrk1 + | |
| 2827 | (r"*O", "&Ogr;"), # ISOgrk1 + | |
| 2828 | (r"*P", "&Pgr;"), # ISOgrk1 + | |
| 2829 | (r"*R", "&Rgr;"), # ISOgrk1 + | |
| 2830 | (r"*S", "&Sgr;"), # ISOgrk1 + | |
| 2831 | (r"*T", "&Tgr;"), # ISOgrk1 + | |
| 2832 | (r"*U", "&Ugr;"), # ISOgrk1 + | |
| 2833 | (r"*F", "&PHgr;"), # ISOgrk1 + | |
| 2834 | (r"*X", "&KHgr;"), # ISOgrk1 + | |
| 2835 | (r"*Q", "&PSgr;"), # ISOgrk1 + | |
| 2836 | (r"*W", "&OHgr;"), # ISOgrk1 + | |
| 2837 | (r"*W", "&OHgr;"), # ISOgrk1 + | |
| 2838 | (r"*a", "&agr;"), # ISOgrk1 + | |
| 2839 | (r"*b", "&bgr;"), # ISOgrk1 + | |
| 2840 | (r"*g", "&ggr;"), # ISOgrk1 + | |
| 2841 | (r"*d", "&dgr;"), # ISOgrk1 + | |
| 2842 | (r"*e", "&egr;"), # ISOgrk1 + | |
| 2843 | (r"*z", "&zgr;"), # ISOgrk1 + | |
| 2844 | (r"*y", "&eegr;"), # ISOgrk1 + | |
| 2845 | (r"*h", "&thgr;"), # ISOgrk1 + | |
| 2846 | (r"*i", "&igr;"), # ISOgrk1 + | |
| 2847 | (r"*k", "&kgr;"), # ISOgrk1 + | |
| 2848 | (r"*l", "&lgr;"), # ISOgrk1 + | |
| 2849 | (r"*m", "&mgr;"), # ISOgrk1 + | |
| 2850 | (r"*n", "&ngr;"), # ISOgrk1 + | |
| 2851 | (r"*c", "ξ"), # ISOgrk1 + | |
| 2852 | (r"*o", "&ogr;"), # ISOgrk1 + | |
| 2853 | (r"*p", "&pgr;"), # ISOgrk1 + | |
| 2854 | (r"*r", "&rgr;"), # ISOgrk1 + | |
| 2855 | (r"ts", "&sfgr;"), # ISOgrk1 + | |
| 2856 | (r"*s", "&sgr;"), # ISOgrk1 + | |
| 2857 | (r"*t", "&tgr;"), # ISOgrk1 + | |
| 2858 | (r"*u", "&ugr;"), # ISOgrk1 + | |
| 2859 | (r"*f", "&phgr;"), # ISOgrk1 + | |
| 2860 | (r"*x", "&khgr;"), # ISOgrk1 + | |
| 2861 | (r"*q", "&psgr;"), # ISOgrk1 + | |
| 2862 | (r"*w", "&ohgr;"), # ISOgrk1 + | |
| 2863 | (r"+h", "&b.thetas;"), # ISOgrk4: variant theta | |
| 2749 | 2864 | (r"+f", "&b.phiv;"), # ISOgrk4: variant phi |
| 2750 | (r"+h", "&b.thetas;"), # ISOgrk4: variant theta | |
| 2751 | 2865 | (r"+p", "&b.omega;"), # ISOgrk4: variant pi, looking like omega |
| 2866 | (r"+e", "&b.epsiv;"), # ISOgrk4: variant epsilon | |
| 2752 | 2867 | # Card symbols |
| 2753 | 2868 | (r"CL", "♣"), # ISOpub: club suit |
| 2754 | 2869 | (r"SP", "♠"), # ISOpub: spade suit |
| 2755 | 2870 | (r"HE", "♥"), # ISOpub: heart suit |
| 2871 | # u2661 is listed at this point in the groff table | |
| 2756 | 2872 | (r"DI", "♦"), # ISOpub: diamond suit |
| 2757 | # Handle some cases of \o here. | |
| 2873 | # u2662 is listed at this point in the groff table | |
| 2874 | # Classic troff special characters not in groff | |
| 2875 | (r"%", "­"), # ISOnum | |
| 2876 | (r"'", "´"), # ISOdia | |
| 2877 | (r"bl", "&phonexb;"), # ISOpub | |
| 2878 | (r"eq", "="), # ISOnum | |
| 2879 | (r"ge", "≥"), # ISOtech | |
| 2880 | (r"le", "≤"), # ISOtech | |
| 2881 | (r"~=", "≅"), # ISOamsr | |
| 2758 | 2882 | # This is a mechanically hacked copy of the "Accented characters" |
| 2759 | 2883 | # table section above. Note, letters followed by ' have been |
| 2760 | 2884 | # omitted because that's the troff string delimiter. |
| 2853 | 2977 | self.groff_features = [] |
| 2854 | 2978 | self.nonportable_features = [] |
| 2855 | 2979 | self.entities_from_strings = False |
| 2980 | self.ignore_outdent = None | |
| 2856 | 2981 | self.registers = { # Register table for nr, rr, rnn |
| 2857 | ".g": "0", | |
| 2858 | ".$": lambda: `len(filter(lambda x: x, self.macroargs and self.macroargs[-1]))`, | |
| 2982 | ".g": '0', | |
| 2983 | ".$": lambda: str(len(filter(lambda x: x, self.macroargs and self.macroargs[-1]))), | |
| 2859 | 2984 | ".T": "XML-DocBook", |
| 2860 | 2985 | } |
| 2861 | 2986 | TroffInterpreter.translations = {} |
| 2879 | 3004 | "Expand strings in the given line." |
| 2880 | 3005 | if '\\' not in line: |
| 2881 | 3006 | return line |
| 3007 | # Expand all known strings | |
| 2882 | 3008 | for (key, value) in self.strings.items(): |
| 2883 | 3009 | line = line.replace(r"\*["+key+"]", value) |
| 2884 | 3010 | if len(key) == 1: |
| 2885 | 3011 | line = line.replace(r"\*"+key, value) |
| 2886 | 3012 | elif len(key) == 2: |
| 2887 | 3013 | line = line.replace(r"\*("+key, value) |
| 3014 | # Expand unknown strings as empty | |
| 3015 | line = re.sub(r"\\\*[a-zA-Z]", "", line) | |
| 3016 | line = re.sub(r"\\\*\([a-zA-Z][a-zA-Z]", "", line) | |
| 2888 | 3017 | # Maybe we're in a macro eval? |
| 2889 | 3018 | if self.macroargs: |
| 2890 | 3019 | for argnum in range(1, 9): |
| 2891 | 3020 | line = line.replace(r"\$%d" % argnum, self.macroargs[-1][argnum-1]) |
| 2892 | line = line.replace("\$*", " ".join(self.macroargs[-1])) | |
| 2893 | line = line.replace("\$@", " ".join(map(lambda s: '"%s"' % s, self.macroargs[-1]))) | |
| 3021 | line = line.replace(r"\$*", " ".join(self.macroargs[-1])) | |
| 3022 | line = line.replace(r"\$@", " ".join(map(lambda s: '"%s"' % s, self.macroargs[-1]))) | |
| 2894 | 3023 | return line |
| 2895 | 3024 | |
| 2896 | 3025 | def eval_register(self, key): |
| 2900 | 3029 | else: |
| 2901 | 3030 | return apply(val) |
| 2902 | 3031 | |
| 2903 | def eval_expr(self, exp): | |
| 2904 | "Evaluate expressions for use in groff conditionals." | |
| 2905 | if macro_verbosity in self.source.verbose: | |
| 2906 | self.evaldepth += " " | |
| 2907 | self.source.notify("%s->eval_expr(%s)" % (self.evaldepth, exp)) | |
| 3032 | def eval_term(self, exp): | |
| 3033 | "Pop a term off an expression string and evaluate it." | |
| 2908 | 3034 | if exp == "": |
| 2909 | v = exp | |
| 2910 | # Accept ! prefix | |
| 2911 | elif exp[0] == "!": | |
| 2912 | v = self.eval_expr(exp[1:]) | |
| 2913 | v = `len(v) and v != '0'` | |
| 3035 | return ("", "") | |
| 2914 | 3036 | # Evaluate built-in conditions |
| 2915 | 3037 | elif exp[0] == 'n': |
| 2916 | v = "1"+self.eval_expr(exp[1:]) # We're an nroff-like device | |
| 3038 | return ("1", exp[1:]) # We're an nroff-like device | |
| 2917 | 3039 | elif exp[0] == 't': |
| 2918 | v = "0"+self.eval_expr(exp[1:]) # Not a troff-like device | |
| 3040 | return ("0", exp[1:]) # Not a troff-like device | |
| 2919 | 3041 | elif exp[0] == 'o': |
| 2920 | v = "1"+self.eval_expr(exp[1:]) # Forever on page 1 | |
| 3042 | return ("1", exp[1:]) # Forever on page 1 | |
| 2921 | 3043 | elif exp[0] == 'e': |
| 2922 | v = "0"+self.eval_expr(exp[1:]) # No page breaks | |
| 3044 | return ("0", exp[1:]) # No page breaks | |
| 2923 | 3045 | elif exp[0] == 'v': |
| 2924 | v = "0"+self.eval_expr(exp[1:]) # This isn't vroff either | |
| 3046 | return ("0", exp[1:]) # This isn't vroff either | |
| 3047 | elif exp[0] == "m": | |
| 3048 | return ("0", exp[1:]) # We are colorless, alas | |
| 3049 | elif exp[0] == "r": | |
| 3050 | exp = exp[1:] | |
| 3051 | if ')' in exp: | |
| 3052 | regname = exp[:exp.find(')')] | |
| 3053 | tail = exp[exp.find(')'):] | |
| 3054 | else: | |
| 3055 | regname = exp | |
| 3056 | tail = "" | |
| 3057 | if regname in self.registers: | |
| 3058 | return ("1", tail) | |
| 3059 | else: | |
| 3060 | return ("0", tail) | |
| 2925 | 3061 | elif exp[0] == 'c': |
| 2926 | 3062 | # This ring-around-the-rosy is necessary to defeat some |
| 2927 | 3063 | # machinery that groff uses to define tty graphics. We |
| 2948 | 3084 | glyph = r"\[" + glyph + "]" |
| 2949 | 3085 | for interpreter in self.source.interpreters: |
| 2950 | 3086 | if glyph in interpreter.translations: |
| 2951 | v = self.eval_expr("1"+self.eval_expr(exp)) | |
| 3087 | return ("1", exp[len(glyph):]) | |
| 2952 | 3088 | else: |
| 2953 | v = self.eval_expr("0"+self.eval_expr(exp)) | |
| 2954 | # Evaluate numeric registers with two-character names | |
| 2955 | elif exp.startswith(r"\n("): | |
| 2956 | if exp[3:5] in self.registers: | |
| 2957 | val = self.eval_register(exp[3:5]) | |
| 2958 | else: | |
| 2959 | val = "0" | |
| 2960 | v = self.eval_expr(val+exp[5:]) | |
| 2961 | # Evaluate a groff named register | |
| 2962 | elif exp.startswith(r"\n[") and exp.find("]") > 4: | |
| 2963 | end = exp.find("]") | |
| 2964 | register = exp[3:end] | |
| 3089 | return ("0", exp[len(glyph):]) | |
| 3090 | # Treat dEQ and dEN as always defined, because we're only going | |
| 3091 | # to encounter them in inclusions generated by eqn because | |
| 3092 | # of an EQ/EN. | |
| 3093 | elif exp[:2] in ("dEQ", "dEN"): | |
| 3094 | return ("1", exp[1:]) | |
| 3095 | elif exp[0] == "d": | |
| 3096 | # Supposed to be true if there's a "string, macro, diversion, | |
| 3097 | # or request" with the specified name. We ignore diversions. | |
| 3098 | # Alas, since there's no list of requests anywhere we're | |
| 3099 | # going to lose if that case is ever used; fortunately it | |
| 3100 | # doesn't seem to be. | |
| 3101 | if ')' in exp: | |
| 3102 | name = exp[:exp.find(')')] | |
| 3103 | tail = exp[exp.find(')'):] | |
| 3104 | else: | |
| 3105 | name = exp | |
| 3106 | tail = "" | |
| 3107 | if name in self.strings or exp[1:] in self.macros: | |
| 3108 | return ("1", tail) | |
| 3109 | else: | |
| 3110 | return ("0", tail) | |
| 3111 | # Evaluate numeric registers | |
| 3112 | elif exp.startswith(r"\n"): | |
| 3113 | exp = exp[2:] | |
| 3114 | increment = None | |
| 3115 | if exp[0] == '+': | |
| 3116 | increment = 1 | |
| 3117 | exp = exp[1:] | |
| 3118 | elif exp[0] == '-': | |
| 3119 | increment = -1 | |
| 3120 | exp = exp[1:] | |
| 3121 | # ...with two-character names | |
| 3122 | if exp[0] == '(': | |
| 3123 | end = 3 | |
| 3124 | register = exp[1:3] | |
| 3125 | # ...with longnames | |
| 3126 | elif exp[0] == '[': | |
| 3127 | end = exp.find("]")+1 | |
| 3128 | register = exp[1:end-1] | |
| 3129 | # ...with one-character names | |
| 3130 | else: | |
| 3131 | end = 1 | |
| 3132 | register = exp[0] | |
| 2965 | 3133 | if register in self.registers: |
| 2966 | val = self.eval_register(register) | |
| 2967 | else: | |
| 2968 | val = "0" | |
| 2969 | v = self.eval_expr(val+exp[end+1:]) | |
| 2970 | elif exp.startswith(r"\n"): | |
| 2971 | if exp[2] in self.registers: | |
| 2972 | val = self.eval_register(exp[2]) | |
| 2973 | else: | |
| 2974 | val = "0" | |
| 2975 | v = self.eval_expr(val+exp[3:]) | |
| 3134 | if increment is not None: | |
| 3135 | self.registers[register] = str(int(self.eval_register(register)) + increment) | |
| 3136 | return (self.eval_register(register), exp[end:]) | |
| 3137 | else: | |
| 3138 | if increment is not None: | |
| 3139 | self.registers[register] = str(increment) | |
| 3140 | return ("0", exp[end:]) | |
| 2976 | 3141 | # Half-assed job of evaluating \w, without the side effects. |
| 2977 | 3142 | # Our 'basic units' are the width of a monospace character |
| 2978 | 3143 | elif exp.startswith(r"\w"): |
| 2979 | 3144 | e = exp[3:].find(exp[2])+3 |
| 2980 | 3145 | istr = exp[3:e] |
| 3146 | if istr in self.strings: | |
| 3147 | istr = self.strings[istr] | |
| 3148 | elif istr.startswith(r"\*("): | |
| 3149 | istr = "" | |
| 2981 | 3150 | entity = None |
| 2982 | 3151 | val = 0 |
| 2983 | 3152 | for c in istr: |
| 3001 | 3170 | }.get(entity, 1) |
| 3002 | 3171 | entity = None |
| 3003 | 3172 | #self.source.warning("%s evaluated to %d" % (exp[:e+1], val)) |
| 3004 | v = self.eval_expr(`val`+exp[e+1:]) | |
| 3173 | return (`val`, exp[e+1:]) | |
| 3005 | 3174 | # Numeric literal may stand alone or be followed by an operator |
| 3006 | 3175 | elif exp[0] in '-0123456789': |
| 3007 | 3176 | v = "" |
| 3015 | 3184 | expcopy = expcopy[1:] |
| 3016 | 3185 | else: |
| 3017 | 3186 | break |
| 3018 | if expcopy: | |
| 3019 | # Look for an operator | |
| 3020 | if expcopy.startswith("=="): | |
| 3021 | v = `int(int(v) == int(self.eval_expr(expcopy[2:])))` | |
| 3022 | elif expcopy.startswith("+"): | |
| 3023 | v = `int(v) + int(self.eval_expr(expcopy[1:]))` | |
| 3024 | elif expcopy.startswith("*"): | |
| 3025 | v = `int(v) * int(self.eval_expr(expcopy[1:]))` | |
| 3026 | elif expcopy.startswith("-"): | |
| 3027 | v = `int(v) - int(self.eval_expr(expcopy[1:]))` | |
| 3028 | elif expcopy.startswith("/"): | |
| 3029 | v = `int(v) / int(self.eval_expr(expcopy[1:]))` | |
| 3030 | elif expcopy.startswith("%"): | |
| 3031 | v = `int(v) % int(self.eval_expr(expcopy[1:]))` | |
| 3032 | elif expcopy.startswith("="): | |
| 3033 | v = `int(int(v) == int(self.eval_expr(expcopy[1:])))` | |
| 3034 | elif expcopy.startswith(">="): | |
| 3035 | v = `int(int(v) >= int(self.eval_expr(expcopy[5:])))` | |
| 3036 | elif expcopy.startswith("<="): | |
| 3037 | v = `int(int(v) <= int(self.eval_expr(expcopy[5:])))` | |
| 3038 | elif expcopy.startswith(">?"): | |
| 3039 | v = `int(max(v, int(self.eval_expr(expcopy[5:]))))` | |
| 3040 | elif expcopy.startswith("<?"): | |
| 3041 | v = `int(min(v, int(self.eval_expr(expcopy[5:]))))` | |
| 3042 | elif expcopy.startswith(">"): | |
| 3043 | v = `int(int(v) > int(self.eval_expr(expcopy[4:])))` | |
| 3044 | elif expcopy.startswith("<"): | |
| 3045 | v = `int(int(v) < int(self.eval_expr(expcopy[4:])))` | |
| 3046 | elif expcopy.startswith("&"): | |
| 3047 | v = `int(v) & int(self.eval_expr(expcopy[1:]))` | |
| 3048 | elif expcopy.startswith(":"): | |
| 3049 | v = `int(v) | int(self.eval_expr(expcopy[1:]))` | |
| 3050 | else: | |
| 3051 | self.source.error('unknown operator %s in %s' % (expcopy, exp)) | |
| 3187 | return (v, expcopy) | |
| 3052 | 3188 | # Some groff pages actually use this! |
| 3053 | 3189 | elif exp.startswith(r"\B'") and "'" in exp[3:]: |
| 3054 | 3190 | self.groff_features.append(r"\B") |
| 3055 | 3191 | end = 3 + exp[3:].find("'") |
| 3056 | 3192 | if re.compile("[0-9]+$").match(exp[3:end]): |
| 3057 | v = '1' | |
| 3058 | else: | |
| 3059 | v = '0' | |
| 3193 | return ('1', exp[:end+1]) | |
| 3194 | else: | |
| 3195 | return ('0', exp[:end+1]) | |
| 3060 | 3196 | # Could be a string comparison |
| 3061 | 3197 | elif exp.count(exp[0]) >= 3: |
| 3062 | 3198 | count = 0 |
| 3068 | 3204 | remainder = exp[i+1:] |
| 3069 | 3205 | exp = exp[:i] |
| 3070 | 3206 | expparts = exp[1:].split(exp[0]) |
| 3071 | v = self.eval_expr(`int(expparts[0]==expparts[1])`+remainder) | |
| 3072 | # We don't know what's going on, just call it true. | |
| 3207 | return (`int(expparts[0]==expparts[1])`, remainder) | |
| 3208 | # Maybe it's a parenthesized expression | |
| 3209 | elif exp[0] == '(': | |
| 3210 | end = exp.find(')') | |
| 3211 | if end == -1: | |
| 3212 | self.source.error("unterminated parenthetical %s" % exp) | |
| 3213 | return (self.eval_expr(exp[1:end]), exp[end+1:]) | |
| 3214 | # Maybe we couldn't do anything with it. | |
| 3073 | 3215 | else: |
| 3074 | self.source.error("bogus-looking expression %s" % exp) | |
| 3075 | v = '1' | |
| 3216 | return ("", exp) | |
| 3217 | ||
| 3218 | def eval_expr(self, exp): | |
| 3219 | "Evaluate expressions for use in groff conditionals." | |
| 3076 | 3220 | if macro_verbosity in self.source.verbose: |
| 3077 | self.source.notify("%s<-eval_expr(%s) -> %s, %s" % (self.evaldepth, exp, v, type(v))) | |
| 3221 | self.evaldepth += " " | |
| 3222 | self.source.notify("%s->eval_expr(%s)" % (self.evaldepth, exp)) | |
| 3223 | # Accept ! prefix | |
| 3224 | if exp and exp[0] == "!": | |
| 3225 | v = self.eval_expr(exp[1:]) | |
| 3226 | v = str(len(v)==0 or v == '0') | |
| 3227 | else: | |
| 3228 | # Expression can consist of a single term only | |
| 3229 | (head, tail) = self.eval_term(exp) | |
| 3230 | if macro_verbosity in self.source.verbose: | |
| 3231 | self.source.notify("%s(hd, tail)=(%s, %s)" % (self.evaldepth,head, tail)) | |
| 3232 | if tail == "": | |
| 3233 | v = head | |
| 3234 | # Arithmetic | |
| 3235 | elif tail.startswith("+"): | |
| 3236 | v = `int(head) + int(self.eval_expr(tail[1:]))` | |
| 3237 | elif tail.startswith("-"): | |
| 3238 | v = `int(head) - int(self.eval_expr(tail[1:]))` | |
| 3239 | elif tail.startswith("*"): | |
| 3240 | v = `int(head) * int(self.eval_expr(tail[1:]))` | |
| 3241 | elif tail.startswith("/"): | |
| 3242 | v = `int(head) / int(self.eval_expr(tail[1:]))` | |
| 3243 | elif tail.startswith("%"): | |
| 3244 | v = `int(head) % int(self.eval_expr(tail[1:]))` | |
| 3245 | # Logical operators | |
| 3246 | elif tail.startswith("&"): | |
| 3247 | v = `int(int(head) and int(self.eval_expr(tail[5:])))` | |
| 3248 | elif tail.startswith(":"): | |
| 3249 | v = `int(int(head) or int(self.eval_expr(tail[5:])))` | |
| 3250 | # Relationals | |
| 3251 | elif tail.startswith("=="): | |
| 3252 | v = `int(int(head) == int(self.eval_expr(tail[2:])))` | |
| 3253 | elif tail.startswith("="): | |
| 3254 | v = `int(int(head) == int(self.eval_expr(tail[1:])))` | |
| 3255 | elif tail.startswith(">"): | |
| 3256 | v = `int(int(head) > int(self.eval_expr(tail[4:])))` | |
| 3257 | elif tail.startswith("<"): | |
| 3258 | v = `int(int(head) < int(self.eval_expr(tail[4:])))` | |
| 3259 | elif tail.startswith(">="): | |
| 3260 | v = `int(int(head) >= int(self.eval_expr(tail[5:])))` | |
| 3261 | elif tail.startswith("<="): | |
| 3262 | v = `int(int(head) <= int(self.eval_expr(tail[5:])))` | |
| 3263 | # Max/min | |
| 3264 | elif tail.startswith(">?"): | |
| 3265 | v = `max(int(head), int(self.eval_expr(tail[5:])))` | |
| 3266 | elif tail.startswith("<?"): | |
| 3267 | v = `min(int(head), int(self.eval_expr(tail[5:])))` | |
| 3268 | # We don't know what's going on, just call it true. | |
| 3269 | else: | |
| 3270 | self.source.error("bogus-looking expression %s" % exp) | |
| 3271 | v = '1' | |
| 3272 | if macro_verbosity in self.source.verbose: | |
| 3273 | self.source.notify("%s<-eval_expr(%s) -> %s" % (self.evaldepth, exp, v)) | |
| 3078 | 3274 | self.evaldepth = self.evaldepth[:-1] |
| 3079 | 3275 | return v |
| 3080 | 3276 | |
| 3097 | 3293 | if macro_verbosity in self.verbose: |
| 3098 | 3294 | self.source.notify("skiptoend(%s) finished" % `tokens`) |
| 3099 | 3295 | |
| 3100 | def interpret(self, line, tokens, caller_unused): | |
| 3296 | def interpret(self, line, tokens, _): | |
| 3101 | 3297 | command = tokens[0][1:] |
| 3102 | 3298 | args = tokens[1:] |
| 3299 | if len(command) > 2: | |
| 3300 | self.nonportable_features.append(command) | |
| 3103 | 3301 | # .nl is apparently an undocumented synonym for .br in groff(1). |
| 3104 | 3302 | if command == "br" or command == "nl": |
| 3105 | 3303 | if self.source.in_synopsis(): |
| 3109 | 3307 | elif command == "ti": |
| 3110 | 3308 | if self.source.in_synopsis(): |
| 3111 | 3309 | pass |
| 3112 | else: | |
| 3113 | self.source.warning(".ti seen in body section") | |
| 3310 | elif self.source.troff.macronames: | |
| 3311 | self.source.warning(".ti seen in macro body") | |
| 3114 | 3312 | self.source.passthrough([command] + args) |
| 3313 | elif self.source.peekline().startswith("."): | |
| 3314 | self.source.warning(".ti with following command") | |
| 3315 | self.source.passthrough([command] + args) | |
| 3316 | else: | |
| 3317 | if args[0].startswith("-"): | |
| 3318 | self.source.warning(".ti with negative indent.") | |
| 3319 | self.source.emit("<blockquote remap='.ti'><para>") | |
| 3320 | self.source.emit(self.source.popline()) | |
| 3321 | self.source.emit("</para></blockquote>") | |
| 3115 | 3322 | elif command == "in": |
| 3116 | 3323 | if self.source.in_synopsis(): |
| 3117 | 3324 | pass |
| 3325 | # Some .in pairs associated with displays can be ignored | |
| 3326 | elif self.source.troff.nf and args and self.ignore_outdent is None: | |
| 3327 | self.ignore_outdent = args[0] | |
| 3328 | elif self.ignore_outdent is not None: | |
| 3329 | if not args: | |
| 3330 | pass # bare .in outdenting a display | |
| 3331 | elif args[0][0]=='-' and args[0][1:]==self.ignore_outdent[1:]: | |
| 3332 | pass # matching outdent | |
| 3333 | else: | |
| 3334 | self.source.warning("closing .in doesn't match opener") | |
| 3335 | self.source.passthrough([command] + args) | |
| 3336 | self.ignore_outdent = None | |
| 3118 | 3337 | else: |
| 3119 | 3338 | self.source.warning(".in seen in body section") |
| 3120 | 3339 | self.source.passthrough([command] + args) |
| 3163 | 3382 | self.source.diversion.append("") |
| 3164 | 3383 | if self.source.body_section() and not self.nf: |
| 3165 | 3384 | self.source.need_para = True |
| 3385 | elif command == "Sp" and "Sp" not in self.longnames: | |
| 3386 | # Catches a common error. See for example mono.1 | |
| 3387 | self.source.pushline(".sp") | |
| 3166 | 3388 | elif command == "bp": |
| 3167 | 3389 | self.nonportable_features.append("bp") |
| 3168 | 3390 | if self.nf: |
| 3180 | 3402 | # which frequently occur in attemps to simulate .DS/.DE and |
| 3181 | 3403 | # are going to turn into <para><emphasis remap="CW"></para> |
| 3182 | 3404 | # which is guaranteed to lose because the scope of <emphasis> |
| 3183 | # can't cross a paragraph boundary. So just swap these... | |
| 3405 | # can't cross a paragraph boundary. To fix this we | |
| 3406 | # must swap the .ft and .nf... | |
| 3184 | 3407 | if args and args[0]!="R" and self.source.peekline(): |
| 3185 | 3408 | # skip any number of things like .in |
| 3186 | 3409 | while self.source.ignorable(self.source.peekline(), nocomplaints=1): |
| 3191 | 3414 | if self.source.quiet: |
| 3192 | 3415 | trailer = "" |
| 3193 | 3416 | else: |
| 3194 | trailer = ' remap=".nf"' | |
| 3417 | trailer = ' remap=".ft %s .nf"' % args[0] | |
| 3195 | 3418 | self.source.emit("<literallayout%s>" % trailer) |
| 3196 | 3419 | self.nf = True |
| 3197 | 3420 | # The actual highlight change |
| 3209 | 3432 | # .in +4n |
| 3210 | 3433 | # .ft |
| 3211 | 3434 | # have to be inverted. |
| 3435 | fontswitch = "" | |
| 3212 | 3436 | if self.source.peekline(): |
| 3213 | 3437 | while blankline.match(self.source.peekline()): |
| 3214 | 3438 | self.source.popline() |
| 3215 | 3439 | while self.source.ignorable(self.source.peekline(), nocomplaints=1): |
| 3216 | 3440 | self.source.emit(make_comment(self.source.popline())) |
| 3217 | 3441 | nextl = self.source.peekline() |
| 3218 | if nextl and next[0:3] == TroffInterpreter.ctrl + "ft": | |
| 3442 | if nextl and nextl[0:3] == TroffInterpreter.ctrl + "ft": | |
| 3443 | fontswitch = nextl | |
| 3219 | 3444 | cmd = lineparse(self.source.popline()) |
| 3220 | 3445 | if len(cmd) == 1: |
| 3221 | 3446 | self.source.emit(r"\fR") |
| 3225 | 3450 | # Because emphasis can't cross a block-layout boundary, |
| 3226 | 3451 | # we need to turn off highlights here. |
| 3227 | 3452 | if self.source.quiet: |
| 3228 | trailer = "" | |
| 3453 | trailer = "" | |
| 3229 | 3454 | else: |
| 3230 | trailer = " <!-- .fi -->" | |
| 3455 | trailer = " <!-- .fi%s -->" % fontswitch | |
| 3231 | 3456 | if self.screen: |
| 3232 | 3457 | self.source.emit(r"\fR</screen>" + trailer) |
| 3233 | 3458 | self.screen = False |
| 3240 | 3465 | if self.source.peekline() == TroffInterpreter.ctrl + "ft CW": |
| 3241 | 3466 | self.source.popline() |
| 3242 | 3467 | self.source.end_paragraph() |
| 3243 | self.source.emit("<screen> <!-- .nf -->") | |
| 3468 | self.source.emit("<screen remap='.nf .ft CW'>") | |
| 3244 | 3469 | self.screen = True |
| 3245 | 3470 | self.nf = True |
| 3246 | 3471 | else: |
| 3356 | 3581 | i += 1 |
| 3357 | 3582 | if i >= len(line): |
| 3358 | 3583 | break |
| 3359 | if line[i] == '"': | |
| 3584 | if len(line) > i and line[i] == '"': | |
| 3360 | 3585 | i += 1 |
| 3361 | 3586 | value = line[i:] |
| 3362 | value = value.replace("'", "'"); | |
| 3587 | value = value.replace(r"\'", "'") | |
| 3588 | value = value.replace("'", "'") | |
| 3363 | 3589 | if self.source.in_preamble and self.entities_from_strings: |
| 3364 | 3590 | self.source.localentities.append((stringname, value)) |
| 3365 | 3591 | self.strings[stringname] = "&" + stringname + ";" |
| 3381 | 3607 | newname = tokens[2] |
| 3382 | 3608 | suppressed = False |
| 3383 | 3609 | for interpreter in self.source.interpreters: |
| 3384 | if oldname in interpreter.immutable_set.keys(): | |
| 3610 | if oldname in interpreter.immutable_set: | |
| 3385 | 3611 | suppressed = True |
| 3386 | 3612 | break |
| 3387 | 3613 | if suppressed: |
| 3416 | 3642 | isused = filter(lambda x: type(x) == type("") and x[0:len(name)+1]==TroffInterpreter.ctrl+name, self.source.lines) |
| 3417 | 3643 | suppressed = False |
| 3418 | 3644 | for interpreter in self.source.interpreters: |
| 3419 | if name in interpreter.immutable_set.keys(): | |
| 3645 | if name in interpreter.immutable_set: | |
| 3420 | 3646 | suppressed = True |
| 3421 | 3647 | break |
| 3422 | 3648 | # We don't want macro listings showing up in the Synopsis section. |
| 3433 | 3659 | linetoks = lineparse(line) |
| 3434 | 3660 | if linetoks: |
| 3435 | 3661 | for interpreter in self.source.interpreters: |
| 3436 | if linetoks[0][1:] in interpreter.ignore_set: | |
| 3662 | command = linetoks[0][1:] | |
| 3663 | if command in interpreter.ignore_set: | |
| 3437 | 3664 | line += '\t.\\" IGNORED' |
| 3438 | elif linetoks[0][1:] in interpreter.complain_set: | |
| 3665 | elif command in interpreter.complain_set: | |
| 3439 | 3666 | line += '\t.\\" IGNORED' |
| 3440 | 3667 | if not suppressed: |
| 3441 | self.source.warning("untranslatable %s in %s definition" % (linetoks[0][1:], name)) | |
| 3668 | self.source.warning("untranslatable %s in %s definition" % (command, name)) | |
| 3442 | 3669 | if listing: |
| 3443 | 3670 | self.source.emit(line) |
| 3444 | 3671 | # Simulate troff's first round of \ interpretation (at |
| 3475 | 3702 | baseval = self.macros[reg] |
| 3476 | 3703 | else: |
| 3477 | 3704 | baseval = '0' |
| 3478 | val = `eval(baseval+val)` | |
| 3705 | val = str(eval(baseval+val)) | |
| 3706 | if macro_verbosity in self.verbose: | |
| 3707 | self.source.warning("register %s = %s" % (reg, val)) | |
| 3479 | 3708 | self.registers[reg] = val |
| 3480 | 3709 | elif command == "rr": |
| 3481 | 3710 | reg = args[0] |
| 3491 | 3720 | self.registers[new] = val |
| 3492 | 3721 | # OK, now process conditionals |
| 3493 | 3722 | elif command in ("ie", "if"): |
| 3723 | if command == "if" and not args: | |
| 3724 | self.source.error("'.if' without arguments is probably a typo for '.fi.'") | |
| 3725 | self.source.pushline(".fi") | |
| 3726 | return True | |
| 3727 | # If somebody tried to parenthesize a guard, throw the whole mess | |
| 3728 | # out. This happens on INIFILE.1 where you get crap like this: | |
| 3729 | # .if (\nx>(\n(.l/2)) .nr x (\n(.l/5) | |
| 3730 | if tokens and tokens[1][0] == '(': | |
| 3731 | return True | |
| 3494 | 3732 | if len(tokens) == 1: |
| 3495 | 3733 | # Cope with a transposition typo...see vmstat(8) for example. |
| 3496 | 3734 | if command == "if" and self.nf: |
| 3530 | 3768 | else: |
| 3531 | 3769 | # Kluge -- we don't want to trip on .ig terminators |
| 3532 | 3770 | for i in range(1, len(args)): |
| 3533 | if args[i] == '.ig' and len(args) > i: | |
| 3771 | if args[i] == '.ig' and len(args) > i+1: | |
| 3534 | 3772 | self.source.ignore(args[i+1]) |
| 3535 | 3773 | # There may be a hanging { on the next line; if so, nuke it |
| 3536 | 3774 | if self.source.peekline() in ("\\{", "\\{\\"): |
| 3567 | 3805 | self.skiptoend(tokens) |
| 3568 | 3806 | if macro_verbosity in self.verbose: |
| 3569 | 3807 | self.source.notify("stack state after .el: %s" % self.ifstack) |
| 3570 | elif command == r"\}": | |
| 3808 | elif command == r"\}" or command == r".\}": | |
| 3571 | 3809 | if self.ifstack: # See above note on a2p |
| 3572 | 3810 | if macro_verbosity in self.verbose: |
| 3573 | 3811 | self.source.notify("stack pop from: " + `tokens`) |
| 3591 | 3829 | self.source.emit(".%s -->" % args[0], trans=0) |
| 3592 | 3830 | break |
| 3593 | 3831 | line = line.replace(r"\^", "––") |
| 3594 | line = line.replace("\-", "—") | |
| 3832 | line = line.replace(r"\-", "—") | |
| 3595 | 3833 | line = line.replace("-", "—") |
| 3596 | 3834 | self.source.emit(line) |
| 3597 | 3835 | if self.source.body_section(): |
| 3609 | 3847 | self.source.lines = self.macros[command] + [self.source.lineno] + self.source.lines |
| 3610 | 3848 | # Extended groff macros |
| 3611 | 3849 | elif command == "do": |
| 3612 | self.groff_features.append("do") | |
| 3613 | pass # Only ever used within macro packages. | |
| 3850 | self.groff_features.append("do") # Only ever used within macro packages. | |
| 3614 | 3851 | elif command == "cc": |
| 3615 | 3852 | self.nonportable_features.append("cc") |
| 3616 | 3853 | TroffInterpreter.ctrl = args[0] |
| 3621 | 3858 | if not args: |
| 3622 | 3859 | args = ["User Abort"] |
| 3623 | 3860 | raise LiftException(" ".join(args), 1) |
| 3861 | elif command == "rj": | |
| 3862 | if not args: | |
| 3863 | self.source.pushline(".br") | |
| 3864 | else: | |
| 3865 | self.source.warning(".rj with arguments seen.") | |
| 3624 | 3866 | elif command == "als": |
| 3625 | 3867 | # Implements soft link rather than hard; hard would be difficult |
| 3626 | 3868 | # because the target would be the old macro name. |
| 3667 | 3909 | def preprocess(self, text): |
| 3668 | 3910 | if r'\*[' in text: |
| 3669 | 3911 | self.groff_features.append(r"\*[") |
| 3912 | # Fixes an error found in OpenLDAP pages that night be generic. | |
| 3913 | # This substitution enables a later stage to detect formations | |
| 3914 | # that should turn into literallayout tag pairs. | |
| 3915 | text = text.replace("\n.ft tt\n", "\n.ft CW\n") | |
| 3916 | # The X.org pages use \N'34' to generate a double quote that | |
| 3917 | # is stable everywhere. We can't translate \N a priori in general | |
| 3918 | # because it indexes into fonts that might have variable glyphs | |
| 3919 | # at particular positions, but this one seems pretty safe. | |
| 3920 | text = text.replace(r"\N'34'", '"') | |
| 3921 | # Turn trailing \}, such as in rnews.1, into something we can process. | |
| 3922 | # This is meatball surgery which might introduce an unwanted \n if | |
| 3923 | # we happen to be in a literal-layout context. | |
| 3924 | text = text.replace("\\}\n", "\n\\}\n") | |
| 3670 | 3925 | # We may need to pre-filter with eqn and pic. |
| 3671 | 3926 | if "\n.EQ" in text: |
| 3672 | 3927 | fp = tempfile.NamedTemporaryFile(prefix="doclifter") |
| 3677 | 3932 | if status == 0 and "<math" in mathml and not "<merror" in mathml: |
| 3678 | 3933 | self.source.eqn_processed = True |
| 3679 | 3934 | # Reduce trivial equations |
| 3680 | mathml = re_compile("<math><m[ion]>(\w*)</m[ion]></math>").sub(r'\\fI\1\\fP', mathml) | |
| 3935 | mathml = re_compile(r"<math><m[ion]>(\w*)</m[ion]></math>").sub(r'\\fI\1\\fP', mathml) | |
| 3681 | 3936 | # Now make sure there is a newline before trailing .ENs |
| 3682 | 3937 | mathml = mathml.replace("</math>.EN", "</math>\n.EN") |
| 3683 | 3938 | # FIXME: this optimization should be done in eqn, really |
| 3757 | 4012 | # tokenization of synopses easier. Turn it back. |
| 3758 | 4013 | text = text.replace(";", ";") |
| 3759 | 4014 | # Convert vertical motions to superscript/subscript operations. |
| 4015 | # Protecct double backslashes first. | |
| 3760 | 4016 | text = text.replace(r"\\", r"@\\@") |
| 3761 | 4017 | upmotion = re_compile(r"\\v'\-\.[0-9]+[mnv]'|\\u(\.[0-9]+[mnv])?") |
| 3762 | 4018 | downmotion = re_compile(r"\\v'\+?\.[0-9]+[mnv]'|\\d(\.[0-9]+[mnv])?") |
| 3776 | 4032 | text = text[:upward.start()] \ |
| 3777 | 4033 | + r"<superscript>" \ |
| 3778 | 4034 | + text[upward.end():] |
| 3779 | direction = 'up'; | |
| 3780 | if io_verbosity in self.verbose: | |
| 3781 | self.source.notify("Starting from None, I see upward %s" % upward) | |
| 4035 | direction = 'up' | |
| 4036 | if supersub_verbosity in self.verbose: | |
| 4037 | self.source.notify("Starting from None, I see upward %s at %d" % (upward.string[upward.start(0):upward.end(0)], upward.start(0))) | |
| 3782 | 4038 | elif downward: |
| 3783 | 4039 | text = text[:downward.start()] \ |
| 3784 | 4040 | + r"<subscript>" \ |
| 3785 | 4041 | + text[downward.end():] |
| 3786 | 4042 | direction = 'down' |
| 3787 | if io_verbosity in self.verbose: | |
| 3788 | self.source.notify("Starting from None, I see downward %s" % downward) | |
| 4043 | if supersub_verbosity in self.verbose: | |
| 4044 | self.source.notify("Starting from None, I see downward %s at %d" % (downward.string[downward.start(0):downward.end(0)], downward.start(0))) | |
| 3789 | 4045 | else: |
| 3790 | 4046 | self.source.error("error in vertical-motion match") |
| 3791 | 4047 | elif direction == 'up': |
| 3797 | 4053 | + r"</superscript>" \ |
| 3798 | 4054 | + text[downward.end():] |
| 3799 | 4055 | direction = None |
| 3800 | if io_verbosity in self.verbose: | |
| 3801 | self.source.notify("Starting from up, I see downward %s" % downward) | |
| 4056 | if supersub_verbosity in self.verbose: | |
| 4057 | self.source.notify("Starting from up, I see downward %s at %d" % (downward.string[downward.start(0):downward.end(0)], downward.start(0))) | |
| 3802 | 4058 | else: |
| 3803 | 4059 | self.source.error("error in vertical-motion match (up)") |
| 3804 | 4060 | elif direction == 'down': |
| 3807 | 4063 | + r"</subscript>" \ |
| 3808 | 4064 | + text[upward.end():] |
| 3809 | 4065 | direction = None |
| 3810 | if io_verbosity in self.verbose: | |
| 3811 | self.source.notify("Starting from down, I see upward %s" % upward) | |
| 4066 | if supersub_verbosity in self.verbose: | |
| 4067 | self.source.notify("Starting from down, I see upward %s at %d" % (upward.string[upward.start(0):upward.end(0)], upward.start(0))) | |
| 3812 | 4068 | elif downward: |
| 3813 | 4069 | self.source.error("two downward motions in a row") |
| 3814 | 4070 | raise SystemExit |
| 3815 | 4071 | else: |
| 3816 | 4072 | self.source.error("error in vertical-motion match (down)") |
| 4073 | text = text.replace(r"@\\@", r"\\") | |
| 3817 | 4074 | # These get generated when ad-hoc tables are wrapped with .nf/.fi; |
| 3818 | 4075 | # the table-compilation code tried to close the display begun by |
| 3819 | 4076 | # the .nf. |
| 3820 | 4077 | text = re.sub("<literallayout remap='.nf'>[ \t\n]*</literallayout>", "", text) |
| 4078 | # Our highlight tracking logic sometimes generates enphasis pairs with | |
| 4079 | # nothing in scope. Remove these. | |
| 4080 | text = re.sub("<emphasis remap='[^']+'>[ \t\n]*</emphasis>", "", text) | |
| 4081 | # Ugh. Another bug is that we sometimes generate too many font closes | |
| 4082 | # in table entries. This fixes the problem in a klugey way. | |
| 4083 | text = re.sub(r"(\\fR)+</para></entry>", "</para></entry>", text) | |
| 4084 | text = re.sub(r"(\\fR)+</entry>", "</entry>", text) | |
| 3821 | 4085 | # Now some pattern lifting to be applied after all macro sets. |
| 3822 | # This hairy pattern matches the result of lifting .nf/.fi | |
| 3823 | # sections, possibly with a highlight. | |
| 4086 | # This transforms literallayouts with program text inside them | |
| 4087 | # into programlistings. | |
| 3824 | 4088 | keyword_lifter = \ |
| 3825 | "(<literallayout(?: remap='.nf')?>(?:\n*<emphasis remap='[A-Z]*'>)?)" \ | |
| 4089 | "(<(?:literallayout|screen)(?: remap='([^']*)')?>(?:\n*<emphasis remap='[A-Z]*'>)?)" \ | |
| 3826 | 4090 | "([^<]*(%s)[^<]*)" \ |
| 3827 | "((</emphasis>\n?)?</literallayout>)" | |
| 4091 | "((</emphasis>\n?)?</(?:literallayout|screen)>)" | |
| 3828 | 4092 | # Continue by recognizing source-code listings and screenshots |
| 3829 | 4093 | # of command examples. |
| 3830 | 4094 | literal_lifts = ( |
| 3831 | 4095 | (r"struct|typedef|#define|#undef", "programlisting"), # C |
| 3832 | ("@_", "programlisting"), # Pel | |
| 4096 | ("@_", "programlisting"), # Perl | |
| 3833 | 4097 | ("\ndef|elif|try|except", "programlisting"), # Python |
| 3834 | 4098 | ("mov|jmp", "programlisting"), # Assembler |
| 3835 | 4099 | ("\nbash$|\n$", "screen") |
| 3837 | 4101 | for (keywords, ltype) in literal_lifts: |
| 3838 | 4102 | listing = re_compile(keyword_lifter % keywords) |
| 3839 | 4103 | ender = ltype.split()[0] |
| 3840 | text = listing.sub(r"<%s remap='.nf'>\2</%s>" % (ltype,ender), text) | |
| 4104 | text = listing.sub(r"<%s remap='\2'>\3</%s>" % (ltype,ender), text) | |
| 3841 | 4105 | # Here is another hack to lift filenames and similar things. |
| 3842 | # Also, handle groff color extension. Alas, no tag-balance checking. | |
| 4106 | # Also, handle groff color extension. Alas, no tag-balance checking. | |
| 3843 | 4107 | color_lifts = map(lambda x: (re_compile(x[0]), x[1]), ( |
| 3844 | ("\\\\m\[\]", "</phrase>"), | |
| 3845 | ("\\\\m\[([a-z]+)\]", "<phrase remap='color:\\1'>"), | |
| 4108 | ("\\\\m\[\]", r"</phrase>"), | |
| 4109 | ("\\\\m\[([a-z]+)\]", r"<phrase remap='color:\1'>"), | |
| 3846 | 4110 | )) |
| 3847 | 4111 | for (regexp, inline) in TroffInterpreter.prefix_lifts + color_lifts: |
| 3848 | 4112 | text = regexp.sub(inline, text) |
| 3872 | 4136 | line = source.popline() |
| 3873 | 4137 | if line == TroffInterpreter.ctrl + "end": |
| 3874 | 4138 | source.pushline(TroffInterpreter.ctrl + "end") |
| 3875 | break; | |
| 4139 | break | |
| 3876 | 4140 | elif line == None: |
| 3877 | 4141 | break |
| 3878 | 4142 | elif line in ("", TroffInterpreter.ctrl, TroffInterpreter.ctrl_nobreak): # Skip blank or null lines |
| 3953 | 4217 | if interpreter_verbosity in source.verbose: |
| 3954 | 4218 | source.notify("interpretation of savesect complete\n") |
| 3955 | 4219 | if filter(lambda x: not not x and x[:4] != "<!--", outlines): |
| 3956 | map(lambda x: source.emit(x), outlines) | |
| 4220 | map(source.emit, outlines) | |
| 3957 | 4221 | else: |
| 3958 | 4222 | source.warning("empty list item, see FIXME") |
| 3959 | 4223 | source.emit("<para> </para> <!-- FIXME: empty list item -->") |
| 3992 | 4256 | nameline = nameline.replace("\t", r' ') |
| 3993 | 4257 | nameline = nameline.replace(r" \-\- ", r' \- ') |
| 3994 | 4258 | nameline = nameline.replace(" - ", r' \- ') |
| 4259 | nameline = nameline.replace(r" \(hy ", r' \- ') | |
| 3995 | 4260 | # Apparent pod2man breakage... |
| 3996 | nameline = nameline.replace(r"&zerosp;-", "\-") | |
| 4261 | nameline = nameline.replace(r"&zerosp;-", r"\-") | |
| 3997 | 4262 | if nameline.find(r" \- ") == -1: |
| 3998 | 4263 | nameline = nameline.replace(r" \(em ", r' \- ') |
| 3999 | 4264 | nameline = nameline.replace(r" — ", r' \- ') |
| 4007 | 4272 | # |
| 4008 | 4273 | |
| 4009 | 4274 | class ParseNode: |
| 4010 | def __init__(self, type, token=None, choice="plain", repeat=0): | |
| 4011 | self.type = type | |
| 4275 | def __init__(self, ntype, token=None, choice="plain", repeat=0): | |
| 4276 | self.type = ntype | |
| 4012 | 4277 | self.token = token |
| 4013 | 4278 | self.choice = choice |
| 4014 | 4279 | self.righthand = None |
| 4236 | 4501 | self.seen_ansi = False |
| 4237 | 4502 | # Shortcut: assume | and ') (' and ] [ can never occur in a function |
| 4238 | 4503 | # synopsis (middle two filters out some Perl code examples). |
| 4239 | # Make ann exception for || as this never occurs in those but may mean | |
| 4504 | # Make an exception for || as this never occurs in those but may mean | |
| 4240 | 4505 | # there is code for a disjunction of feature macros, as in logf(3). |
| 4241 | 4506 | # Look for these and return immediately if we find them. |
| 4242 | 4507 | if filter(lambda x: ("||" not in x and "|" in x) or "('" in x or "')" in x or "] [" in x, self.io.lines): |
| 4288 | 4553 | "Recognize that a line is source code." |
| 4289 | 4554 | if blankline.search(text): |
| 4290 | 4555 | return True |
| 4291 | for (pattern,lang) in FunctionSynopsisParser.language_lines: | |
| 4556 | for (pattern, dummy) in FunctionSynopsisParser.language_lines: | |
| 4292 | 4557 | if pattern.search(text): |
| 4293 | 4558 | return True |
| 4294 | for (pattern,lang) in FunctionSynopsisParser.language_fragments: | |
| 4559 | for (pattern, dummy) in FunctionSynopsisParser.language_fragments: | |
| 4295 | 4560 | if pattern.search(text): |
| 4296 | 4561 | return True |
| 4297 | 4562 | return False |
| 4320 | 4585 | last = len(lst) - 1 |
| 4321 | 4586 | for i in range(0, last+1): |
| 4322 | 4587 | if lst[last - i] == x: |
| 4323 | return last - i | |
| 4588 | return last - i | |
| 4324 | 4589 | return -1 |
| 4325 | 4590 | last = len(arg) - 1 |
| 4326 | 4591 | if arg[-1] == ')': |
| 4407 | 4672 | if classify_verbosity in self.source.verbose: |
| 4408 | 4673 | self.source.notify("name is %s, non-identifier is %s" % (name, `tnext`)) |
| 4409 | 4674 | elif seentype: |
| 4410 | if general_verbosity in self.source.verbose: | |
| 4675 | if classify_verbosity in self.source.verbose: | |
| 4411 | 4676 | self.source.notify("looks like text, not a function declaration: %s" % tok) |
| 4412 | 4677 | self.io.unroll() |
| 4413 | 4678 | return "" |
| 4618 | 4883 | self.source.notify("ending function prototype parse") |
| 4619 | 4884 | return output |
| 4620 | 4885 | |
| 4621 | def __detect_passthroughs(self): | |
| 4886 | def __detect_passthroughs(self, line=None): | |
| 4622 | 4887 | # Detect language-specific line pattern |
| 4888 | if line is None: | |
| 4889 | line = self.io.peekline() | |
| 4623 | 4890 | for (pattern, lang) in FunctionSynopsisParser.language_lines: |
| 4624 | if pattern.search(self.io.peekline()): | |
| 4891 | if pattern.search(line): | |
| 4625 | 4892 | return lang |
| 4626 | 4893 | return None |
| 4627 | 4894 | def __parse_function_synopsis_info(self): |
| 4640 | 4907 | # Pass through blank lines |
| 4641 | 4908 | if blankline.match(line): |
| 4642 | 4909 | synopsisinfo += line |
| 4643 | self.io.popline() | |
| 4910 | self.io.popline() | |
| 4644 | 4911 | continue |
| 4645 | 4912 | # Pass through breaks |
| 4646 | 4913 | if line.startswith("<sbr/>"): |
| 4653 | 4920 | # at a later parse stage. |
| 4654 | 4921 | if line.startswith("cc") or line.startswith("gcc"): |
| 4655 | 4922 | synopsisinfo += line |
| 4656 | self.io.popline() | |
| 4923 | self.io.popline() | |
| 4657 | 4924 | continue |
| 4658 | 4925 | # Also pass through anything that looks like a Qt section header |
| 4659 | 4926 | if line.strip() in qt_headers: |
| 4660 | 4927 | synopsisinfo += line |
| 4661 | self.io.popline() | |
| 4928 | self.io.popline() | |
| 4662 | 4929 | continue |
| 4663 | 4930 | # Other things, like cpp directives, should pass through as well. |
| 4664 | 4931 | # Test for single-line typedefs here so as not to have a bad |
| 4669 | 4936 | self.source.notify("from %s language identified as %s\n"% (`line`, lang)) |
| 4670 | 4937 | self.language = lang |
| 4671 | 4938 | synopsisinfo += line |
| 4672 | self.io.popline() | |
| 4939 | self.io.popline() | |
| 4673 | 4940 | continue |
| 4674 | 4941 | # On the other hand, seeing ( means we have run into what should be |
| 4675 | 4942 | # a function synopsis. Throw it back. |
| 4680 | 4947 | # obvious keyword up front. |
| 4681 | 4948 | if line.endswith(";\n"): |
| 4682 | 4949 | synopsisinfo += line |
| 4683 | self.io.popline() | |
| 4950 | self.io.popline() | |
| 4684 | 4951 | continue |
| 4685 | 4952 | # Pass through any line ending with colon after a blank line. |
| 4686 | 4953 | # This catches things like DEPRECATED: in the libpng pages. |
| 4687 | 4954 | if not self.source.diversion[-1].strip() and line.endswith(":\n"): |
| 4688 | 4955 | synopsisinfo += line |
| 4689 | self.io.popline() | |
| 4956 | self.io.popline() | |
| 4690 | 4957 | continue |
| 4691 | 4958 | # Pass through line sequences bracketed by specified token pairs. |
| 4692 | 4959 | # This is where we catch stuff like multiline struct declarations. |
| 4695 | 4962 | if parse_verbosity in self.source.verbose: |
| 4696 | 4963 | self.source.notify("Declaration starts with %s" % start) |
| 4697 | 4964 | while self.io.lines: |
| 4698 | line = detroff(self.io.popline()).strip() | |
| 4965 | line = detroff(self.io.popline()) | |
| 4699 | 4966 | if parse_verbosity in self.source.verbose: |
| 4700 | 4967 | self.source.notify(`line`) |
| 4701 | synopsisinfo += line + " " | |
| 4968 | synopsisinfo += line | |
| 4702 | 4969 | # This is the magic that allows us to avoid elaborate |
| 4703 | 4970 | # tokenization rules. Look for the terminator as the |
| 4704 | 4971 | # suffix of a token. |
| 4705 | 4972 | if end.search(line): |
| 4706 | break | |
| 4973 | break | |
| 4707 | 4974 | else: |
| 4708 | 4975 | raise LiftException("missing end token for " + errmsg) |
| 4709 | 4976 | else: |
| 4728 | 4995 | self.output = "" |
| 4729 | 4996 | self.confirmed = False |
| 4730 | 4997 | self.error = None |
| 4998 | self.context = None | |
| 4999 | self.callnest = "" | |
| 5000 | self.groupnest = 0 | |
| 4731 | 5001 | self.lastnest = [] |
| 4732 | 5002 | # Arrange for lexical analysis to work |
| 4733 | 5003 | self.io.tokenize(self.__pretokenize) |
| 4747 | 5017 | break |
| 4748 | 5018 | nextpart.append(line) |
| 4749 | 5019 | if not filter(self.is_command_synopsis_line, nextpart): |
| 4750 | break; | |
| 5020 | break | |
| 4751 | 5021 | output = self.parse_command_synopsis() |
| 4752 | 5022 | if not output: |
| 4753 | 5023 | break |
| 4858 | 5128 | raise LiftException("first token %s in synopsis looks wrong." % command) |
| 4859 | 5129 | self.io.checkpoint() |
| 4860 | 5130 | while self.io.lines: |
| 5131 | if is_nltext_line(self.io.lines[0]): | |
| 5132 | break | |
| 4861 | 5133 | arg = self.__compile_arg() |
| 4862 | 5134 | if arg == None: |
| 4863 | 5135 | break |
| 4873 | 5145 | (self.io.token_peek(), self.io.token_index, e.message) |
| 4874 | 5146 | self.io.unroll() |
| 4875 | 5147 | # Generate a useful error message: |
| 4876 | errmsg = "\n" + self.error + "\n" | |
| 5148 | self.context = "\n" | |
| 4877 | 5149 | if self.lastnest: |
| 4878 | errmsg += " ".join(self.io.lookbehind[:self.lastnest[-1]]) | |
| 4879 | errmsg += " $ " | |
| 4880 | errmsg += " ".join(self.io.lookbehind[self.lastnest[-1]:]) | |
| 4881 | else: | |
| 4882 | errmsg += " ".join(self.io.lookbehind[:self.io.token_index]) | |
| 4883 | errmsg += " ^ " | |
| 4884 | errmsg += " ".join(self.io.lookbehind[self.io.token_index:]) | |
| 4885 | errmsg += "\n" | |
| 4886 | return "\n" + make_comment(errmsg) + "\n" | |
| 5150 | self.context += " ".join(self.io.lookbehind[:self.lastnest[-1]]) | |
| 5151 | self.context += " $ " | |
| 5152 | self.context += " ".join(self.io.lookbehind[self.lastnest[-1]:]) | |
| 5153 | else: | |
| 5154 | self.context += " ".join(self.io.lookbehind[:self.io.token_index]) | |
| 5155 | self.context += " ^ " | |
| 5156 | self.context += " ".join(self.io.lookbehind[self.io.token_index:]) | |
| 5157 | return "\n" + make_comment("\n" + self.error + "\n" + self.context) + "\n" | |
| 4887 | 5158 | |
| 4888 | 5159 | # Lexical tests |
| 4889 | 5160 | def __is_next_special(self): |
| 4922 | 5193 | # # -- gphoto.1 |
| 4923 | 5194 | # ? -- cdecl.1 and other places where ? invokes help. |
| 4924 | 5195 | # / -- dummy filename arguments |
| 4925 | elif tnext[0] in string.letters + "./=:'\"@%,#?" or (tnext[:4] == "<" and tnext != "<") or self.__is_next_numeric() or is_file_or_command_name(tnext): | |
| 5196 | # \ -- TeX commands such as luatex.1 | |
| 5197 | # & -- TeX commands such as luatex.1 | |
| 5198 | elif tnext[0] in string.letters + "./=:'\"@%,#?\\&" or (tnext[:4] == "<" and tnext != "<") or self.__is_next_numeric() or is_file_or_command_name(tnext): | |
| 4926 | 5199 | return True |
| 4927 | 5200 | # nm.1 |
| 4928 | 5201 | elif re.match("[0-9]+_[0-9]+", tnext): |
| 5073 | 5346 | return res |
| 5074 | 5347 | |
| 5075 | 5348 | |
| 5349 | def is_nltext_line(line): | |
| 5350 | "Are there patterns here that must be natural language?" | |
| 5351 | if line is None: | |
| 5352 | return False | |
| 5353 | line = line.strip() | |
| 5354 | if not line or len(line) < 2: | |
| 5355 | return False | |
| 5356 | # Line ending with period that is not part of an ellipsis has to be a | |
| 5357 | # NL sentence, because lone periods can't occur in command | |
| 5358 | # synopses and periods can't occur at all in function synopses. | |
| 5359 | if line[-1] == '.' and line[-2].isalpha(): | |
| 5360 | return True | |
| 5361 | # Line ending with semicolon has to be a NL sentence. Note that | |
| 5362 | # embedded colons can occur as argument leaders in, e.g., | |
| 5363 | # port suffixes for some network commands. | |
| 5364 | if line[-1] == ':': | |
| 5365 | return True | |
| 5366 | words = line.split() | |
| 5367 | if len(line) < 8: | |
| 5368 | return False | |
| 5369 | if len(words) < 3: | |
| 5370 | return False | |
| 5371 | # Look for giveaway words. | |
| 5372 | for word in ("the", "and", "with", "whitespace", "abbreviated"): | |
| 5373 | if word in words: | |
| 5374 | return True | |
| 5375 | return False | |
| 5376 | ||
| 5076 | 5377 | class DisplayParser: |
| 5077 | 5378 | "Parse a block into function synopsis, command synopsis or display text." |
| 5078 | 5379 | old_style_option_glue = re_compile(r"([^A-Za-z]-[A-Za-z]*)(?:\f.)([A-Za-z])") |
| 5079 | 5380 | unparseable = re_compile(r"\$|=>|[^:]//") # Perl and other nightmares |
| 5080 | def __init__(self, source, try_synopsis, refnames={}): | |
| 5381 | def __init__(self, source, try_synopsis, literal, refnames=None): | |
| 5081 | 5382 | "Arrange the interpreter to accumulate synopsis lines in this object." |
| 5082 | 5383 | self.source = source |
| 5083 | 5384 | self.try_synopsis = try_synopsis |
| 5385 | self.literal = literal | |
| 5084 | 5386 | self.refnames = refnames |
| 5387 | if self.refnames is None: | |
| 5388 | self.refnames = {} | |
| 5085 | 5389 | self.synopses = [] |
| 5086 | 5390 | source.diversion = self.synopses |
| 5391 | self.io = None | |
| 5087 | 5392 | source.ignore("nf") |
| 5088 | 5393 | source.ignore("fi") |
| 5089 | 5394 | source.ignore("ft") |
| 5125 | 5430 | return True |
| 5126 | 5431 | # Also detect things that look like SQL synopses |
| 5127 | 5432 | if text.split()[0].isupper() and self.source.find("SQL", backwards=True): |
| 5128 | return True | |
| 5129 | return False | |
| 5130 | def is_nltext_line(self, line): | |
| 5131 | "Are there patterns here that must be natural language?" | |
| 5132 | if not line: | |
| 5133 | return False | |
| 5134 | words = line.split() | |
| 5135 | if len(line) < 8: | |
| 5136 | return False | |
| 5137 | # Line ending with period that is not part of an ellipsis has to be a | |
| 5138 | # NL sentence, because lone periods can't occur in command | |
| 5139 | # synopses and periods can't occur at all in function synopses. | |
| 5140 | if line[-1] == '.' and len[-2].isalpha(): | |
| 5141 | return True | |
| 5142 | if len(words) < 3: | |
| 5143 | return False | |
| 5144 | # Look for giveaway words. | |
| 5145 | for word in ("the", "and", "with", "whitespace", "abbreviated"): | |
| 5146 | if word in words: | |
| 5147 | return True | |
| 5148 | # Colons cannot occur in either function or command synopses | |
| 5149 | if ':' in line: | |
| 5150 | 5433 | return True |
| 5151 | 5434 | return False |
| 5152 | 5435 | def __emit_text(self, lines): |
| 5219 | 5502 | # means the text we're interpreting may contain <. >, and tags. |
| 5220 | 5503 | # |
| 5221 | 5504 | # The strategy we use is to repeatedly look for function synopses, |
| 5222 | # command synopses, or lines that we can unambgiguously identify as | |
| 5505 | # command synopses, or lines that we can unambiguously identify as | |
| 5223 | 5506 | # natural language. When we fail to find one starting on a |
| 5224 | 5507 | # given line, we stash that line away and advance to the next. |
| 5225 | 5508 | # Each time we find one of the structured things we can detect |
| 5233 | 5516 | if classify_verbosity in self.source.verbose: |
| 5234 | 5517 | self.source.notify("got unparseable synopsis ") |
| 5235 | 5518 | else: |
| 5236 | known_nl = False | |
| 5519 | classified = False | |
| 5237 | 5520 | stash = [] |
| 5238 | 5521 | while self.io.lines: |
| 5239 | 5522 | parsepass += 1 |
| 5257 | 5540 | # done first because synopses for libraries not infrequently |
| 5258 | 5541 | # contain link instructions that can be mistaken for command |
| 5259 | 5542 | # synopses. |
| 5260 | while self.is_nltext_line(self.io.peekline()): | |
| 5261 | known_nl = True | |
| 5543 | while is_nltext_line(self.io.peekline()): | |
| 5544 | classified = True | |
| 5262 | 5545 | nextl = self.io.popline() |
| 5263 | 5546 | if classify_verbosity in self.source.verbose: |
| 5264 | 5547 | self.source.warning("stashing '%s' (NL)" % `nextl`) |
| 5278 | 5561 | out += obj.output |
| 5279 | 5562 | if self.source.in_synopsis(): |
| 5280 | 5563 | self.source.error(obj.error) |
| 5564 | if self.source.verbose: | |
| 5565 | self.source.error("error context: %s" % obj.context) | |
| 5281 | 5566 | elif classify_verbosity in self.source.verbose: |
| 5282 | 5567 | self.source.warning(obj.error) |
| 5568 | # Look for a filename - some manual pages for | |
| 5569 | # configuration files just give the full path of the | |
| 5570 | # file as the synopsis. This case doesn't do anything | |
| 5571 | # very interesting, but it does avoid throwing a | |
| 5572 | # warning. | |
| 5573 | line = self.io.peekline() | |
| 5574 | if line and re.match(r"/[\S]*$", line): | |
| 5575 | out += self.__emit_text(stash) | |
| 5576 | fnpart = "<filename>" + line.strip() + "</filename>" | |
| 5577 | if self.literal: | |
| 5578 | out += fnpart + "\n" | |
| 5579 | else: | |
| 5580 | out += "<para>" + fnpart + "</para>\n" | |
| 5581 | self.io.popline() | |
| 5582 | classified = True | |
| 5583 | continue | |
| 5283 | 5584 | # None of the above. Stash the current line and try again on |
| 5284 | 5585 | # the next one. |
| 5285 | 5586 | nextl = self.io.popline() |
| 5286 | 5587 | if nextl: |
| 5287 | known_nl = False | |
| 5588 | classified = False | |
| 5288 | 5589 | if classify_verbosity in self.source.verbose: |
| 5289 | 5590 | self.source.warning("stashing '%s'" % `nextl`) |
| 5290 | 5591 | stash.append(nextl) |
| 5297 | 5598 | # Postprocess the output to remove glue and clean up empty tags |
| 5298 | 5599 | out = hotglue.sub("", out) |
| 5299 | 5600 | out = cleantag.sub("", out) |
| 5300 | out = re.sub("<funcsynopsisinfo>\s*</funcsynopsisinfo>", "", out) | |
| 5301 | out = re.sub("<funcsynopsis>\s*</funcsynopsis>", "", out) | |
| 5302 | return (out, parsepass > 1 and errors == 0 and not known_nl) | |
| 5601 | out = re.sub(r"<funcsynopsisinfo>\s*</funcsynopsisinfo>", "", out) | |
| 5602 | out = re.sub(r"<funcsynopsis>\s*</funcsynopsis>", "", out) | |
| 5603 | return (out, parsepass > 1 and errors == 0 and not classified) | |
| 5303 | 5604 | |
| 5304 | 5605 | # |
| 5305 | 5606 | # Macro interpreters. |
| 5363 | 5664 | name = "man" |
| 5364 | 5665 | exclusive = True |
| 5365 | 5666 | toptag = "refentry" |
| 5366 | immutable_set = { "B":1, "I":1,"R" :1,"SM":1,"CB":1,"CR":1, | |
| 5367 | "BI":1,"BR":1,"IB":1,"IR":1, | |
| 5368 | "IL":1,"RB":1,"RI":1,"RL":1,"SB":1,"LB":1,"LI":1,"LR":1, | |
| 5369 | "P" :1,"PP":1,"LP":1,"HP":1, | |
| 5370 | "IP":1,"RS":1,"RE":1,"SH":1,"SS":1,"HP":1,"TP":1, | |
| 5371 | "UE":1,"UN":1,"UR":1,"IX":1,"BY":1,} | |
| 5372 | ignore_set = {"PD":1, "DT":1, | |
| 5667 | immutable_set = set(["B", "I","R" ,"SM","CB","CR", | |
| 5668 | "BI","BR","IB","IR", | |
| 5669 | "IL","RB","RI","RL","SB","LB","LI","LR", | |
| 5670 | "P" ,"PP","LP","HP", | |
| 5671 | "IP","RS","RE","SH","SS","TP", | |
| 5672 | "UE","UN","UR","IX","BY",]) | |
| 5673 | ignore_set = set(["PD", "DT", | |
| 5373 | 5674 | # Undocumented and obscure |
| 5374 | "LO":1, "PU":1, "UC":1, "l":1, | |
| 5675 | "LO", "PU", "UC", "l", | |
| 5375 | 5676 | # Extensions from mtools doc set; we can safely ignore them |
| 5376 | "iX":1, "lp":1, | |
| 5677 | "iX", "lp", | |
| 5377 | 5678 | # fm is some kind of attribution extension in MIT pages |
| 5378 | "FM":1, | |
| 5679 | "FM", | |
| 5379 | 5680 | # Undocumented, used in the attr(3) man pages |
| 5380 | "Op":1, | |
| 5681 | "Op", | |
| 5381 | 5682 | # Occurs in X Consortium manpages redundant with .ta, |
| 5382 | # but not all such man pages have an identifiable X headers. | |
| 5383 | "TA":1,} | |
| 5384 | complain_set = {} | |
| 5385 | parabreak_set = {"blank":1,"P":1,"PP":1,"LP":1,"HP":1,"IP":1,"TP":1,} | |
| 5386 | sectionbreak_set = {"SH":1,"SS":1,} | |
| 5387 | listbreak_set = {"P":1,"PP":1,"LP":1,"HP":1,"IP":1,"TP":1,"SH":1,"SS":1,} | |
| 5388 | for thing in ip_tag_mapping.values(): | |
| 5389 | listbreak_set["IP+" + thing] = 1 | |
| 5683 | # but not all such man pages have an identifiable X header. | |
| 5684 | "TA",]) | |
| 5685 | complain_set = set([]) | |
| 5686 | parabreak_set = set(["blank","P","PP","LP","HP","IP","TP",]) | |
| 5687 | sectionbreak_set = set(["SH","SS",]) | |
| 5688 | listbreak_set = set(["P","PP","LP","HP","SH","SS",]) | |
| 5390 | 5689 | translations = { |
| 5391 | 5690 | "\\*" : [ |
| 5392 | 5691 | (r"\*R", "®"), |
| 5421 | 5720 | self.have_name = False |
| 5422 | 5721 | self.stash_linkender = None |
| 5423 | 5722 | self.manual = "" |
| 5723 | self.msrc = "" | |
| 5424 | 5724 | #self.systype = None |
| 5425 | 5725 | # .Id is used to embed RCS IDs in pages like ci.1. The |
| 5426 | 5726 | # effect we're after here is to make it a no-op, but allow it |
| 5451 | 5751 | self.source.unignore("HP") |
| 5452 | 5752 | self.source.unignore("RS") |
| 5453 | 5753 | self.source.unignore("RE") |
| 5454 | def interpret(self, line_unused, tokens, caller_unused): | |
| 5754 | def interpret(self, dummy_line, tokens, dummy_caller): | |
| 5455 | 5755 | cmd = tokens[0][1:] |
| 5456 | 5756 | args = tokens[1:] |
| 5457 | 5757 | # Highlighting |
| 5562 | 5862 | # it, so just barf. |
| 5563 | 5863 | try: |
| 5564 | 5864 | (name, description) = parse_name_section(namesect) |
| 5565 | except: | |
| 5865 | except (TypeError, ValueError): | |
| 5566 | 5866 | self.source.error("ill-formed NAME section '%s' in %s, giving up." % (namesect, self.source.file)) |
| 5567 | 5867 | return |
| 5568 | 5868 | self.source.emit("<refnamediv>") |
| 5572 | 5872 | self.source.emit("<refname>%s</refname>" % nid) |
| 5573 | 5873 | self.source.emit("<refpurpose>%s</refpurpose>"%description) |
| 5574 | 5874 | self.source.emit("</refnamediv>") |
| 5575 | elif filter(lambda x: synopsis_label.search(x), args) and \ | |
| 5576 | not self.source.synopsis: | |
| 5875 | elif filter(synopsis_label.search, args) and not self.source.synopsis: | |
| 5577 | 5876 | self.source.end_paragraph() |
| 5578 | 5877 | self.source.sectname = "SYNOPSIS" |
| 5579 | 5878 | self.source.ignore("RS") |
| 5584 | 5883 | self.source.ignore("Ip") # For Perl generated man pages |
| 5585 | 5884 | self.source.sectionhooks.append(self.end_synopsis) |
| 5586 | 5885 | try_synopsis = self.volnum != "3pm" and self.manual.find("Perl") == -1 or self.msrc.find("perl ") == -1 |
| 5587 | self.source.synopsis = DisplayParser(self.source, try_synopsis, self.refnames) | |
| 5886 | self.source.synopsis = DisplayParser(self.source, | |
| 5887 | try_synopsis, | |
| 5888 | False, | |
| 5889 | self.refnames) | |
| 5588 | 5890 | elif not self.source.synopsis and self.source.find(synopsis_header): |
| 5589 | 5891 | if section_verbosity in self.source.verbose: |
| 5590 | 5892 | self.source.notify("transplanting section...") |
| 5594 | 5896 | self.source.declare_body_start() |
| 5595 | 5897 | self.source.push_section(1, " ".join(args)) |
| 5596 | 5898 | elif cmd == "SS": |
| 5899 | self.source.diversion = self.source.output | |
| 5597 | 5900 | if not args: |
| 5598 | 5901 | args = self.source.popline().split() |
| 5599 | 5902 | if self.source.body_section(): |
| 5651 | 5954 | else: |
| 5652 | 5955 | self.source.end_paragraph(label=cmd) |
| 5653 | 5956 | # Discard second argument of IP tag |
| 5654 | args = [args[0]] | |
| 5957 | args = args[:1] | |
| 5655 | 5958 | # Some tags can turn into an ItemizedList. Give |
| 5656 | 5959 | # each type a different name, otherwise the lower-level |
| 5657 | 5960 | # machinery gets confused about list boundaries. |
| 5690 | 5993 | # Mark it on the stack so a following RE will pop it. |
| 5691 | 5994 | nextl = self.source.peekline() |
| 5692 | 5995 | if nextl and nextl.startswith(TroffInterpreter.ctrl + "nf"): |
| 5693 | self.source.pushlist("RS", explicit=True) | |
| 5996 | self.source.pushlist("RS") | |
| 5694 | 5997 | return True |
| 5695 | 5998 | # No markup for .nf+.RS, too, but note it on the stack |
| 5696 | 5999 | elif self.source.last_tag("<literallayout"): |
| 5697 | self.source.pushlist("RS", explicit=True) | |
| 6000 | self.source.pushlist("RS") | |
| 5698 | 6001 | return True |
| 5699 | 6002 | # If we're in list content, nest the list a level deeper |
| 5700 | 6003 | elif self.source.stash_indents: |
| 5701 | if not nextl.startswith(".TP") and not nextl.startswith(".IP"): | |
| 6004 | if nextl.startswith(".TP") or nextl.startswith(".IP"): | |
| 6005 | self.source.pushlist("RS", None) | |
| 6006 | else: | |
| 5702 | 6007 | self.source.begin_block("blockquote", remap='RS') |
| 5703 | self.source.pushlist("RS", "blockquote", explicit=True) | |
| 6008 | self.source.pushlist("RS", "blockquote") | |
| 5704 | 6009 | self.source.need_paragraph() |
| 5705 | 6010 | return True |
| 5706 | 6011 | # Next check for single-line .RS/.RE blocks. |
| 5717 | 6022 | self.source.pushline(text) |
| 5718 | 6023 | # Fall through |
| 5719 | 6024 | # None of the special cases fired. Punt; treat as blockquote |
| 5720 | self.source.pushlist("RS", "blockquote", explicit=True) | |
| 6025 | self.source.pushlist("RS", "blockquote") | |
| 5721 | 6026 | self.source.begin_block("blockquote", remap='RS') |
| 5722 | 6027 | elif cmd == "RE": |
| 5723 | self.source.poplist("blockquote", "RS") | |
| 6028 | self.source.poplist("RS", remap="RE") | |
| 5724 | 6029 | self.source.need_paragraph() |
| 5725 | 6030 | # FSF extension macros |
| 5726 | 6031 | elif cmd == "UE": # End of link text |
| 5766 | 6071 | self.source.pushline(self.source.index(map(deemphasize, args))) |
| 5767 | 6072 | # Ultrix extensions. Taken from groff's man.ultrix file |
| 5768 | 6073 | # Some of these (like EX/EE) appear in Linux manual pages. |
| 6074 | # The special guards on some of these avoid problems if, as is | |
| 6075 | # sometimes the case, the macros are defined specially in the file. | |
| 5769 | 6076 | # See http://www.geocrawler.com/archives/3/377/1992/10/0/2062814/ |
| 5770 | 6077 | # for an interesting historical sidelight. |
| 5771 | 6078 | elif cmd == "CT": |
| 5772 | 6079 | self.source.pushline("<CTRL/%s<" % args[0]) |
| 5773 | 6080 | elif cmd == "Ds": |
| 5774 | self.source.begin_block("literallayout", remap="Ds") | |
| 6081 | self.source.begin_block("literallayout", remap="Ds") | |
| 5775 | 6082 | elif cmd == "De": |
| 5776 | self.source.end_block("literallayout", remap="De", ends="Ds") | |
| 5777 | elif cmd == "EX": | |
| 6083 | self.source.end_block("literallayout", remap="De") | |
| 6084 | elif cmd == "EX" and "EX" not in self.source.troff.macros: | |
| 5778 | 6085 | self.source.begin_block("literallayout", remap="EX") |
| 5779 | elif cmd == "EE": | |
| 5780 | self.source.end_block("literallayout", remap="EE", ends="EX") | |
| 5781 | elif cmd == "NT": | |
| 6086 | elif cmd == "EE" and "EE" not in self.source.troff.macros: | |
| 6087 | self.source.end_block("literallayout", remap="EE") | |
| 6088 | elif cmd == "NT" and "NT" not in self.source.troff.macros: | |
| 5782 | 6089 | self.source.begin_block("note", remap="NT") |
| 5783 | elif cmd == "NE": | |
| 5784 | self.source.end_block("note", remap="NE", ends="NT") | |
| 6090 | elif cmd == "NE" and "NE" not in self.source.troff.macros: | |
| 6091 | self.source.end_block("note", remap="NE") | |
| 5785 | 6092 | elif cmd == "RN": |
| 5786 | 6093 | self.source.pushline("<keycap>RETURN</keycap>") |
| 5787 | 6094 | elif cmd == "PN": |
| 5818 | 6125 | # self.systype = "4.3 Berkeley Distribution" |
| 5819 | 6126 | # elif args[0] == "7": |
| 5820 | 6127 | # self.systype = "4.4 Berkeley Distribution" |
| 5821 | # mtools man pages use these...ugh | |
| 5822 | elif cmd == "(l": | |
| 5823 | self.source.pushline(TroffInterpreter.ctrl + "nf") | |
| 5824 | elif cmd == ")l": | |
| 5825 | self.source.pushline(TroffInterpreter.ctrl + "fi") | |
| 5826 | 6128 | # DS/DE isn't part of the man macros. Interpret it anyway, |
| 5827 | 6129 | # as there is an obvious meaning that people try to use. |
| 5828 | 6130 | elif cmd == "DS": |
| 5847 | 6149 | self.source.pushline("[" + " ".join(args) + "]") |
| 5848 | 6150 | elif cmd == "YS": |
| 5849 | 6151 | pass |
| 5850 | # Ghod knows where this came from. Moderately common typo for .EX/.EE | |
| 5851 | elif cmd == "Ex": | |
| 5852 | self.source.begin_block("literallayout", remap="Ex") | |
| 5853 | elif cmd == "Ee": | |
| 5854 | self.source.end_block("literallayout", remap="Ee", ends="Ex") | |
| 5855 | 6152 | # Use our reductions as fallbacks |
| 5856 | 6153 | elif cmd in ManInterpreter.reductions: |
| 5857 | 6154 | replace_with = ManInterpreter.reductions[cmd] |
| 5892 | 6189 | # Brain-damage emitted often by Pod2Man, occasionally by humans |
| 5893 | 6190 | text = re_compile("\\.PD.*\n+(.S[hHsS])").sub("\n\n\\1", text) |
| 5894 | 6191 | text = re_compile("\\.RS.*\n+(.S[hHsS])").sub("\n\n\\1", text) |
| 6192 | # Cheating way to avoid some annoying warnings on function pages | |
| 6193 | text = re_compile("(\\.in [+-][0-9]*n)?(\nFeature Test)", re.I).sub(".SH FEATURE TEST\n\n\\2", text) | |
| 5895 | 6194 | return text |
| 5896 | 6195 | def postprocess(self, text): |
| 5897 | 6196 | # Page might be generated crap with no sections, which can't be lifted. |
| 5905 | 6204 | # If there was no explicit URL markup, process implicit ones |
| 5906 | 6205 | if self.hack_urls and not self.source.is_active("mwww") and not xmlns_re.search(text): |
| 5907 | 6206 | text = url_re.sub(r"<ulink url='\g<url>'>\g<url></ulink>", text) |
| 5908 | # Pattern-based lifting in the final sections | |
| 5909 | if not self.source.is_active("mwww"): | |
| 5910 | foundit = text.rfind("AUTHOR") | |
| 5911 | if foundit > -1: | |
| 5912 | before = text[:foundit] | |
| 5913 | after = text[foundit:] | |
| 5914 | after = email_re.sub(r'<email>\1</email>', after) | |
| 5915 | text = before + after | |
| 5916 | 6207 | foundit = text.rfind("SEE ALSO") |
| 5917 | 6208 | if foundit > -1: |
| 5918 | 6209 | before = text[:foundit] |
| 5937 | 6228 | name = "pod2man" |
| 5938 | 6229 | exclusive = False |
| 5939 | 6230 | toptag = "refentry" |
| 5940 | immutable_set = {"Sp":1,"Ip":1,"Sh":1,"Vb":1,"Ve":1,} | |
| 5941 | ignore_set = {} | |
| 5942 | complain_set = {} | |
| 5943 | parabreak_set = {"Sp":1, "Ip":1,} | |
| 5944 | sectionbreak_set = {"Sh":1,} | |
| 5945 | listbreak_set = {"Ip":1,"Sh":1,} | |
| 6231 | immutable_set = set(["Sp","Ip","Sh","Vb","Ve",]) | |
| 6232 | ignore_set = set([]) | |
| 6233 | complain_set = set([]) | |
| 6234 | parabreak_set = set(["Sp", "Ip",]) | |
| 6235 | sectionbreak_set = set(["Sh",]) | |
| 6236 | listbreak_set = set(["Sh",]) | |
| 5946 | 6237 | translations = { |
| 5947 | 6238 | "\\*" : [ |
| 5948 | 6239 | (r'\*`', "´"), |
| 5967 | 6258 | def __init__(self, source, verbose=0): |
| 5968 | 6259 | self.source = source |
| 5969 | 6260 | self.verbose = verbose |
| 5970 | def interpret(self, line_unused, tokens, caller_unused): | |
| 6261 | def interpret(self, dummy_line, tokens, dummy_caller): | |
| 5971 | 6262 | cmd = tokens[0][1:] |
| 5972 | 6263 | args = tokens[1:] |
| 5973 | 6264 | # Sectioning |
| 6015 | 6306 | def postprocess(self, text): |
| 6016 | 6307 | return text |
| 6017 | 6308 | |
| 6018 | class reStructeredTextInterpreter: | |
| 6019 | "Interpret documents generated by reStructeredText." | |
| 6020 | name = "reStructeredText" | |
| 6309 | class reStructuredTextInterpreter: | |
| 6310 | "Interpret documents generated by reStructuredText." | |
| 6311 | name = "reStructuredText" | |
| 6021 | 6312 | exclusive = False |
| 6022 | 6313 | toptag = "refentry" |
| 6023 | immutable_set = {} | |
| 6024 | ignore_set = {} | |
| 6025 | complain_set = {} | |
| 6026 | parabreak_set = {} | |
| 6027 | sectionbreak_set = {} | |
| 6028 | listbreak_set = {} | |
| 6314 | immutable_set = set([]) | |
| 6315 | ignore_set = set([]) | |
| 6316 | complain_set = set([]) | |
| 6317 | parabreak_set = set([]) | |
| 6318 | sectionbreak_set = set([]) | |
| 6319 | listbreak_set = set([]) | |
| 6029 | 6320 | translations = {} |
| 6030 | 6321 | requires = [ManInterpreter] |
| 6031 | 6322 | def __init__(self, source, verbose=0): |
| 6032 | 6323 | self.source = source |
| 6033 | 6324 | self.verbose = verbose |
| 6034 | def interpret(self, line_unused, tokens, caller_unused): | |
| 6325 | def interpret(self, dummy_line, tokens, dummy_caller): | |
| 6035 | 6326 | cmd = tokens[0][1:] |
| 6036 | 6327 | # Ignore indent commands for now. It's possible we might |
| 6037 | 6328 | # want to map them to .RS/.RE later. |
| 6043 | 6334 | return False |
| 6044 | 6335 | return True |
| 6045 | 6336 | def preprocess(self, text): |
| 6046 | # Detect and strip out what reStructeredText wedges into the | |
| 6337 | # Detect and strip out what reStructuredText wedges into the | |
| 6047 | 6338 | # NAME section. All it does is define INDENT and UNINDENT; we |
| 6048 | 6339 | # can emulate those easily enough. |
| 6049 | 6340 | lines = text.split("\n") |
| 6050 | 6341 | savelines = [] |
| 6051 | 6342 | cookie = re_compile(r"nr rst2man-indent-level 0") |
| 6052 | 6343 | starter = re_compile(r"\.SH") |
| 6053 | while not cookie.search(lines[0]): | |
| 6344 | while lines and not cookie.search(lines[0]): | |
| 6054 | 6345 | savelines.append(lines.pop(0)) |
| 6055 | savelines.pop() | |
| 6056 | lines.pop(0) | |
| 6057 | while not starter.match(lines[0]): | |
| 6346 | if savelines: | |
| 6347 | savelines.pop() | |
| 6348 | if lines: | |
| 6058 | 6349 | lines.pop(0) |
| 6350 | while not starter.match(lines[0]): | |
| 6351 | lines.pop(0) | |
| 6059 | 6352 | savelines += lines |
| 6060 | 6353 | if len(savelines) == 1: |
| 6061 | raise LiftException("empty reStructeredText page") | |
| 6354 | raise LiftException("empty reStructuredText page") | |
| 6062 | 6355 | text = "\n".join(savelines) |
| 6063 | 6356 | return text |
| 6064 | 6357 | def postprocess(self, text): |
| 6069 | 6362 | name = "DocBook" |
| 6070 | 6363 | exclusive = False |
| 6071 | 6364 | toptag = "refentry" |
| 6072 | immutable_set = {} | |
| 6073 | ignore_set = {} | |
| 6074 | complain_set = {} | |
| 6075 | parabreak_set = {} | |
| 6076 | sectionbreak_set = {} | |
| 6077 | listbreak_set = {} | |
| 6365 | immutable_set = set([]) | |
| 6366 | ignore_set = set([]) | |
| 6367 | complain_set = set([]) | |
| 6368 | parabreak_set = set([]) | |
| 6369 | sectionbreak_set = set([]) | |
| 6370 | listbreak_set = set([]) | |
| 6078 | 6371 | translations = {} |
| 6079 | 6372 | requires = [ManInterpreter] |
| 6080 | 6373 | def __init__(self, source, verbose=0): |
| 6081 | 6374 | self.source = source |
| 6082 | 6375 | self.verbose = verbose |
| 6083 | def interpret(self, line_unused, tokens, caller_unused): | |
| 6376 | def interpret(self, dummy, tokens, dummy_caller): | |
| 6084 | 6377 | cmd = tokens[0][1:] |
| 6085 | 6378 | # The generated inclusion defines some new commands. |
| 6086 | 6379 | # We might want or need to interpret these sometime. |
| 6112 | 6405 | def postprocess(self, text): |
| 6113 | 6406 | return text |
| 6114 | 6407 | |
| 6408 | class FoojzsInterpreter: | |
| 6409 | "Interpret man pages with Rick Richardson's foojzs profile." | |
| 6410 | name = "foojzs" | |
| 6411 | exclusive = False | |
| 6412 | toptag = "refentry" | |
| 6413 | immutable_set = set([]) | |
| 6414 | ignore_set = set([]) | |
| 6415 | complain_set = set([]) | |
| 6416 | parabreak_set = set([]) | |
| 6417 | sectionbreak_set = set([]) | |
| 6418 | listbreak_set = set([]) | |
| 6419 | translations = {} | |
| 6420 | requires = [ManInterpreter] | |
| 6421 | def __init__(self, source, verbose=0): | |
| 6422 | self.source = source | |
| 6423 | self.verbose = verbose | |
| 6424 | def interpret(self, dummy, dummy_tokens, dummy_caller): | |
| 6425 | return False | |
| 6426 | def preprocess(self, text): | |
| 6427 | # Replace macro definitions in the header with blank lines. | |
| 6428 | # Better than removing them, because line numbers won't be perturbed. | |
| 6429 | lines = text.split("\n") | |
| 6430 | th = re_compile(r"\.TH") | |
| 6431 | starter = re_compile(r"\.SH") | |
| 6432 | i = 0 | |
| 6433 | while not th.search(lines[i]): | |
| 6434 | i += 1 | |
| 6435 | while not starter.search(lines[i]): | |
| 6436 | if not lines[i].startswith(r'.\"'): | |
| 6437 | lines[i] = '.\"' | |
| 6438 | i += 1 | |
| 6439 | text = "\n".join(lines) | |
| 6440 | return text | |
| 6441 | def postprocess(self, text): | |
| 6442 | return text | |
| 6443 | ||
| 6115 | 6444 | class XManInterpreter: |
| 6116 | 6445 | "Interpret local macros used in X documentation." |
| 6117 | 6446 | name = "XMan" |
| 6119 | 6448 | toptag = "refentry" |
| 6120 | 6449 | # Some of the X local macros (Ds, De, NT, NE, PN) are Ultrix extensions |
| 6121 | 6450 | # already handled by ManInterpreter. |
| 6122 | immutable_set = {"FD":1,"FN":1,"IN":1,"ZN":1,"hN":1} | |
| 6123 | ignore_set = {"IN":1} | |
| 6124 | complain_set = {} | |
| 6125 | parabreak_set = {} | |
| 6126 | sectionbreak_set = {} | |
| 6127 | listbreak_set = {} | |
| 6451 | immutable_set = set(["FD","FN","IN","ZN","hN"]) | |
| 6452 | ignore_set = set(["IN"]) | |
| 6453 | complain_set = set([]) | |
| 6454 | parabreak_set = set([]) | |
| 6455 | sectionbreak_set = set([]) | |
| 6456 | listbreak_set = set([]) | |
| 6128 | 6457 | translations = {} |
| 6129 | 6458 | reductions = {} |
| 6130 | 6459 | requires = [ManInterpreter] |
| 6132 | 6461 | self.source = source |
| 6133 | 6462 | self.verbose = verbose |
| 6134 | 6463 | self.source.troff.entities_from_strings = True |
| 6135 | def interpret(self, line_unused, tokens, caller_unused): | |
| 6464 | def interpret(self, dummy, tokens, dummy_caller): | |
| 6136 | 6465 | cmd = tokens[0][1:] |
| 6137 | 6466 | args = tokens[1:] |
| 6138 | 6467 | # .Ds and .De are already handled by ManInterpreter |
| 6140 | 6469 | # This wants to be a keep, but DocBook can't express that. |
| 6141 | 6470 | self.source.begin_block("literallayout", remap="FD") |
| 6142 | 6471 | elif cmd == "FN": |
| 6143 | self.source.end_block("literallayout", remap="FN", ends="FD") | |
| 6472 | self.source.end_block("literallayout", remap="FN") | |
| 6144 | 6473 | elif cmd == "ZN": |
| 6145 | 6474 | self.source.pushline("<symbol role='ZN'>%s</symbol>%s" % (args[0], "".join(args[1:]))) |
| 6146 | 6475 | elif cmd == "Pn": |
| 6150 | 6479 | elif cmd == "C{": |
| 6151 | 6480 | self.source.begin_block("programlisting", remap="C{") |
| 6152 | 6481 | elif cmd == "C}": |
| 6153 | self.source.end_block("programlisting", remap="C}", ends="C{") | |
| 6482 | self.source.end_block("programlisting", remap="C}") | |
| 6154 | 6483 | elif cmd == "NT": |
| 6155 | 6484 | self.source.begin_block("note", remap="NT") |
| 6156 | 6485 | elif cmd == "NE": |
| 6157 | self.source.end_block("note", remap="NE", ends="NT") | |
| 6486 | self.source.end_block("note", remap="NE") | |
| 6158 | 6487 | else: |
| 6159 | 6488 | return False |
| 6160 | 6489 | return True |
| 6178 | 6507 | def postprocess(self, text): |
| 6179 | 6508 | return text |
| 6180 | 6509 | |
| 6510 | class ASTInterpreter: | |
| 6511 | "Interpret macros used in Bell Labs AST and the derived version at CERN." | |
| 6512 | name = "AST/CERN" | |
| 6513 | exclusive = False | |
| 6514 | toptag = "refentry" | |
| 6515 | immutable_set = set(["FN", "DS", "DE"]) | |
| 6516 | ignore_set = set(["SP"]) | |
| 6517 | complain_set = set([]) | |
| 6518 | parabreak_set = set([]) | |
| 6519 | sectionbreak_set = set([]) | |
| 6520 | listbreak_set = set([]) | |
| 6521 | translations = {} | |
| 6522 | reductions = {} | |
| 6523 | requires = [ManInterpreter] | |
| 6524 | def __init__(self, source, verbose=0): | |
| 6525 | self.source = source | |
| 6526 | self.verbose = verbose | |
| 6527 | self.source.troff.entities_from_strings = True | |
| 6528 | self.headerset = set([]) | |
| 6529 | assert self.source.interpreters[0].name == "man" | |
| 6530 | def interpret(self, dummy, tokens, dummy_caller): | |
| 6531 | cmd = tokens[0][1:] | |
| 6532 | args = tokens[1:] | |
| 6533 | if cmd in ("H0", "H1", "H2", "H3", "H4"): | |
| 6534 | self.headerset.add(cmd) | |
| 6535 | self.source.push_section(len(self.headerset)+1, " ".join(args)) | |
| 6536 | elif cmd == "OP": | |
| 6537 | # Here's what we're emulating: | |
| 6538 | # | |
| 6539 | # .de OP | |
| 6540 | # .nr mH 0 | |
| 6541 | # .ie !'\\$1'-' \{ | |
| 6542 | # .ds mO \\fB\\-\\$1\\fP | |
| 6543 | # .ds mS ,\\0 | |
| 6544 | # .\} | |
| 6545 | # .el \{ | |
| 6546 | # .ds mO \\& | |
| 6547 | # .ds mS \\& | |
| 6548 | # .\} | |
| 6549 | # .ie '\\$2'-' \{ | |
| 6550 | # .if !'\\$4'-' .as mO \\0\\fI\\$4\\fP | |
| 6551 | # .\} | |
| 6552 | # .el \{ | |
| 6553 | # .as mO \\*(mS\\fB\\-\\-\\$2\\fP | |
| 6554 | # .if !'\\$4'-' .as mO =\\fI\\$4\\fP | |
| 6555 | # .\} | |
| 6556 | # .in 5n | |
| 6557 | # \\*(mO | |
| 6558 | # .in 9n | |
| 6559 | # .. | |
| 6560 | # | |
| 6561 | # And here's how I interpret it: | |
| 6562 | # | |
| 6563 | # 1. Takes exactly three or four arguments. | |
| 6564 | # | |
| 6565 | # 2. The first argument is interpreted as a | |
| 6566 | # single-character option name; should be given without | |
| 6567 | # the preceding '-', but is emitted in the resulting | |
| 6568 | # output with a preceding '-'. | |
| 6569 | # | |
| 6570 | # 3. If the second and fourth arguments are '-', no | |
| 6571 | # further output is emitted. | |
| 6572 | # | |
| 6573 | # 4. If the second argument is '-' but the fourth is not, | |
| 6574 | # a space followed by the fourth argument set in italics is emitted. | |
| 6575 | # | |
| 6576 | # 5. If the second argument is not '-', it is omitted with | |
| 6577 | # '--' prepended (as the name of a long option) after a | |
| 6578 | # comma and space. Then, if the fourth argument is not | |
| 6579 | # null, it is interpreted as a metavariable name | |
| 6580 | # describing a long-option value and emitted in italics | |
| 6581 | # following a '='. | |
| 6582 | # | |
| 6583 | # 6. The third argument is ignored and serves only as | |
| 6584 | # documentation of the option type. | |
| 6585 | if len(args) < 3: | |
| 6586 | self.source.error("expected at least three arguments for .OP") | |
| 6587 | elif len(args) < 4: | |
| 6588 | args.append("-") | |
| 6589 | options = ['-' + args[0]] | |
| 6590 | if args[1] == '-': | |
| 6591 | if args[3] != '-': | |
| 6592 | options[0] += " <emphasis>%s</emphasis>" % args[3] | |
| 6593 | else: | |
| 6594 | options.append("--" + args[1]) | |
| 6595 | if args[3] != '-': | |
| 6596 | options[1] += "=<emphasis>%s</emphasis>" % args[3] | |
| 6597 | self.source.emit_variablelist("OP", options) | |
| 6598 | elif cmd in ("SH", "SS"): | |
| 6599 | self.headerset = set([]) | |
| 6600 | self.source.interpreters[1].interpret(dummy, tokens, dummy_caller) | |
| 6601 | else: | |
| 6602 | return False | |
| 6603 | return True | |
| 6604 | def preprocess(self, text): | |
| 6605 | # Detect and strip out standard X macro preamble. | |
| 6606 | if text.find(".de H0\n") == -1: | |
| 6607 | self.source.error("AST/CERN preamble not found where expected.") | |
| 6608 | else: | |
| 6609 | stripped = [] | |
| 6610 | lines = text.split("\n") | |
| 6611 | while not lines[0].startswith(TroffInterpreter.ctrl + "de H0"): | |
| 6612 | stripped.append(lines.pop(0)) | |
| 6613 | self.source.lineno += 1 | |
| 6614 | while not lines[0].startswith(TroffInterpreter.ctrl + "SH NAME"): | |
| 6615 | lines.pop(0) | |
| 6616 | self.source.lineno += 1 | |
| 6617 | return "\n".join(stripped + lines) | |
| 6618 | def postprocess(self, text): | |
| 6619 | return text | |
| 6620 | ||
| 6181 | 6621 | class TkManInterpreter: |
| 6182 | 6622 | "Interpret Tk manual emulation macros." |
| 6183 | 6623 | name = "tkman" |
| 6184 | 6624 | exclusive = False |
| 6185 | 6625 | toptag = "refentry" |
| 6186 | immutable_set = {"AP":1,"AS":1,"AS":1,"BS":1,"BE":1,"CS":1,"CE":1, | |
| 6187 | "VS":1,"VE":1,"DS":1,"DE":1,"SO":1,"SE":1,"OP":1, | |
| 6188 | "UL":1,"^B":1,} | |
| 6189 | ignore_set = {} | |
| 6190 | complain_set = {} | |
| 6191 | parabreak_set = {"AP":1,} | |
| 6192 | sectionbreak_set = {} | |
| 6193 | listbreak_set = {} | |
| 6626 | immutable_set = set(["AP","AS","BS","BE","CS","CE", | |
| 6627 | "VS","VE","DS","DE","SO","SE","OP", | |
| 6628 | "UL","^B","QW","PQ"]) | |
| 6629 | ignore_set = set([]) | |
| 6630 | complain_set = set([]) | |
| 6631 | parabreak_set = set(["AP",]) | |
| 6632 | sectionbreak_set = set([]) | |
| 6633 | listbreak_set = set([]) | |
| 6194 | 6634 | translations = {} |
| 6195 | 6635 | requires = [ManInterpreter] |
| 6196 | 6636 | def __init__(self, source, verbose=0): |
| 6197 | 6637 | self.source = source |
| 6198 | 6638 | self.verbose = verbose |
| 6199 | def interpret(self, line_unused, tokens, caller_unused): | |
| 6639 | def interpret(self, dummy, tokens, dummy_caller): | |
| 6200 | 6640 | cmd = tokens[0][1:] |
| 6201 | 6641 | args = tokens[1:] |
| 6202 | 6642 | # Documentation for these is taken from the wish.1 header. |
| 6272 | 6712 | # by tabs. |
| 6273 | 6713 | # .SE |
| 6274 | 6714 | # End of list of standard options for a Tk widget. |
| 6275 | elif cmd == "SO": | |
| 6715 | elif cmd == "SO": | |
| 6276 | 6716 | self.source.push_section(1, 'STANDARD OPTIONS') |
| 6277 | 6717 | self.source.pushline("l l l l.") |
| 6278 | 6718 | self.source.TBL(TroffInterpreter.ctrl + "SE") |
| 6279 | elif cmd == "OP": | |
| 6719 | elif cmd == "OP": | |
| 6280 | 6720 | # .OP cmdName dbName dbClass |
| 6281 | 6721 | # Start of description of a specific option. cmdName gives the |
| 6282 | 6722 | # option's name as specified in the class command, dbName gives |
| 6291 | 6731 | # Print arg1 underlined, then print arg2 normally. |
| 6292 | 6732 | elif cmd == "UL": |
| 6293 | 6733 | self.source.pushline("<emphasis remap='U'>%s</emphasis>%s"%(args[0],args[1])) |
| 6734 | # .QW arg1 ?arg2? | |
| 6735 | # Print arg1 in quotes, then arg2 normally (for trailing punctuation). | |
| 6736 | # | |
| 6737 | elif cmd == "QW": | |
| 6738 | if len(args) == 1: | |
| 6739 | args.append("") | |
| 6740 | self.source.emit("<quote>%s</quote>%s" % (args[0], args[1])) | |
| 6741 | # .PQ arg1 ?arg2? | |
| 6742 | # Print an open parenthesis, arg1 in quotes, then arg2 normally | |
| 6743 | # (for trailing punctuation) and then a closing parenthesis. | |
| 6744 | elif cmd == "PQ": | |
| 6745 | if len(args) == 1: | |
| 6746 | args.append("") | |
| 6747 | self.source.emit("(<quote>%s</quote>%s)" % (args[0], args[1])) | |
| 6294 | 6748 | else: |
| 6295 | 6749 | return False |
| 6296 | 6750 | return True |
| 6304 | 6758 | name = "mdoc" |
| 6305 | 6759 | exclusive = True |
| 6306 | 6760 | toptag = "refentry" |
| 6307 | immutable_set = {} | |
| 6308 | ignore_set = {"blank":1, "Bk":1, "Ek":1,} | |
| 6309 | complain_set = {"Cd":1,"Db":1,} | |
| 6310 | parabreak_set = {"Pp":1,} | |
| 6311 | sectionbreak_set = {"Sh":1, "Ss":1} | |
| 6312 | listbreak_set = {} | |
| 6761 | immutable_set = set([]) | |
| 6762 | ignore_set = set(["blank", "Bk", "Ek",]) | |
| 6763 | complain_set = set(["Db",]) | |
| 6764 | parabreak_set = set(["Pp",]) | |
| 6765 | sectionbreak_set = set(["Sh", "Ss"]) | |
| 6766 | listbreak_set = set([]) | |
| 6313 | 6767 | translations = { |
| 6314 | 6768 | "\\*" : [ |
| 6315 | 6769 | (r"\*q", '"'), |
| 6325 | 6779 | (r"\*(Gt", ">"), |
| 6326 | 6780 | (r"\*(Pm", "±"), |
| 6327 | 6781 | (r"\*(If", "∞"), |
| 6782 | (r"\*(Am", "&"), | |
| 6328 | 6783 | (r"\*(Na", "NaN"), |
| 6329 | 6784 | (r"\*(Ba", "|"), |
| 6330 | ] | |
| 6785 | (r"\*(ga", "`"), | |
| 6786 | (r"\*(aa", "´"), | |
| 6787 | (r"\*(ua", "↑"), | |
| 6788 | (r"\*(ua", "↑"), | |
| 6789 | (r"\*(>=", "≥"), | |
| 6790 | (r"\*(<=", "≤"), | |
| 6791 | ], | |
| 6792 | "\\*[" : [ | |
| 6793 | (r"\*[Lq]", "“"), # ISOnum | |
| 6794 | (r"\*[Rq]", "”"), # ISOpub | |
| 6795 | (r"\*[Pi]", "&pgrk;"), | |
| 6796 | (r"\*[Ne]", "≠"), | |
| 6797 | (r"\*[Le]", "≤"), | |
| 6798 | (r"\*[Ge]", "≥"), | |
| 6799 | (r"\*[Lt]", "<"), | |
| 6800 | (r"\*[Gt]", ">"), | |
| 6801 | (r"\*[Pm]", "±"), | |
| 6802 | (r"\*[If]", "∞"), | |
| 6803 | (r"\*[Am]", "&"), | |
| 6804 | (r"\*[Na]", "NaN"), | |
| 6805 | (r"\*[Ba]", "|"), | |
| 6806 | (r"\*[ga]", "`"), | |
| 6807 | (r"\*[aa]", "´"), | |
| 6808 | (r"\*[ua]", "↑"), | |
| 6809 | (r"\*[q]", "'"), | |
| 6810 | (r"\*[ua]", "↑"), | |
| 6811 | (r"\*[>=]", "≥"), | |
| 6812 | (r"\*[<=]", "≤"), | |
| 6813 | (r"\*[operating-system]", "BSD"), | |
| 6814 | (r"\*[volume-operating-system]", "BSD"), | |
| 6815 | (r"\*[volume-as-i386]", "i386"), | |
| 6816 | (r"\*[volume-ds-1]", "1"), | |
| 6817 | (r"\*[volume-ds-2]", "2"), | |
| 6818 | (r"\*[volume-ds-3]", "3"), | |
| 6819 | (r"\*[volume-ds-4]", "4"), | |
| 6820 | (r"\*[volume-ds-5]", "5"), | |
| 6821 | (r"\*[volume-ds-6]", "6"), | |
| 6822 | (r"\*[volume-ds-7]", "7"), | |
| 6823 | (r"\*[volume-ds-8]", "8"), | |
| 6824 | (r"\*[volume-ds-9]", "9"), | |
| 6825 | (r"\*[volume-ds-USD", "User's Supplementary Documents"), | |
| 6826 | (r"\*[volume-ds-PS1", "Programmer's Supplementary Documents"), | |
| 6827 | (r"\*[volume-ds-AMD", "Ancestral Manual Documents"), | |
| 6828 | (r"\*[volume-ds-SMM", "System Manager's Manual"), | |
| 6829 | (r"\*[volume-ds-URM", "User's Reference Manual"), | |
| 6830 | (r"\*[volume-ds-PRM", "Programmer's Manual"), | |
| 6831 | (r"\*[volume-ds-KM", "Kernel Manual"), | |
| 6832 | (r"\*[volume-ds-IND", "Manual Master Index"), | |
| 6833 | (r"\*[volume-ds-LOCAL", "Local Manual"), | |
| 6834 | (r"\*[volume-ds-CON", "Contributed Software Manual"), | |
| 6835 | ], | |
| 6331 | 6836 | } |
| 6332 | 6837 | # These are listed in the order they appear on the mdoc(7) man page, |
| 6333 | # except for .Fl, .Nd, %N, %D, %O, Lb, St, which are missing from | |
| 6838 | # except for .Fl, .Nd, %N, %D, %O, Lb, St, Ms, which are missing from | |
| 6334 | 6839 | # those tables. Ai and Px are not documented at all. |
| 6335 | 6840 | # Also we have to treat Sm as parseable even through it isn't. |
| 6336 | parsed = {"Ad":1,"Ai":1,"An":1,"Ar":1,"Cm":1,"Dv":1,"Er":1,"Ev":1,"Fa":1, | |
| 6337 | "Fl":1,"Ic":1,"Lb":1,"Li":1,"Nd":1, | |
| 6338 | "Nm":1,"Op":1,"Oo":1,"Oc":1,"Ot":1,"Pa":1,"St":1,"Va":1, | |
| 6339 | "Vt":1,"Xr":1,"%A":1,"%B":1,"%D":1,"%J":1,"%N":1,"%O":1,"%Q":1, | |
| 6340 | "%R":1,"%T":1,"Ac":1,"Ao":1,"Ap":1,"Aq":1,"Bc":1,"Bo":1,"Bq":1, | |
| 6341 | "Brq":1,"Bx":1,"Dc":1,"Do":1,"Dq":1,"Ec":1,"Em":1,"Eo":1,"Eq":1, | |
| 6342 | "No":1,"Ns":1,"Pc":1,"Pf":1,"Po":1,"Pq":1,"Px":1,"Qc":1, | |
| 6343 | "Ql":1,"Qo":1,"Qq":1,"Sc":1,"Sc":1,"Sm":1,"So":1,"Sq":1,"St":1, | |
| 6344 | "Sx":1,"Sy":1,"Ta":1,"Tn":1,"Ux":1,"Xc":1,"Xo":1,} | |
| 6345 | callable = {"Ad":1,"Ai":1,"An":1,"Ar":1,"Cm":1,"Dv":1,"Er":1,"Ev":1, | |
| 6346 | "Fa":1,"Fd":1,"Fl":1,"Fo":1,"Fc":1,"Ic":1,"Lb":1,"Li":1,"Nm":1, | |
| 6347 | "Oc":1,"0o":1,"Op":1,"Ot":1,"Pa":1,"St":1,"Va":1,"Vt":1,"Xr":1, | |
| 6348 | "%B":1,"%T":1,"Ac":1,"Ao":1,"Ap":1,"Aq":1,"Bc":1,"Bo":1, | |
| 6349 | "Bq":1,"Bx":1,"Dc":1,"Do":1,"Dq":1,"Ec":1,"Em":1,"Eo":1, | |
| 6350 | "No":1,"Ns":1,"Pc":1,"Po":1,"Pq":1,"Px":1,"Qc":1,"Ql":1, | |
| 6351 | "Qo":1,"Qq":1,"Sc":1,"So":1,"Sq":1,"St":1,"Sx":1,"Sy":1, | |
| 6352 | "Ta":1,"Tn":1,"Ux":1,"Xc":1,"Xo":1,} | |
| 6841 | parsed = set(["Ad","Ai","An","Ar","Cm","Dv","Er","Ev","Fa", | |
| 6842 | "Fl","Ic","Lb","Li","Nd", "Ms", | |
| 6843 | "Nm","Op","Oo","Oc","Ot","Pa","Va", | |
| 6844 | "Vt","Xr","%A","%B","%D","%J","%N","%O","%Q", | |
| 6845 | "%R","%T","Ac","Ao","Ap","Aq","Bc","Bo","Bq", | |
| 6846 | "Brq","Bx","Dc","Do","Dq","Ec","Em","Eo","Eq", | |
| 6847 | "No","Mt","Ns","Pc","Pf","Po","Pq","Px","Qc", | |
| 6848 | "Ql","Qo","Qq","Sc","Sm","So","Sq","St", | |
| 6849 | "Sx","Sy","Ta","Tn","Ux","Xc","Xo",]) | |
| 6850 | callable = set(["Ad","Ai","An","Ar","Cm","Dv","Er","Ev", | |
| 6851 | "Fa","Fd","Fl","Fo","Fc","Ic","Lb","Li","Ms","Nm", | |
| 6852 | "Oc","Oo","Op","Ot","Pa","Va","Vt","Xr", | |
| 6853 | "%B","%T","Ac","Ao","Ap","Aq","Bc","Bo", | |
| 6854 | "Bq","Bx","Dc","Do","Dq","Ec","Em","Eo", | |
| 6855 | "Mt","No","Ns","Pc","Po","Pq","Px","Qc","Ql", | |
| 6856 | "Qo","Qq","Sc","So","Sq","St","Sx","Sy", | |
| 6857 | "Ta","Tn","Ux","Xc","Xo",]) | |
| 6353 | 6858 | # Substitution strings for the St request |
| 6354 | 6859 | st_dict = { |
| 6355 | 6860 | # ANSI/ISO C |
| 6358 | 6863 | "-isoC": "ISO/IEC 9899:1990 (ISO C 89)", |
| 6359 | 6864 | "-isoC-90": "ISO/IEC 9899:1999 (ISO C 90)", |
| 6360 | 6865 | "-isoC-99": "ISO/IEC 9899:1999 (ISO C 99)", |
| 6866 | "-isoC-2011": "ISO/IEC 9899:2011 (\"ISO C11\")", | |
| 6361 | 6867 | # POSIX Part 1: System API |
| 6362 | 6868 | "-p1003.1": "IEEE Std 1003.1 (POSIX.1)", |
| 6363 | 6869 | "-p1003.1-88": "IEEE Std 1003.1-1988 (POSIX.1)", |
| 6371 | 6877 | "-p1003.1g-2000": "IEEE Std 1003.1g-2000 (POSIX.1)", |
| 6372 | 6878 | "-p1003.1-2001": "IEEE Std 1003.1-2001 (POSIX.1)", |
| 6373 | 6879 | "-p1003.1-2004": "IEEE Std 1003.1-2004 (POSIX.1)", |
| 6880 | "-p1003.1-2008": "IEEE Std 1003.1-2008 (POSIX.1)", | |
| 6374 | 6881 | |
| 6375 | 6882 | # POSIX Part 2: Shell and Utilities |
| 6376 | 6883 | "-p1003.2": "IEEE Std 1003.2 (POSIX.2)", |
| 6380 | 6887 | |
| 6381 | 6888 | # X/Open |
| 6382 | 6889 | "-susv2": "Version 2 of the Single UNIX Specification (SuSv2)", |
| 6890 | "-susv3": "Version 3 of the Single UNIX Specification (SuSv2)", | |
| 6383 | 6891 | "-svid4": "System V Interface Definition, Fourth Edition (SVID)", |
| 6384 | 6892 | "-xbd5": "X/Open System Interface Definitions Issue 5 (XBD 5)", |
| 6385 | 6893 | "-xcu5": "X/Open Commands and Utilities Issue 5 (XCU 5)", |
| 6397 | 6905 | } |
| 6398 | 6906 | |
| 6399 | 6907 | lb_dict = { |
| 6908 | "libarchive": "Reading and Writing Streaming Archives Library (libarchive, -larchive)", | |
| 6400 | 6909 | "libarm": "ARM Architecture Library (libarm, -larm)", |
| 6401 | 6910 | "libarm32": "ARM32 Architecture Library (libarm32, -larm32)", |
| 6911 | "libbluetooth": "Bluetooth Library (libbluetooth, -lbluetooth)", | |
| 6912 | "libbsm": "Basic Security Module Library (libbsm, -lbsm)", | |
| 6402 | 6913 | "libc": "Standard C Library (libc, -lc)", |
| 6914 | "libc_r": "Reentrant C Library (libc_r, -lc_r)", | |
| 6915 | "libcalendar": "Calendar Arithmetic Library (libcalendar, -lcalendar)", | |
| 6916 | "libcam": "Common Access Method User Library (libcam, -lcam)", | |
| 6403 | 6917 | "libcdk": "Curses Development Kit Library (libcdk, -lcdk)", |
| 6918 | "libcipher": "FreeSec Crypt Library (libcipher, -lcipher)", | |
| 6404 | 6919 | "libcompat": "Compatibility Library (libcompat, -lcompat)", |
| 6405 | 6920 | "libcrypt": "Crypt Library (libcrypt, -lcrypt)", |
| 6406 | 6921 | "libcurses": "Curses Library (libcurses, -lcurses)", |
| 6922 | "libdevinfo": "Device and Resource Information Utility Library (libdevinfo, -ldevinfo)", | |
| 6923 | "libdevstat": "Device Statistics Library (libdevstat, -ldevstat)", | |
| 6924 | "libdisk": "Interface to Slice and Partition Labels Library (libdisk, -ldisk)", | |
| 6925 | "libdwarf": "DWARF Access Library (libdwarf, -ldwarf)", | |
| 6407 | 6926 | "libedit": "Command Line Editor Library (libedit, -ledit)", |
| 6927 | "libelf": "ELF Access Library (libelf, -lelf)", | |
| 6408 | 6928 | "libevent": "Event Notification Library (libevent, -levent)", |
| 6929 | "libfetch": "File Transfer Library for URLs (libfetch, -lfetch)", | |
| 6409 | 6930 | "libform": "Curses Form Library (libform, -lform)", |
| 6931 | "libgeom": "Userland API Library for kernel GEOM subsystem (libgeom, -lgeom)", | |
| 6932 | "libgpib": "General-Purpose Instrument Bus (GPIB) library (libgpib, -lgpib)", | |
| 6410 | 6933 | "libi386": "i386 Architecture Library (libi386, -li386)", |
| 6411 | 6934 | "libintl": "Internationalized Message Handling Library (libintl, -lintl)", |
| 6412 | 6935 | "libipsec": "IPsec Policy Control Library (libipsec, -lipsec)", |
| 6413 | "libkvm": "Kernel Data Access Library (libkvm, -lkvm)", | |
| 6936 | "libipx": "IPX Address Conversion Support Library (libipx, -lipx)", | |
| 6937 | "libiscsi": "iSCSI protocol library (libiscsi, -liscsi)", | |
| 6938 | "libjail": "Jail Library (libjail, -ljail)", | |
| 6939 | "libkiconv": "Kernel side iconv library (libkiconv, -lkiconv)", | |
| 6940 | "libkse": "N:M Threading Library (libkse, -lkse)", | |
| 6941 | "libkvm": "Kernel Data Access Library (libkvm, -lkvm)", | |
| 6414 | 6942 | "libm": "Math Library (libm, -lm)", |
| 6943 | "libmd": "Message Digest (MD4, MD5, etc.) Support Library (libmd, -lmd)", | |
| 6415 | 6944 | "libm68k": "m68k Architecture Library (libm68k, -lm68k)", |
| 6416 | 6945 | "libmagic": "Magic Number Recognition Library (libmagic, -lmagic)", |
| 6946 | "libmemstat": "Kernel Memory Allocator Statistics Library (libmemstat, -lmemstat)", | |
| 6417 | 6947 | "libmenu": "Curses Menu Library (libmenu, -lmenu)", |
| 6418 | "libossaudio": "OSS Audio Emulation Library (libossaudio, -lossaudio)", | |
| 6948 | "libnetgraph": "Netgraph User Library (libnetgraph, -lnetgraph)", | |
| 6949 | "libnetpgp": "Netpgp signing, verification, encryption and decryption (libnetpgp, -lnetpgp)", | |
| 6950 | "libossaudio": "OSS Audio Emulation Library (libossaudio, -lossaudio)", | |
| 6419 | 6951 | "libpam": "Pluggable Authentication Module Library (libpam, -lpam)", |
| 6420 | 6952 | "libpcap": "Packet Capture Library (libpcap, -lpcap)", |
| 6421 | 6953 | "libpci": "PCI Bus Access Library (libpci, -lpci)", |
| 6422 | 6954 | "libpmc": "Performance Counters Library (libpmc, -lpmc)", |
| 6423 | 6955 | "libposix": "POSIX Compatibility Library (libposix, -lposix)", |
| 6956 | "libprop": "Property Container Object Library (libprop, -lprop)", | |
| 6424 | 6957 | "libpthread": "POSIX Threads Library (libpthread, -lpthread)", |
| 6958 | "libpuffs": "puffs Convenience Library (libpuffs, -lpuffs)", | |
| 6959 | "librefuse": "File System in Userspace Convenience Library (librefuse, -lrefuse)", | |
| 6425 | 6960 | "libresolv": "DNS Resolver Library (libresolv, -lresolv)", |
| 6961 | "librpcsec_gss":"RPC GSS-API Authentication Library (librpcsec_gss, -lrpcsec_gss)", | |
| 6962 | "librpcsvc": "RPC Service Library (librpcsvc, -lrpcsvc)", | |
| 6426 | 6963 | "librt": "POSIX Real-time Library (librt, -lrt)", |
| 6964 | "libsdp": "Bluetooth Service Discovery Protocol User Library (libsdp, -lsdp)", | |
| 6965 | "libssp": "Buffer Overflow Protection Library (libssp, -lssp)", | |
| 6966 | "libSystem": "System Library (libSystem, -lSystem)", | |
| 6427 | 6967 | "libtermcap": "Termcap Access Library (libtermcap, -ltermcap)", |
| 6968 | "libterminfo": "Terminal Information Library (libterminfo, -lterminfo)", | |
| 6969 | "libthr": "1:1 Threading Library (libthr, -lthr)", | |
| 6970 | "libufs": "UFS File System Access Library (libufs, -lufs)", | |
| 6971 | "libugidfw": "File System Firewall Interface Library (libugidfw, -lugidfw)", | |
| 6972 | "libulog": "User Login Record Library (libulog, -lulog)", | |
| 6428 | 6973 | "libusbhid": "USB Human Interface Devices Library (libusbhid, -lusbhid)", |
| 6429 | 6974 | "libutil": "System Utilities Library (libutil, -lutil)", |
| 6975 | "libvgl": "Video Graphics Library (libvgl, -lvgl)", | |
| 6430 | 6976 | "libx86_64": "x86_64 Architecture Library (libx86_64, -lx86_64)", |
| 6431 | 6977 | "libz": "Compression Library (libz, -lz)", |
| 6432 | 6978 | } |
| 6433 | openers = {"(":1, "[":1} | |
| 6434 | closers = {".":1, ",":1, ";":1, ")":1, "]":1,} | |
| 6979 | openers = set(["(", "["]) | |
| 6980 | closers = set([".", ",", ";", ")", "]",]) | |
| 6435 | 6981 | def __init__(self, source, verbose=0): |
| 6436 | 6982 | self.source = source |
| 6437 | 6983 | self.verbose = verbose |
| 6443 | 6989 | self.os = None # .Os |
| 6444 | 6990 | self.name = None # .Nm |
| 6445 | 6991 | self.desc = None # .Nd |
| 6992 | self.manual = "" | |
| 6446 | 6993 | self.msrc = "" |
| 6447 | 6994 | # Other internal state |
| 6448 | 6995 | self.tokens = [] |
| 6449 | 6996 | self.liststack = [] |
| 6997 | self.bdstack = [] | |
| 6450 | 6998 | self.itemcount = [] |
| 6451 | 6999 | self.suppress_callables = False |
| 6452 | 7000 | self.spacemode = True |
| 6480 | 7028 | return False |
| 6481 | 7029 | else: |
| 6482 | 7030 | return True |
| 6483 | def interpret(self, line_unused, tokens, caller_unused): | |
| 7031 | def interpret(self, dummy, tokens, dummy_caller): | |
| 6484 | 7032 | tokens[0] = tokens[0][1:] |
| 6485 | 7033 | # First, collect any additional arguments implied by o/c enclosures. |
| 6486 | 7034 | for c in ("A", "B", "D", "O", "P", "Q", "S", "X"): |
| 6488 | 7036 | while True: |
| 6489 | 7037 | line = self.source.popline() |
| 6490 | 7038 | newtokens = lineparse(line) |
| 6491 | tokens.append("\n") | |
| 7039 | #tokens.append("\n") | |
| 6492 | 7040 | if newtokens is None: |
| 6493 | 7041 | tokens.append("No") |
| 6494 | 7042 | tokens.append(line) |
| 6505 | 7053 | args = tokens[1:] |
| 6506 | 7054 | # First, check parsed/callable macros |
| 6507 | 7055 | if command in MdocInterpreter.parsed: |
| 6508 | self.source.pushline(self.eval(tokens)) | |
| 7056 | self.source.pushline(self.macroeval(tokens)) | |
| 6509 | 7057 | # These aren't in the parsed/callable set in mdoc(7) |
| 6510 | 7058 | elif command == "At": |
| 6511 | 7059 | self.source.pushline("<productname>AT&T Unix</productname>") |
| 6515 | 7063 | else: |
| 6516 | 7064 | version = "" |
| 6517 | 7065 | self.source.pushline("<productname>BSD/OS%s</productname>" % version) |
| 7066 | elif command == "Bt": | |
| 7067 | self.source.emit("is currently in beta test.") | |
| 7068 | elif command == "Cd": | |
| 7069 | ||
| 7070 | if self.source.in_synopsis(): | |
| 7071 | self.source.pushline(".br") | |
| 7072 | self.source.pushline(" ".join(args)) | |
| 7073 | self.source.pushline(".br") | |
| 7074 | else: | |
| 7075 | self.source.pushline(r"\fB" + " ".join(args) + r"\fP") | |
| 6518 | 7076 | elif command == "Fx": |
| 6519 | 7077 | if args: |
| 6520 | 7078 | version = " " + args[0] |
| 6541 | 7099 | self.source.pushline("<productname>DragonFly%s</productname>" % version) |
| 6542 | 7100 | elif command in ("Dl", "D1"): |
| 6543 | 7101 | if self.hasargs(command, args): |
| 6544 | self.source.pushline("<phrase role='%s'>%s</phrase>" % (command, self.eval(["No"] + args))) | |
| 7102 | self.source.pushline("<phrase role='%s'>%s</phrase>" % (command, self.macroeval(["No"] + args))) | |
| 6545 | 7103 | elif command == "In": |
| 6546 | 7104 | self.source.pushline("#include <%s>" % args[0]) |
| 6547 | 7105 | # Ex, Fa, Fd, Fn, Rv are not in the non-parseable exception list, |
| 6589 | 7147 | self.stash_linkender = "</link>" |
| 6590 | 7148 | # Structure requests |
| 6591 | 7149 | elif command == "Dd": |
| 7150 | if args[0] == "$Mdocdate:": | |
| 7151 | args.pop(0) | |
| 6592 | 7152 | # acpi_fakekey.1 has an ISO date that doesn't conform to mdoc. |
| 6593 | 7153 | if re.compile("[0-9]+-[0-9]+-[0-9]+").search(args[0]): |
| 6594 | 7154 | (self.year, self.month, self.day) = args[0].split("-") |
| 7155 | # synctex.1 does this - might happen elsewhere | |
| 7156 | elif re.compile("[0-9]+/[0-9]+/[0-9]+").search(args[0]): | |
| 7157 | (self.day, self.month, self.year) = args[0].split("/") | |
| 6595 | 7158 | else: |
| 6596 | 7159 | (self.month, self.day, self.year) = args[:3] |
| 7160 | if len(self.year) == 2: | |
| 7161 | self.source.warning("two-digit year in .Dd macro.") | |
| 6597 | 7162 | self.day = self.day[:-1] |
| 6598 | 7163 | elif command == "Dt": |
| 6599 | 7164 | self.title = args |
| 6604 | 7169 | else: |
| 6605 | 7170 | self.os = "BSD" |
| 6606 | 7171 | elif command == "Sh": |
| 7172 | self.source.diversion = self.source.output | |
| 6607 | 7173 | if not args: |
| 6608 | 7174 | args = self.source.popline().split() |
| 6609 | 7175 | if name_synonyms.match(args[0]): |
| 6626 | 7192 | if synopsis_label.search(args[0]): |
| 6627 | 7193 | self.source.end_paragraph() |
| 6628 | 7194 | self.source.sectname = "Synopsis" |
| 6629 | self.source.synopsis = DisplayParser(self.source, True, self.refnames) | |
| 7195 | self.source.synopsis = DisplayParser(self.source, | |
| 7196 | True, | |
| 7197 | False, | |
| 7198 | self.refnames) | |
| 6630 | 7199 | self.source.sectionhooks.append(self.source.flush_transplant) |
| 6631 | 7200 | return True # Declaration macros will do the work |
| 6632 | 7201 | elif not self.source.synopsis and self.source.find(synopsis_header): |
| 6638 | 7207 | self.flush_refmeta() |
| 6639 | 7208 | self.source.declare_body_start() |
| 6640 | 7209 | # in case someone forgets to close a list (see mktemp.1). |
| 6641 | for lst in self.liststack: | |
| 7210 | for _ in self.liststack: | |
| 6642 | 7211 | self.source.pushline(TroffInterpreter.ctrl + "El") |
| 6643 | 7212 | self.source.push_section(1, " ".join(args)) |
| 6644 | 7213 | elif command == "Ss": |
| 7214 | self.source.diversion = self.source.output | |
| 6645 | 7215 | # in case someone forgets to close a list |
| 6646 | for lst in self.liststack: | |
| 7216 | for _ in self.liststack: | |
| 6647 | 7217 | self.source.pushline(TroffInterpreter.ctrl + "El") |
| 6648 | 7218 | self.source.push_section(2, " ".join(args)) |
| 6649 | 7219 | elif command == "Pp": |
| 6652 | 7222 | else: |
| 6653 | 7223 | self.source.emit("<sbr/>") |
| 6654 | 7224 | elif command == "Bd": |
| 6655 | if args == ["-ragged", "-offset", "indent"]: | |
| 6656 | # Treat as blockquote | |
| 6657 | self.source.pushlist("Bd", "blockquote", explicit=True) | |
| 6658 | self.source.begin_block("blockquote", remap='RS') | |
| 6659 | elif self.source.peekline() and self.source.peekline()[0:3] != TroffInterpreter.ctrl + "Bl": | |
| 7225 | # Possible args are: | |
| 7226 | # -ragged = left-justify only (treat as blockquote) | |
| 7227 | # -centered = center (we throw a warning) | |
| 7228 | # -unfilled = don't fill (we map this to literallayout) | |
| 7229 | # -filled = fill normally (treat as blockquote) | |
| 7230 | # -literal = no fill, use constant width (map to programlisting) | |
| 7231 | # -file = insert file (throw a warning) | |
| 7232 | # -offset = set indent (we ignore this) | |
| 7233 | # -compact = Suppress vertical space before display (we ignore this) | |
| 7234 | if "-centered" in args or "-file" in args: | |
| 7235 | self.source.warning("can't process -center or -file in .Bd") | |
| 7236 | enclosuretype = None | |
| 7237 | if self.source.peekline() and self.source.peekline()[0:3] == TroffInterpreter.ctrl + "Bl": | |
| 7238 | enclosuretype = None | |
| 7239 | elif '-ragged' in args or '-filled' in args: | |
| 7240 | enclosuretype = "blockquote" | |
| 7241 | elif '-unfilled' in args: | |
| 7242 | enclosuretype = 'literallayout' | |
| 6660 | 7243 | self.source.begin_block("literallayout", remap="Bd") |
| 7244 | elif '-literal' in args: | |
| 7245 | enclosuretype = 'programlisting' | |
| 7246 | self.source.begin_block("programlisting", remap="Bd") | |
| 7247 | self.bdstack.append(enclosuretype) | |
| 6661 | 7248 | elif command == "Ed": |
| 6662 | if self.source.troff.nf: | |
| 6663 | self.source.end_block("literallayout", remap="Bd") | |
| 6664 | else: | |
| 6665 | self.source.poplist("blockquote", "Bd") | |
| 7249 | dtype = self.bdstack.pop() | |
| 7250 | if dtype == 'blockquote': | |
| 7251 | self.source.poplist("Bd", remap="Ed (list)") | |
| 7252 | elif dtype is not None: | |
| 7253 | self.source.end_block(dtype, remap="Ed (block)") | |
| 6666 | 7254 | self.source.need_paragraph() |
| 6667 | 7255 | # List markup |
| 6668 | 7256 | elif command == "Bl": |
| 7257 | header = " ".join(tokens) | |
| 6669 | 7258 | # There may be leading text here that's not part of an item |
| 6670 | 7259 | # (as in ash(1)). Pass it through before emitting the list header. |
| 6671 | 7260 | while True: |
| 6676 | 7265 | else: |
| 6677 | 7266 | self.source.interpret_block([nextl]) |
| 6678 | 7267 | self.source.end_paragraph(label="Bl") |
| 6679 | hasbodies = False | |
| 6680 | ind = 0 | |
| 6681 | while ind < len(self.source.lines): | |
| 6682 | nextl = self.source.lines[ind] | |
| 6683 | ind += 1 | |
| 6684 | if match_command(nextl, "El"): | |
| 6685 | break | |
| 6686 | if not match_command(nextl, "It"): | |
| 6687 | hasbodies += 1 | |
| 7268 | hasbodies = xoskip = False | |
| 7269 | depth = 1 | |
| 7270 | for future in self.source.lines: | |
| 7271 | if match_command(future, "El"): | |
| 7272 | depth -= 1 | |
| 7273 | if depth == 0: | |
| 7274 | break | |
| 7275 | elif match_command(future, "Bl"): | |
| 7276 | depth += 1 | |
| 7277 | nextl = future.strip() | |
| 7278 | if is_comment(nextl): | |
| 7279 | continue | |
| 7280 | elif 'Xo' in nextl: | |
| 7281 | xoskip = True | |
| 7282 | elif match_command("Xc", nextl): | |
| 7283 | xoskip = False | |
| 7284 | if not xoskip and not match_command(nextl, "It"): | |
| 7285 | hasbodies = True | |
| 7286 | if bsd_verbosity in self.source.verbose: | |
| 7287 | self.source.notify("%s has bodies? %s" % (header, hasbodies)) | |
| 6688 | 7288 | self.itemcount.append(0) |
| 6689 | if not hasbodies or "-column" in tokens[1:]: | |
| 6690 | self.source.emit("<table remap='%s'><title></title>"% " ".join(tokens)) | |
| 7289 | if "-column" in tokens[1:]: | |
| 7290 | self.source.emit("<table remap=%s><title></title>"% repr(header)) | |
| 6691 | 7291 | self.liststack.append("</table>") |
| 6692 | 7292 | self.rowcount = 0 |
| 7293 | elif not hasbodies: | |
| 7294 | self.source.emit("<itemizedlist remap='%s'> <!-- no bodies -->" % header) | |
| 7295 | self.liststack.append("</itemizedlist>") | |
| 6693 | 7296 | elif "-bullet" in tokens[1:]: |
| 6694 | self.source.emit("<itemizedlist remap='%s' mark='bullet'>" % " ".join(tokens)) | |
| 7297 | self.source.emit("<itemizedlist remap='%s' mark='bullet'>" % header) | |
| 7298 | self.liststack.append("</itemizedlist>") | |
| 7299 | elif "-dash" in tokens[1:] or "-hyphen" in tokens[1:]: | |
| 7300 | # See the comment near ip_tag_mapping | |
| 7301 | self.source.emit("<itemizedlist remap=%s mark='box'>" % repr(header)) | |
| 6695 | 7302 | self.liststack.append("</itemizedlist>") |
| 6696 | 7303 | elif "-item" in tokens[1:]: |
| 6697 | self.source.emit("<itemizedlist remap='%s'>"% " ".join(tokens)) | |
| 7304 | self.source.emit("<itemizedlist remap=%s>"% repr(header)) | |
| 6698 | 7305 | self.liststack.append("</itemizedlist>") |
| 6699 | 7306 | elif "-enum" in tokens[1:]: |
| 6700 | self.source.emit("<orderedlist remap='%s'>" % " ".join(tokens)) | |
| 7307 | self.source.emit("<orderedlist remap=%s>" % repr(header)) | |
| 6701 | 7308 | self.liststack.append("</orderedlist>") |
| 6702 | 7309 | elif "-tag" in tokens[1:]: |
| 6703 | self.source.emit("<variablelist remap='%s'>"% " ".join(tokens)) | |
| 7310 | self.source.emit("<variablelist remap=%s>"% repr(header)) | |
| 6704 | 7311 | self.liststack.append("</variablelist>") |
| 6705 | 7312 | elif "-diag" in tokens[1:]: |
| 6706 | self.source.emit("<variablelist remap='%s'>"% " ".join(tokens)) | |
| 7313 | self.source.emit("<variablelist remap=%s>"% repr(header)) | |
| 6707 | 7314 | self.liststack.append("</variablelist>") |
| 6708 | 7315 | self.suppress_callables = True |
| 6709 | 7316 | elif "-hang" in tokens[1:]: |
| 6710 | self.source.emit("<variablelist remap='%s'>"% " ".join(tokens)) | |
| 7317 | self.source.emit("<variablelist remap=%s>"% repr(header)) | |
| 6711 | 7318 | self.liststack.append("</variablelist>") |
| 6712 | 7319 | elif "-ohang" in tokens[1:]: |
| 6713 | self.source.emit("<variablelist remap='%s'>"% " ".join(tokens)) | |
| 7320 | self.source.emit("<variablelist remap=%s>"% repr(header)) | |
| 6714 | 7321 | self.liststack.append("</variablelist>") |
| 6715 | 7322 | elif "-inset" in tokens[1:]: |
| 6716 | self.source.emit("<variablelist remap='%s'>"% " ".join(tokens)) | |
| 7323 | self.source.emit("<variablelist remap=%s>"% repr(header)) | |
| 6717 | 7324 | self.liststack.append("</variablelist>") |
| 6718 | 7325 | elif command == "It": |
| 6719 | 7326 | if self.liststack[-1] == "</table>": |
| 6720 | # Columns into tables: the arguments of the item macro | |
| 6721 | # are entries. If first arg is callable, wrap each | |
| 6722 | # successive arg with the result of doing so. | |
| 6723 | if args[0] == 'Li': | |
| 6724 | args.pop(0) | |
| 6725 | elif args[0] in MdocInterpreter.callable: | |
| 6726 | newargs = [] | |
| 6727 | for arg in args[1:]: | |
| 6728 | newargs.append(self.eval([args[0], arg])) | |
| 6729 | args = newargs | |
| 7327 | # Columns into tables | |
| 7328 | segments = [[]] | |
| 7329 | for fld in args: | |
| 7330 | if fld == "Ta": | |
| 7331 | segments.append([]) | |
| 7332 | else: | |
| 7333 | segments[-1].append(fld) | |
| 7334 | for (i, seg) in enumerate(segments): | |
| 7335 | if seg[0] in MdocInterpreter.callable: | |
| 7336 | segments[i] = self.macroeval(seg) | |
| 7337 | else: | |
| 7338 | segments[i] = " ".join(segments[i]) | |
| 6730 | 7339 | self.rowcount += 1 |
| 6731 | 7340 | if self.rowcount == 1: |
| 6732 | 7341 | self.source.emit("<tgroup cols='%d'><tbody>" % len(args)) |
| 6733 | 7342 | self.source.emit(" <row>") |
| 6734 | for fld in args: | |
| 6735 | self.source.emit(" <entry>%s</entry>" % fontclose(fld)) | |
| 7343 | for seg in segments: | |
| 7344 | self.source.emit(" <entry>%s</entry>" % fontclose(seg)) | |
| 6736 | 7345 | self.source.emit(" </row>") |
| 6737 | 7346 | else: |
| 6738 | 7347 | # Otherwise we may have to close a previous entry |
| 6739 | 7348 | if args: |
| 6740 | tagline = self.eval(["No"] + args) | |
| 7349 | tagline = self.macroeval(["No"] + args) | |
| 6741 | 7350 | else: |
| 6742 | 7351 | tagline = "" |
| 6743 | 7352 | if self.itemcount[-1]: |
| 6751 | 7360 | nextl = self.source.popline() |
| 6752 | 7361 | if match_command(nextl, "It"): |
| 6753 | 7362 | digested = lineparse(nextl) |
| 6754 | digested = self.eval(["No"] + digested[1:]) | |
| 7363 | digested = self.macroeval(["No"] + digested[1:]) | |
| 6755 | 7364 | termlines.append(digested) |
| 6756 | 7365 | else: |
| 6757 | 7366 | self.source.pushline(nextl) |
| 6758 | break; | |
| 6759 | term = "</term>\n<term>\n".join(termlines) | |
| 7367 | break | |
| 6760 | 7368 | # We certainly have to open a new entry. |
| 6761 | 7369 | if self.liststack[-1] == "</variablelist>": |
| 6762 | 7370 | self.source.emit("<varlistentry>") |
| 6763 | self.source.emit("<term>%s</term>" % fontclose(term)) | |
| 6764 | self.source.emit("<listitem>") | |
| 7371 | self.source.emit("<term>%s</term>" % fontclose("</term>\n<term>\n".join(termlines))) | |
| 7372 | self.source.emit("<listitem>") | |
| 7373 | elif self.liststack[-1] == "</itemizedlist>": | |
| 7374 | body = "\n".join(termlines) | |
| 7375 | if body: | |
| 7376 | self.source.emit("<listitem><para>%s</para></listitem>" % body) | |
| 7377 | else: | |
| 7378 | self.source.emit("<listitem>") | |
| 7379 | elif self.liststack[-1] == "</orderedlist>": | |
| 7380 | self.source.emit("<listitem>") | |
| 6765 | 7381 | self.source.need_paragraph() |
| 6766 | 7382 | elif command == "El": |
| 6767 | 7383 | if self.liststack[-1] == "</table>": |
| 6768 | 7384 | self.source.emit(" </tbody></tgroup>") |
| 6769 | 7385 | else: |
| 6770 | 7386 | self.source.end_paragraph(label="El") |
| 6771 | self.source.emit("</listitem>") | |
| 6772 | 7387 | if self.liststack[-1] == "</variablelist>": |
| 7388 | self.source.emit("</listitem>") | |
| 6773 | 7389 | self.source.emit("</varlistentry>") |
| 7390 | elif self.liststack[-1] == "</orderedlist>": | |
| 7391 | self.source.emit("</listitem>") | |
| 7392 | elif self.liststack[-1] == "</itemizedlist>": | |
| 7393 | if not self.source.endswith("</listitem>"): | |
| 7394 | self.source.emit("</listitem>") | |
| 6774 | 7395 | self.source.emit(self.liststack.pop()) |
| 6775 | 7396 | self.itemcount.pop() |
| 6776 | 7397 | self.source.need_paragraph() |
| 6847 | 7468 | elif cmd == "An": |
| 6848 | 7469 | if self.hasargs("An", args): |
| 6849 | 7470 | return self.encloseargs(args, "phrase", "role='author'") |
| 7471 | elif cmd == "Ap": | |
| 7472 | return self.replacemacro(args, "'@GLUE@") | |
| 6850 | 7473 | elif cmd == "Aq": |
| 6851 | if self.hasargs("Aq", args): | |
| 6852 | return self.encloseargs(args, "<@GLUE@", "@GLUE@>") | |
| 7474 | return self.encloseargs(args, "<@GLUE@", "@GLUE@>") | |
| 6853 | 7475 | elif cmd == "Ac": |
| 6854 | 7476 | return self.replacemacro(args, "@GLUE@>") |
| 6855 | 7477 | elif cmd == "Ao": |
| 6870 | 7492 | elif cmd == "Brq": |
| 6871 | 7493 | return self.encloseargs(args, "{@GLUE@", "@GLUE@}") |
| 6872 | 7494 | elif cmd == "Bx": |
| 6873 | if not args: | |
| 6874 | return ["BSD UNIX"] | |
| 6875 | else: | |
| 6876 | return self.process_punct(args, lambda x: ["-".join(["%sBSD" % x[0]] + x[1:])], 1) | |
| 7495 | def bxhelper(args): | |
| 7496 | if not args: | |
| 7497 | return ["BSD UNIX"] | |
| 7498 | else: | |
| 7499 | return ["-".join(["%sBSD" % args[0]] + args[1:])] | |
| 7500 | return self.process_punct(args, bxhelper, True) | |
| 6877 | 7501 | elif cmd == "Cm": |
| 6878 | 7502 | if self.hasargs("Cm", args): |
| 6879 | 7503 | return self.styleargs(args, "command") |
| 6907 | 7531 | if not args: |
| 6908 | 7532 | return ["-"] |
| 6909 | 7533 | else: |
| 6910 | return self.styleargs(args, "option", "", "-") | |
| 7534 | dashes = '-' | |
| 7535 | while args and args[0] == 'Fl': | |
| 7536 | dashes += '-' | |
| 7537 | args.pop(0) | |
| 7538 | args[0] = dashes + args[0] | |
| 7539 | return self.styleargs(args, "option", "", "") | |
| 6911 | 7540 | elif cmd == "Ic": |
| 6912 | 7541 | if self.hasargs("Ic", args): |
| 6913 | 7542 | return self.styleargs(args, "command", "remap='Ic'") |
| 6914 | 7543 | elif cmd == "Lb": |
| 6915 | return self.process_punct(args, self.lbhook, 1) | |
| 7544 | return self.process_punct(args, self.lbhook, True) | |
| 6916 | 7545 | elif cmd == "Li": |
| 6917 | 7546 | return self.styleargs(args, "literal") |
| 7547 | elif cmd == "Ms": | |
| 7548 | return self.styleargs(args,"literal") | |
| 7549 | elif cmd == "Mt": | |
| 7550 | return self.encloseargs(args,"<email>","</email>") | |
| 6918 | 7551 | elif cmd == "Nd": |
| 6919 | 7552 | savesect = [" ".join(self.encloseargs(args, "", ""))] |
| 6920 | 7553 | while True: |
| 6992 | 7625 | elif cmd == "So": |
| 6993 | 7626 | return self.replacemacro(args, "\'@GLUE@") |
| 6994 | 7627 | elif cmd == "Sq": |
| 6995 | return self.encloseargs(args, '\`@GLUE@', '@GLUE@\'') | |
| 7628 | return self.encloseargs(args, "`@GLUE@", "@GLUE@\'") | |
| 6996 | 7629 | elif cmd == "St": |
| 6997 | return self.process_punct(args, self.sthook, 1) | |
| 7630 | return self.process_punct(args, self.sthook, True) | |
| 6998 | 7631 | elif cmd == "Sx": |
| 6999 | 7632 | #title = " ".join(args) |
| 7000 | return self.process_punct(args, lambda x: ["<link role='Sx' linkend='%s'>%s</link>" % (self.source.id_from_title(" ".join(x)), " ".join(x))], 0) | |
| 7633 | return self.process_punct(args, lambda x: ["<link role='Sx' linkend='%s'>%s</link>" % (self.source.id_from_title(" ".join(x)), " ".join(x))], False) | |
| 7001 | 7634 | elif cmd == "Sy": |
| 7002 | 7635 | return self.styleargs(args, "emphasis", 'remap="Sy"') |
| 7003 | 7636 | elif cmd == "Ta": |
| 7004 | 7637 | return self.replacemacro(args, "\t") |
| 7005 | 7638 | elif cmd == "Tn": |
| 7006 | return self.styleargs(args, "acronym", "remap='Tn'") | |
| 7639 | # We used to set this with an acronym tag, following an older | |
| 7640 | # version of the mdoc manual, but that won't work - among | |
| 7641 | # other things, groff_mdoc(7) uses it at presentation level | |
| 7642 | # to set contents items in small caps. | |
| 7643 | return self.styleargs(args, "phrase", "remap='Tn'") | |
| 7007 | 7644 | elif cmd == "Ux": |
| 7008 | 7645 | return ["<productname>Unix</productname>"] |
| 7009 | 7646 | elif cmd == "Va": |
| 7013 | 7650 | elif cmd == "Xc": |
| 7014 | 7651 | return self.replacemacro(args, "") |
| 7015 | 7652 | elif cmd == "Xo": |
| 7016 | self.source.warning("translation of .Xo/.Xc blocks is unreliable.") | |
| 7017 | 7653 | return self.replacemacro(args, "") |
| 7018 | 7654 | elif cmd == "Xr": |
| 7019 | return self.process_punct(args, self.xrhook, 0) | |
| 7655 | return self.process_punct(args, self.xrhook, False) | |
| 7020 | 7656 | elif cmd[0] == "%": |
| 7021 | lst = self.process_punct(args, lambda x: self.bibliohook(cmd[1], x), 1) | |
| 7657 | lst = self.process_punct(args, lambda x: self.bibliohook(cmd[1], x), True) | |
| 7022 | 7658 | if self.inref: |
| 7023 | 7659 | return [] |
| 7024 | 7660 | else: |
| 7050 | 7686 | # Otherwise return the reference. |
| 7051 | 7687 | else: |
| 7052 | 7688 | for entry in self.biblio: |
| 7053 | if ref in entry[field]: | |
| 7689 | if field in entry and ref in entry[field]: | |
| 7054 | 7690 | return ["<link linkend='ref%s'>[%s]</link>" % (entry["id"], entry["id"])] |
| 7055 | 7691 | else: |
| 7056 | 7692 | raise LiftException("unresolved reference to '%s'" % ref) |
| 7111 | 7747 | return result |
| 7112 | 7748 | def encloseargs(self, args, opener, closer): |
| 7113 | 7749 | "Grab and process arguments for an enclosure macro." |
| 7114 | return self.process_punct(args, lambda x: [opener] + x + [closer], 0) | |
| 7115 | def stylehook(self, args, tag, attr, prefix_unused=""): | |
| 7750 | return self.process_punct(args, lambda x: [opener] + x + [closer], False) | |
| 7751 | def stylehook(self, args, tag, attr, dummy_prefix): | |
| 7116 | 7752 | "Wrap non-punctuation characters in given tag pair." |
| 7117 | 7753 | result = [] |
| 7118 | 7754 | if attr: |
| 7133 | 7769 | return self.process_punct(args, lambda x: self.stylehook(x, tag, attribute, prefix), 1) |
| 7134 | 7770 | def replacemacro(self, args, withmac): |
| 7135 | 7771 | return self.process_punct(args, lambda x: [withmac] + x, 1) |
| 7136 | def eval(self, args): | |
| 7772 | def macroeval(self, args): | |
| 7137 | 7773 | "Evaluate a macro, returning a list." |
| 7774 | if bsd_verbosity in self.source.verbose: | |
| 7775 | self.source.notify("macroeval%s\n" % (tuple(args),)) | |
| 7776 | ||
| 7138 | 7777 | if args[0][0] == '.': |
| 7139 | 7778 | args[0] = args[0][1:] |
| 7140 | 7779 | # Consume arguments and macro calls until none are left |
| 7151 | 7790 | result = " ".join(result) |
| 7152 | 7791 | result = hotglue.sub("", result) |
| 7153 | 7792 | result = cleantag.sub("", result) |
| 7793 | if bsd_verbosity in self.source.verbose: | |
| 7794 | self.source.notify("macroeval -> %s\n" % repr(result)) | |
| 7154 | 7795 | return result |
| 7155 | 7796 | def preprocess(self, text): |
| 7156 | 7797 | return text |
| 7167 | 7808 | if self.source.id_exists(mid): |
| 7168 | 7809 | text = text[:linkstart+6] + text[linkstart+15:] |
| 7169 | 7810 | else: |
| 7170 | self.source.warning("unresolved Sx label") | |
| 7811 | self.source.warning("unresolved Sx label %s" % label) | |
| 7171 | 7812 | text = text[:linkstart] + \ |
| 7172 | 7813 | "<emphasis role='Sx'>%s</emphasis>" % label + \ |
| 7173 | 7814 | text[linkend:] |
| 7174 | 7815 | else: |
| 7175 | 7816 | break |
| 7817 | # Ugh...this can be produced by ,It .Xo/Xc; there's an example on | |
| 7818 | # groff_mdoc(7). | |
| 7819 | text = text.replace("<listitem>\n</listitem>", "") | |
| 7820 | # Sanity check | |
| 7176 | 7821 | if not self.source.section_count: |
| 7177 | 7822 | raise LiftException("no mdoc section structure, can't be lifted.") |
| 7178 | 7823 | return text |
| 7182 | 7827 | name = "ms" |
| 7183 | 7828 | exclusive = True |
| 7184 | 7829 | toptag = "article" |
| 7185 | immutable_set = {} | |
| 7186 | ignore_set = { | |
| 7830 | immutable_set = set([]) | |
| 7831 | ignore_set = set([ | |
| 7187 | 7832 | # Ignore presentation-level-only requests from Bell Labs. |
| 7188 | "RP":1, "ND":1, "DA":1, "1C":1, "2C":1, "MC":1, | |
| 7189 | "BX":1, "KS":1, "KE":1, "KF":1, | |
| 7833 | "RP", "ND", "DA", "1C", "2C", "MC", | |
| 7834 | "BX", "KS", "KE", "KF", | |
| 7190 | 7835 | # Also ignore the Berkeley thesis-mode extension |
| 7191 | "TM":1, "CT":1, "XS":1, "XE":1, "XA":1, "PX":1, "AM":1, | |
| 7192 | "EH":1, "OH":1, "EF":1, "OF":1, | |
| 7836 | "TM", "CT", "XS", "XE", "XA", "PX", "AM", | |
| 7837 | "EH", "OH", "EF", "OF", | |
| 7193 | 7838 | # These are not documented in the ms reference, but |
| 7194 | 7839 | # they occur in ms papers, probably as relics from mm. |
| 7195 | "MH":1, "CS":1, "D3":1 | |
| 7196 | } | |
| 7197 | complain_set = {"RS":1, "RE":1,} | |
| 7198 | parabreak_set = {"blank":1,"PP":1, "LP":1, "XP":1, "IP":1,} | |
| 7199 | sectionbreak_set = {"NH":1, "SH":1, "SC":1,} | |
| 7200 | listbreak_set = {"PP":1, "LP":1, "XP":1, "NH":1, "SH":1, "SC":1,} | |
| 7840 | "MH", "CS", "D3" | |
| 7841 | ]) | |
| 7842 | complain_set = set(["RS", "RE",]) | |
| 7843 | parabreak_set = set(["blank","PP", "LP", "XP", "IP",]) | |
| 7844 | sectionbreak_set = set(["NH", "SH", "SC",]) | |
| 7845 | listbreak_set = set(["PP", "LP", "XP", "NH", "SH", "SC",]) | |
| 7201 | 7846 | translations = { |
| 7202 | 7847 | "\\*" : [ |
| 7203 | 7848 | # The Bell Labs prefix diacriticals |
| 7242 | 7887 | self.font = "R" |
| 7243 | 7888 | self.pointsize = 0 |
| 7244 | 7889 | self.fmt = "R" |
| 7890 | self.author = Author() | |
| 7245 | 7891 | self.TL = None |
| 7246 | 7892 | self.AU = None |
| 7247 | 7893 | self.AI = [] |
| 7248 | 7894 | self.AB = None |
| 7249 | 7895 | self.flushed = False |
| 7250 | def interpret(self, line_unused, tokens, caller): | |
| 7896 | def interpret(self, dummy, tokens, caller): | |
| 7251 | 7897 | command = tokens[0][1:] |
| 7252 | 7898 | args = tokens[1:] |
| 7253 | 7899 | if command in ("B", "I", "R", "UL", "SM", "LG", "NL"): |
| 7313 | 7959 | if tokens and tokens[0][1:3] == "AE": |
| 7314 | 7960 | break |
| 7315 | 7961 | if not (is_command(line) and self.source.ignorable(line)): |
| 7316 | self.AB.append(line) | |
| 7962 | self.AB.append(line) | |
| 7317 | 7963 | return True |
| 7318 | 7964 | # Here's where we analyze the front matter and generate the header |
| 7319 | 7965 | if not self.flushed: |
| 7365 | 8011 | title = self.source.popline() |
| 7366 | 8012 | try: |
| 7367 | 8013 | newdepth = int(tokens[1]) |
| 7368 | except: | |
| 8014 | except ValueError: | |
| 7369 | 8015 | newdepth = 1 |
| 7370 | 8016 | self.source.push_section(newdepth, title) |
| 7371 | 8017 | elif command == "IP": |
| 7426 | 8072 | name = "me" |
| 7427 | 8073 | exclusive = True |
| 7428 | 8074 | toptag = "article" |
| 7429 | immutable_set = {} | |
| 7430 | ignore_set = {"1c":1,"2c":1,"bc":1,"bl":1,"ef":1,"eh":1,"ep":1,"fo":1, | |
| 7431 | "he":1,"hx":1,"m1":1,"m2":1,"m3":1,"m4":1,"n1":1,"n2":1, | |
| 7432 | "of":1,"oh":1,"tp":1,"xl":1,"xp":1,"sk":1,"(z":1,")z":1, | |
| 7433 | "sz":1,"(l":1,")l":1, | |
| 7434 | } | |
| 7435 | complain_set = {"ba":1,"bx":1,"ix":1,"(b":1,")b":1,"(c":1,")c":1,"pa":1, | |
| 7436 | "sx":1,"uh":1,".$p":1,".$c":1,".$f":1,".$h":1,".$s":1, | |
| 7437 | "+c":1,"(x":1,")x":1, | |
| 7438 | } | |
| 7439 | parabreak_set = {"blank":1,"lp":1,"pp":1,"ip":1,"np":1,} | |
| 7440 | sectionbreak_set = {"sh":1,} | |
| 7441 | listbreak_set = {"lp":1,"pp":1,"np":1,"sh":1,} | |
| 8075 | immutable_set = set([]) | |
| 8076 | ignore_set = set(["1c","2c","bc","bl","ef","eh","ep","fo", | |
| 8077 | "he","hx","m1","m2","m3","m4","n1","n2", | |
| 8078 | "of","oh","tp","xl","xp","sk","(z",")z", | |
| 8079 | "sz","(l",")l", | |
| 8080 | ]) | |
| 8081 | complain_set = set(["ba","bx","ix","(b",")b","(c",")c","pa", | |
| 8082 | "sx","uh",".$p",".$c",".$f",".$h",".$s", | |
| 8083 | "+c","(x",")x", | |
| 8084 | ]) | |
| 8085 | parabreak_set = set(["blank","lp","pp","ip","np",]) | |
| 8086 | sectionbreak_set = set(["sh",]) | |
| 8087 | listbreak_set = set(["lp","pp","np","sh",]) | |
| 7442 | 8088 | translations = { |
| 7443 | 8089 | "\\*" : [ |
| 7444 | 8090 | (r"\*-", "–"), # Not quite right, supposed to be 3/4 dash |
| 7471 | 8117 | self.source.in_preamble = False |
| 7472 | 8118 | if io_verbosity in self.source.verbose: |
| 7473 | 8119 | self.source.notify("exiting preamble") |
| 7474 | def interpret(self, line_unused, tokens, caller_unused): | |
| 8120 | def interpret(self, dummy, tokens, dummy_caller): | |
| 7475 | 8121 | cmd = tokens[0][1:] |
| 7476 | 8122 | args = tokens[1:] |
| 7477 | 8123 | if cmd in ("b", "bi", "i", "r", "rb", "sm", "u"): |
| 7508 | 8154 | elif cmd == "(d": |
| 7509 | 8155 | self.source.diversion = self.delay |
| 7510 | 8156 | elif cmd == ")d": |
| 7511 | self.source.diversion = self.output | |
| 8157 | self.source.diversion = self.source.output | |
| 7512 | 8158 | elif cmd == "pd": |
| 7513 | self.output += self.delay | |
| 8159 | self.source.output += self.delay | |
| 7514 | 8160 | self.delay = [] |
| 7515 | 8161 | elif cmd == "sh": |
| 7516 | 8162 | self.source.push_section(int(tokens[1]), tokens[2]) |
| 7534 | 8180 | name = "mm" |
| 7535 | 8181 | exclusive = True |
| 7536 | 8182 | toptag = "article" |
| 7537 | immutable_set = {"B":1, "I":1, "R":1, | |
| 7538 | "BI":1, "BR":1, "IB":1, "IR":1, "RB":1, "RI":1, | |
| 7539 | "AE":1, "AF":1, "AL":1, "RL":1, "APP":1, "APPSK":1, | |
| 7540 | "AS":1, "AT":1, "AU":1, "B1":1, "B2":1, "BE":1, | |
| 7541 | "BL":1, "ML":1, "BS":1, "BVL":1, "VL":1, "DE":1, "DL":1, | |
| 7542 | "DS":1, "FE":1, "FS":1, "H":1, "HU":1, "IA":1, "IE":1, | |
| 7543 | "IND":1, "LB":1, "LC":1, "LE":1, "LI":1, "P":1, | |
| 7544 | "RF":1, "SM":1, "TL":1, "VERBOFF":1, "VERBON":1, | |
| 7545 | "WA":1, "WE":1, } | |
| 7546 | ignore_set = {")E":1, "1C":1, "2C":1, "AST":1, "AV":1, "AVL":1, | |
| 7547 | "COVER":1, "COVEND":1, "EF":1, "EH":1, "EDP":1, | |
| 7548 | "EPIC":1, "FC":1, "FD":1, "HC":1, "HM":1, | |
| 7549 | "GETR":1, "GETST":1, "HM":1, | |
| 7550 | "INITI":1, "INITR":1, "INDP":1, "ISODATE":1, | |
| 7551 | "MT":1, "NS":1, "ND":1, "OF":1, "OH":1, "OP":1, | |
| 7552 | "PGFORM":1, "PGNH":1, "PE":1, "PF":1, "PH":1, | |
| 7553 | "RP":1, "S":1, "SA":1, "SP":1, | |
| 7554 | "SG":1, "SK":1, "TAB":1, "TB":1, "TC":1, "VM":1, "WC":1} | |
| 7555 | complain_set = {"EC":1, "EX":1, "FG":1, | |
| 7556 | "GETHN":1, "GETPN":1, "GETR":1, "GETST":1, | |
| 7557 | "LT":1, "LD":1, "LO":1, | |
| 7558 | "MOVE":1, "MULB":1, "MULN":1, "MULE":1, "NCOL":1, | |
| 7559 | "nP":1, "PIC":1, "RD":1, "RS":1, "RE":1, "SETR":1, } | |
| 7560 | parabreak_set = {} | |
| 7561 | sectionbreak_set = {} | |
| 7562 | listbreak_set = {} | |
| 8183 | immutable_set = set(["B", "I", "R", | |
| 8184 | "BI", "BR", "IB", "IR", "RB", "RI", | |
| 8185 | "AE", "AF", "AL", "RL", "APP", "APPSK", | |
| 8186 | "AS", "AT", "AU", "B1", "B2", "BE", | |
| 8187 | "BL", "ML", "BS", "BVL", "VL", "DE", "DL", | |
| 8188 | "DS", "FE", "FS", "H", "HU", "IA", "IE", | |
| 8189 | "IND", "LB", "LC", "LE", "LI", "P", | |
| 8190 | "RF", "SM", "TL", "VERBOFF", "VERBON", | |
| 8191 | "WA", "WE", ]) | |
| 8192 | ignore_set = set([")E", "1C", "2C", "AST", "AV", "AVL", | |
| 8193 | "COVER", "COVEND", "EF", "EH", "EDP", | |
| 8194 | "EPIC", "FC", "FD", "HC", "HM", | |
| 8195 | "GETR", "GETST", | |
| 8196 | "INITI", "INITR", "INDP", "ISODATE", | |
| 8197 | "MT", "NS", "ND", "OF", "OH", "OP", | |
| 8198 | "PGFORM", "PGNH", "PE", "PF", "PH", | |
| 8199 | "RP", "S", "SA", "SP", | |
| 8200 | "SG", "SK", "TAB", "TB", "TC", "VM", "WC"]) | |
| 8201 | complain_set = set(["EC", "EX", "FG", | |
| 8202 | "GETHN", "GETPN", "GETR", "GETST", | |
| 8203 | "LT", "LD", "LO", | |
| 8204 | "MOVE", "MULB", "MULN", "MULE", "NCOL", | |
| 8205 | "nP", "PIC", "RD", "RS", "RE", "SETR", ]) | |
| 8206 | parabreak_set = set([]) | |
| 8207 | sectionbreak_set = set([]) | |
| 8208 | listbreak_set = set([]) | |
| 7563 | 8209 | translations = { |
| 7564 | 8210 | "\\*" : [ |
| 7565 | 8211 | (r"\*F", ""), # Assumes that footnote marks are adjacent to footnotes |
| 7596 | 8242 | return self.source.alternating_highlight(cmd, args) |
| 7597 | 8243 | else: |
| 7598 | 8244 | return None |
| 7599 | def interpret(self, line_unused, tokens, caller): | |
| 8245 | def interpret(self, dummy, tokens, caller): | |
| 7600 | 8246 | cmd = tokens[0][1:] |
| 7601 | 8247 | args = tokens[1:] |
| 7602 | 8248 | # Highlighting |
| 7627 | 8273 | if tokens and tokens[0][1:3] == "AE": |
| 7628 | 8274 | break |
| 7629 | 8275 | if not (is_command(line) and self.source.ignorable(line)): |
| 7630 | self.AS.append(line) | |
| 8276 | self.AS.append(line) | |
| 7631 | 8277 | return True |
| 7632 | 8278 | # Here's where we analyze the front matter and generate the header |
| 7633 | 8279 | if not self.flushed: |
| 7810 | 8456 | name = "mwww" |
| 7811 | 8457 | exclusive = False |
| 7812 | 8458 | toptag = "article" |
| 7813 | immutable_set = {"HX":1, "BCL":1, "BGIMG":1, | |
| 7814 | "URL":1, "MTO":1, "FTP":1, "IMG":1, "HTML":1, | |
| 7815 | "TAG":1, "HR":1,} | |
| 7816 | ignore_set = {"HX":1, "BCL":1, "BGIMG":1, | |
| 7817 | "HTML":1, "HR":1, "LK":1, "NHR":1, | |
| 7818 | "HnS":1, "HnE":1, "DC":1, "HTL":1, } | |
| 7819 | complain_set = {} | |
| 7820 | parabreak_set = {} | |
| 7821 | sectionbreak_set = {} | |
| 7822 | listbreak_set = {} | |
| 8459 | immutable_set = set(["HX", "BCL", "BGIMG", | |
| 8460 | "URL", "MTO", "FTP", "IMG", "HTML", | |
| 8461 | "TAG", "HR",]) | |
| 8462 | ignore_set = set(["HX", "BCL", "BGIMG", | |
| 8463 | "HTML", "HR", "LK", "NHR", | |
| 8464 | "HnS", "HnE", "DC", "HTL", ]) | |
| 8465 | complain_set = set([]) | |
| 8466 | parabreak_set = set([]) | |
| 8467 | sectionbreak_set = set([]) | |
| 8468 | listbreak_set = set([]) | |
| 7823 | 8469 | translations = {} |
| 7824 | 8470 | reductions = {} |
| 7825 | 8471 | def __init__(self, source, verbose=0): |
| 7826 | 8472 | self.source = source |
| 7827 | 8473 | self.verbose = verbose |
| 7828 | def interpret(self, line_unused, tokens, caller_unused): | |
| 8474 | def interpret(self, dummy_line, tokens, dummy_caller): | |
| 7829 | 8475 | cmd = tokens[0][1:] |
| 7830 | 8476 | args = tokens[1:] |
| 7831 | 8477 | if len(args) == 1: |
| 7887 | 8533 | "ZN": XManInterpreter, |
| 7888 | 8534 | "Pn": XManInterpreter, |
| 7889 | 8535 | "ny0": XManInterpreter, |
| 7890 | "reStructeredText": reStructeredTextInterpreter, | |
| 8536 | "reStructuredText": reStructuredTextInterpreter, | |
| 8537 | "reStructeredText": reStructuredTextInterpreter, | |
| 7891 | 8538 | "DocBook XSL Stylesheets" : DocBookInterpreter, |
| 8539 | "pdfdest" : FoojzsInterpreter, | |
| 8540 | "H0": ASTInterpreter, | |
| 7892 | 8541 | # These are all of the supported Mwww tags |
| 7893 | 8542 | "URL": MwwwInterpreter, |
| 7894 | 8543 | "FTP": MwwwInterpreter, |
| 7895 | 8544 | "MTO": MwwwInterpreter, |
| 7896 | "FTP": MwwwInterpreter, | |
| 7897 | 8545 | "PIMG": MwwwInterpreter, |
| 7898 | 8546 | "IMG": MwwwInterpreter, |
| 7899 | 8547 | "TAG": MwwwInterpreter, |
| 7929 | 8577 | infp = open(ifile) |
| 7930 | 8578 | indoc = infp.read() |
| 7931 | 8579 | infp.close() |
| 7932 | tempfile = ifile + ".~%s-%d~" % (name, os.getpid()) | |
| 8580 | tmpfile = ifile + ".~%s-%d~" % (name, os.getpid()) | |
| 7933 | 8581 | try: |
| 7934 | outfp = open(tempfile, "w") | |
| 8582 | outfp = open(tmpfile, "w") | |
| 7935 | 8583 | except OSError: |
| 7936 | 8584 | stderr.write("%s: can't open tempfile" % name) |
| 7937 | 8585 | return True |
| 7938 | 8586 | try: |
| 7939 | 8587 | outdoc = translate_data(name, ifile, indoc, len(arguments)>1) |
| 7940 | 8588 | except: |
| 7941 | os.remove(tempfile) | |
| 8589 | os.remove(tmpfile) | |
| 7942 | 8590 | # Pass the exception upwards |
| 7943 | 8591 | (exc_type, exc_value, exc_traceback) = sys.exc_info() |
| 7944 | 8592 | raise exc_type, exc_value, exc_traceback |
| 7945 | 8593 | if outdoc == indoc: |
| 7946 | os.remove(tempfile) | |
| 8594 | os.remove(tmpfile) | |
| 7947 | 8595 | if outdoc is None: |
| 7948 | 8596 | continue |
| 7949 | 8597 | else: |
| 7950 | 8598 | outfp.write(outdoc) |
| 7951 | 8599 | outfp.close() # under Windows you can't rename an open file |
| 7952 | 8600 | if not trans_filename: |
| 7953 | os.rename(tempfile, ifile) | |
| 8601 | os.rename(tmpfile, ifile) | |
| 7954 | 8602 | elif type(trans_filename) == type(""): |
| 7955 | os.rename(tempfile, ifile + trans_filename) | |
| 8603 | os.rename(tmpfile, ifile + trans_filename) | |
| 7956 | 8604 | else: |
| 7957 | os.rename(tempfile, trans_filename(ifile)) | |
| 8605 | os.rename(tmpfile, trans_filename(ifile)) | |
| 7958 | 8606 | |
| 7959 | 8607 | stdout = sys.stdout |
| 7960 | 8608 | stderr = sys.stderr |
| 7961 | 8609 | pretty = pprint.PrettyPrinter(indent=4) |
| 7962 | 8610 | globalhints = SemanticHintsRegistry() |
| 7963 | 8611 | |
| 7964 | def main(args, mainout_unused=stdout, mainerr=stderr): | |
| 7965 | global globalhints, pretty | |
| 8612 | def main(args, dummy_mainout=stdout, mainerr=stderr): | |
| 8613 | #global globalhints, pretty | |
| 7966 | 8614 | import getopt |
| 7967 | (options, arguments) = getopt.getopt(args, "d:e:D:I:h:qsxvw") | |
| 8615 | (options, arguments) = getopt.getopt(args, "d:e:D:I:h:qsxvwV") | |
| 7968 | 8616 | includepath = ["."] |
| 7969 | 8617 | hintfile = None |
| 7970 | 8618 | quiet = False |
| 7992 | 8640 | verbosity_level += 1 |
| 7993 | 8641 | elif switch == '-w': |
| 7994 | 8642 | portability += 1 |
| 8643 | elif switch == '-V': | |
| 8644 | sys.stdout.write("doclifter version %s\n" % version) | |
| 8645 | sys.exit(0) | |
| 7995 | 8646 | if not verbosity: |
| 7996 | 8647 | verbosity = "gpscmibz"[:verbosity_level] |
| 7997 | 8648 | try: |
| 0 | 0 | '\" t |
| 1 | 1 | .\" Title: doclifter |
| 2 | 2 | .\" Author: [see the "Author" section] |
| 3 | .\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/> | |
| 4 | .\" Date: 11/25/2010 | |
| 3 | .\" Generator: DocBook XSL Stylesheets v1.76.1 <http://docbook.sf.net/> | |
| 4 | .\" Date: 06/01/2013 | |
| 5 | 5 | .\" Manual: Documentation Tools |
| 6 | 6 | .\" Source: doclifter |
| 7 | 7 | .\" Language: English |
| 8 | 8 | .\" |
| 9 | .TH "DOCLIFTER" "1" "11/25/2010" "doclifter" "Documentation Tools" | |
| 9 | .TH "DOCLIFTER" "1" "06/01/2013" "doclifter" "Documentation Tools" | |
| 10 | 10 | .\" ----------------------------------------------------------------- |
| 11 | 11 | .\" * Define some portability stuff |
| 12 | 12 | .\" ----------------------------------------------------------------- |
| 30 | 30 | doclifter \- translate troff requests into DocBook |
| 31 | 31 | .SH "SYNOPSIS" |
| 32 | 32 | .HP \w'\fBdoclifter\fR\ 'u |
| 33 | \fBdoclifter\fR [\-e\ \fIencoding\fR] [\-h\ \fIhintfile\fR] [\-q] [\-x] [\-v] [\-w] [\-D\ \fItoken=type\fR] [\-I\ \fIpath\fR] \fIfile\fR... | |
| 33 | \fBdoclifter\fR [\-e\ \fIencoding\fR] [\-h\ \fIhintfile\fR] [\-q] [\-x] [\-v] [\-w] [\-V] [\-D\ \fItoken=type\fR] [\-I\ \fIpath\fR] [\-I\ \fIpath\fR] \fIfile\fR... | |
| 34 | 34 | .SH "DESCRIPTION" |
| 35 | 35 | .PP |
| 36 | 36 | \fBdoclifter\fR |
| 61 | 61 | .PP |
| 62 | 62 | The tag |
| 63 | 63 | \fB\&.ta\fR |
| 64 | is passed through with a complaint unless followed by text lines containing tabs, in which case the following span of lines containing tabs is lifted to a table\&. | |
| 64 | is passed through with a complaint unless the immediarely following by text lines contains a tab, in which case the following span of lines containing tabs is lifted to a table\&. | |
| 65 | 65 | .PP |
| 66 | 66 | Under some circumstances, |
| 67 | 67 | \fBdoclifter\fR |
| 71 | 71 | \fBlynx\fR(1))\&. Translations produced in this way will be prone to miss structural features, but this fallback is good enough for simple man pages\&. |
| 72 | 72 | .PP |
| 73 | 73 | \fBdoclifter\fR |
| 74 | does not do a perfect job, merely an extremely good one\&. Final polish should be applied by a human being capable of recognizing patterns too subtle for a computer\&. But | |
| 74 | does not do a perfect job, merely a surprisingly good one\&. Final polish should be applied by a human being capable of recognizing patterns too subtle for a computer\&. But | |
| 75 | 75 | \fBdoclifter\fR |
| 76 | 76 | will almost always produce translations that are good enough to be usable before hand\-hacking\&. |
| 77 | 77 | .PP |
| 139 | 139 | .RS 4 |
| 140 | 140 | Enable strict portability checking\&. Multiple instances of \-w increase the strictness\&. See |
| 141 | 141 | the section called \(lqPORTABILITY CHECKING\(rq\&. |
| 142 | .RE | |
| 143 | .PP | |
| 144 | \-V | |
| 145 | .RS 4 | |
| 146 | With this option, the program emits a version message and exits\&. | |
| 142 | 147 | .RE |
| 143 | 148 | .SH "TRANSLATION RULES" |
| 144 | 149 | .PP |
| 166 | 171 | \fBdoclifter\fR |
| 167 | 172 | does a good job on most man pages, It knows about the extended |
| 168 | 173 | \fBUR\fR/\fBUE\fR/\fBUN\fR |
| 174 | and | |
| 175 | \fBURL\fR | |
| 169 | 176 | requests supported under Linux\&. If any |
| 170 | 177 | \fB\&.UR\fR |
| 171 | 178 | request is present, it will translate these but not wrap URLs outide them with |
| 256 | 263 | \fB\&.IP\fR |
| 257 | 264 | the result is nested lists\&. Otherwise, the |
| 258 | 265 | \fB\&.RS\fR/\fB\&.RE\fR |
| 259 | pair is translated into a Blockquote tag\-pair\&. | |
| 266 | pair is translated into a | |
| 267 | Blockquote | |
| 268 | tag\-pair\&. | |
| 260 | 269 | .PP |
| 261 | 270 | \fB\&.DS\fR/\fB\&.DE\fR |
| 262 | 271 | is not part of the documented man macro set, but is recognized because it shows up with some frequency on legacy man pages from older Unixes\&. |
| 282 | 291 | The |
| 283 | 292 | \fB\&.TA\fR |
| 284 | 293 | and |
| 285 | \fBIN\fR | |
| 294 | \fB\&.IN\fR | |
| 286 | 295 | requests are ignored\&. |
| 287 | 296 | .PP |
| 288 | 297 | When the man macros are active, any |
| 367 | 376 | \fB\&.CS\fR, |
| 368 | 377 | \fB\&.CE\fR, |
| 369 | 378 | \fB\&.SO\fR, |
| 370 | \fB\&.SE\fR, and | |
| 371 | \fB\&.UL\fR | |
| 379 | \fB\&.SE\fR, | |
| 380 | \fB\&.UL\fR, | |
| 381 | \fB\&.QW\fR | |
| 382 | and | |
| 383 | \fB\&.PQ\fR | |
| 372 | 384 | macros are translated structurally\&. |
| 373 | 385 | .SS "Mandoc Translation" |
| 374 | 386 | .PP |
| 653 | 665 | \fBHTMLINDEX\fR, |
| 654 | 666 | \fBBODYCOLOR\fR, |
| 655 | 667 | \fBBACKGROUND\fR, |
| 656 | \fBHTML\fR, an | |
| 668 | \fBHTML\fR, and | |
| 657 | 669 | \fBLINE\fR |
| 658 | 670 | tags are ignored\&. |
| 659 | 671 | .SS "TBL Translation" |
| 732 | 744 | BeginPage |
| 733 | 745 | tag (in paragraphed text only)\&. Calls to |
| 734 | 746 | \fB\&.sp\fR |
| 735 | generate a paragraph break (in paragraphed text only)\&. These are the only troff requests we translate to DocBook\&. The rest of the troff emulation exists because macro packages use it internally to expand macros into elements that might be structural\&. | |
| 747 | generate a paragraph break (in paragraphed text only)\&. Calls to | |
| 748 | \fB\&.ti\fR | |
| 749 | wrap the following line in a | |
| 750 | BlockQuote | |
| 751 | These are the only troff requests we translate to DocBook\&. The rest of the troff emulation exists because macro packages use it internally to expand macros into elements that might be structural\&. | |
| 736 | 752 | .PP |
| 737 | 753 | Requests relating to macro definitions and strings (\fB\&.ds\fR, |
| 738 | 754 | \fB\&.as\fR, |
| 748 | 764 | \fB\&.ie\fR, |
| 749 | 765 | \fB\&.el\fR) are handled\&. The built\-in conditions o, n, t, e, and c are evaluated as if for |
| 750 | 766 | nroff |
| 751 | on page one of a document\&. String comparisons are evaluated by straight textual comparison\&. All numeric expressions evaluate to true\&. | |
| 767 | on page one of a document\&. The m, d, and r troff conditionals are also interpreted\&. String comparisons are evaluated by straight textual comparison\&. All numeric expressions evaluate to true\&. | |
| 752 | 768 | .PP |
| 753 | 769 | The extended |
| 754 | 770 | groff |
| 784 | 800 | .sp -1 |
| 785 | 801 | .IP " 1." 4.2 |
| 786 | 802 | .\} |
| 787 | The \ee escape becomes a bare backslash, \e\&. a period, and \e\- a bare dash\&. | |
| 803 | The \ee and \e\e escapes become a bare backslash, \e\&. a period, and \e\- a bare dash\&. | |
| 788 | 804 | .RE |
| 789 | 805 | .sp |
| 790 | 806 | .RS 4 |
| 1021 | 1037 | \fBdoclifter\fR |
| 1022 | 1038 | will produce invalid DocBook markup even from correct troff markup\&. Usually this results from strange constructions in the source page, or macro calls that are beyond the ability of |
| 1023 | 1039 | \fBdoclifter\fR\*(Aqs macro processor to get right\&. Here are some things to watch for, and how to fix them: |
| 1024 | .PP | |
| 1025 | \fIMalformed command synopses\&.\fR | |
| 1040 | .SS "Malformed command synopses\&." | |
| 1041 | .PP | |
| 1026 | 1042 | If you get a message that says |
| 1027 | "command synopsis parse failed", look at the XML output\&. It will contain a comment telling you what the command synopsis looked like after preprocessing, and indicate on which token the parse failed (both with a token number and a caret sign inserted in the dump of the synopsis tokens)\&. Try rewriting the synopsis in your manual page source\&. The most common cause of failure is unbalanced [] groupings, a bug that can be very difficult to notice by eyeball\&. To assist with this, the error token dump tries to insert \(oq$\(cq at the point of the last nesting\-depth increase, but the code that does this is failure\-prone\&. | |
| 1028 | .PP | |
| 1029 | \fIConfusing macro calls\&.\fR | |
| 1043 | "command synopsis parse failed", try rewriting the synopsis in your manual page source\&. The most common cause of failure is unbalanced [] groupings, a bug that can be very difficult to notice by eyeball\&. To assist with this, the error message includes a token number in parentheses indicating on which token the parse failed\&. | |
| 1044 | .PP | |
| 1045 | For more information, use the \-v option\&. This will trigger a dump telling you what the command synopsis looked like after preprocessing, and indicate on which token the parse failed (both with a token number and a caret sign inserted in the dump of the synopsis tokens)\&. Try rewriting the synopsis in your manual page source\&. The most common cause of failure is unbalanced [] groupings, a bug that can be very difficult to notice by eyeball\&. To assist with this, the error token dump tries to insert \(oq$\(cq at the point of the last nesting\-depth increase, but the code that does this is failure\-prone\&. | |
| 1046 | .SS "Confusing macro calls\&." | |
| 1047 | .PP | |
| 1030 | 1048 | Some manual page authors replace standard requests (like |
| 1031 | 1049 | \fB\&.PP\fR, |
| 1032 | 1050 | \fB\&.SH\fR |
| 1040 | 1058 | tries to cope and usually does a good job, the quirks of [nt]roff are legion and confusing macro calls sometimes lead to bad XML being generated\&. A common symptom of such problems is unclosed |
| 1041 | 1059 | Emphasis |
| 1042 | 1060 | tags\&. |
| 1061 | .SS "Malformed list syntax\&." | |
| 1062 | .PP | |
| 1063 | The manual\-page parser can be confused by | |
| 1064 | \fB\&.TP\fR | |
| 1065 | constructs that have header tags but no following body\&. If the XML produced doesn\*(Aqt validate, and the problem seems to be a misplaced | |
| 1066 | listitem | |
| 1067 | tag, try using the verbose (\-v) option\&. This will enable line\-numbered warnings that may help you zero in on the problem\&. | |
| 1068 | .SS "Section nesting problems with SS\&." | |
| 1043 | 1069 | .PP |
| 1044 | 1070 | The message |
| 1045 | 1071 | "possible section nesting error" |
| 1046 | 1072 | means that the program has seen two adjacent subsection headers\&. In man pages, subsections don\*(Aqt have a depth argument, so |
| 1047 | 1073 | \fBdoclifter\fR |
| 1048 | 1074 | cannot be certain how subsections should be nested\&. Any subsection heading between the indicated line and the beginning of the next top\-level section might be wrong and require correcting by hand\&. |
| 1049 | .PP | |
| 1050 | If you\*(Aqre translating a page that uses user\-defined macros and you get bad output, the first thing to do is simplify or eliminate the user\-defined macros\&. Replace them with stock requests where possible\&. | |
| 1051 | .SH "RETURN VALUES" | |
| 1052 | .PP | |
| 1053 | On successful completion, the program returns status 0\&. It returns 1 if some file or standard input could not be translated\&. It returns 2 if one of the input sources was a | |
| 1054 | \fB\&.so\fR | |
| 1055 | inclusion\&. It returns 3 if there is an error in reading or writing files\&. It returns 4 to indicate an internal error\&. It returns 5 when aborted by a keyboard interrupt\&. | |
| 1056 | .PP | |
| 1057 | Note that a zero return does not guarantee that the output is valid DocBook\&. It will almost always (as in, more than 96% of cases) be syntactically valid XML, but in some rare cases fixups by hand may be necessary to meet the semantics of the DocBook DTD\&. Validation problems are most likely to occur with complicated list markup\&. | |
| 1058 | .SH "BUGS AND WARNINGS" | |
| 1059 | .PP | |
| 1060 | About 4% of man pages will either make this program throw error status 1 or generate invalid XML\&. In almost all such cases the misbehavior is triggered by markup bugs in the source that are too severe to be coped with\&. | |
| 1075 | .SS "Bad output with no doclifter error message" | |
| 1076 | .PP | |
| 1077 | If you\*(Aqre translating a page that uses user\-defined macros, and doclifter fails to complain about it but you get bad output, the first thing to do is simplify or eliminate the user\-defined macros\&. Replace them with stock requests where possible\&. | |
| 1078 | .SH "IMPROVING TRANSLATION QUALITY" | |
| 1079 | .PP | |
| 1080 | There are a few constructions that are a good idea to check by hand after lifting a page\&. | |
| 1081 | .PP | |
| 1082 | Look near the | |
| 1083 | BlockQuote | |
| 1084 | tags\&. The troff temporary indent request (\fB\&.ti\fR) is translated into a | |
| 1085 | BlockQuote | |
| 1086 | wrapper around the following line\&. Sometimes | |
| 1087 | LiteralLayout | |
| 1088 | or | |
| 1089 | ProgramListing | |
| 1090 | would be a better translation, but | |
| 1091 | \fBdoclifter\fR | |
| 1092 | has no way to know this\&. | |
| 1093 | .PP | |
| 1094 | It is not possible to unambiguously detect candidates for wrapping in a DocBook | |
| 1095 | option | |
| 1096 | tag in running text\&. If you care, you\*(Aqll have to check for these and fix them by hand\&. | |
| 1097 | .SH "BUGS AND LIMITATIONS" | |
| 1098 | .PP | |
| 1099 | About 3% of man pages will either make this program throw error status 1 or generate invalid XML\&. In almost all such cases the misbehavior is triggered by markup bugs in the source that are too severe to be coped with\&. | |
| 1061 | 1100 | .PP |
| 1062 | 1101 | Equation number arguments of EQN calls are ignored\&. |
| 1063 | 1102 | .PP |
| 1079 | 1118 | .PP |
| 1080 | 1119 | Macro definitions in a manual page NAME section are not interpreted\&. |
| 1081 | 1120 | .PP |
| 1082 | In Berkeley mdoc interpretation, handling of | |
| 1083 | \fB\&.Xo\fR/\fB\&.Xc\fR | |
| 1084 | enclosures is failure\-prone\&. | |
| 1085 | .PP | |
| 1086 | 1121 | Uses of \ec for line continuation sometimes are not translated, leaving the \ec in the output XML\&. The program will print a warning when this occurs\&. |
| 1087 | 1122 | .PP |
| 1088 | It is not possible to unambiguously detect candidates for wrapping in a DocBook option tag in running text\&. You\*(Aqll have to check for these by hand\&. | |
| 1123 | It is not possible to unambiguously detect candidates for wrapping in a DocBook | |
| 1124 | option | |
| 1125 | tag in running text\&. If you care, you\*(Aqll have to check for these and fix them by hand\&. | |
| 1089 | 1126 | .PP |
| 1090 | 1127 | The line numbers in |
| 1091 | 1128 | \fBdoclifter\fR |
| 1101 | 1138 | translator uses the Bell Labs interpretation when |
| 1102 | 1139 | \fB\&.P2\fR |
| 1103 | 1140 | is present in the document, and otherwise ignores the request\&. |
| 1141 | .SH "RETURN VALUES" | |
| 1142 | .PP | |
| 1143 | On successful completion, the program returns status 0\&. It returns 1 if some file or standard input could not be translated\&. It returns 2 if one of the input sources was a | |
| 1144 | \fB\&.so\fR | |
| 1145 | inclusion\&. It returns 3 if there is an error in reading or writing files\&. It returns 4 to indicate an internal error\&. It returns 5 when aborted by a keyboard interrupt\&. | |
| 1146 | .PP | |
| 1147 | Note that a zero return does not guarantee that the output is valid DocBook\&. It will almost always (as in, more than 98% of cases) be syntactically valid XML, but in some rare cases fixups by hand may be necessary to meet the semantics of the DocBook DTD\&. Validation problems are most likely to occur with complicated list markup\&. | |
| 1104 | 1148 | .SH "REQUIREMENTS" |
| 1105 | 1149 | .PP |
| 1106 | 1150 | The |
| 23 | 23 | <arg choice='opt'>-x</arg> |
| 24 | 24 | <arg choice='opt'>-v</arg> |
| 25 | 25 | <arg choice='opt'>-w</arg> |
| 26 | <arg choice='opt'>-V</arg> | |
| 26 | 27 | <arg choice='opt'>-D <replaceable>token=type</replaceable></arg> |
| 28 | <arg choice='opt'>-I <replaceable>path</replaceable></arg> | |
| 27 | 29 | <arg choice='opt'>-I <replaceable>path</replaceable></arg> |
| 28 | 30 | <arg choice='plain' rep='repeat'><replaceable>file</replaceable></arg> |
| 29 | 31 | </cmdsynopsis> |
| 67 | 69 | markup that <command>doclifter</command> cannot translate into |
| 68 | 70 | structure; the output will require hand-fixing.</para> |
| 69 | 71 | |
| 70 | <para>The tag <markup>.ta</markup> is passed through with a complaint unless | |
| 71 | followed by text lines containing tabs, in which case the following | |
| 72 | span of lines containing tabs is lifted to a table.</para> | |
| 72 | <para>The tag <markup>.ta</markup> is passed through with a complaint | |
| 73 | unless the immediarely following by text lines contains a tab, in | |
| 74 | which case the following span of lines containing tabs is lifted to a | |
| 75 | table.</para> | |
| 73 | 76 | |
| 74 | 77 | <para>Under some circumstances, <command>doclifter</command> can even |
| 75 | 78 | lift formatted manual pages and the text output produced by |
| 83 | 86 | pages.</para> |
| 84 | 87 | |
| 85 | 88 | <para><command>doclifter</command> does not do a perfect job, merely |
| 86 | an extremely good one. Final polish should be applied by a human | |
| 89 | a surprisingly good one. Final polish should be applied by a human | |
| 87 | 90 | being capable of recognizing patterns too subtle for a computer. But |
| 88 | 91 | <command>doclifter</command> will almost always produce translations |
| 89 | 92 | that are good enough to be usable before hand-hacking.</para> |
| 168 | 171 | -w increase the strictness. See <xref linkend='portability'/>.</para> |
| 169 | 172 | </listitem> |
| 170 | 173 | </varlistentry> |
| 174 | <varlistentry> | |
| 175 | <term>-V</term> | |
| 176 | <listitem> | |
| 177 | <para>With this option, the program emits a version message and exits.</para> | |
| 178 | </listitem> | |
| 179 | </varlistentry> | |
| 171 | 180 | </variablelist> |
| 172 | 181 | </refsect1> |
| 173 | 182 | |
| 201 | 210 | |
| 202 | 211 | <para><command>doclifter</command> does a good job on most man pages, |
| 203 | 212 | It knows about the extended |
| 204 | <markup>UR</markup>/<markup>UE</markup>/<markup>UN</markup> requests | |
| 205 | supported under Linux. If any <markup>.UR</markup> request is | |
| 206 | present, it will translate these but not wrap URLs outide them with | |
| 207 | <sgmltag>Ulink</sgmltag> tags. It also knows about the extended | |
| 208 | <markup>.L</markup> (literal) font markup from Bell Labs Version 8, | |
| 209 | and its friends.</para> | |
| 213 | <markup>UR</markup>/<markup>UE</markup>/<markup>UN</markup> and | |
| 214 | <markup>URL</markup> requests supported under Linux. If any | |
| 215 | <markup>.UR</markup> request is present, it will translate these but | |
| 216 | not wrap URLs outide them with <sgmltag>Ulink</sgmltag> tags. It also | |
| 217 | knows about the extended <markup>.L</markup> (literal) font markup | |
| 218 | from Bell Labs Version 8, and its friends.</para> | |
| 210 | 219 | |
| 211 | 220 | <para>The <markup>.TH</markup> macro is used to generate a <sgmltag |
| 212 | 221 | class='element'>RefMeta</sgmltag> section. If present, the |
| 261 | 270 | list markup. When <markup>.RS</markup> occurs just before <markup>.TP</markup> |
| 262 | 271 | or <markup>.IP</markup> the result is nested lists. Otherwise, the |
| 263 | 272 | <markup>.RS</markup>/<markup>.RE</markup> pair is translated into a |
| 264 | Blockquote tag-pair.</para> | |
| 273 | <sgmltag>Blockquote</sgmltag> tag-pair.</para> | |
| 265 | 274 | |
| 266 | 275 | <para><markup>.DS</markup>/<markup>.DE</markup> is not part of the |
| 267 | 276 | documented man macro set, but is recognized because it shows up with |
| 283 | 292 | <markup>.FN</markup>, <markup>.IN</markup>, <markup>.ZN</markup>, |
| 284 | 293 | <markup>.hN</markup>, and <markup>.C{</markup>/<markup>.C}</markup> |
| 285 | 294 | <!-- triggers display parsing.--> The <markup>.TA</markup> and |
| 286 | <markup>IN</markup> requests are ignored.</para> | |
| 295 | <markup>.IN</markup> requests are ignored.</para> | |
| 287 | 296 | |
| 288 | 297 | <para>When the man macros are active, any <markup>.Pp</markup> macro |
| 289 | 298 | definition containing the request <markup>.PP</markup> will be |
| 335 | 344 | <markup>.DE</markup>, <markup>.SO</markup>, <markup>.SE</markup>, |
| 336 | 345 | <markup>.UL</markup>, <markup>.VS</markup>, <markup>.VE</markup>. The |
| 337 | 346 | <markup>.AP</markup>, <markup>.CS</markup>, <markup>.CE</markup>, |
| 338 | <markup>.SO</markup>, <markup>.SE</markup>, and <markup>.UL</markup> | |
| 347 | <markup>.SO</markup>, <markup>.SE</markup>, <markup>.UL</markup>, | |
| 348 | <markup>.QW</markup> and <markup>.PQ</markup> | |
| 339 | 349 | macros are translated structurally. |
| 340 | 350 | <!-- <markup>.CS</markup>/<markup>.CE</markup> triggers display processing. --> |
| 341 | 351 | </para> |
| 521 | 531 | <markup>MAILTO</markup>, <markup>FTP</markup>, <markup>IMAGE</markup>, |
| 522 | 532 | <markup>TAG</markup> tags are translated structurally. The |
| 523 | 533 | <markup>HTMLINDEX</markup>, <markup>BODYCOLOR</markup>, |
| 524 | <markup>BACKGROUND</markup>, <markup>HTML</markup>, an | |
| 534 | <markup>BACKGROUND</markup>, <markup>HTML</markup>, and | |
| 525 | 535 | <markup>LINE</markup> tags are ignored.</para> |
| 526 | 536 | </refsect2> |
| 527 | 537 | |
| 593 | 603 | translation on output. Calls to <markup>.bp</markup> generate a |
| 594 | 604 | <sgmltag class='element'>BeginPage</sgmltag> tag (in paragraphed text |
| 595 | 605 | only). Calls to <markup>.sp</markup> generate a paragraph break (in |
| 596 | paragraphed text only). These are the only troff requests we | |
| 597 | translate to DocBook. The rest of the troff emulation exists because | |
| 598 | macro packages use it internally to expand macros into elements that | |
| 599 | might be structural.</para> | |
| 606 | paragraphed text only). Calls to <markup>.ti</markup> wrap the | |
| 607 | following line in a <sgmltag class='element'>BlockQuote</sgmltag> | |
| 608 | These are the only troff requests we translate to DocBook. The rest | |
| 609 | of the troff emulation exists because macro packages use it internally | |
| 610 | to expand macros into elements that might be structural.</para> | |
| 600 | 611 | |
| 601 | 612 | <para>Requests relating to macro definitions and strings |
| 602 | 613 | (<markup>.ds</markup>, <markup>.as</markup>, <markup>.de</markup>, |
| 607 | 618 | <para>Conditional macros (<markup>.if</markup>, <markup>.ie</markup>, |
| 608 | 619 | <markup>.el</markup>) are handled. The built-in conditions o, n, t, |
| 609 | 620 | e, and c are evaluated as if for <application>nroff</application> on |
| 610 | page one of a document. String comparisons are evaluated by straight | |
| 621 | page one of a document. The m, d, and r troff conditionals | |
| 622 | are also interpreted. String comparisons are evaluated by straight | |
| 611 | 623 | textual comparison. All numeric expressions evaluate to true. </para> |
| 612 | 624 | |
| 613 | 625 | <para>The extended <application>groff</application> requests |
| 626 | 638 | <para>Some troff escape sequences are lifted:</para> |
| 627 | 639 | |
| 628 | 640 | <orderedlist> |
| 629 | <listitem><para>The \e escape becomes a bare backslash, \. a period, and \- | |
| 630 | a bare dash.</para></listitem> | |
| 641 | <listitem><para>The \e and \\ escapes become a bare backslash, \. a | |
| 642 | period, and \- a bare dash.</para></listitem> | |
| 631 | 643 | |
| 632 | 644 | <listitem><para>The troff escapes \^, \`, \' \&, \0, and \| are lifted |
| 633 | 645 | to equivalent ISO special spacing characters.</para></listitem> |
| 752 | 764 | </refsect1> |
| 753 | 765 | |
| 754 | 766 | <refsect1 id="troubleshooting"><title>Troubleshooting</title> |
| 767 | ||
| 755 | 768 | <para><command>doclifter</command> tries to warn about problems that |
| 756 | 769 | it can can diagnose but not fix by itself. When it says |
| 757 | 770 | <computeroutput>"look for FIXME"</computeroutput>, do that in the |
| 764 | 777 | ability of <command>doclifter</command>'s macro processor to get |
| 765 | 778 | right. Here are some things to watch for, and how to fix them:</para> |
| 766 | 779 | |
| 767 | <para><emphasis>Malformed command synopses.</emphasis> If you get a | |
| 780 | <refsect2><title>Malformed command synopses.</title> | |
| 781 | ||
| 782 | <para>If you get a | |
| 768 | 783 | message that says <computeroutput>"command synopsis parse |
| 769 | failed"</computeroutput>, look at the XML output. It will contain a | |
| 770 | comment telling you what the command synopsis looked like after | |
| 784 | failed"</computeroutput>, try rewriting the synopsis in your manual | |
| 785 | page source. The most common cause of failure is unbalanced [] | |
| 786 | groupings, a bug that can be very difficult to notice by eyeball. To | |
| 787 | assist with this, the error message includes a token number in | |
| 788 | parentheses indicating on which token the parse failed.</para> | |
| 789 | ||
| 790 | <para>For more information, use the -v option. This will trigger | |
| 791 | a dump telling you what the command synopsis looked like after | |
| 771 | 792 | preprocessing, and indicate on which token the parse failed (both with |
| 772 | 793 | a token number and a caret sign inserted in the dump of the synopsis |
| 773 | 794 | tokens). Try rewriting the synopsis in your manual page source. The |
| 777 | 798 | last nesting-depth increase, but the code that does this is |
| 778 | 799 | failure-prone.</para> |
| 779 | 800 | |
| 780 | <para><emphasis>Confusing macro calls.</emphasis> Some manual page | |
| 781 | authors replace standard requests (like <markup>.PP</markup>, | |
| 782 | <markup>.SH</markup> and <markup>.TP</markup>) with versions that do | |
| 783 | different things in <command>nroff</command> and | |
| 801 | </refsect2> | |
| 802 | <refsect2><title>Confusing macro calls.</title> | |
| 803 | ||
| 804 | <para>Some manual page authors replace standard requests (like | |
| 805 | <markup>.PP</markup>, <markup>.SH</markup> and <markup>.TP</markup>) | |
| 806 | with versions that do different things in <command>nroff</command> and | |
| 784 | 807 | <command>troff</command> environments. While |
| 785 | 808 | <command>doclifter</command> tries to cope and usually does a good |
| 786 | 809 | job, the quirks of [nt]roff are legion and confusing macro calls |
| 787 | 810 | sometimes lead to bad XML being generated. A common symptom of such |
| 788 | 811 | problems is unclosed <sgmltag class='element'>Emphasis</sgmltag> |
| 789 | 812 | tags.</para> |
| 813 | ||
| 814 | </refsect2> | |
| 815 | <refsect2><title>Malformed list syntax.</title> | |
| 816 | ||
| 817 | <para> The manual-page parser can be confused by <markup>.TP</markup> | |
| 818 | constructs that have header tags but no following body. If the XML | |
| 819 | produced doesn't validate, and the problem seems to be a misplaced | |
| 820 | <sgmltag>listitem</sgmltag> tag, try using the verbose (-v) option. | |
| 821 | This will enable line-numbered warnings that may help you zero in on | |
| 822 | the problem.</para> | |
| 823 | ||
| 824 | </refsect2> | |
| 825 | <refsect2><title>Section nesting problems with SS.</title> | |
| 790 | 826 | |
| 791 | 827 | <para>The message <computeroutput>"possible section nesting |
| 792 | 828 | error"</computeroutput> means that the program has seen two adjacent |
| 796 | 832 | indicated line and the beginning of the next top-level section might |
| 797 | 833 | be wrong and require correcting by hand.</para> |
| 798 | 834 | |
| 799 | <para>If you're translating a page that uses user-defined macros and | |
| 800 | you get bad output, the first thing to do is simplify or eliminate | |
| 801 | the user-defined macros. Replace them with stock requests where | |
| 802 | possible.</para> | |
| 803 | </refsect1> | |
| 804 | ||
| 805 | <!-- refsect1 id='improving'><title>Improving Translation Quality</title> | |
| 806 | <para>The troff-level <markup>.nf</markup>/<markup>.fi</markup> macros | |
| 835 | </refsect2> | |
| 836 | <refsect2><title>Bad output with no doclifter error message</title> | |
| 837 | ||
| 838 | <para>If you're translating a page that uses user-defined macros, and | |
| 839 | doclifter fails to complain about it but you get bad output, the first | |
| 840 | thing to do is simplify or eliminate the user-defined macros. Replace | |
| 841 | them with stock requests where possible.</para> | |
| 842 | ||
| 843 | </refsect2> | |
| 844 | </refsect1> | |
| 845 | ||
| 846 | <refsect1 id='improving'><title>Improving Translation Quality</title> | |
| 847 | ||
| 848 | <para>There are a few constructions that are a good idea to check by hand | |
| 849 | after lifting a page.</para> | |
| 850 | ||
| 851 | <para>Look near the <sgmltag class='element'>BlockQuote</sgmltag> tags. | |
| 852 | The troff temporary indent request (<markup>.ti</markup>) is translated | |
| 853 | into a <sgmltag class='element'>BlockQuote</sgmltag> wrapper around the | |
| 854 | following line. Sometimes <sgmltag class='element'>LiteralLayout</sgmltag> | |
| 855 | or <sgmltag class='element'>ProgramListing</sgmltag> would be a better | |
| 856 | translation, but <command>doclifter</command> has no way to know this. | |
| 857 | </para> | |
| 858 | ||
| 859 | <para>It is not possible to unambiguously detect candidates for | |
| 860 | wrapping in a DocBook <sgmltag>option</sgmltag> tag in running | |
| 861 | text. If you care, you'll have to check for these and fix them by | |
| 862 | hand.</para> | |
| 863 | ||
| 864 | <!-- para>The troff-level <markup>.nf</markup>/<markup>.fi</markup> macros | |
| 807 | 865 | don't trigger display parsing (doing so would wildly complicate macro |
| 808 | 866 | interpretation). If you are translating a document that uses them to wrap |
| 809 | 867 | function synopses, you can improve the translation by hand-hacking |
| 810 | 868 | them to <markup>.DS</markup>/<markup>.DE</markup> or the equivalent in |
| 811 | whatever macro set is active.</para> | |
| 812 | </refsect1 --> | |
| 869 | whatever macro set is active.</para --> | |
| 870 | ||
| 871 | </refsect1> | |
| 872 | ||
| 873 | <refsect1><title>Bugs And Limitations</title> | |
| 874 | ||
| 875 | <para>About 3% of man pages will either make this program throw error status | |
| 876 | 1 or generate invalid XML. In almost all such cases the misbehavior is | |
| 877 | triggered by markup bugs in the source that are too severe to be | |
| 878 | coped with.</para> | |
| 879 | ||
| 880 | <para>Equation number arguments of EQN calls are ignored.</para> | |
| 881 | ||
| 882 | <para>The function-synopsis parser is crude (it's not a compiler) and | |
| 883 | prone to errors. Function-synopsis markup should be checked carefully | |
| 884 | by a human.</para> | |
| 885 | ||
| 886 | <para>If a man page has both paragraphed text in a Synopsis section | |
| 887 | and also a body section before the Synopis section, bad things will | |
| 888 | happen.</para> | |
| 889 | ||
| 890 | <para>Running text (e.g., explanatory notes) at the end of a Synopsis | |
| 891 | section cannot reliably be distinguished from synopsis-syntax | |
| 892 | markup. (This problem is AI-complete.)</para> | |
| 893 | ||
| 894 | <para>Some firewalls put in to cope with common malformations in troff | |
| 895 | code mean that the tail end of a span between two | |
| 896 | <markup>\f{B,I,U,(CW}</markup> or <markup>.ft</markup> highlight | |
| 897 | changes may not be completely covered by corresponding <sgmltag | |
| 898 | class='element'>Emphasis</sgmltag> macros if (for example) the span | |
| 899 | crosses a boundary between filled and unfilled | |
| 900 | (<markup>.nf</markup>/<markup>.fi</markup>) text.</para> | |
| 901 | ||
| 902 | <para>The treatment of conditionals relies on the assumption that | |
| 903 | conditional macros never generate structural or font-highlight markup | |
| 904 | that differs between the if and else branches. This appears to be | |
| 905 | true of all the standard macro packages, but if you roll any of your | |
| 906 | own macros you're on your own.</para> | |
| 907 | ||
| 908 | <para>Macro definitions in a manual page NAME section are not | |
| 909 | interpreted.</para> | |
| 910 | ||
| 911 | <para>Uses of \c for line continuation sometimes are not translated, | |
| 912 | leaving the \c in the output XML. The program will print a warning | |
| 913 | when this occurs.</para> | |
| 914 | ||
| 915 | <para>It is not possible to unambiguously detect candidates for | |
| 916 | wrapping in a DocBook <sgmltag>option</sgmltag> tag in running | |
| 917 | text. If you care, you'll have to check for these and fix them by | |
| 918 | hand.</para> | |
| 919 | ||
| 920 | <para>The line numbers in <command>doclifter</command> error messages | |
| 921 | are unreliable in the presence of <markup>.EQ/.EN</markup>, | |
| 922 | <markup>.PS/.PE</markup>, and quantum fluctuations.</para> | |
| 923 | </refsect1> | |
| 924 | ||
| 925 | <refsect1><title>Old macro sets</title> | |
| 926 | <para>There is a conflict between Berkeley ms's documented | |
| 927 | <markup>.P1</markup> print-header-on-page request and an undocumented | |
| 928 | Bell Labs use for displayed program and equation listings. The | |
| 929 | <emphasis remap='B'>ms</emphasis> translator uses the Bell Labs | |
| 930 | interpretation when <markup>.P2</markup> is present in the document, | |
| 931 | and otherwise ignores the request.</para> | |
| 932 | </refsect1> | |
| 813 | 933 | |
| 814 | 934 | <refsect1><title>Return Values</title> |
| 815 | 935 | <para>On successful completion, the program returns status 0. |
| 820 | 940 | It returns 5 when aborted by a keyboard interrupt. </para> |
| 821 | 941 | |
| 822 | 942 | <para>Note that a zero return does not guarantee that the output is |
| 823 | valid DocBook. It will almost always (as in, more than 96% of cases) | |
| 943 | valid DocBook. It will almost always (as in, more than 98% of cases) | |
| 824 | 944 | be syntactically valid XML, but in some rare cases fixups by hand may be |
| 825 | 945 | necessary to meet the semantics of the DocBook DTD. Validation |
| 826 | 946 | problems are most likely to occur with complicated list markup.</para> |
| 827 | </refsect1> | |
| 828 | ||
| 829 | <refsect1><title>Bugs And Warnings</title> | |
| 830 | ||
| 831 | <para>About 4% of man pages will either make this program throw error status | |
| 832 | 1 or generate invalid XML. In almost all such cases the misbehavior is | |
| 833 | triggered by markup bugs in the source that are too severe to be | |
| 834 | coped with.</para> | |
| 835 | ||
| 836 | <para>Equation number arguments of EQN calls are ignored.</para> | |
| 837 | ||
| 838 | <para>The function-synopsis parser is crude (it's not a compiler) and | |
| 839 | prone to errors. Function-synopsis markup should be checked carefully | |
| 840 | by a human.</para> | |
| 841 | ||
| 842 | <para>If a man page has both paragraphed text in a Synopsis section | |
| 843 | and also a body section before the Synopis section, bad things will | |
| 844 | happen.</para> | |
| 845 | ||
| 846 | <para>Running text (e.g., explanatory notes) at the end of a Synopsis | |
| 847 | section cannot reliably be distinguished from synopsis-syntax | |
| 848 | markup. (This problem is AI-complete.)</para> | |
| 849 | ||
| 850 | <para>Some firewalls put in to cope with common malformations in troff | |
| 851 | code mean that the tail end of a span between two | |
| 852 | <markup>\f{B,I,U,(CW}</markup> or <markup>.ft</markup> highlight | |
| 853 | changes may not be completely covered by corresponding <sgmltag | |
| 854 | class='element'>Emphasis</sgmltag> macros if (for example) the span | |
| 855 | crosses a boundary between filled and unfilled | |
| 856 | (<markup>.nf</markup>/<markup>.fi</markup>) text.</para> | |
| 857 | ||
| 858 | <para>The treatment of conditionals relies on the assumption that | |
| 859 | conditional macros never generate structural or font-highlight markup | |
| 860 | that differs between the if and else branches. This appears to be | |
| 861 | true of all the standard macro packages, but if you roll any of your | |
| 862 | own macros you're on your own.</para> | |
| 863 | ||
| 864 | <para>Macro definitions in a manual page NAME section are not | |
| 865 | interpreted.</para> | |
| 866 | ||
| 867 | <para>In Berkeley mdoc interpretation, handling of | |
| 868 | <markup>.Xo</markup>/<markup>.Xc</markup> enclosures is failure-prone.</para> | |
| 869 | ||
| 870 | <para>Uses of \c for line continuation sometimes are not translated, | |
| 871 | leaving the \c in the output XML. The program will print a warning | |
| 872 | when this occurs.</para> | |
| 873 | ||
| 874 | <para>It is not possible to unambiguously detect candidates for | |
| 875 | wrapping in a DocBook option tag in running text. You'll have to check | |
| 876 | for these by hand.</para> | |
| 877 | ||
| 878 | <para>The line numbers in <command>doclifter</command> error messages | |
| 879 | are unreliable in the presence of <markup>.EQ/.EN</markup>, | |
| 880 | <markup>.PS/.PE</markup>, and quantum fluctuations.</para> | |
| 881 | </refsect1> | |
| 882 | ||
| 883 | <refsect1><title>Old macro sets</title> | |
| 884 | <para>There is a conflict between Berkeley ms's documented | |
| 885 | <markup>.P1</markup> print-header-on-page request and an undocumented | |
| 886 | Bell Labs use for displayed program and equation listings. The | |
| 887 | <emphasis remap='B'>ms</emphasis> translator uses the Bell Labs | |
| 888 | interpretation when <markup>.P2</markup> is present in the document, | |
| 889 | and otherwise ignores the request.</para> | |
| 890 | 947 | </refsect1> |
| 891 | 948 | |
| 892 | 949 | <refsect1><title>Requirements</title> |
| 0 | .\" Test load for doclifter | |
| 1 | .TH docliftertest1 1 | |
| 2 | .SH NAME | |
| 3 | docliftertest1 \- section 1 test load for doclifter | |
| 4 | .SH SYNOPSIS | |
| 5 | \fBdocliftertest1\fR [-a | -b] [\fIoptional...\fR] | |
| 6 | ||
| 7 | \fBdocliftertest1\fR -c \fI<required>\fP | |
| 8 | ||
| 9 | \fBdocliftertest1\fR -d | |
| 10 | [ | |
| 11 | .B optional | |
| 12 | ] | |
| 13 | ||
| 14 | \fBdocliftertest1\fR [ -e | -f foo ] ... | |
| 15 | .SH DESCRIPTION | |
| 16 | This file is a test load for doclifter, intended to exercise as much as possible | |
| 17 | of its translation capability. You are now reading the last sentence | |
| 18 | of an ordinary paragraph; by inspecting the output, you can check that | |
| 19 | your formatter is generating a correct beginning-of-body even after | |
| 20 | the section title, and an end-of-body event at the end of the | |
| 21 | paragraph. | |
| 22 | .PP | |
| 23 | This is an ordinary paragraph started by a \fB.PP\fR macro. | |
| 24 | A second line illustrates the effect of filling. | |
| 25 | .PP | |
| 26 | This | |
| 27 | .B word | |
| 28 | should be bold. This | |
| 29 | .SM word | |
| 30 | should be small. The word | |
| 31 | .SM ASCII | |
| 32 | is actually an acronym. This is a reference to section: | |
| 33 | .SM SEE ALSO | |
| 34 | it should be a link now. Visiting the | |
| 35 | .SM SYNOPSIS | |
| 36 | is important. While the | |
| 37 | .SM SYNOPYOSIS | |
| 38 | is not important and doesn't exist. | |
| 39 | .IR This sentence should alternate italic and bold. | |
| 40 | The words in the last sentence should have been run together. | |
| 41 | .LP | |
| 42 | This is an ordinary paragraph started by a \fB.LP\fR macro. | |
| 43 | A second line illustrates the effect of filling. | |
| 44 | .HP 5 | |
| 45 | This is a paragraph started by an \fB.HP\fR macro. | |
| 46 | We translate it to DocBook as an ordinary paragraph break. | |
| 47 | .IP & 5 | |
| 48 | This paragraph was led with \fB.IP & 5\fP. | |
| 49 | A sample line to see how it formats -- it should turn into list markup. | |
| 50 | .PP | |
| 51 | There should be an index entry generated right after this sentence. | |
| 52 | .IX Item <sample> | |
| 53 | And right before this one. | |
| 54 | .IP 5 | |
| 55 | This paragraph was led with \fB.IP 5\fP. | |
| 56 | This should turn into an ordinary paragraph. | |
| 57 | .PP | |
| 58 | This paragraph contains a URL, http://www.google.com, that doesn't have | |
| 59 | explicit \fB.UR\fP/\fB.UN\fR tags around it. It should not be marked | |
| 60 | up, because \fB.UR\fP/\fB.UN\fR tags exist in this document. | |
| 61 | .IP \(bu | |
| 62 | This is the first item in a bulleted list. | |
| 63 | .IP \(bu | |
| 64 | This is the second item in a bulleted list. | |
| 65 | .IP \(bu | |
| 66 | This is the third item in a bulleted list. | |
| 67 | .PP | |
| 68 | This is another ordinary paragraph. It's going to be immediately | |
| 69 | followed (without an intervening paragraph tag) by a table example | |
| 70 | lifted straight from Mike Lesk's original tbl paper: | |
| 71 | .TS | |
| 72 | center, box; | |
| 73 | c s s s | |
| 74 | c s s s | |
| 75 | c |c |c |c | |
| 76 | c |c |c |c | |
| 77 | l |n |n |n. | |
| 78 | 1970 Federal Budget Transfers | |
| 79 | \s-2(in billions of dollars)\s0 | |
| 80 | = | |
| 81 | State Taxes Money Net | |
| 82 | \^ collected spent \^ | |
| 83 | _ | |
| 84 | New York 22.91 21.35 \-1.56 | |
| 85 | New Jersey 8.33 6.96 \-1.37 | |
| 86 | Connecticut 4.12 3.10 \-1.02 | |
| 87 | Maine 0.74 0.67 \-0.07 | |
| 88 | California 22.29 22.42 +0.13 | |
| 89 | New Mexico 0.70 1.49 +0.79 | |
| 90 | Georgia 3.30 4.28 +0.98 | |
| 91 | Mississippi 1.15 2.32 +1.17 | |
| 92 | Texas 9.33 11.13 +1.80 | |
| 93 | .TE | |
| 94 | In the above table, the presence or absence of cell borders may not be | |
| 95 | exactly as | |
| 96 | .BR tbl (1) | |
| 97 | specified them (the DocBook DSSL toolchain sets BORDER=1 if there is | |
| 98 | any frame attribute, which is wrong; according to the DocBook | |
| 99 | specification, the frame attribute should only control box drawing | |
| 100 | around the exterior of the table). But the horizontal spanning and | |
| 101 | centering should be displayed properly. | |
| 102 | .SS MORE TABLES | |
| 103 | We just started a subsection. | |
| 104 | .P | |
| 105 | Here's another table. The first line of the table contains a heading | |
| 106 | centered across all three columns; each remaining line contains a | |
| 107 | left-adjusted item in the first column followed by two columns of | |
| 108 | numerical data. (The numerical alignment won't translate into DocBook.) | |
| 109 | .TS | |
| 110 | c s s | |
| 111 | l n n. | |
| 112 | Overall title | |
| 113 | Item-a 34.22 9.1 | |
| 114 | Item-b 12.65 .02 | |
| 115 | Items: c,d,e 23 5.8 | |
| 116 | Total 69.87 14.92 | |
| 117 | .TE | |
| 118 | This table illustrates the effect of the \fBexpand\fR option: | |
| 119 | .TS | |
| 120 | expand; | |
| 121 | c s s s | |
| 122 | c c c c | |
| 123 | l l n n. | |
| 124 | Bell Labs Locations | |
| 125 | Name Address Area Code Phone | |
| 126 | Holmdel Holmdel, N. J. 07733 201 949-3000 | |
| 127 | Murray Hill Murray Hill, N. J. 07974 201 582-6377 | |
| 128 | Whippany Whippany, N. J. 07981 201 386-3000 | |
| 129 | Indian Hill Naperville, Illinois 60540 312 690-2000 | |
| 130 | .TE | |
| 131 | Here's a really gnarly table with a lot of vertically spanned | |
| 132 | content and several multiline items per line. However this | |
| 133 | is not done with a vertically-spanned format; for that, see the | |
| 134 | next example. | |
| 135 | .TS | |
| 136 | box; | |
| 137 | cb s s s | |
| 138 | c | c | c s | |
| 139 | ltiw(1i) | ltw(2i) | lp8| lw(1.6i)p8. | |
| 140 | Some Interesting Places | |
| 141 | _ | |
| 142 | Name Description Practical Information | |
| 143 | _ | |
| 144 | T{ | |
| 145 | American Museum of Natural History | |
| 146 | T} T{ | |
| 147 | The collections fill 11.5 acres (Michelin) or 25 acres (MTA) | |
| 148 | of exhibition halls on four floors. | |
| 149 | There is a full-sized replica | |
| 150 | of a blue whale and the world's largest star sapphire (stolen in 1964). | |
| 151 | T} Hours 10-5, ex. Sun 11-5, Wed. to 9 | |
| 152 | \^ \^ Location T{ | |
| 153 | Central Park West & 79th St. | |
| 154 | T} | |
| 155 | \^ \^ Admission Donation: $1.00 asked | |
| 156 | \^ \^ Subway AA to 81st St. | |
| 157 | \^ \^ Telephone 212-873-4225 | |
| 158 | _ | |
| 159 | Bronx Zoo T{ | |
| 160 | About a mile long and .6 mile wide, this is the largest zoo in America. | |
| 161 | A lion eats 18 pounds | |
| 162 | of meat a day while a sea lion eats 15 pounds of fish. | |
| 163 | T} Hours T{ | |
| 164 | 10-4:30 winter, to 5:00 summer | |
| 165 | T} | |
| 166 | \^ \^ Location T{ | |
| 167 | 185th St. & Southern Blvd, the Bronx. | |
| 168 | T} | |
| 169 | \^ \^ Admission $1.00, but Tu,We,Th free | |
| 170 | \^ \^ Subway 2, 5 to East Tremont Ave. | |
| 171 | \^ \^ Telephone 212-933-1759 | |
| 172 | _ | |
| 173 | Brooklyn Museum T{ | |
| 174 | Five floors of galleries contain American and ancient art. | |
| 175 | There are American period rooms and architectural ornaments saved | |
| 176 | from wreckers, such as a classical figure from Pennsylvania Station. | |
| 177 | T} Hours Wed-Sat, 10-5, Sun 12-5 | |
| 178 | \^ \^ Location T{ | |
| 179 | Eastern Parkway & Washington Ave., Brooklyn. | |
| 180 | T} | |
| 181 | \^ \^ Admission Free | |
| 182 | \^ \^ Subway 2,3 to Eastern Parkway. | |
| 183 | \^ \^ Telephone 212-638-5000 | |
| 184 | _ | |
| 185 | T{ | |
| 186 | New-York Historical Society | |
| 187 | T} T{ | |
| 188 | All the original paintings for Audubon's | |
| 189 | .I Birds of America | |
| 190 | are here, as are exhibits of American decorative arts, New York history, | |
| 191 | Hudson River school paintings, carriages, and glass paperweights. | |
| 192 | T} Hours T{ | |
| 193 | Tues-Fri & Sun, 1-5; Sat 10-5 | |
| 194 | T} | |
| 195 | \^ \^ Location T{ | |
| 196 | Central Park West & 77th St. | |
| 197 | T} | |
| 198 | \^ \^ Admission Free | |
| 199 | \^ \^ Subway AA to 81st St. | |
| 200 | \^ \^ Telephone 212-873-3400 | |
| 201 | .TE | |
| 202 | OK, here is a table example with spanned vertical format. It | |
| 203 | illustrates the vertical-spanning bug noted on the | |
| 204 | .BR doclifter (1) | |
| 205 | manual page (but | |
| 206 | .BR troff2docbook (1) | |
| 207 | translates this table correctly). If the translation were completely | |
| 208 | correct, the "E" entry would span one row further downward. | |
| 209 | .TS | |
| 210 | allbox; | |
| 211 | l l l | |
| 212 | l l l | |
| 213 | l ^ l. | |
| 214 | A B C | |
| 215 | _ | |
| 216 | D E F | |
| 217 | G H | |
| 218 | I J | |
| 219 | .TE | |
| 220 | .P | |
| 221 | Now we'll test PIC translation to SVG. | |
| 222 | .PS | |
| 223 | box "box" | |
| 224 | .PE | |
| 225 | This line tests recognition of \v'-.4m'\fIsuperscripting\fR\v'.4m') | |
| 226 | ,br | |
| 227 | This line tests recognition of the \uother\d superscript idiom. | |
| 228 | ||
| 229 | .SH FILES | |
| 230 | The following items illustrate \fB.TP\fR markup: | |
| 231 | .TP 5 | |
| 232 | ${HOME}/.profile | |
| 233 | read at startup by | |
| 234 | .BR sh (1). | |
| 235 | .TP | |
| 236 | /etc/hosts | |
| 237 | list of static host addresses used by the \fIbind\fR(8) library. | |
| 238 | .SH SEE ALSO | |
| 239 | ls(1), | |
| 240 | .IR mkdir (1). | |
| 241 | .\" End |
| 12 | 12 | makehtml = False |
| 13 | 13 | xslfragment = None |
| 14 | 14 | processed = set([]) |
| 15 | excluded_files = [] | |
| 15 | 16 | |
| 16 | 17 | def manfile(section, basename=""): |
| 17 | 18 | "Return a manual file or directory based on section name." |
| 30 | 31 | def analyze_manpage(manpage): |
| 31 | 32 | "Provide log annotations based on content." |
| 32 | 33 | exclusions = ( |
| 33 | ("auto-generated by docbook2man-spec", "SGML DocBook"), | |
| 34 | ("<html>", "This page is HTML"), | |
| 35 | ("auto-generated by docbook2man-spec", "DocBook"), | |
| 36 | ("automatically generated by docbook2man", "DocBook"), | |
| 34 | 37 | ("Generated by db2man.xsl", "XML DocBook"), |
| 35 | 38 | ("Automatically generated by Pod::Man", "Pod::Man"), |
| 36 | ("Man page generated from reStructeredText", "reStructeredText."), | |
| 39 | ("Man page generated from reStructeredText", "reStructuredText"), | |
| 40 | ("Man page generated from reStructuredText", "reStructuredText"), | |
| 41 | ("Generator: DocBook XSL Stylesheets", "DocBook stylesheets"), | |
| 42 | ("Generated by docutils manpage writer", "docutils"), | |
| 43 | ("DocBook SGML with docbook-to-man", "DocBook SGML"), | |
| 44 | ("Doxygen", "Doxygen"), | |
| 37 | 45 | ) |
| 38 | 46 | output = "" |
| 39 | # Check to see if it has DocBook masters | |
| 40 | 47 | fp = open(manpage) |
| 41 | firstline = fp.readline() | |
| 48 | text = fp.read() | |
| 42 | 49 | for (pattern, generator) in exclusions: |
| 43 | if firstline.find(pattern) > -1: | |
| 50 | if text.find(pattern) > -1: | |
| 44 | 51 | output += "Generated from %s\n" % generator |
| 45 | if firstline.startswith("<html>"): | |
| 46 | output += "This page is HTML.\n" | |
| 47 | 52 | fp.close() |
| 48 | 53 | return output |
| 49 | 54 | |
| 78 | 83 | file = ".".join(file.split(".")[:-1]) # Remove section |
| 79 | 84 | return file |
| 80 | 85 | |
| 81 | def make_xml(source, options, batchmode): | |
| 86 | def make_xml(source, options): | |
| 82 | 87 | "Make XML from specified man page." |
| 83 | doclifter.stdout = doclifter.stderr = keep_io = cStringIO.StringIO() | |
| 84 | args = ["-I", mandir,] + options.split() + [source,] | |
| 85 | doclifter_status = doclifter.main(args, keep_io, keep_io) | |
| 86 | output = keep_io.getvalue() | |
| 87 | keep_io.close() | |
| 88 | (doclifter_status, output) = commands.getstatusoutput("doclifter -I %s %s %s" % (mandir, options, source)) | |
| 89 | if output: | |
| 90 | output += "\n" | |
| 91 | if os.WIFEXITED(doclifter_status): | |
| 92 | doclifter_status = os.WEXITSTATUS(doclifter_status) | |
| 93 | else: | |
| 94 | # Should never happen | |
| 95 | raise ValueError | |
| 88 | 96 | lxmlloc = None |
| 89 | 97 | if doclifter_status == 2: |
| 90 | 98 | fp = open(source) |
| 104 | 112 | # usually trivial wrappers like builtins.1 |
| 105 | 113 | try: |
| 106 | 114 | fp = open(translation) |
| 107 | inclusions = re.compile("<!ENTITY.*SYSTEM '(.*)'>").search(fp.read()) | |
| 115 | text = fp.read() | |
| 116 | inclusions = re.compile("<!ENTITY.*SYSTEM '(.*)'>").search(text) | |
| 117 | equation = "<equation" in text | |
| 108 | 118 | fp.close() |
| 109 | 119 | if inclusions: |
| 110 | 120 | output += "Won't validate due to entity inclusion of %s\n" % inclusions.group(1) |
| 121 | return (0, output) | |
| 122 | if equation: | |
| 123 | output += "Won't validate due to MathML inclusions\n" | |
| 111 | 124 | return (0, output) |
| 112 | 125 | except IOError: |
| 113 | 126 | output += "%s is missing.\n" % translation |
| 190 | 203 | global processed |
| 191 | 204 | tmpstem = os.path.join(outdir, tmpstem) |
| 192 | 205 | source = tmpstem + ".man" |
| 206 | # Grab the actual manual page | |
| 207 | localcopy = os.path.join(outdir, withsect) | |
| 208 | (status, output) = fetch_page(file, localcopy, patch) | |
| 209 | if (status): | |
| 210 | return (status, False, output) | |
| 193 | 211 | # Save work by doing conversions only as needed |
| 212 | analysis = analyze_manpage(localcopy) | |
| 194 | 213 | rebuild_xml = True |
| 195 | 214 | if batchmode and os.path.exists(xmlloc): |
| 196 | 215 | if os.stat(file).st_mtime < os.lstat(xmlloc).st_mtime: |
| 197 | output += "XML conversion is up to date\n" | |
| 216 | output += "XML conversion is up to date.\n" | |
| 198 | 217 | processed.discard(withsect) |
| 199 | 218 | rebuild_xml = False |
| 219 | if batchmode and "DocBook" in analysis: | |
| 220 | output += "Made from DocBook masters.\n" | |
| 221 | processed.discard(withsect) | |
| 222 | return (7, False, output) | |
| 223 | if batchmode and "Doxygen" in analysis: | |
| 224 | output += "Made by Doxygen.\n" | |
| 225 | processed.discard(withsect) | |
| 226 | return (7, False, output) | |
| 200 | 227 | htmlloc = os.path.join(subdir, stem + ".html") |
| 201 | 228 | if rebuild_xml: |
| 202 | # Grab the actual manual page | |
| 203 | localcopy = os.path.join(outdir, withsect) | |
| 204 | (status, output) = fetch_page(file, localcopy, patch) | |
| 205 | if (status): | |
| 206 | return (status, False, output) | |
| 207 | 229 | # Note the the patch was used |
| 208 | 230 | processed.discard(withsect) |
| 209 | 231 | # Add any annotations |
| 210 | output += analyze_manpage(localcopy) | |
| 232 | output += analysis | |
| 211 | 233 | # Save the location of the page |
| 212 | 234 | loc = tmpstem + ".loc" |
| 213 | 235 | lfp = open(loc, "w") |
| 216 | 238 | # Move the source file into the output directory |
| 217 | 239 | os.rename(localcopy, source) |
| 218 | 240 | # Run the translator |
| 219 | (doclifter_status, lxmlloc, note) = make_xml(source, options, batchmode) | |
| 241 | (doclifter_status, lxmlloc, note) = make_xml(source, options) | |
| 220 | 242 | output += note |
| 221 | 243 | if doclifter_status not in (0, 2): |
| 222 | 244 | if not batchmode: |
| 307 | 329 | total = 0 |
| 308 | 330 | starttime = int(time.time()) |
| 309 | 331 | eligible = len(files) |
| 310 | doclifter_error_count = xmllint_error_count = total = 0 | |
| 332 | doclifter_error_count = xmllint_error_count = docbook_count = total = 0 | |
| 311 | 333 | def report(sig, frame, out=sys.stderr): |
| 312 | 334 | ftotal = float(total) |
| 313 | 335 | elapsed = int(time.time()) - starttime |
| 314 | out.write("\n%%%d of %d files in %s, %d OK, %d patched, %d doclifter errors, %d validation failures, %2.2f%% good.\n" % \ | |
| 336 | out.write("\n%%%d of %d files in %s, %d OK, %d preconverted, %d patched, %d doclifter errors, %d validation failures, %2.2f%% good.\n" % \ | |
| 315 | 337 | (total, eligible, report_elapsed(elapsed), |
| 316 | 338 | (total - doclifter_error_count - xmllint_error_count), |
| 339 | docbook_count, | |
| 317 | 340 | patched, |
| 318 | 341 | doclifter_error_count, |
| 319 | 342 | xmllint_error_count, |
| 320 | 343 | (ftotal-doclifter_error_count-xmllint_error_count-patched)*100.0/ftotal)) |
| 321 | 344 | def test(file, options): |
| 322 | before = time.time() | |
| 323 | (status, patched, output) = singlerun(file=file, options=options, batchmode=True) | |
| 324 | after = time.time() | |
| 325 | sys.stdout.write("! %s=%d%s (%2.2f)\n%s\n" % (file, status, " *"[patched], after-before, output)) | |
| 326 | return (status, output) | |
| 345 | before = time.time() | |
| 346 | (status, patched, output) = singlerun(file=file, options=options, batchmode=True) | |
| 347 | after = time.time() | |
| 348 | sys.stdout.write("! %s=%d%s (%2.2f)\n%s\n" % (file, status, " *"[patched], after-before, output)) | |
| 349 | return (status, output) | |
| 327 | 350 | signal.signal(signal.SIGUSR2, report) |
| 328 | 351 | signal.signal(signal.SIGHUP, bailout) |
| 329 | 352 | signal.signal(signal.SIGINT, bailout) |
| 336 | 359 | print "%Profiling not enabled.\n" |
| 337 | 360 | try: |
| 338 | 361 | for file in files: |
| 362 | if file in excluded_files: | |
| 363 | continue | |
| 339 | 364 | (status, output) = test(file=file, options=options) |
| 340 | 365 | if status == -1: |
| 341 | 366 | break |
| 345 | 370 | pass |
| 346 | 371 | elif status in (3, 5): # File I/O error or keyboard interrupt |
| 347 | 372 | pass |
| 348 | elif status == 6: | |
| 373 | elif status == 6: # Validation failure | |
| 349 | 374 | xmllint_error_count += 1 |
| 375 | elif status == 7: | |
| 376 | docbook_count += 1 | |
| 350 | 377 | total = total + 1 |
| 351 | 378 | except KeyboardInterrupt: |
| 352 | 379 | pass |
| 413 | 440 | ofp.write(htmltrailer) |
| 414 | 441 | |
| 415 | 442 | def statistics(): |
| 416 | counts = [0] * 7 | |
| 417 | 443 | legends = ( |
| 418 | 444 | "OK ", # No error |
| 419 | 445 | "???", # Unliftable (normal error status) |
| 421 | 447 | "I/O", # I/O failure, could not reach page |
| 422 | 448 | "!!!", # Internal error, doclifter blew up |
| 423 | 449 | "^C ", # Translation interrupted |
| 424 | "XML", # XML validation failure | |
| 450 | "XML", # XML validation failure | |
| 451 | "NOP", # Already in DocBook | |
| 425 | 452 | ) |
| 453 | counts = [0] * len(legends) | |
| 426 | 454 | |
| 427 | 455 | patchcount = re.compile("([0-9]+) patched") |
| 428 | totalcount = 0 | |
| 456 | warnings = 0 | |
| 457 | warn_latch = False | |
| 429 | 458 | while True: |
| 430 | 459 | line = sys.stdin.readline() |
| 431 | 460 | if not line: |
| 432 | 461 | break |
| 462 | elif not line.strip(): | |
| 463 | if warn_latch: | |
| 464 | warnings += 1 | |
| 465 | continue | |
| 433 | 466 | m = patchcount.search(line) |
| 434 | 467 | if m: |
| 435 | 468 | patched = int(m.group(1)) |
| 469 | if "warning -" in line: | |
| 470 | warn_latch = True | |
| 436 | 471 | if line[0] != '!': |
| 437 | 472 | continue |
| 473 | warn_latch = False | |
| 438 | 474 | line = line[2:] |
| 439 | 475 | rcolon = line.rindex("=") |
| 440 | 476 | file = line[:rcolon] |
| 449 | 485 | file = file[:-2] |
| 450 | 486 | file = os.path.basename(file) |
| 451 | 487 | counts[int(retval)] += 1 |
| 452 | totalcount += 1 | |
| 453 | 488 | |
| 454 | 489 | total = sum(counts) |
| 455 | 490 | for (i, count) in enumerate(counts): |
| 456 | 491 | print "%d = %s: %5d %2.2f%%" % (i, legends[i], count, (count * 1.0)*100/total) |
| 457 | print "Total: %d Errors: %d " % (totalcount, sum(counts)-counts[0]) | |
| 458 | print "Patched: %d (%2.2f%%)" % (patched, patched*100/float(totalcount)) | |
| 459 | print "With patches: %d (%2.2f%%)" % (counts[0], (counts[0])*100/float(totalcount)) | |
| 460 | print "Without patches: %d (%2.2f%%)" % (counts[0]-patched, (counts[0]-patched)*100/float(totalcount)) | |
| 492 | good = counts[0] | |
| 493 | bad = sum(counts[1:7]) | |
| 494 | print "Total: %d Errors: %d Warnings: %d" % (total, bad, warnings) | |
| 495 | print "Patched: %d (%2.2f%%)" % (patched, patched*100/float(total)) | |
| 496 | print "With patches: %d (%2.2f%%)" % (good, good*100/float(total)) | |
| 497 | print "Without patches: %d (%2.2f%%)" % (good-patched, (good-patched)*100/float(total)) | |
| 461 | 498 | |
| 462 | 499 | def errorclean(error_only, pattern): |
| 463 | 500 | if pattern: |
| 478 | 515 | while 1: |
| 479 | 516 | line = sys.stdin.readline() |
| 480 | 517 | trailer += line |
| 481 | if not line or line == '\n': | |
| 518 | if not line or not line.strip(): | |
| 482 | 519 | break |
| 483 | 520 | if pattern: |
| 484 | 521 | # Emit by pattern |
| 491 | 528 | continue |
| 492 | 529 | if status == 1 and (matches("page is empty") or matches("page has no text")): |
| 493 | 530 | continue |
| 494 | if status == 2: | |
| 531 | if status in (2, 7): | |
| 495 | 532 | continue |
| 496 | 533 | # Otherwise, emit |
| 497 | 534 | if error_only: |
| 547 | 584 | |
| 548 | 585 | def doclifter_driver(options, arguments): |
| 549 | 586 | "Lift old markup to new." |
| 550 | global mandir, makehtml, outdir, xslfragment, patchdir, makepatch | |
| 587 | global mandir, makehtml, outdir, xslfragment, patchdir, makepatch, excluded_files | |
| 551 | 588 | filelist = [] |
| 552 | 589 | sections = [] |
| 553 | 590 | callopts = "" |
| 591 | patchlift = False | |
| 554 | 592 | makehtml = False |
| 555 | 593 | errorfilter = False |
| 556 | 594 | quiet = False |
| 557 | 595 | fval = None |
| 558 | 596 | makepatch = False |
| 559 | 597 | profiling = False |
| 598 | excluded_files = [] | |
| 560 | 599 | for (switch, val) in options: |
| 561 | 600 | if (switch == '-d'): |
| 562 | 601 | callopts += " -d " + val |
| 570 | 609 | mandir = val |
| 571 | 610 | elif (switch == '-m'): # Make a patch from the last fetched page |
| 572 | 611 | makepatch = True |
| 612 | elif (switch == '-M'): # Make a patch with specified page | |
| 613 | patchlift = True | |
| 573 | 614 | elif (switch == '-p'): # Specify patch directory |
| 574 | 615 | patchdir = os.path.abspath(val) |
| 575 | 616 | elif (switch == '-P'): |
| 582 | 623 | elif (switch == '-S'): # Generate statistics from log on stdin |
| 583 | 624 | statistics() |
| 584 | 625 | sys.exit(0) |
| 626 | elif (switch == '-X'): | |
| 627 | excluded_files = open(val).read().split() | |
| 585 | 628 | if not sections: |
| 586 | 629 | sections = ["1", "2", "3", "4", "5", "6", "7", "8"] |
| 587 | 630 | if not outdir: |
| 609 | 652 | (status, patched, output) = singlerun(manpage, callopts, "foobar", batchmode=False) |
| 610 | 653 | print output |
| 611 | 654 | break |
| 655 | if patchlift: | |
| 656 | patchman() | |
| 612 | 657 | elif makepatch: |
| 613 | 658 | patchman() |
| 614 | 659 | elif errorfilter: |
| 646 | 691 | else: |
| 647 | 692 | sys.stderr.write("manlifter: can't find doclifter!\n") |
| 648 | 693 | sys.exit(1) |
| 649 | # Import it, so we can modify it while the test is running without | |
| 650 | # screwing up the results | |
| 651 | try: | |
| 652 | os.system("cp %s doclifter_test%s.py" % (where, os.getpid())) | |
| 653 | sys.path.append(".") | |
| 654 | exec 'import doclifter_test%s' % os.getpid() | |
| 655 | exec "doclifter=doclifter_test%s" % os.getpid() | |
| 656 | finally: | |
| 657 | os.system("rm -f doclifter_test%s.py*" % os.getpid()) | |
| 658 | 694 | # Gather options |
| 659 | (options, arguments) = getopt.getopt(sys.argv[1:], "d:ef:hI:mp:Pqs:Svw") | |
| 695 | (options, arguments) = getopt.getopt(sys.argv[1:], "d:ef:hI:mMp:Pqs:SvwX:") | |
| 660 | 696 | # Do the real work |
| 661 | 697 | if "-P" in sys.argv: |
| 662 | 698 | prof = hotshot.Profile("manlifter.prof") |
| 0 | 0 | '\" t |
| 1 | 1 | .\" Title: manlifter |
| 2 | 2 | .\" Author: [see the "Author" section] |
| 3 | .\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/> | |
| 4 | .\" Date: 11/25/2010 | |
| 3 | .\" Generator: DocBook XSL Stylesheets v1.76.1 <http://docbook.sf.net/> | |
| 4 | .\" Date: 06/01/2013 | |
| 5 | 5 | .\" Manual: Documentation Tools |
| 6 | 6 | .\" Source: manlifter |
| 7 | 7 | .\" Language: English |
| 8 | 8 | .\" |
| 9 | .TH "MANLIFTER" "1" "11/25/2010" "manlifter" "Documentation Tools" | |
| 9 | .TH "MANLIFTER" "1" "06/01/2013" "manlifter" "Documentation Tools" | |
| 10 | 10 | .\" ----------------------------------------------------------------- |
| 11 | 11 | .\" * Define some portability stuff |
| 12 | 12 | .\" ----------------------------------------------------------------- |
| 30 | 30 | manlifter \- mass\-conversion script and test harness for doclifter |
| 31 | 31 | .SH "SYNOPSIS" |
| 32 | 32 | .HP \w'\fBmanlifter\fR\ 'u |
| 33 | \fBmanlifter\fR [\-d\ \fIoption\fR] [\-e] [\-f\ \fIlistfile\fR] [\-h] [\-I\ \fImandir\fR] [\-m] [\-o\ \fIoutdir\fR] [\-p\ \fIpatch\-directory\fR] [\-P] [\-q] [\-v] [\-s\ \fIsection\fR] \fIname\fR... | |
| 33 | \fBmanlifter\fR [\-d\ \fIoption\fR] [\-e] [\-f\ \fIlistfile\fR] [\-h] [\-I\ \fImandir\fR] [\-m] [\-M] [\-o\ \fIoutdir\fR] [\-p\ \fIpatch\-directory\fR] [\-P] [\-q] [\-v] [\-s\ \fIsection\fR] [\-X\ \fIexclude\fR] \fIname\fR... | |
| 34 | 34 | .HP \w'\fBmanlifter\fR\ 'u |
| 35 | 35 | \fBmanlifter\fR [\-S] |
| 36 | 36 | .SH "DESCRIPTION" |
| 40 | 40 | \fBdoclifter\fR(1) |
| 41 | 41 | to convert an entire manual\-page tree to XML\-Docbook, optionally also generating HTML from the XML\&. Another use is as a torture\-test tool for doclifter; it logs errors to standard output and collects timings\&. |
| 42 | 42 | .PP |
| 43 | Called without any file arguments, manlifter tries to convert all man pages installed on the system, placing the resulting xml files under | |
| 43 | Called without any file arguments, manlifter tries to convert all eligible man pages installed on the system, placing the resulting xml files under | |
| 44 | 44 | xmlman |
| 45 | 45 | in the current directory\&. Each successfully translated page foo\&.N is copied to manN/foo\&.xml beneath the output directory, regardless of what source directory it came from\&. |
| 46 | .PP | |
| 47 | A manual page is considered ineligible for batch conversion if it contains text indicating it has been generated from DocBook masters of from Doxygen\&. | |
| 46 | 48 | .PP |
| 47 | 49 | For each source file examined, if the destination file exists and is newer than the source, the conversion is skipped; thus, incremental runs of |
| 48 | 50 | \fBmanlifter\fR |
| 103 | 105 | .PP |
| 104 | 106 | \-m |
| 105 | 107 | .RS 4 |
| 106 | Make a patch to correct the last page fetched\&. It is copied, an editor is called on the copy (using tghe environment variable | |
| 108 | Make a patch to correct the last page fetched\&. It is copied, an editor is called on the copy (using the environment variable | |
| 107 | 109 | \fB$EDITOR\fR), and then |
| 108 | 110 | \fBdiff\fR(1) |
| 109 | 111 | is called to drop the patch in the prepatch directory\&. Fails with an error if such a patch is already present\&. |
| 112 | .RE | |
| 113 | .PP | |
| 114 | \-M | |
| 115 | .RS 4 | |
| 116 | Lift the specified files, then do the equivalent of the \-m option\&. | |
| 110 | 117 | .RE |
| 111 | 118 | .PP |
| 112 | 119 | \-o |
| 157 | 164 | developers\&. |
| 158 | 165 | .RE |
| 159 | 166 | .PP |
| 167 | \-X | |
| 168 | .RS 4 | |
| 169 | In batch mode exclude pages listed in the argument file\&. Meant to be used for pages that are known good and take an extremely long time to lift, in order to cut down the time for a test run\&. (Most pages lift in less than a half second, but a few can take 15 minutes or longer\&.) | |
| 170 | .RE | |
| 171 | .PP | |
| 160 | 172 | \fBmanlifter\fR |
| 161 | 173 | emits a logfile to standard output\&. The file begins with a timestamp line and a blank line, and ends with a line giving run time and various interesting statistics\&. Between these are stanzas, separated by blank lines, one for each file on which |
| 162 | 174 | \fBdoclifter\fR |
| 23 | 23 | <arg choice='opt'>-h</arg> |
| 24 | 24 | <arg choice='opt'>-I <replaceable>mandir</replaceable></arg> |
| 25 | 25 | <arg choice='opt'>-m</arg> |
| 26 | <arg choice='opt'>-M</arg> | |
| 26 | 27 | <arg choice='opt'>-o <replaceable>outdir</replaceable></arg> |
| 27 | 28 | <arg choice='opt'>-p <replaceable>patch-directory</replaceable></arg> |
| 28 | 29 | <arg choice='opt'>-P</arg> |
| 29 | 30 | <arg choice='opt'>-q</arg> |
| 30 | 31 | <arg choice='opt'>-v</arg> |
| 31 | 32 | <arg choice='opt'>-s <replaceable>section</replaceable></arg> |
| 33 | <arg choice='opt'>-X <replaceable>exclude</replaceable></arg> | |
| 32 | 34 | <arg choice='plain' rep='repeat'><replaceable>name</replaceable></arg> |
| 33 | 35 | </cmdsynopsis> |
| 34 | 36 | <cmdsynopsis> |
| 46 | 48 | timings.</para> |
| 47 | 49 | |
| 48 | 50 | <para>Called without any file arguments, manlifter tries to convert |
| 49 | all man pages installed on the system, placing the resulting xml files | |
| 51 | all eligible man pages installed on the system, placing the resulting xml files | |
| 50 | 52 | under <filename>xmlman</filename> in the current directory. Each |
| 51 | 53 | successfully translated page foo.N is copied to manN/foo.xml beneath |
| 52 | 54 | the output directory, regardless of what source directory it came |
| 53 | 55 | from. |
| 54 | 56 | </para> |
| 57 | ||
| 58 | <para>A manual page is considered ineligible for batch conversion if | |
| 59 | it contains text indicating it has been generated from DocBook masters | |
| 60 | of from Doxygen.</para> | |
| 55 | 61 | |
| 56 | 62 | <para>For each source file examined, if the destination file exists |
| 57 | 63 | and is newer than the source, the conversion is skipped; thus, |
| 117 | 123 | <varlistentry> |
| 118 | 124 | <term>-m</term> |
| 119 | 125 | <listitem><para>Make a patch to correct the last page fetched. It is |
| 120 | copied, an editor is called on the copy (using tghe environment | |
| 126 | copied, an editor is called on the copy (using the environment | |
| 121 | 127 | variable <envar>$EDITOR</envar>), and then |
| 122 | 128 | <citerefentry><refentrytitle>diff</refentrytitle><manvolnum>1</manvolnum></citerefentry> |
| 123 | 129 | is called to drop the patch in the prepatch directory. Fails with an |
| 124 | 130 | error if such a patch is already present.</para></listitem> |
| 131 | </varlistentry> | |
| 132 | <varlistentry> | |
| 133 | <term>-M</term> | |
| 134 | <listitem><para>Lift the specified files, then do the equivalent of | |
| 135 | the -m option.</para></listitem> | |
| 125 | 136 | </varlistentry> |
| 126 | 137 | <varlistentry> |
| 127 | 138 | <term>-o</term> |
| 172 | 183 | This option will be of interest mainly to <command>doclifter</command> |
| 173 | 184 | developers.</para></listitem> |
| 174 | 185 | </varlistentry> |
| 186 | <varlistentry> | |
| 187 | <term>-X</term> | |
| 188 | <listitem><para>In batch mode exclude pages listed in the argument file. | |
| 189 | Meant to be used for pages that are known good and take an extremely | |
| 190 | long time to lift, in order to cut down the time for a test run. (Most | |
| 191 | pages lift in less than a half second, but a few can take 15 minutes | |
| 192 | or longer.) | |
| 193 | </para></listitem> | |
| 194 | </varlistentry> | |
| 175 | 195 | </variablelist> |
| 176 | 196 | |
| 177 | 197 | <para><command>manlifter</command> emits a logfile to standard |
| 0 | .\" Test for various troff features | |
| 1 | .\" Test translation | |
| 2 | .tr $\(bu | |
| 3 | We should see a bullet literal $ here. | |
| 4 | .ds XX frozzle | |
| 5 | This is a \*(XX string expansion example. | |
| 6 | .\" Simple macro definition, no macro calls inside it | |
| 7 | .de YY | |
| 8 | Macro expansion text with argument \$1 | |
| 9 | .. | |
| 10 | .\" Here's the test invocation | |
| 11 | .YY foo | |
| 12 | .\" Let's be sure we keep getting lines after macroexpansion | |
| 13 | .de AA | |
| 14 | Before subcall | |
| 15 | .YY bar | |
| 16 | After subcall: \$1 | |
| 17 | .. | |
| 18 | .\" next line tests .so | |
| 19 | .so testinclude | |
| 20 | .\" OK, here's the two-level macroexpansion | |
| 21 | .AA baz | |
| 22 | .\" Test conditionals | |
| 23 | .de CO1 | |
| 24 | .if n | |
| 25 | 1: You should see this | |
| 26 | .\} | |
| 27 | .. | |
| 28 | .CO1 | |
| 29 | .de CO2 | |
| 30 | .ie n \{ | |
| 31 | 2: You should see this | |
| 32 | .\} | |
| 33 | .el\{ | |
| 34 | 2: You should not see this | |
| 35 | .\} | |
| 36 | .. | |
| 37 | .CO2 | |
| 38 | .pm | |
| 39 | .ie n 3: You should see this | |
| 40 | .el 3: You should not see this | |
| 41 | .\" Something is funky with the else handling | |
| 42 | .if n TRUE | |
| 43 | .el FALSE | |
| 44 | \" Test HTMLization | |
| 45 | .br <foo> | |
| 46 | Hi there | |
| 47 | .de Sh | |
| 48 | dummy | |
| 49 | .. | |
| 50 | .\" Do we blow our stack? | |
| 51 | .if n .Sh """Considerations""" | |
| 52 | .el .Sh "``Considerations''" | |
| 53 | .\" Example test | |
| 54 | .ft CW | |
| 55 | .in +4 | |
| 56 | .nf | |
| 57 | This is an example | |
| 58 | .ft | |
| 59 | .in -4 | |
| 60 | .fi | |
| 61 | foo\ bar | |
| 62 | .br | |
| 63 | This line tests recognition of \v'-.4m'\fIsuperscripting\*(ic\fR\v'.4m') | |
| 64 | This line tests recognition of the \uother\d superscript idiom. | |
| 65 | Before ignore | |
| 66 | .ig | |
| 67 | This line is ignored | |
| 68 | .. | |
| 69 | After ignore | |
| 70 | # End. |
| 0 | # Regression tests for doclifter | |
| 1 | ||
| 2 | TESTLOADS := $(shell ls *.man | sed '/.man/s///') | |
| 3 | ||
| 4 | test: regress | |
| 5 | @echo "No output (other than a testfile stem name) is good news." | |
| 6 | ||
| 7 | rebuild: | |
| 8 | @for file in $(TESTLOADS); do \ | |
| 9 | echo "Remaking $${file}.chk"; \ | |
| 10 | ../doclifter <$${file}.man >$${file}.chk 2>&1; \ | |
| 11 | done | |
| 12 | regress: | |
| 13 | @for file in $(TESTLOADS); do \ | |
| 14 | echo $${file}; \ | |
| 15 | if ../doclifter <$${file}.man >/tmp/regress$$; \ | |
| 16 | then diff -u $${file}.chk /tmp/regress$$; \ | |
| 17 | else echo "*** Nonzero return status on $${file}!"; exit 1; fi \ | |
| 18 | done | |
| 19 | @rm -f /tmp/regress |
| 0 | What the various test loads are for: | |
| 1 | ||
| 2 | basic.troff | |
| 3 | Test translation of some low-level troff idioms. | |
| 4 | ||
| 5 | capabilities.man: | |
| 6 | Tests lists nested within .RS. | |
| 7 | ||
| 8 | console_ioctl.man | |
| 9 | Tests table and display processing. | |
| 10 | ||
| 11 | corosync.conf.man | |
| 12 | Tests recognition of a bare filename in the Synopsis section | |
| 13 | ||
| 14 | docliftertest1.man | |
| 15 | General test for many features, including section and paragraph | |
| 16 | recognition and highlight mapping. | |
| 17 | ||
| 18 | grap.man | |
| 19 | Tests lists nested within .Bd/.Ed. | |
| 20 | ||
| 21 | groff_char.man: | |
| 22 | Tests recognition of every special chracter groff knows about. | |
| 23 | ||
| 24 | pax.man | |
| 25 | Test the kluge to avoid excess font closes in table entries. | |
| 26 | ||
| 27 | stringwidth.man | |
| 28 | Test a common evaluation case of the \w macro. | |
| 29 | ||
| 30 | xoxc.man | |
| 31 | Tests translation of .Xo/.Xc construct in BSD macros. | |
| 32 | ||
| 33 | sudoers.man: | |
| 34 | Tests the filename case in .Bl -literal. |
| 0 | .\" Test for various troff features | |
| 1 | .\" Test translation | |
| 2 | .tr $\(bu | |
| 3 | We should see a bullet literal $ here. | |
| 4 | .ds XX frozzle | |
| 5 | This is a \*(XX string expansion example. | |
| 6 | .\" Simple macro definition, no macro calls inside it | |
| 7 | .de YY | |
| 8 | Macro expansion text with argument \$1 | |
| 9 | .. | |
| 10 | .\" Here's the test invocation | |
| 11 | .YY foo | |
| 12 | .\" Let's be sure we keep getting lines after macroexpansion | |
| 13 | .de AA | |
| 14 | Before subcall | |
| 15 | .YY bar | |
| 16 | After subcall: \$1 | |
| 17 | .. | |
| 18 | .\" next line tests .so | |
| 19 | .so testinclude | |
| 20 | .\" OK, here's the two-level macroexpansion | |
| 21 | .AA baz | |
| 22 | .\" Test conditionals | |
| 23 | .de CO1 | |
| 24 | .if n | |
| 25 | 1: You should see this | |
| 26 | .\} | |
| 27 | .. | |
| 28 | .CO1 | |
| 29 | .de CO2 | |
| 30 | .ie n \{ | |
| 31 | 2: You should see this | |
| 32 | .\} | |
| 33 | .el\{ | |
| 34 | 2: You should not see this | |
| 35 | .\} | |
| 36 | .. | |
| 37 | .CO2 | |
| 38 | .pm | |
| 39 | .ie n 3: You should see this | |
| 40 | .el 3: You should not see this | |
| 41 | .\" Something is funky with the else handling | |
| 42 | .if n TRUE | |
| 43 | .el FALSE | |
| 44 | \" Test HTMLization | |
| 45 | .br <foo> | |
| 46 | Hi there | |
| 47 | .de Sh | |
| 48 | dummy | |
| 49 | .. | |
| 50 | .\" Do we blow our stack? | |
| 51 | .if n .Sh """Considerations""" | |
| 52 | .el .Sh "``Considerations''" | |
| 53 | .\" Example test | |
| 54 | .ft CW | |
| 55 | .in +4 | |
| 56 | .nf | |
| 57 | This is an example | |
| 58 | .ft | |
| 59 | .in -4 | |
| 60 | .fi | |
| 61 | foo\ bar | |
| 62 | .br | |
| 63 | This line tests recognition of \v'-.4m'\fIsuperscripting\*(ic\fR\v'.4m') | |
| 64 | This line tests recognition of the \uother\d superscript idiom. | |
| 65 | Before ignore | |
| 66 | .ig | |
| 67 | This line is ignored | |
| 68 | .. | |
| 69 | After ignore | |
| 70 | # End. |
| 0 | <?xml version="1.0" encoding="ISO-8859-1"?> | |
| 1 | <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" | |
| 2 | "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"> | |
| 3 | <!-- lifted from man+troff by doclifter --> | |
| 4 | <refentry> | |
| 5 | <!-- Copyright (c) 2002 by Michael Kerrisk <mtk.manpages@gmail.com> --> | |
| 6 | ||
| 7 | <!-- Permission is granted to make and distribute verbatim copies of this | |
| 8 | manual provided the copyright notice and this permission notice are | |
| 9 | preserved on all copies. --> | |
| 10 | ||
| 11 | <!-- Permission is granted to copy and distribute modified versions of this | |
| 12 | manual under the conditions for verbatim copying, provided that the | |
| 13 | entire resulting derived work is distributed under the terms of a | |
| 14 | permission notice identical to this one. --> | |
| 15 | ||
| 16 | <!-- Since the Linux kernel and libraries are constantly changing, this | |
| 17 | manual page may be incorrect or out\-of\-date. The author(s) assume no | |
| 18 | responsibility for errors or omissions, or for damages resulting from | |
| 19 | the use of the information contained herein. The author(s) may not | |
| 20 | have taken the same level of care in the production of this manual, | |
| 21 | which is licensed free of charge, as they might when working | |
| 22 | professionally. --> | |
| 23 | ||
| 24 | <!-- Formatted or processed versions of this manual, if unaccompanied by | |
| 25 | the source, must acknowledge the copyright and authors of this work. --> | |
| 26 | ||
| 27 | <!-- 6 Aug 2002 \- Initial Creation | |
| 28 | Modified 2003\-05\-23, Michael Kerrisk, <mtk.manpages@gmail.com> | |
| 29 | Modified 2004\-05\-27, Michael Kerrisk, <mtk.manpages@gmail.com> | |
| 30 | 2004\-12\-08, mtk Added O_NOATIME for CAP_FOWNER | |
| 31 | 2005\-08\-16, mtk, Added CAP_AUDIT_CONTROL and CAP_AUDIT_WRITE | |
| 32 | 2008\-07\-15, Serge Hallyn <serue@us.bbm.com> | |
| 33 | Document file capabilities, per\-process capability | |
| 34 | bounding set, changed semantics for CAP_SETPCAP, | |
| 35 | and other changes in 2.6.2[45]. | |
| 36 | Add CAP_MAC_ADMIN, CAP_MAC_OVERRIDE, CAP_SETFCAP. | |
| 37 | 2008\-07\-15, mtk | |
| 38 | Add text describing circumstances in which CAP_SETPCAP | |
| 39 | (theoretically) permits a thread to change the | |
| 40 | capability sets of another thread. | |
| 41 | Add section describing rules for programmatically | |
| 42 | adjusting thread capability sets. | |
| 43 | Describe rationale for capability bounding set. | |
| 44 | Document "securebits" flags. | |
| 45 | Add text noting that if we set the effective flag for one file | |
| 46 | capability, then we must also set the effective flag for all | |
| 47 | other capabilities where the permitted or inheritable bit is set. | |
| 48 | 2011\-09\-07, mtk/Serge hallyn: Add CAP_SYSLOG | |
| 49 | FIXME: Linux 3.0 added CAP_WAKE_ALARM --> | |
| 50 | ||
| 51 | <refentryinfo><date>2011-10-04</date></refentryinfo> | |
| 52 | <refmeta> | |
| 53 | <refentrytitle>CAPABILITIES</refentrytitle> | |
| 54 | <manvolnum>7</manvolnum> | |
| 55 | <refmiscinfo class='date'>2011-10-04</refmiscinfo> | |
| 56 | <refmiscinfo class='source'>Linux</refmiscinfo> | |
| 57 | <refmiscinfo class='manual'>Linux Programmer's Manual</refmiscinfo> | |
| 58 | </refmeta> | |
| 59 | <refnamediv> | |
| 60 | <refname>capabilities</refname> | |
| 61 | <refpurpose>overview of Linux capabilities</refpurpose> | |
| 62 | </refnamediv> | |
| 63 | <!-- body begins here --> | |
| 64 | ||
| 65 | <refsect1 id='description'><title>DESCRIPTION</title> | |
| 66 | <para>For the purpose of performing permission checks, | |
| 67 | traditional UNIX implementations distinguish two categories of processes: | |
| 68 | <emphasis remap='I'>privileged</emphasis> | |
| 69 | processes (whose effective user ID is 0, referred to as superuser or root), | |
| 70 | and | |
| 71 | <emphasis remap='I'>unprivileged</emphasis> | |
| 72 | processes (whose effective UID is nonzero). | |
| 73 | Privileged processes bypass all kernel permission checks, | |
| 74 | while unprivileged processes are subject to full permission | |
| 75 | checking based on the process's credentials | |
| 76 | (usually: effective UID, effective GID, and supplementary group list).</para> | |
| 77 | ||
| 78 | <para>Starting with kernel 2.2, Linux divides the privileges traditionally | |
| 79 | associated with superuser into distinct units, known as | |
| 80 | <emphasis remap='I'>capabilities</emphasis>, | |
| 81 | which can be independently enabled and disabled. | |
| 82 | Capabilities are a per-thread attribute.</para> | |
| 83 | ||
| 84 | ||
| 85 | <refsect2 id='capabilities_list'><title>Capabilities List</title> | |
| 86 | <para>The following list shows the capabilities implemented on Linux, | |
| 87 | and the operations or behaviors that each capability permits:</para> | |
| 88 | <variablelist remap='TP'> | |
| 89 | <varlistentry> | |
| 90 | <term><emphasis remap='B'>CAP_AUDIT_CONTROL</emphasis> (since Linux 2.6.11)</term> | |
| 91 | <listitem> | |
| 92 | <para>Enable and disable kernel auditing; change auditing filter rules; | |
| 93 | retrieve auditing status and filtering rules.</para> | |
| 94 | </listitem> | |
| 95 | </varlistentry> | |
| 96 | <varlistentry> | |
| 97 | <term><emphasis remap='B'>CAP_AUDIT_WRITE</emphasis> (since Linux 2.6.11)</term> | |
| 98 | <listitem> | |
| 99 | <para>Write records to kernel auditing log.</para> | |
| 100 | </listitem> | |
| 101 | </varlistentry> | |
| 102 | <varlistentry> | |
| 103 | <term><emphasis remap='B'>CAP_CHOWN</emphasis></term> | |
| 104 | <listitem> | |
| 105 | <para>Make arbitrary changes to file UIDs and GIDs (see | |
| 106 | <citerefentry><refentrytitle>chown</refentrytitle><manvolnum>2</manvolnum></citerefentry>).</para> | |
| 107 | </listitem> | |
| 108 | </varlistentry> | |
| 109 | <varlistentry> | |
| 110 | <term><emphasis remap='B'>CAP_DAC_OVERRIDE</emphasis></term> | |
| 111 | <listitem> | |
| 112 | <para>Bypass file read, write, and execute permission checks. | |
| 113 | (DAC is an abbreviation of "discretionary access control".)</para> | |
| 114 | </listitem> | |
| 115 | </varlistentry> | |
| 116 | <varlistentry> | |
| 117 | <term><emphasis remap='B'>CAP_DAC_READ_SEARCH</emphasis></term> | |
| 118 | <listitem> | |
| 119 | <para>Bypass file read permission checks and | |
| 120 | directory read and execute permission checks.</para> | |
| 121 | </listitem> | |
| 122 | </varlistentry> | |
| 123 | <varlistentry> | |
| 124 | <term><emphasis remap='B'>CAP_FOWNER</emphasis></term> | |
| 125 | <listitem> | |
| 126 | <!-- PD 0 --> | |
| 127 | <itemizedlist remap='IP+bullet'> | |
| 128 | <listitem override='bullet'> | |
| 129 | <para>Bypass permission checks on operations that normally | |
| 130 | require the file system UID of the process to match the UID of | |
| 131 | the file (e.g., | |
| 132 | <citerefentry><refentrytitle>chmod</refentrytitle><manvolnum>2</manvolnum></citerefentry>, | |
| 133 | <citerefentry><refentrytitle>utime</refentrytitle><manvolnum>2</manvolnum></citerefentry>), | |
| 134 | excluding those operations covered by | |
| 135 | <emphasis remap='B'>CAP_DAC_OVERRIDE</emphasis> | |
| 136 | and | |
| 137 | <emphasis remap='B'>CAP_DAC_READ_SEARCH</emphasis>;</para> | |
| 138 | </listitem> | |
| 139 | <listitem override='bullet'> | |
| 140 | <para>set extended file attributes (see | |
| 141 | <citerefentry><refentrytitle>chattr</refentrytitle><manvolnum>1</manvolnum></citerefentry>) | |
| 142 | on arbitrary files;</para> | |
| 143 | </listitem> | |
| 144 | <listitem override='bullet'> | |
| 145 | <para>set Access Control Lists (ACLs) on arbitrary files;</para> | |
| 146 | </listitem> | |
| 147 | <listitem override='bullet'> | |
| 148 | <para>ignore directory sticky bit on file deletion;</para> | |
| 149 | </listitem> | |
| 150 | <listitem override='bullet'> | |
| 151 | <para>specify | |
| 152 | <emphasis remap='B'>O_NOATIME</emphasis> | |
| 153 | for arbitrary files in | |
| 154 | <citerefentry><refentrytitle>open</refentrytitle><manvolnum>2</manvolnum></citerefentry> | |
| 155 | and | |
| 156 | <citerefentry><refentrytitle>fcntl</refentrytitle><manvolnum>2</manvolnum></citerefentry>.</para> | |
| 157 | </listitem> | |
| 158 | </itemizedlist> | |
| 159 | <!-- PD --> | |
| 160 | </listitem> | |
| 161 | </varlistentry> | |
| 162 | <varlistentry> | |
| 163 | <term><emphasis remap='B'>CAP_FSETID</emphasis></term> | |
| 164 | <listitem> | |
| 165 | <para>Don't clear set-user-ID and set-group-ID permission | |
| 166 | bits when a file is modified; | |
| 167 | set the set-group-ID bit for a file whose GID does not match | |
| 168 | the file system or any of the supplementary GIDs of the calling process.</para> | |
| 169 | </listitem> | |
| 170 | </varlistentry> | |
| 171 | <varlistentry> | |
| 172 | <term><emphasis remap='B'>CAP_IPC_LOCK</emphasis></term> | |
| 173 | <listitem> | |
| 174 | <para>Lock memory | |
| 175 | (<citerefentry><refentrytitle>mlock</refentrytitle><manvolnum>2</manvolnum></citerefentry>, | |
| 176 | <citerefentry><refentrytitle>mlockall</refentrytitle><manvolnum>2</manvolnum></citerefentry>, | |
| 177 | <citerefentry><refentrytitle>mmap</refentrytitle><manvolnum>2</manvolnum></citerefentry>, | |
| 178 | <citerefentry><refentrytitle>shmctl</refentrytitle><manvolnum>2</manvolnum></citerefentry>).</para> | |
| 179 | </listitem> | |
| 180 | </varlistentry> | |
| 181 | <varlistentry> | |
| 182 | <term><emphasis remap='B'>CAP_IPC_OWNER</emphasis></term> | |
| 183 | <listitem> | |
| 184 | <para>Bypass permission checks for operations on System V IPC objects.</para> | |
| 185 | </listitem> | |
| 186 | </varlistentry> | |
| 187 | <varlistentry> | |
| 188 | <term><emphasis remap='B'>CAP_KILL</emphasis></term> | |
| 189 | <listitem> | |
| 190 | <para>Bypass permission checks for sending signals (see | |
| 191 | <citerefentry><refentrytitle>kill</refentrytitle><manvolnum>2</manvolnum></citerefentry>). | |
| 192 | This includes use of the | |
| 193 | <citerefentry><refentrytitle>ioctl</refentrytitle><manvolnum>2</manvolnum></citerefentry> | |
| 194 | <emphasis remap='B'>KDSIGACCEPT</emphasis> | |
| 195 | operation.</para> | |
| 196 | <!-- FIXME CAP_KILL also has an effect for threads + setting child | |
| 197 | termination signal to other than SIGCHLD: without this | |
| 198 | capability, the termination signal reverts to SIGCHLD | |
| 199 | if the child does an exec(). What is the rationale | |
| 200 | for this? --> | |
| 201 | </listitem> | |
| 202 | </varlistentry> | |
| 203 | <varlistentry> | |
| 204 | <term><emphasis remap='B'>CAP_LEASE</emphasis> (since Linux 2.4)</term> | |
| 205 | <listitem> | |
| 206 | <para>Establish leases on arbitrary files (see | |
| 207 | <citerefentry><refentrytitle>fcntl</refentrytitle><manvolnum>2</manvolnum></citerefentry>).</para> | |
| 208 | </listitem> | |
| 209 | </varlistentry> | |
| 210 | <varlistentry> | |
| 211 | <term><emphasis remap='B'>CAP_LINUX_IMMUTABLE</emphasis></term> | |
| 212 | <listitem> | |
| 213 | <para>Set the | |
| 214 | <emphasis remap='B'>FS_APPEND_FL</emphasis> | |
| 215 | and | |
| 216 | <emphasis remap='B'>FS_IMMUTABLE_FL</emphasis> | |
| 217 | <!-- These attributes are now available on ext2, ext3, Reiserfs, XFS, JFS --> | |
| 218 | i-node flags (see | |
| 219 | <citerefentry><refentrytitle>chattr</refentrytitle><manvolnum>1</manvolnum></citerefentry>).</para> | |
| 220 | </listitem> | |
| 221 | </varlistentry> | |
| 222 | <varlistentry> | |
| 223 | <term><emphasis remap='B'>CAP_MAC_ADMIN</emphasis> (since Linux 2.6.25)</term> | |
| 224 | <listitem> | |
| 225 | <para>Override Mandatory Access Control (MAC). | |
| 226 | Implemented for the Smack Linux Security Module (LSM).</para> | |
| 227 | </listitem> | |
| 228 | </varlistentry> | |
| 229 | <varlistentry> | |
| 230 | <term><emphasis remap='B'>CAP_MAC_OVERRIDE</emphasis> (since Linux 2.6.25)</term> | |
| 231 | <listitem> | |
| 232 | <para>Allow MAC configuration or state changes. | |
| 233 | Implemented for the Smack LSM.</para> | |
| 234 | </listitem> | |
| 235 | </varlistentry> | |
| 236 | <varlistentry> | |
| 237 | <term><emphasis remap='B'>CAP_MKNOD</emphasis> (since Linux 2.4)</term> | |
| 238 | <listitem> | |
| 239 | <para>Create special files using | |
| 240 | <citerefentry><refentrytitle>mknod</refentrytitle><manvolnum>2</manvolnum></citerefentry>.</para> | |
| 241 | </listitem> | |
| 242 | </varlistentry> | |
| 243 | <varlistentry> | |
| 244 | <term><emphasis remap='B'>CAP_NET_ADMIN</emphasis></term> | |
| 245 | <listitem> | |
| 246 | <para>Perform various network-related operations | |
| 247 | (e.g., setting privileged socket options, | |
| 248 | enabling multicasting, interface configuration, | |
| 249 | modifying routing tables).</para> | |
| 250 | </listitem> | |
| 251 | </varlistentry> | |
| 252 | <varlistentry> | |
| 253 | <term><emphasis remap='B'>CAP_NET_BIND_SERVICE</emphasis></term> | |
| 254 | <listitem> | |
| 255 | <para>Bind a socket to Internet domain privileged ports | |
| 256 | (port numbers less than 1024).</para> | |
| 257 | </listitem> | |
| 258 | </varlistentry> | |
| 259 | <varlistentry> | |
| 260 | <term><emphasis remap='B'>CAP_NET_BROADCAST</emphasis></term> | |
| 261 | <listitem> | |
| 262 | <para>(Unused) Make socket broadcasts, and listen to multicasts.</para> | |
| 263 | </listitem> | |
| 264 | </varlistentry> | |
| 265 | <varlistentry> | |
| 266 | <term><emphasis remap='B'>CAP_NET_RAW</emphasis></term> | |
| 267 | <listitem> | |
| 268 | <para>Use RAW and PACKET sockets.</para> | |
| 269 | <!-- Also various IP options and setsockopt(SO_BINDTODEVICE) --> | |
| 270 | </listitem> | |
| 271 | </varlistentry> | |
| 272 | <varlistentry> | |
| 273 | <term><emphasis remap='B'>CAP_SETGID</emphasis></term> | |
| 274 | <listitem> | |
| 275 | <para>Make arbitrary manipulations of process GIDs and supplementary GID list; | |
| 276 | forge GID when passing socket credentials via UNIX domain sockets.</para> | |
| 277 | </listitem> | |
| 278 | </varlistentry> | |
| 279 | <varlistentry> | |
| 280 | <term><emphasis remap='B'>CAP_SETFCAP</emphasis> (since Linux 2.6.24)</term> | |
| 281 | <listitem> | |
| 282 | <para>Set file capabilities.</para> | |
| 283 | </listitem> | |
| 284 | </varlistentry> | |
| 285 | <varlistentry> | |
| 286 | <term><emphasis remap='B'>CAP_SETPCAP</emphasis></term> | |
| 287 | <listitem> | |
| 288 | <para>If file capabilities are not supported: | |
| 289 | grant or remove any capability in the | |
| 290 | caller's permitted capability set to or from any other process. | |
| 291 | (This property of | |
| 292 | <emphasis remap='B'>CAP_SETPCAP</emphasis> | |
| 293 | is not available when the kernel is configured to support | |
| 294 | file capabilities, since | |
| 295 | <emphasis remap='B'>CAP_SETPCAP</emphasis> | |
| 296 | has entirely different semantics for such kernels.)</para> | |
| 297 | ||
| 298 | <para>If file capabilities are supported: | |
| 299 | add any capability from the calling thread's bounding set | |
| 300 | to its inheritable set; | |
| 301 | drop capabilities from the bounding set (via | |
| 302 | <citerefentry><refentrytitle>prctl</refentrytitle><manvolnum>2</manvolnum></citerefentry> | |
| 303 | <emphasis remap='B'>PR_CAPBSET_DROP</emphasis>); | |
| 304 | make changes to the | |
| 305 | <emphasis remap='I'>securebits</emphasis> | |
| 306 | flags.</para> | |
| 307 | </listitem> | |
| 308 | </varlistentry> | |
| 309 | <varlistentry> | |
| 310 | <term><emphasis remap='B'>CAP_SETUID</emphasis></term> | |
| 311 | <listitem> | |
| 312 | <para>Make arbitrary manipulations of process UIDs | |
| 313 | (<citerefentry><refentrytitle>setuid</refentrytitle><manvolnum>2</manvolnum></citerefentry>, | |
| 314 | <citerefentry><refentrytitle>setreuid</refentrytitle><manvolnum>2</manvolnum></citerefentry>, | |
| 315 | <citerefentry><refentrytitle>setresuid</refentrytitle><manvolnum>2</manvolnum></citerefentry>, | |
| 316 | <citerefentry><refentrytitle>setfsuid</refentrytitle><manvolnum>2</manvolnum></citerefentry>); | |
| 317 | make forged UID when passing socket credentials via UNIX domain sockets.</para> | |
| 318 | <!-- FIXME CAP_SETUID also an effect in exec(); document this. --> | |
| 319 | </listitem> | |
| 320 | </varlistentry> | |
| 321 | <varlistentry> | |
| 322 | <term><emphasis remap='B'>CAP_SYS_ADMIN</emphasis></term> | |
| 323 | <listitem> | |
| 324 | <!-- PD 0 --> | |
| 325 | <itemizedlist remap='IP+bullet'> | |
| 326 | <listitem override='bullet'> | |
| 327 | <para>Perform a range of system administration operations including: | |
| 328 | <citerefentry><refentrytitle>quotactl</refentrytitle><manvolnum>2</manvolnum></citerefentry>, | |
| 329 | <citerefentry><refentrytitle>mount</refentrytitle><manvolnum>2</manvolnum></citerefentry>, | |
| 330 | <citerefentry><refentrytitle>umount</refentrytitle><manvolnum>2</manvolnum></citerefentry>, | |
| 331 | <citerefentry><refentrytitle>swapon</refentrytitle><manvolnum>2</manvolnum></citerefentry>, | |
| 332 | <citerefentry><refentrytitle>swapoff</refentrytitle><manvolnum>2</manvolnum></citerefentry>, | |
| 333 | <citerefentry><refentrytitle>sethostname</refentrytitle><manvolnum>2</manvolnum></citerefentry>, | |
| 334 | and | |
| 335 | <citerefentry><refentrytitle>setdomainname</refentrytitle><manvolnum>2</manvolnum></citerefentry>;</para> | |
| 336 | </listitem> | |
| 337 | <listitem override='bullet'> | |
| 338 | <para>perform privileged | |
| 339 | <citerefentry><refentrytitle>syslog</refentrytitle><manvolnum>2</manvolnum></citerefentry> | |
| 340 | operations (since Linux 2.6.37, | |
| 341 | <emphasis remap='B'>CAP_SYSLOG</emphasis> | |
| 342 | should be used to permit such operations);</para> | |
| 343 | </listitem> | |
| 344 | <listitem override='bullet'> | |
| 345 | <para>perform | |
| 346 | <emphasis remap='B'>IPC_SET</emphasis> | |
| 347 | and | |
| 348 | <emphasis remap='B'>IPC_RMID</emphasis> | |
| 349 | operations on arbitrary System V IPC objects;</para> | |
| 350 | </listitem> | |
| 351 | <listitem override='bullet'> | |
| 352 | <para>perform operations on | |
| 353 | <emphasis remap='I'>trusted</emphasis> | |
| 354 | and | |
| 355 | <emphasis remap='I'>security</emphasis> | |
| 356 | Extended Attributes (see | |
| 357 | <citerefentry><refentrytitle>attr</refentrytitle><manvolnum>5</manvolnum></citerefentry>);</para> | |
| 358 | </listitem> | |
| 359 | <listitem override='bullet'> | |
| 360 | <para>use | |
| 361 | <citerefentry><refentrytitle>lookup_dcookie</refentrytitle><manvolnum>2</manvolnum></citerefentry>;</para> | |
| 362 | </listitem> | |
| 363 | <listitem override='bullet'> | |
| 364 | <para>use | |
| 365 | <citerefentry><refentrytitle>ioprio_set</refentrytitle><manvolnum>2</manvolnum></citerefentry> | |
| 366 | to assign | |
| 367 | <emphasis remap='B'>IOPRIO_CLASS_RT</emphasis> | |
| 368 | and (before Linux 2.6.25) | |
| 369 | <emphasis remap='B'>IOPRIO_CLASS_IDLE</emphasis> | |
| 370 | I/O scheduling classes;</para> | |
| 371 | </listitem> | |
| 372 | <listitem override='bullet'> | |
| 373 | <para>forge UID when passing socket credentials;</para> | |
| 374 | </listitem> | |
| 375 | <listitem override='bullet'> | |
| 376 | <para>exceed | |
| 377 | <filename>/proc/sys/fs/file-max</filename>, | |
| 378 | the system-wide limit on the number of open files, | |
| 379 | in system calls that open files (e.g., | |
| 380 | <citerefentry><refentrytitle>accept</refentrytitle><manvolnum>2</manvolnum></citerefentry>, | |
| 381 | <citerefentry><refentrytitle>execve</refentrytitle><manvolnum>2</manvolnum></citerefentry>, | |
| 382 | <citerefentry><refentrytitle>open</refentrytitle><manvolnum>2</manvolnum></citerefentry>, | |
| 383 | <citerefentry><refentrytitle>pipe</refentrytitle><manvolnum>2</manvolnum></citerefentry>);</para> | |
| 384 | </listitem> | |
| 385 | <listitem override='bullet'> | |
| 386 | <para>employ | |
| 387 | <emphasis remap='B'>CLONE_NEWNS</emphasis> | |
| 388 | flag with | |
| 389 | <citerefentry><refentrytitle>clone</refentrytitle><manvolnum>2</manvolnum></citerefentry> | |
| 390 | and | |
| 391 | <citerefentry><refentrytitle>unshare</refentrytitle><manvolnum>2</manvolnum></citerefentry>;</para> | |
| 392 | </listitem> | |
| 393 | <listitem override='bullet'> | |
| 394 | <para>call | |
| 395 | <citerefentry><refentrytitle>setns</refentrytitle><manvolnum>2</manvolnum></citerefentry>;</para> | |
| 396 | </listitem> | |
| 397 | <listitem override='bullet'> | |
| 398 | <para>perform | |
| 399 | <emphasis remap='B'>KEYCTL_CHOWN</emphasis> | |
| 400 | and | |
| 401 | <emphasis remap='B'>KEYCTL_SETPERM</emphasis> | |
| 402 | <citerefentry><refentrytitle>keyctl</refentrytitle><manvolnum>2</manvolnum></citerefentry> | |
| 403 | operations;</para> | |
| 404 | </listitem> | |
| 405 | <listitem override='bullet'> | |
| 406 | <para>perform | |
| 407 | <citerefentry><refentrytitle>madvise</refentrytitle><manvolnum>2</manvolnum></citerefentry> | |
| 408 | <emphasis remap='B'>MADV_HWPOISON</emphasis> | |
| 409 | operation.</para> | |
| 410 | </listitem> | |
| 411 | </itemizedlist> | |
| 412 | <!-- PD --> | |
| 413 | </listitem> | |
| 414 | </varlistentry> | |
| 415 | <varlistentry> | |
| 416 | <term><emphasis remap='B'>CAP_SYS_BOOT</emphasis></term> | |
| 417 | <listitem> | |
| 418 | <para>Use | |
| 419 | <citerefentry><refentrytitle>reboot</refentrytitle><manvolnum>2</manvolnum></citerefentry> | |
| 420 | and | |
| 421 | <citerefentry><refentrytitle>kexec_load</refentrytitle><manvolnum>2</manvolnum></citerefentry>.</para> | |
| 422 | </listitem> | |
| 423 | </varlistentry> | |
| 424 | <varlistentry> | |
| 425 | <term><emphasis remap='B'>CAP_SYS_CHROOT</emphasis></term> | |
| 426 | <listitem> | |
| 427 | <para>Use | |
| 428 | <citerefentry><refentrytitle>chroot</refentrytitle><manvolnum>2</manvolnum></citerefentry>.</para> | |
| 429 | </listitem> | |
| 430 | </varlistentry> | |
| 431 | <varlistentry> | |
| 432 | <term><emphasis remap='B'>CAP_SYS_MODULE</emphasis></term> | |
| 433 | <listitem> | |
| 434 | <para>Load and unload kernel modules | |
| 435 | (see | |
| 436 | <citerefentry><refentrytitle>init_module</refentrytitle><manvolnum>2</manvolnum></citerefentry> | |
| 437 | and | |
| 438 | <citerefentry><refentrytitle>delete_module</refentrytitle><manvolnum>2</manvolnum></citerefentry>); | |
| 439 | in kernels before 2.6.25: | |
| 440 | drop capabilities from the system-wide capability bounding set.</para> | |
| 441 | </listitem> | |
| 442 | </varlistentry> | |
| 443 | <varlistentry> | |
| 444 | <term><emphasis remap='B'>CAP_SYS_NICE</emphasis></term> | |
| 445 | <listitem> | |
| 446 | <!-- PD 0 --> | |
| 447 | <itemizedlist remap='IP+bullet'> | |
| 448 | <listitem override='bullet'> | |
| 449 | <para>Raise process nice value | |
| 450 | (<citerefentry><refentrytitle>nice</refentrytitle><manvolnum>2</manvolnum></citerefentry>, | |
| 451 | <citerefentry><refentrytitle>setpriority</refentrytitle><manvolnum>2</manvolnum></citerefentry>) | |
| 452 | and change the nice value for arbitrary processes;</para> | |
| 453 | </listitem> | |
| 454 | <listitem override='bullet'> | |
| 455 | <para>set real-time scheduling policies for calling process, | |
| 456 | and set scheduling policies and priorities for arbitrary processes | |
| 457 | (<citerefentry><refentrytitle>sched_setscheduler</refentrytitle><manvolnum>2</manvolnum></citerefentry>, | |
| 458 | <citerefentry><refentrytitle>sched_setparam</refentrytitle><manvolnum>2</manvolnum></citerefentry>);</para> | |
| 459 | </listitem> | |
| 460 | <listitem override='bullet'> | |
| 461 | <para>set CPU affinity for arbitrary processes | |
| 462 | (<citerefentry><refentrytitle>sched_setaffinity</refentrytitle><manvolnum>2</manvolnum></citerefentry>);</para> | |
| 463 | </listitem> | |
| 464 | <listitem override='bullet'> | |
| 465 | <para>set I/O scheduling class and priority for arbitrary processes | |
| 466 | (<citerefentry><refentrytitle>ioprio_set</refentrytitle><manvolnum>2</manvolnum></citerefentry>);</para> | |
| 467 | </listitem> | |
| 468 | <listitem override='bullet'> | |
| 469 | <para>apply | |
| 470 | <citerefentry><refentrytitle>migrate_pages</refentrytitle><manvolnum>2</manvolnum></citerefentry> | |
| 471 | to arbitrary processes and allow processes | |
| 472 | to be migrated to arbitrary nodes;</para> | |
| 473 | <!-- FIXME CAP_SYS_NICE also has the following effect for | |
| 474 | migrate_pages(2): | |
| 475 | do_migrate_pages(mm, &old, &new, | |
| 476 | capable(CAP_SYS_NICE) ? MPOL_MF_MOVE_ALL : MPOL_MF_MOVE); --> | |
| 477 | </listitem> | |
| 478 | <listitem override='bullet'> | |
| 479 | <para>apply | |
| 480 | <citerefentry><refentrytitle>move_pages</refentrytitle><manvolnum>2</manvolnum></citerefentry> | |
| 481 | to arbitrary processes;</para> | |
| 482 | </listitem> | |
| 483 | <listitem override='bullet'> | |
| 484 | <para>use the | |
| 485 | <emphasis remap='B'>MPOL_MF_MOVE_ALL</emphasis> | |
| 486 | flag with | |
| 487 | <citerefentry><refentrytitle>mbind</refentrytitle><manvolnum>2</manvolnum></citerefentry> | |
| 488 | and | |
| 489 | <citerefentry><refentrytitle>move_pages</refentrytitle><manvolnum>2</manvolnum></citerefentry>.</para> | |
| 490 | </listitem> | |
| 491 | </itemizedlist> | |
| 492 | <!-- PD --> | |
| 493 | </listitem> | |
| 494 | </varlistentry> | |
| 495 | <varlistentry> | |
| 496 | <term><emphasis remap='B'>CAP_SYS_PACCT</emphasis></term> | |
| 497 | <listitem> | |
| 498 | <para>Use | |
| 499 | <citerefentry><refentrytitle>acct</refentrytitle><manvolnum>2</manvolnum></citerefentry>.</para> | |
| 500 | </listitem> | |
| 501 | </varlistentry> | |
| 502 | <varlistentry> | |
| 503 | <term><emphasis remap='B'>CAP_SYS_PTRACE</emphasis></term> | |
| 504 | <listitem> | |
| 505 | <para>Trace arbitrary processes using | |
| 506 | <citerefentry><refentrytitle>ptrace</refentrytitle><manvolnum>2</manvolnum></citerefentry>; | |
| 507 | apply | |
| 508 | <citerefentry><refentrytitle>get_robust_list</refentrytitle><manvolnum>2</manvolnum></citerefentry> | |
| 509 | to arbitrary processes.</para> | |
| 510 | </listitem> | |
| 511 | </varlistentry> | |
| 512 | <varlistentry> | |
| 513 | <term><emphasis remap='B'>CAP_SYS_RAWIO</emphasis></term> | |
| 514 | <listitem> | |
| 515 | <para>Perform I/O port operations | |
| 516 | (<citerefentry><refentrytitle>iopl</refentrytitle><manvolnum>2</manvolnum></citerefentry> | |
| 517 | and | |
| 518 | <citerefentry><refentrytitle>ioperm</refentrytitle><manvolnum>2</manvolnum></citerefentry>); | |
| 519 | access | |
| 520 | <filename>/proc/kcore</filename>.</para> | |
| 521 | </listitem> | |
| 522 | </varlistentry> | |
| 523 | <varlistentry> | |
| 524 | <term><emphasis remap='B'>CAP_SYS_RESOURCE</emphasis></term> | |
| 525 | <listitem> | |
| 526 | <!-- PD 0 --> | |
| 527 | <itemizedlist remap='IP+bullet'> | |
| 528 | <listitem override='bullet'> | |
| 529 | <para>Use reserved space on ext2 file systems;</para> | |
| 530 | </listitem> | |
| 531 | <listitem override='bullet'> | |
| 532 | <para>make | |
| 533 | <citerefentry><refentrytitle>ioctl</refentrytitle><manvolnum>2</manvolnum></citerefentry> | |
| 534 | calls controlling ext3 journaling;</para> | |
| 535 | </listitem> | |
| 536 | <listitem override='bullet'> | |
| 537 | <para>override disk quota limits;</para> | |
| 538 | </listitem> | |
| 539 | <listitem override='bullet'> | |
| 540 | <para>increase resource limits (see | |
| 541 | <citerefentry><refentrytitle>setrlimit</refentrytitle><manvolnum>2</manvolnum></citerefentry>);</para> | |
| 542 | </listitem> | |
| 543 | <listitem override='bullet'> | |
| 544 | <para>override | |
| 545 | <emphasis remap='B'>RLIMIT_NPROC</emphasis> | |
| 546 | resource limit;</para> | |
| 547 | </listitem> | |
| 548 | <listitem override='bullet'> | |
| 549 | <para>raise | |
| 550 | <emphasis remap='I'>msg_qbytes</emphasis> | |
| 551 | limit for a System V message queue above the limit in | |
| 552 | <filename>/proc/sys/kernel/msgmnb</filename> | |
| 553 | (see | |
| 554 | <citerefentry><refentrytitle>msgop</refentrytitle><manvolnum>2</manvolnum></citerefentry> | |
| 555 | and | |
| 556 | <citerefentry><refentrytitle>msgctl</refentrytitle><manvolnum>2</manvolnum></citerefentry>).</para> | |
| 557 | </listitem> | |
| 558 | <listitem override='bullet'> | |
| 559 | <para>use | |
| 560 | <emphasis remap='B'>F_SETPIPE_SZ</emphasis> | |
| 561 | to increase the capacity of a pipe above the limit specified by | |
| 562 | <filename>/proc/sys/fs/pipe-max-size</filename>.</para> | |
| 563 | </listitem> | |
| 564 | </itemizedlist> | |
| 565 | <!-- PD --> | |
| 566 | </listitem> | |
| 567 | </varlistentry> | |
| 568 | <varlistentry> | |
| 569 | <term><emphasis remap='B'>CAP_SYS_TIME</emphasis></term> | |
| 570 | <listitem> | |
| 571 | <para>Set system clock | |
| 572 | (<citerefentry><refentrytitle>settimeofday</refentrytitle><manvolnum>2</manvolnum></citerefentry>, | |
| 573 | <citerefentry><refentrytitle>stime</refentrytitle><manvolnum>2</manvolnum></citerefentry>, | |
| 574 | <citerefentry><refentrytitle>adjtimex</refentrytitle><manvolnum>2</manvolnum></citerefentry>); | |
| 575 | set real-time (hardware) clock.</para> | |
| 576 | </listitem> | |
| 577 | </varlistentry> | |
| 578 | <varlistentry> | |
| 579 | <term><emphasis remap='B'>CAP_SYS_TTY_CONFIG</emphasis></term> | |
| 580 | <listitem> | |
| 581 | <para>Use | |
| 582 | <citerefentry><refentrytitle>vhangup</refentrytitle><manvolnum>2</manvolnum></citerefentry>.</para> | |
| 583 | </listitem> | |
| 584 | </varlistentry> | |
| 585 | <varlistentry> | |
| 586 | <term><emphasis remap='B'>CAP_SYSLOG</emphasis> (since Linux 2.6.37)</term> | |
| 587 | <listitem> | |
| 588 | <para>Perform privileged | |
| 589 | <citerefentry><refentrytitle>syslog</refentrytitle><manvolnum>2</manvolnum></citerefentry> | |
| 590 | operations. | |
| 591 | See | |
| 592 | <citerefentry><refentrytitle>syslog</refentrytitle><manvolnum>2</manvolnum></citerefentry> | |
| 593 | for information on which operations require privilege.</para> | |
| 594 | ||
| 595 | </listitem> | |
| 596 | </varlistentry> | |
| 597 | </variablelist> | |
| 598 | </refsect2> | |
| 599 | ||
| 600 | <refsect2 id='past_and_current_implementation'><title>Past and Current Implementation</title> | |
| 601 | <para>A full implementation of capabilities requires that:</para> | |
| 602 | <variablelist remap='IP'> | |
| 603 | <varlistentry> | |
| 604 | <term>1.</term> | |
| 605 | <listitem> | |
| 606 | <para>For all privileged operations, | |
| 607 | the kernel must check whether the thread has the required | |
| 608 | capability in its effective set.</para> | |
| 609 | </listitem> | |
| 610 | </varlistentry> | |
| 611 | <varlistentry> | |
| 612 | <term>2.</term> | |
| 613 | <listitem> | |
| 614 | <para>The kernel must provide system calls allowing a thread's capability sets to | |
| 615 | be changed and retrieved.</para> | |
| 616 | </listitem> | |
| 617 | </varlistentry> | |
| 618 | <varlistentry> | |
| 619 | <term>3.</term> | |
| 620 | <listitem> | |
| 621 | <para>The file system must support attaching capabilities to an executable file, | |
| 622 | so that a process gains those capabilities when the file is executed.</para> | |
| 623 | ||
| 624 | <para>Before kernel 2.6.24, only the first two of these requirements are met; | |
| 625 | since kernel 2.6.24, all three requirements are met.</para> | |
| 626 | ||
| 627 | </listitem> | |
| 628 | </varlistentry> | |
| 629 | </variablelist> | |
| 630 | </refsect2> | |
| 631 | ||
| 632 | <refsect2 id='thread_capability_sets'><title>Thread Capability Sets</title> | |
| 633 | <para>Each thread has three capability sets containing zero or more | |
| 634 | of the above capabilities:</para> | |
| 635 | <variablelist remap='TP'> | |
| 636 | <varlistentry> | |
| 637 | <term><emphasis remap='I'>Permitted</emphasis>:</term> | |
| 638 | <listitem> | |
| 639 | <para>This is a limiting superset for the effective | |
| 640 | capabilities that the thread may assume. | |
| 641 | It is also a limiting superset for the capabilities that | |
| 642 | may be added to the inheritable set by a thread that does not have the | |
| 643 | <emphasis remap='B'>CAP_SETPCAP</emphasis> | |
| 644 | capability in its effective set.</para> | |
| 645 | ||
| 646 | <para>If a thread drops a capability from its permitted set, | |
| 647 | it can never reacquire that capability (unless it | |
| 648 | <citerefentry><refentrytitle>execve</refentrytitle><manvolnum>2</manvolnum></citerefentry>s | |
| 649 | either a set-user-ID-root program, or | |
| 650 | a program whose associated file capabilities grant that capability).</para> | |
| 651 | </listitem> | |
| 652 | </varlistentry> | |
| 653 | <varlistentry> | |
| 654 | <term><emphasis remap='I'>Inheritable</emphasis>:</term> | |
| 655 | <listitem> | |
| 656 | <para>This is a set of capabilities preserved across an | |
| 657 | <citerefentry><refentrytitle>execve</refentrytitle><manvolnum>2</manvolnum></citerefentry>. | |
| 658 | It provides a mechanism for a process to assign capabilities | |
| 659 | to the permitted set of the new program during an | |
| 660 | <citerefentry><refentrytitle>execve</refentrytitle><manvolnum>2</manvolnum></citerefentry>.</para> | |
| 661 | </listitem> | |
| 662 | </varlistentry> | |
| 663 | <varlistentry> | |
| 664 | <term><emphasis remap='I'>Effective</emphasis>:</term> | |
| 665 | <listitem> | |
| 666 | <para>This is the set of capabilities used by the kernel to | |
| 667 | perform permission checks for the thread.</para> | |
| 668 | ||
| 669 | <para>A child created via | |
| 670 | <citerefentry><refentrytitle>fork</refentrytitle><manvolnum>2</manvolnum></citerefentry> | |
| 671 | inherits copies of its parent's capability sets. | |
| 672 | See below for a discussion of the treatment of capabilities during | |
| 673 | <citerefentry><refentrytitle>execve</refentrytitle><manvolnum>2</manvolnum></citerefentry>.</para> | |
| 674 | ||
| 675 | <para>Using | |
| 676 | <citerefentry><refentrytitle>capset</refentrytitle><manvolnum>2</manvolnum></citerefentry>, | |
| 677 | a thread may manipulate its own capability sets (see below).</para> | |
| 678 | ||
| 679 | </listitem> | |
| 680 | </varlistentry> | |
| 681 | </variablelist> | |
| 682 | </refsect2> | |
| 683 | ||
| 684 | <refsect2 id='file_capabilities'><title>File Capabilities</title> | |
| 685 | <para>Since kernel 2.6.24, the kernel supports | |
| 686 | associating capability sets with an executable file using | |
| 687 | <citerefentry><refentrytitle>setcap</refentrytitle><manvolnum>8</manvolnum></citerefentry>. | |
| 688 | The file capability sets are stored in an extended attribute (see | |
| 689 | <citerefentry><refentrytitle>setxattr</refentrytitle><manvolnum>2</manvolnum></citerefentry>) | |
| 690 | named | |
| 691 | <emphasis remap='I'>security.capability</emphasis>. | |
| 692 | Writing to this extended attribute requires the | |
| 693 | <emphasis remap='B'>CAP_SETFCAP</emphasis> | |
| 694 | capability. | |
| 695 | The file capability sets, | |
| 696 | in conjunction with the capability sets of the thread, | |
| 697 | determine the capabilities of a thread after an | |
| 698 | <citerefentry><refentrytitle>execve</refentrytitle><manvolnum>2</manvolnum></citerefentry>.</para> | |
| 699 | ||
| 700 | <para>The three file capability sets are:</para> | |
| 701 | <variablelist remap='TP'> | |
| 702 | <varlistentry> | |
| 703 | <term><emphasis remap='I'>Permitted</emphasis> (formerly known as <emphasis remap='I'>forced</emphasis>):</term> | |
| 704 | <listitem> | |
| 705 | <para>These capabilities are automatically permitted to the thread, | |
| 706 | regardless of the thread's inheritable capabilities.</para> | |
| 707 | </listitem> | |
| 708 | </varlistentry> | |
| 709 | <varlistentry> | |
| 710 | <term><emphasis remap='I'>Inheritable</emphasis> (formerly known as <emphasis remap='I'>allowed</emphasis>):</term> | |
| 711 | <listitem> | |
| 712 | <para>This set is ANDed with the thread's inheritable set to determine which | |
| 713 | inheritable capabilities are enabled in the permitted set of | |
| 714 | the thread after the | |
| 715 | <citerefentry><refentrytitle>execve</refentrytitle><manvolnum>2</manvolnum></citerefentry>.</para> | |
| 716 | </listitem> | |
| 717 | </varlistentry> | |
| 718 | <varlistentry> | |
| 719 | <term><emphasis remap='I'>Effective</emphasis>:</term> | |
| 720 | <listitem> | |
| 721 | <para>This is not a set, but rather just a single bit. | |
| 722 | If this bit is set, then during an | |
| 723 | <citerefentry><refentrytitle>execve</refentrytitle><manvolnum>2</manvolnum></citerefentry> | |
| 724 | all of the new permitted capabilities for the thread are | |
| 725 | also raised in the effective set. | |
| 726 | If this bit is not set, then after an | |
| 727 | <citerefentry><refentrytitle>execve</refentrytitle><manvolnum>2</manvolnum></citerefentry>, | |
| 728 | none of the new permitted capabilities is in the new effective set.</para> | |
| 729 | ||
| 730 | <para>Enabling the file effective capability bit implies | |
| 731 | that any file permitted or inheritable capability that causes a | |
| 732 | thread to acquire the corresponding permitted capability during an | |
| 733 | <citerefentry><refentrytitle>execve</refentrytitle><manvolnum>2</manvolnum></citerefentry> | |
| 734 | (see the transformation rules described below) will also acquire that | |
| 735 | capability in its effective set. | |
| 736 | Therefore, when assigning capabilities to a file | |
| 737 | (<citerefentry><refentrytitle>setcap</refentrytitle><manvolnum>8</manvolnum></citerefentry>, | |
| 738 | <citerefentry><refentrytitle>cap_set_file</refentrytitle><manvolnum>3</manvolnum></citerefentry>, | |
| 739 | <citerefentry><refentrytitle>cap_set_fd</refentrytitle><manvolnum>3</manvolnum></citerefentry>), | |
| 740 | if we specify the effective flag as being enabled for any capability, | |
| 741 | then the effective flag must also be specified as enabled | |
| 742 | for all other capabilities for which the corresponding permitted or | |
| 743 | inheritable flags is enabled.</para> | |
| 744 | ||
| 745 | </listitem> | |
| 746 | </varlistentry> | |
| 747 | </variablelist> | |
| 748 | </refsect2> | |
| 749 | ||
| 750 | <refsect2 id='transformation_of_capabilities_during_ex'><title>Transformation of Capabilities During execve()</title> | |
| 751 | ||
| 752 | <para>During an | |
| 753 | <citerefentry><refentrytitle>execve</refentrytitle><manvolnum>2</manvolnum></citerefentry>, | |
| 754 | the kernel calculates the new capabilities of | |
| 755 | the process using the following algorithm:</para> | |
| 756 | <literallayout remap='.nf'> | |
| 757 | ||
| 758 | P'(permitted) = (P(inheritable) & F(inheritable)) | | |
| 759 | (F(permitted) & cap_bset) | |
| 760 | ||
| 761 | P'(effective) = F(effective) ? P'(permitted) : 0 | |
| 762 | ||
| 763 | P'(inheritable) = P(inheritable) [i.e., unchanged] | |
| 764 | ||
| 765 | </literallayout> <!-- .fi --> | |
| 766 | <para>where:</para> | |
| 767 | <blockquote remap='RS'> | |
| 768 | <variablelist remap='IP'> | |
| 769 | <varlistentry> | |
| 770 | <term>P</term> | |
| 771 | <listitem> | |
| 772 | <para>denotes the value of a thread capability set before the | |
| 773 | <citerefentry><refentrytitle>execve</refentrytitle><manvolnum>2</manvolnum></citerefentry></para> | |
| 774 | </listitem> | |
| 775 | </varlistentry> | |
| 776 | <varlistentry> | |
| 777 | <term>P'</term> | |
| 778 | <listitem> | |
| 779 | <para>denotes the value of a capability set after the | |
| 780 | <citerefentry><refentrytitle>execve</refentrytitle><manvolnum>2</manvolnum></citerefentry></para> | |
| 781 | </listitem> | |
| 782 | </varlistentry> | |
| 783 | <varlistentry> | |
| 784 | <term>F</term> | |
| 785 | <listitem> | |
| 786 | <para>denotes a file capability set</para> | |
| 787 | </listitem> | |
| 788 | </varlistentry> | |
| 789 | <varlistentry> | |
| 790 | <term>cap_bset</term> | |
| 791 | <listitem> | |
| 792 | <para>is the value of the capability bounding set (described below).</para> | |
| 793 | </listitem> | |
| 794 | </varlistentry> | |
| 795 | </variablelist> | |
| 796 | </blockquote> <!-- remap='RE' --> | |
| 797 | ||
| 798 | </refsect2> | |
| 799 | ||
| 800 | <refsect2 id='capabilities_and_execution_of_programs_b'><title>Capabilities and execution of programs by root</title> | |
| 801 | <para>In order to provide an all-powerful | |
| 802 | <emphasis remap='I'>root</emphasis> | |
| 803 | using capability sets, during an | |
| 804 | <citerefentry><refentrytitle>execve</refentrytitle><manvolnum>2</manvolnum></citerefentry>:</para> | |
| 805 | <variablelist remap='IP'> | |
| 806 | <varlistentry> | |
| 807 | <term>1.</term> | |
| 808 | <listitem> | |
| 809 | <para>If a set-user-ID-root program is being executed, | |
| 810 | or the real user ID of the process is 0 (root) | |
| 811 | then the file inheritable and permitted sets are defined to be all ones | |
| 812 | (i.e., all capabilities enabled).</para> | |
| 813 | </listitem> | |
| 814 | </varlistentry> | |
| 815 | <varlistentry> | |
| 816 | <term>2.</term> | |
| 817 | <listitem> | |
| 818 | <para>If a set-user-ID-root program is being executed, | |
| 819 | then the file effective bit is defined to be one (enabled).</para> | |
| 820 | ||
| 821 | <para>The upshot of the above rules, | |
| 822 | combined with the capabilities transformations described above, | |
| 823 | is that when a process | |
| 824 | <citerefentry><refentrytitle>execve</refentrytitle><manvolnum>2</manvolnum></citerefentry>s | |
| 825 | a set-user-ID-root program, or when a process with an effective UID of 0 | |
| 826 | <citerefentry><refentrytitle>execve</refentrytitle><manvolnum>2</manvolnum></citerefentry>s | |
| 827 | a program, | |
| 828 | it gains all capabilities in its permitted and effective capability sets, | |
| 829 | except those masked out by the capability bounding set. | |
| 830 | <!-- If a process with real UID 0, and nonzero effective UID does an | |
| 831 | exec(), then it gets all capabilities in its | |
| 832 | permitted set, and no effective capabilities --> | |
| 833 | This provides semantics that are the same as those provided by | |
| 834 | traditional UNIX systems.</para> | |
| 835 | </listitem> | |
| 836 | </varlistentry> | |
| 837 | </variablelist> | |
| 838 | </refsect2> | |
| 839 | ||
| 840 | <refsect2 id='capability_bounding_set'><title>Capability bounding set</title> | |
| 841 | <para>The capability bounding set is a security mechanism that can be used | |
| 842 | to limit the capabilities that can be gained during an | |
| 843 | <citerefentry><refentrytitle>execve</refentrytitle><manvolnum>2</manvolnum></citerefentry>. | |
| 844 | The bounding set is used in the following ways:</para> | |
| 845 | <itemizedlist remap='IP+bullet'> | |
| 846 | <listitem override='bullet'> | |
| 847 | <para>During an | |
| 848 | <citerefentry><refentrytitle>execve</refentrytitle><manvolnum>2</manvolnum></citerefentry>, | |
| 849 | the capability bounding set is ANDed with the file permitted | |
| 850 | capability set, and the result of this operation is assigned to the | |
| 851 | thread's permitted capability set. | |
| 852 | The capability bounding set thus places a limit on the permitted | |
| 853 | capabilities that may be granted by an executable file.</para> | |
| 854 | </listitem> | |
| 855 | <listitem override='bullet'> | |
| 856 | <para>(Since Linux 2.6.25) | |
| 857 | The capability bounding set acts as a limiting superset for | |
| 858 | the capabilities that a thread can add to its inheritable set using | |
| 859 | <citerefentry><refentrytitle>capset</refentrytitle><manvolnum>2</manvolnum></citerefentry>. | |
| 860 | This means that if a capability is not in the bounding set, | |
| 861 | then a thread can't add this capability to its | |
| 862 | inheritable set, even if it was in its permitted capabilities, | |
| 863 | and thereby cannot have this capability preserved in its | |
| 864 | permitted set when it | |
| 865 | <citerefentry><refentrytitle>execve</refentrytitle><manvolnum>2</manvolnum></citerefentry>s | |
| 866 | a file that has the capability in its inheritable set.</para> | |
| 867 | ||
| 868 | <para>Note that the bounding set masks the file permitted capabilities, | |
| 869 | but not the inherited capabilities. | |
| 870 | If a thread maintains a capability in its inherited set | |
| 871 | that is not in its bounding set, | |
| 872 | then it can still gain that capability in its permitted set | |
| 873 | by executing a file that has the capability in its inherited set.</para> | |
| 874 | ||
| 875 | <para>Depending on the kernel version, the capability bounding set is either | |
| 876 | a system-wide attribute, or a per-process attribute.</para> | |
| 877 | ||
| 878 | <para><emphasis remap='B'>Capability bounding set prior to Linux 2.6.25</emphasis></para> | |
| 879 | ||
| 880 | <para>In kernels before 2.6.25, the capability bounding set is a system-wide | |
| 881 | attribute that affects all threads on the system. | |
| 882 | The bounding set is accessible via the file | |
| 883 | <filename>/proc/sys/kernel/cap-bound</filename>. | |
| 884 | (Confusingly, this bit mask parameter is expressed as a | |
| 885 | signed decimal number in | |
| 886 | <filename>/proc/sys/kernel/cap-bound</filename>.)</para> | |
| 887 | ||
| 888 | <para>Only the | |
| 889 | <emphasis remap='B'>init</emphasis> | |
| 890 | process may set capabilities in the capability bounding set; | |
| 891 | other than that, the superuser (more precisely: programs with the | |
| 892 | <emphasis remap='B'>CAP_SYS_MODULE</emphasis> | |
| 893 | capability) may only clear capabilities from this set.</para> | |
| 894 | ||
| 895 | <para>On a standard system the capability bounding set always masks out the | |
| 896 | <emphasis remap='B'>CAP_SETPCAP</emphasis> | |
| 897 | capability. | |
| 898 | To remove this restriction (dangerous!), modify the definition of | |
| 899 | <emphasis remap='B'>CAP_INIT_EFF_SET</emphasis> | |
| 900 | in | |
| 901 | <emphasis remap='I'>include/linux/capability.h</emphasis> | |
| 902 | and rebuild the kernel.</para> | |
| 903 | ||
| 904 | <para>The system-wide capability bounding set feature was added | |
| 905 | to Linux starting with kernel version 2.2.11.</para> | |
| 906 | ||
| 907 | ||
| 908 | <para><emphasis remap='B'>Capability bounding set from Linux 2.6.25 onward</emphasis></para> | |
| 909 | ||
| 910 | <para>From Linux 2.6.25, the | |
| 911 | <emphasis remap='I'>capability bounding set</emphasis> | |
| 912 | is a per-thread attribute. | |
| 913 | (There is no longer a system-wide capability bounding set.)</para> | |
| 914 | ||
| 915 | <para>The bounding set is inherited at | |
| 916 | <citerefentry><refentrytitle>fork</refentrytitle><manvolnum>2</manvolnum></citerefentry> | |
| 917 | from the thread's parent, and is preserved across an | |
| 918 | <citerefentry><refentrytitle>execve</refentrytitle><manvolnum>2</manvolnum></citerefentry>.</para> | |
| 919 | ||
| 920 | <para>A thread may remove capabilities from its capability bounding set using the | |
| 921 | <citerefentry><refentrytitle>prctl</refentrytitle><manvolnum>2</manvolnum></citerefentry> | |
| 922 | <emphasis remap='B'>PR_CAPBSET_DROP</emphasis> | |
| 923 | operation, provided it has the | |
| 924 | <emphasis remap='B'>CAP_SETPCAP</emphasis> | |
| 925 | capability. | |
| 926 | Once a capability has been dropped from the bounding set, | |
| 927 | it cannot be restored to that set. | |
| 928 | A thread can determine if a capability is in its bounding set using the | |
| 929 | <citerefentry><refentrytitle>prctl</refentrytitle><manvolnum>2</manvolnum></citerefentry> | |
| 930 | <emphasis remap='B'>PR_CAPBSET_READ</emphasis> | |
| 931 | operation.</para> | |
| 932 | ||
| 933 | <para>Removing capabilities from the bounding set is only supported if file | |
| 934 | capabilities are compiled into the kernel. | |
| 935 | In kernels before Linux 2.6.33, | |
| 936 | file capabilities were an optional feature configurable via the | |
| 937 | CONFIG_SECURITY_FILE_CAPABILITIES | |
| 938 | option. | |
| 939 | Since Linux 2.6.33, the configuration option has been removed | |
| 940 | and file capabilities are always part of the kernel. | |
| 941 | When file capabilities are compiled into the kernel, the | |
| 942 | <emphasis remap='B'>init</emphasis> | |
| 943 | process (the ancestor of all processes) begins with a full bounding set. | |
| 944 | If file capabilities are not compiled into the kernel, then | |
| 945 | <emphasis remap='B'>init</emphasis> | |
| 946 | begins with a full bounding set minus | |
| 947 | <emphasis remap='B'>CAP_SETPCAP</emphasis>, | |
| 948 | because this capability has a different meaning when there are | |
| 949 | no file capabilities.</para> | |
| 950 | ||
| 951 | <para>Removing a capability from the bounding set does not remove it | |
| 952 | from the thread's inherited set. | |
| 953 | However it does prevent the capability from being added | |
| 954 | back into the thread's inherited set in the future.</para> | |
| 955 | ||
| 956 | ||
| 957 | </listitem> | |
| 958 | </itemizedlist> | |
| 959 | </refsect2> | |
| 960 | ||
| 961 | <refsect2 id='effect_of_user_id_changes_on_capabilitie'><title>Effect of User ID Changes on Capabilities</title> | |
| 962 | <para>To preserve the traditional semantics for transitions between | |
| 963 | 0 and nonzero user IDs, | |
| 964 | the kernel makes the following changes to a thread's capability | |
| 965 | sets on changes to the thread's real, effective, saved set, | |
| 966 | and file system user IDs (using | |
| 967 | <citerefentry><refentrytitle>setuid</refentrytitle><manvolnum>2</manvolnum></citerefentry>, | |
| 968 | <citerefentry><refentrytitle>setresuid</refentrytitle><manvolnum>2</manvolnum></citerefentry>, | |
| 969 | or similar):</para> | |
| 970 | <variablelist remap='IP'> | |
| 971 | <varlistentry> | |
| 972 | <term>1.</term> | |
| 973 | <listitem> | |
| 974 | <para>If one or more of the real, effective or saved set user IDs | |
| 975 | was previously 0, and as a result of the UID changes all of these IDs | |
| 976 | have a nonzero value, | |
| 977 | then all capabilities are cleared from the permitted and effective | |
| 978 | capability sets.</para> | |
| 979 | </listitem> | |
| 980 | </varlistentry> | |
| 981 | <varlistentry> | |
| 982 | <term>2.</term> | |
| 983 | <listitem> | |
| 984 | <para>If the effective user ID is changed from 0 to nonzero, | |
| 985 | then all capabilities are cleared from the effective set.</para> | |
| 986 | </listitem> | |
| 987 | </varlistentry> | |
| 988 | <varlistentry> | |
| 989 | <term>3.</term> | |
| 990 | <listitem> | |
| 991 | <para>If the effective user ID is changed from nonzero to 0, | |
| 992 | then the permitted set is copied to the effective set.</para> | |
| 993 | </listitem> | |
| 994 | </varlistentry> | |
| 995 | <varlistentry> | |
| 996 | <term>4.</term> | |
| 997 | <listitem> | |
| 998 | <para>If the file system user ID is changed from 0 to nonzero (see | |
| 999 | <citerefentry><refentrytitle>setfsuid</refentrytitle><manvolnum>2</manvolnum></citerefentry>) | |
| 1000 | then the following capabilities are cleared from the effective set: | |
| 1001 | <emphasis remap='B'>CAP_CHOWN</emphasis>, | |
| 1002 | <emphasis remap='B'>CAP_DAC_OVERRIDE</emphasis>, | |
| 1003 | <emphasis remap='B'>CAP_DAC_READ_SEARCH</emphasis>, | |
| 1004 | <emphasis remap='B'>CAP_FOWNER</emphasis>, | |
| 1005 | <emphasis remap='B'>CAP_FSETID</emphasis>, | |
| 1006 | <emphasis remap='B'>CAP_LINUX_IMMUTABLE</emphasis> | |
| 1007 | (since Linux 2.2.30), | |
| 1008 | <emphasis remap='B'>CAP_MAC_OVERRIDE</emphasis>, | |
| 1009 | and | |
| 1010 | <emphasis remap='B'>CAP_MKNOD</emphasis> | |
| 1011 | (since Linux 2.2.30). | |
| 1012 | If the file system UID is changed from nonzero to 0, | |
| 1013 | then any of these capabilities that are enabled in the permitted set | |
| 1014 | are enabled in the effective set.</para> | |
| 1015 | ||
| 1016 | <para>If a thread that has a 0 value for one or more of its user IDs wants | |
| 1017 | to prevent its permitted capability set being cleared when it resets | |
| 1018 | all of its user IDs to nonzero values, it can do so using the | |
| 1019 | <citerefentry><refentrytitle>prctl</refentrytitle><manvolnum>2</manvolnum></citerefentry> | |
| 1020 | <emphasis remap='B'>PR_SET_KEEPCAPS</emphasis> | |
| 1021 | operation.</para> | |
| 1022 | ||
| 1023 | </listitem> | |
| 1024 | </varlistentry> | |
| 1025 | </variablelist> | |
| 1026 | </refsect2> | |
| 1027 | ||
| 1028 | <refsect2 id='programmatically_adjusting_capability_se'><title>Programmatically adjusting capability sets</title> | |
| 1029 | <para>A thread can retrieve and change its capability sets using the | |
| 1030 | <citerefentry><refentrytitle>capget</refentrytitle><manvolnum>2</manvolnum></citerefentry> | |
| 1031 | and | |
| 1032 | <citerefentry><refentrytitle>capset</refentrytitle><manvolnum>2</manvolnum></citerefentry> | |
| 1033 | system calls. | |
| 1034 | However, the use of | |
| 1035 | <citerefentry><refentrytitle>cap_get_proc</refentrytitle><manvolnum>3</manvolnum></citerefentry> | |
| 1036 | and | |
| 1037 | <citerefentry><refentrytitle>cap_set_proc</refentrytitle><manvolnum>3</manvolnum></citerefentry>, | |
| 1038 | both provided in the | |
| 1039 | <emphasis remap='I'>libcap</emphasis> | |
| 1040 | package, | |
| 1041 | is preferred for this purpose. | |
| 1042 | The following rules govern changes to the thread capability sets:</para> | |
| 1043 | <variablelist remap='IP'> | |
| 1044 | <varlistentry> | |
| 1045 | <term>1.</term> | |
| 1046 | <listitem> | |
| 1047 | <para>If the caller does not have the | |
| 1048 | <emphasis remap='B'>CAP_SETPCAP</emphasis> | |
| 1049 | capability, | |
| 1050 | the new inheritable set must be a subset of the combination | |
| 1051 | of the existing inheritable and permitted sets.</para> | |
| 1052 | </listitem> | |
| 1053 | </varlistentry> | |
| 1054 | <varlistentry> | |
| 1055 | <term>2.</term> | |
| 1056 | <listitem> | |
| 1057 | <para>(Since kernel 2.6.25) | |
| 1058 | The new inheritable set must be a subset of the combination of the | |
| 1059 | existing inheritable set and the capability bounding set.</para> | |
| 1060 | </listitem> | |
| 1061 | </varlistentry> | |
| 1062 | <varlistentry> | |
| 1063 | <term>3.</term> | |
| 1064 | <listitem> | |
| 1065 | <para>The new permitted set must be a subset of the existing permitted set | |
| 1066 | (i.e., it is not possible to acquire permitted capabilities | |
| 1067 | that the thread does not currently have).</para> | |
| 1068 | </listitem> | |
| 1069 | </varlistentry> | |
| 1070 | <varlistentry> | |
| 1071 | <term>4.</term> | |
| 1072 | <listitem> | |
| 1073 | <para>The new effective set must be a subset of the new permitted set.</para> | |
| 1074 | </listitem> | |
| 1075 | </varlistentry> | |
| 1076 | </variablelist> | |
| 1077 | </refsect2> | |
| 1078 | ||
| 1079 | <refsect2 id='the_securebits_flags_establishing_a_capa'><title>The "securebits" flags: establishing a capabilities-only environment</title> | |
| 1080 | <!-- For some background: | |
| 1081 | see <ulink url='http://lwn.net/Articles/280279/'>http://lwn.net/Articles/280279/</ulink> and | |
| 1082 | <ulink url='http://article.gmane.org/gmane.linux.kernel.lsm/5476/'>http://article.gmane.org/gmane.linux.kernel.lsm/5476/</ulink> --> | |
| 1083 | <para>Starting with kernel 2.6.26, | |
| 1084 | and with a kernel in which file capabilities are enabled, | |
| 1085 | Linux implements a set of per-thread | |
| 1086 | <emphasis remap='I'>securebits</emphasis> | |
| 1087 | flags that can be used to disable special handling of capabilities for UID 0 | |
| 1088 | (<emphasis remap='I'>root</emphasis>). | |
| 1089 | These flags are as follows:</para> | |
| 1090 | <variablelist remap='TP'> | |
| 1091 | <varlistentry> | |
| 1092 | <term><emphasis remap='B'>SECBIT_KEEP_CAPS</emphasis></term> | |
| 1093 | <listitem> | |
| 1094 | <para>Setting this flag allows a thread that has one or more 0 UIDs to retain | |
| 1095 | its capabilities when it switches all of its UIDs to a nonzero value. | |
| 1096 | If this flag is not set, | |
| 1097 | then such a UID switch causes the thread to lose all capabilities. | |
| 1098 | This flag is always cleared on an | |
| 1099 | <citerefentry><refentrytitle>execve</refentrytitle><manvolnum>2</manvolnum></citerefentry>. | |
| 1100 | (This flag provides the same functionality as the older | |
| 1101 | <citerefentry><refentrytitle>prctl</refentrytitle><manvolnum>2</manvolnum></citerefentry> | |
| 1102 | <emphasis remap='B'>PR_SET_KEEPCAPS</emphasis> | |
| 1103 | operation.)</para> | |
| 1104 | </listitem> | |
| 1105 | </varlistentry> | |
| 1106 | <varlistentry> | |
| 1107 | <term><emphasis remap='B'>SECBIT_NO_SETUID_FIXUP</emphasis></term> | |
| 1108 | <listitem> | |
| 1109 | <para>Setting this flag stops the kernel from adjusting capability sets when | |
| 1110 | the threads's effective and file system UIDs are switched between | |
| 1111 | zero and nonzero values. | |
| 1112 | (See the subsection | |
| 1113 | <emphasis remap='I'>Effect of User ID Changes on Capabilities</emphasis>.)</para> | |
| 1114 | </listitem> | |
| 1115 | </varlistentry> | |
| 1116 | <varlistentry> | |
| 1117 | <term><emphasis remap='B'>SECBIT_NOROOT</emphasis></term> | |
| 1118 | <listitem> | |
| 1119 | <para>If this bit is set, then the kernel does not grant capabilities | |
| 1120 | when a set-user-ID-root program is executed, or when a process with | |
| 1121 | an effective or real UID of 0 calls | |
| 1122 | <citerefentry><refentrytitle>execve</refentrytitle><manvolnum>2</manvolnum></citerefentry>. | |
| 1123 | (See the subsection | |
| 1124 | <emphasis remap='I'>Capabilities and execution of programs by root</emphasis>.)</para> | |
| 1125 | ||
| 1126 | <para>Each of the above "base" flags has a companion "locked" flag. | |
| 1127 | Setting any of the "locked" flags is irreversible, | |
| 1128 | and has the effect of preventing further changes to the | |
| 1129 | corresponding "base" flag. | |
| 1130 | The locked flags are: | |
| 1131 | <emphasis remap='B'>SECBIT_KEEP_CAPS_LOCKED</emphasis>, | |
| 1132 | <emphasis remap='B'>SECBIT_NO_SETUID_FIXUP_LOCKED</emphasis>, | |
| 1133 | and | |
| 1134 | <emphasis remap='B'>SECBIT_NOROOT_LOCKED</emphasis>.</para> | |
| 1135 | ||
| 1136 | <para>The | |
| 1137 | <emphasis remap='I'>securebits</emphasis> | |
| 1138 | flags can be modified and retrieved using the | |
| 1139 | <citerefentry><refentrytitle>prctl</refentrytitle><manvolnum>2</manvolnum></citerefentry> | |
| 1140 | <emphasis remap='B'>PR_SET_SECUREBITS</emphasis> | |
| 1141 | and | |
| 1142 | <emphasis remap='B'>PR_GET_SECUREBITS</emphasis> | |
| 1143 | operations. | |
| 1144 | The | |
| 1145 | <emphasis remap='B'>CAP_SETPCAP</emphasis> | |
| 1146 | capability is required to modify the flags.</para> | |
| 1147 | ||
| 1148 | <para>The | |
| 1149 | <emphasis remap='I'>securebits</emphasis> | |
| 1150 | flags are inherited by child processes. | |
| 1151 | During an | |
| 1152 | <citerefentry><refentrytitle>execve</refentrytitle><manvolnum>2</manvolnum></citerefentry>, | |
| 1153 | all of the flags are preserved, except | |
| 1154 | <emphasis remap='B'>SECBIT_KEEP_CAPS</emphasis> | |
| 1155 | which is always cleared.</para> | |
| 1156 | ||
| 1157 | <para>An application can use the following call to lock itself, | |
| 1158 | and all of its descendants, | |
| 1159 | into an environment where the only way of gaining capabilities | |
| 1160 | is by executing a program with associated file capabilities:</para> | |
| 1161 | <literallayout remap='.nf'> | |
| 1162 | ||
| 1163 | prctl(PR_SET_SECUREBITS, | |
| 1164 | SECBIT_KEEP_CAPS_LOCKED | | |
| 1165 | SECBIT_NO_SETUID_FIXUP | | |
| 1166 | SECBIT_NO_SETUID_FIXUP_LOCKED | | |
| 1167 | SECBIT_NOROOT | | |
| 1168 | SECBIT_NOROOT_LOCKED); | |
| 1169 | </literallayout> <!-- .fi --> | |
| 1170 | </listitem> | |
| 1171 | </varlistentry> | |
| 1172 | </variablelist> | |
| 1173 | </refsect2> | |
| 1174 | </refsect1> | |
| 1175 | ||
| 1176 | <refsect1 id='conforming_to'><title>CONFORMING TO</title> | |
| 1177 | <para>No standards govern capabilities, but the Linux capability implementation | |
| 1178 | is based on the withdrawn POSIX.1e draft standard; see | |
| 1179 | <emphasis remap='I'><ulink url='http://wt.xpilot.org/publications/posix.1e/'>http://wt.xpilot.org/publications/posix.1e/</ulink></emphasis>.</para> | |
| 1180 | </refsect1> | |
| 1181 | ||
| 1182 | <refsect1 id='notes'><title>NOTES</title> | |
| 1183 | <para>Since kernel 2.5.27, capabilities are an optional kernel component, | |
| 1184 | and can be enabled/disabled via the CONFIG_SECURITY_CAPABILITIES | |
| 1185 | kernel configuration option.</para> | |
| 1186 | ||
| 1187 | <para>The | |
| 1188 | <filename>/proc/PID/task/TID/status</filename> | |
| 1189 | file can be used to view the capability sets of a thread. | |
| 1190 | The | |
| 1191 | <filename>/proc/PID/status</filename> | |
| 1192 | file shows the capability sets of a process's main thread.</para> | |
| 1193 | ||
| 1194 | <para>The | |
| 1195 | <emphasis remap='I'>libcap</emphasis> | |
| 1196 | package provides a suite of routines for setting and | |
| 1197 | getting capabilities that is more comfortable and less likely | |
| 1198 | to change than the interface provided by | |
| 1199 | <citerefentry><refentrytitle>capset</refentrytitle><manvolnum>2</manvolnum></citerefentry> | |
| 1200 | and | |
| 1201 | <citerefentry><refentrytitle>capget</refentrytitle><manvolnum>2</manvolnum></citerefentry>. | |
| 1202 | This package also provides the | |
| 1203 | <citerefentry><refentrytitle>setcap</refentrytitle><manvolnum>8</manvolnum></citerefentry> | |
| 1204 | and | |
| 1205 | <citerefentry><refentrytitle>getcap</refentrytitle><manvolnum>8</manvolnum></citerefentry> | |
| 1206 | programs. | |
| 1207 | It can be found at</para> | |
| 1208 | ||
| 1209 | <para><emphasis remap='I'><ulink url='http://www.kernel.org/pub/linux/libs/security/linux-privs'>http://www.kernel.org/pub/linux/libs/security/linux-privs</ulink></emphasis>.</para> | |
| 1210 | ||
| 1211 | <para>Before kernel 2.6.24, and since kernel 2.6.24 if | |
| 1212 | file capabilities are not enabled, a thread with the | |
| 1213 | <emphasis remap='B'>CAP_SETPCAP</emphasis> | |
| 1214 | capability can manipulate the capabilities of threads other than itself. | |
| 1215 | However, this is only theoretically possible, | |
| 1216 | since no thread ever has | |
| 1217 | <emphasis remap='B'>CAP_SETPCAP</emphasis> | |
| 1218 | in either of these cases:</para> | |
| 1219 | <itemizedlist remap='IP+bullet'> | |
| 1220 | <listitem override='bullet'> | |
| 1221 | <para>In the pre-2.6.25 implementation the system-wide capability bounding set, | |
| 1222 | <filename>/proc/sys/kernel/cap-bound</filename>, | |
| 1223 | always masks out this capability, and this can not be changed | |
| 1224 | without modifying the kernel source and rebuilding.</para> | |
| 1225 | </listitem> | |
| 1226 | <listitem override='bullet'> | |
| 1227 | <para>If file capabilities are disabled in the current implementation, then | |
| 1228 | <emphasis remap='B'>init</emphasis> | |
| 1229 | starts out with this capability removed from its per-process bounding | |
| 1230 | set, and that bounding set is inherited by all other processes | |
| 1231 | created on the system.</para> | |
| 1232 | </listitem> | |
| 1233 | </itemizedlist> | |
| 1234 | </refsect1> | |
| 1235 | ||
| 1236 | <refsect1 id='see_also'><title>SEE ALSO</title> | |
| 1237 | <para><citerefentry><refentrytitle>capget</refentrytitle><manvolnum>2</manvolnum></citerefentry>, | |
| 1238 | <citerefentry><refentrytitle>prctl</refentrytitle><manvolnum>2</manvolnum></citerefentry>, | |
| 1239 | <citerefentry><refentrytitle>setfsuid</refentrytitle><manvolnum>2</manvolnum></citerefentry>, | |
| 1240 | <citerefentry><refentrytitle>cap_clear</refentrytitle><manvolnum>3</manvolnum></citerefentry>, | |
| 1241 | <citerefentry><refentrytitle>cap_copy_ext</refentrytitle><manvolnum>3</manvolnum></citerefentry>, | |
| 1242 | <citerefentry><refentrytitle>cap_from_text</refentrytitle><manvolnum>3</manvolnum></citerefentry>, | |
| 1243 | <citerefentry><refentrytitle>cap_get_file</refentrytitle><manvolnum>3</manvolnum></citerefentry>, | |
| 1244 | <citerefentry><refentrytitle>cap_get_proc</refentrytitle><manvolnum>3</manvolnum></citerefentry>, | |
| 1245 | <citerefentry><refentrytitle>cap_init</refentrytitle><manvolnum>3</manvolnum></citerefentry>, | |
| 1246 | <citerefentry><refentrytitle>capgetp</refentrytitle><manvolnum>3</manvolnum></citerefentry>, | |
| 1247 | <citerefentry><refentrytitle>capsetp</refentrytitle><manvolnum>3</manvolnum></citerefentry>, | |
| 1248 | <citerefentry><refentrytitle>credentials</refentrytitle><manvolnum>7</manvolnum></citerefentry>, | |
| 1249 | <citerefentry><refentrytitle>pthreads</refentrytitle><manvolnum>7</manvolnum></citerefentry>, | |
| 1250 | <citerefentry><refentrytitle>getcap</refentrytitle><manvolnum>8</manvolnum></citerefentry>, | |
| 1251 | <citerefentry><refentrytitle>setcap</refentrytitle><manvolnum>8</manvolnum></citerefentry></para> | |
| 1252 | ||
| 1253 | <para><emphasis remap='I'>include/linux/capability.h</emphasis> | |
| 1254 | in the kernel source</para> | |
| 1255 | </refsect1> | |
| 1256 | ||
| 1257 | <refsect1 id='colophon'><title>COLOPHON</title> | |
| 1258 | <para>This page is part of release 3.35 of the Linux | |
| 1259 | <emphasis remap='I'>man-pages</emphasis> | |
| 1260 | project. | |
| 1261 | A description of the project, | |
| 1262 | and information about reporting bugs, | |
| 1263 | can be found at | |
| 1264 | <ulink url='http://man7.org/linux/man-pages/'>http://man7.org/linux/man-pages/</ulink>.</para> | |
| 1265 | </refsect1> | |
| 1266 | </refentry> | |
| 1267 |
| 0 | .\" Copyright (c) 2002 by Michael Kerrisk <mtk.manpages@gmail.com> | |
| 1 | .\" | |
| 2 | .\" Permission is granted to make and distribute verbatim copies of this | |
| 3 | .\" manual provided the copyright notice and this permission notice are | |
| 4 | .\" preserved on all copies. | |
| 5 | .\" | |
| 6 | .\" Permission is granted to copy and distribute modified versions of this | |
| 7 | .\" manual under the conditions for verbatim copying, provided that the | |
| 8 | .\" entire resulting derived work is distributed under the terms of a | |
| 9 | .\" permission notice identical to this one. | |
| 10 | .\" | |
| 11 | .\" Since the Linux kernel and libraries are constantly changing, this | |
| 12 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
| 13 | .\" responsibility for errors or omissions, or for damages resulting from | |
| 14 | .\" the use of the information contained herein. The author(s) may not | |
| 15 | .\" have taken the same level of care in the production of this manual, | |
| 16 | .\" which is licensed free of charge, as they might when working | |
| 17 | .\" professionally. | |
| 18 | .\" | |
| 19 | .\" Formatted or processed versions of this manual, if unaccompanied by | |
| 20 | .\" the source, must acknowledge the copyright and authors of this work. | |
| 21 | .\" | |
| 22 | .\" 6 Aug 2002 - Initial Creation | |
| 23 | .\" Modified 2003-05-23, Michael Kerrisk, <mtk.manpages@gmail.com> | |
| 24 | .\" Modified 2004-05-27, Michael Kerrisk, <mtk.manpages@gmail.com> | |
| 25 | .\" 2004-12-08, mtk Added O_NOATIME for CAP_FOWNER | |
| 26 | .\" 2005-08-16, mtk, Added CAP_AUDIT_CONTROL and CAP_AUDIT_WRITE | |
| 27 | .\" 2008-07-15, Serge Hallyn <serue@us.bbm.com> | |
| 28 | .\" Document file capabilities, per-process capability | |
| 29 | .\" bounding set, changed semantics for CAP_SETPCAP, | |
| 30 | .\" and other changes in 2.6.2[45]. | |
| 31 | .\" Add CAP_MAC_ADMIN, CAP_MAC_OVERRIDE, CAP_SETFCAP. | |
| 32 | .\" 2008-07-15, mtk | |
| 33 | .\" Add text describing circumstances in which CAP_SETPCAP | |
| 34 | .\" (theoretically) permits a thread to change the | |
| 35 | .\" capability sets of another thread. | |
| 36 | .\" Add section describing rules for programmatically | |
| 37 | .\" adjusting thread capability sets. | |
| 38 | .\" Describe rationale for capability bounding set. | |
| 39 | .\" Document "securebits" flags. | |
| 40 | .\" Add text noting that if we set the effective flag for one file | |
| 41 | .\" capability, then we must also set the effective flag for all | |
| 42 | .\" other capabilities where the permitted or inheritable bit is set. | |
| 43 | .\" 2011-09-07, mtk/Serge hallyn: Add CAP_SYSLOG | |
| 44 | .\" FIXME: Linux 3.0 added CAP_WAKE_ALARM | |
| 45 | .\" | |
| 46 | .TH CAPABILITIES 7 2011-10-04 "Linux" "Linux Programmer's Manual" | |
| 47 | .SH NAME | |
| 48 | capabilities \- overview of Linux capabilities | |
| 49 | .SH DESCRIPTION | |
| 50 | For the purpose of performing permission checks, | |
| 51 | traditional UNIX implementations distinguish two categories of processes: | |
| 52 | .I privileged | |
| 53 | processes (whose effective user ID is 0, referred to as superuser or root), | |
| 54 | and | |
| 55 | .I unprivileged | |
| 56 | processes (whose effective UID is nonzero). | |
| 57 | Privileged processes bypass all kernel permission checks, | |
| 58 | while unprivileged processes are subject to full permission | |
| 59 | checking based on the process's credentials | |
| 60 | (usually: effective UID, effective GID, and supplementary group list). | |
| 61 | ||
| 62 | Starting with kernel 2.2, Linux divides the privileges traditionally | |
| 63 | associated with superuser into distinct units, known as | |
| 64 | .IR capabilities , | |
| 65 | which can be independently enabled and disabled. | |
| 66 | Capabilities are a per-thread attribute. | |
| 67 | .\" | |
| 68 | .SS Capabilities List | |
| 69 | The following list shows the capabilities implemented on Linux, | |
| 70 | and the operations or behaviors that each capability permits: | |
| 71 | .TP | |
| 72 | .BR CAP_AUDIT_CONTROL " (since Linux 2.6.11)" | |
| 73 | Enable and disable kernel auditing; change auditing filter rules; | |
| 74 | retrieve auditing status and filtering rules. | |
| 75 | .TP | |
| 76 | .BR CAP_AUDIT_WRITE " (since Linux 2.6.11)" | |
| 77 | Write records to kernel auditing log. | |
| 78 | .TP | |
| 79 | .B CAP_CHOWN | |
| 80 | Make arbitrary changes to file UIDs and GIDs (see | |
| 81 | .BR chown (2)). | |
| 82 | .TP | |
| 83 | .B CAP_DAC_OVERRIDE | |
| 84 | Bypass file read, write, and execute permission checks. | |
| 85 | (DAC is an abbreviation of "discretionary access control".) | |
| 86 | .TP | |
| 87 | .B CAP_DAC_READ_SEARCH | |
| 88 | Bypass file read permission checks and | |
| 89 | directory read and execute permission checks. | |
| 90 | .TP | |
| 91 | .B CAP_FOWNER | |
| 92 | .PD 0 | |
| 93 | .RS | |
| 94 | .IP * 2 | |
| 95 | Bypass permission checks on operations that normally | |
| 96 | require the file system UID of the process to match the UID of | |
| 97 | the file (e.g., | |
| 98 | .BR chmod (2), | |
| 99 | .BR utime (2)), | |
| 100 | excluding those operations covered by | |
| 101 | .B CAP_DAC_OVERRIDE | |
| 102 | and | |
| 103 | .BR CAP_DAC_READ_SEARCH ; | |
| 104 | .IP * | |
| 105 | set extended file attributes (see | |
| 106 | .BR chattr (1)) | |
| 107 | on arbitrary files; | |
| 108 | .IP * | |
| 109 | set Access Control Lists (ACLs) on arbitrary files; | |
| 110 | .IP * | |
| 111 | ignore directory sticky bit on file deletion; | |
| 112 | .IP * | |
| 113 | specify | |
| 114 | .B O_NOATIME | |
| 115 | for arbitrary files in | |
| 116 | .BR open (2) | |
| 117 | and | |
| 118 | .BR fcntl (2). | |
| 119 | .RE | |
| 120 | .PD | |
| 121 | .TP | |
| 122 | .B CAP_FSETID | |
| 123 | Don't clear set-user-ID and set-group-ID permission | |
| 124 | bits when a file is modified; | |
| 125 | set the set-group-ID bit for a file whose GID does not match | |
| 126 | the file system or any of the supplementary GIDs of the calling process. | |
| 127 | .TP | |
| 128 | .B CAP_IPC_LOCK | |
| 129 | Lock memory | |
| 130 | .RB ( mlock (2), | |
| 131 | .BR mlockall (2), | |
| 132 | .BR mmap (2), | |
| 133 | .BR shmctl (2)). | |
| 134 | .TP | |
| 135 | .B CAP_IPC_OWNER | |
| 136 | Bypass permission checks for operations on System V IPC objects. | |
| 137 | .TP | |
| 138 | .B CAP_KILL | |
| 139 | Bypass permission checks for sending signals (see | |
| 140 | .BR kill (2)). | |
| 141 | This includes use of the | |
| 142 | .BR ioctl (2) | |
| 143 | .B KDSIGACCEPT | |
| 144 | operation. | |
| 145 | .\" FIXME CAP_KILL also has an effect for threads + setting child | |
| 146 | .\" termination signal to other than SIGCHLD: without this | |
| 147 | .\" capability, the termination signal reverts to SIGCHLD | |
| 148 | .\" if the child does an exec(). What is the rationale | |
| 149 | .\" for this? | |
| 150 | .TP | |
| 151 | .BR CAP_LEASE " (since Linux 2.4)" | |
| 152 | Establish leases on arbitrary files (see | |
| 153 | .BR fcntl (2)). | |
| 154 | .TP | |
| 155 | .B CAP_LINUX_IMMUTABLE | |
| 156 | Set the | |
| 157 | .B FS_APPEND_FL | |
| 158 | and | |
| 159 | .B FS_IMMUTABLE_FL | |
| 160 | .\" These attributes are now available on ext2, ext3, Reiserfs, XFS, JFS | |
| 161 | i-node flags (see | |
| 162 | .BR chattr (1)). | |
| 163 | .TP | |
| 164 | .BR CAP_MAC_ADMIN " (since Linux 2.6.25)" | |
| 165 | Override Mandatory Access Control (MAC). | |
| 166 | Implemented for the Smack Linux Security Module (LSM). | |
| 167 | .TP | |
| 168 | .BR CAP_MAC_OVERRIDE " (since Linux 2.6.25)" | |
| 169 | Allow MAC configuration or state changes. | |
| 170 | Implemented for the Smack LSM. | |
| 171 | .TP | |
| 172 | .BR CAP_MKNOD " (since Linux 2.4)" | |
| 173 | Create special files using | |
| 174 | .BR mknod (2). | |
| 175 | .TP | |
| 176 | .B CAP_NET_ADMIN | |
| 177 | Perform various network-related operations | |
| 178 | (e.g., setting privileged socket options, | |
| 179 | enabling multicasting, interface configuration, | |
| 180 | modifying routing tables). | |
| 181 | .TP | |
| 182 | .B CAP_NET_BIND_SERVICE | |
| 183 | Bind a socket to Internet domain privileged ports | |
| 184 | (port numbers less than 1024). | |
| 185 | .TP | |
| 186 | .B CAP_NET_BROADCAST | |
| 187 | (Unused) Make socket broadcasts, and listen to multicasts. | |
| 188 | .TP | |
| 189 | .B CAP_NET_RAW | |
| 190 | Use RAW and PACKET sockets. | |
| 191 | .\" Also various IP options and setsockopt(SO_BINDTODEVICE) | |
| 192 | .TP | |
| 193 | .B CAP_SETGID | |
| 194 | Make arbitrary manipulations of process GIDs and supplementary GID list; | |
| 195 | forge GID when passing socket credentials via UNIX domain sockets. | |
| 196 | .TP | |
| 197 | .BR CAP_SETFCAP " (since Linux 2.6.24)" | |
| 198 | Set file capabilities. | |
| 199 | .TP | |
| 200 | .B CAP_SETPCAP | |
| 201 | If file capabilities are not supported: | |
| 202 | grant or remove any capability in the | |
| 203 | caller's permitted capability set to or from any other process. | |
| 204 | (This property of | |
| 205 | .B CAP_SETPCAP | |
| 206 | is not available when the kernel is configured to support | |
| 207 | file capabilities, since | |
| 208 | .B CAP_SETPCAP | |
| 209 | has entirely different semantics for such kernels.) | |
| 210 | ||
| 211 | If file capabilities are supported: | |
| 212 | add any capability from the calling thread's bounding set | |
| 213 | to its inheritable set; | |
| 214 | drop capabilities from the bounding set (via | |
| 215 | .BR prctl (2) | |
| 216 | .BR PR_CAPBSET_DROP ); | |
| 217 | make changes to the | |
| 218 | .I securebits | |
| 219 | flags. | |
| 220 | .TP | |
| 221 | .B CAP_SETUID | |
| 222 | Make arbitrary manipulations of process UIDs | |
| 223 | .RB ( setuid (2), | |
| 224 | .BR setreuid (2), | |
| 225 | .BR setresuid (2), | |
| 226 | .BR setfsuid (2)); | |
| 227 | make forged UID when passing socket credentials via UNIX domain sockets. | |
| 228 | .\" FIXME CAP_SETUID also an effect in exec(); document this. | |
| 229 | .TP | |
| 230 | .B CAP_SYS_ADMIN | |
| 231 | .PD 0 | |
| 232 | .RS | |
| 233 | .IP * 2 | |
| 234 | Perform a range of system administration operations including: | |
| 235 | .BR quotactl (2), | |
| 236 | .BR mount (2), | |
| 237 | .BR umount (2), | |
| 238 | .BR swapon (2), | |
| 239 | .BR swapoff (2), | |
| 240 | .BR sethostname (2), | |
| 241 | and | |
| 242 | .BR setdomainname (2); | |
| 243 | .IP * | |
| 244 | perform privileged | |
| 245 | .BR syslog (2) | |
| 246 | operations (since Linux 2.6.37, | |
| 247 | .BR CAP_SYSLOG | |
| 248 | should be used to permit such operations); | |
| 249 | .IP * | |
| 250 | perform | |
| 251 | .B IPC_SET | |
| 252 | and | |
| 253 | .B IPC_RMID | |
| 254 | operations on arbitrary System V IPC objects; | |
| 255 | .IP * | |
| 256 | perform operations on | |
| 257 | .I trusted | |
| 258 | and | |
| 259 | .I security | |
| 260 | Extended Attributes (see | |
| 261 | .BR attr (5)); | |
| 262 | .IP * | |
| 263 | use | |
| 264 | .BR lookup_dcookie (2); | |
| 265 | .IP * | |
| 266 | use | |
| 267 | .BR ioprio_set (2) | |
| 268 | to assign | |
| 269 | .B IOPRIO_CLASS_RT | |
| 270 | and (before Linux 2.6.25) | |
| 271 | .B IOPRIO_CLASS_IDLE | |
| 272 | I/O scheduling classes; | |
| 273 | .IP * | |
| 274 | forge UID when passing socket credentials; | |
| 275 | .IP * | |
| 276 | exceed | |
| 277 | .IR /proc/sys/fs/file-max , | |
| 278 | the system-wide limit on the number of open files, | |
| 279 | in system calls that open files (e.g., | |
| 280 | .BR accept (2), | |
| 281 | .BR execve (2), | |
| 282 | .BR open (2), | |
| 283 | .BR pipe (2)); | |
| 284 | .IP * | |
| 285 | employ | |
| 286 | .B CLONE_NEWNS | |
| 287 | flag with | |
| 288 | .BR clone (2) | |
| 289 | and | |
| 290 | .BR unshare (2); | |
| 291 | .IP * | |
| 292 | call | |
| 293 | .BR setns (2); | |
| 294 | .IP * | |
| 295 | perform | |
| 296 | .B KEYCTL_CHOWN | |
| 297 | and | |
| 298 | .B KEYCTL_SETPERM | |
| 299 | .BR keyctl (2) | |
| 300 | operations; | |
| 301 | .IP * | |
| 302 | perform | |
| 303 | .BR madvise (2) | |
| 304 | .B MADV_HWPOISON | |
| 305 | operation. | |
| 306 | .RE | |
| 307 | .PD | |
| 308 | .TP | |
| 309 | .B CAP_SYS_BOOT | |
| 310 | Use | |
| 311 | .BR reboot (2) | |
| 312 | and | |
| 313 | .BR kexec_load (2). | |
| 314 | .TP | |
| 315 | .B CAP_SYS_CHROOT | |
| 316 | Use | |
| 317 | .BR chroot (2). | |
| 318 | .TP | |
| 319 | .B CAP_SYS_MODULE | |
| 320 | Load and unload kernel modules | |
| 321 | (see | |
| 322 | .BR init_module (2) | |
| 323 | and | |
| 324 | .BR delete_module (2)); | |
| 325 | in kernels before 2.6.25: | |
| 326 | drop capabilities from the system-wide capability bounding set. | |
| 327 | .TP | |
| 328 | .B CAP_SYS_NICE | |
| 329 | .PD 0 | |
| 330 | .RS | |
| 331 | .IP * 2 | |
| 332 | Raise process nice value | |
| 333 | .RB ( nice (2), | |
| 334 | .BR setpriority (2)) | |
| 335 | and change the nice value for arbitrary processes; | |
| 336 | .IP * | |
| 337 | set real-time scheduling policies for calling process, | |
| 338 | and set scheduling policies and priorities for arbitrary processes | |
| 339 | .RB ( sched_setscheduler (2), | |
| 340 | .BR sched_setparam (2)); | |
| 341 | .IP * | |
| 342 | set CPU affinity for arbitrary processes | |
| 343 | .RB ( sched_setaffinity (2)); | |
| 344 | .IP * | |
| 345 | set I/O scheduling class and priority for arbitrary processes | |
| 346 | .RB ( ioprio_set (2)); | |
| 347 | .IP * | |
| 348 | apply | |
| 349 | .BR migrate_pages (2) | |
| 350 | to arbitrary processes and allow processes | |
| 351 | to be migrated to arbitrary nodes; | |
| 352 | .\" FIXME CAP_SYS_NICE also has the following effect for | |
| 353 | .\" migrate_pages(2): | |
| 354 | .\" do_migrate_pages(mm, &old, &new, | |
| 355 | .\" capable(CAP_SYS_NICE) ? MPOL_MF_MOVE_ALL : MPOL_MF_MOVE); | |
| 356 | .IP * | |
| 357 | apply | |
| 358 | .BR move_pages (2) | |
| 359 | to arbitrary processes; | |
| 360 | .IP * | |
| 361 | use the | |
| 362 | .B MPOL_MF_MOVE_ALL | |
| 363 | flag with | |
| 364 | .BR mbind (2) | |
| 365 | and | |
| 366 | .BR move_pages (2). | |
| 367 | .RE | |
| 368 | .PD | |
| 369 | .TP | |
| 370 | .B CAP_SYS_PACCT | |
| 371 | Use | |
| 372 | .BR acct (2). | |
| 373 | .TP | |
| 374 | .B CAP_SYS_PTRACE | |
| 375 | Trace arbitrary processes using | |
| 376 | .BR ptrace (2); | |
| 377 | apply | |
| 378 | .BR get_robust_list (2) | |
| 379 | to arbitrary processes. | |
| 380 | .TP | |
| 381 | .B CAP_SYS_RAWIO | |
| 382 | Perform I/O port operations | |
| 383 | .RB ( iopl (2) | |
| 384 | and | |
| 385 | .BR ioperm (2)); | |
| 386 | access | |
| 387 | .IR /proc/kcore . | |
| 388 | .TP | |
| 389 | .B CAP_SYS_RESOURCE | |
| 390 | .PD 0 | |
| 391 | .RS | |
| 392 | .IP * 2 | |
| 393 | Use reserved space on ext2 file systems; | |
| 394 | .IP * | |
| 395 | make | |
| 396 | .BR ioctl (2) | |
| 397 | calls controlling ext3 journaling; | |
| 398 | .IP * | |
| 399 | override disk quota limits; | |
| 400 | .IP * | |
| 401 | increase resource limits (see | |
| 402 | .BR setrlimit (2)); | |
| 403 | .IP * | |
| 404 | override | |
| 405 | .B RLIMIT_NPROC | |
| 406 | resource limit; | |
| 407 | .IP * | |
| 408 | raise | |
| 409 | .I msg_qbytes | |
| 410 | limit for a System V message queue above the limit in | |
| 411 | .I /proc/sys/kernel/msgmnb | |
| 412 | (see | |
| 413 | .BR msgop (2) | |
| 414 | and | |
| 415 | .BR msgctl (2)). | |
| 416 | .IP * | |
| 417 | use | |
| 418 | .BR F_SETPIPE_SZ | |
| 419 | to increase the capacity of a pipe above the limit specified by | |
| 420 | .IR /proc/sys/fs/pipe-max-size . | |
| 421 | .RE | |
| 422 | .PD | |
| 423 | .TP | |
| 424 | .B CAP_SYS_TIME | |
| 425 | Set system clock | |
| 426 | .RB ( settimeofday (2), | |
| 427 | .BR stime (2), | |
| 428 | .BR adjtimex (2)); | |
| 429 | set real-time (hardware) clock. | |
| 430 | .TP | |
| 431 | .B CAP_SYS_TTY_CONFIG | |
| 432 | Use | |
| 433 | .BR vhangup (2). | |
| 434 | .TP | |
| 435 | .BR CAP_SYSLOG " (since Linux 2.6.37)" | |
| 436 | Perform privileged | |
| 437 | .BR syslog (2) | |
| 438 | operations. | |
| 439 | See | |
| 440 | .BR syslog (2) | |
| 441 | for information on which operations require privilege. | |
| 442 | .\" | |
| 443 | .SS Past and Current Implementation | |
| 444 | A full implementation of capabilities requires that: | |
| 445 | .IP 1. 3 | |
| 446 | For all privileged operations, | |
| 447 | the kernel must check whether the thread has the required | |
| 448 | capability in its effective set. | |
| 449 | .IP 2. | |
| 450 | The kernel must provide system calls allowing a thread's capability sets to | |
| 451 | be changed and retrieved. | |
| 452 | .IP 3. | |
| 453 | The file system must support attaching capabilities to an executable file, | |
| 454 | so that a process gains those capabilities when the file is executed. | |
| 455 | .PP | |
| 456 | Before kernel 2.6.24, only the first two of these requirements are met; | |
| 457 | since kernel 2.6.24, all three requirements are met. | |
| 458 | .\" | |
| 459 | .SS Thread Capability Sets | |
| 460 | Each thread has three capability sets containing zero or more | |
| 461 | of the above capabilities: | |
| 462 | .TP | |
| 463 | .IR Permitted : | |
| 464 | This is a limiting superset for the effective | |
| 465 | capabilities that the thread may assume. | |
| 466 | It is also a limiting superset for the capabilities that | |
| 467 | may be added to the inheritable set by a thread that does not have the | |
| 468 | .B CAP_SETPCAP | |
| 469 | capability in its effective set. | |
| 470 | ||
| 471 | If a thread drops a capability from its permitted set, | |
| 472 | it can never reacquire that capability (unless it | |
| 473 | .BR execve (2)s | |
| 474 | either a set-user-ID-root program, or | |
| 475 | a program whose associated file capabilities grant that capability). | |
| 476 | .TP | |
| 477 | .IR Inheritable : | |
| 478 | This is a set of capabilities preserved across an | |
| 479 | .BR execve (2). | |
| 480 | It provides a mechanism for a process to assign capabilities | |
| 481 | to the permitted set of the new program during an | |
| 482 | .BR execve (2). | |
| 483 | .TP | |
| 484 | .IR Effective : | |
| 485 | This is the set of capabilities used by the kernel to | |
| 486 | perform permission checks for the thread. | |
| 487 | .PP | |
| 488 | A child created via | |
| 489 | .BR fork (2) | |
| 490 | inherits copies of its parent's capability sets. | |
| 491 | See below for a discussion of the treatment of capabilities during | |
| 492 | .BR execve (2). | |
| 493 | .PP | |
| 494 | Using | |
| 495 | .BR capset (2), | |
| 496 | a thread may manipulate its own capability sets (see below). | |
| 497 | .\" | |
| 498 | .SS File Capabilities | |
| 499 | Since kernel 2.6.24, the kernel supports | |
| 500 | associating capability sets with an executable file using | |
| 501 | .BR setcap (8). | |
| 502 | The file capability sets are stored in an extended attribute (see | |
| 503 | .BR setxattr (2)) | |
| 504 | named | |
| 505 | .IR "security.capability" . | |
| 506 | Writing to this extended attribute requires the | |
| 507 | .BR CAP_SETFCAP | |
| 508 | capability. | |
| 509 | The file capability sets, | |
| 510 | in conjunction with the capability sets of the thread, | |
| 511 | determine the capabilities of a thread after an | |
| 512 | .BR execve (2). | |
| 513 | ||
| 514 | The three file capability sets are: | |
| 515 | .TP | |
| 516 | .IR Permitted " (formerly known as " forced ): | |
| 517 | These capabilities are automatically permitted to the thread, | |
| 518 | regardless of the thread's inheritable capabilities. | |
| 519 | .TP | |
| 520 | .IR Inheritable " (formerly known as " allowed ): | |
| 521 | This set is ANDed with the thread's inheritable set to determine which | |
| 522 | inheritable capabilities are enabled in the permitted set of | |
| 523 | the thread after the | |
| 524 | .BR execve (2). | |
| 525 | .TP | |
| 526 | .IR Effective : | |
| 527 | This is not a set, but rather just a single bit. | |
| 528 | If this bit is set, then during an | |
| 529 | .BR execve (2) | |
| 530 | all of the new permitted capabilities for the thread are | |
| 531 | also raised in the effective set. | |
| 532 | If this bit is not set, then after an | |
| 533 | .BR execve (2), | |
| 534 | none of the new permitted capabilities is in the new effective set. | |
| 535 | ||
| 536 | Enabling the file effective capability bit implies | |
| 537 | that any file permitted or inheritable capability that causes a | |
| 538 | thread to acquire the corresponding permitted capability during an | |
| 539 | .BR execve (2) | |
| 540 | (see the transformation rules described below) will also acquire that | |
| 541 | capability in its effective set. | |
| 542 | Therefore, when assigning capabilities to a file | |
| 543 | .RB ( setcap (8), | |
| 544 | .BR cap_set_file (3), | |
| 545 | .BR cap_set_fd (3)), | |
| 546 | if we specify the effective flag as being enabled for any capability, | |
| 547 | then the effective flag must also be specified as enabled | |
| 548 | for all other capabilities for which the corresponding permitted or | |
| 549 | inheritable flags is enabled. | |
| 550 | .\" | |
| 551 | .SS Transformation of Capabilities During execve() | |
| 552 | .PP | |
| 553 | During an | |
| 554 | .BR execve (2), | |
| 555 | the kernel calculates the new capabilities of | |
| 556 | the process using the following algorithm: | |
| 557 | .RS | |
| 558 | .nf | |
| 559 | ||
| 560 | P'(permitted) = (P(inheritable) & F(inheritable)) | | |
| 561 | (F(permitted) & cap_bset) | |
| 562 | ||
| 563 | P'(effective) = F(effective) ? P'(permitted) : 0 | |
| 564 | ||
| 565 | P'(inheritable) = P(inheritable) [i.e., unchanged] | |
| 566 | ||
| 567 | .fi | |
| 568 | .RE | |
| 569 | where: | |
| 570 | .RS 4 | |
| 571 | .IP P 10 | |
| 572 | denotes the value of a thread capability set before the | |
| 573 | .BR execve (2) | |
| 574 | .IP P' | |
| 575 | denotes the value of a capability set after the | |
| 576 | .BR execve (2) | |
| 577 | .IP F | |
| 578 | denotes a file capability set | |
| 579 | .IP cap_bset | |
| 580 | is the value of the capability bounding set (described below). | |
| 581 | .RE | |
| 582 | .\" | |
| 583 | .SS Capabilities and execution of programs by root | |
| 584 | In order to provide an all-powerful | |
| 585 | .I root | |
| 586 | using capability sets, during an | |
| 587 | .BR execve (2): | |
| 588 | .IP 1. 3 | |
| 589 | If a set-user-ID-root program is being executed, | |
| 590 | or the real user ID of the process is 0 (root) | |
| 591 | then the file inheritable and permitted sets are defined to be all ones | |
| 592 | (i.e., all capabilities enabled). | |
| 593 | .IP 2. | |
| 594 | If a set-user-ID-root program is being executed, | |
| 595 | then the file effective bit is defined to be one (enabled). | |
| 596 | .PP | |
| 597 | The upshot of the above rules, | |
| 598 | combined with the capabilities transformations described above, | |
| 599 | is that when a process | |
| 600 | .BR execve (2)s | |
| 601 | a set-user-ID-root program, or when a process with an effective UID of 0 | |
| 602 | .BR execve (2)s | |
| 603 | a program, | |
| 604 | it gains all capabilities in its permitted and effective capability sets, | |
| 605 | except those masked out by the capability bounding set. | |
| 606 | .\" If a process with real UID 0, and nonzero effective UID does an | |
| 607 | .\" exec(), then it gets all capabilities in its | |
| 608 | .\" permitted set, and no effective capabilities | |
| 609 | This provides semantics that are the same as those provided by | |
| 610 | traditional UNIX systems. | |
| 611 | .SS Capability bounding set | |
| 612 | The capability bounding set is a security mechanism that can be used | |
| 613 | to limit the capabilities that can be gained during an | |
| 614 | .BR execve (2). | |
| 615 | The bounding set is used in the following ways: | |
| 616 | .IP * 2 | |
| 617 | During an | |
| 618 | .BR execve (2), | |
| 619 | the capability bounding set is ANDed with the file permitted | |
| 620 | capability set, and the result of this operation is assigned to the | |
| 621 | thread's permitted capability set. | |
| 622 | The capability bounding set thus places a limit on the permitted | |
| 623 | capabilities that may be granted by an executable file. | |
| 624 | .IP * | |
| 625 | (Since Linux 2.6.25) | |
| 626 | The capability bounding set acts as a limiting superset for | |
| 627 | the capabilities that a thread can add to its inheritable set using | |
| 628 | .BR capset (2). | |
| 629 | This means that if a capability is not in the bounding set, | |
| 630 | then a thread can't add this capability to its | |
| 631 | inheritable set, even if it was in its permitted capabilities, | |
| 632 | and thereby cannot have this capability preserved in its | |
| 633 | permitted set when it | |
| 634 | .BR execve (2)s | |
| 635 | a file that has the capability in its inheritable set. | |
| 636 | .PP | |
| 637 | Note that the bounding set masks the file permitted capabilities, | |
| 638 | but not the inherited capabilities. | |
| 639 | If a thread maintains a capability in its inherited set | |
| 640 | that is not in its bounding set, | |
| 641 | then it can still gain that capability in its permitted set | |
| 642 | by executing a file that has the capability in its inherited set. | |
| 643 | .PP | |
| 644 | Depending on the kernel version, the capability bounding set is either | |
| 645 | a system-wide attribute, or a per-process attribute. | |
| 646 | .PP | |
| 647 | .B "Capability bounding set prior to Linux 2.6.25" | |
| 648 | .PP | |
| 649 | In kernels before 2.6.25, the capability bounding set is a system-wide | |
| 650 | attribute that affects all threads on the system. | |
| 651 | The bounding set is accessible via the file | |
| 652 | .IR /proc/sys/kernel/cap-bound . | |
| 653 | (Confusingly, this bit mask parameter is expressed as a | |
| 654 | signed decimal number in | |
| 655 | .IR /proc/sys/kernel/cap-bound .) | |
| 656 | ||
| 657 | Only the | |
| 658 | .B init | |
| 659 | process may set capabilities in the capability bounding set; | |
| 660 | other than that, the superuser (more precisely: programs with the | |
| 661 | .B CAP_SYS_MODULE | |
| 662 | capability) may only clear capabilities from this set. | |
| 663 | ||
| 664 | On a standard system the capability bounding set always masks out the | |
| 665 | .B CAP_SETPCAP | |
| 666 | capability. | |
| 667 | To remove this restriction (dangerous!), modify the definition of | |
| 668 | .B CAP_INIT_EFF_SET | |
| 669 | in | |
| 670 | .I include/linux/capability.h | |
| 671 | and rebuild the kernel. | |
| 672 | ||
| 673 | The system-wide capability bounding set feature was added | |
| 674 | to Linux starting with kernel version 2.2.11. | |
| 675 | .\" | |
| 676 | .PP | |
| 677 | .B "Capability bounding set from Linux 2.6.25 onward" | |
| 678 | .PP | |
| 679 | From Linux 2.6.25, the | |
| 680 | .I "capability bounding set" | |
| 681 | is a per-thread attribute. | |
| 682 | (There is no longer a system-wide capability bounding set.) | |
| 683 | ||
| 684 | The bounding set is inherited at | |
| 685 | .BR fork (2) | |
| 686 | from the thread's parent, and is preserved across an | |
| 687 | .BR execve (2). | |
| 688 | ||
| 689 | A thread may remove capabilities from its capability bounding set using the | |
| 690 | .BR prctl (2) | |
| 691 | .B PR_CAPBSET_DROP | |
| 692 | operation, provided it has the | |
| 693 | .B CAP_SETPCAP | |
| 694 | capability. | |
| 695 | Once a capability has been dropped from the bounding set, | |
| 696 | it cannot be restored to that set. | |
| 697 | A thread can determine if a capability is in its bounding set using the | |
| 698 | .BR prctl (2) | |
| 699 | .B PR_CAPBSET_READ | |
| 700 | operation. | |
| 701 | ||
| 702 | Removing capabilities from the bounding set is only supported if file | |
| 703 | capabilities are compiled into the kernel. | |
| 704 | In kernels before Linux 2.6.33, | |
| 705 | file capabilities were an optional feature configurable via the | |
| 706 | CONFIG_SECURITY_FILE_CAPABILITIES | |
| 707 | option. | |
| 708 | Since Linux 2.6.33, the configuration option has been removed | |
| 709 | and file capabilities are always part of the kernel. | |
| 710 | When file capabilities are compiled into the kernel, the | |
| 711 | .B init | |
| 712 | process (the ancestor of all processes) begins with a full bounding set. | |
| 713 | If file capabilities are not compiled into the kernel, then | |
| 714 | .B init | |
| 715 | begins with a full bounding set minus | |
| 716 | .BR CAP_SETPCAP , | |
| 717 | because this capability has a different meaning when there are | |
| 718 | no file capabilities. | |
| 719 | ||
| 720 | Removing a capability from the bounding set does not remove it | |
| 721 | from the thread's inherited set. | |
| 722 | However it does prevent the capability from being added | |
| 723 | back into the thread's inherited set in the future. | |
| 724 | .\" | |
| 725 | .\" | |
| 726 | .SS Effect of User ID Changes on Capabilities | |
| 727 | To preserve the traditional semantics for transitions between | |
| 728 | 0 and nonzero user IDs, | |
| 729 | the kernel makes the following changes to a thread's capability | |
| 730 | sets on changes to the thread's real, effective, saved set, | |
| 731 | and file system user IDs (using | |
| 732 | .BR setuid (2), | |
| 733 | .BR setresuid (2), | |
| 734 | or similar): | |
| 735 | .IP 1. 3 | |
| 736 | If one or more of the real, effective or saved set user IDs | |
| 737 | was previously 0, and as a result of the UID changes all of these IDs | |
| 738 | have a nonzero value, | |
| 739 | then all capabilities are cleared from the permitted and effective | |
| 740 | capability sets. | |
| 741 | .IP 2. | |
| 742 | If the effective user ID is changed from 0 to nonzero, | |
| 743 | then all capabilities are cleared from the effective set. | |
| 744 | .IP 3. | |
| 745 | If the effective user ID is changed from nonzero to 0, | |
| 746 | then the permitted set is copied to the effective set. | |
| 747 | .IP 4. | |
| 748 | If the file system user ID is changed from 0 to nonzero (see | |
| 749 | .BR setfsuid (2)) | |
| 750 | then the following capabilities are cleared from the effective set: | |
| 751 | .BR CAP_CHOWN , | |
| 752 | .BR CAP_DAC_OVERRIDE , | |
| 753 | .BR CAP_DAC_READ_SEARCH , | |
| 754 | .BR CAP_FOWNER , | |
| 755 | .BR CAP_FSETID , | |
| 756 | .B CAP_LINUX_IMMUTABLE | |
| 757 | (since Linux 2.2.30), | |
| 758 | .BR CAP_MAC_OVERRIDE , | |
| 759 | and | |
| 760 | .B CAP_MKNOD | |
| 761 | (since Linux 2.2.30). | |
| 762 | If the file system UID is changed from nonzero to 0, | |
| 763 | then any of these capabilities that are enabled in the permitted set | |
| 764 | are enabled in the effective set. | |
| 765 | .PP | |
| 766 | If a thread that has a 0 value for one or more of its user IDs wants | |
| 767 | to prevent its permitted capability set being cleared when it resets | |
| 768 | all of its user IDs to nonzero values, it can do so using the | |
| 769 | .BR prctl (2) | |
| 770 | .B PR_SET_KEEPCAPS | |
| 771 | operation. | |
| 772 | .\" | |
| 773 | .SS Programmatically adjusting capability sets | |
| 774 | A thread can retrieve and change its capability sets using the | |
| 775 | .BR capget (2) | |
| 776 | and | |
| 777 | .BR capset (2) | |
| 778 | system calls. | |
| 779 | However, the use of | |
| 780 | .BR cap_get_proc (3) | |
| 781 | and | |
| 782 | .BR cap_set_proc (3), | |
| 783 | both provided in the | |
| 784 | .I libcap | |
| 785 | package, | |
| 786 | is preferred for this purpose. | |
| 787 | The following rules govern changes to the thread capability sets: | |
| 788 | .IP 1. 3 | |
| 789 | If the caller does not have the | |
| 790 | .B CAP_SETPCAP | |
| 791 | capability, | |
| 792 | the new inheritable set must be a subset of the combination | |
| 793 | of the existing inheritable and permitted sets. | |
| 794 | .IP 2. | |
| 795 | (Since kernel 2.6.25) | |
| 796 | The new inheritable set must be a subset of the combination of the | |
| 797 | existing inheritable set and the capability bounding set. | |
| 798 | .IP 3. | |
| 799 | The new permitted set must be a subset of the existing permitted set | |
| 800 | (i.e., it is not possible to acquire permitted capabilities | |
| 801 | that the thread does not currently have). | |
| 802 | .IP 4. | |
| 803 | The new effective set must be a subset of the new permitted set. | |
| 804 | .SS The """securebits"" flags: establishing a capabilities-only environment | |
| 805 | .\" For some background: | |
| 806 | .\" see http://lwn.net/Articles/280279/ and | |
| 807 | .\" http://article.gmane.org/gmane.linux.kernel.lsm/5476/ | |
| 808 | Starting with kernel 2.6.26, | |
| 809 | and with a kernel in which file capabilities are enabled, | |
| 810 | Linux implements a set of per-thread | |
| 811 | .I securebits | |
| 812 | flags that can be used to disable special handling of capabilities for UID 0 | |
| 813 | .RI ( root ). | |
| 814 | These flags are as follows: | |
| 815 | .TP | |
| 816 | .B SECBIT_KEEP_CAPS | |
| 817 | Setting this flag allows a thread that has one or more 0 UIDs to retain | |
| 818 | its capabilities when it switches all of its UIDs to a nonzero value. | |
| 819 | If this flag is not set, | |
| 820 | then such a UID switch causes the thread to lose all capabilities. | |
| 821 | This flag is always cleared on an | |
| 822 | .BR execve (2). | |
| 823 | (This flag provides the same functionality as the older | |
| 824 | .BR prctl (2) | |
| 825 | .B PR_SET_KEEPCAPS | |
| 826 | operation.) | |
| 827 | .TP | |
| 828 | .B SECBIT_NO_SETUID_FIXUP | |
| 829 | Setting this flag stops the kernel from adjusting capability sets when | |
| 830 | the threads's effective and file system UIDs are switched between | |
| 831 | zero and nonzero values. | |
| 832 | (See the subsection | |
| 833 | .IR "Effect of User ID Changes on Capabilities" .) | |
| 834 | .TP | |
| 835 | .B SECBIT_NOROOT | |
| 836 | If this bit is set, then the kernel does not grant capabilities | |
| 837 | when a set-user-ID-root program is executed, or when a process with | |
| 838 | an effective or real UID of 0 calls | |
| 839 | .BR execve (2). | |
| 840 | (See the subsection | |
| 841 | .IR "Capabilities and execution of programs by root" .) | |
| 842 | .PP | |
| 843 | Each of the above "base" flags has a companion "locked" flag. | |
| 844 | Setting any of the "locked" flags is irreversible, | |
| 845 | and has the effect of preventing further changes to the | |
| 846 | corresponding "base" flag. | |
| 847 | The locked flags are: | |
| 848 | .BR SECBIT_KEEP_CAPS_LOCKED , | |
| 849 | .BR SECBIT_NO_SETUID_FIXUP_LOCKED , | |
| 850 | and | |
| 851 | .BR SECBIT_NOROOT_LOCKED . | |
| 852 | .PP | |
| 853 | The | |
| 854 | .I securebits | |
| 855 | flags can be modified and retrieved using the | |
| 856 | .BR prctl (2) | |
| 857 | .B PR_SET_SECUREBITS | |
| 858 | and | |
| 859 | .B PR_GET_SECUREBITS | |
| 860 | operations. | |
| 861 | The | |
| 862 | .B CAP_SETPCAP | |
| 863 | capability is required to modify the flags. | |
| 864 | ||
| 865 | The | |
| 866 | .I securebits | |
| 867 | flags are inherited by child processes. | |
| 868 | During an | |
| 869 | .BR execve (2), | |
| 870 | all of the flags are preserved, except | |
| 871 | .B SECBIT_KEEP_CAPS | |
| 872 | which is always cleared. | |
| 873 | ||
| 874 | An application can use the following call to lock itself, | |
| 875 | and all of its descendants, | |
| 876 | into an environment where the only way of gaining capabilities | |
| 877 | is by executing a program with associated file capabilities: | |
| 878 | .RS | |
| 879 | .nf | |
| 880 | ||
| 881 | prctl(PR_SET_SECUREBITS, | |
| 882 | SECBIT_KEEP_CAPS_LOCKED | | |
| 883 | SECBIT_NO_SETUID_FIXUP | | |
| 884 | SECBIT_NO_SETUID_FIXUP_LOCKED | | |
| 885 | SECBIT_NOROOT | | |
| 886 | SECBIT_NOROOT_LOCKED); | |
| 887 | .fi | |
| 888 | .RE | |
| 889 | .SH "CONFORMING TO" | |
| 890 | .PP | |
| 891 | No standards govern capabilities, but the Linux capability implementation | |
| 892 | is based on the withdrawn POSIX.1e draft standard; see | |
| 893 | .IR http://wt.xpilot.org/publications/posix.1e/ . | |
| 894 | .SH NOTES | |
| 895 | Since kernel 2.5.27, capabilities are an optional kernel component, | |
| 896 | and can be enabled/disabled via the CONFIG_SECURITY_CAPABILITIES | |
| 897 | kernel configuration option. | |
| 898 | ||
| 899 | The | |
| 900 | .I /proc/PID/task/TID/status | |
| 901 | file can be used to view the capability sets of a thread. | |
| 902 | The | |
| 903 | .I /proc/PID/status | |
| 904 | file shows the capability sets of a process's main thread. | |
| 905 | ||
| 906 | The | |
| 907 | .I libcap | |
| 908 | package provides a suite of routines for setting and | |
| 909 | getting capabilities that is more comfortable and less likely | |
| 910 | to change than the interface provided by | |
| 911 | .BR capset (2) | |
| 912 | and | |
| 913 | .BR capget (2). | |
| 914 | This package also provides the | |
| 915 | .BR setcap (8) | |
| 916 | and | |
| 917 | .BR getcap (8) | |
| 918 | programs. | |
| 919 | It can be found at | |
| 920 | .br | |
| 921 | .IR http://www.kernel.org/pub/linux/libs/security/linux-privs . | |
| 922 | ||
| 923 | Before kernel 2.6.24, and since kernel 2.6.24 if | |
| 924 | file capabilities are not enabled, a thread with the | |
| 925 | .B CAP_SETPCAP | |
| 926 | capability can manipulate the capabilities of threads other than itself. | |
| 927 | However, this is only theoretically possible, | |
| 928 | since no thread ever has | |
| 929 | .BR CAP_SETPCAP | |
| 930 | in either of these cases: | |
| 931 | .IP * 2 | |
| 932 | In the pre-2.6.25 implementation the system-wide capability bounding set, | |
| 933 | .IR /proc/sys/kernel/cap-bound , | |
| 934 | always masks out this capability, and this can not be changed | |
| 935 | without modifying the kernel source and rebuilding. | |
| 936 | .IP * | |
| 937 | If file capabilities are disabled in the current implementation, then | |
| 938 | .B init | |
| 939 | starts out with this capability removed from its per-process bounding | |
| 940 | set, and that bounding set is inherited by all other processes | |
| 941 | created on the system. | |
| 942 | .SH "SEE ALSO" | |
| 943 | .BR capget (2), | |
| 944 | .BR prctl (2), | |
| 945 | .BR setfsuid (2), | |
| 946 | .BR cap_clear (3), | |
| 947 | .BR cap_copy_ext (3), | |
| 948 | .BR cap_from_text (3), | |
| 949 | .BR cap_get_file (3), | |
| 950 | .BR cap_get_proc (3), | |
| 951 | .BR cap_init (3), | |
| 952 | .BR capgetp (3), | |
| 953 | .BR capsetp (3), | |
| 954 | .BR credentials (7), | |
| 955 | .BR pthreads (7), | |
| 956 | .BR getcap (8), | |
| 957 | .BR setcap (8) | |
| 958 | .PP | |
| 959 | .I include/linux/capability.h | |
| 960 | in the kernel source | |
| 961 | .SH COLOPHON | |
| 962 | This page is part of release 3.35 of the Linux | |
| 963 | .I man-pages | |
| 964 | project. | |
| 965 | A description of the project, | |
| 966 | and information about reporting bugs, | |
| 967 | can be found at | |
| 968 | http://man7.org/linux/man-pages/. |
| 0 | <?xml version="1.0" encoding="ISO-8859-1"?> | |
| 1 | <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" | |
| 2 | "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"> | |
| 3 | <!-- lifted from man+troff by doclifter --> | |
| 4 | <refentry> | |
| 5 | <!-- Copyright (c) 1995 Jim Van Zandt <jrv@vanzandt.mv.com> and aeb | |
| 6 | Sun Feb 26 11:46:23 MET 1995 --> | |
| 7 | ||
| 8 | <!-- This is free documentation; you can redistribute it and/or | |
| 9 | modify it under the terms of the GNU General Public License as | |
| 10 | published by the Free Software Foundation; either version 2 of | |
| 11 | the License, or (at your option) any later version. --> | |
| 12 | ||
| 13 | <!-- The GNU General Public License's references to "object code" | |
| 14 | and "executables" are to be interpreted as the output of any | |
| 15 | document formatting or typesetting system, including | |
| 16 | intermediate and printed output. --> | |
| 17 | ||
| 18 | <!-- This manual is distributed in the hope that it will be useful, | |
| 19 | but WITHOUT ANY WARRANTY; without even the implied warranty of | |
| 20 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
| 21 | GNU General Public License for more details. --> | |
| 22 | ||
| 23 | <!-- You should have received a copy of the GNU General Public | |
| 24 | License along with this manual; if not, write to the Free | |
| 25 | Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, | |
| 26 | USA. --> | |
| 27 | ||
| 28 | <!-- Modified, Sun Feb 26 15:04:20 1995, faith@cs.unc.edu | |
| 29 | Modified, Thu Apr 20 22:08:17 1995, jrv@vanzandt.mv.com | |
| 30 | Modified, Mon Sep 18 22:32:47 1995, hpa@storm.net (H. Peter Anvin) | |
| 31 | FIXME The following are not documented: | |
| 32 | KDFONTOP (since 2.1.111) | |
| 33 | KDGKBDIACRUC (since 2.6.24) | |
| 34 | KDSKBDIACR | |
| 35 | KDSKBDIACRUC (since 2.6.24) | |
| 36 | KDKBDREP (since 2.1.113) | |
| 37 | KDMAPDISP (not implemented as at 2.6.27) | |
| 38 | KDUNMAPDISP (not implemented as at 2.6.27) | |
| 39 | VT_LOCKSWITCH (since 1.3.47, needs CAP_SYS_TTY_CONFIG) | |
| 40 | VT_UNLOCKSWITCH (since 1.3.47, needs CAP_SYS_TTY_CONFIG) | |
| 41 | VT_GETHIFONTMASK (since 2.6.18) --> | |
| 42 | ||
| 43 | <refentryinfo><date>2009-02-28</date></refentryinfo> | |
| 44 | <refmeta> | |
| 45 | <refentrytitle>CONSOLE_IOCTL</refentrytitle> | |
| 46 | <manvolnum>4</manvolnum> | |
| 47 | <refmiscinfo class='date'>2009-02-28</refmiscinfo> | |
| 48 | <refmiscinfo class='source'>Linux</refmiscinfo> | |
| 49 | <refmiscinfo class='manual'>Linux Programmer's Manual</refmiscinfo> | |
| 50 | </refmeta> | |
| 51 | <refnamediv> | |
| 52 | <refname>console_ioctl</refname> | |
| 53 | <refpurpose>ioctl's for console terminal and virtual consoles</refpurpose> | |
| 54 | </refnamediv> | |
| 55 | <!-- body begins here --> | |
| 56 | ||
| 57 | <refsect1 id='description'><title>DESCRIPTION</title> | |
| 58 | <para>The following Linux-specific | |
| 59 | <citerefentry><refentrytitle>ioctl</refentrytitle><manvolnum>2</manvolnum></citerefentry> | |
| 60 | requests are supported. | |
| 61 | Each requires a third argument, assumed here to be <emphasis remap='I'>argp</emphasis>.</para> | |
| 62 | <variablelist remap='IP'> | |
| 63 | <varlistentry> | |
| 64 | <term><emphasis remap='B'>KDGETLED</emphasis></term> | |
| 65 | <listitem> | |
| 66 | <para>Get state of LEDs. | |
| 67 | <emphasis remap='I'>argp</emphasis> points to a <emphasis remap='I'>char</emphasis>. | |
| 68 | The lower three bits | |
| 69 | of <emphasis remap='I'>*argp</emphasis> are set to the state of the LEDs, as follows:</para> | |
| 70 | ||
| 71 | <informaltable pgwide='0' frame='none'> | |
| 72 | <tgroup cols='3' align='center'> | |
| 73 | <colspec colname='c1'/> | |
| 74 | <colspec colname='c2'/> | |
| 75 | <colspec colname='c3'/> | |
| 76 | <tbody> | |
| 77 | <row> | |
| 78 | <entry align='left'>LED_CAP </entry> | |
| 79 | <entry align='left'>0x04</entry> | |
| 80 | <entry align='left'>caps lock led</entry> | |
| 81 | </row> | |
| 82 | <row> | |
| 83 | <entry align='left'>LEC_NUM </entry> | |
| 84 | <entry align='left'>0x02</entry> | |
| 85 | <entry align='left'>num lock led</entry> | |
| 86 | </row> | |
| 87 | <row> | |
| 88 | <entry align='left'>LED_SCR </entry> | |
| 89 | <entry align='left'>0x01</entry> | |
| 90 | <entry align='left'>scroll lock led</entry> | |
| 91 | </row> | |
| 92 | </tbody> | |
| 93 | </tgroup> | |
| 94 | </informaltable> | |
| 95 | ||
| 96 | ||
| 97 | ||
| 98 | </listitem> | |
| 99 | </varlistentry> | |
| 100 | <varlistentry> | |
| 101 | <term><emphasis remap='B'>KDSETLED</emphasis></term> | |
| 102 | <listitem> | |
| 103 | <para>Set the LEDs. | |
| 104 | The LEDs are set to correspond to the lower three bits of | |
| 105 | <emphasis remap='I'>argp</emphasis>. | |
| 106 | However, if a higher order bit is set, | |
| 107 | the LEDs revert to normal: displaying the state of the | |
| 108 | keyboard functions of caps lock, num lock, and scroll lock.</para> | |
| 109 | ||
| 110 | <para>Before 1.1.54, the LEDs just reflected the state of the corresponding | |
| 111 | keyboard flags, and KDGETLED/KDSETLED would also change the keyboard | |
| 112 | flags. | |
| 113 | Since 1.1.54 the leds can be made to display arbitrary | |
| 114 | information, but by default they display the keyboard flags. | |
| 115 | The following two ioctl's are used to access the keyboard flags.</para> | |
| 116 | </listitem> | |
| 117 | </varlistentry> | |
| 118 | <varlistentry> | |
| 119 | <term><emphasis remap='B'>KDGKBLED</emphasis></term> | |
| 120 | <listitem> | |
| 121 | <para>Get keyboard flags CapsLock, NumLock, ScrollLock (not lights). | |
| 122 | <emphasis remap='I'>argp</emphasis> points to a char which is set to the flag state. | |
| 123 | The low order three bits (mask 0x7) get the current flag state, | |
| 124 | and the low order bits of the next nibble (mask 0x70) get | |
| 125 | the default flag state. | |
| 126 | (Since 1.1.54.)</para> | |
| 127 | </listitem> | |
| 128 | </varlistentry> | |
| 129 | <varlistentry> | |
| 130 | <term><emphasis remap='B'>KDSKBLED</emphasis></term> | |
| 131 | <listitem> | |
| 132 | <para>Set keyboard flags CapsLock, NumLock, ScrollLock (not lights). | |
| 133 | <emphasis remap='I'>argp</emphasis> has the desired flag state. | |
| 134 | The low order three bits (mask 0x7) have the flag state, | |
| 135 | and the low order bits of the next nibble (mask 0x70) have | |
| 136 | the default flag state. | |
| 137 | (Since 1.1.54.)</para> | |
| 138 | </listitem> | |
| 139 | </varlistentry> | |
| 140 | <varlistentry> | |
| 141 | <term><emphasis remap='B'>KDGKBTYPE</emphasis></term> | |
| 142 | <listitem> | |
| 143 | <para>Get keyboard type. | |
| 144 | This returns the value KB_101, defined as 0x02.</para> | |
| 145 | </listitem> | |
| 146 | </varlistentry> | |
| 147 | <varlistentry> | |
| 148 | <term><emphasis remap='B'>KDADDIO</emphasis></term> | |
| 149 | <listitem> | |
| 150 | <para>Add I/O port as valid. | |
| 151 | Equivalent to <emphasis remap='I'>ioperm(arg,1,1)</emphasis>.</para> | |
| 152 | </listitem> | |
| 153 | </varlistentry> | |
| 154 | <varlistentry> | |
| 155 | <term><emphasis remap='B'>KDDELIO</emphasis></term> | |
| 156 | <listitem> | |
| 157 | <para>Delete I/O port as valid. | |
| 158 | Equivalent to <emphasis remap='I'>ioperm(arg,1,0)</emphasis>.</para> | |
| 159 | </listitem> | |
| 160 | </varlistentry> | |
| 161 | <varlistentry> | |
| 162 | <term><emphasis remap='B'>KDENABIO</emphasis></term> | |
| 163 | <listitem> | |
| 164 | <para>Enable I/O to video board. | |
| 165 | Equivalent to <emphasis remap='I'>ioperm(0x3b4, 0x3df-0x3b4+1, 1)</emphasis>.</para> | |
| 166 | </listitem> | |
| 167 | </varlistentry> | |
| 168 | <varlistentry> | |
| 169 | <term><emphasis remap='B'>KDDISABIO</emphasis></term> | |
| 170 | <listitem> | |
| 171 | <para>Disable I/O to video board. | |
| 172 | Equivalent to <emphasis remap='I'>ioperm(0x3b4, 0x3df-0x3b4+1, 0)</emphasis>.</para> | |
| 173 | </listitem> | |
| 174 | </varlistentry> | |
| 175 | <varlistentry> | |
| 176 | <term><emphasis remap='B'>KDSETMODE</emphasis></term> | |
| 177 | <listitem> | |
| 178 | <para>Set text/graphics mode. | |
| 179 | <emphasis remap='I'>argp</emphasis> is one of these:</para> | |
| 180 | ||
| 181 | <informaltable pgwide='0' frame='none'> | |
| 182 | <tgroup cols='2' align='center'> | |
| 183 | <colspec colname='c1'/> | |
| 184 | <colspec colname='c2'/> | |
| 185 | <tbody> | |
| 186 | <row> | |
| 187 | <entry align='left'>KD_TEXT </entry> | |
| 188 | <entry align='left'>0x00</entry> | |
| 189 | </row> | |
| 190 | <row> | |
| 191 | <entry align='left'>KD_GRAPHICS</entry> | |
| 192 | <entry align='left'>0x01</entry> | |
| 193 | </row> | |
| 194 | </tbody> | |
| 195 | </tgroup> | |
| 196 | </informaltable> | |
| 197 | ||
| 198 | ||
| 199 | ||
| 200 | </listitem> | |
| 201 | </varlistentry> | |
| 202 | <varlistentry> | |
| 203 | <term><emphasis remap='B'>KDGETMODE</emphasis></term> | |
| 204 | <listitem> | |
| 205 | <para>Get text/graphics mode. | |
| 206 | <emphasis remap='I'>argp</emphasis> points to a <emphasis remap='I'>long</emphasis> which is set to one | |
| 207 | of the above values.</para> | |
| 208 | </listitem> | |
| 209 | </varlistentry> | |
| 210 | <varlistentry> | |
| 211 | <term><emphasis remap='B'>KDMKTONE</emphasis></term> | |
| 212 | <listitem> | |
| 213 | <para>Generate tone of specified length. | |
| 214 | The lower 16 bits of <emphasis remap='I'>argp</emphasis> specify the period in clock cycles, | |
| 215 | and the upper 16 bits give the duration in msec. | |
| 216 | If the duration is zero, the sound is turned off. | |
| 217 | Control returns immediately. | |
| 218 | For example, <emphasis remap='I'>argp</emphasis> = (125<<16) + 0x637 would specify | |
| 219 | the beep normally associated with a ctrl-G. | |
| 220 | (Thus since 0.99pl1; broken in 2.1.49-50.)</para> | |
| 221 | </listitem> | |
| 222 | </varlistentry> | |
| 223 | <varlistentry> | |
| 224 | <term><emphasis remap='B'>KIOCSOUND</emphasis></term> | |
| 225 | <listitem> | |
| 226 | <para>Start or stop sound generation. | |
| 227 | The lower 16 bits of | |
| 228 | <emphasis remap='I'>argp</emphasis> specify the period in clock cycles | |
| 229 | (that is, <emphasis remap='I'>argp</emphasis> = 1193180/frequency). | |
| 230 | <emphasis remap='I'>argp</emphasis> = 0 turns sound off. | |
| 231 | In either case, control returns immediately.</para> | |
| 232 | </listitem> | |
| 233 | </varlistentry> | |
| 234 | <varlistentry> | |
| 235 | <term><emphasis remap='B'>GIO_CMAP</emphasis></term> | |
| 236 | <listitem> | |
| 237 | <para>Get the current default color map from kernel. | |
| 238 | <emphasis remap='I'>argp</emphasis> points to | |
| 239 | a 48-byte array. | |
| 240 | (Since 1.3.3.)</para> | |
| 241 | </listitem> | |
| 242 | </varlistentry> | |
| 243 | <varlistentry> | |
| 244 | <term><emphasis remap='B'>PIO_CMAP</emphasis></term> | |
| 245 | <listitem> | |
| 246 | <para>Change the default text-mode color map. | |
| 247 | <emphasis remap='I'>argp</emphasis> points to a | |
| 248 | 48-byte array which contains, in order, the Red, Green, and Blue | |
| 249 | values for the 16 available screen colors: 0 is off, and 255 is full | |
| 250 | intensity. | |
| 251 | The default colors are, in order: black, dark red, dark | |
| 252 | green, brown, dark blue, dark purple, dark cyan, light grey, dark | |
| 253 | grey, bright red, bright green, yellow, bright blue, bright purple, | |
| 254 | bright cyan and white. | |
| 255 | (Since 1.3.3.)</para> | |
| 256 | </listitem> | |
| 257 | </varlistentry> | |
| 258 | <varlistentry> | |
| 259 | <term><emphasis remap='B'>GIO_FONT</emphasis></term> | |
| 260 | <listitem> | |
| 261 | <para>Gets 256-character screen font in expanded form. | |
| 262 | <emphasis remap='I'>argp</emphasis> points to an 8192 byte array. | |
| 263 | Fails with error code <errorcode>EINVAL</errorcode> if the | |
| 264 | currently loaded font is a 512-character font, or if the console is | |
| 265 | not in text mode.</para> | |
| 266 | </listitem> | |
| 267 | </varlistentry> | |
| 268 | <varlistentry> | |
| 269 | <term><emphasis remap='B'>GIO_FONTX</emphasis></term> | |
| 270 | <listitem> | |
| 271 | <para>Gets screen font and associated information. | |
| 272 | <emphasis remap='I'>argp</emphasis> points to a | |
| 273 | <emphasis remap='I'>struct consolefontdesc</emphasis> (see <emphasis remap='B'>PIO_FONTX</emphasis>). | |
| 274 | On call, the | |
| 275 | <emphasis remap='I'>charcount</emphasis> field should be set to the maximum number of | |
| 276 | characters that would fit in the buffer pointed to by <emphasis remap='I'>chardata</emphasis>. | |
| 277 | On return, the <emphasis remap='I'>charcount</emphasis> and <emphasis remap='I'>charheight</emphasis> are filled with | |
| 278 | the respective data for the currently loaded font, and the | |
| 279 | <emphasis remap='I'>chardata</emphasis> array contains the font data if the initial value of | |
| 280 | <emphasis remap='I'>charcount</emphasis> indicated enough space was available; otherwise the | |
| 281 | buffer is untouched and <varname>errno</varname> is set to <errorcode>ENOMEM</errorcode>. | |
| 282 | (Since 1.3.1.)</para> | |
| 283 | </listitem> | |
| 284 | </varlistentry> | |
| 285 | <varlistentry> | |
| 286 | <term><emphasis remap='B'>PIO_FONT</emphasis></term> | |
| 287 | <listitem> | |
| 288 | <para>Sets 256-character screen font. | |
| 289 | Load font into the EGA/VGA character | |
| 290 | generator. | |
| 291 | <emphasis remap='I'>argp</emphasis> points to a 8192 byte map, with 32 bytes per | |
| 292 | character. | |
| 293 | Only first <emphasis remap='I'>N</emphasis> of them are used for an 8x<emphasis remap='I'>N</emphasis> font | |
| 294 | (0 < <emphasis remap='I'>N</emphasis> <= 32). | |
| 295 | This call also invalidates the Unicode mapping.</para> | |
| 296 | </listitem> | |
| 297 | </varlistentry> | |
| 298 | <varlistentry> | |
| 299 | <term><emphasis remap='B'>PIO_FONTX</emphasis></term> | |
| 300 | <listitem> | |
| 301 | <para>Sets screen font and associated rendering information. | |
| 302 | <emphasis remap='I'>argp</emphasis> | |
| 303 | points to a</para> | |
| 304 | ||
| 305 | <programlisting remap='.nf .ft CW'> | |
| 306 | struct consolefontdesc { | |
| 307 | unsigned short charcount; /* characters in font | |
| 308 | (256 or 512) */ | |
| 309 | unsigned short charheight; /* scan lines per | |
| 310 | character (1-32) */ | |
| 311 | char *chardata; /* font data in | |
| 312 | expanded form */ | |
| 313 | }; | |
| 314 | </programlisting> <!-- .fi --> | |
| 315 | ||
| 316 | <para>If necessary, the screen will be appropriately resized, and | |
| 317 | <constant>SIGWINCH</constant> sent to the appropriate processes. | |
| 318 | This call also invalidates the Unicode mapping. | |
| 319 | (Since 1.3.1.)</para> | |
| 320 | </listitem> | |
| 321 | </varlistentry> | |
| 322 | <varlistentry> | |
| 323 | <term><emphasis remap='B'>PIO_FONTRESET</emphasis></term> | |
| 324 | <listitem> | |
| 325 | <para>Resets the screen font, size and Unicode mapping to the bootup | |
| 326 | defaults. | |
| 327 | <emphasis remap='I'>argp</emphasis> is unused, but should be set to NULL to | |
| 328 | ensure compatibility with future versions of Linux. | |
| 329 | (Since 1.3.28.)</para> | |
| 330 | </listitem> | |
| 331 | </varlistentry> | |
| 332 | <varlistentry> | |
| 333 | <term><emphasis remap='B'>GIO_SCRNMAP</emphasis></term> | |
| 334 | <listitem> | |
| 335 | <para>Get screen mapping from kernel. | |
| 336 | <emphasis remap='I'>argp</emphasis> points to an area of size | |
| 337 | E_TABSZ, which is loaded with the font positions used to display each | |
| 338 | character. | |
| 339 | This call is likely to return useless information if the | |
| 340 | currently loaded font is more than 256 characters.</para> | |
| 341 | </listitem> | |
| 342 | </varlistentry> | |
| 343 | <varlistentry> | |
| 344 | <term><emphasis remap='B'>GIO_UNISCRNMAP</emphasis></term> | |
| 345 | <listitem> | |
| 346 | <para>Get full Unicode screen mapping from kernel. | |
| 347 | <emphasis remap='I'>argp</emphasis> points to an | |
| 348 | area of size E_TABSZ*sizeof(unsigned short), which is loaded with the | |
| 349 | Unicodes each character represent. | |
| 350 | A special set of Unicodes, | |
| 351 | starting at U+F000, are used to represent "direct to font" mappings. | |
| 352 | (Since 1.3.1.)</para> | |
| 353 | </listitem> | |
| 354 | </varlistentry> | |
| 355 | <varlistentry> | |
| 356 | <term><emphasis remap='B'>PIO_SCRNMAP</emphasis></term> | |
| 357 | <listitem> | |
| 358 | <para>Loads the "user definable" (fourth) table in the kernel which maps | |
| 359 | bytes into console screen symbols. | |
| 360 | <emphasis remap='I'>argp</emphasis> points to an area of | |
| 361 | size E_TABSZ.</para> | |
| 362 | </listitem> | |
| 363 | </varlistentry> | |
| 364 | <varlistentry> | |
| 365 | <term><emphasis remap='B'>PIO_UNISCRNMAP</emphasis></term> | |
| 366 | <listitem> | |
| 367 | <para>Loads the "user definable" (fourth) table in the kernel which maps | |
| 368 | bytes into Unicodes, which are then translated into screen symbols | |
| 369 | according to the currently loaded Unicode-to-font map. | |
| 370 | Special Unicodes starting at U+F000 can be used to map directly to the font | |
| 371 | symbols. | |
| 372 | (Since 1.3.1.)</para> | |
| 373 | </listitem> | |
| 374 | </varlistentry> | |
| 375 | <varlistentry> | |
| 376 | <term><emphasis remap='B'>GIO_UNIMAP</emphasis></term> | |
| 377 | <listitem> | |
| 378 | <para>Get Unicode-to-font mapping from kernel. | |
| 379 | <emphasis remap='I'>argp</emphasis> points to a</para> | |
| 380 | ||
| 381 | <programlisting remap='.nf .ft CW'> | |
| 382 | struct unimapdesc { | |
| 383 | unsigned short entry_ct; | |
| 384 | struct unipair *entries; | |
| 385 | }; | |
| 386 | </programlisting> <!-- .fi --> | |
| 387 | ||
| 388 | <para>where <emphasis remap='I'>entries</emphasis> points to an array of</para> | |
| 389 | ||
| 390 | <programlisting remap='.nf .ft CW'> | |
| 391 | struct unipair { | |
| 392 | unsigned short unicode; | |
| 393 | unsigned short fontpos; | |
| 394 | }; | |
| 395 | </programlisting> <!-- .fi --> | |
| 396 | ||
| 397 | <para>(Since 1.1.92.)</para> | |
| 398 | </listitem> | |
| 399 | </varlistentry> | |
| 400 | <varlistentry> | |
| 401 | <term><emphasis remap='B'>PIO_UNIMAP</emphasis></term> | |
| 402 | <listitem> | |
| 403 | <para>Put unicode-to-font mapping in kernel. | |
| 404 | <emphasis remap='I'>argp</emphasis> points to a | |
| 405 | <emphasis remap='I'>struct unimapdesc</emphasis>. | |
| 406 | (Since 1.1.92)</para> | |
| 407 | </listitem> | |
| 408 | </varlistentry> | |
| 409 | <varlistentry> | |
| 410 | <term><emphasis remap='B'>PIO_UNIMAPCLR</emphasis></term> | |
| 411 | <listitem> | |
| 412 | <para>Clear table, possibly advise hash algorithm. | |
| 413 | <emphasis remap='I'>argp</emphasis> points to a</para> | |
| 414 | ||
| 415 | <programlisting remap='.nf .ft CW'> | |
| 416 | struct unimapinit { | |
| 417 | unsigned short advised_hashsize; /* 0 if no opinion */ | |
| 418 | unsigned short advised_hashstep; /* 0 if no opinion */ | |
| 419 | unsigned short advised_hashlevel; /* 0 if no opinion */ | |
| 420 | }; | |
| 421 | </programlisting> <!-- .fi --> | |
| 422 | ||
| 423 | <para>(Since 1.1.92.)</para> | |
| 424 | </listitem> | |
| 425 | </varlistentry> | |
| 426 | <varlistentry> | |
| 427 | <term><emphasis remap='B'>KDGKBMODE</emphasis></term> | |
| 428 | <listitem> | |
| 429 | <para>Gets current keyboard mode. | |
| 430 | <emphasis remap='I'>argp</emphasis> points to a <emphasis remap='I'>long</emphasis> which is set to one | |
| 431 | of these:</para> | |
| 432 | ||
| 433 | <informaltable pgwide='0' frame='none'> | |
| 434 | <tgroup cols='2' align='center'> | |
| 435 | <colspec colname='c1'/> | |
| 436 | <colspec colname='c2'/> | |
| 437 | <tbody> | |
| 438 | <row> | |
| 439 | <entry align='left'>K_RAW </entry> | |
| 440 | <entry align='left'>0x00</entry> | |
| 441 | </row> | |
| 442 | <row> | |
| 443 | <entry align='left'>K_XLATE </entry> | |
| 444 | <entry align='left'>0x01</entry> | |
| 445 | </row> | |
| 446 | <row> | |
| 447 | <entry align='left'>K_MEDIUMRAW</entry> | |
| 448 | <entry align='left'>0x02</entry> | |
| 449 | </row> | |
| 450 | <row> | |
| 451 | <entry align='left'>K_UNICODE </entry> | |
| 452 | <entry align='left'>0x03</entry> | |
| 453 | </row> | |
| 454 | </tbody> | |
| 455 | </tgroup> | |
| 456 | </informaltable> | |
| 457 | ||
| 458 | ||
| 459 | ||
| 460 | </listitem> | |
| 461 | </varlistentry> | |
| 462 | <varlistentry> | |
| 463 | <term><emphasis remap='B'>KDSKBMODE</emphasis></term> | |
| 464 | <listitem> | |
| 465 | <para>Sets current keyboard mode. | |
| 466 | <emphasis remap='I'>argp</emphasis> is a <emphasis remap='I'>long</emphasis> equal to one of the above values.</para> | |
| 467 | </listitem> | |
| 468 | </varlistentry> | |
| 469 | <varlistentry> | |
| 470 | <term><emphasis remap='B'>KDGKBMETA</emphasis></term> | |
| 471 | <listitem> | |
| 472 | <para>Gets meta key handling mode. | |
| 473 | <emphasis remap='I'>argp</emphasis> points to a <emphasis remap='I'>long</emphasis> which is | |
| 474 | set to one of these:</para> | |
| 475 | ||
| 476 | <informaltable pgwide='0' frame='none'> | |
| 477 | <tgroup cols='3' align='center'> | |
| 478 | <colspec colname='c1'/> | |
| 479 | <colspec colname='c2'/> | |
| 480 | <colspec colname='c3'/> | |
| 481 | <tbody> | |
| 482 | <row> | |
| 483 | <entry align='left'>K_METABIT </entry> | |
| 484 | <entry align='left'>0x03</entry> | |
| 485 | <entry align='left'>set high order bit</entry> | |
| 486 | </row> | |
| 487 | <row> | |
| 488 | <entry align='left'>K_ESCPREFIX</entry> | |
| 489 | <entry align='left'>0x04</entry> | |
| 490 | <entry align='left'>escape prefix</entry> | |
| 491 | </row> | |
| 492 | </tbody> | |
| 493 | </tgroup> | |
| 494 | </informaltable> | |
| 495 | ||
| 496 | ||
| 497 | ||
| 498 | </listitem> | |
| 499 | </varlistentry> | |
| 500 | <varlistentry> | |
| 501 | <term><emphasis remap='B'>KDSKBMETA</emphasis></term> | |
| 502 | <listitem> | |
| 503 | <para>Sets meta key handling mode. | |
| 504 | <emphasis remap='I'>argp</emphasis> is a <emphasis remap='I'>long</emphasis> equal to one of the above values.</para> | |
| 505 | </listitem> | |
| 506 | </varlistentry> | |
| 507 | <varlistentry> | |
| 508 | <term><emphasis remap='B'>KDGKBENT</emphasis></term> | |
| 509 | <listitem> | |
| 510 | <para>Gets one entry in key translation table (keycode to action code). | |
| 511 | <emphasis remap='I'>argp</emphasis> points to a</para> | |
| 512 | ||
| 513 | <programlisting remap='.nf .ft CW'> | |
| 514 | struct kbentry { | |
| 515 | unsigned char kb_table; | |
| 516 | unsigned char kb_index; | |
| 517 | unsigned short kb_value; | |
| 518 | }; | |
| 519 | </programlisting> <!-- .fi --> | |
| 520 | ||
| 521 | <para>with the first two members filled in: | |
| 522 | <emphasis remap='I'>kb_table</emphasis> selects the key table (0 <= <emphasis remap='I'>kb_table</emphasis> < MAX_NR_KEYMAPS), | |
| 523 | and <emphasis remap='I'>kb_index</emphasis> is the keycode (0 <= <emphasis remap='I'>kb_index</emphasis> < NR_KEYS). | |
| 524 | <emphasis remap='I'>kb_value</emphasis> is set to the corresponding action code, | |
| 525 | or K_HOLE if there is no such key, | |
| 526 | or K_NOSUCHMAP if <emphasis remap='I'>kb_table</emphasis> is invalid.</para> | |
| 527 | </listitem> | |
| 528 | </varlistentry> | |
| 529 | <varlistentry> | |
| 530 | <term><emphasis remap='B'>KDSKBENT</emphasis></term> | |
| 531 | <listitem> | |
| 532 | <para>Sets one entry in translation table. | |
| 533 | <emphasis remap='I'>argp</emphasis> points to | |
| 534 | a <emphasis remap='I'>struct kbentry</emphasis>.</para> | |
| 535 | </listitem> | |
| 536 | </varlistentry> | |
| 537 | <varlistentry> | |
| 538 | <term><emphasis remap='B'>KDGKBSENT</emphasis></term> | |
| 539 | <listitem> | |
| 540 | <para>Gets one function key string. | |
| 541 | <emphasis remap='I'>argp</emphasis> points to a</para> | |
| 542 | ||
| 543 | <programlisting remap='.nf .ft CW'> | |
| 544 | struct kbsentry { | |
| 545 | unsigned char kb_func; | |
| 546 | unsigned char kb_string[512]; | |
| 547 | }; | |
| 548 | </programlisting> <!-- .fi --> | |
| 549 | ||
| 550 | <para><emphasis remap='I'>kb_string</emphasis> is set to the (null-terminated) string corresponding to | |
| 551 | the <emphasis remap='I'>kb_func</emphasis>th function key action code.</para> | |
| 552 | </listitem> | |
| 553 | </varlistentry> | |
| 554 | <varlistentry> | |
| 555 | <term><emphasis remap='B'>KDSKBSENT</emphasis></term> | |
| 556 | <listitem> | |
| 557 | <para>Sets one function key string entry. | |
| 558 | <emphasis remap='I'>argp</emphasis> points to | |
| 559 | a <emphasis remap='I'>struct kbsentry</emphasis>.</para> | |
| 560 | </listitem> | |
| 561 | </varlistentry> | |
| 562 | <varlistentry> | |
| 563 | <term><emphasis remap='B'>KDGKBDIACR</emphasis></term> | |
| 564 | <listitem> | |
| 565 | <para>Read kernel accent table. | |
| 566 | <emphasis remap='I'>argp</emphasis> points to a</para> | |
| 567 | ||
| 568 | <programlisting remap='.nf .ft CW'> | |
| 569 | struct kbdiacrs { | |
| 570 | unsigned int kb_cnt; | |
| 571 | struct kbdiacr kbdiacr[256]; | |
| 572 | }; | |
| 573 | </programlisting> <!-- .fi --> | |
| 574 | ||
| 575 | <para>where <emphasis remap='I'>kb_cnt</emphasis> is the number of entries in the array, each of which | |
| 576 | is a</para> | |
| 577 | ||
| 578 | <programlisting remap='.nf .ft CW'> | |
| 579 | struct kbdiacr { | |
| 580 | unsigned char diacr; | |
| 581 | unsigned char base; | |
| 582 | unsigned char result; | |
| 583 | }; | |
| 584 | </programlisting> <!-- .fi --> | |
| 585 | </listitem> | |
| 586 | </varlistentry> | |
| 587 | <varlistentry> | |
| 588 | <term><emphasis remap='B'>KDGETKEYCODE</emphasis></term> | |
| 589 | <listitem> | |
| 590 | <para>Read kernel keycode table entry (scan code to keycode). | |
| 591 | <emphasis remap='I'>argp</emphasis> points to a</para> | |
| 592 | ||
| 593 | <programlisting remap='.nf .ft CW'> | |
| 594 | struct kbkeycode { | |
| 595 | unsigned int scancode; | |
| 596 | unsigned int keycode; | |
| 597 | }; | |
| 598 | </programlisting> <!-- .fi --> | |
| 599 | ||
| 600 | <para><emphasis remap='I'>keycode</emphasis> is set to correspond to the given <emphasis remap='I'>scancode</emphasis>. | |
| 601 | (89 <= <emphasis remap='I'>scancode</emphasis> <= 255 only. | |
| 602 | For 1 <= <emphasis remap='I'>scancode</emphasis> <= 88, <emphasis remap='I'>keycode</emphasis>==<emphasis remap='I'>scancode</emphasis>.) | |
| 603 | (Since 1.1.63.)</para> | |
| 604 | </listitem> | |
| 605 | </varlistentry> | |
| 606 | <varlistentry> | |
| 607 | <term><emphasis remap='B'>KDSETKEYCODE</emphasis></term> | |
| 608 | <listitem> | |
| 609 | <para>Write kernel keycode table entry. | |
| 610 | <emphasis remap='I'>argp</emphasis> points to | |
| 611 | a <emphasis remap='I'>struct kbkeycode</emphasis>. | |
| 612 | (Since 1.1.63.)</para> | |
| 613 | </listitem> | |
| 614 | </varlistentry> | |
| 615 | <varlistentry> | |
| 616 | <term><emphasis remap='B'>KDSIGACCEPT</emphasis></term> | |
| 617 | <listitem> | |
| 618 | <para>The calling process indicates its willingness to accept the signal | |
| 619 | <emphasis remap='I'>argp</emphasis> when it is generated by pressing an appropriate key combination. | |
| 620 | (1 <= <emphasis remap='I'>argp</emphasis> <= NSIG). | |
| 621 | (See spawn_console() in linux/drivers/char/keyboard.c.)</para> | |
| 622 | </listitem> | |
| 623 | </varlistentry> | |
| 624 | <varlistentry> | |
| 625 | <term><emphasis remap='B'>VT_OPENQRY</emphasis></term> | |
| 626 | <listitem> | |
| 627 | <para>Returns the first available (non-opened) console. | |
| 628 | <emphasis remap='I'>argp</emphasis> points to an <emphasis remap='I'>int</emphasis> which is set to the | |
| 629 | number of the vt (1 <= <emphasis remap='I'>*argp</emphasis> <= MAX_NR_CONSOLES).</para> | |
| 630 | </listitem> | |
| 631 | </varlistentry> | |
| 632 | <varlistentry> | |
| 633 | <term><emphasis remap='B'>VT_GETMODE</emphasis></term> | |
| 634 | <listitem> | |
| 635 | <para>Get mode of active vt. | |
| 636 | <emphasis remap='I'>argp</emphasis> points to a</para> | |
| 637 | ||
| 638 | <programlisting remap='.nf .ft CW'> | |
| 639 | struct vt_mode { | |
| 640 | char mode; /* vt mode */ | |
| 641 | char waitv; /* if set, hang on writes if not active */ | |
| 642 | short relsig; /* signal to raise on release req */ | |
| 643 | short acqsig; /* signal to raise on acquisition */ | |
| 644 | short frsig; /* unused (set to 0) */ | |
| 645 | }; | |
| 646 | </programlisting> <!-- .fi --> | |
| 647 | ||
| 648 | <para>which is set to the mode of the active vt. | |
| 649 | <emphasis remap='I'>mode</emphasis> is set to one of these values:</para> | |
| 650 | ||
| 651 | <informaltable pgwide='0' frame='none'> | |
| 652 | <tgroup cols='2' align='center'> | |
| 653 | <colspec colname='c1'/> | |
| 654 | <colspec colname='c2'/> | |
| 655 | <tbody> | |
| 656 | <row> | |
| 657 | <entry align='left'>VT_AUTO </entry> | |
| 658 | <entry align='left'>auto vt switching</entry> | |
| 659 | </row> | |
| 660 | <row> | |
| 661 | <entry align='left'>VT_PROCESS</entry> | |
| 662 | <entry align='left'>process controls switching</entry> | |
| 663 | </row> | |
| 664 | <row> | |
| 665 | <entry align='left'>VT_ACKACQ </entry> | |
| 666 | <entry align='left'>acknowledge switch</entry> | |
| 667 | </row> | |
| 668 | </tbody> | |
| 669 | </tgroup> | |
| 670 | </informaltable> | |
| 671 | ||
| 672 | ||
| 673 | ||
| 674 | </listitem> | |
| 675 | </varlistentry> | |
| 676 | <varlistentry> | |
| 677 | <term><emphasis remap='B'>VT_SETMODE</emphasis></term> | |
| 678 | <listitem> | |
| 679 | <para>Set mode of active vt. | |
| 680 | <emphasis remap='I'>argp</emphasis> points to | |
| 681 | a <emphasis remap='I'>struct vt_mode</emphasis>.</para> | |
| 682 | </listitem> | |
| 683 | </varlistentry> | |
| 684 | <varlistentry> | |
| 685 | <term><emphasis remap='B'>VT_GETSTATE</emphasis></term> | |
| 686 | <listitem> | |
| 687 | <para>Get global vt state info. | |
| 688 | <emphasis remap='I'>argp</emphasis> points to a</para> | |
| 689 | ||
| 690 | <programlisting remap='.nf .ft CW'> | |
| 691 | struct vt_stat { | |
| 692 | unsigned short v_active; /* active vt */ | |
| 693 | unsigned short v_signal; /* signal to send */ | |
| 694 | unsigned short v_state; /* vt bit mask */ | |
| 695 | }; | |
| 696 | </programlisting> <!-- .fi --> | |
| 697 | ||
| 698 | <para>For each vt in use, the corresponding bit in the <emphasis remap='I'>v_state</emphasis> member is set. | |
| 699 | (Kernels 1.0 through 1.1.92.)</para> | |
| 700 | </listitem> | |
| 701 | </varlistentry> | |
| 702 | <varlistentry> | |
| 703 | <term><emphasis remap='B'>VT_RELDISP</emphasis></term> | |
| 704 | <listitem> | |
| 705 | <para>Release a display.</para> | |
| 706 | </listitem> | |
| 707 | </varlistentry> | |
| 708 | <varlistentry> | |
| 709 | <term><emphasis remap='B'>VT_ACTIVATE</emphasis></term> | |
| 710 | <listitem> | |
| 711 | <para>Switch to vt <emphasis remap='I'>argp</emphasis> (1 <= <emphasis remap='I'>argp</emphasis> <= MAX_NR_CONSOLES).</para> | |
| 712 | </listitem> | |
| 713 | </varlistentry> | |
| 714 | <varlistentry> | |
| 715 | <term><emphasis remap='B'>VT_WAITACTIVE</emphasis></term> | |
| 716 | <listitem> | |
| 717 | <para>Wait until vt <emphasis remap='I'>argp</emphasis> has been activated.</para> | |
| 718 | </listitem> | |
| 719 | </varlistentry> | |
| 720 | <varlistentry> | |
| 721 | <term><emphasis remap='B'>VT_DISALLOCATE</emphasis></term> | |
| 722 | <listitem> | |
| 723 | <para>Deallocate the memory associated with vt <emphasis remap='I'>argp</emphasis>. | |
| 724 | (Since 1.1.54.)</para> | |
| 725 | </listitem> | |
| 726 | </varlistentry> | |
| 727 | <varlistentry> | |
| 728 | <term><emphasis remap='B'>VT_RESIZE</emphasis></term> | |
| 729 | <listitem> | |
| 730 | <para>Set the kernel's idea of screensize. | |
| 731 | <emphasis remap='I'>argp</emphasis> points to a</para> | |
| 732 | ||
| 733 | <programlisting remap='.nf .ft CW'> | |
| 734 | struct vt_sizes { | |
| 735 | unsigned short v_rows; /* # rows */ | |
| 736 | unsigned short v_cols; /* # columns */ | |
| 737 | unsigned short v_scrollsize; /* no longer used */ | |
| 738 | }; | |
| 739 | </programlisting> <!-- .fi --> | |
| 740 | ||
| 741 | <para>Note that this does not change the videomode. | |
| 742 | See | |
| 743 | <citerefentry><refentrytitle>resizecons</refentrytitle><manvolnum>8</manvolnum></citerefentry>. | |
| 744 | (Since 1.1.54.)</para> | |
| 745 | </listitem> | |
| 746 | </varlistentry> | |
| 747 | <varlistentry> | |
| 748 | <term><emphasis remap='B'>VT_RESIZEX</emphasis></term> | |
| 749 | <listitem> | |
| 750 | <para>Set the kernel's idea of various screen parameters. | |
| 751 | <emphasis remap='I'>argp</emphasis> points to a</para> | |
| 752 | ||
| 753 | <programlisting remap='.nf .ft CW'> | |
| 754 | struct vt_consize { | |
| 755 | unsigned short v_rows; /* number of rows */ | |
| 756 | unsigned short v_cols; /* number of columns */ | |
| 757 | unsigned short v_vlin; /* number of pixel rows | |
| 758 | on screen */ | |
| 759 | unsigned short v_clin; /* number of pixel rows | |
| 760 | per character */ | |
| 761 | unsigned short v_vcol; /* number of pixel columns | |
| 762 | on screen */ | |
| 763 | unsigned short v_ccol; /* number of pixel columns | |
| 764 | per character */ | |
| 765 | }; | |
| 766 | </programlisting> <!-- .fi --> | |
| 767 | ||
| 768 | <para>Any parameter may be set to zero, indicating "no change", but if | |
| 769 | multiple parameters are set, they must be self-consistent. | |
| 770 | Note that this does not change the videomode. | |
| 771 | See | |
| 772 | <citerefentry><refentrytitle>resizecons</refentrytitle><manvolnum>8</manvolnum></citerefentry>. | |
| 773 | (Since 1.3.3.)</para> | |
| 774 | ||
| 775 | <para>The action of the following ioctls depends on the first byte in the struct | |
| 776 | pointed to by <emphasis remap='I'>argp</emphasis>, referred to here as the <emphasis remap='I'>subcode</emphasis>. | |
| 777 | These are legal only for the superuser or the owner of the current tty.</para> | |
| 778 | </listitem> | |
| 779 | </varlistentry> | |
| 780 | <varlistentry> | |
| 781 | <term><emphasis remap='B'>TIOCLINUX, subcode=0</emphasis></term> | |
| 782 | <listitem> | |
| 783 | <para>Dump the screen. | |
| 784 | Disappeared in 1.1.92. (With kernel 1.1.92 or later, read from | |
| 785 | /dev/vcsN or /dev/vcsaN instead.)</para> | |
| 786 | </listitem> | |
| 787 | </varlistentry> | |
| 788 | <varlistentry> | |
| 789 | <term><emphasis remap='B'>TIOCLINUX, subcode=1</emphasis></term> | |
| 790 | <listitem> | |
| 791 | <para>Get task information. | |
| 792 | Disappeared in 1.1.92.</para> | |
| 793 | </listitem> | |
| 794 | </varlistentry> | |
| 795 | <varlistentry> | |
| 796 | <term><emphasis remap='B'>TIOCLINUX, subcode=2</emphasis></term> | |
| 797 | <listitem> | |
| 798 | <para>Set selection. | |
| 799 | <emphasis remap='I'>argp</emphasis> points to a</para> | |
| 800 | <programlisting remap='.nf .ft CW'> | |
| 801 | ||
| 802 | struct { | |
| 803 | char subcode; | |
| 804 | short xs, ys, xe, ye; | |
| 805 | short sel_mode; | |
| 806 | }; | |
| 807 | ||
| 808 | </programlisting> <!-- .fi --> | |
| 809 | <para><emphasis remap='I'>xs</emphasis> and <emphasis remap='I'>ys</emphasis> are the starting column and row. | |
| 810 | <emphasis remap='I'>xe</emphasis> and <emphasis remap='I'>ye</emphasis> are the ending | |
| 811 | column and row. | |
| 812 | (Upper left corner is row=column=1.) | |
| 813 | <emphasis remap='I'>sel_mode</emphasis> is 0 for character-by-character selection, | |
| 814 | 1 for word-by-word selection, | |
| 815 | or 2 for line-by-line selection. | |
| 816 | The indicated screen characters are highlighted and saved | |
| 817 | in the static array sel_buffer in devices/char/console.c.</para> | |
| 818 | </listitem> | |
| 819 | </varlistentry> | |
| 820 | <varlistentry> | |
| 821 | <term><emphasis remap='B'>TIOCLINUX, subcode=3</emphasis></term> | |
| 822 | <listitem> | |
| 823 | <para>Paste selection. | |
| 824 | The characters in the selection buffer are | |
| 825 | written to <emphasis remap='I'>fd</emphasis>.</para> | |
| 826 | </listitem> | |
| 827 | </varlistentry> | |
| 828 | <varlistentry> | |
| 829 | <term><emphasis remap='B'>TIOCLINUX, subcode=4</emphasis></term> | |
| 830 | <listitem> | |
| 831 | <para>Unblank the screen.</para> | |
| 832 | </listitem> | |
| 833 | </varlistentry> | |
| 834 | <varlistentry> | |
| 835 | <term><emphasis remap='B'>TIOCLINUX, subcode=5</emphasis></term> | |
| 836 | <listitem> | |
| 837 | <para>Sets contents of a 256-bit look up table defining characters in a "word", | |
| 838 | for word-by-word selection. | |
| 839 | (Since 1.1.32.)</para> | |
| 840 | </listitem> | |
| 841 | </varlistentry> | |
| 842 | <varlistentry> | |
| 843 | <term><emphasis remap='B'>TIOCLINUX, subcode=6</emphasis></term> | |
| 844 | <listitem> | |
| 845 | <para><emphasis remap='I'>argp</emphasis> points to a char which is set to the value of the kernel | |
| 846 | variable <emphasis remap='I'>shift_state</emphasis>. | |
| 847 | (Since 1.1.32.)</para> | |
| 848 | </listitem> | |
| 849 | </varlistentry> | |
| 850 | <varlistentry> | |
| 851 | <term><emphasis remap='B'>TIOCLINUX, subcode=7</emphasis></term> | |
| 852 | <listitem> | |
| 853 | <para><emphasis remap='I'>argp</emphasis> points to a char which is set to the value of the kernel | |
| 854 | variable <emphasis remap='I'>report_mouse</emphasis>. | |
| 855 | (Since 1.1.33.)</para> | |
| 856 | </listitem> | |
| 857 | </varlistentry> | |
| 858 | <varlistentry> | |
| 859 | <term><emphasis remap='B'>TIOCLINUX, subcode=8</emphasis></term> | |
| 860 | <listitem> | |
| 861 | <para>Dump screen width and height, cursor position, and all the | |
| 862 | character-attribute pairs. | |
| 863 | (Kernels 1.1.67 through 1.1.91 only. | |
| 864 | With kernel 1.1.92 or later, read from /dev/vcsa* instead.)</para> | |
| 865 | </listitem> | |
| 866 | </varlistentry> | |
| 867 | <varlistentry> | |
| 868 | <term><emphasis remap='B'>TIOCLINUX, subcode=9</emphasis></term> | |
| 869 | <listitem> | |
| 870 | <para>Restore screen width and height, cursor position, and all the | |
| 871 | character-attribute pairs. | |
| 872 | (Kernels 1.1.67 through 1.1.91 only. | |
| 873 | With kernel 1.1.92 or later, write to /dev/vcsa* instead.)</para> | |
| 874 | </listitem> | |
| 875 | </varlistentry> | |
| 876 | <varlistentry> | |
| 877 | <term><emphasis remap='B'>TIOCLINUX, subcode=10</emphasis></term> | |
| 878 | <listitem> | |
| 879 | <para>Handles the Power Saving | |
| 880 | feature of the new generation of monitors. | |
| 881 | VESA screen blanking mode is set to <emphasis remap='I'>argp</emphasis>[1], which governs what | |
| 882 | screen blanking does:</para> | |
| 883 | ||
| 884 | <para> <literal>0</literal>: Screen blanking is disabled.</para> | |
| 885 | ||
| 886 | <para> <literal>1</literal>: The current video adapter | |
| 887 | register settings are saved, then the controller is programmed to turn off | |
| 888 | the vertical synchronization pulses. | |
| 889 | This puts the monitor into "standby" mode. | |
| 890 | If your monitor has an Off_Mode timer, then | |
| 891 | it will eventually power down by itself.</para> | |
| 892 | ||
| 893 | <para> <literal>2</literal>: The current | |
| 894 | settings are saved, then both the vertical and horizontal | |
| 895 | synchronization pulses are turned off. | |
| 896 | This puts the monitor into "off" mode. | |
| 897 | If your monitor has no Off_Mode timer, | |
| 898 | or if you want your monitor to power down immediately when the | |
| 899 | blank_timer times out, then you choose this option. | |
| 900 | (<emphasis remap='I'>Caution:</emphasis> Powering down frequently will damage the monitor.)</para> | |
| 901 | ||
| 902 | <para>(Since 1.1.76.)</para> | |
| 903 | </listitem> | |
| 904 | </varlistentry> | |
| 905 | </variablelist> | |
| 906 | </refsect1> | |
| 907 | ||
| 908 | <refsect1 id='return_value'><title>RETURN VALUE</title> | |
| 909 | <para>On success, 0 is returned. | |
| 910 | On error -1 is returned, and <varname>errno</varname> is set.</para> | |
| 911 | </refsect1> | |
| 912 | ||
| 913 | <refsect1 id='errors'><title>ERRORS</title> | |
| 914 | <para><varname>errno</varname> may take on these values:</para> | |
| 915 | <variablelist remap='TP'> | |
| 916 | <varlistentry> | |
| 917 | <term><errorcode>EBADF</errorcode></term> | |
| 918 | <listitem> | |
| 919 | <para>The file descriptor is invalid.</para> | |
| 920 | </listitem> | |
| 921 | </varlistentry> | |
| 922 | <varlistentry> | |
| 923 | <term><errorcode>ENOTTY</errorcode></term> | |
| 924 | <listitem> | |
| 925 | <para>The file descriptor is not associated with a character special device, | |
| 926 | or the specified request does not apply to it.</para> | |
| 927 | </listitem> | |
| 928 | </varlistentry> | |
| 929 | <varlistentry> | |
| 930 | <term><errorcode>EINVAL</errorcode></term> | |
| 931 | <listitem> | |
| 932 | <para>The file descriptor or <emphasis remap='I'>argp</emphasis> is invalid.</para> | |
| 933 | </listitem> | |
| 934 | </varlistentry> | |
| 935 | <varlistentry> | |
| 936 | <term><errorcode>EPERM</errorcode></term> | |
| 937 | <listitem> | |
| 938 | <para>Insufficient permission.</para> | |
| 939 | </listitem> | |
| 940 | </varlistentry> | |
| 941 | </variablelist> | |
| 942 | </refsect1> | |
| 943 | ||
| 944 | <refsect1 id='notes'><title>NOTES</title> | |
| 945 | <para><emphasis remap='B'>Warning</emphasis>: | |
| 946 | Do not regard this man page as documentation of the Linux console ioctl's. | |
| 947 | This is provided for the curious only, as an alternative to reading the | |
| 948 | source. | |
| 949 | Ioctl's are undocumented Linux internals, liable to be changed | |
| 950 | without warning. | |
| 951 | (And indeed, this page more or less describes the | |
| 952 | situation as of kernel version 1.1.94; | |
| 953 | there are many minor and not-so-minor | |
| 954 | differences with earlier versions.)</para> | |
| 955 | ||
| 956 | <para>Very often, ioctl's are introduced for communication between the | |
| 957 | kernel and one particular well-known program (fdisk, hdparm, setserial, | |
| 958 | tunelp, loadkeys, selection, setfont, etc.), and their behavior will be | |
| 959 | changed when required by this particular program.</para> | |
| 960 | ||
| 961 | <para>Programs using these ioctl's will not be portable to other versions | |
| 962 | of UNIX, will not work on older versions of Linux, and will not work | |
| 963 | on future versions of Linux.</para> | |
| 964 | ||
| 965 | <para>Use POSIX functions.</para> | |
| 966 | </refsect1> | |
| 967 | ||
| 968 | <refsect1 id='see_also'><title>SEE ALSO</title> | |
| 969 | <para><citerefentry><refentrytitle>dumpkeys</refentrytitle><manvolnum>1</manvolnum></citerefentry>, | |
| 970 | <citerefentry><refentrytitle>kbd_mode</refentrytitle><manvolnum>1</manvolnum></citerefentry>, | |
| 971 | <citerefentry><refentrytitle>loadkeys</refentrytitle><manvolnum>1</manvolnum></citerefentry>, | |
| 972 | <citerefentry><refentrytitle>mknod</refentrytitle><manvolnum>1</manvolnum></citerefentry>, | |
| 973 | <citerefentry><refentrytitle>setleds</refentrytitle><manvolnum>1</manvolnum></citerefentry>, | |
| 974 | <citerefentry><refentrytitle>setmetamode</refentrytitle><manvolnum>1</manvolnum></citerefentry>, | |
| 975 | <citerefentry><refentrytitle>execve</refentrytitle><manvolnum>2</manvolnum></citerefentry>, | |
| 976 | <citerefentry><refentrytitle>fcntl</refentrytitle><manvolnum>2</manvolnum></citerefentry>, | |
| 977 | <citerefentry><refentrytitle>ioperm</refentrytitle><manvolnum>2</manvolnum></citerefentry>, | |
| 978 | <citerefentry><refentrytitle>termios</refentrytitle><manvolnum>3</manvolnum></citerefentry>, | |
| 979 | <citerefentry><refentrytitle>console</refentrytitle><manvolnum>4</manvolnum></citerefentry>, | |
| 980 | <citerefentry><refentrytitle>console_codes</refentrytitle><manvolnum>4</manvolnum></citerefentry>, | |
| 981 | <citerefentry><refentrytitle>mt</refentrytitle><manvolnum>4</manvolnum></citerefentry>, | |
| 982 | <citerefentry><refentrytitle>sd</refentrytitle><manvolnum>4</manvolnum></citerefentry>, | |
| 983 | <citerefentry><refentrytitle>tty</refentrytitle><manvolnum>4</manvolnum></citerefentry>, | |
| 984 | <citerefentry><refentrytitle>tty_ioctl</refentrytitle><manvolnum>4</manvolnum></citerefentry>, | |
| 985 | <citerefentry><refentrytitle>ttyS</refentrytitle><manvolnum>4</manvolnum></citerefentry>, | |
| 986 | <citerefentry><refentrytitle>vcs</refentrytitle><manvolnum>4</manvolnum></citerefentry>, | |
| 987 | <citerefentry><refentrytitle>vcsa</refentrytitle><manvolnum>4</manvolnum></citerefentry>, | |
| 988 | <citerefentry><refentrytitle>charsets</refentrytitle><manvolnum>7</manvolnum></citerefentry>, | |
| 989 | <citerefentry><refentrytitle>mapscrn</refentrytitle><manvolnum>8</manvolnum></citerefentry>, | |
| 990 | <citerefentry><refentrytitle>resizecons</refentrytitle><manvolnum>8</manvolnum></citerefentry>, | |
| 991 | <citerefentry><refentrytitle>setfont</refentrytitle><manvolnum>8</manvolnum></citerefentry>, | |
| 992 | <filename>/usr/include/linux/kd.h</filename>, | |
| 993 | <filename>/usr/include/linux/vt.h</filename></para> | |
| 994 | </refsect1> | |
| 995 | ||
| 996 | <refsect1 id='colophon'><title>COLOPHON</title> | |
| 997 | <para>This page is part of release 3.35 of the Linux | |
| 998 | <emphasis remap='I'>man-pages</emphasis> | |
| 999 | project. | |
| 1000 | A description of the project, | |
| 1001 | and information about reporting bugs, | |
| 1002 | can be found at | |
| 1003 | <ulink url='http://man7.org/linux/man-pages/'>http://man7.org/linux/man-pages/</ulink>.</para> | |
| 1004 | </refsect1> | |
| 1005 | </refentry> | |
| 1006 |
| 0 | .\" Copyright (c) 1995 Jim Van Zandt <jrv@vanzandt.mv.com> and aeb | |
| 1 | .\" Sun Feb 26 11:46:23 MET 1995 | |
| 2 | .\" | |
| 3 | .\" This is free documentation; you can redistribute it and/or | |
| 4 | .\" modify it under the terms of the GNU General Public License as | |
| 5 | .\" published by the Free Software Foundation; either version 2 of | |
| 6 | .\" the License, or (at your option) any later version. | |
| 7 | .\" | |
| 8 | .\" The GNU General Public License's references to "object code" | |
| 9 | .\" and "executables" are to be interpreted as the output of any | |
| 10 | .\" document formatting or typesetting system, including | |
| 11 | .\" intermediate and printed output. | |
| 12 | .\" | |
| 13 | .\" This manual is distributed in the hope that it will be useful, | |
| 14 | .\" but WITHOUT ANY WARRANTY; without even the implied warranty of | |
| 15 | .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
| 16 | .\" GNU General Public License for more details. | |
| 17 | .\" | |
| 18 | .\" You should have received a copy of the GNU General Public | |
| 19 | .\" License along with this manual; if not, write to the Free | |
| 20 | .\" Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, | |
| 21 | .\" USA. | |
| 22 | .\" | |
| 23 | .\" Modified, Sun Feb 26 15:04:20 1995, faith@cs.unc.edu | |
| 24 | .\" Modified, Thu Apr 20 22:08:17 1995, jrv@vanzandt.mv.com | |
| 25 | .\" Modified, Mon Sep 18 22:32:47 1995, hpa@storm.net (H. Peter Anvin) | |
| 26 | .\" FIXME The following are not documented: | |
| 27 | .\" KDFONTOP (since 2.1.111) | |
| 28 | .\" KDGKBDIACRUC (since 2.6.24) | |
| 29 | .\" KDSKBDIACR | |
| 30 | .\" KDSKBDIACRUC (since 2.6.24) | |
| 31 | .\" KDKBDREP (since 2.1.113) | |
| 32 | .\" KDMAPDISP (not implemented as at 2.6.27) | |
| 33 | .\" KDUNMAPDISP (not implemented as at 2.6.27) | |
| 34 | .\" VT_LOCKSWITCH (since 1.3.47, needs CAP_SYS_TTY_CONFIG) | |
| 35 | .\" VT_UNLOCKSWITCH (since 1.3.47, needs CAP_SYS_TTY_CONFIG) | |
| 36 | .\" VT_GETHIFONTMASK (since 2.6.18) | |
| 37 | .\" | |
| 38 | .TH CONSOLE_IOCTL 4 2009-02-28 "Linux" "Linux Programmer's Manual" | |
| 39 | .SH NAME | |
| 40 | console_ioctl \- ioctl's for console terminal and virtual consoles | |
| 41 | .SH DESCRIPTION | |
| 42 | The following Linux-specific | |
| 43 | .BR ioctl (2) | |
| 44 | requests are supported. | |
| 45 | Each requires a third argument, assumed here to be \fIargp\fP. | |
| 46 | .IP \fBKDGETLED\fP | |
| 47 | Get state of LEDs. | |
| 48 | \fIargp\fP points to a \fIchar\fP. | |
| 49 | The lower three bits | |
| 50 | of \fI*argp\fP are set to the state of the LEDs, as follows: | |
| 51 | ||
| 52 | .TS | |
| 53 | l l l. | |
| 54 | LED_CAP 0x04 caps lock led | |
| 55 | LEC_NUM 0x02 num lock led | |
| 56 | LED_SCR 0x01 scroll lock led | |
| 57 | .TE | |
| 58 | ||
| 59 | .IP \fBKDSETLED\fP | |
| 60 | Set the LEDs. | |
| 61 | The LEDs are set to correspond to the lower three bits of | |
| 62 | \fIargp\fP. | |
| 63 | However, if a higher order bit is set, | |
| 64 | the LEDs revert to normal: displaying the state of the | |
| 65 | keyboard functions of caps lock, num lock, and scroll lock. | |
| 66 | .LP | |
| 67 | Before 1.1.54, the LEDs just reflected the state of the corresponding | |
| 68 | keyboard flags, and KDGETLED/KDSETLED would also change the keyboard | |
| 69 | flags. | |
| 70 | Since 1.1.54 the leds can be made to display arbitrary | |
| 71 | information, but by default they display the keyboard flags. | |
| 72 | The following two ioctl's are used to access the keyboard flags. | |
| 73 | .IP \fBKDGKBLED\fP | |
| 74 | Get keyboard flags CapsLock, NumLock, ScrollLock (not lights). | |
| 75 | \fIargp\fP points to a char which is set to the flag state. | |
| 76 | The low order three bits (mask 0x7) get the current flag state, | |
| 77 | and the low order bits of the next nibble (mask 0x70) get | |
| 78 | the default flag state. | |
| 79 | (Since 1.1.54.) | |
| 80 | .IP \fBKDSKBLED\fP | |
| 81 | Set keyboard flags CapsLock, NumLock, ScrollLock (not lights). | |
| 82 | \fIargp\fP has the desired flag state. | |
| 83 | The low order three bits (mask 0x7) have the flag state, | |
| 84 | and the low order bits of the next nibble (mask 0x70) have | |
| 85 | the default flag state. | |
| 86 | (Since 1.1.54.) | |
| 87 | .IP \fBKDGKBTYPE\fP | |
| 88 | Get keyboard type. | |
| 89 | This returns the value KB_101, defined as 0x02. | |
| 90 | .IP \fBKDADDIO\fP | |
| 91 | Add I/O port as valid. | |
| 92 | Equivalent to \fIioperm(arg,1,1)\fP. | |
| 93 | .IP \fBKDDELIO\fP | |
| 94 | Delete I/O port as valid. | |
| 95 | Equivalent to \fIioperm(arg,1,0)\fP. | |
| 96 | .IP \fBKDENABIO\fP | |
| 97 | Enable I/O to video board. | |
| 98 | Equivalent to \fIioperm(0x3b4, 0x3df-0x3b4+1, 1)\fP. | |
| 99 | .IP \fBKDDISABIO\fP | |
| 100 | Disable I/O to video board. | |
| 101 | Equivalent to \fIioperm(0x3b4, 0x3df-0x3b4+1, 0)\fP. | |
| 102 | .IP \fBKDSETMODE\fP | |
| 103 | Set text/graphics mode. | |
| 104 | \fIargp\fP is one of these: | |
| 105 | ||
| 106 | .TS | |
| 107 | l l. | |
| 108 | KD_TEXT 0x00 | |
| 109 | KD_GRAPHICS 0x01 | |
| 110 | .TE | |
| 111 | ||
| 112 | .IP \fBKDGETMODE\fP | |
| 113 | Get text/graphics mode. | |
| 114 | \fIargp\fP points to a \fIlong\fP which is set to one | |
| 115 | of the above values. | |
| 116 | .IP \fBKDMKTONE\fP | |
| 117 | Generate tone of specified length. | |
| 118 | The lower 16 bits of \fIargp\fP specify the period in clock cycles, | |
| 119 | and the upper 16 bits give the duration in msec. | |
| 120 | If the duration is zero, the sound is turned off. | |
| 121 | Control returns immediately. | |
| 122 | For example, \fIargp\fP = (125<<16) + 0x637 would specify | |
| 123 | the beep normally associated with a ctrl-G. | |
| 124 | (Thus since 0.99pl1; broken in 2.1.49-50.) | |
| 125 | .IP \fBKIOCSOUND\fP | |
| 126 | Start or stop sound generation. | |
| 127 | The lower 16 bits of | |
| 128 | \fIargp\fP specify the period in clock cycles | |
| 129 | (that is, \fIargp\fP = 1193180/frequency). | |
| 130 | \fIargp\fP = 0 turns sound off. | |
| 131 | In either case, control returns immediately. | |
| 132 | .IP \fBGIO_CMAP\fP | |
| 133 | Get the current default color map from kernel. | |
| 134 | \fIargp\fP points to | |
| 135 | a 48-byte array. | |
| 136 | (Since 1.3.3.) | |
| 137 | .IP \fBPIO_CMAP\fP | |
| 138 | Change the default text-mode color map. | |
| 139 | \fIargp\fP points to a | |
| 140 | 48-byte array which contains, in order, the Red, Green, and Blue | |
| 141 | values for the 16 available screen colors: 0 is off, and 255 is full | |
| 142 | intensity. | |
| 143 | The default colors are, in order: black, dark red, dark | |
| 144 | green, brown, dark blue, dark purple, dark cyan, light grey, dark | |
| 145 | grey, bright red, bright green, yellow, bright blue, bright purple, | |
| 146 | bright cyan and white. | |
| 147 | (Since 1.3.3.) | |
| 148 | .IP \fBGIO_FONT\fP | |
| 149 | Gets 256-character screen font in expanded form. | |
| 150 | \fIargp\fP points to an 8192 byte array. | |
| 151 | Fails with error code \fBEINVAL\fP if the | |
| 152 | currently loaded font is a 512-character font, or if the console is | |
| 153 | not in text mode. | |
| 154 | .IP \fBGIO_FONTX\fP | |
| 155 | Gets screen font and associated information. | |
| 156 | \fIargp\fP points to a | |
| 157 | \fIstruct consolefontdesc\fP (see \fBPIO_FONTX\fP). | |
| 158 | On call, the | |
| 159 | \fIcharcount\fP field should be set to the maximum number of | |
| 160 | characters that would fit in the buffer pointed to by \fIchardata\fP. | |
| 161 | On return, the \fIcharcount\fP and \fIcharheight\fP are filled with | |
| 162 | the respective data for the currently loaded font, and the | |
| 163 | \fIchardata\fP array contains the font data if the initial value of | |
| 164 | \fIcharcount\fP indicated enough space was available; otherwise the | |
| 165 | buffer is untouched and \fIerrno\fP is set to \fBENOMEM\fP. | |
| 166 | (Since 1.3.1.) | |
| 167 | .IP \fBPIO_FONT\fP | |
| 168 | Sets 256-character screen font. | |
| 169 | Load font into the EGA/VGA character | |
| 170 | generator. | |
| 171 | \fIargp\fP points to a 8192 byte map, with 32 bytes per | |
| 172 | character. | |
| 173 | Only first \fIN\fP of them are used for an 8x\fIN\fP font | |
| 174 | (0 < \fIN\fP <= 32). | |
| 175 | This call also invalidates the Unicode mapping. | |
| 176 | .IP \fBPIO_FONTX\fP | |
| 177 | Sets screen font and associated rendering information. | |
| 178 | \fIargp\fP | |
| 179 | points to a | |
| 180 | ||
| 181 | .RS | |
| 182 | .nf | |
| 183 | .ft CW | |
| 184 | struct consolefontdesc { | |
| 185 | unsigned short charcount; /* characters in font | |
| 186 | (256 or 512) */ | |
| 187 | unsigned short charheight; /* scan lines per | |
| 188 | character (1-32) */ | |
| 189 | char *chardata; /* font data in | |
| 190 | expanded form */ | |
| 191 | }; | |
| 192 | .ft | |
| 193 | .fi | |
| 194 | .RE | |
| 195 | ||
| 196 | If necessary, the screen will be appropriately resized, and | |
| 197 | \fBSIGWINCH\fP sent to the appropriate processes. | |
| 198 | This call also invalidates the Unicode mapping. | |
| 199 | (Since 1.3.1.) | |
| 200 | .IP \fBPIO_FONTRESET\fP | |
| 201 | Resets the screen font, size and Unicode mapping to the bootup | |
| 202 | defaults. | |
| 203 | \fIargp\fP is unused, but should be set to NULL to | |
| 204 | ensure compatibility with future versions of Linux. | |
| 205 | (Since 1.3.28.) | |
| 206 | .IP \fBGIO_SCRNMAP\fP | |
| 207 | Get screen mapping from kernel. | |
| 208 | \fIargp\fP points to an area of size | |
| 209 | E_TABSZ, which is loaded with the font positions used to display each | |
| 210 | character. | |
| 211 | This call is likely to return useless information if the | |
| 212 | currently loaded font is more than 256 characters. | |
| 213 | .IP \fBGIO_UNISCRNMAP\fP | |
| 214 | Get full Unicode screen mapping from kernel. | |
| 215 | \fIargp\fP points to an | |
| 216 | area of size E_TABSZ*sizeof(unsigned short), which is loaded with the | |
| 217 | Unicodes each character represent. | |
| 218 | A special set of Unicodes, | |
| 219 | starting at U+F000, are used to represent "direct to font" mappings. | |
| 220 | (Since 1.3.1.) | |
| 221 | .IP \fBPIO_SCRNMAP\fP | |
| 222 | Loads the "user definable" (fourth) table in the kernel which maps | |
| 223 | bytes into console screen symbols. | |
| 224 | \fIargp\fP points to an area of | |
| 225 | size E_TABSZ. | |
| 226 | .IP \fBPIO_UNISCRNMAP\fP | |
| 227 | Loads the "user definable" (fourth) table in the kernel which maps | |
| 228 | bytes into Unicodes, which are then translated into screen symbols | |
| 229 | according to the currently loaded Unicode-to-font map. | |
| 230 | Special Unicodes starting at U+F000 can be used to map directly to the font | |
| 231 | symbols. | |
| 232 | (Since 1.3.1.) | |
| 233 | .IP \fBGIO_UNIMAP\fP | |
| 234 | Get Unicode-to-font mapping from kernel. | |
| 235 | \fIargp\fP points to a | |
| 236 | ||
| 237 | .RS | |
| 238 | .nf | |
| 239 | .ft CW | |
| 240 | struct unimapdesc { | |
| 241 | unsigned short entry_ct; | |
| 242 | struct unipair *entries; | |
| 243 | }; | |
| 244 | .ft | |
| 245 | .fi | |
| 246 | .RE | |
| 247 | ||
| 248 | where \fIentries\fP points to an array of | |
| 249 | ||
| 250 | .RS | |
| 251 | .nf | |
| 252 | .ft CW | |
| 253 | struct unipair { | |
| 254 | unsigned short unicode; | |
| 255 | unsigned short fontpos; | |
| 256 | }; | |
| 257 | .ft | |
| 258 | .fi | |
| 259 | .RE | |
| 260 | ||
| 261 | (Since 1.1.92.) | |
| 262 | .IP \fBPIO_UNIMAP\fP | |
| 263 | Put unicode-to-font mapping in kernel. | |
| 264 | \fIargp\fP points to a | |
| 265 | \fIstruct unimapdesc\fP. | |
| 266 | (Since 1.1.92) | |
| 267 | .IP \fBPIO_UNIMAPCLR\fP | |
| 268 | Clear table, possibly advise hash algorithm. | |
| 269 | \fIargp\fP points to a | |
| 270 | ||
| 271 | .RS | |
| 272 | .nf | |
| 273 | .ft CW | |
| 274 | struct unimapinit { | |
| 275 | unsigned short advised_hashsize; /* 0 if no opinion */ | |
| 276 | unsigned short advised_hashstep; /* 0 if no opinion */ | |
| 277 | unsigned short advised_hashlevel; /* 0 if no opinion */ | |
| 278 | }; | |
| 279 | .ft | |
| 280 | .fi | |
| 281 | .RE | |
| 282 | ||
| 283 | (Since 1.1.92.) | |
| 284 | .IP \fBKDGKBMODE\fP | |
| 285 | Gets current keyboard mode. | |
| 286 | \fIargp\fP points to a \fIlong\fP which is set to one | |
| 287 | of these: | |
| 288 | ||
| 289 | .TS | |
| 290 | l l. | |
| 291 | K_RAW 0x00 | |
| 292 | K_XLATE 0x01 | |
| 293 | K_MEDIUMRAW 0x02 | |
| 294 | K_UNICODE 0x03 | |
| 295 | .TE | |
| 296 | ||
| 297 | .IP \fBKDSKBMODE\fP | |
| 298 | Sets current keyboard mode. | |
| 299 | \fIargp\fP is a \fIlong\fP equal to one of the above values. | |
| 300 | .IP \fBKDGKBMETA\fP | |
| 301 | Gets meta key handling mode. | |
| 302 | \fIargp\fP points to a \fIlong\fP which is | |
| 303 | set to one of these: | |
| 304 | ||
| 305 | .TS | |
| 306 | l l l. | |
| 307 | K_METABIT 0x03 set high order bit | |
| 308 | K_ESCPREFIX 0x04 escape prefix | |
| 309 | .TE | |
| 310 | ||
| 311 | .IP \fBKDSKBMETA\fP | |
| 312 | Sets meta key handling mode. | |
| 313 | \fIargp\fP is a \fIlong\fP equal to one of the above values. | |
| 314 | .IP \fBKDGKBENT\fP | |
| 315 | Gets one entry in key translation table (keycode to action code). | |
| 316 | \fIargp\fP points to a | |
| 317 | ||
| 318 | .RS | |
| 319 | .nf | |
| 320 | .ft CW | |
| 321 | struct kbentry { | |
| 322 | unsigned char kb_table; | |
| 323 | unsigned char kb_index; | |
| 324 | unsigned short kb_value; | |
| 325 | }; | |
| 326 | .ft | |
| 327 | .fi | |
| 328 | .RE | |
| 329 | ||
| 330 | with the first two members filled in: | |
| 331 | \fIkb_table\fP selects the key table (0 <= \fIkb_table\fP < MAX_NR_KEYMAPS), | |
| 332 | and \fIkb_index\fP is the keycode (0 <= \fIkb_index\fP < NR_KEYS). | |
| 333 | \fIkb_value\fP is set to the corresponding action code, | |
| 334 | or K_HOLE if there is no such key, | |
| 335 | or K_NOSUCHMAP if \fIkb_table\fP is invalid. | |
| 336 | .IP \fBKDSKBENT\fP | |
| 337 | Sets one entry in translation table. | |
| 338 | \fIargp\fP points to | |
| 339 | a \fIstruct kbentry\fP. | |
| 340 | .IP \fBKDGKBSENT\fP | |
| 341 | Gets one function key string. | |
| 342 | \fIargp\fP points to a | |
| 343 | ||
| 344 | .RS | |
| 345 | .nf | |
| 346 | .ft CW | |
| 347 | struct kbsentry { | |
| 348 | unsigned char kb_func; | |
| 349 | unsigned char kb_string[512]; | |
| 350 | }; | |
| 351 | .ft | |
| 352 | .fi | |
| 353 | .RE | |
| 354 | ||
| 355 | \fIkb_string\fP is set to the (null-terminated) string corresponding to | |
| 356 | the \fIkb_func\fPth function key action code. | |
| 357 | .IP \fBKDSKBSENT\fP | |
| 358 | Sets one function key string entry. | |
| 359 | \fIargp\fP points to | |
| 360 | a \fIstruct kbsentry\fP. | |
| 361 | .IP \fBKDGKBDIACR\fP | |
| 362 | Read kernel accent table. | |
| 363 | \fIargp\fP points to a | |
| 364 | ||
| 365 | .RS | |
| 366 | .nf | |
| 367 | .ft CW | |
| 368 | struct kbdiacrs { | |
| 369 | unsigned int kb_cnt; | |
| 370 | struct kbdiacr kbdiacr[256]; | |
| 371 | }; | |
| 372 | .ft | |
| 373 | .fi | |
| 374 | .RE | |
| 375 | ||
| 376 | where \fIkb_cnt\fP is the number of entries in the array, each of which | |
| 377 | is a | |
| 378 | ||
| 379 | .RS | |
| 380 | .nf | |
| 381 | .ft CW | |
| 382 | struct kbdiacr { | |
| 383 | unsigned char diacr; | |
| 384 | unsigned char base; | |
| 385 | unsigned char result; | |
| 386 | }; | |
| 387 | .ft | |
| 388 | .fi | |
| 389 | .RE | |
| 390 | .IP \fBKDGETKEYCODE\fP | |
| 391 | Read kernel keycode table entry (scan code to keycode). | |
| 392 | \fIargp\fP points to a | |
| 393 | ||
| 394 | .RS | |
| 395 | .nf | |
| 396 | .ft CW | |
| 397 | struct kbkeycode { | |
| 398 | unsigned int scancode; | |
| 399 | unsigned int keycode; | |
| 400 | }; | |
| 401 | .ft | |
| 402 | .fi | |
| 403 | .RE | |
| 404 | ||
| 405 | \fIkeycode\fP is set to correspond to the given \fIscancode\fP. | |
| 406 | (89 <= \fIscancode\fP <= 255 only. | |
| 407 | For 1 <= \fIscancode\fP <= 88, \fIkeycode\fP==\fIscancode\fP.) | |
| 408 | (Since 1.1.63.) | |
| 409 | .IP \fBKDSETKEYCODE\fP | |
| 410 | Write kernel keycode table entry. | |
| 411 | \fIargp\fP points to | |
| 412 | a \fIstruct kbkeycode\fP. | |
| 413 | (Since 1.1.63.) | |
| 414 | .IP \fBKDSIGACCEPT\fP | |
| 415 | The calling process indicates its willingness to accept the signal | |
| 416 | \fIargp\fP when it is generated by pressing an appropriate key combination. | |
| 417 | (1 <= \fIargp\fP <= NSIG). | |
| 418 | (See spawn_console() in linux/drivers/char/keyboard.c.) | |
| 419 | .IP \fBVT_OPENQRY\fP | |
| 420 | Returns the first available (non-opened) console. | |
| 421 | \fIargp\fP points to an \fIint\fP which is set to the | |
| 422 | number of the vt (1 <= \fI*argp\fP <= MAX_NR_CONSOLES). | |
| 423 | .IP \fBVT_GETMODE\fP | |
| 424 | Get mode of active vt. | |
| 425 | \fIargp\fP points to a | |
| 426 | ||
| 427 | .RS | |
| 428 | .nf | |
| 429 | .ft CW | |
| 430 | struct vt_mode { | |
| 431 | char mode; /* vt mode */ | |
| 432 | char waitv; /* if set, hang on writes if not active */ | |
| 433 | short relsig; /* signal to raise on release req */ | |
| 434 | short acqsig; /* signal to raise on acquisition */ | |
| 435 | short frsig; /* unused (set to 0) */ | |
| 436 | }; | |
| 437 | .ft | |
| 438 | .fi | |
| 439 | .RE | |
| 440 | ||
| 441 | which is set to the mode of the active vt. | |
| 442 | \fImode\fP is set to one of these values: | |
| 443 | ||
| 444 | .TS | |
| 445 | l l. | |
| 446 | VT_AUTO auto vt switching | |
| 447 | VT_PROCESS process controls switching | |
| 448 | VT_ACKACQ acknowledge switch | |
| 449 | .TE | |
| 450 | ||
| 451 | .IP \fBVT_SETMODE\fP | |
| 452 | Set mode of active vt. | |
| 453 | \fIargp\fP points to | |
| 454 | a \fIstruct vt_mode\fP. | |
| 455 | .IP \fBVT_GETSTATE\fP | |
| 456 | Get global vt state info. | |
| 457 | \fIargp\fP points to a | |
| 458 | ||
| 459 | .RS | |
| 460 | .nf | |
| 461 | .ft CW | |
| 462 | struct vt_stat { | |
| 463 | unsigned short v_active; /* active vt */ | |
| 464 | unsigned short v_signal; /* signal to send */ | |
| 465 | unsigned short v_state; /* vt bit mask */ | |
| 466 | }; | |
| 467 | .ft | |
| 468 | .fi | |
| 469 | .RE | |
| 470 | ||
| 471 | For each vt in use, the corresponding bit in the \fIv_state\fP member is set. | |
| 472 | (Kernels 1.0 through 1.1.92.) | |
| 473 | .IP \fBVT_RELDISP\fP | |
| 474 | Release a display. | |
| 475 | .IP \fBVT_ACTIVATE\fP | |
| 476 | Switch to vt \fIargp\fP (1 <= \fIargp\fP <= MAX_NR_CONSOLES). | |
| 477 | .IP \fBVT_WAITACTIVE\fP | |
| 478 | Wait until vt \fIargp\fP has been activated. | |
| 479 | .IP \fBVT_DISALLOCATE\fP | |
| 480 | Deallocate the memory associated with vt \fIargp\fP. | |
| 481 | (Since 1.1.54.) | |
| 482 | .IP \fBVT_RESIZE\fP | |
| 483 | Set the kernel's idea of screensize. | |
| 484 | \fIargp\fP points to a | |
| 485 | ||
| 486 | .RS | |
| 487 | .nf | |
| 488 | .ft CW | |
| 489 | struct vt_sizes { | |
| 490 | unsigned short v_rows; /* # rows */ | |
| 491 | unsigned short v_cols; /* # columns */ | |
| 492 | unsigned short v_scrollsize; /* no longer used */ | |
| 493 | }; | |
| 494 | .ft | |
| 495 | .fi | |
| 496 | .RE | |
| 497 | ||
| 498 | Note that this does not change the videomode. | |
| 499 | See | |
| 500 | .BR resizecons (8). | |
| 501 | (Since 1.1.54.) | |
| 502 | .IP \fBVT_RESIZEX\fP | |
| 503 | Set the kernel's idea of various screen parameters. | |
| 504 | \fIargp\fP points to a | |
| 505 | ||
| 506 | .RS | |
| 507 | .nf | |
| 508 | .ft CW | |
| 509 | struct vt_consize { | |
| 510 | unsigned short v_rows; /* number of rows */ | |
| 511 | unsigned short v_cols; /* number of columns */ | |
| 512 | unsigned short v_vlin; /* number of pixel rows | |
| 513 | on screen */ | |
| 514 | unsigned short v_clin; /* number of pixel rows | |
| 515 | per character */ | |
| 516 | unsigned short v_vcol; /* number of pixel columns | |
| 517 | on screen */ | |
| 518 | unsigned short v_ccol; /* number of pixel columns | |
| 519 | per character */ | |
| 520 | }; | |
| 521 | .ft | |
| 522 | .fi | |
| 523 | .RE | |
| 524 | ||
| 525 | Any parameter may be set to zero, indicating "no change", but if | |
| 526 | multiple parameters are set, they must be self-consistent. | |
| 527 | Note that this does not change the videomode. | |
| 528 | See | |
| 529 | .BR resizecons (8). | |
| 530 | (Since 1.3.3.) | |
| 531 | .PP | |
| 532 | The action of the following ioctls depends on the first byte in the struct | |
| 533 | pointed to by \fIargp\fP, referred to here as the \fIsubcode\fP. | |
| 534 | These are legal only for the superuser or the owner of the current tty. | |
| 535 | .IP "\fBTIOCLINUX, subcode=0\fP" | |
| 536 | Dump the screen. | |
| 537 | Disappeared in 1.1.92. (With kernel 1.1.92 or later, read from | |
| 538 | /dev/vcsN or /dev/vcsaN instead.) | |
| 539 | .IP "\fBTIOCLINUX, subcode=1\fP" | |
| 540 | Get task information. | |
| 541 | Disappeared in 1.1.92. | |
| 542 | .IP "\fBTIOCLINUX, subcode=2\fP" | |
| 543 | Set selection. | |
| 544 | \fIargp\fP points to a | |
| 545 | .RS | |
| 546 | .nf | |
| 547 | .ft CW | |
| 548 | ||
| 549 | struct { | |
| 550 | char subcode; | |
| 551 | short xs, ys, xe, ye; | |
| 552 | short sel_mode; | |
| 553 | }; | |
| 554 | ||
| 555 | .ft | |
| 556 | .fi | |
| 557 | .RE | |
| 558 | \fIxs\fP and \fIys\fP are the starting column and row. | |
| 559 | \fIxe\fP and \fIye\fP are the ending | |
| 560 | column and row. | |
| 561 | (Upper left corner is row=column=1.) | |
| 562 | \fIsel_mode\fP is 0 for character-by-character selection, | |
| 563 | 1 for word-by-word selection, | |
| 564 | or 2 for line-by-line selection. | |
| 565 | The indicated screen characters are highlighted and saved | |
| 566 | in the static array sel_buffer in devices/char/console.c. | |
| 567 | .IP "\fBTIOCLINUX, subcode=3\fP" | |
| 568 | Paste selection. | |
| 569 | The characters in the selection buffer are | |
| 570 | written to \fIfd\fP. | |
| 571 | .IP "\fBTIOCLINUX, subcode=4\fP" | |
| 572 | Unblank the screen. | |
| 573 | .IP "\fBTIOCLINUX, subcode=5\fP" | |
| 574 | Sets contents of a 256-bit look up table defining characters in a "word", | |
| 575 | for word-by-word selection. | |
| 576 | (Since 1.1.32.) | |
| 577 | .IP "\fBTIOCLINUX, subcode=6\fP" | |
| 578 | \fIargp\fP points to a char which is set to the value of the kernel | |
| 579 | variable \fIshift_state\fP. | |
| 580 | (Since 1.1.32.) | |
| 581 | .IP "\fBTIOCLINUX, subcode=7\fP" | |
| 582 | \fIargp\fP points to a char which is set to the value of the kernel | |
| 583 | variable \fIreport_mouse\fP. | |
| 584 | (Since 1.1.33.) | |
| 585 | .IP "\fBTIOCLINUX, subcode=8\fP" | |
| 586 | Dump screen width and height, cursor position, and all the | |
| 587 | character-attribute pairs. | |
| 588 | (Kernels 1.1.67 through 1.1.91 only. | |
| 589 | With kernel 1.1.92 or later, read from /dev/vcsa* instead.) | |
| 590 | .IP "\fBTIOCLINUX, subcode=9\fP" | |
| 591 | Restore screen width and height, cursor position, and all the | |
| 592 | character-attribute pairs. | |
| 593 | (Kernels 1.1.67 through 1.1.91 only. | |
| 594 | With kernel 1.1.92 or later, write to /dev/vcsa* instead.) | |
| 595 | .IP "\fBTIOCLINUX, subcode=10\fP" | |
| 596 | Handles the Power Saving | |
| 597 | feature of the new generation of monitors. | |
| 598 | VESA screen blanking mode is set to \fIargp\fP[1], which governs what | |
| 599 | screen blanking does: | |
| 600 | ||
| 601 | \fI0\fP: Screen blanking is disabled. | |
| 602 | ||
| 603 | \fI1\fP: The current video adapter | |
| 604 | register settings are saved, then the controller is programmed to turn off | |
| 605 | the vertical synchronization pulses. | |
| 606 | This puts the monitor into "standby" mode. | |
| 607 | If your monitor has an Off_Mode timer, then | |
| 608 | it will eventually power down by itself. | |
| 609 | ||
| 610 | \fI2\fP: The current | |
| 611 | settings are saved, then both the vertical and horizontal | |
| 612 | synchronization pulses are turned off. | |
| 613 | This puts the monitor into "off" mode. | |
| 614 | If your monitor has no Off_Mode timer, | |
| 615 | or if you want your monitor to power down immediately when the | |
| 616 | blank_timer times out, then you choose this option. | |
| 617 | (\fICaution:\fP Powering down frequently will damage the monitor.) | |
| 618 | ||
| 619 | (Since 1.1.76.) | |
| 620 | .SH "RETURN VALUE" | |
| 621 | On success, 0 is returned. | |
| 622 | On error \-1 is returned, and \fIerrno\fP is set. | |
| 623 | .SH ERRORS | |
| 624 | \fIerrno\fP may take on these values: | |
| 625 | .TP | |
| 626 | .B EBADF | |
| 627 | The file descriptor is invalid. | |
| 628 | .TP | |
| 629 | .B ENOTTY | |
| 630 | The file descriptor is not associated with a character special device, | |
| 631 | or the specified request does not apply to it. | |
| 632 | .TP | |
| 633 | .B EINVAL | |
| 634 | The file descriptor or \fIargp\fP is invalid. | |
| 635 | .TP | |
| 636 | .B EPERM | |
| 637 | Insufficient permission. | |
| 638 | .SH NOTES | |
| 639 | .BR Warning : | |
| 640 | Do not regard this man page as documentation of the Linux console ioctl's. | |
| 641 | This is provided for the curious only, as an alternative to reading the | |
| 642 | source. | |
| 643 | Ioctl's are undocumented Linux internals, liable to be changed | |
| 644 | without warning. | |
| 645 | (And indeed, this page more or less describes the | |
| 646 | situation as of kernel version 1.1.94; | |
| 647 | there are many minor and not-so-minor | |
| 648 | differences with earlier versions.) | |
| 649 | ||
| 650 | Very often, ioctl's are introduced for communication between the | |
| 651 | kernel and one particular well-known program (fdisk, hdparm, setserial, | |
| 652 | tunelp, loadkeys, selection, setfont, etc.), and their behavior will be | |
| 653 | changed when required by this particular program. | |
| 654 | ||
| 655 | Programs using these ioctl's will not be portable to other versions | |
| 656 | of UNIX, will not work on older versions of Linux, and will not work | |
| 657 | on future versions of Linux. | |
| 658 | ||
| 659 | Use POSIX functions. | |
| 660 | .SH "SEE ALSO" | |
| 661 | .BR dumpkeys (1), | |
| 662 | .BR kbd_mode (1), | |
| 663 | .BR loadkeys (1), | |
| 664 | .BR mknod (1), | |
| 665 | .BR setleds (1), | |
| 666 | .BR setmetamode (1), | |
| 667 | .BR execve (2), | |
| 668 | .BR fcntl (2), | |
| 669 | .BR ioperm (2), | |
| 670 | .BR termios (3), | |
| 671 | .BR console (4), | |
| 672 | .BR console_codes (4), | |
| 673 | .BR mt (4), | |
| 674 | .BR sd (4), | |
| 675 | .BR tty (4), | |
| 676 | .BR tty_ioctl (4), | |
| 677 | .BR ttyS (4), | |
| 678 | .BR vcs (4), | |
| 679 | .BR vcsa (4), | |
| 680 | .BR charsets (7), | |
| 681 | .BR mapscrn (8), | |
| 682 | .BR resizecons (8), | |
| 683 | .BR setfont (8), | |
| 684 | .IR /usr/include/linux/kd.h , | |
| 685 | .I /usr/include/linux/vt.h | |
| 686 | .SH COLOPHON | |
| 687 | This page is part of release 3.35 of the Linux | |
| 688 | .I man-pages | |
| 689 | project. | |
| 690 | A description of the project, | |
| 691 | and information about reporting bugs, | |
| 692 | can be found at | |
| 693 | http://man7.org/linux/man-pages/. |
| 0 | <?xml version="1.0" encoding="ISO-8859-1"?> | |
| 1 | <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" | |
| 2 | "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"> | |
| 3 | <!-- lifted from man+troff by doclifter --> | |
| 4 | <refentry> | |
| 5 | <!-- /* | |
| 6 | * Copyright (c) 2005 MontaVista Software, Inc. | |
| 7 | * Copyright (c) 2006\-2010 Red Hat, Inc. | |
| 8 | * | |
| 9 | * All rights reserved. | |
| 10 | * | |
| 11 | * Author: Steven Dake (sdake@redhat.com) | |
| 12 | * | |
| 13 | * This software licensed under BSD license, the text of which follows: | |
| 14 | * | |
| 15 | * Redistribution and use in source and binary forms, with or without | |
| 16 | * modification, are permitted provided that the following conditions are met: | |
| 17 | * | |
| 18 | * \- Redistributions of source code must retain the above copyright notice, | |
| 19 | * this list of conditions and the following disclaimer. | |
| 20 | * \- Redistributions in binary form must reproduce the above copyright notice, | |
| 21 | * this list of conditions and the following disclaimer in the documentation | |
| 22 | * and/or other materials provided with the distribution. | |
| 23 | * \- Neither the name of the MontaVista Software, Inc. nor the names of its | |
| 24 | * contributors may be used to endorse or promote products derived from this | |
| 25 | * software without specific prior written permission. | |
| 26 | * | |
| 27 | * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" | |
| 28 | * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE | |
| 29 | * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE | |
| 30 | * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE | |
| 31 | * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR | |
| 32 | * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF | |
| 33 | * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS | |
| 34 | * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN | |
| 35 | * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) | |
| 36 | * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF | |
| 37 | * THE POSSIBILITY OF SUCH DAMAGE. | |
| 38 | */ --> | |
| 39 | <refentryinfo><date>2006-03-28</date></refentryinfo> | |
| 40 | <refmeta> | |
| 41 | <refentrytitle>COROSYNC_CONF</refentrytitle> | |
| 42 | <manvolnum>5</manvolnum> | |
| 43 | <refmiscinfo class='date'>2006-03-28</refmiscinfo> | |
| 44 | <refmiscinfo class='source'>corosync Man Page</refmiscinfo> | |
| 45 | <refmiscinfo class='manual'>Corosync Cluster Engine Programmer's Manual</refmiscinfo> | |
| 46 | </refmeta> | |
| 47 | <refnamediv> | |
| 48 | <refname>corosync.conf</refname> | |
| 49 | <refpurpose>corosync executive configuration file</refpurpose> | |
| 50 | </refnamediv> | |
| 51 | <!-- body begins here --> | |
| 52 | <refsynopsisdiv id='synopsis'> | |
| 53 | <para><filename>/etc/corosync.conf</filename></para> | |
| 54 | </refsynopsisdiv> | |
| 55 | ||
| 56 | ||
| 57 | <refsect1 id='description'><title>DESCRIPTION</title> | |
| 58 | <para>The corosync.conf instructs the corosync executive about various parameters | |
| 59 | needed to control the corosync executive. Empty lines and lines starting with | |
| 60 | # character are ignored. The configuration file consists of bracketed top level | |
| 61 | directives. The possible directive choices are:</para> | |
| 62 | ||
| 63 | <variablelist remap='TP'> | |
| 64 | <varlistentry> | |
| 65 | <term>totem { }</term> | |
| 66 | <listitem> | |
| 67 | <para>This top level directive contains configuration options for the totem protocol.</para> | |
| 68 | </listitem> | |
| 69 | </varlistentry> | |
| 70 | <varlistentry> | |
| 71 | <term>logging { }</term> | |
| 72 | <listitem> | |
| 73 | <para>This top level directive contains configuration options for logging.</para> | |
| 74 | </listitem> | |
| 75 | </varlistentry> | |
| 76 | <varlistentry> | |
| 77 | <term>event { }</term> | |
| 78 | <listitem> | |
| 79 | <para>This top level directive contains configuration options for the event service.</para> | |
| 80 | ||
| 81 | ||
| 82 | ||
| 83 | <para>It is also possible to specify the top level parameter | |
| 84 | <emphasis remap='B'>compatibility.</emphasis> | |
| 85 | This directive indicates the level of compatibility requested by the user. The | |
| 86 | option whitetank can be specified to remain backward compatable with | |
| 87 | openais-0.80.z. The option none can be specified to only be compatable | |
| 88 | with corosync-1.Y.Z. Extra processing during configuration changes is | |
| 89 | required to remain backward compatable.</para> | |
| 90 | ||
| 91 | <para>The default is whitetank. (backwards compatibility)</para> | |
| 92 | ||
| 93 | ||
| 94 | ||
| 95 | <para>Within the | |
| 96 | <emphasis remap='B'>totem</emphasis> | |
| 97 | directive, an interface directive is required. There is also one configuration | |
| 98 | option which is required:</para> | |
| 99 | ||
| 100 | ||
| 101 | <para>Within the | |
| 102 | <emphasis remap='B'>interface</emphasis> | |
| 103 | sub-directive of totem there are four parameters which are required. There is | |
| 104 | one parameter which is optional.</para> | |
| 105 | ||
| 106 | </listitem> | |
| 107 | </varlistentry> | |
| 108 | <varlistentry> | |
| 109 | <term>ringnumber</term> | |
| 110 | <listitem> | |
| 111 | <para>This specifies the ring number for the interface. When using the redundant | |
| 112 | ring protocol, each interface should specify separate ring numbers to uniquely | |
| 113 | identify to the membership protocol which interface to use for which redundant | |
| 114 | ring. The ringnumber must start at 0.</para> | |
| 115 | ||
| 116 | </listitem> | |
| 117 | </varlistentry> | |
| 118 | <varlistentry> | |
| 119 | <term>bindnetaddr</term> | |
| 120 | <listitem> | |
| 121 | <para>This specifies the network address the corosync executive should bind | |
| 122 | to. For example, if the local interface is 192.168.5.92 with netmask | |
| 123 | 255.255.255.0, set bindnetaddr to 192.168.5.0. If the local interface | |
| 124 | is 192.168.5.92 with netmask 255.255.255.192, set bindnetaddr to | |
| 125 | 192.168.5.64, and so forth.</para> | |
| 126 | ||
| 127 | <para>This may also be an IPV6 address, in which case IPV6 networking will be used. | |
| 128 | In this case, the full address must be specified and there is no automatic | |
| 129 | selection of the network interface within a specific subnet as with IPv4.</para> | |
| 130 | ||
| 131 | <para>If IPv6 networking is used, the nodeid field must be specified.</para> | |
| 132 | ||
| 133 | </listitem> | |
| 134 | </varlistentry> | |
| 135 | <varlistentry> | |
| 136 | <term>broadcast</term> | |
| 137 | <listitem> | |
| 138 | <para>This is optional and can be set to yes. If it is set to yes, the broadcast | |
| 139 | address will be used for communication. If this option is set, mcastaddr | |
| 140 | should not be set.</para> | |
| 141 | ||
| 142 | </listitem> | |
| 143 | </varlistentry> | |
| 144 | <varlistentry> | |
| 145 | <term>mcastaddr</term> | |
| 146 | <listitem> | |
| 147 | <para>This is the multicast address used by corosync executive. The default | |
| 148 | should work for most networks, but the network administrator should be queried | |
| 149 | about a multicast address to use. Avoid 224.x.x.x because this is a "config" | |
| 150 | multicast address.</para> | |
| 151 | ||
| 152 | <para>This may also be an IPV6 multicast address, in which case IPV6 networking | |
| 153 | will be used. If IPv6 networking is used, the nodeid field must be specified.</para> | |
| 154 | ||
| 155 | </listitem> | |
| 156 | </varlistentry> | |
| 157 | <varlistentry> | |
| 158 | <term>mcastport</term> | |
| 159 | <listitem> | |
| 160 | <para>This specifies the UDP port number. It is possible to use the same multicast | |
| 161 | address on a network with the corosync services configured for different | |
| 162 | UDP ports. | |
| 163 | Please note corosync uses two UDP ports mcastport (for mcast receives) and | |
| 164 | mcastport - 1 (for mcast sends). | |
| 165 | If you have multiple clusters on the same network using the same mcastaddr | |
| 166 | please configure the mcastports with a gap.</para> | |
| 167 | ||
| 168 | </listitem> | |
| 169 | </varlistentry> | |
| 170 | <varlistentry> | |
| 171 | <term>ttl</term> | |
| 172 | <listitem> | |
| 173 | <para>This specifies the Time To Live (TTL). If you run your cluster on a routed | |
| 174 | network then the default of "1" will be too small. This option provides | |
| 175 | a way to increase this up to 255. The valid range is 0..255. | |
| 176 | Note that this is only valid on multicast transport types.</para> | |
| 177 | ||
| 178 | </listitem> | |
| 179 | </varlistentry> | |
| 180 | <varlistentry> | |
| 181 | <term>member</term> | |
| 182 | <listitem> | |
| 183 | <para>This specifies a member on the interface and used with the udpu transport only. | |
| 184 | Every node that should be a member of the membership should be specified as | |
| 185 | a separate member directive. Within the member directive there is a parameter | |
| 186 | memberaddr which specifies the ip address of one of the nodes.</para> | |
| 187 | ||
| 188 | ||
| 189 | ||
| 190 | <para>Within the | |
| 191 | <emphasis remap='B'>totem</emphasis> | |
| 192 | directive, there are seven configuration options of which one is required, | |
| 193 | five are optional, and one is required when IPV6 is configured in the interface | |
| 194 | subdirective. The required directive controls the version of the totem | |
| 195 | configuration. The optional option unless using IPV6 directive controls | |
| 196 | identification of the processor. The optional options control secrecy and | |
| 197 | authentication, the redundant ring mode of operation, maximum network MTU, | |
| 198 | and number of sending threads, and the nodeid field.</para> | |
| 199 | ||
| 200 | </listitem> | |
| 201 | </varlistentry> | |
| 202 | <varlistentry> | |
| 203 | <term>version</term> | |
| 204 | <listitem> | |
| 205 | <para>This specifies the version of the configuration file. Currently the only | |
| 206 | valid version for this directive is 2.</para> | |
| 207 | ||
| 208 | ||
| 209 | ||
| 210 | </listitem> | |
| 211 | </varlistentry> | |
| 212 | <varlistentry> | |
| 213 | <term>nodeid</term> | |
| 214 | <listitem> | |
| 215 | <para>This configuration option is optional when using IPv4 and required when using | |
| 216 | IPv6. This is a 32 bit value specifying the node identifier delivered to the | |
| 217 | cluster membership service. If this is not specified with IPv4, the node id | |
| 218 | will be determined from the 32 bit IP address the system to which the system | |
| 219 | is bound with ring identifier of 0. The node identifier value of zero is | |
| 220 | reserved and should not be used.</para> | |
| 221 | ||
| 222 | </listitem> | |
| 223 | </varlistentry> | |
| 224 | <varlistentry> | |
| 225 | <term>clear_node_high_bit</term> | |
| 226 | <listitem> | |
| 227 | <para>This configuration option is optional and is only relevant when no nodeid is | |
| 228 | specified. Some openais clients require a signed 32 bit nodeid that is greater | |
| 229 | than zero however by default openais uses all 32 bits of the IPv4 address space | |
| 230 | when generating a nodeid. Set this option to yes to force the high bit to be | |
| 231 | zero and therefor ensure the nodeid is a positive signed 32 bit integer.</para> | |
| 232 | ||
| 233 | <para>WARNING: The clusters behavior is undefined if this option is enabled on only | |
| 234 | a subset of the cluster (for example during a rolling upgrade).</para> | |
| 235 | ||
| 236 | </listitem> | |
| 237 | </varlistentry> | |
| 238 | <varlistentry> | |
| 239 | <term>secauth</term> | |
| 240 | <listitem> | |
| 241 | <para>This specifies that HMAC/SHA1 authentication should be used to authenticate | |
| 242 | all messages. It further specifies that all data should be encrypted with the | |
| 243 | sober128 encryption algorithm to protect data from eavesdropping.</para> | |
| 244 | ||
| 245 | <para>Enabling this option adds a 36 byte header to every message sent by totem which | |
| 246 | reduces total throughput. Encryption and authentication consume 75% of CPU | |
| 247 | cycles in aisexec as measured with gprof when enabled.</para> | |
| 248 | ||
| 249 | <para>For 100mbit networks with 1500 MTU frame transmissions: | |
| 250 | A throughput of 9mb/sec is possible with 100% cpu utilization when this | |
| 251 | option is enabled on 3ghz cpus. | |
| 252 | A throughput of 10mb/sec is possible wth 20% cpu utilization when this | |
| 253 | optin is disabled on 3ghz cpus.</para> | |
| 254 | ||
| 255 | <para>For gig-e networks with large frame transmissions: | |
| 256 | A throughput of 20mb/sec is possible when this option is enabled on | |
| 257 | 3ghz cpus. | |
| 258 | A throughput of 60mb/sec is possible when this option is disabled on | |
| 259 | 3ghz cpus.</para> | |
| 260 | ||
| 261 | <para>The default is on.</para> | |
| 262 | ||
| 263 | </listitem> | |
| 264 | </varlistentry> | |
| 265 | <varlistentry> | |
| 266 | <term>rrp_mode</term> | |
| 267 | <listitem> | |
| 268 | <para>This specifies the mode of redundant ring, which may be none, active, or | |
| 269 | passive. Active replication offers slightly lower latency from transmit | |
| 270 | to delivery in faulty network environments but with less performance. | |
| 271 | Passive replication may nearly double the speed of the totem protocol | |
| 272 | if the protocol doesn't become cpu bound. The final option is none, in | |
| 273 | which case only one network interface will be used to operate the totem | |
| 274 | protocol.</para> | |
| 275 | ||
| 276 | <para>If only one interface directive is specified, none is automatically chosen. | |
| 277 | If multiple interface directives are specified, only active or passive may | |
| 278 | be chosen.</para> | |
| 279 | ||
| 280 | </listitem> | |
| 281 | </varlistentry> | |
| 282 | <varlistentry> | |
| 283 | <term>netmtu</term> | |
| 284 | <listitem> | |
| 285 | <para>This specifies the network maximum transmit unit. To set this value beyond | |
| 286 | 1500, the regular frame MTU, requires ethernet devices that support large, or | |
| 287 | also called jumbo, frames. If any device in the network doesn't support large | |
| 288 | frames, the protocol will not operate properly. The hosts must also have their | |
| 289 | mtu size set from 1500 to whatever frame size is specified here.</para> | |
| 290 | ||
| 291 | <para>Please note while some NICs or switches claim large frame support, they support | |
| 292 | 9000 MTU as the maximum frame size including the IP header. Setting the netmtu | |
| 293 | and host MTUs to 9000 will cause totem to use the full 9000 bytes of the frame. | |
| 294 | Then Linux will add a 18 byte header moving the full frame size to 9018. As a | |
| 295 | result some hardware will not operate properly with this size of data. A netmtu | |
| 296 | of 8982 seems to work for the few large frame devices that have been tested. | |
| 297 | Some manufacturers claim large frame support when in fact they support frame | |
| 298 | sizes of 4500 bytes.</para> | |
| 299 | ||
| 300 | <para>Increasing the MTU from 1500 to 8982 doubles throughput performance from 30MB/sec | |
| 301 | to 60MB/sec as measured with evsbench with 175000 byte messages with the secauth | |
| 302 | directive set to off.</para> | |
| 303 | ||
| 304 | <para>When sending multicast traffic, if the network frequently reconfigures, chances are | |
| 305 | that some device in the network doesn't support large frames.</para> | |
| 306 | ||
| 307 | <para>Choose hardware carefully if intending to use large frame support.</para> | |
| 308 | ||
| 309 | <para>The default is 1500.</para> | |
| 310 | ||
| 311 | </listitem> | |
| 312 | </varlistentry> | |
| 313 | <varlistentry> | |
| 314 | <term>threads</term> | |
| 315 | <listitem> | |
| 316 | <para>This directive controls how many threads are used to encrypt and send multicast | |
| 317 | messages. If secauth is off, the protocol will never use threaded sending. | |
| 318 | If secauth is on, this directive allows systems to be configured to use | |
| 319 | multiple threads to encrypt and send multicast messages.</para> | |
| 320 | ||
| 321 | <para>A thread directive of 0 indicates that no threaded send should be used. This | |
| 322 | mode offers best performance for non-SMP systems.</para> | |
| 323 | ||
| 324 | <para>The default is 0.</para> | |
| 325 | ||
| 326 | </listitem> | |
| 327 | </varlistentry> | |
| 328 | <varlistentry> | |
| 329 | <term>vsftype</term> | |
| 330 | <listitem> | |
| 331 | <para>This directive controls the virtual synchrony filter type used to identify | |
| 332 | a primary component. The preferred choice is YKD dynamic linear voting, | |
| 333 | however, for clusters larger then 32 nodes YKD consumes alot of memory. For | |
| 334 | large scale clusters that are created by changing the MAX_PROCESSORS_COUNT | |
| 335 | #define in the C code totem.h file, the virtual synchrony filter "none" is | |
| 336 | recommended but then AMF and DLCK services (which are currently experimental) | |
| 337 | are not safe for use.</para> | |
| 338 | ||
| 339 | <para>The default is ykd. The vsftype can also be set to none.</para> | |
| 340 | ||
| 341 | </listitem> | |
| 342 | </varlistentry> | |
| 343 | <varlistentry> | |
| 344 | <term>transport</term> | |
| 345 | <listitem> | |
| 346 | <para>This directive controls the transport mechanism used. If the interface to | |
| 347 | which corosync is binding is an RDMA interface such as RoCEE or Infiniband, the | |
| 348 | "iba" parameter may be specified. To avoid the use of multicast entirely, a | |
| 349 | unicast transport parameter "udpu" can be specified. This requires specifying | |
| 350 | the list of members that could potentially make up the membership before | |
| 351 | deployment.</para> | |
| 352 | ||
| 353 | <para>The default is udp. The transport type can also be set to udpu or iba.</para> | |
| 354 | ||
| 355 | <para>Within the | |
| 356 | <emphasis remap='B'>totem</emphasis> | |
| 357 | directive, there are several configuration options which are used to control | |
| 358 | the operation of the protocol. It is generally not recommended to change any | |
| 359 | of these values without proper guidance and sufficient testing. Some networks | |
| 360 | may require larger values if suffering from frequent reconfigurations. Some | |
| 361 | applications may require faster failure detection times which can be achieved | |
| 362 | by reducing the token timeout.</para> | |
| 363 | ||
| 364 | </listitem> | |
| 365 | </varlistentry> | |
| 366 | <varlistentry> | |
| 367 | <term>token</term> | |
| 368 | <listitem> | |
| 369 | <para>This timeout specifies in milliseconds until a token loss is declared after not | |
| 370 | receiving a token. This is the time spent detecting a failure of a processor | |
| 371 | in the current configuration. Reforming a new configuration takes about 50 | |
| 372 | milliseconds in addition to this timeout.</para> | |
| 373 | ||
| 374 | <para>The default is 1000 milliseconds.</para> | |
| 375 | ||
| 376 | </listitem> | |
| 377 | </varlistentry> | |
| 378 | <varlistentry> | |
| 379 | <term>token_retransmit</term> | |
| 380 | <listitem> | |
| 381 | <para>This timeout specifies in milliseconds after how long before receiving a token | |
| 382 | the token is retransmitted. This will be automatically calculated if token | |
| 383 | is modified. It is not recommended to alter this value without guidance from | |
| 384 | the corosync community.</para> | |
| 385 | ||
| 386 | <para>The default is 238 milliseconds.</para> | |
| 387 | ||
| 388 | </listitem> | |
| 389 | </varlistentry> | |
| 390 | <varlistentry> | |
| 391 | <term>hold</term> | |
| 392 | <listitem> | |
| 393 | <para>This timeout specifies in milliseconds how long the token should be held by | |
| 394 | the representative when the protocol is under low utilization. It is not | |
| 395 | recommended to alter this value without guidance from the corosync community.</para> | |
| 396 | ||
| 397 | <para>The default is 180 milliseconds.</para> | |
| 398 | ||
| 399 | </listitem> | |
| 400 | </varlistentry> | |
| 401 | <varlistentry> | |
| 402 | <term>token_retransmits_before_loss_const</term> | |
| 403 | <listitem> | |
| 404 | <para>This value identifies how many token retransmits should be attempted before | |
| 405 | forming a new configuration. If this value is set, retransmit and hold will | |
| 406 | be automatically calculated from retransmits_before_loss and token.</para> | |
| 407 | ||
| 408 | <para>The default is 4 retransmissions.</para> | |
| 409 | ||
| 410 | </listitem> | |
| 411 | </varlistentry> | |
| 412 | <varlistentry> | |
| 413 | <term>join</term> | |
| 414 | <listitem> | |
| 415 | <para>This timeout specifies in milliseconds how long to wait for join messages in | |
| 416 | the membership protocol.</para> | |
| 417 | ||
| 418 | <para>The default is 50 milliseconds.</para> | |
| 419 | ||
| 420 | </listitem> | |
| 421 | </varlistentry> | |
| 422 | <varlistentry> | |
| 423 | <term>send_join</term> | |
| 424 | <listitem> | |
| 425 | <para>This timeout specifies in milliseconds an upper range between 0 and send_join | |
| 426 | to wait before sending a join message. For configurations with less then | |
| 427 | 32 nodes, this parameter is not necessary. For larger rings, this parameter | |
| 428 | is necessary to ensure the NIC is not overflowed with join messages on | |
| 429 | formation of a new ring. A reasonable value for large rings (128 nodes) would | |
| 430 | be 80msec. Other timer values must also change if this value is changed. Seek | |
| 431 | advice from the corosync mailing list if trying to run larger configurations.</para> | |
| 432 | ||
| 433 | <para>The default is 0 milliseconds.</para> | |
| 434 | ||
| 435 | </listitem> | |
| 436 | </varlistentry> | |
| 437 | <varlistentry> | |
| 438 | <term>consensus</term> | |
| 439 | <listitem> | |
| 440 | <para>This timeout specifies in milliseconds how long to wait for consensus to be | |
| 441 | achieved before starting a new round of membership configuration. The minimum | |
| 442 | value for consensus must be 1.2 * token. This value will be automatically | |
| 443 | calculated at 1.2 * token if the user doesn't specify a consensus value.</para> | |
| 444 | ||
| 445 | <para>For two node clusters, a consensus larger then the join timeout but less then | |
| 446 | token is safe. For three node or larger clusters, consensus should be larger | |
| 447 | then token. There is an increasing risk of odd membership changes, which stil | |
| 448 | guarantee virtual synchrony, as node count grows if consensus is less than | |
| 449 | token.</para> | |
| 450 | ||
| 451 | <para>The default is 1200 milliseconds.</para> | |
| 452 | ||
| 453 | </listitem> | |
| 454 | </varlistentry> | |
| 455 | <varlistentry> | |
| 456 | <term>merge</term> | |
| 457 | <listitem> | |
| 458 | <para>This timeout specifies in milliseconds how long to wait before checking for | |
| 459 | a partition when no multicast traffic is being sent. If multicast traffic | |
| 460 | is being sent, the merge detection happens automatically as a function of | |
| 461 | the protocol.</para> | |
| 462 | ||
| 463 | <para>The default is 200 milliseconds.</para> | |
| 464 | ||
| 465 | </listitem> | |
| 466 | </varlistentry> | |
| 467 | <varlistentry> | |
| 468 | <term>downcheck</term> | |
| 469 | <listitem> | |
| 470 | <para>This timeout specifies in milliseconds how long to wait before checking | |
| 471 | that a network interface is back up after it has been downed.</para> | |
| 472 | ||
| 473 | <para>The default is 1000 millseconds.</para> | |
| 474 | ||
| 475 | </listitem> | |
| 476 | </varlistentry> | |
| 477 | <varlistentry> | |
| 478 | <term>fail_recv_const</term> | |
| 479 | <listitem> | |
| 480 | <para>This constant specifies how many rotations of the token without receiving any | |
| 481 | of the messages when messages should be received may occur before a new | |
| 482 | configuration is formed.</para> | |
| 483 | ||
| 484 | <para>The default is 2500 failures to receive a message.</para> | |
| 485 | ||
| 486 | </listitem> | |
| 487 | </varlistentry> | |
| 488 | <varlistentry> | |
| 489 | <term>seqno_unchanged_const</term> | |
| 490 | <listitem> | |
| 491 | <para>This constant specifies how many rotations of the token without any multicast | |
| 492 | traffic should occur before the merge detection timeout is started.</para> | |
| 493 | ||
| 494 | <para>The default is 30 rotations.</para> | |
| 495 | ||
| 496 | </listitem> | |
| 497 | </varlistentry> | |
| 498 | <varlistentry> | |
| 499 | <term>heartbeat_failures_allowed</term> | |
| 500 | <listitem> | |
| 501 | <para>[HeartBeating mechanism] | |
| 502 | Configures the optional HeartBeating mechanism for faster failure detection. Keep in | |
| 503 | mind that engaging this mechanism in lossy networks could cause faulty loss declaration | |
| 504 | as the mechanism relies on the network for heartbeating.</para> | |
| 505 | ||
| 506 | <para>So as a rule of thumb use this mechanism if you require improved failure in low to | |
| 507 | medium utilized networks.</para> | |
| 508 | ||
| 509 | <para>This constant specifies the number of heartbeat failures the system should tolerate | |
| 510 | before declaring heartbeat failure e.g 3. Also if this value is not set or is 0 then the | |
| 511 | heartbeat mechanism is not engaged in the system and token rotation is the method | |
| 512 | of failure detection</para> | |
| 513 | ||
| 514 | <para>The default is 0 (disabled).</para> | |
| 515 | ||
| 516 | </listitem> | |
| 517 | </varlistentry> | |
| 518 | <varlistentry> | |
| 519 | <term>max_network_delay</term> | |
| 520 | <listitem> | |
| 521 | <para>[HeartBeating mechanism] | |
| 522 | This constant specifies in milliseconds the approximate delay that your network takes | |
| 523 | to transport one packet from one machine to another. This value is to be set by system | |
| 524 | engineers and please dont change if not sure as this effects the failure detection | |
| 525 | mechanism using heartbeat.</para> | |
| 526 | ||
| 527 | <para>The default is 50 milliseconds.</para> | |
| 528 | ||
| 529 | </listitem> | |
| 530 | </varlistentry> | |
| 531 | <varlistentry> | |
| 532 | <term>window_size</term> | |
| 533 | <listitem> | |
| 534 | <para>This constant specifies the maximum number of messages that may be sent on one | |
| 535 | token rotation. If all processors perform equally well, this value could be | |
| 536 | large (300), which would introduce higher latency from origination to delivery | |
| 537 | for very large rings. To reduce latency in large rings(16+), the defaults are | |
| 538 | a safe compromise. If 1 or more slow processor(s) are present among fast | |
| 539 | processors, window_size should be no larger then 256000 / netmtu to avoid | |
| 540 | overflow of the kernel receive buffers. The user is notified of this by | |
| 541 | the display of a retransmit list in the notification logs. There is no loss | |
| 542 | of data, but performance is reduced when these errors occur.</para> | |
| 543 | ||
| 544 | <para>The default is 50 messages.</para> | |
| 545 | ||
| 546 | </listitem> | |
| 547 | </varlistentry> | |
| 548 | <varlistentry> | |
| 549 | <term>max_messages</term> | |
| 550 | <listitem> | |
| 551 | <para>This constant specifies the maximum number of messages that may be sent by one | |
| 552 | processor on receipt of the token. The max_messages parameter is limited to | |
| 553 | 256000 / netmtu to prevent overflow of the kernel transmit buffers.</para> | |
| 554 | ||
| 555 | <para>The default is 17 messages.</para> | |
| 556 | ||
| 557 | </listitem> | |
| 558 | </varlistentry> | |
| 559 | <varlistentry> | |
| 560 | <term>miss_count_const</term> | |
| 561 | <listitem> | |
| 562 | <para>This constant defines the maximum number of times on receipt of a token | |
| 563 | a message is checked for retransmission before a retransmission occurs. This | |
| 564 | parameter is useful to modify for switches that delay multicast packets | |
| 565 | compared to unicast packets. The default setting works well for nearly all | |
| 566 | modern switches.</para> | |
| 567 | ||
| 568 | <para>The default is 5 messages.</para> | |
| 569 | ||
| 570 | </listitem> | |
| 571 | </varlistentry> | |
| 572 | <varlistentry> | |
| 573 | <term>rrp_problem_count_timeout</term> | |
| 574 | <listitem> | |
| 575 | <para>This specifies the time in milliseconds to wait before decrementing the | |
| 576 | problem count by 1 for a particular ring to ensure a link is not marked | |
| 577 | faulty for transient network failures.</para> | |
| 578 | ||
| 579 | <para>The default is 2000 milliseconds.</para> | |
| 580 | ||
| 581 | </listitem> | |
| 582 | </varlistentry> | |
| 583 | <varlistentry> | |
| 584 | <term>rrp_problem_count_threshold</term> | |
| 585 | <listitem> | |
| 586 | <para>This specifies the number of times a problem is detected with a link before | |
| 587 | setting the link faulty. Once a link is set faulty, no more data is | |
| 588 | transmitted upon it. Also, the problem counter is no longer decremented when | |
| 589 | the problem count timeout expires.</para> | |
| 590 | ||
| 591 | <para>A problem is detected whenever all tokens from the proceeding processor have | |
| 592 | not been received within the rrp_token_expired_timeout. The | |
| 593 | rrp_problem_count_threshold * rrp_token_expired_timeout should be atleast 50 | |
| 594 | milliseconds less then the token timeout, or a complete reconfiguration | |
| 595 | may occur.</para> | |
| 596 | ||
| 597 | <para>The default is 10 problem counts.</para> | |
| 598 | ||
| 599 | </listitem> | |
| 600 | </varlistentry> | |
| 601 | <varlistentry> | |
| 602 | <term>rrp_problem_count_mcast_threshold</term> | |
| 603 | <listitem> | |
| 604 | <para>This specifies the number of times a problem is detected with multicast before | |
| 605 | setting the link faulty for passive rrp mode. This variable is unused in active | |
| 606 | rrp mode.</para> | |
| 607 | ||
| 608 | <para>The default is 10 times rrp_problem_count_threshold.</para> | |
| 609 | ||
| 610 | </listitem> | |
| 611 | </varlistentry> | |
| 612 | <varlistentry> | |
| 613 | <term>rrp_token_expired_timeout</term> | |
| 614 | <listitem> | |
| 615 | <para>This specifies the time in milliseconds to increment the problem counter for | |
| 616 | the redundant ring protocol after not having received a token from all rings | |
| 617 | for a particular processor.</para> | |
| 618 | ||
| 619 | <para>This value will automatically be calculated from the token timeout and | |
| 620 | problem_count_threshold but may be overridden. It is not recommended to | |
| 621 | override this value without guidance from the corosync community.</para> | |
| 622 | ||
| 623 | <para>The default is 47 milliseconds.</para> | |
| 624 | ||
| 625 | </listitem> | |
| 626 | </varlistentry> | |
| 627 | <varlistentry> | |
| 628 | <term>rrp_autorecovery_check_timeout</term> | |
| 629 | <listitem> | |
| 630 | <para>This specifies the time in milliseconds to check if the failed ring can be | |
| 631 | auto-recovered.</para> | |
| 632 | ||
| 633 | <para>The default is 1000 milliseconds.</para> | |
| 634 | ||
| 635 | ||
| 636 | <para>Within the | |
| 637 | <emphasis remap='B'>logging</emphasis> | |
| 638 | directive, there are several configuration options which are all optional.</para> | |
| 639 | ||
| 640 | ||
| 641 | <para>The following 3 options are valid only for the top level logging directive:</para> | |
| 642 | ||
| 643 | </listitem> | |
| 644 | </varlistentry> | |
| 645 | <varlistentry> | |
| 646 | <term>timestamp</term> | |
| 647 | <listitem> | |
| 648 | <para>This specifies that a timestamp is placed on all log messages.</para> | |
| 649 | ||
| 650 | <para>The default is off.</para> | |
| 651 | ||
| 652 | </listitem> | |
| 653 | </varlistentry> | |
| 654 | <varlistentry> | |
| 655 | <term>fileline</term> | |
| 656 | <listitem> | |
| 657 | <para>This specifies that file and line should be printed.</para> | |
| 658 | ||
| 659 | <para>The default is off.</para> | |
| 660 | ||
| 661 | </listitem> | |
| 662 | </varlistentry> | |
| 663 | <varlistentry> | |
| 664 | <term>function_name</term> | |
| 665 | <listitem> | |
| 666 | <para>This specifies that the code function name should be printed.</para> | |
| 667 | ||
| 668 | <para>The default is off.</para> | |
| 669 | ||
| 670 | ||
| 671 | <para>The following options are valid both for top level logging directive | |
| 672 | and they can be overriden in logger_subsys entries.</para> | |
| 673 | ||
| 674 | </listitem> | |
| 675 | </varlistentry> | |
| 676 | <varlistentry> | |
| 677 | <term>to_stderr</term> | |
| 678 | <term>to_logfile</term> | |
| 679 | <term>to_syslog</term> | |
| 680 | <listitem> | |
| 681 | <para>These specify the destination of logging output. Any combination of | |
| 682 | these options may be specified. Valid options are | |
| 683 | <emphasis remap='B'>yes</emphasis> | |
| 684 | and | |
| 685 | <emphasis remap='B'>no.</emphasis></para> | |
| 686 | ||
| 687 | <para>The default is syslog and stderr.</para> | |
| 688 | ||
| 689 | <para>Please note, if you are using to_logfile and want to rotate the file, use logrotate(8) | |
| 690 | with the option | |
| 691 | <emphasis remap='B'>copytruncate.</emphasis> | |
| 692 | eg.</para> | |
| 693 | <!-- ne 18 --> | |
| 694 | <screen remap='.nf .ft CW'> | |
| 695 | /var/log/corosync.log { | |
| 696 | missingok | |
| 697 | compress | |
| 698 | notifempty | |
| 699 | daily | |
| 700 | rotate 7 | |
| 701 | copytruncate | |
| 702 | } | |
| 703 | </screen> <!-- .fi --> | |
| 704 | ||
| 705 | </listitem> | |
| 706 | </varlistentry> | |
| 707 | <varlistentry> | |
| 708 | <term>logfile</term> | |
| 709 | <listitem> | |
| 710 | <para>If the | |
| 711 | <emphasis remap='B'>to_logfile</emphasis> | |
| 712 | directive is set to | |
| 713 | <emphasis remap='B'>yes</emphasis> | |
| 714 | , this option specifies the pathname of the log file.</para> | |
| 715 | ||
| 716 | <para>No default.</para> | |
| 717 | ||
| 718 | </listitem> | |
| 719 | </varlistentry> | |
| 720 | <varlistentry> | |
| 721 | <term>logfile_priority</term> | |
| 722 | <listitem> | |
| 723 | <para>This specifies the logfile priority for this particular subsystem. Ignored if debug is on. | |
| 724 | Possible values are: alert, crit, debug (same as debug = on), emerg, err, info, notice, warning.</para> | |
| 725 | ||
| 726 | <para>The default is: info.</para> | |
| 727 | ||
| 728 | </listitem> | |
| 729 | </varlistentry> | |
| 730 | <varlistentry> | |
| 731 | <term>syslog_facility</term> | |
| 732 | <listitem> | |
| 733 | <para>This specifies the syslog facility type that will be used for any messages | |
| 734 | sent to syslog. options are daemon, local0, local1, local2, local3, local4, | |
| 735 | local5, local6 & local7.</para> | |
| 736 | ||
| 737 | <para>The default is daemon.</para> | |
| 738 | ||
| 739 | </listitem> | |
| 740 | </varlistentry> | |
| 741 | <varlistentry> | |
| 742 | <term>syslog_priority</term> | |
| 743 | <listitem> | |
| 744 | <para>This specifies the syslog level for this particular subsystem. Ignored if debug is on. | |
| 745 | Possible values are: alert, crit, debug (same as debug = on), emerg, err, info, notice, warning.</para> | |
| 746 | ||
| 747 | <para>The default is: info.</para> | |
| 748 | ||
| 749 | </listitem> | |
| 750 | </varlistentry> | |
| 751 | <varlistentry> | |
| 752 | <term>debug</term> | |
| 753 | <listitem> | |
| 754 | <para>This specifies whether debug output is logged for this particular logger.</para> | |
| 755 | ||
| 756 | <para>The default is off.</para> | |
| 757 | ||
| 758 | </listitem> | |
| 759 | </varlistentry> | |
| 760 | <varlistentry> | |
| 761 | <term>tags</term> | |
| 762 | <listitem> | |
| 763 | <para>This specifies which tags should be traced for this particular logger. | |
| 764 | Set debug directive to | |
| 765 | <emphasis remap='B'>on</emphasis> | |
| 766 | in order to enable tracing using tags. | |
| 767 | Values are specified using a vertical bar as a logical OR separator:</para> | |
| 768 | ||
| 769 | <para>enter|leave|trace1|trace2|trace3|...</para> | |
| 770 | ||
| 771 | <para>The default is none.</para> | |
| 772 | ||
| 773 | ||
| 774 | <para>Within the | |
| 775 | <emphasis remap='B'>logging</emphasis> | |
| 776 | directive, logger_subsys directives are optional.</para> | |
| 777 | ||
| 778 | ||
| 779 | <para>Within the | |
| 780 | <emphasis remap='B'>logger_subsys</emphasis> | |
| 781 | sub-directive, all of the above logging configuration options are valid and | |
| 782 | can be used to override the default settings. | |
| 783 | The subsys entry, described below, is mandatory to identify the subsystem.</para> | |
| 784 | ||
| 785 | </listitem> | |
| 786 | </varlistentry> | |
| 787 | <varlistentry> | |
| 788 | <term>subsys</term> | |
| 789 | <listitem> | |
| 790 | <para>This specifies the subsystem identity (name) for which logging is specified. This is the | |
| 791 | name used by a service in the log_init () call. E.g. 'CKPT'. This directive is | |
| 792 | required.</para> | |
| 793 | ||
| 794 | </listitem> | |
| 795 | </varlistentry> | |
| 796 | </variablelist> | |
| 797 | </refsect1> | |
| 798 | ||
| 799 | <refsect1 id='files'><title>FILES</title> | |
| 800 | <variablelist remap='TP'> | |
| 801 | <varlistentry> | |
| 802 | <term><filename>/etc/corosync.conf</filename></term> | |
| 803 | <listitem> | |
| 804 | <para>The corosync executive configuration file.</para> | |
| 805 | ||
| 806 | </listitem> | |
| 807 | </varlistentry> | |
| 808 | </variablelist> | |
| 809 | </refsect1> | |
| 810 | ||
| 811 | <refsect1 id='see_also'><title>SEE ALSO</title> | |
| 812 | <para><citerefentry><refentrytitle>corosync_overview</refentrytitle><manvolnum>8</manvolnum></citerefentry>, | |
| 813 | <citerefentry><refentrytitle>logrotate</refentrytitle><manvolnum>8</manvolnum></citerefentry></para> | |
| 814 | ||
| 815 | </refsect1> | |
| 816 | </refentry> | |
| 817 |
| 0 | .\"/* | |
| 1 | .\" * Copyright (c) 2005 MontaVista Software, Inc. | |
| 2 | .\" * Copyright (c) 2006-2010 Red Hat, Inc. | |
| 3 | .\" * | |
| 4 | .\" * All rights reserved. | |
| 5 | .\" * | |
| 6 | .\" * Author: Steven Dake (sdake@redhat.com) | |
| 7 | .\" * | |
| 8 | .\" * This software licensed under BSD license, the text of which follows: | |
| 9 | .\" * | |
| 10 | .\" * Redistribution and use in source and binary forms, with or without | |
| 11 | .\" * modification, are permitted provided that the following conditions are met: | |
| 12 | .\" * | |
| 13 | .\" * - Redistributions of source code must retain the above copyright notice, | |
| 14 | .\" * this list of conditions and the following disclaimer. | |
| 15 | .\" * - Redistributions in binary form must reproduce the above copyright notice, | |
| 16 | .\" * this list of conditions and the following disclaimer in the documentation | |
| 17 | .\" * and/or other materials provided with the distribution. | |
| 18 | .\" * - Neither the name of the MontaVista Software, Inc. nor the names of its | |
| 19 | .\" * contributors may be used to endorse or promote products derived from this | |
| 20 | .\" * software without specific prior written permission. | |
| 21 | .\" * | |
| 22 | .\" * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" | |
| 23 | .\" * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE | |
| 24 | .\" * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE | |
| 25 | .\" * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE | |
| 26 | .\" * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR | |
| 27 | .\" * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF | |
| 28 | .\" * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS | |
| 29 | .\" * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN | |
| 30 | .\" * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) | |
| 31 | .\" * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF | |
| 32 | .\" * THE POSSIBILITY OF SUCH DAMAGE. | |
| 33 | .\" */ | |
| 34 | .TH COROSYNC_CONF 5 2006-03-28 "corosync Man Page" "Corosync Cluster Engine Programmer's Manual" | |
| 35 | .SH NAME | |
| 36 | corosync.conf - corosync executive configuration file | |
| 37 | ||
| 38 | .SH SYNOPSIS | |
| 39 | /etc/corosync.conf | |
| 40 | ||
| 41 | .SH DESCRIPTION | |
| 42 | The corosync.conf instructs the corosync executive about various parameters | |
| 43 | needed to control the corosync executive. Empty lines and lines starting with | |
| 44 | # character are ignored. The configuration file consists of bracketed top level | |
| 45 | directives. The possible directive choices are: | |
| 46 | ||
| 47 | .TP | |
| 48 | totem { } | |
| 49 | This top level directive contains configuration options for the totem protocol. | |
| 50 | .TP | |
| 51 | logging { } | |
| 52 | This top level directive contains configuration options for logging. | |
| 53 | .TP | |
| 54 | event { } | |
| 55 | This top level directive contains configuration options for the event service. | |
| 56 | ||
| 57 | .PP | |
| 58 | .PP | |
| 59 | It is also possible to specify the top level parameter | |
| 60 | .B compatibility. | |
| 61 | This directive indicates the level of compatibility requested by the user. The | |
| 62 | option whitetank can be specified to remain backward compatable with | |
| 63 | openais-0.80.z. The option none can be specified to only be compatable | |
| 64 | with corosync-1.Y.Z. Extra processing during configuration changes is | |
| 65 | required to remain backward compatable. | |
| 66 | ||
| 67 | The default is whitetank. (backwards compatibility) | |
| 68 | ||
| 69 | .PP | |
| 70 | .PP | |
| 71 | Within the | |
| 72 | .B totem | |
| 73 | directive, an interface directive is required. There is also one configuration | |
| 74 | option which is required: | |
| 75 | .PP | |
| 76 | .PP | |
| 77 | Within the | |
| 78 | .B interface | |
| 79 | sub-directive of totem there are four parameters which are required. There is | |
| 80 | one parameter which is optional. | |
| 81 | ||
| 82 | .TP | |
| 83 | ringnumber | |
| 84 | This specifies the ring number for the interface. When using the redundant | |
| 85 | ring protocol, each interface should specify separate ring numbers to uniquely | |
| 86 | identify to the membership protocol which interface to use for which redundant | |
| 87 | ring. The ringnumber must start at 0. | |
| 88 | ||
| 89 | .TP | |
| 90 | bindnetaddr | |
| 91 | This specifies the network address the corosync executive should bind | |
| 92 | to. For example, if the local interface is 192.168.5.92 with netmask | |
| 93 | 255.255.255.0, set bindnetaddr to 192.168.5.0. If the local interface | |
| 94 | is 192.168.5.92 with netmask 255.255.255.192, set bindnetaddr to | |
| 95 | 192.168.5.64, and so forth. | |
| 96 | ||
| 97 | This may also be an IPV6 address, in which case IPV6 networking will be used. | |
| 98 | In this case, the full address must be specified and there is no automatic | |
| 99 | selection of the network interface within a specific subnet as with IPv4. | |
| 100 | ||
| 101 | If IPv6 networking is used, the nodeid field must be specified. | |
| 102 | ||
| 103 | .TP | |
| 104 | broadcast | |
| 105 | This is optional and can be set to yes. If it is set to yes, the broadcast | |
| 106 | address will be used for communication. If this option is set, mcastaddr | |
| 107 | should not be set. | |
| 108 | ||
| 109 | .TP | |
| 110 | mcastaddr | |
| 111 | This is the multicast address used by corosync executive. The default | |
| 112 | should work for most networks, but the network administrator should be queried | |
| 113 | about a multicast address to use. Avoid 224.x.x.x because this is a "config" | |
| 114 | multicast address. | |
| 115 | ||
| 116 | This may also be an IPV6 multicast address, in which case IPV6 networking | |
| 117 | will be used. If IPv6 networking is used, the nodeid field must be specified. | |
| 118 | ||
| 119 | .TP | |
| 120 | mcastport | |
| 121 | This specifies the UDP port number. It is possible to use the same multicast | |
| 122 | address on a network with the corosync services configured for different | |
| 123 | UDP ports. | |
| 124 | Please note corosync uses two UDP ports mcastport (for mcast receives) and | |
| 125 | mcastport - 1 (for mcast sends). | |
| 126 | If you have multiple clusters on the same network using the same mcastaddr | |
| 127 | please configure the mcastports with a gap. | |
| 128 | ||
| 129 | .TP | |
| 130 | ttl | |
| 131 | This specifies the Time To Live (TTL). If you run your cluster on a routed | |
| 132 | network then the default of "1" will be too small. This option provides | |
| 133 | a way to increase this up to 255. The valid range is 0..255. | |
| 134 | Note that this is only valid on multicast transport types. | |
| 135 | ||
| 136 | .TP | |
| 137 | member | |
| 138 | This specifies a member on the interface and used with the udpu transport only. | |
| 139 | Every node that should be a member of the membership should be specified as | |
| 140 | a separate member directive. Within the member directive there is a parameter | |
| 141 | memberaddr which specifies the ip address of one of the nodes. | |
| 142 | ||
| 143 | .PP | |
| 144 | .PP | |
| 145 | Within the | |
| 146 | .B totem | |
| 147 | directive, there are seven configuration options of which one is required, | |
| 148 | five are optional, and one is required when IPV6 is configured in the interface | |
| 149 | subdirective. The required directive controls the version of the totem | |
| 150 | configuration. The optional option unless using IPV6 directive controls | |
| 151 | identification of the processor. The optional options control secrecy and | |
| 152 | authentication, the redundant ring mode of operation, maximum network MTU, | |
| 153 | and number of sending threads, and the nodeid field. | |
| 154 | ||
| 155 | .TP | |
| 156 | version | |
| 157 | This specifies the version of the configuration file. Currently the only | |
| 158 | valid version for this directive is 2. | |
| 159 | ||
| 160 | .PP | |
| 161 | .PP | |
| 162 | .TP | |
| 163 | nodeid | |
| 164 | This configuration option is optional when using IPv4 and required when using | |
| 165 | IPv6. This is a 32 bit value specifying the node identifier delivered to the | |
| 166 | cluster membership service. If this is not specified with IPv4, the node id | |
| 167 | will be determined from the 32 bit IP address the system to which the system | |
| 168 | is bound with ring identifier of 0. The node identifier value of zero is | |
| 169 | reserved and should not be used. | |
| 170 | ||
| 171 | .TP | |
| 172 | clear_node_high_bit | |
| 173 | This configuration option is optional and is only relevant when no nodeid is | |
| 174 | specified. Some openais clients require a signed 32 bit nodeid that is greater | |
| 175 | than zero however by default openais uses all 32 bits of the IPv4 address space | |
| 176 | when generating a nodeid. Set this option to yes to force the high bit to be | |
| 177 | zero and therefor ensure the nodeid is a positive signed 32 bit integer. | |
| 178 | ||
| 179 | WARNING: The clusters behavior is undefined if this option is enabled on only | |
| 180 | a subset of the cluster (for example during a rolling upgrade). | |
| 181 | ||
| 182 | .TP | |
| 183 | secauth | |
| 184 | This specifies that HMAC/SHA1 authentication should be used to authenticate | |
| 185 | all messages. It further specifies that all data should be encrypted with the | |
| 186 | sober128 encryption algorithm to protect data from eavesdropping. | |
| 187 | ||
| 188 | Enabling this option adds a 36 byte header to every message sent by totem which | |
| 189 | reduces total throughput. Encryption and authentication consume 75% of CPU | |
| 190 | cycles in aisexec as measured with gprof when enabled. | |
| 191 | ||
| 192 | For 100mbit networks with 1500 MTU frame transmissions: | |
| 193 | A throughput of 9mb/sec is possible with 100% cpu utilization when this | |
| 194 | option is enabled on 3ghz cpus. | |
| 195 | A throughput of 10mb/sec is possible wth 20% cpu utilization when this | |
| 196 | optin is disabled on 3ghz cpus. | |
| 197 | ||
| 198 | For gig-e networks with large frame transmissions: | |
| 199 | A throughput of 20mb/sec is possible when this option is enabled on | |
| 200 | 3ghz cpus. | |
| 201 | A throughput of 60mb/sec is possible when this option is disabled on | |
| 202 | 3ghz cpus. | |
| 203 | ||
| 204 | The default is on. | |
| 205 | ||
| 206 | .TP | |
| 207 | rrp_mode | |
| 208 | This specifies the mode of redundant ring, which may be none, active, or | |
| 209 | passive. Active replication offers slightly lower latency from transmit | |
| 210 | to delivery in faulty network environments but with less performance. | |
| 211 | Passive replication may nearly double the speed of the totem protocol | |
| 212 | if the protocol doesn't become cpu bound. The final option is none, in | |
| 213 | which case only one network interface will be used to operate the totem | |
| 214 | protocol. | |
| 215 | ||
| 216 | If only one interface directive is specified, none is automatically chosen. | |
| 217 | If multiple interface directives are specified, only active or passive may | |
| 218 | be chosen. | |
| 219 | ||
| 220 | .TP | |
| 221 | netmtu | |
| 222 | This specifies the network maximum transmit unit. To set this value beyond | |
| 223 | 1500, the regular frame MTU, requires ethernet devices that support large, or | |
| 224 | also called jumbo, frames. If any device in the network doesn't support large | |
| 225 | frames, the protocol will not operate properly. The hosts must also have their | |
| 226 | mtu size set from 1500 to whatever frame size is specified here. | |
| 227 | ||
| 228 | Please note while some NICs or switches claim large frame support, they support | |
| 229 | 9000 MTU as the maximum frame size including the IP header. Setting the netmtu | |
| 230 | and host MTUs to 9000 will cause totem to use the full 9000 bytes of the frame. | |
| 231 | Then Linux will add a 18 byte header moving the full frame size to 9018. As a | |
| 232 | result some hardware will not operate properly with this size of data. A netmtu | |
| 233 | of 8982 seems to work for the few large frame devices that have been tested. | |
| 234 | Some manufacturers claim large frame support when in fact they support frame | |
| 235 | sizes of 4500 bytes. | |
| 236 | ||
| 237 | Increasing the MTU from 1500 to 8982 doubles throughput performance from 30MB/sec | |
| 238 | to 60MB/sec as measured with evsbench with 175000 byte messages with the secauth | |
| 239 | directive set to off. | |
| 240 | ||
| 241 | When sending multicast traffic, if the network frequently reconfigures, chances are | |
| 242 | that some device in the network doesn't support large frames. | |
| 243 | ||
| 244 | Choose hardware carefully if intending to use large frame support. | |
| 245 | ||
| 246 | The default is 1500. | |
| 247 | ||
| 248 | .TP | |
| 249 | threads | |
| 250 | This directive controls how many threads are used to encrypt and send multicast | |
| 251 | messages. If secauth is off, the protocol will never use threaded sending. | |
| 252 | If secauth is on, this directive allows systems to be configured to use | |
| 253 | multiple threads to encrypt and send multicast messages. | |
| 254 | ||
| 255 | A thread directive of 0 indicates that no threaded send should be used. This | |
| 256 | mode offers best performance for non-SMP systems. | |
| 257 | ||
| 258 | The default is 0. | |
| 259 | ||
| 260 | .TP | |
| 261 | vsftype | |
| 262 | This directive controls the virtual synchrony filter type used to identify | |
| 263 | a primary component. The preferred choice is YKD dynamic linear voting, | |
| 264 | however, for clusters larger then 32 nodes YKD consumes alot of memory. For | |
| 265 | large scale clusters that are created by changing the MAX_PROCESSORS_COUNT | |
| 266 | #define in the C code totem.h file, the virtual synchrony filter "none" is | |
| 267 | recommended but then AMF and DLCK services (which are currently experimental) | |
| 268 | are not safe for use. | |
| 269 | ||
| 270 | The default is ykd. The vsftype can also be set to none. | |
| 271 | ||
| 272 | .TP | |
| 273 | transport | |
| 274 | This directive controls the transport mechanism used. If the interface to | |
| 275 | which corosync is binding is an RDMA interface such as RoCEE or Infiniband, the | |
| 276 | "iba" parameter may be specified. To avoid the use of multicast entirely, a | |
| 277 | unicast transport parameter "udpu" can be specified. This requires specifying | |
| 278 | the list of members that could potentially make up the membership before | |
| 279 | deployment. | |
| 280 | ||
| 281 | The default is udp. The transport type can also be set to udpu or iba. | |
| 282 | ||
| 283 | Within the | |
| 284 | .B totem | |
| 285 | directive, there are several configuration options which are used to control | |
| 286 | the operation of the protocol. It is generally not recommended to change any | |
| 287 | of these values without proper guidance and sufficient testing. Some networks | |
| 288 | may require larger values if suffering from frequent reconfigurations. Some | |
| 289 | applications may require faster failure detection times which can be achieved | |
| 290 | by reducing the token timeout. | |
| 291 | ||
| 292 | .TP | |
| 293 | token | |
| 294 | This timeout specifies in milliseconds until a token loss is declared after not | |
| 295 | receiving a token. This is the time spent detecting a failure of a processor | |
| 296 | in the current configuration. Reforming a new configuration takes about 50 | |
| 297 | milliseconds in addition to this timeout. | |
| 298 | ||
| 299 | The default is 1000 milliseconds. | |
| 300 | ||
| 301 | .TP | |
| 302 | token_retransmit | |
| 303 | This timeout specifies in milliseconds after how long before receiving a token | |
| 304 | the token is retransmitted. This will be automatically calculated if token | |
| 305 | is modified. It is not recommended to alter this value without guidance from | |
| 306 | the corosync community. | |
| 307 | ||
| 308 | The default is 238 milliseconds. | |
| 309 | ||
| 310 | .TP | |
| 311 | hold | |
| 312 | This timeout specifies in milliseconds how long the token should be held by | |
| 313 | the representative when the protocol is under low utilization. It is not | |
| 314 | recommended to alter this value without guidance from the corosync community. | |
| 315 | ||
| 316 | The default is 180 milliseconds. | |
| 317 | ||
| 318 | .TP | |
| 319 | token_retransmits_before_loss_const | |
| 320 | This value identifies how many token retransmits should be attempted before | |
| 321 | forming a new configuration. If this value is set, retransmit and hold will | |
| 322 | be automatically calculated from retransmits_before_loss and token. | |
| 323 | ||
| 324 | The default is 4 retransmissions. | |
| 325 | ||
| 326 | .TP | |
| 327 | join | |
| 328 | This timeout specifies in milliseconds how long to wait for join messages in | |
| 329 | the membership protocol. | |
| 330 | ||
| 331 | The default is 50 milliseconds. | |
| 332 | ||
| 333 | .TP | |
| 334 | send_join | |
| 335 | This timeout specifies in milliseconds an upper range between 0 and send_join | |
| 336 | to wait before sending a join message. For configurations with less then | |
| 337 | 32 nodes, this parameter is not necessary. For larger rings, this parameter | |
| 338 | is necessary to ensure the NIC is not overflowed with join messages on | |
| 339 | formation of a new ring. A reasonable value for large rings (128 nodes) would | |
| 340 | be 80msec. Other timer values must also change if this value is changed. Seek | |
| 341 | advice from the corosync mailing list if trying to run larger configurations. | |
| 342 | ||
| 343 | The default is 0 milliseconds. | |
| 344 | ||
| 345 | .TP | |
| 346 | consensus | |
| 347 | This timeout specifies in milliseconds how long to wait for consensus to be | |
| 348 | achieved before starting a new round of membership configuration. The minimum | |
| 349 | value for consensus must be 1.2 * token. This value will be automatically | |
| 350 | calculated at 1.2 * token if the user doesn't specify a consensus value. | |
| 351 | ||
| 352 | For two node clusters, a consensus larger then the join timeout but less then | |
| 353 | token is safe. For three node or larger clusters, consensus should be larger | |
| 354 | then token. There is an increasing risk of odd membership changes, which stil | |
| 355 | guarantee virtual synchrony, as node count grows if consensus is less than | |
| 356 | token. | |
| 357 | ||
| 358 | The default is 1200 milliseconds. | |
| 359 | ||
| 360 | .TP | |
| 361 | merge | |
| 362 | This timeout specifies in milliseconds how long to wait before checking for | |
| 363 | a partition when no multicast traffic is being sent. If multicast traffic | |
| 364 | is being sent, the merge detection happens automatically as a function of | |
| 365 | the protocol. | |
| 366 | ||
| 367 | The default is 200 milliseconds. | |
| 368 | ||
| 369 | .TP | |
| 370 | downcheck | |
| 371 | This timeout specifies in milliseconds how long to wait before checking | |
| 372 | that a network interface is back up after it has been downed. | |
| 373 | ||
| 374 | The default is 1000 millseconds. | |
| 375 | ||
| 376 | .TP | |
| 377 | fail_recv_const | |
| 378 | This constant specifies how many rotations of the token without receiving any | |
| 379 | of the messages when messages should be received may occur before a new | |
| 380 | configuration is formed. | |
| 381 | ||
| 382 | The default is 2500 failures to receive a message. | |
| 383 | ||
| 384 | .TP | |
| 385 | seqno_unchanged_const | |
| 386 | This constant specifies how many rotations of the token without any multicast | |
| 387 | traffic should occur before the merge detection timeout is started. | |
| 388 | ||
| 389 | The default is 30 rotations. | |
| 390 | ||
| 391 | .TP | |
| 392 | heartbeat_failures_allowed | |
| 393 | [HeartBeating mechanism] | |
| 394 | Configures the optional HeartBeating mechanism for faster failure detection. Keep in | |
| 395 | mind that engaging this mechanism in lossy networks could cause faulty loss declaration | |
| 396 | as the mechanism relies on the network for heartbeating. | |
| 397 | ||
| 398 | So as a rule of thumb use this mechanism if you require improved failure in low to | |
| 399 | medium utilized networks. | |
| 400 | ||
| 401 | This constant specifies the number of heartbeat failures the system should tolerate | |
| 402 | before declaring heartbeat failure e.g 3. Also if this value is not set or is 0 then the | |
| 403 | heartbeat mechanism is not engaged in the system and token rotation is the method | |
| 404 | of failure detection | |
| 405 | ||
| 406 | The default is 0 (disabled). | |
| 407 | ||
| 408 | .TP | |
| 409 | max_network_delay | |
| 410 | [HeartBeating mechanism] | |
| 411 | This constant specifies in milliseconds the approximate delay that your network takes | |
| 412 | to transport one packet from one machine to another. This value is to be set by system | |
| 413 | engineers and please dont change if not sure as this effects the failure detection | |
| 414 | mechanism using heartbeat. | |
| 415 | ||
| 416 | The default is 50 milliseconds. | |
| 417 | ||
| 418 | .TP | |
| 419 | window_size | |
| 420 | This constant specifies the maximum number of messages that may be sent on one | |
| 421 | token rotation. If all processors perform equally well, this value could be | |
| 422 | large (300), which would introduce higher latency from origination to delivery | |
| 423 | for very large rings. To reduce latency in large rings(16+), the defaults are | |
| 424 | a safe compromise. If 1 or more slow processor(s) are present among fast | |
| 425 | processors, window_size should be no larger then 256000 / netmtu to avoid | |
| 426 | overflow of the kernel receive buffers. The user is notified of this by | |
| 427 | the display of a retransmit list in the notification logs. There is no loss | |
| 428 | of data, but performance is reduced when these errors occur. | |
| 429 | ||
| 430 | The default is 50 messages. | |
| 431 | ||
| 432 | .TP | |
| 433 | max_messages | |
| 434 | This constant specifies the maximum number of messages that may be sent by one | |
| 435 | processor on receipt of the token. The max_messages parameter is limited to | |
| 436 | 256000 / netmtu to prevent overflow of the kernel transmit buffers. | |
| 437 | ||
| 438 | The default is 17 messages. | |
| 439 | ||
| 440 | .TP | |
| 441 | miss_count_const | |
| 442 | This constant defines the maximum number of times on receipt of a token | |
| 443 | a message is checked for retransmission before a retransmission occurs. This | |
| 444 | parameter is useful to modify for switches that delay multicast packets | |
| 445 | compared to unicast packets. The default setting works well for nearly all | |
| 446 | modern switches. | |
| 447 | ||
| 448 | The default is 5 messages. | |
| 449 | ||
| 450 | .TP | |
| 451 | rrp_problem_count_timeout | |
| 452 | This specifies the time in milliseconds to wait before decrementing the | |
| 453 | problem count by 1 for a particular ring to ensure a link is not marked | |
| 454 | faulty for transient network failures. | |
| 455 | ||
| 456 | The default is 2000 milliseconds. | |
| 457 | ||
| 458 | .TP | |
| 459 | rrp_problem_count_threshold | |
| 460 | This specifies the number of times a problem is detected with a link before | |
| 461 | setting the link faulty. Once a link is set faulty, no more data is | |
| 462 | transmitted upon it. Also, the problem counter is no longer decremented when | |
| 463 | the problem count timeout expires. | |
| 464 | ||
| 465 | A problem is detected whenever all tokens from the proceeding processor have | |
| 466 | not been received within the rrp_token_expired_timeout. The | |
| 467 | rrp_problem_count_threshold * rrp_token_expired_timeout should be atleast 50 | |
| 468 | milliseconds less then the token timeout, or a complete reconfiguration | |
| 469 | may occur. | |
| 470 | ||
| 471 | The default is 10 problem counts. | |
| 472 | ||
| 473 | .TP | |
| 474 | rrp_problem_count_mcast_threshold | |
| 475 | This specifies the number of times a problem is detected with multicast before | |
| 476 | setting the link faulty for passive rrp mode. This variable is unused in active | |
| 477 | rrp mode. | |
| 478 | ||
| 479 | The default is 10 times rrp_problem_count_threshold. | |
| 480 | ||
| 481 | .TP | |
| 482 | rrp_token_expired_timeout | |
| 483 | This specifies the time in milliseconds to increment the problem counter for | |
| 484 | the redundant ring protocol after not having received a token from all rings | |
| 485 | for a particular processor. | |
| 486 | ||
| 487 | This value will automatically be calculated from the token timeout and | |
| 488 | problem_count_threshold but may be overridden. It is not recommended to | |
| 489 | override this value without guidance from the corosync community. | |
| 490 | ||
| 491 | The default is 47 milliseconds. | |
| 492 | ||
| 493 | .TP | |
| 494 | rrp_autorecovery_check_timeout | |
| 495 | This specifies the time in milliseconds to check if the failed ring can be | |
| 496 | auto-recovered. | |
| 497 | ||
| 498 | The default is 1000 milliseconds. | |
| 499 | ||
| 500 | .PP | |
| 501 | Within the | |
| 502 | .B logging | |
| 503 | directive, there are several configuration options which are all optional. | |
| 504 | ||
| 505 | .PP | |
| 506 | The following 3 options are valid only for the top level logging directive: | |
| 507 | ||
| 508 | .TP | |
| 509 | timestamp | |
| 510 | This specifies that a timestamp is placed on all log messages. | |
| 511 | ||
| 512 | The default is off. | |
| 513 | ||
| 514 | .TP | |
| 515 | fileline | |
| 516 | This specifies that file and line should be printed. | |
| 517 | ||
| 518 | The default is off. | |
| 519 | ||
| 520 | .TP | |
| 521 | function_name | |
| 522 | This specifies that the code function name should be printed. | |
| 523 | ||
| 524 | The default is off. | |
| 525 | ||
| 526 | .PP | |
| 527 | The following options are valid both for top level logging directive | |
| 528 | and they can be overriden in logger_subsys entries. | |
| 529 | ||
| 530 | .TP | |
| 531 | to_stderr | |
| 532 | .TP | |
| 533 | to_logfile | |
| 534 | .TP | |
| 535 | to_syslog | |
| 536 | These specify the destination of logging output. Any combination of | |
| 537 | these options may be specified. Valid options are | |
| 538 | .B yes | |
| 539 | and | |
| 540 | .B no. | |
| 541 | ||
| 542 | The default is syslog and stderr. | |
| 543 | ||
| 544 | Please note, if you are using to_logfile and want to rotate the file, use logrotate(8) | |
| 545 | with the option | |
| 546 | .B | |
| 547 | copytruncate. | |
| 548 | eg. | |
| 549 | .ne 18 | |
| 550 | .RS | |
| 551 | .nf | |
| 552 | .ft CW | |
| 553 | /var/log/corosync.log { | |
| 554 | missingok | |
| 555 | compress | |
| 556 | notifempty | |
| 557 | daily | |
| 558 | rotate 7 | |
| 559 | copytruncate | |
| 560 | } | |
| 561 | .ft | |
| 562 | .fi | |
| 563 | .RE | |
| 564 | ||
| 565 | .TP | |
| 566 | logfile | |
| 567 | If the | |
| 568 | .B to_logfile | |
| 569 | directive is set to | |
| 570 | .B yes | |
| 571 | , this option specifies the pathname of the log file. | |
| 572 | ||
| 573 | No default. | |
| 574 | ||
| 575 | .TP | |
| 576 | logfile_priority | |
| 577 | This specifies the logfile priority for this particular subsystem. Ignored if debug is on. | |
| 578 | Possible values are: alert, crit, debug (same as debug = on), emerg, err, info, notice, warning. | |
| 579 | ||
| 580 | The default is: info. | |
| 581 | ||
| 582 | .TP | |
| 583 | syslog_facility | |
| 584 | This specifies the syslog facility type that will be used for any messages | |
| 585 | sent to syslog. options are daemon, local0, local1, local2, local3, local4, | |
| 586 | local5, local6 & local7. | |
| 587 | ||
| 588 | The default is daemon. | |
| 589 | ||
| 590 | .TP | |
| 591 | syslog_priority | |
| 592 | This specifies the syslog level for this particular subsystem. Ignored if debug is on. | |
| 593 | Possible values are: alert, crit, debug (same as debug = on), emerg, err, info, notice, warning. | |
| 594 | ||
| 595 | The default is: info. | |
| 596 | ||
| 597 | .TP | |
| 598 | debug | |
| 599 | This specifies whether debug output is logged for this particular logger. | |
| 600 | ||
| 601 | The default is off. | |
| 602 | ||
| 603 | .TP | |
| 604 | tags | |
| 605 | This specifies which tags should be traced for this particular logger. | |
| 606 | Set debug directive to | |
| 607 | .B on | |
| 608 | in order to enable tracing using tags. | |
| 609 | Values are specified using a vertical bar as a logical OR separator: | |
| 610 | ||
| 611 | enter|leave|trace1|trace2|trace3|... | |
| 612 | ||
| 613 | The default is none. | |
| 614 | ||
| 615 | .PP | |
| 616 | Within the | |
| 617 | .B logging | |
| 618 | directive, logger_subsys directives are optional. | |
| 619 | ||
| 620 | .PP | |
| 621 | Within the | |
| 622 | .B logger_subsys | |
| 623 | sub-directive, all of the above logging configuration options are valid and | |
| 624 | can be used to override the default settings. | |
| 625 | The subsys entry, described below, is mandatory to identify the subsystem. | |
| 626 | ||
| 627 | .TP | |
| 628 | subsys | |
| 629 | This specifies the subsystem identity (name) for which logging is specified. This is the | |
| 630 | name used by a service in the log_init () call. E.g. 'CKPT'. This directive is | |
| 631 | required. | |
| 632 | ||
| 633 | .SH "FILES" | |
| 634 | .TP | |
| 635 | /etc/corosync.conf | |
| 636 | The corosync executive configuration file. | |
| 637 | ||
| 638 | .SH "SEE ALSO" | |
| 639 | .BR corosync_overview (8), | |
| 640 | .BR logrotate (8) | |
| 641 | .PP |
| 0 | <?xml version="1.0" encoding="ISO-8859-1"?> | |
| 1 | <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" | |
| 2 | "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"> | |
| 3 | <!-- lifted from man+troff by doclifter --> | |
| 4 | ||
| 5 | <refentry> | |
| 6 | <?xml version="1.0" encoding="ISO-8859-1" standalone="no"?> | |
| 7 | <!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "<ulink url='http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd'>http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd</ulink>"> | |
| 8 | <svg version="1.1" baseProfile="full" id="body" width="8in" height="8in" viewBox="0 0 1 1" preserveAspectRatio="none" xmlns="<ulink url='http://www.w3.org/2000/svg'>http://www.w3.org/2000/svg</ulink>" xmlns:xlink="<ulink url='http://www.w3.org/1999/xlink'>http://www.w3.org/1999/xlink</ulink>" xmlns:ev="<ulink url='http://www.w3.org/2001/xml-events'>http://www.w3.org/2001/xml-events</ulink>"> | |
| 9 | <title>SVG drawing</title> | |
| 10 | <desc>This was produced by version 4.4 of GNU libplot, a free library for exporting 2-D vector graphics.</desc> | |
| 11 | <rect id="background" x="0" y="0" width="1" height="1" stroke="none" fill="white"/> | |
| 12 | <g id="content" transform="translate(0.45312,0.5) scale(1,-1) scale(0.125) " xml:space="preserve" stroke="black" stroke-linecap="butt" stroke-linejoin="miter" stroke-miterlimit="10.433" stroke-dasharray="none" stroke-dashoffset="0" stroke-opacity="1" fill="none" fill-rule="evenodd" fill-opacity="1" font-style="normal" font-variant="normal" font-weight="normal" font-stretch="normal" font-size-adjust="none" letter-spacing="normal" word-spacing="normal" text-anchor="start"> | |
| 13 | <rect x="0" y="-0.25" width="0.75" height="0.5" stroke-width="0.0094118" /> | |
| 14 | <text transform="translate(0.26306,-0.049028) scale(1,-1) scale(0.0069444) " font-family="Helvetica,sans-serif" font-size="20px" stroke="none" fill="black" >box</text> | |
| 15 | </g> | |
| 16 | </svg> | |
| 17 | ||
| 18 | ||
| 19 | <refsect1><title>Description</title> | |
| 20 | <para>This empty page was brought to you by brain damage somewhere in POD, | |
| 21 | the Perl build system, or the Perl maintainers' release procedures.</para> | |
| 22 | </refsect1> | |
| 23 | </refentry> |
| 0 | .\" Test load for doclifter | |
| 1 | .TH docliftertest1 1 | |
| 2 | .SH NAME | |
| 3 | docliftertest1 \- section 1 test load for doclifter | |
| 4 | .SH SYNOPSIS | |
| 5 | \fBdocliftertest1\fR [-a | -b] [\fIoptional...\fR] | |
| 6 | ||
| 7 | \fBdocliftertest1\fR -c \fI<required>\fP | |
| 8 | ||
| 9 | \fBdocliftertest1\fR -d | |
| 10 | [ | |
| 11 | .B optional | |
| 12 | ] | |
| 13 | ||
| 14 | \fBdocliftertest1\fR [ -e | -f foo ] ... | |
| 15 | .SH DESCRIPTION | |
| 16 | This file is a test load for doclifter, intended to exercise as much as possible | |
| 17 | of its translation capability. You are now reading the last sentence | |
| 18 | of an ordinary paragraph; by inspecting the output, you can check that | |
| 19 | your formatter is generating a correct beginning-of-body even after | |
| 20 | the section title, and an end-of-body event at the end of the | |
| 21 | paragraph. | |
| 22 | .PP | |
| 23 | This is an ordinary paragraph started by a \fB.PP\fR macro. | |
| 24 | A second line illustrates the effect of filling. | |
| 25 | .PP | |
| 26 | This | |
| 27 | .B word | |
| 28 | should be bold. This | |
| 29 | .SM word | |
| 30 | should be small. The word | |
| 31 | .SM ASCII | |
| 32 | is actually an acronym. This is a reference to section: | |
| 33 | .SM SEE ALSO | |
| 34 | it should be a link now. Visiting the | |
| 35 | .SM SYNOPSIS | |
| 36 | is important. While the | |
| 37 | .SM SYNOPYOSIS | |
| 38 | is not important and doesn't exist. | |
| 39 | .IR This sentence should alternate italic and bold. | |
| 40 | The words in the last sentence should have been run together. | |
| 41 | .LP | |
| 42 | This is an ordinary paragraph started by a \fB.LP\fR macro. | |
| 43 | A second line illustrates the effect of filling. | |
| 44 | .HP 5 | |
| 45 | This is a paragraph started by an \fB.HP\fR macro. | |
| 46 | We translate it to DocBook as an ordinary paragraph break. | |
| 47 | .IP & 5 | |
| 48 | This paragraph was led with \fB.IP & 5\fP. | |
| 49 | A sample line to see how it formats -- it should turn into list markup. | |
| 50 | .PP | |
| 51 | There should be an index entry generated right after this sentence. | |
| 52 | .IX Item <sample> | |
| 53 | And right before this one. | |
| 54 | .IP 5 | |
| 55 | This paragraph was led with \fB.IP 5\fP. | |
| 56 | This should turn into an ordinary paragraph. | |
| 57 | .PP | |
| 58 | This paragraph contains a URL, http://www.google.com, that doesn't have | |
| 59 | explicit \fB.UR\fP/\fB.UN\fR tags around it. It should not be marked | |
| 60 | up, because \fB.UR\fP/\fB.UN\fR tags exist in this document. | |
| 61 | .IP \(bu | |
| 62 | This is the first item in a bulleted list. | |
| 63 | .IP \(bu | |
| 64 | This is the second item in a bulleted list. | |
| 65 | .IP \(bu | |
| 66 | This is the third item in a bulleted list. | |
| 67 | .PP | |
| 68 | This is another ordinary paragraph. It's going to be immediately | |
| 69 | followed (without an intervening paragraph tag) by a table example | |
| 70 | lifted straight from Mike Lesk's original tbl paper: | |
| 71 | .TS | |
| 72 | center, box; | |
| 73 | c s s s | |
| 74 | c s s s | |
| 75 | c |c |c |c | |
| 76 | c |c |c |c | |
| 77 | l |n |n |n. | |
| 78 | 1970 Federal Budget Transfers | |
| 79 | \s-2(in billions of dollars)\s0 | |
| 80 | = | |
| 81 | State Taxes Money Net | |
| 82 | \^ collected spent \^ | |
| 83 | _ | |
| 84 | New York 22.91 21.35 \-1.56 | |
| 85 | New Jersey 8.33 6.96 \-1.37 | |
| 86 | Connecticut 4.12 3.10 \-1.02 | |
| 87 | Maine 0.74 0.67 \-0.07 | |
| 88 | California 22.29 22.42 +0.13 | |
| 89 | New Mexico 0.70 1.49 +0.79 | |
| 90 | Georgia 3.30 4.28 +0.98 | |
| 91 | Mississippi 1.15 2.32 +1.17 | |
| 92 | Texas 9.33 11.13 +1.80 | |
| 93 | .TE | |
| 94 | In the above table, the presence or absence of cell borders may not be | |
| 95 | exactly as | |
| 96 | .BR tbl (1) | |
| 97 | specified them (the DocBook DSSL toolchain sets BORDER=1 if there is | |
| 98 | any frame attribute, which is wrong; according to the DocBook | |
| 99 | specification, the frame attribute should only control box drawing | |
| 100 | around the exterior of the table). But the horizontal spanning and | |
| 101 | centering should be displayed properly. | |
| 102 | .SS MORE TABLES | |
| 103 | We just started a subsection. | |
| 104 | .P | |
| 105 | Here's another table. The first line of the table contains a heading | |
| 106 | centered across all three columns; each remaining line contains a | |
| 107 | left-adjusted item in the first column followed by two columns of | |
| 108 | numerical data. (The numerical alignment won't translate into DocBook.) | |
| 109 | .TS | |
| 110 | c s s | |
| 111 | l n n. | |
| 112 | Overall title | |
| 113 | Item-a 34.22 9.1 | |
| 114 | Item-b 12.65 .02 | |
| 115 | Items: c,d,e 23 5.8 | |
| 116 | Total 69.87 14.92 | |
| 117 | .TE | |
| 118 | This table illustrates the effect of the \fBexpand\fR option: | |
| 119 | .TS | |
| 120 | expand; | |
| 121 | c s s s | |
| 122 | c c c c | |
| 123 | l l n n. | |
| 124 | Bell Labs Locations | |
| 125 | Name Address Area Code Phone | |
| 126 | Holmdel Holmdel, N. J. 07733 201 949-3000 | |
| 127 | Murray Hill Murray Hill, N. J. 07974 201 582-6377 | |
| 128 | Whippany Whippany, N. J. 07981 201 386-3000 | |
| 129 | Indian Hill Naperville, Illinois 60540 312 690-2000 | |
| 130 | .TE | |
| 131 | Here's a really gnarly table with a lot of vertically spanned | |
| 132 | content and several multiline items per line. However this | |
| 133 | is not done with a vertically-spanned format; for that, see the | |
| 134 | next example. | |
| 135 | .TS | |
| 136 | box; | |
| 137 | cb s s s | |
| 138 | c | c | c s | |
| 139 | ltiw(1i) | ltw(2i) | lp8| lw(1.6i)p8. | |
| 140 | Some Interesting Places | |
| 141 | _ | |
| 142 | Name Description Practical Information | |
| 143 | _ | |
| 144 | T{ | |
| 145 | American Museum of Natural History | |
| 146 | T} T{ | |
| 147 | The collections fill 11.5 acres (Michelin) or 25 acres (MTA) | |
| 148 | of exhibition halls on four floors. | |
| 149 | There is a full-sized replica | |
| 150 | of a blue whale and the world's largest star sapphire (stolen in 1964). | |
| 151 | T} Hours 10-5, ex. Sun 11-5, Wed. to 9 | |
| 152 | \^ \^ Location T{ | |
| 153 | Central Park West & 79th St. | |
| 154 | T} | |
| 155 | \^ \^ Admission Donation: $1.00 asked | |
| 156 | \^ \^ Subway AA to 81st St. | |
| 157 | \^ \^ Telephone 212-873-4225 | |
| 158 | _ | |
| 159 | Bronx Zoo T{ | |
| 160 | About a mile long and .6 mile wide, this is the largest zoo in America. | |
| 161 | A lion eats 18 pounds | |
| 162 | of meat a day while a sea lion eats 15 pounds of fish. | |
| 163 | T} Hours T{ | |
| 164 | 10-4:30 winter, to 5:00 summer | |
| 165 | T} | |
| 166 | \^ \^ Location T{ | |
| 167 | 185th St. & Southern Blvd, the Bronx. | |
| 168 | T} | |
| 169 | \^ \^ Admission $1.00, but Tu,We,Th free | |
| 170 | \^ \^ Subway 2, 5 to East Tremont Ave. | |
| 171 | \^ \^ Telephone 212-933-1759 | |
| 172 | _ | |
| 173 | Brooklyn Museum T{ | |
| 174 | Five floors of galleries contain American and ancient art. | |
| 175 | There are American period rooms and architectural ornaments saved | |
| 176 | from wreckers, such as a classical figure from Pennsylvania Station. | |
| 177 | T} Hours Wed-Sat, 10-5, Sun 12-5 | |
| 178 | \^ \^ Location T{ | |
| 179 | Eastern Parkway & Washington Ave., Brooklyn. | |
| 180 | T} | |
| 181 | \^ \^ Admission Free | |
| 182 | \^ \^ Subway 2,3 to Eastern Parkway. | |
| 183 | \^ \^ Telephone 212-638-5000 | |
| 184 | _ | |
| 185 | T{ | |
| 186 | New-York Historical Society | |
| 187 | T} T{ | |
| 188 | All the original paintings for Audubon's | |
| 189 | .I Birds of America | |
| 190 | are here, as are exhibits of American decorative arts, New York history, | |
| 191 | Hudson River school paintings, carriages, and glass paperweights. | |
| 192 | T} Hours T{ | |
| 193 | Tues-Fri & Sun, 1-5; Sat 10-5 | |
| 194 | T} | |
| 195 | \^ \^ Location T{ | |
| 196 | Central Park West & 77th St. | |
| 197 | T} | |
| 198 | \^ \^ Admission Free | |
| 199 | \^ \^ Subway AA to 81st St. | |
| 200 | \^ \^ Telephone 212-873-3400 | |
| 201 | .TE | |
| 202 | OK, here is a table example with spanned vertical format. It | |
| 203 | illustrates the vertical-spanning bug noted on the | |
| 204 | .BR doclifter (1) | |
| 205 | manual page (but | |
| 206 | .BR troff2docbook (1) | |
| 207 | translates this table correctly). If the translation were completely | |
| 208 | correct, the "E" entry would span one row further downward. | |
| 209 | .TS | |
| 210 | allbox; | |
| 211 | l l l | |
| 212 | l l l | |
| 213 | l ^ l. | |
| 214 | A B C | |
| 215 | _ | |
| 216 | D E F | |
| 217 | G H | |
| 218 | I J | |
| 219 | .TE | |
| 220 | .P | |
| 221 | Now we'll test PIC translation to SVG. | |
| 222 | .PS | |
| 223 | box "box" | |
| 224 | .PE | |
| 225 | This line tests recognition of \v'-.4m'\fIsuperscripting\fR\v'.4m') | |
| 226 | ,br | |
| 227 | This line tests recognition of the \uother\d superscript idiom. | |
| 228 | ||
| 229 | .SH FILES | |
| 230 | The following items illustrate \fB.TP\fR markup: | |
| 231 | .TP 5 | |
| 232 | ${HOME}/.profile | |
| 233 | read at startup by | |
| 234 | .BR sh (1). | |
| 235 | .TP | |
| 236 | /etc/hosts | |
| 237 | list of static host addresses used by the \fIbind\fR(8) library. | |
| 238 | .SH SEE ALSO | |
| 239 | ls(1), | |
| 240 | .IR mkdir (1). | |
| 241 | .\" End |
| 0 | <?xml version="1.0" encoding="ISO-8859-1"?> | |
| 1 | <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" | |
| 2 | "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"> | |
| 3 | <!-- lifted from mdoc+troff by doclifter --> | |
| 4 | <refentry> | |
| 5 | <!-- \-*\-nroff\-*\- | |
| 6 | This file is (c) 1998\-2006 Ted Faber (faber@lunabase.org) see | |
| 7 | COPYRIGHT for the full copyright and limitations of liabilities. --> | |
| 8 | ||
| 9 | ||
| 10 | <refmeta> | |
| 11 | <refentrytitle>GRAP</refentrytitle> | |
| 12 | <manvolnum>1</manvolnum> | |
| 13 | </refmeta> | |
| 14 | ||
| 15 | <refnamediv id='purpose'> | |
| 16 | <refname> grap </refname> | |
| 17 | <refpurpose> Kernighan and Bentley's language for typesetting graphs </refpurpose> | |
| 18 | </refnamediv> | |
| 19 | <!-- body begins here --> | |
| 20 | <refsynopsisdiv id='synopsis'> | |
| 21 | <cmdsynopsis> | |
| 22 | <command>grap</command> | |
| 23 | <arg choice='plain'>--d <replaceable>defines_file</replaceable></arg> | |
| 24 | <arg choice='plain'>--D </arg> | |
| 25 | <arg choice='plain'>--l </arg> | |
| 26 | <arg choice='plain'>--M <replaceable>include</replaceable></arg> | |
| 27 | <arg choice='plain'><replaceable>path</replaceable></arg> | |
| 28 | <arg choice='plain'>--R </arg> | |
| 29 | <arg choice='plain'>--r </arg> | |
| 30 | <arg choice='plain'>--v </arg> | |
| 31 | <arg choice='plain'>--u </arg> | |
| 32 | <arg choice='plain'>--C </arg> | |
| 33 | <arg choice='plain'>--c </arg> | |
| 34 | <arg choice='plain'>--h </arg> | |
| 35 | <arg choice='plain' rep='repeat'><replaceable>filename</replaceable></arg> | |
| 36 | ||
| 37 | </cmdsynopsis> | |
| 38 | </refsynopsisdiv> | |
| 39 | ||
| 40 | ||
| 41 | <refsect1 id='description'><title>DESCRIPTION</title> | |
| 42 | <para><command remap='Nm'> grap </command> | |
| 43 | is an implementation of Kernighan and Bentley's language for | |
| 44 | typesetting graphs, as described in “Grap-A Language for Typesetting | |
| 45 | Graphs, Tutorial and User Manual,” by Jon L. Bentley and Brian W. | |
| 46 | Kernighan, revised May 1991, which is the primary source for | |
| 47 | information on how to use | |
| 48 | <command remap='Nm'> grap </command> | |
| 49 | As of this writing, it is available electronically at | |
| 50 | <literal>http://www.kohala.com/start/troff/cstr114.ps</literal>. | |
| 51 | Additional documentation and examples, packaged with | |
| 52 | <command remap='Nm'> grap </command> | |
| 53 | may have been installed locally as well. If available, paths to them | |
| 54 | can be displayed using | |
| 55 | <command remap='Nm'> grap </command> | |
| 56 | <option>-h</option> | |
| 57 | or | |
| 58 | <command remap='Nm'> grap </command> | |
| 59 | <option>-v</option> | |
| 60 | (or | |
| 61 | <command remap='Nm'> grap </command> | |
| 62 | <option>--help</option> | |
| 63 | / | |
| 64 | <command remap='Nm'> grap </command> | |
| 65 | <option>--version</option>)</para> | |
| 66 | ||
| 67 | <para>This version is a black box implementation of | |
| 68 | <command remap='Nm'> grap </command> | |
| 69 | and some inconsistencies are to be expected. The remainder of this | |
| 70 | manual page will briefly outline the | |
| 71 | <command remap='Nm'> grap </command> | |
| 72 | language as implemented here.</para> | |
| 73 | ||
| 74 | <para><command remap='Nm'> grap </command> | |
| 75 | is a | |
| 76 | <citerefentry><refentrytitle>pic</refentrytitle><manvolnum>1</manvolnum></citerefentry> | |
| 77 | pre-processor. It takes commands embedded in a | |
| 78 | <citerefentry><refentrytitle>troff</refentrytitle><manvolnum>1</manvolnum></citerefentry> | |
| 79 | source file which are surrounded by | |
| 80 | <command remap='Ic'>.G1</command> | |
| 81 | and | |
| 82 | <command remap='Ic'>.G2</command> | |
| 83 | macros, and rewrites them into | |
| 84 | <citerefentry><refentrytitle>pic</refentrytitle></citerefentry> | |
| 85 | commands to display the graph. | |
| 86 | Other lines are copied. Output is always to the standard output, | |
| 87 | which is usually redirected. Input is from the given | |
| 88 | <replaceable>filename</replaceable>,s | |
| 89 | which are read in order. A | |
| 90 | <replaceable>filename</replaceable> | |
| 91 | of | |
| 92 | - | |
| 93 | is the standard input. | |
| 94 | If no | |
| 95 | <replaceable>filename</replaceable>s | |
| 96 | are given, input is read from the standard input.</para> | |
| 97 | ||
| 98 | <para>Because | |
| 99 | <command remap='Nm'> grap </command> | |
| 100 | is a | |
| 101 | <citerefentry><refentrytitle>pic</refentrytitle></citerefentry> | |
| 102 | preprocessor, and GNU | |
| 103 | <citerefentry><refentrytitle>pic</refentrytitle></citerefentry> | |
| 104 | will output TeX, it is possible to use | |
| 105 | <command remap='Nm'> grap </command> | |
| 106 | with TeX.</para> | |
| 107 | ||
| 108 | <para>The | |
| 109 | <option>-d</option> | |
| 110 | option specifies a file of macro definitions to be read at startup, | |
| 111 | and defaults to /usr/local/share/grap/grap.defines . | |
| 112 | The | |
| 113 | <option>-D</option> | |
| 114 | option inhibits the reading of any initial macros file | |
| 115 | (the | |
| 116 | <option>-l</option> | |
| 117 | flag is a synonym for | |
| 118 | <option>-D</option>, | |
| 119 | though I do not remember why). The defines | |
| 120 | file can also be given using the | |
| 121 | <envar>GRAP_DEFINES</envar> | |
| 122 | environment variable. (See below).</para> | |
| 123 | ||
| 124 | <para><option>-v</option> | |
| 125 | prints the version information on the standard output and exits. | |
| 126 | <option>--version</option> | |
| 127 | is a synonym for | |
| 128 | <option>-v</option>.</para> | |
| 129 | ||
| 130 | <para><option>-u</option> | |
| 131 | makes labels unaligned by default. This version of | |
| 132 | <command remap='Nm'> grap </command> | |
| 133 | uses new features of GNU | |
| 134 | <citerefentry><refentrytitle>pic</refentrytitle></citerefentry> | |
| 135 | to align the left and right labels with | |
| 136 | the axes, that is that the left and right labels run at right angles | |
| 137 | to the text of the paper. This may be useful in porting old | |
| 138 | <command remap='Nm'> grap </command> | |
| 139 | programs. | |
| 140 | <option>-c</option> | |
| 141 | makes plot strings unclipped by default. Some versions of | |
| 142 | <command remap='Nm'> grap </command> | |
| 143 | allow users to place a string anywhere in the coordinate space, rather than | |
| 144 | only in the frame. By default this version of | |
| 145 | <command remap='Nm'> grap </command> | |
| 146 | does not plot any string centered outside the frame. | |
| 147 | <option>-c</option> | |
| 148 | allows strings to be placed anywhere. See also the | |
| 149 | <command remap='Ic'>clipped</command> | |
| 150 | and | |
| 151 | <command remap='Ic'>unclipped</command> | |
| 152 | string modifiers described in the | |
| 153 | <command remap='Ic'>plot</command> | |
| 154 | statement.</para> | |
| 155 | ||
| 156 | <para><option>-M</option> | |
| 157 | is followed by a colon-separated list of directories used to search | |
| 158 | for relative pathnames included via | |
| 159 | <command remap='Ic'>copy</command>. | |
| 160 | The path is also used to locate the defines file, so if the | |
| 161 | <option>-d</option> | |
| 162 | changes the defines file name to a relative name, it will be searched | |
| 163 | for in the path given by | |
| 164 | <option>-M</option>. | |
| 165 | The search path always includes the current directory, and by default | |
| 166 | that directory is searched last.</para> | |
| 167 | ||
| 168 | <para>All numbers used internally by | |
| 169 | <command remap='Nm'> grap </command> | |
| 170 | are double precision floating point values. Sometimes using floating point | |
| 171 | numbers has unintended consequences. To help avoid these problems, | |
| 172 | <command remap='Nm'> grap </command> | |
| 173 | can use two thresholds for comparison of floating point numbers, set by | |
| 174 | <option>-R</option> | |
| 175 | or | |
| 176 | <option>-r</option>. | |
| 177 | The | |
| 178 | <option>-R</option> | |
| 179 | flag sets coarse comparison mode, which is suitable for most applications. If | |
| 180 | you are plotting small values – less than 1e-6 or so – consider using | |
| 181 | <option>-r</option> | |
| 182 | which uses very fine comparisons between numbers. You may also want to rescale your plotted values to be larger in magnitude. The coarse comarisons are | |
| 183 | used by default.</para> | |
| 184 | ||
| 185 | <para>To be precise, the value by which two numbers must differ for | |
| 186 | <command remap='Nm'> grap </command> | |
| 187 | to consider them not equal is called the comparison limit and the smallest | |
| 188 | non-zero number is called the minimum value. The values a given version of | |
| 189 | <command remap='Nm'> grap </command> | |
| 190 | uses for these are included in the output of | |
| 191 | <option>-v</option> | |
| 192 | or | |
| 193 | <option>-h</option>.</para> | |
| 194 | ||
| 195 | <para>All | |
| 196 | <command remap='Nm'> grap </command> | |
| 197 | commands are included between | |
| 198 | <command remap='Ic'>.G1</command> | |
| 199 | and | |
| 200 | <command remap='Ic'>.G2</command> | |
| 201 | macros, which are consumed by | |
| 202 | <command remap='Nm'> grap </command> | |
| 203 | The output contains | |
| 204 | <citerefentry><refentrytitle>pic</refentrytitle></citerefentry> | |
| 205 | between | |
| 206 | <command remap='Ic'>.PS</command> | |
| 207 | and | |
| 208 | <command remap='Ic'>.PE</command> | |
| 209 | macros. Any arguments to the | |
| 210 | <command remap='Ic'>.G1</command> | |
| 211 | macro in the input are arguments to the | |
| 212 | <command remap='Ic'>.PS</command> | |
| 213 | macro in the output, so graphs can be scaled just like | |
| 214 | <citerefentry><refentrytitle>pic</refentrytitle></citerefentry> | |
| 215 | diagrams. | |
| 216 | If | |
| 217 | <option>-C</option> | |
| 218 | is given, any macro beginning with .G1 or .G2 is treated as a .G1 or | |
| 219 | .G2 macro, for compatibility with old versions of troff. Using | |
| 220 | <option>-C</option> | |
| 221 | also forces pure troff syntax on embedded font change commands when strings | |
| 222 | have the | |
| 223 | <command remap='Ic'>size</command> | |
| 224 | attribute, and all strings to be | |
| 225 | <command remap='Ic'>unclipped</command>.</para> | |
| 226 | ||
| 227 | <para>The | |
| 228 | <option>-h</option> | |
| 229 | flag prints a brief help message and exits. | |
| 230 | <option>--help</option> | |
| 231 | is a synonym for | |
| 232 | <option>-h</option>.</para> | |
| 233 | ||
| 234 | <para>It is possible for someone to cause | |
| 235 | <command remap='Nm'> grap </command> | |
| 236 | to fail by passing a bad format string and data to the | |
| 237 | <command remap='Ic'>sprintf</command> | |
| 238 | command. If | |
| 239 | <command remap='Nm'> grap </command> | |
| 240 | is integrated as part of the printing system, this could conceivably | |
| 241 | provided a path to breaching security on the machine. If you choose to | |
| 242 | use | |
| 243 | <command remap='Nm'> grap </command> | |
| 244 | as part of a printing system run by the super-user, you should disable | |
| 245 | <command remap='Ic'>sprintf</command> | |
| 246 | commands. This can be done by calling | |
| 247 | <command remap='Nm'> grap </command> | |
| 248 | with the | |
| 249 | <option>-S</option> | |
| 250 | flag, setting the | |
| 251 | <envar>GRAP_SAFER</envar> | |
| 252 | environment variable, or compiling with the GRAP_SAFER preprocessor | |
| 253 | symbol defined. (The GNU configure script included with | |
| 254 | <command remap='Nm'> grap </command> | |
| 255 | will define that preprocessor symbol if the | |
| 256 | <option>--with-grap-safe</option> | |
| 257 | option is given.)</para> | |
| 258 | ||
| 259 | <para>The | |
| 260 | <command remap='Nm'> grap </command> | |
| 261 | commands are sketched below. Refer to Kernighan and Bentley's paper | |
| 262 | for the details.</para> | |
| 263 | ||
| 264 | <para>New versions of | |
| 265 | <citerefentry><refentrytitle>groff</refentrytitle><manvolnum>1</manvolnum></citerefentry> | |
| 266 | will invoke | |
| 267 | <command remap='Nm'> grap </command> | |
| 268 | if | |
| 269 | <option>-G</option> | |
| 270 | is given.</para> | |
| 271 | ||
| 272 | <refsect2 id='commands'><title>Commands</title> | |
| 273 | ||
| 274 | <para>Commands are separated from one another by newlines or semicolons (;).</para> | |
| 275 | ||
| 276 | <para><command remap='Ic'>frame</command> | |
| 277 | <replaceable>line_description</replaceable> | |
| 278 | [Bk -words <command>ht</command> <replaceable>height</replaceable> | <command>wid</command> <replaceable>width</replaceable> <replaceable>Ek</replaceable>] | |
| 279 | [Bk -words [Sm off (<command>top</command> | <command>bottom</command> | <command>left</command> | Sm on <command>right</command>) <replaceable>line_description</replaceable> <replaceable>Ek</replaceable>] | |
| 280 | ... | |
| 281 | ]</para> | |
| 282 | ||
| 283 | <para><command remap='Ic'>frame</command> | |
| 284 | [Bk -words <command>ht</command> <replaceable>height</replaceable> | <command>wid</command> <replaceable>width</replaceable> <replaceable>Ek</replaceable>] | |
| 285 | <replaceable>line_description</replaceable> | |
| 286 | [Bk -words [Sm off (<command>top</command> | <command>bottom</command> | <command>left</command> | Sm on <command>right</command>) <replaceable>line_description</replaceable> <replaceable>Ek</replaceable>] | |
| 287 | ... | |
| 288 | ] | |
| 289 | This describes how the axes for the graph are drawn. A | |
| 290 | <replaceable>line_description</replaceable> | |
| 291 | is a | |
| 292 | <citerefentry><refentrytitle>pic</refentrytitle></citerefentry> | |
| 293 | line description, e.g., | |
| 294 | <literal>dashed</literal> | |
| 295 | <literal>0.5</literal>, | |
| 296 | or the literal | |
| 297 | <literal>solid</literal>. | |
| 298 | It may also include a | |
| 299 | <command remap='Ic'>color</command> | |
| 300 | keyword followed by the color to draw the string in double quotes. Any color | |
| 301 | understood by the underlying groff system can be used. Color can only be used | |
| 302 | under GNU pic, and is not available in compatibility mode. Similarly, for | |
| 303 | pic implementations that understand | |
| 304 | <command remap='Ic'>thickness</command>, | |
| 305 | that attribute may be used with a real valued parameter. | |
| 306 | <command remap='Ic'>Thickness</command> | |
| 307 | is not available in compatibility mode.</para> | |
| 308 | ||
| 309 | <para>If the first | |
| 310 | <replaceable>line_description</replaceable> | |
| 311 | is given, the frame is drawn with that style. The default is | |
| 312 | <literal>solid</literal>. | |
| 313 | The height and width of the frame can also be specified in inches. | |
| 314 | The default line style can be over-ridden for sides of the frame by | |
| 315 | specifying additional parameters to | |
| 316 | <command remap='Ic'>frame</command>.</para> | |
| 317 | ||
| 318 | <para>If no plotting commands have been given before the | |
| 319 | <command remap='Ic'>frame</command> | |
| 320 | command is issued, the frame will be output at that point in the | |
| 321 | plotting stream relative to embedded | |
| 322 | <citerefentry><refentrytitle>troff</refentrytitle></citerefentry> | |
| 323 | or | |
| 324 | <citerefentry><refentrytitle>pic</refentrytitle></citerefentry> | |
| 325 | commands. Otherwise the frame is output before the first plotted | |
| 326 | object (even invisible ones).</para> | |
| 327 | ||
| 328 | <para><command remap='Ic'>ht</command> | |
| 329 | and | |
| 330 | <command remap='Ic'>wid</command> | |
| 331 | are in inches by default, but can be any | |
| 332 | <citerefentry><refentrytitle>groff</refentrytitle></citerefentry> | |
| 333 | unit. If omitted, the dimensions are 2 inches high by 3 inches wide.</para> | |
| 334 | ||
| 335 | <para><command remap='Ic'>coord</command> | |
| 336 | <replaceable>name</replaceable> | |
| 337 | <command>x</command> <replaceable>expr</replaceable>, <replaceable>expr</replaceable> | |
| 338 | <command>y</command> <replaceable>expr</replaceable>, <replaceable>expr</replaceable> | |
| 339 | [<command>log</command> <command>x</command> | <command>log</command> <command>y</command> | <command>log</command> <command>log</command>] | |
| 340 | The | |
| 341 | <command remap='Ic'>coord</command> | |
| 342 | command specifies a new coordinate system or sets limits on the | |
| 343 | default system. It defines the largest and smallest values that can | |
| 344 | be plotted, and therefore the scale of the data in the frame. The | |
| 345 | limits for the x and y coordinate systems can be given separately. If | |
| 346 | a | |
| 347 | <replaceable>name</replaceable> | |
| 348 | is given, that coordinate system is defined, if not the default system | |
| 349 | is modified.</para> | |
| 350 | ||
| 351 | <para>A coordinate system created by one | |
| 352 | <command remap='Ic'>coord</command> | |
| 353 | command may be modified by subsequent | |
| 354 | <command remap='Ic'>coord</command> | |
| 355 | commands. A | |
| 356 | <command remap='Nm'> grap </command> | |
| 357 | program may declare a coordinate space using | |
| 358 | <command remap='Ic'>coord</command>, | |
| 359 | <command remap='Ic'>copy</command> | |
| 360 | a file of data through a macro that plots the data and finds its | |
| 361 | maxima and minima, and then define the size of the coordinate system | |
| 362 | with a second | |
| 363 | <command remap='Ic'>coord</command> | |
| 364 | statement.</para> | |
| 365 | ||
| 366 | <para>This command also determines if a scale is plotted logarithmically. | |
| 367 | <command>log</command> <command>log</command> | |
| 368 | means the same thing as | |
| 369 | <command>log</command> <command>x</command> <command>log</command> <command>y</command>.</para> | |
| 370 | ||
| 371 | <para><command remap='Ic'>draw</command> | |
| 372 | <replaceable>line_name</replaceable> | |
| 373 | <replaceable>line_description</replaceable> | |
| 374 | <replaceable>plot_string</replaceable> | |
| 375 | The | |
| 376 | <command remap='Ic'>draw</command> | |
| 377 | command defines the style with which a given line will be plotted. If | |
| 378 | <replaceable>line_name</replaceable> | |
| 379 | is given, the style is associated with that name, otherwise the | |
| 380 | default style is set. | |
| 381 | <replaceable>line_description</replaceable> | |
| 382 | is a | |
| 383 | <citerefentry><refentrytitle>pic</refentrytitle></citerefentry> | |
| 384 | line description, and the optional | |
| 385 | <replaceable>plot_string</replaceable> | |
| 386 | is a string to be centered at each point. The default line | |
| 387 | description is | |
| 388 | <literal>invis</literal>, | |
| 389 | and the default plotting string is a centered bullet, so by default | |
| 390 | each point is a filled circle, and they are unconnected. | |
| 391 | If points are being connected, each | |
| 392 | <command remap='Ic'>draw</command> | |
| 393 | command ends any current line and begins a new one.</para> | |
| 394 | ||
| 395 | <para>When defining a line style, that is the first | |
| 396 | <command remap='Ic'>draw</command> | |
| 397 | command for a given line name, specifying no plot string means that | |
| 398 | there are to be no plot strings. Omitting the plot string on | |
| 399 | subsequent | |
| 400 | <command remap='Ic'>draw</command> | |
| 401 | commands addressing the same named line means not to change the plot | |
| 402 | string. If a line has been defined with a plot string, and the format | |
| 403 | is changed by a subsequent | |
| 404 | <command remap='Ic'>draw</command> | |
| 405 | statement, the plot string can be removed by specifying "" in the | |
| 406 | <command remap='Ic'>draw</command> | |
| 407 | statement.</para> | |
| 408 | ||
| 409 | <para>The plot string can have its format changed through several string_modifiers. | |
| 410 | String_modifiers are described in the description of the | |
| 411 | <command remap='Ic'>plot</command> | |
| 412 | command.</para> | |
| 413 | ||
| 414 | <para>The standard defines file includes several macros useful as plot strings, | |
| 415 | including | |
| 416 | <command remap='Ic'>bullet</command>, | |
| 417 | <command remap='Ic'>square</command>, | |
| 418 | and | |
| 419 | <command remap='Ic'>delta</command>.</para> | |
| 420 | ||
| 421 | <para><command remap='Ic'>new</command> | |
| 422 | is a synonym for | |
| 423 | <command remap='Ic'>draw</command>.</para> | |
| 424 | ||
| 425 | <para><command remap='Ic'>next</command> | |
| 426 | <replaceable>line_name</replaceable> | |
| 427 | <command>at</command> | |
| 428 | <replaceable>coordinates_name</replaceable> | |
| 429 | <replaceable>expr</replaceable>, <replaceable>expr</replaceable> | |
| 430 | <replaceable>line_description</replaceable> | |
| 431 | The | |
| 432 | <command remap='Ic'>next</command> | |
| 433 | command plots the given point using the line style given by | |
| 434 | <replaceable>line_name</replaceable>, | |
| 435 | or the default if none is given. If | |
| 436 | <replaceable>line_name</replaceable> | |
| 437 | is given, it should have been defined by an earlier | |
| 438 | <command remap='Ic'>draw</command> | |
| 439 | command, if not a new line style with that name is created, | |
| 440 | initialized the same way as the default style. The two expressions | |
| 441 | give the point's x and y values, relative to the optional coordinate | |
| 442 | system. That system should have been defined by an earlier | |
| 443 | <command remap='Ic'>coord</command> | |
| 444 | command, if not, grap will exit. If the optional | |
| 445 | <replaceable>line_description</replaceable> | |
| 446 | is given, it overrides the style's default line description. You | |
| 447 | cannot over-ride the plotting string. To use a different plotting | |
| 448 | string use the | |
| 449 | <command remap='Ic'>plot</command> | |
| 450 | command.</para> | |
| 451 | ||
| 452 | <para>The coordinates may optionally be enclosed in parentheses: | |
| 453 | (<replaceable>expr</replaceable>, <replaceable>expr</replaceable>)</para> | |
| 454 | ||
| 455 | <para><replaceable>quoted_string</replaceable> | |
| 456 | <replaceable>string_modifiers</replaceable> | |
| 457 | [, <replaceable>quoted_string</replaceable> [<replaceable>string_modifiers</replaceable>] | |
| 458 | ] | |
| 459 | ... | |
| 460 | <command>at</command> | |
| 461 | <replaceable>coordinates_name</replaceable> | |
| 462 | <replaceable>expr</replaceable>, <replaceable>expr</replaceable></para> | |
| 463 | ||
| 464 | <para><command remap='Ic'>plot</command> | |
| 465 | <replaceable>expr</replaceable> | |
| 466 | <replaceable>format_string</replaceable> | |
| 467 | <command>at</command> | |
| 468 | <replaceable>coordinates_name</replaceable> | |
| 469 | <replaceable>expr</replaceable>, <replaceable>expr</replaceable> | |
| 470 | These commands both plot a string at the given point. In the first | |
| 471 | case the literal strings are stacked above each other. The string_modifiers | |
| 472 | include the | |
| 473 | <citerefentry><refentrytitle>pic</refentrytitle></citerefentry> | |
| 474 | justification modifiers | |
| 475 | , (<command remap='Ic'>ljust</command> | |
| 476 | <command remap='Ic'>rjust</command>, | |
| 477 | <command remap='Ic'>above</command>, | |
| 478 | and | |
| 479 | <command remap='Ic'>below</command>), | |
| 480 | and absolute and relative | |
| 481 | <literal>size</literal> | |
| 482 | modifiers. See the | |
| 483 | <citerefentry><refentrytitle>pic</refentrytitle></citerefentry> | |
| 484 | documentation for the description of the justification modifiers. | |
| 485 | <command remap='Nm'> grap </command> | |
| 486 | also supports the | |
| 487 | <command remap='Ic'>aligned</command> | |
| 488 | and | |
| 489 | <command remap='Ic'>unaligned</command> | |
| 490 | modifiers which are briefly noted in the description of the | |
| 491 | <command remap='Ic'>label</command> | |
| 492 | command.</para> | |
| 493 | ||
| 494 | <para>The standard defines file includes several macros useful as plot strings, | |
| 495 | including | |
| 496 | <command remap='Ic'>bullet</command>, | |
| 497 | <command remap='Ic'>square</command>, | |
| 498 | and | |
| 499 | <command remap='Ic'>delta</command>.</para> | |
| 500 | ||
| 501 | <para>Strings placed by either format of the | |
| 502 | <command remap='Ic'>plot</command> | |
| 503 | command are restricted to being within the frame. This can be overridden by | |
| 504 | using the | |
| 505 | <command remap='Ic'>unclipped</command> | |
| 506 | attribute, which allows a string to be plotted in or out of the frame. The | |
| 507 | <option>-c</option> | |
| 508 | and | |
| 509 | <option>-C</option> | |
| 510 | flags set | |
| 511 | <command remap='Ic'>unclipped</command> | |
| 512 | on all strings, and to prevent a string from being plotted outside the frame | |
| 513 | when those flags are active, the | |
| 514 | <command remap='Ic'>clipped</command> | |
| 515 | attribute can be used to retore clipping behavior. Though | |
| 516 | <command remap='Ic'>clipped</command> | |
| 517 | or | |
| 518 | <command remap='Ic'>unclipped</command> | |
| 519 | can be applied to any string, it only has meaning for | |
| 520 | <command remap='Ic'>plot</command> | |
| 521 | statements.</para> | |
| 522 | ||
| 523 | <para><literal>size</literal> | |
| 524 | <replaceable>expr</replaceable> | |
| 525 | sets the string size to | |
| 526 | <replaceable>expr</replaceable> | |
| 527 | points. If | |
| 528 | <replaceable>expr</replaceable> | |
| 529 | is preceded by a + or -, the size is increased or decreased by that | |
| 530 | many points.</para> | |
| 531 | ||
| 532 | <para>If | |
| 533 | <command remap='Ic'>color</command> | |
| 534 | and a color name in double quotes appears, the string will be rendered in that | |
| 535 | color under a version of GNU troff that supports color. Color is not available | |
| 536 | in compatibility mode.</para> | |
| 537 | ||
| 538 | <para>In the second version, the | |
| 539 | <replaceable>expr</replaceable> | |
| 540 | is converted to a string and placed on the graph. | |
| 541 | <replaceable>format_string</replaceable> | |
| 542 | is a | |
| 543 | <citerefentry><refentrytitle>printf</refentrytitle><manvolnum>3</manvolnum></citerefentry> | |
| 544 | format string. Only formatting escapes for printing | |
| 545 | floating point numbers make sense. The format string is only respected | |
| 546 | if the | |
| 547 | <command remap='Ic'>sprintf</command> | |
| 548 | command is also active. See the description of | |
| 549 | <command remap='Ic'>sprintf</command> | |
| 550 | for the various ways to disable it. | |
| 551 | <command remap='Ic'>Plot</command> | |
| 552 | and | |
| 553 | <command remap='Ic'>sprintf</command> | |
| 554 | respond differently when | |
| 555 | <command remap='Nm'> grap </command> | |
| 556 | is running safely. | |
| 557 | <command remap='Ic'>Sprintf</command> | |
| 558 | ignores any arguments, passing the format string through without | |
| 559 | substitution. | |
| 560 | <command remap='Ic'>plot</command> | |
| 561 | ignores the format string completely, plotting | |
| 562 | <replaceable>expr</replaceable> | |
| 563 | using the | |
| 564 | "%g" | |
| 565 | format.</para> | |
| 566 | ||
| 567 | <para>Points are specified the same way as for | |
| 568 | <command remap='Ic'>next</command> | |
| 569 | commands, with the same consequences for undefined coordinate systems.</para> | |
| 570 | ||
| 571 | <para>The second form of this command is because the first form can be used | |
| 572 | with a | |
| 573 | <command remap='Nm'> grap </command> | |
| 574 | <command remap='Ic'>sprintf</command> | |
| 575 | expression (See | |
| 576 | <link linkend='expressions'>Expressions</link>).</para> | |
| 577 | ||
| 578 | <para><command remap='Ic'>ticks</command> | |
| 579 | <!-- blank --> | |
| 580 | (<command>left</command> | <command>right</command> | <command>top</command> | <command>bottom</command>) | |
| 581 | [Smon(<command>in</command>|<command>out</command>)<replaceable>expr</replaceable>] | |
| 582 | <!-- blank --> | |
| 583 | [<command>on|autoSmon</command><replaceable>coord_name</replaceable>]</para> | |
| 584 | ||
| 585 | <para><command remap='Ic'>ticks</command> | |
| 586 | <!-- blank --> | |
| 587 | (<command>left</command> | <command>right</command> | <command>top</command> | <command>bottom</command>) | |
| 588 | <!-- blank --> | |
| 589 | (<command>in</command>|<command>out</command>) | |
| 590 | <replaceable>expr</replaceable> | |
| 591 | [<command>up</command> <replaceable>expr</replaceable> | <command>down</command> <replaceable>expr</replaceable> | <command>left</command> <replaceable>expr</replaceable> | <command>right</command> <replaceable>expr</replaceable>] | |
| 592 | <command>at</command> | |
| 593 | <replaceable>coord_name</replaceable> | |
| 594 | <replaceable>expr</replaceable> | |
| 595 | <replaceable>format_string</replaceable> | |
| 596 | [[, <replaceable>expr</replaceable> [<replaceable>format_string</replaceable>] | |
| 597 | ] | |
| 598 | ||
| 599 | ]</para> | |
| 600 | ||
| 601 | <para><command remap='Ic'>ticks</command> | |
| 602 | <!-- blank --> | |
| 603 | (<command>left</command> | <command>right</command> | <command>top</command> | <command>bottom</command>) | |
| 604 | <!-- blank --> | |
| 605 | (<command>in</command>|<command>out</command>) | |
| 606 | <replaceable>expr</replaceable> | |
| 607 | [<command>up</command> <replaceable>expr</replaceable> | <command>down</command> <replaceable>expr</replaceable> | <command>left</command> <replaceable>expr</replaceable> | <command>right</command> <replaceable>expr</replaceable>] | |
| 608 | <command>from</command> | |
| 609 | [coord_name] | |
| 610 | <replaceable>start_expr</replaceable> | |
| 611 | <command>to</command> | |
| 612 | <replaceable>end_expr</replaceable> | |
| 613 | [<command>by</command> <command>Sm</command> <command>off</command> [+ | - | * | / Sm on] | |
| 614 | <replaceable>by_expr</replaceable> | |
| 615 | ] | |
| 616 | [format_string]</para> | |
| 617 | ||
| 618 | <para><command remap='Ic'>ticks</command> | |
| 619 | <!-- blank --> | |
| 620 | [<command>left</command> | <command>right</command> | <command>top</command> | <command>bottom</command>] | |
| 621 | <!-- blank --> | |
| 622 | <command>off</command> | |
| 623 | This command controls the placement of ticks on the frame. By | |
| 624 | default, ticks are automatically generated on the left and bottom | |
| 625 | sides of the frame.</para> | |
| 626 | ||
| 627 | <para>The first version of this command turns on the automatic tick | |
| 628 | generation for a given side. The | |
| 629 | <command>in</command> | |
| 630 | or | |
| 631 | <command>out</command> | |
| 632 | parameter controls the direction and length of the ticks. If a | |
| 633 | <replaceable>coord_name</replaceable> | |
| 634 | is specified, the ticks are automatically generated using that | |
| 635 | coordinate system. If no system is specified, the default coordinate | |
| 636 | system is used. As with | |
| 637 | <command remap='Ic'>next</command> | |
| 638 | and | |
| 639 | <command remap='Ic'>plot</command>, | |
| 640 | the coordinate system must be declared before the | |
| 641 | <command remap='Ic'>ticks</command> | |
| 642 | statement that references it. This syntax for requesting | |
| 643 | automatically generated ticks is an extension, and will not port to | |
| 644 | older | |
| 645 | <command remap='Nm'> grap </command> | |
| 646 | implementations.</para> | |
| 647 | ||
| 648 | <para>The second version of the | |
| 649 | <command remap='Ic'>ticks</command> | |
| 650 | command overrides the automatic placement of the ticks by specifying | |
| 651 | a list of coordinates at which to place the ticks. If the ticks are | |
| 652 | not defined with respect to the default coordinate system, the | |
| 653 | <replaceable>coord_name</replaceable> | |
| 654 | parameter must be given. For each tick a | |
| 655 | <citerefentry><refentrytitle>printf</refentrytitle><manvolnum>3</manvolnum></citerefentry> | |
| 656 | style format string can be given. The | |
| 657 | <replaceable>format_string</replaceable> | |
| 658 | defaults to | |
| 659 | "%g". | |
| 660 | The format string can also take string modifiers as described in the | |
| 661 | <command remap='Ic'>plot</command> | |
| 662 | command. | |
| 663 | To place ticks with no labels, specify | |
| 664 | <replaceable>format_string</replaceable> | |
| 665 | as | |
| 666 | "".</para> | |
| 667 | ||
| 668 | <para>If | |
| 669 | <command remap='Ic'>sprintf</command> | |
| 670 | is disabled, | |
| 671 | <command remap='Ic'>ticks</command> | |
| 672 | behaves as | |
| 673 | <command remap='Ic'>plot</command> | |
| 674 | with respect to the format string.</para> | |
| 675 | ||
| 676 | <para>The labels on the ticks may be shifted by specifying a direction and | |
| 677 | the distance in inches to offset the label. That is the optional | |
| 678 | direction and expression immediately preceding the | |
| 679 | <command>at</command>.</para> | |
| 680 | ||
| 681 | <para>The third format of the | |
| 682 | <command remap='Ic'>ticks</command> | |
| 683 | command over-rides the default tick generation with a set of ticks ar | |
| 684 | regular intervals. The syntax is reminiscent of programming | |
| 685 | language for loops. Ticks are placed starting at | |
| 686 | <replaceable>start_expr</replaceable> | |
| 687 | ending at | |
| 688 | <replaceable>end_expr</replaceable> | |
| 689 | one unit apart. If the | |
| 690 | <command>by</command> | |
| 691 | clause is specified, ticks are | |
| 692 | <replaceable>by_expr</replaceable> | |
| 693 | units apart. If an operator appears before | |
| 694 | <replaceable>by_expr</replaceable> | |
| 695 | each tick is operated on by that operator instead of +. For example</para> | |
| 696 | <programlisting remap='Bd'> | |
| 697 | ticks left out from 2 to 32 by *2 | |
| 698 | </programlisting> <!-- remap='Ed (block)' --> | |
| 699 | ||
| 700 | <para>will put ticks at 2, 4, 8, 16, and 32. If | |
| 701 | <replaceable>format_string</replaceable> | |
| 702 | is specified, all ticks are formatted using it.</para> | |
| 703 | ||
| 704 | <para>The parameters preceding the | |
| 705 | <command>from</command> | |
| 706 | act as described above.</para> | |
| 707 | ||
| 708 | <para>The | |
| 709 | <command>at</command> | |
| 710 | and | |
| 711 | <command>for</command> | |
| 712 | forms of tick command may both be issued on the same | |
| 713 | side of a frame. For example:</para> | |
| 714 | <programlisting remap='Bd'> | |
| 715 | ticks left out from 2 to 32 by *2 | |
| 716 | ticks left in 3, 5, 7 | |
| 717 | </programlisting> <!-- remap='Ed (block)' --> | |
| 718 | ||
| 719 | <para>will put ticks on the left side of the frame pointing out at 2, 4, 8, | |
| 720 | 16, and 32 and in at 3, 5, and 7.</para> | |
| 721 | ||
| 722 | <para>The final form of | |
| 723 | <command remap='Ic'>ticks</command> | |
| 724 | turns off ticks on a given side. If no side is given the ticks for | |
| 725 | all sides are cancelled.</para> | |
| 726 | ||
| 727 | <para><command remap='Ic'>tick</command> | |
| 728 | is a synonym for | |
| 729 | <command remap='Ic'>ticks</command>.</para> | |
| 730 | ||
| 731 | <para><command remap='Ic'>grid</command> | |
| 732 | <!-- blank --> | |
| 733 | (<command>left</command> | <command>right</command> | <command>top</command> | <command>bottom</command>) | |
| 734 | <!-- blank --> | |
| 735 | <literal>ticks</literal> <literal>off</literal> | |
| 736 | <replaceable>line_description</replaceable> | |
| 737 | [<command>up</command> <replaceable>expr</replaceable> | <command>down</command> <replaceable>expr</replaceable> | <command>left</command> <replaceable>expr</replaceable> | <command>right</command> <replaceable>expr</replaceable>] | |
| 738 | [Sm off <command>on</command> <command>|</command> <command>auto</command> <command>Sm</command> <command>on</command> <replaceable>coord_name</replaceable>]</para> | |
| 739 | ||
| 740 | <para><command remap='Ic'>grid</command> | |
| 741 | <!-- blank --> | |
| 742 | (<command>left</command> | <command>right</command> | <command>top</command> | <command>bottom</command>) | |
| 743 | <!-- blank --> | |
| 744 | <literal>ticks</literal> <literal>off</literal> | |
| 745 | <replaceable>line_description</replaceable> | |
| 746 | [<command>up</command> <replaceable>expr</replaceable> | <command>down</command> <replaceable>expr</replaceable> | <command>left</command> <replaceable>expr</replaceable> | <command>right</command> <replaceable>expr</replaceable>] | |
| 747 | <command>at</command> | |
| 748 | <replaceable>coord_name</replaceable> | |
| 749 | <replaceable>expr</replaceable> | |
| 750 | <replaceable>format_string</replaceable> | |
| 751 | [[, <replaceable>expr</replaceable> [<replaceable>format_string</replaceable>] | |
| 752 | ] | |
| 753 | ||
| 754 | ]</para> | |
| 755 | ||
| 756 | <para><command remap='Ic'>grid</command> | |
| 757 | <!-- blank --> | |
| 758 | (<command>left</command> | <command>right</command> | <command>top</command> | <command>bottom</command>) | |
| 759 | <!-- blank --> | |
| 760 | <literal>ticks</literal> <literal>off</literal> | |
| 761 | <replaceable>line_description</replaceable> | |
| 762 | [<command>up</command> <replaceable>expr</replaceable> | <command>down</command> <replaceable>expr</replaceable> | <command>left</command> <replaceable>expr</replaceable> | <command>right</command> <replaceable>expr</replaceable>] | |
| 763 | <command>from</command> | |
| 764 | [coord_name] | |
| 765 | <replaceable>start_expr</replaceable> | |
| 766 | <command>to</command> | |
| 767 | <replaceable>end_expr</replaceable> | |
| 768 | [<command>by</command> <command>Sm</command> <command>off</command> [+ | - | * | / Sm on] | |
| 769 | <replaceable>by_expr</replaceable> | |
| 770 | ] | |
| 771 | [format_string] | |
| 772 | The | |
| 773 | <command remap='Ic'>grid</command> | |
| 774 | command is similar to the | |
| 775 | <command remap='Ic'>ticks</command> | |
| 776 | command except that | |
| 777 | <command remap='Ic'>grid</command> | |
| 778 | specifies the placement of lines in the frame. The syntax is similar | |
| 779 | to | |
| 780 | <command remap='Ic'>ticks</command> | |
| 781 | as well.</para> | |
| 782 | ||
| 783 | <para>By specifying | |
| 784 | <literal>ticks</literal> <literal>off</literal> | |
| 785 | in the command, no ticks are drawn on that side of the frame. If | |
| 786 | ticks appear on a side by default, or have been declared by an earlier | |
| 787 | <command remap='Ic'>ticks</command> | |
| 788 | command, | |
| 789 | <command remap='Ic'>grid</command> | |
| 790 | does not cancel them unless | |
| 791 | <literal>ticks</literal> <literal>off</literal> | |
| 792 | is specified.</para> | |
| 793 | ||
| 794 | <para>Instead of a direction for ticks, | |
| 795 | <command remap='Ic'>grid</command> | |
| 796 | allows the user to pick a line description for the grid lines. The | |
| 797 | usual | |
| 798 | <citerefentry><refentrytitle>pic</refentrytitle></citerefentry> | |
| 799 | line descriptions are allowed.</para> | |
| 800 | ||
| 801 | <para>Grids are labelled by default. To omit labels, specify the format | |
| 802 | string as | |
| 803 | "".</para> | |
| 804 | ||
| 805 | <para>If | |
| 806 | <command remap='Ic'>sprintf</command> | |
| 807 | is disabled, | |
| 808 | <command remap='Ic'>grid</command> | |
| 809 | behaves as | |
| 810 | <command remap='Ic'>plot</command> | |
| 811 | with respect to the format string.</para> | |
| 812 | ||
| 813 | <para><command remap='Ic'>label</command> | |
| 814 | <!-- blank --> | |
| 815 | (<command>left</command> | <command>right</command> | <command>top</command> | <command>bottom</command>) | |
| 816 | <!-- blank --> | |
| 817 | <replaceable>quoted_string</replaceable> | |
| 818 | <replaceable>string_modifiers</replaceable> | |
| 819 | [, <replaceable>quoted_string</replaceable> [<replaceable>string_modifiers</replaceable>] | |
| 820 | ] | |
| 821 | ... | |
| 822 | [<command>up</command> <replaceable>expr</replaceable> | <command>down</command> <replaceable>expr</replaceable> | <command>left</command> <replaceable>expr</replaceable> | <command>right</command> <replaceable>expr</replaceable>] | |
| 823 | The | |
| 824 | <command remap='Ic'>label</command> | |
| 825 | command places a label on the given axis. It is possible to specify | |
| 826 | several labels, which will be stacked over each other as in | |
| 827 | <citerefentry><refentrytitle>pic</refentrytitle></citerefentry>. | |
| 828 | The final argument, if present, specifies how many inches the label is | |
| 829 | shifted from the axis.</para> | |
| 830 | ||
| 831 | <para>By default the labels on the left and right labels run parallel to the | |
| 832 | frame. You can cancel this by specifying | |
| 833 | <literal>unaligned</literal> | |
| 834 | as a | |
| 835 | <replaceable>string_modifier</replaceable>.</para> | |
| 836 | ||
| 837 | <para><command remap='Ic'>circle</command> | |
| 838 | <command>at</command> | |
| 839 | <replaceable>coordinate_name</replaceable> | |
| 840 | <replaceable>expr</replaceable>, <replaceable>expr</replaceable> | |
| 841 | <command>radius</command> <replaceable>expr</replaceable> | |
| 842 | <replaceable>linedesc</replaceable> | |
| 843 | This draws an circle at the point indicated. By default, the | |
| 844 | circle is small, 0.025 inches. This can be over-ridden by specifying | |
| 845 | a radius. The coordinates of the point are relative to the named | |
| 846 | coordinate system, or the default system if none is specified.</para> | |
| 847 | ||
| 848 | <para>This command has been extended to take a line description, | |
| 849 | e.g., | |
| 850 | <literal>dotted</literal>. | |
| 851 | It also accepts the filling extensions described below in the | |
| 852 | <command remap='Ic'>bar</command> | |
| 853 | command. It will also accept a | |
| 854 | <command remap='Ic'>color</command> | |
| 855 | keyword that gives the color of the outline of the circle in double | |
| 856 | quotes and a | |
| 857 | <command remap='Ic'>fillcolor</command> | |
| 858 | command that sets the color to fill the circle with similarly. Colors | |
| 859 | are only available when compatibility mode is off, and using a version | |
| 860 | of GNU pic that supports color.</para> | |
| 861 | ||
| 862 | <para><command remap='Ic'>line</command> | |
| 863 | <replaceable>line_description</replaceable> | |
| 864 | <command>from</command> | |
| 865 | <replaceable>coordinate_name</replaceable> | |
| 866 | <replaceable>expr</replaceable>, <replaceable>expr</replaceable> | |
| 867 | <command>to</command> | |
| 868 | <replaceable>coordinate_name</replaceable> | |
| 869 | <replaceable>expr</replaceable>, <replaceable>expr</replaceable> | |
| 870 | <replaceable>line_description</replaceable></para> | |
| 871 | ||
| 872 | <para><command remap='Ic'>arrow</command> | |
| 873 | <replaceable>line_description</replaceable> | |
| 874 | <command>from</command> | |
| 875 | <replaceable>coordinate_name</replaceable> | |
| 876 | <replaceable>expr</replaceable>, <replaceable>expr</replaceable> | |
| 877 | <command>to</command> | |
| 878 | <replaceable>coordinate_name</replaceable> | |
| 879 | <replaceable>expr</replaceable>, <replaceable>expr</replaceable> | |
| 880 | <replaceable>line_description</replaceable> | |
| 881 | This draws a line or arrow from the first point to the second using | |
| 882 | the given style. The default line style is | |
| 883 | <literal>solid</literal>. | |
| 884 | The | |
| 885 | <replaceable>line_description</replaceable> | |
| 886 | can be given either before the | |
| 887 | <command>from</command> | |
| 888 | or after the | |
| 889 | <command>to</command> | |
| 890 | clause. If both are given the second is used. It is possible to | |
| 891 | specify one point in one coordinate system and one in another, note | |
| 892 | that if both points are in a named coordinate system (even if they are | |
| 893 | in the same named coordinate system), both points must have | |
| 894 | <replaceable>coordinate_name</replaceable> | |
| 895 | given.</para> | |
| 896 | ||
| 897 | ||
| 898 | <para><command remap='Ic'>copy</command> | |
| 899 | "Ar filename" | |
| 900 | <command>until</command> "Ar string" | |
| 901 | <command>thru</command> <replaceable>macro</replaceable> | |
| 902 | The | |
| 903 | <command remap='Ic'>copy</command> | |
| 904 | command imports data from another file into the current graph. The | |
| 905 | form with only a filename given is a simple file inclusion; the | |
| 906 | included file is simply read into the input stream and can contain | |
| 907 | arbitrary | |
| 908 | <command remap='Nm'> grap </command> | |
| 909 | commands. The more common case is that it is a number list; see | |
| 910 | <link role='Sx' linkend='number_lists'>Number Lists</link> | |
| 911 | below.</para> | |
| 912 | ||
| 913 | <para>The second form takes lines from the file, splits them into words | |
| 914 | delimited by one or more spaces, and calls the given macro with those | |
| 915 | words as parameters. The macro may either be defined here, or be a | |
| 916 | macro defined earlier. See | |
| 917 | <link linkend='macros'>Macros</link> | |
| 918 | for more information on macros.</para> | |
| 919 | ||
| 920 | <para>The | |
| 921 | <replaceable>filename</replaceable> | |
| 922 | may be omitted if the | |
| 923 | <command>until</command> | |
| 924 | clause is present. If so the current file is treated as the input | |
| 925 | file until | |
| 926 | <replaceable>string</replaceable> | |
| 927 | is encountered at the beginning of the line.</para> | |
| 928 | ||
| 929 | <para><command remap='Ic'>copy</command> | |
| 930 | is one of the workhorses of | |
| 931 | <command remap='Nm'> grap </command> | |
| 932 | Check out the paper and | |
| 933 | <filename>/usr/local/share/examples/grap</filename> | |
| 934 | for more details. Confirm the location of the examples directory using the | |
| 935 | <option>-v</option> | |
| 936 | flag.</para> | |
| 937 | <para><command remap='Ic'>print</command> | |
| 938 | <!-- blank --> | |
| 939 | (<replaceable>expr|string</replaceable>) | |
| 940 | <!-- blank --> | |
| 941 | Prints its argument to the standard error.</para> | |
| 942 | ||
| 943 | <para><command remap='Ic'>sh</command> <replaceable>block</replaceable> | |
| 944 | This passes | |
| 945 | <replaceable>block</replaceable> | |
| 946 | to | |
| 947 | <citerefentry><refentrytitle>sh</refentrytitle><manvolnum>1</manvolnum></citerefentry>. | |
| 948 | Unlike K&B | |
| 949 | <command remap='Nm'> grap </command> | |
| 950 | no macro or variable expansion is done. I believe that this is also | |
| 951 | true for GNU | |
| 952 | <citerefentry><refentrytitle>pic</refentrytitle></citerefentry> | |
| 953 | version 1.10. See the | |
| 954 | <link linkend='macros'>Macros</link> | |
| 955 | section for information on defining blocks.</para> | |
| 956 | ||
| 957 | <para><command remap='Ic'>pic</command> <replaceable>pic_statement</replaceable> | |
| 958 | This issues the given | |
| 959 | <citerefentry><refentrytitle>pic</refentrytitle></citerefentry> | |
| 960 | statements in the enclosing | |
| 961 | <command remap='Ic'>.PS</command> | |
| 962 | and | |
| 963 | <command remap='Ic'>.PE</command> | |
| 964 | at the point where the command is issued.</para> | |
| 965 | ||
| 966 | <para>Statements that begin with a period are considered to be | |
| 967 | <citerefentry><refentrytitle>troff</refentrytitle><manvolnum>statements</manvolnum></citerefentry> | |
| 968 | and are output in the enclosing | |
| 969 | <command remap='Ic'>.PS</command> | |
| 970 | and | |
| 971 | <command remap='Ic'>.PE</command> | |
| 972 | at the point where the command appears.</para> | |
| 973 | ||
| 974 | <para>For the purposes of relative placement of | |
| 975 | <citerefentry><refentrytitle>pic</refentrytitle></citerefentry> | |
| 976 | or | |
| 977 | <citerefentry><refentrytitle>troff</refentrytitle></citerefentry> | |
| 978 | commands, the frame is output immediately before the first plotted | |
| 979 | object, or the | |
| 980 | <command remap='Ic'>frame</command> | |
| 981 | statement, if any. If the user specifies | |
| 982 | <citerefentry><refentrytitle>pic</refentrytitle></citerefentry> | |
| 983 | or | |
| 984 | <citerefentry><refentrytitle>troff</refentrytitle></citerefentry> | |
| 985 | commands and neither any plotable object nor a | |
| 986 | <command remap='Ic'>frame</command> | |
| 987 | command, the commands will not be output.</para> | |
| 988 | ||
| 989 | <para><command remap='Ic'>graph</command> <replaceable>Name</replaceable> <replaceable>pic_commands</replaceable> | |
| 990 | This command is used to position graphs with respect to each other. | |
| 991 | The current graph is given the | |
| 992 | <citerefentry><refentrytitle>pic</refentrytitle></citerefentry> | |
| 993 | name | |
| 994 | <replaceable>Name</replaceable> | |
| 995 | (names used by | |
| 996 | <citerefentry><refentrytitle>pic</refentrytitle></citerefentry> | |
| 997 | begin with capital letters). Any | |
| 998 | <citerefentry><refentrytitle>pic</refentrytitle></citerefentry> | |
| 999 | commands following the graph are used to position the next graph. The | |
| 1000 | frame of the graph is available for use with | |
| 1001 | <citerefentry><refentrytitle>pic</refentrytitle></citerefentry> | |
| 1002 | name | |
| 1003 | <literal>Frame.</literal> | |
| 1004 | The following places a second graph below the first:</para> | |
| 1005 | <programlisting remap='Bd'> | |
| 1006 | graph Linear | |
| 1007 | [ graph description ] | |
| 1008 | <funcsynopsis> | |
| 1009 | <funcsynopsisinfo> | |
| 1010 | graph Exponential with .Frame.n at \ | |
| 1011 | </funcsynopsisinfo> | |
| 1012 | </funcsynopsis> | |
| 1013 | Linear.Frame.s - (0, .05) | |
| 1014 | [ graph description ] | |
| 1015 | </programlisting> <!-- remap='Ed (block)' --> | |
| 1016 | ||
| 1017 | <para><replaceable>name</replaceable> <replaceable>=</replaceable> <replaceable>expr</replaceable> | |
| 1018 | This assigns | |
| 1019 | <replaceable>expr</replaceable> | |
| 1020 | to the variable | |
| 1021 | <replaceable>name</replaceable>. | |
| 1022 | <command remap='Nm'> grap </command> | |
| 1023 | has only numeric (double) variables.</para> | |
| 1024 | ||
| 1025 | <para>Assignment creates a variable if it does not exist. Variables persist | |
| 1026 | across graphs. Assignments can cascade; | |
| 1027 | <literal>a</literal> <literal>=</literal> <literal>b</literal> <literal>=</literal> <literal>35</literal> | |
| 1028 | assigns 35 to | |
| 1029 | <literal>a</literal> | |
| 1030 | and | |
| 1031 | <literal>b</literal>.</para> | |
| 1032 | ||
| 1033 | <para><command remap='Ic'>bar</command> | |
| 1034 | <!-- blank --> | |
| 1035 | ()<command>up</command> | <command>right</command> | |
| 1036 | <!-- blank --> | |
| 1037 | <replaceable>coordinates_name</replaceable> | |
| 1038 | <replaceable>offset</replaceable> | |
| 1039 | <command>ht</command> | |
| 1040 | <replaceable>height</replaceable> | |
| 1041 | <command>wid</command> <replaceable>width</replaceable> | |
| 1042 | <command>base</command> <replaceable>base_offset</replaceable> | |
| 1043 | <replaceable>line_description</replaceable></para> | |
| 1044 | ||
| 1045 | <para><command remap='Ic'>bar</command> | |
| 1046 | <replaceable>coordinates_name</replaceable> | |
| 1047 | <replaceable>expr</replaceable>, <replaceable>expr</replaceable>, | |
| 1048 | <replaceable>coordinates_name</replaceable> | |
| 1049 | <replaceable>expr</replaceable>, <replaceable>expr</replaceable>, | |
| 1050 | <replaceable>line_description</replaceable> | |
| 1051 | The | |
| 1052 | <command remap='Ic'>bar</command> | |
| 1053 | command facilitates drawing bar graphs. The first form of the | |
| 1054 | command describes the bar somewhat generally and has | |
| 1055 | <command remap='Nm'> grap </command> | |
| 1056 | place it. | |
| 1057 | The bar may extend up or to the right, is centered on | |
| 1058 | <replaceable>offset</replaceable> | |
| 1059 | and extends up or right | |
| 1060 | <replaceable>height</replaceable> | |
| 1061 | units (in the given coordinate system). For example</para> | |
| 1062 | <programlisting remap='Bd'> | |
| 1063 | bar up 3 ht 2 | |
| 1064 | </programlisting> <!-- remap='Ed (block)' --> | |
| 1065 | ||
| 1066 | <para>draws a 2 unit high bar sitting on the x axis, centered on x=3. By | |
| 1067 | default bars are 1 unit wide, but this can be changed with the | |
| 1068 | <command remap='Ic'>wid</command> | |
| 1069 | keyword. By default bars sit on the base axis, i.e., bars directed up | |
| 1070 | will extend from y=0. That may be overridden by the | |
| 1071 | <command remap='Ic'>base</command> | |
| 1072 | keyword. (The bar described above has corners (2.5, 0) and (3.5, 2).)</para> | |
| 1073 | ||
| 1074 | <para>The line description has been extended to include a | |
| 1075 | <command remap='Ic'>fill</command> <replaceable>expr</replaceable> | |
| 1076 | keyword that specifies the shading inside the bar. Bars may be drawn | |
| 1077 | in any line style. They support the | |
| 1078 | <command remap='Ic'>color</command> | |
| 1079 | and | |
| 1080 | <command remap='Ic'>fillcolor</command> | |
| 1081 | keywords described under | |
| 1082 | <command remap='Ic'>circle</command>.</para> | |
| 1083 | ||
| 1084 | <para>The second form of the command draws a box with the two points as | |
| 1085 | corners. This can be used to draw boxes highlighting certain data as | |
| 1086 | well as bar graphs. Note that filled bars will cover data drawn under | |
| 1087 | them.</para> | |
| 1088 | </refsect2> | |
| 1089 | ||
| 1090 | <refsect2 id='control_flow'><title>Control Flow</title> | |
| 1091 | ||
| 1092 | <para><command remap='Ic'>if</command> <replaceable>expr</replaceable> <command remap='Ic'>then</command> <replaceable>block</replaceable> | |
| 1093 | <command remap='Ic'>else</command> <replaceable>block</replaceable> | |
| 1094 | The | |
| 1095 | <command remap='Ic'>if</command> | |
| 1096 | statement provides simple conditional execution. If | |
| 1097 | <replaceable>expr</replaceable> | |
| 1098 | is non-zero, the | |
| 1099 | <replaceable>block</replaceable> | |
| 1100 | after the | |
| 1101 | <command remap='Ic'>then</command> | |
| 1102 | statement is executed. If not the | |
| 1103 | <replaceable>block</replaceable> | |
| 1104 | after the | |
| 1105 | <command remap='Ic'>else</command> | |
| 1106 | is executed, if present. See | |
| 1107 | <link linkend='macros'>Macros</link> | |
| 1108 | for the definition of blocks. Early versions of this implementation | |
| 1109 | of | |
| 1110 | <command remap='Nm'> grap </command> | |
| 1111 | treated the blocks as macros that were defined and expanded in place. | |
| 1112 | This led to unnecessary confusion because explicit separators were | |
| 1113 | sometimes called for. Now, | |
| 1114 | <command remap='Nm'> grap </command> | |
| 1115 | inserts a separator (;) after the last character in | |
| 1116 | <replaceable>block</replaceable>, | |
| 1117 | so constructs like</para> | |
| 1118 | <programlisting remap='Bd'> | |
| 1119 | if (x == 3) { y = y + 1 } | |
| 1120 | x = x + 1 | |
| 1121 | ||
| 1122 | </programlisting> <!-- remap='Ed (block)' --> | |
| 1123 | <para>behave as expected. A separator is also appended to the end of a | |
| 1124 | <command remap='Ic'>for</command> | |
| 1125 | block.</para> | |
| 1126 | ||
| 1127 | <para><command remap='Ic'>for</command> <replaceable>name</replaceable> <command remap='Ic'>from</command> <replaceable>from_expr</replaceable> <command remap='Ic'>to</command> <replaceable>to_expr</replaceable> | |
| 1128 | [<command remap='Ic'>by</command> +|-|*|/ <replaceable>by_expr</replaceable>] | |
| 1129 | <command remap='Ic'>do</command> | |
| 1130 | <replaceable>block</replaceable> | |
| 1131 | This command executes | |
| 1132 | <replaceable>block</replaceable> | |
| 1133 | iteratively. The variable | |
| 1134 | <replaceable>name</replaceable> | |
| 1135 | is set to | |
| 1136 | <replaceable>from_expr</replaceable> | |
| 1137 | and incremented by | |
| 1138 | <replaceable>by_expr</replaceable> | |
| 1139 | until it exceeds | |
| 1140 | <replaceable>to_expr</replaceable>. | |
| 1141 | The iteration has the semantics defined in the | |
| 1142 | <command remap='Ic'>ticks</command> | |
| 1143 | command. The definition of | |
| 1144 | <replaceable>block</replaceable> | |
| 1145 | is discussed in | |
| 1146 | <link linkend='macros'>Macros</link>. | |
| 1147 | See also the note about implicit separators in the description of the | |
| 1148 | <command remap='Ic'>if</command> | |
| 1149 | command.</para> | |
| 1150 | ||
| 1151 | <para>An | |
| 1152 | <command remap='Ic'>=</command> | |
| 1153 | can be used in place of | |
| 1154 | <command remap='Ic'>from</command>.</para> | |
| 1155 | </refsect2> | |
| 1156 | ||
| 1157 | <refsect2 id='expressions'><title>Expressions</title> | |
| 1158 | ||
| 1159 | <para><command remap='Nm'> grap </command> | |
| 1160 | supports most standard arithmetic operators: + - / * ^. The carat | |
| 1161 | (^) is exponentiation. In an | |
| 1162 | <command remap='Ic'>if</command> | |
| 1163 | statement | |
| 1164 | <command remap='Nm'> grap </command> | |
| 1165 | also supports the C logical operators ==, !=, | |
| 1166 | &&, || and unary !. Also in an | |
| 1167 | <command remap='Ic'>if</command>, | |
| 1168 | == and != are overloaded for the comparison of | |
| 1169 | quoted strings. Parentheses are used for grouping.</para> | |
| 1170 | ||
| 1171 | <para>Assignment is not allowed in an expression in any context, except for | |
| 1172 | simple cascading of assignments. | |
| 1173 | <literal>a</literal> <literal>=</literal> <literal>b</literal> <literal>=</literal> <literal>35</literal> | |
| 1174 | works as expected; | |
| 1175 | <literal>a</literal> <literal>=</literal> <literal>3.5</literal> <literal>*</literal> <literal>(b</literal> <literal>=</literal> <literal>10)</literal> | |
| 1176 | does not execute.</para> | |
| 1177 | ||
| 1178 | <para><command remap='Nm'> grap </command> | |
| 1179 | supports the following functions that take one argument: | |
| 1180 | <command remap='Ic'>log</command>, <command remap='Ic'>exp</command>, <command remap='Ic'>int</command>, <command remap='Ic'>sin</command>, <command remap='Ic'>cos</command>, <command remap='Ic'>sqrt</command>, <command remap='Ic'>rand</command>. | |
| 1181 | The logarithms are base 10 and the trigonometric functions are in | |
| 1182 | radians. | |
| 1183 | <command remap='Ic'>eexp</command> | |
| 1184 | returns Euler's number to the given power and | |
| 1185 | <command remap='Ic'>ln</command> | |
| 1186 | returns the natural logarithm. The natural log and exponentiation | |
| 1187 | functions are extensions and are probably not available in other | |
| 1188 | <command remap='Nm'> grap </command> | |
| 1189 | implementations.</para> | |
| 1190 | ||
| 1191 | <para><command remap='Ic'>rand</command> | |
| 1192 | returns a random number uniformly | |
| 1193 | distributed on [0,1). The following two-argument functions are supported: | |
| 1194 | <command remap='Ic'>atan2</command>, <command remap='Ic'>min</command>, <command remap='Ic'>max</command>. | |
| 1195 | <command remap='Ic'>atan2</command> | |
| 1196 | works just like | |
| 1197 | <citerefentry><refentrytitle>atan2</refentrytitle><manvolnum>3</manvolnum></citerefentry>. | |
| 1198 | The random number generator can be seeded by calling | |
| 1199 | <command remap='Ic'>srand</command> | |
| 1200 | with a single parameter (converted internally to an integer). Because | |
| 1201 | its return value is of no use, you must use | |
| 1202 | <command remap='Ic'>srand</command> | |
| 1203 | as a separate statement, it is not part of a valid expression. | |
| 1204 | <command remap='Ic'>srand</command> | |
| 1205 | is not portable.</para> | |
| 1206 | ||
| 1207 | <para>The | |
| 1208 | <command remap='Ic'>getpid</command> | |
| 1209 | function takes no arguments and returns the process id. This may be | |
| 1210 | used to seed the random number generator, but do not expect | |
| 1211 | cryptographically random values to result.</para> | |
| 1212 | ||
| 1213 | <para>Other than string comparison, no expressions can use strings. One | |
| 1214 | string valued function exists: | |
| 1215 | <command remap='Ic'>sprintf</command> (, <replaceable>format</replaceable> | |
| 1216 | [<replaceable>expr</replaceable> <replaceable>,</replaceable> <replaceable>expr</replaceable>] | |
| 1217 | ). It operates like | |
| 1218 | <citerefentry><refentrytitle>sprintf</refentrytitle><manvolnum>3</manvolnum></citerefentry>, | |
| 1219 | except returning the value. It can be used anywhere a quoted string | |
| 1220 | is used. If | |
| 1221 | <command remap='Nm'> grap </command> | |
| 1222 | is run with | |
| 1223 | <option>-S</option>, | |
| 1224 | the environment variable | |
| 1225 | <envar>GRAP_SAFER</envar> | |
| 1226 | is defined, or | |
| 1227 | <command remap='Nm'> grap </command> | |
| 1228 | has been compiled for safer operation, the | |
| 1229 | <command remap='Ic'>sprintf</command> | |
| 1230 | command will return the format string. This mode of operation is only | |
| 1231 | intended to be used only if | |
| 1232 | <command remap='Nm'> grap </command> | |
| 1233 | is being used as part of a super-user enabled print system.</para> | |
| 1234 | </refsect2> | |
| 1235 | ||
| 1236 | <refsect2 id='macros'><title>Macros</title> | |
| 1237 | <para><command remap='Nm'> grap </command> | |
| 1238 | has a simple but powerful macro facility. Macros are defined using | |
| 1239 | the | |
| 1240 | <command remap='Ic'>define</command> | |
| 1241 | command :</para> | |
| 1242 | ||
| 1243 | <para><command remap='Ic'>define</command> <replaceable>name</replaceable> <replaceable>block</replaceable> | |
| 1244 | <!-- br --> | |
| 1245 | <command remap='Ic'>undefine</command> <replaceable>name</replaceable> | |
| 1246 | Every occurrence of | |
| 1247 | <replaceable>name</replaceable> | |
| 1248 | in the program text is replaced by the contents of | |
| 1249 | <replaceable>block</replaceable>. | |
| 1250 | <replaceable>block</replaceable> | |
| 1251 | is defined by a series of statements in nested { }'s, or a series of | |
| 1252 | statements surrounded by the same letter. An example of the latter is</para> | |
| 1253 | <programlisting remap='Bd'> | |
| 1254 | define foo X coord x 1,3 X | |
| 1255 | </programlisting> <!-- remap='Ed (block)' --> | |
| 1256 | <para>Each time | |
| 1257 | <literal>foo</literal> | |
| 1258 | appears in the text, it will be replaced by | |
| 1259 | <literal>coord</literal> <literal>x</literal> <literal>1,3</literal>. | |
| 1260 | Macros are literal, and can contain newlines. If a macro does not | |
| 1261 | span multiple lines, it should end in a semicolon to avoid parsing | |
| 1262 | errors.</para> | |
| 1263 | ||
| 1264 | <para>Macros can take parameters, too. If a macro call is followed by a | |
| 1265 | parenthesized, comma-separated list the values starting with $1 will | |
| 1266 | be replaced in the macro with the elements of the list. A $ not | |
| 1267 | followed by a digit is left unchanged. This parsing | |
| 1268 | is very rudimentary; no nesting or parentheses or escaping of commas | |
| 1269 | is allowed. Also, there is no way to say argument 1 followed by a | |
| 1270 | digit (${1}0 in sh(1)).</para> | |
| 1271 | ||
| 1272 | <para>The following will draw a line with slope 1.</para> | |
| 1273 | <programlisting remap='Bd'> | |
| 1274 | <synopsis> | |
| 1275 | define foo { next at $1, $2 } | |
| 1276 | for i from 1 to 5 { foo(i,i) } | |
| 1277 | </synopsis> | |
| 1278 | </programlisting> <!-- remap='Ed (block)' --> | |
| 1279 | <para>Macros persist across graphs. The file | |
| 1280 | <filename>/usr/local/share/grap/grap.defines</filename> | |
| 1281 | contains simple macros for plotting common characters. The | |
| 1282 | <command remap='Ic'>undefine</command> | |
| 1283 | command deletes a macro.</para> | |
| 1284 | ||
| 1285 | <para>See the directory | |
| 1286 | <filename>/usr/local/share/examples/grap</filename> | |
| 1287 | for more examples of macros. | |
| 1288 | Confirm the location of the examples directory using the | |
| 1289 | <option>-v</option> | |
| 1290 | flag.</para> | |
| 1291 | </refsect2> | |
| 1292 | ||
| 1293 | <refsect2 id='number_lists'><title>Number Lists</title> | |
| 1294 | ||
| 1295 | <para>A whitespace-separated list of numbers is treated specially. The list | |
| 1296 | is taken to be points to be plotted using the default line style on | |
| 1297 | the default coordinate system. If more than two numbers are given, | |
| 1298 | the extra numbers are taken to be additional y values to plot at the | |
| 1299 | first x value. Number lists in DWB | |
| 1300 | <command remap='Nm'> grap </command> | |
| 1301 | can be comma-separated, and this | |
| 1302 | <command remap='Nm'> grap </command> | |
| 1303 | supports that as well. More precisely, numbers in number lists can be | |
| 1304 | separated by either whitespace, commas, or both.</para> | |
| 1305 | <programlisting remap='Bd'> | |
| 1306 | 1 2 3 | |
| 1307 | 4 5 6 | |
| 1308 | </programlisting> <!-- remap='Ed (block)' --> | |
| 1309 | ||
| 1310 | <para>Will plot points using the default line style at (1,2), (1,3),(4,5) | |
| 1311 | and (4,6). A simple way to plot a set of numbers in a file named | |
| 1312 | <filename>./data</filename> | |
| 1313 | is:</para> | |
| 1314 | <programlisting remap='Bd'> | |
| 1315 | .G1 | |
| 1316 | copy "./data" | |
| 1317 | .G2 | |
| 1318 | </programlisting> <!-- remap='Ed (block)' --> | |
| 1319 | </refsect2> | |
| 1320 | ||
| 1321 | <refsect2 id='pic_macros'><title>Pic Macros</title> | |
| 1322 | ||
| 1323 | <para><command remap='Nm'> grap </command> | |
| 1324 | defines pic macros that can be used in embedded pic code to place | |
| 1325 | elements in the graph. The macros are | |
| 1326 | <command remap='Ic'>x_gg</command>, | |
| 1327 | <command remap='Ic'>y_gg</command>, | |
| 1328 | and | |
| 1329 | <command remap='Ic'>xy_gg</command>. | |
| 1330 | These macros define pic distances that correspond to the given | |
| 1331 | argument. They can be used to size boxes or to plot pic constructs on | |
| 1332 | the graph. To place a given construct on the graph, you should add | |
| 1333 | Frame.Origin to it. | |
| 1334 | Other coordinate spaces can be used by replacing | |
| 1335 | <command remap='Ic'>gg</command> | |
| 1336 | with the name of the coordinate space. A coordinate space named | |
| 1337 | <command remap='Ic'>gg</command> | |
| 1338 | cannot be reliably accessed by these macros.</para> | |
| 1339 | ||
| 1340 | <para>The macros are emitted immediately before the frame is drawn.</para> | |
| 1341 | ||
| 1342 | <para>DWB | |
| 1343 | <command remap='Nm'> grap </command> | |
| 1344 | may use these as part of its implementation. This | |
| 1345 | <command remap='Nm'> grap </command> | |
| 1346 | provides them only for compatibility. Note that these are very simple | |
| 1347 | macros, and may not do what you expect under complex conditions.</para> | |
| 1348 | </refsect2> | |
| 1349 | </refsect1> | |
| 1350 | ||
| 1351 | <refsect1 id='environment_variables'><title>ENVIRONMENT VARIABLES</title> | |
| 1352 | ||
| 1353 | <para>If the environment variable | |
| 1354 | <envar>GRAP_DEFINES</envar> | |
| 1355 | is defined, | |
| 1356 | <command remap='Nm'> grap </command> | |
| 1357 | will look for its defines file there. If that value is a relative path | |
| 1358 | name the path specified in the | |
| 1359 | <option>-M</option> | |
| 1360 | option will be searched for it. | |
| 1361 | <envar>GRAP_DEFINES</envar> | |
| 1362 | overrides the compiled in location of the defines file, but may be | |
| 1363 | overridden by the | |
| 1364 | <option>-d</option> | |
| 1365 | or | |
| 1366 | <option>-D</option> | |
| 1367 | flags.</para> | |
| 1368 | ||
| 1369 | <para>If | |
| 1370 | <envar>GRAP_SAFER</envar> | |
| 1371 | is set, | |
| 1372 | <command remap='Ic'>sprintf</command> | |
| 1373 | is disabled to prevent forcing | |
| 1374 | <command remap='Nm'> grap </command> | |
| 1375 | to core dump or smash the stack.</para> | |
| 1376 | </refsect1> | |
| 1377 | ||
| 1378 | <refsect1 id='files'><title>FILES</title> | |
| 1379 | <para><filename>/usr/local/share/grap/grap.defines</filename></para> | |
| 1380 | </refsect1> | |
| 1381 | ||
| 1382 | <refsect1 id='see_also'><title>SEE ALSO</title> | |
| 1383 | <para><citerefentry><refentrytitle>atan2</refentrytitle><manvolnum>3</manvolnum></citerefentry>, | |
| 1384 | <citerefentry><refentrytitle>groff</refentrytitle><manvolnum>1</manvolnum></citerefentry>, | |
| 1385 | <citerefentry><refentrytitle>pic</refentrytitle><manvolnum>1</manvolnum></citerefentry>, | |
| 1386 | <citerefentry><refentrytitle>printf</refentrytitle><manvolnum>3</manvolnum></citerefentry>, | |
| 1387 | <citerefentry><refentrytitle>sh</refentrytitle><manvolnum>1</manvolnum></citerefentry>, | |
| 1388 | <citerefentry><refentrytitle>sprintf</refentrytitle><manvolnum>3</manvolnum></citerefentry>, | |
| 1389 | <citerefentry><refentrytitle>troff</refentrytitle><manvolnum>1</manvolnum></citerefentry></para> | |
| 1390 | ||
| 1391 | <para>If documentation and examples have been installed, | |
| 1392 | <command remap='Nm'> grap </command> | |
| 1393 | <option>--version</option> | |
| 1394 | or | |
| 1395 | <command remap='Nm'> grap </command> | |
| 1396 | <option>--help</option> | |
| 1397 | will display the locations.</para> | |
| 1398 | </refsect1> | |
| 1399 | ||
| 1400 | <refsect1 id='bugs'><title>BUGS</title> | |
| 1401 | ||
| 1402 | <para>There are several small incompatibilities with K&R | |
| 1403 | <command remap='Nm'> grap </command> | |
| 1404 | They include the | |
| 1405 | <command remap='Ic'>sh</command> | |
| 1406 | command not expanding variables and macros, and a more strict | |
| 1407 | adherence to parameter order in the internal commands.</para> | |
| 1408 | ||
| 1409 | <para>Although much improved, the error reporting code can still be | |
| 1410 | confused. Notably, an error in a macro is not detected until the | |
| 1411 | macro is used, and it produces unusual output in the error message.</para> | |
| 1412 | ||
| 1413 | <para>Iterating many times over a macro with no newlines can run | |
| 1414 | <command remap='Nm'> grap </command> | |
| 1415 | out of memory.</para> | |
| 1416 | </refsect1> | |
| 1417 | ||
| 1418 | <refsect1 id='author'><title>AUTHOR</title> | |
| 1419 | <para>This implementation was done by | |
| 1420 | phrase Ted Faber Ao faber@lunabase.org Ac Ns role='author'. | |
| 1421 | phrase Bruce Lilly Ao blilly@erols.com Ac role='author' | |
| 1422 | contributed many bug fixes, including a considerable revamp of the | |
| 1423 | error reporting code. If you can actually find an error in your | |
| 1424 | <command remap='Nm'> grap </command> | |
| 1425 | code, you can probably thank him. | |
| 1426 | <command remap='Nm'> grap </command> | |
| 1427 | was designed and specified by | |
| 1428 | phrase Brian Kernighan role='author' | |
| 1429 | and | |
| 1430 | phrase Jon Bentley role='author'.</para> | |
| 1431 | </refsect1> | |
| 1432 | </refentry> | |
| 1433 |
| 0 | .\"-*-nroff-*- | |
| 1 | .\" This file is (c) 1998-2006 Ted Faber (faber@lunabase.org) see | |
| 2 | .\" COPYRIGHT for the full copyright and limitations of liabilities. | |
| 3 | .Dd March 11, 2006 | |
| 4 | .Os | |
| 5 | .Dt GRAP 1 | |
| 6 | .Sh NAME | |
| 7 | .Nm grap | |
| 8 | .Nd Kernighan and Bentley's language for typesetting graphs | |
| 9 | .Sh SYNOPSIS | |
| 10 | .Nm | |
| 11 | .Op Fl d Ar defines_file | |
| 12 | .Op Fl D | |
| 13 | .Op Fl l | |
| 14 | .Op Fl M Ar include path | |
| 15 | .Op Fl R | |
| 16 | .Op Fl r | |
| 17 | .Op Fl v | |
| 18 | .Op Fl u | |
| 19 | .Op Fl C | |
| 20 | .Op Fl c | |
| 21 | .Op Fl h | |
| 22 | .Op Ar filename ... | |
| 23 | .Sh DESCRIPTION | |
| 24 | .Nm | |
| 25 | is an implementation of Kernighan and Bentley's language for | |
| 26 | typesetting graphs, as described in ``Grap-A Language for Typesetting | |
| 27 | Graphs, Tutorial and User Manual,'' by Jon L. Bentley and Brian W. | |
| 28 | Kernighan, revised May 1991, which is the primary source for | |
| 29 | information on how to use | |
| 30 | .Nm grap . | |
| 31 | As of this writing, it is available electronically at | |
| 32 | .Li http://www.kohala.com/start/troff/cstr114.ps . | |
| 33 | Additional documentation and examples, packaged with | |
| 34 | .Nm , | |
| 35 | may have been installed locally as well. If available, paths to them | |
| 36 | can be displayed using | |
| 37 | .Nm | |
| 38 | .Fl h | |
| 39 | or | |
| 40 | .Nm | |
| 41 | .Fl v | |
| 42 | (or | |
| 43 | .Nm | |
| 44 | .Fl -help | |
| 45 | / | |
| 46 | .Nm | |
| 47 | .Fl -version ) | |
| 48 | .Pp | |
| 49 | This version is a black box implementation of | |
| 50 | .Nm grap , | |
| 51 | and some inconsistencies are to be expected. The remainder of this | |
| 52 | manual page will briefly outline the | |
| 53 | .Nm | |
| 54 | language as implemented here. | |
| 55 | .Pp | |
| 56 | .Nm | |
| 57 | is a | |
| 58 | .Xr pic 1 | |
| 59 | pre-processor. It takes commands embedded in a | |
| 60 | .Xr troff 1 | |
| 61 | source file which are surrounded by | |
| 62 | .Ic .G1 | |
| 63 | and | |
| 64 | .Ic .G2 | |
| 65 | macros, and rewrites them into | |
| 66 | .Xr pic | |
| 67 | commands to display the graph. | |
| 68 | Other lines are copied. Output is always to the standard output, | |
| 69 | which is usually redirected. Input is from the given | |
| 70 | .Ar filename Ns No s , | |
| 71 | which are read in order. A | |
| 72 | .Ar filename | |
| 73 | of | |
| 74 | .Fl | |
| 75 | is the standard input. | |
| 76 | If no | |
| 77 | .Ar filename Ns No s | |
| 78 | are given, input is read from the standard input. | |
| 79 | .Pp | |
| 80 | Because | |
| 81 | .Nm | |
| 82 | is a | |
| 83 | .Xr pic | |
| 84 | preprocessor, and GNU | |
| 85 | .Xr pic | |
| 86 | will output TeX, it is possible to use | |
| 87 | .Nm | |
| 88 | with TeX. | |
| 89 | .Pp | |
| 90 | The | |
| 91 | .Fl d | |
| 92 | option specifies a file of macro definitions to be read at startup, | |
| 93 | and defaults to /usr/local/share/grap/grap.defines . | |
| 94 | The | |
| 95 | .Fl D | |
| 96 | option inhibits the reading of any initial macros file | |
| 97 | (the | |
| 98 | .Fl l | |
| 99 | flag is a synonym for | |
| 100 | .Fl D , | |
| 101 | though I do not remember why). The defines | |
| 102 | file can also be given using the | |
| 103 | .Ev GRAP_DEFINES | |
| 104 | environment variable. (See below). | |
| 105 | .Pp | |
| 106 | .Fl v | |
| 107 | prints the version information on the standard output and exits. | |
| 108 | .Fl -version | |
| 109 | is a synonym for | |
| 110 | .Fl v . | |
| 111 | .Pp | |
| 112 | .Fl u | |
| 113 | makes labels unaligned by default. This version of | |
| 114 | .Nm | |
| 115 | uses new features of GNU | |
| 116 | .Xr pic | |
| 117 | to align the left and right labels with | |
| 118 | the axes, that is that the left and right labels run at right angles | |
| 119 | to the text of the paper. This may be useful in porting old | |
| 120 | .Nm | |
| 121 | programs. | |
| 122 | .Fl c | |
| 123 | makes plot strings unclipped by default. Some versions of | |
| 124 | .Nm | |
| 125 | allow users to place a string anywhere in the coordinate space, rather than | |
| 126 | only in the frame. By default this version of | |
| 127 | .Nm | |
| 128 | does not plot any string centered outside the frame. | |
| 129 | .Fl c | |
| 130 | allows strings to be placed anywhere. See also the | |
| 131 | .Ic clipped | |
| 132 | and | |
| 133 | .Ic unclipped | |
| 134 | string modifiers described in the | |
| 135 | .Ic plot | |
| 136 | statement. | |
| 137 | .Pp | |
| 138 | .Fl M | |
| 139 | is followed by a colon-separated list of directories used to search | |
| 140 | for relative pathnames included via | |
| 141 | .Ic copy . | |
| 142 | The path is also used to locate the defines file, so if the | |
| 143 | .Fl d | |
| 144 | changes the defines file name to a relative name, it will be searched | |
| 145 | for in the path given by | |
| 146 | .Fl M . | |
| 147 | The search path always includes the current directory, and by default | |
| 148 | that directory is searched last. | |
| 149 | .Pp | |
| 150 | All numbers used internally by | |
| 151 | .Nm | |
| 152 | are double precision floating point values. Sometimes using floating point | |
| 153 | numbers has unintended consequences. To help avoid these problems, | |
| 154 | .Nm | |
| 155 | can use two thresholds for comparison of floating point numbers, set by | |
| 156 | .Fl R | |
| 157 | or | |
| 158 | .Fl r . | |
| 159 | The | |
| 160 | .Fl R | |
| 161 | flag sets coarse comparison mode, which is suitable for most applications. If | |
| 162 | you are plotting small values \(en less than 1e-6 or so \(en consider using | |
| 163 | .Fl r | |
| 164 | which uses very fine comparisons between numbers. You may also want to rescale your plotted values to be larger in magnitude. The coarse comarisons are | |
| 165 | used by default. | |
| 166 | .Pp | |
| 167 | To be precise, the value by which two numbers must differ for | |
| 168 | .Nm | |
| 169 | to consider them not equal is called the comparison limit and the smallest | |
| 170 | non-zero number is called the minimum value. The values a given version of | |
| 171 | .Nm | |
| 172 | uses for these are included in the output of | |
| 173 | .Fl v | |
| 174 | or | |
| 175 | .Fl h . | |
| 176 | .Pp | |
| 177 | All | |
| 178 | .Nm | |
| 179 | commands are included between | |
| 180 | .Ic .G1 | |
| 181 | and | |
| 182 | .Ic .G2 | |
| 183 | macros, which are consumed by | |
| 184 | .Nm grap . | |
| 185 | The output contains | |
| 186 | .Xr pic | |
| 187 | between | |
| 188 | .Ic .PS | |
| 189 | and | |
| 190 | .Ic .PE | |
| 191 | macros. Any arguments to the | |
| 192 | .Ic .G1 | |
| 193 | macro in the input are arguments to the | |
| 194 | .Ic .PS | |
| 195 | macro in the output, so graphs can be scaled just like | |
| 196 | .Xr pic | |
| 197 | diagrams. | |
| 198 | If | |
| 199 | .Fl C | |
| 200 | is given, any macro beginning with \&.G1 or \&.G2 is treated as a \&.G1 or | |
| 201 | \&.G2 macro, for compatibility with old versions of troff. Using | |
| 202 | .Fl C | |
| 203 | also forces pure troff syntax on embedded font change commands when strings | |
| 204 | have the | |
| 205 | .Ic size | |
| 206 | attribute, and all strings to be | |
| 207 | .Ic unclipped . | |
| 208 | .Pp | |
| 209 | The | |
| 210 | .Fl h | |
| 211 | flag prints a brief help message and exits. | |
| 212 | .Fl -help | |
| 213 | is a synonym for | |
| 214 | .Fl h . | |
| 215 | .Pp | |
| 216 | It is possible for someone to cause | |
| 217 | .Nm | |
| 218 | to fail by passing a bad format string and data to the | |
| 219 | .Ic sprintf | |
| 220 | command. If | |
| 221 | .Nm | |
| 222 | is integrated as part of the printing system, this could conceivably | |
| 223 | provided a path to breaching security on the machine. If you choose to | |
| 224 | use | |
| 225 | .Nm | |
| 226 | as part of a printing system run by the super-user, you should disable | |
| 227 | .Ic sprintf | |
| 228 | commands. This can be done by calling | |
| 229 | .Nm | |
| 230 | with the | |
| 231 | .Fl S | |
| 232 | flag, setting the | |
| 233 | .Ev GRAP_SAFER | |
| 234 | environment variable, or compiling with the GRAP_SAFER preprocessor | |
| 235 | symbol defined. (The GNU configure script included with | |
| 236 | .Nm | |
| 237 | will define that preprocessor symbol if the | |
| 238 | .Fl -with-grap-safe | |
| 239 | option is given.) | |
| 240 | .Pp | |
| 241 | The | |
| 242 | .Nm | |
| 243 | commands are sketched below. Refer to Kernighan and Bentley's paper | |
| 244 | for the details. | |
| 245 | .Pp | |
| 246 | New versions of | |
| 247 | .Xr groff 1 | |
| 248 | will invoke | |
| 249 | .Nm | |
| 250 | if | |
| 251 | .Fl G | |
| 252 | is given. | |
| 253 | .Ss Commands | |
| 254 | .Pp | |
| 255 | Commands are separated from one another by newlines or semicolons (;). | |
| 256 | .Pp | |
| 257 | .Ic frame | |
| 258 | .Op Ar line_description | |
| 259 | .Oo | |
| 260 | .Bk -words | |
| 261 | .Cm ht Ar height No \(or Cm wid Ar width | |
| 262 | .Ek | |
| 263 | .Oc | |
| 264 | .Oo | |
| 265 | .Bk -words | |
| 266 | .Oo | |
| 267 | .Sm off | |
| 268 | .Cm ( top No \(or Cm bottom No \(or | |
| 269 | .Cm left No \(or | |
| 270 | .Sm on | |
| 271 | .Cm right ) | |
| 272 | .Ar line_description | |
| 273 | .Ek | |
| 274 | .Oc | |
| 275 | \&... | |
| 276 | .Oc | |
| 277 | .sp | |
| 278 | .Ic frame | |
| 279 | .Oo | |
| 280 | .Bk -words | |
| 281 | .Cm ht Ar height No \(or Cm wid Ar width | |
| 282 | .Ek | |
| 283 | .Oc | |
| 284 | .Op Ar line_description | |
| 285 | .Oo | |
| 286 | .Bk -words | |
| 287 | .Oo | |
| 288 | .Sm off | |
| 289 | .Cm ( top No \(or Cm bottom No \(or | |
| 290 | .Cm left No \(or | |
| 291 | .Sm on | |
| 292 | .Cm right ) | |
| 293 | .Ar line_description | |
| 294 | .Ek | |
| 295 | .Oc | |
| 296 | \&... | |
| 297 | .Oc | |
| 298 | .Bd -filled -offset indent | |
| 299 | This describes how the axes for the graph are drawn. A | |
| 300 | .Ar line_description | |
| 301 | is a | |
| 302 | .Xr pic | |
| 303 | line description, e.g., | |
| 304 | .Li dashed | |
| 305 | .Li 0.5 , | |
| 306 | or the literal | |
| 307 | .Li solid . | |
| 308 | It may also include a | |
| 309 | .Ic color | |
| 310 | keyword followed by the color to draw the string in double quotes. Any color | |
| 311 | understood by the underlying groff system can be used. Color can only be used | |
| 312 | under GNU pic, and is not available in compatibility mode. Similarly, for | |
| 313 | pic implementations that understand | |
| 314 | .Ic thickness , | |
| 315 | that attribute may be used with a real valued parameter. | |
| 316 | .Ic Thickness | |
| 317 | is not available in compatibility mode. | |
| 318 | .Pp | |
| 319 | If the first | |
| 320 | .Ar line_description | |
| 321 | is given, the frame is drawn with that style. The default is | |
| 322 | .Li solid . | |
| 323 | The height and width of the frame can also be specified in inches. | |
| 324 | The default line style can be over-ridden for sides of the frame by | |
| 325 | specifying additional parameters to | |
| 326 | .Ic frame . | |
| 327 | .Pp | |
| 328 | If no plotting commands have been given before the | |
| 329 | .Ic frame | |
| 330 | command is issued, the frame will be output at that point in the | |
| 331 | plotting stream relative to embedded | |
| 332 | .Xr troff | |
| 333 | or | |
| 334 | .Xr pic | |
| 335 | commands. Otherwise the frame is output before the first plotted | |
| 336 | object (even invisible ones). | |
| 337 | .Pp | |
| 338 | .Ic ht | |
| 339 | and | |
| 340 | .Ic wid | |
| 341 | are in inches by default, but can be any | |
| 342 | .Xr groff | |
| 343 | unit. If omitted, the dimensions are 2 inches high by 3 inches wide. | |
| 344 | .Ed | |
| 345 | .Pp | |
| 346 | .Ic coord | |
| 347 | .Op Ar name | |
| 348 | .Op Cm x Ar expr , expr | |
| 349 | .Op Cm y Ar expr , expr | |
| 350 | .Oo | |
| 351 | .Cm log x No \(or | |
| 352 | .Cm log y No \(or | |
| 353 | .Cm log log | |
| 354 | .Oc | |
| 355 | .Bd -filled -offset indent | |
| 356 | The | |
| 357 | .Ic coord | |
| 358 | command specifies a new coordinate system or sets limits on the | |
| 359 | default system. It defines the largest and smallest values that can | |
| 360 | be plotted, and therefore the scale of the data in the frame. The | |
| 361 | limits for the x and y coordinate systems can be given separately. If | |
| 362 | a | |
| 363 | .Ar name | |
| 364 | is given, that coordinate system is defined, if not the default system | |
| 365 | is modified. | |
| 366 | .Pp | |
| 367 | A coordinate system created by one | |
| 368 | .Ic coord | |
| 369 | command may be modified by subsequent | |
| 370 | .Ic coord | |
| 371 | commands. A | |
| 372 | .Nm | |
| 373 | program may declare a coordinate space using | |
| 374 | .Ic coord , | |
| 375 | .Ic copy | |
| 376 | a file of data through a macro that plots the data and finds its | |
| 377 | maxima and minima, and then define the size of the coordinate system | |
| 378 | with a second | |
| 379 | .Ic coord | |
| 380 | statement. | |
| 381 | .Pp | |
| 382 | This command also determines if a scale is plotted logarithmically. | |
| 383 | .Cm log log | |
| 384 | means the same thing as | |
| 385 | .Cm log x log y . | |
| 386 | .Ed | |
| 387 | .Pp | |
| 388 | .Ic draw | |
| 389 | .Op Ar line_name | |
| 390 | .Op Ar line_description | |
| 391 | .Op Ar plot_string | |
| 392 | .Bd -filled -offset indent | |
| 393 | The | |
| 394 | .Ic draw | |
| 395 | command defines the style with which a given line will be plotted. If | |
| 396 | .Ar line_name | |
| 397 | is given, the style is associated with that name, otherwise the | |
| 398 | default style is set. | |
| 399 | .Ar line_description | |
| 400 | is a | |
| 401 | .Xr pic | |
| 402 | line description, and the optional | |
| 403 | .Ar plot_string | |
| 404 | is a string to be centered at each point. The default line | |
| 405 | description is | |
| 406 | .Li invis , | |
| 407 | and the default plotting string is a centered bullet, so by default | |
| 408 | each point is a filled circle, and they are unconnected. | |
| 409 | If points are being connected, each | |
| 410 | .Ic draw | |
| 411 | command ends any current line and begins a new one. | |
| 412 | .Pp | |
| 413 | When defining a line style, that is the first | |
| 414 | .Ic draw | |
| 415 | command for a given line name, specifying no plot string means that | |
| 416 | there are to be no plot strings. Omitting the plot string on | |
| 417 | subsequent | |
| 418 | .Ic draw | |
| 419 | commands addressing the same named line means not to change the plot | |
| 420 | string. If a line has been defined with a plot string, and the format | |
| 421 | is changed by a subsequent | |
| 422 | .Ic draw | |
| 423 | statement, the plot string can be removed by specifying "" in the | |
| 424 | .Ic draw | |
| 425 | statement. | |
| 426 | .Pp | |
| 427 | The plot string can have its format changed through several string_modifiers. | |
| 428 | String_modifiers are described in the description of the | |
| 429 | .Ic plot | |
| 430 | command. | |
| 431 | .Pp | |
| 432 | The standard defines file includes several macros useful as plot strings, | |
| 433 | including | |
| 434 | .Ic bullet , | |
| 435 | .Ic square , | |
| 436 | and | |
| 437 | .Ic delta . | |
| 438 | .Pp | |
| 439 | .Ic new | |
| 440 | is a synonym for | |
| 441 | .Ic draw . | |
| 442 | .Ed | |
| 443 | .Pp | |
| 444 | .Ic next | |
| 445 | .Op Ar line_name | |
| 446 | .Cm at | |
| 447 | .Op Ar coordinates_name | |
| 448 | .Ar expr , expr | |
| 449 | .Op Ar line_description | |
| 450 | .Bd -filled -offset indent | |
| 451 | The | |
| 452 | .Ic next | |
| 453 | command plots the given point using the line style given by | |
| 454 | .Ar line_name , | |
| 455 | or the default if none is given. If | |
| 456 | .Ar line_name | |
| 457 | is given, it should have been defined by an earlier | |
| 458 | .Ic draw | |
| 459 | command, if not a new line style with that name is created, | |
| 460 | initialized the same way as the default style. The two expressions | |
| 461 | give the point's x and y values, relative to the optional coordinate | |
| 462 | system. That system should have been defined by an earlier | |
| 463 | .Ic coord | |
| 464 | command, if not, grap will exit. If the optional | |
| 465 | .Ar line_description | |
| 466 | is given, it overrides the style's default line description. You | |
| 467 | cannot over-ride the plotting string. To use a different plotting | |
| 468 | string use the | |
| 469 | .Ic plot | |
| 470 | command. | |
| 471 | .Pp | |
| 472 | The coordinates may optionally be enclosed in parentheses: | |
| 473 | .Ar ( expr , expr ) | |
| 474 | .Ed | |
| 475 | .Pp | |
| 476 | .Ar quoted_string | |
| 477 | .Op Ar string_modifiers | |
| 478 | .Oo | |
| 479 | .No , Ar quoted_string | |
| 480 | .Oo | |
| 481 | .Ar string_modifiers | |
| 482 | .Oc | |
| 483 | .Oc | |
| 484 | \&... | |
| 485 | .Cm at | |
| 486 | .Op Ar coordinates_name | |
| 487 | .Ar expr , expr | |
| 488 | .Pp | |
| 489 | .Ic plot | |
| 490 | .Ar expr | |
| 491 | .Op Ar format_string | |
| 492 | .Cm at | |
| 493 | .Op Ar coordinates_name | |
| 494 | .Ar expr , expr | |
| 495 | .Bd -filled -offset indent | |
| 496 | These commands both plot a string at the given point. In the first | |
| 497 | case the literal strings are stacked above each other. The string_modifiers | |
| 498 | include the | |
| 499 | .Xr pic | |
| 500 | justification modifiers | |
| 501 | .Ns No ( Ic ljust , | |
| 502 | .Ic rjust , | |
| 503 | .Ic above , | |
| 504 | and | |
| 505 | .Ic below Ns No ), | |
| 506 | and absolute and relative | |
| 507 | .Li size | |
| 508 | modifiers. See the | |
| 509 | .Xr pic | |
| 510 | documentation for the description of the justification modifiers. | |
| 511 | .Nm | |
| 512 | also supports the | |
| 513 | .Ic aligned | |
| 514 | and | |
| 515 | .Ic unaligned | |
| 516 | modifiers which are briefly noted in the description of the | |
| 517 | .Ic label | |
| 518 | command. | |
| 519 | .Pp | |
| 520 | The standard defines file includes several macros useful as plot strings, | |
| 521 | including | |
| 522 | .Ic bullet , | |
| 523 | .Ic square , | |
| 524 | and | |
| 525 | .Ic delta . | |
| 526 | .Pp | |
| 527 | Strings placed by either format of the | |
| 528 | .Ic plot | |
| 529 | command are restricted to being within the frame. This can be overridden by | |
| 530 | using the | |
| 531 | .Ic unclipped | |
| 532 | attribute, which allows a string to be plotted in or out of the frame. The | |
| 533 | .Fl c | |
| 534 | and | |
| 535 | .Fl C | |
| 536 | flags set | |
| 537 | .Ic unclipped | |
| 538 | on all strings, and to prevent a string from being plotted outside the frame | |
| 539 | when those flags are active, the | |
| 540 | .Ic clipped | |
| 541 | attribute can be used to retore clipping behavior. Though | |
| 542 | .Ic clipped | |
| 543 | or | |
| 544 | .Ic unclipped | |
| 545 | can be applied to any string, it only has meaning for | |
| 546 | .Ic plot | |
| 547 | statements. | |
| 548 | .Pp | |
| 549 | .Li size | |
| 550 | .Ar expr | |
| 551 | sets the string size to | |
| 552 | .Ar expr | |
| 553 | points. If | |
| 554 | .Ar expr | |
| 555 | is preceded by a + or -, the size is increased or decreased by that | |
| 556 | many points. | |
| 557 | .Pp | |
| 558 | If | |
| 559 | .Ic color | |
| 560 | and a color name in double quotes appears, the string will be rendered in that | |
| 561 | color under a version of GNU troff that supports color. Color is not available | |
| 562 | in compatibility mode. | |
| 563 | .Pp | |
| 564 | In the second version, the | |
| 565 | .Ar expr | |
| 566 | is converted to a string and placed on the graph. | |
| 567 | .Ar format_string | |
| 568 | is a | |
| 569 | .Xr printf 3 | |
| 570 | format string. Only formatting escapes for printing | |
| 571 | floating point numbers make sense. The format string is only respected | |
| 572 | if the | |
| 573 | .Ic sprintf | |
| 574 | command is also active. See the description of | |
| 575 | .Ic sprintf | |
| 576 | for the various ways to disable it. | |
| 577 | .Ic Plot | |
| 578 | and | |
| 579 | .Ic sprintf | |
| 580 | respond differently when | |
| 581 | .Nm | |
| 582 | is running safely. | |
| 583 | .Ic Sprintf | |
| 584 | ignores any arguments, passing the format string through without | |
| 585 | substitution. | |
| 586 | .Ic plot | |
| 587 | ignores the format string completely, plotting | |
| 588 | .Ar expr | |
| 589 | using the | |
| 590 | .Qq %g | |
| 591 | format. | |
| 592 | .Pp | |
| 593 | Points are specified the same way as for | |
| 594 | .Ic next | |
| 595 | commands, with the same consequences for undefined coordinate systems. | |
| 596 | .Pp | |
| 597 | The second form of this command is because the first form can be used | |
| 598 | with a | |
| 599 | .Nm | |
| 600 | .Ic sprintf | |
| 601 | expression (See | |
| 602 | .Sx Expressions ) . | |
| 603 | .Ed | |
| 604 | .Pp | |
| 605 | .Ic ticks | |
| 606 | .Sm off | |
| 607 | .Xo ( Cm left No \(or Cm right | |
| 608 | .No \(or Cm top No \(or Cm bottom ) | |
| 609 | .Xc | |
| 610 | .Oo | |
| 611 | .Sm on | |
| 612 | .Xo ( Cm in Ns No \(or Ns Cm out ) | |
| 613 | .Xc | |
| 614 | .Op Ar expr | |
| 615 | .Oc | |
| 616 | .Sm off | |
| 617 | .Oo | |
| 618 | .Cm on \(or Cm auto | |
| 619 | .Sm on | |
| 620 | .Ar coord_name | |
| 621 | .Oc | |
| 622 | .Pp | |
| 623 | .Ic ticks | |
| 624 | .Sm off | |
| 625 | .Xo ( Cm left No \(or Cm right No \(or Cm top No \(or Cm bottom ) | |
| 626 | .Xc | |
| 627 | .Sm on | |
| 628 | .Xo ( Cm in Ns No \(or Ns Cm out ) | |
| 629 | .Xc | |
| 630 | .Op Ar expr | |
| 631 | .Oo | |
| 632 | .Cm up Ar expr No \(or | |
| 633 | .Cm down Ar expr No \(or | |
| 634 | .Cm left Ar expr No \(or | |
| 635 | .Cm right Ar expr | |
| 636 | .Oc | |
| 637 | .Cm at | |
| 638 | .Op Ar coord_name | |
| 639 | .Ar expr | |
| 640 | .Op Ar format_string | |
| 641 | .Oo | |
| 642 | .Oo | |
| 643 | .No , Ar expr | |
| 644 | .Oo | |
| 645 | .Ar format_string | |
| 646 | .Oc | |
| 647 | .Oc | |
| 648 | .No ... | |
| 649 | .Oc | |
| 650 | .Pp | |
| 651 | .Ic ticks | |
| 652 | .Sm off | |
| 653 | .Xo ( Cm left No \(or Cm right | |
| 654 | .No \(or Cm top No \(or Cm bottom ) | |
| 655 | .Xc | |
| 656 | .Sm on | |
| 657 | .Xo ( Cm in Ns No \(or Ns Cm out ) | |
| 658 | .Xc | |
| 659 | .Op Ar expr | |
| 660 | .Oo | |
| 661 | .Cm up Ar expr No \(or | |
| 662 | .Cm down Ar expr No \(or | |
| 663 | .Cm left Ar expr No \(or | |
| 664 | .Cm right Ar expr | |
| 665 | .Oc | |
| 666 | .Cm from | |
| 667 | .Op coord_name | |
| 668 | .Ar start_expr | |
| 669 | .Cm to | |
| 670 | .Ar end_expr | |
| 671 | .Oo | |
| 672 | .Cm by | |
| 673 | .Sm off | |
| 674 | .Oo | |
| 675 | .No + \(or - \(or * \(or / | |
| 676 | .Sm on | |
| 677 | .Oc | |
| 678 | .Ar by_expr | |
| 679 | .Oc | |
| 680 | .Op format_string | |
| 681 | .Pp | |
| 682 | .Ic ticks | |
| 683 | .Sm off | |
| 684 | .Oo | |
| 685 | .Cm left Xo No \(or Cm right | |
| 686 | .No \(or Cm top No \(or Cm bottom | |
| 687 | .Oc | |
| 688 | .Xc | |
| 689 | .Sm on | |
| 690 | .Cm off | |
| 691 | .Bd -filled -offset indent | |
| 692 | This command controls the placement of ticks on the frame. By | |
| 693 | default, ticks are automatically generated on the left and bottom | |
| 694 | sides of the frame. | |
| 695 | .Pp | |
| 696 | The first version of this command turns on the automatic tick | |
| 697 | generation for a given side. The | |
| 698 | .Cm in | |
| 699 | or | |
| 700 | .Cm out | |
| 701 | parameter controls the direction and length of the ticks. If a | |
| 702 | .Ar coord_name | |
| 703 | is specified, the ticks are automatically generated using that | |
| 704 | coordinate system. If no system is specified, the default coordinate | |
| 705 | system is used. As with | |
| 706 | .Ic next | |
| 707 | and | |
| 708 | .Ic plot , | |
| 709 | the coordinate system must be declared before the | |
| 710 | .Ic ticks | |
| 711 | statement that references it. This syntax for requesting | |
| 712 | automatically generated ticks is an extension, and will not port to | |
| 713 | older | |
| 714 | .Nm | |
| 715 | implementations. | |
| 716 | .Pp | |
| 717 | The second version of the | |
| 718 | .Ic ticks | |
| 719 | command overrides the automatic placement of the ticks by specifying | |
| 720 | a list of coordinates at which to place the ticks. If the ticks are | |
| 721 | not defined with respect to the default coordinate system, the | |
| 722 | .Ar coord_name | |
| 723 | parameter must be given. For each tick a | |
| 724 | .Xr printf 3 | |
| 725 | style format string can be given. The | |
| 726 | .Ar format_string | |
| 727 | defaults to | |
| 728 | .Qq %g . | |
| 729 | The format string can also take string modifiers as described in the | |
| 730 | .Ic plot | |
| 731 | command. | |
| 732 | To place ticks with no labels, specify | |
| 733 | .Ar format_string | |
| 734 | as | |
| 735 | .Qq \& . | |
| 736 | .Pp | |
| 737 | If | |
| 738 | .Ic sprintf | |
| 739 | is disabled, | |
| 740 | .Ic ticks | |
| 741 | behaves as | |
| 742 | .Ic plot | |
| 743 | with respect to the format string. | |
| 744 | .Pp | |
| 745 | The labels on the ticks may be shifted by specifying a direction and | |
| 746 | the distance in inches to offset the label. That is the optional | |
| 747 | direction and expression immediately preceding the | |
| 748 | .Cm at . | |
| 749 | .Pp | |
| 750 | The third format of the | |
| 751 | .Ic ticks | |
| 752 | command over-rides the default tick generation with a set of ticks ar | |
| 753 | regular intervals. The syntax is reminiscent of programming | |
| 754 | language for loops. Ticks are placed starting at | |
| 755 | .Ar start_expr | |
| 756 | ending at | |
| 757 | .Ar end_expr | |
| 758 | one unit apart. If the | |
| 759 | .Cm by | |
| 760 | clause is specified, ticks are | |
| 761 | .Ar by_expr | |
| 762 | units apart. If an operator appears before | |
| 763 | .Ar by_expr | |
| 764 | each tick is operated on by that operator instead of +. For example | |
| 765 | .Bd -literal -offset indent-two | |
| 766 | ticks left out from 2 to 32 by *2 | |
| 767 | .Ed | |
| 768 | .Pp | |
| 769 | will put ticks at 2, 4, 8, 16, and 32. If | |
| 770 | .Ar format_string | |
| 771 | is specified, all ticks are formatted using it. | |
| 772 | .Pp | |
| 773 | The parameters preceding the | |
| 774 | .Cm from | |
| 775 | act as described above. | |
| 776 | .Pp | |
| 777 | The | |
| 778 | .Cm at | |
| 779 | and | |
| 780 | .Cm for | |
| 781 | forms of tick command may both be issued on the same | |
| 782 | side of a frame. For example: | |
| 783 | .Bd -literal -offset indent-two | |
| 784 | ticks left out from 2 to 32 by *2 | |
| 785 | ticks left in 3, 5, 7 | |
| 786 | .Ed | |
| 787 | .Pp | |
| 788 | will put ticks on the left side of the frame pointing out at 2, 4, 8, | |
| 789 | 16, and 32 and in at 3, 5, and 7. | |
| 790 | .Pp | |
| 791 | The final form of | |
| 792 | .Ic ticks | |
| 793 | turns off ticks on a given side. If no side is given the ticks for | |
| 794 | all sides are cancelled. | |
| 795 | .Pp | |
| 796 | .Ic tick | |
| 797 | is a synonym for | |
| 798 | .Ic ticks . | |
| 799 | .Ed | |
| 800 | .Pp | |
| 801 | .Ic grid | |
| 802 | .Sm off | |
| 803 | .Xo ( Cm left No \(or Cm right | |
| 804 | .No \(or Cm top No \(or Cm bottom ) | |
| 805 | .Xc | |
| 806 | .Sm on | |
| 807 | .Op Li ticks off | |
| 808 | .Op Ar line_description | |
| 809 | .Oo | |
| 810 | .Cm up Ar expr No \(or | |
| 811 | .Cm down Ar expr No \(or | |
| 812 | .Cm left Ar expr No \(or | |
| 813 | .Cm right Ar expr | |
| 814 | .Oc | |
| 815 | .Oo | |
| 816 | .Sm off | |
| 817 | .Cm on \(or Cm auto | |
| 818 | .Sm on | |
| 819 | .Op Ar coord_name | |
| 820 | .Oc | |
| 821 | .Pp | |
| 822 | .Ic grid | |
| 823 | .Sm off | |
| 824 | .Xo ( Cm left No \(or Cm right | |
| 825 | .No \(or Cm top No \(or Cm bottom ) | |
| 826 | .Xc | |
| 827 | .Sm on | |
| 828 | .Op Li ticks off | |
| 829 | .Op Ar line_description | |
| 830 | .Oo | |
| 831 | .Cm up Ar expr No \(or | |
| 832 | .Cm down Ar expr No \(or | |
| 833 | .Cm left Ar expr No \(or | |
| 834 | .Cm right Ar expr | |
| 835 | .Oc | |
| 836 | .Cm at | |
| 837 | .Op Ar coord_name | |
| 838 | .Ar expr | |
| 839 | .Op Ar format_string | |
| 840 | .Oo | |
| 841 | .Oo | |
| 842 | .No , Ar expr | |
| 843 | .Oo | |
| 844 | .Ar format_string | |
| 845 | .Oc | |
| 846 | .Oc | |
| 847 | .No ... | |
| 848 | .Oc | |
| 849 | .Pp | |
| 850 | .Ic grid | |
| 851 | .Sm off | |
| 852 | .Xo ( Cm left No \(or Cm right | |
| 853 | .No \(or Cm top No \(or Cm bottom ) | |
| 854 | .Xc | |
| 855 | .Sm on | |
| 856 | .Op Li ticks off | |
| 857 | .Op Ar line_description | |
| 858 | .Oo | |
| 859 | .Cm up Ar expr No \(or | |
| 860 | .Cm down Ar expr No \(or | |
| 861 | .Cm left Ar expr No \(or | |
| 862 | .Cm right Ar expr | |
| 863 | .Oc | |
| 864 | .Cm from | |
| 865 | .Op coord_name | |
| 866 | .Ar start_expr | |
| 867 | .Cm to | |
| 868 | .Ar end_expr | |
| 869 | .Oo | |
| 870 | .Cm by | |
| 871 | .Sm off | |
| 872 | .Oo | |
| 873 | .No + \(or - \(or * \(or / | |
| 874 | .Sm on | |
| 875 | .Oc | |
| 876 | .Ar by_expr | |
| 877 | .Oc | |
| 878 | .Op format_string | |
| 879 | .Bd -filled -offset indent | |
| 880 | The | |
| 881 | .Ic grid | |
| 882 | command is similar to the | |
| 883 | .Ic ticks | |
| 884 | command except that | |
| 885 | .Ic grid | |
| 886 | specifies the placement of lines in the frame. The syntax is similar | |
| 887 | to | |
| 888 | .Ic ticks | |
| 889 | as well. | |
| 890 | .Pp | |
| 891 | By specifying | |
| 892 | .Li ticks off | |
| 893 | in the command, no ticks are drawn on that side of the frame. If | |
| 894 | ticks appear on a side by default, or have been declared by an earlier | |
| 895 | .Ic ticks | |
| 896 | command, | |
| 897 | .Ic grid | |
| 898 | does not cancel them unless | |
| 899 | .Li ticks off | |
| 900 | is specified. | |
| 901 | .Pp | |
| 902 | Instead of a direction for ticks, | |
| 903 | .Ic grid | |
| 904 | allows the user to pick a line description for the grid lines. The | |
| 905 | usual | |
| 906 | .Xr pic | |
| 907 | line descriptions are allowed. | |
| 908 | .Pp | |
| 909 | Grids are labelled by default. To omit labels, specify the format | |
| 910 | string as | |
| 911 | .Qq \& . | |
| 912 | .Pp | |
| 913 | If | |
| 914 | .Ic sprintf | |
| 915 | is disabled, | |
| 916 | .Ic grid | |
| 917 | behaves as | |
| 918 | .Ic plot | |
| 919 | with respect to the format string. | |
| 920 | .Ed | |
| 921 | .Pp | |
| 922 | .Ic label | |
| 923 | .Sm off | |
| 924 | .Xo ( Cm left No \(or Cm right | |
| 925 | .No \(or Cm top No \(or Cm bottom ) | |
| 926 | .Xc | |
| 927 | .Sm on | |
| 928 | .Ar quoted_string | |
| 929 | .Op Ar string_modifiers | |
| 930 | .Oo | |
| 931 | .No , Ar quoted_string | |
| 932 | .Oo | |
| 933 | .Ar string_modifiers | |
| 934 | .Oc | |
| 935 | .Oc | |
| 936 | \&... | |
| 937 | .Oo | |
| 938 | .Cm up Ar expr No \(or | |
| 939 | .Cm down Ar expr No \(or | |
| 940 | .Cm left Ar expr No \(or | |
| 941 | .Cm right Ar expr | |
| 942 | .Oc | |
| 943 | .Bd -filled -offset indent | |
| 944 | The | |
| 945 | .Ic label | |
| 946 | command places a label on the given axis. It is possible to specify | |
| 947 | several labels, which will be stacked over each other as in | |
| 948 | .Xr pic . | |
| 949 | The final argument, if present, specifies how many inches the label is | |
| 950 | shifted from the axis. | |
| 951 | .Pp | |
| 952 | By default the labels on the left and right labels run parallel to the | |
| 953 | frame. You can cancel this by specifying | |
| 954 | .Li unaligned | |
| 955 | as a | |
| 956 | .Ar string_modifier . | |
| 957 | .Ed | |
| 958 | .Pp | |
| 959 | .Ic circle | |
| 960 | .Cm at | |
| 961 | .Op Ar coordinate_name | |
| 962 | .Ar expr , expr | |
| 963 | .Op Cm radius Ar expr | |
| 964 | .Op Ar linedesc | |
| 965 | .Bd -filled -offset indent | |
| 966 | This draws an circle at the point indicated. By default, the | |
| 967 | circle is small, 0.025 inches. This can be over-ridden by specifying | |
| 968 | a radius. The coordinates of the point are relative to the named | |
| 969 | coordinate system, or the default system if none is specified. | |
| 970 | .Pp | |
| 971 | This command has been extended to take a line description, | |
| 972 | e.g., | |
| 973 | .Li dotted . | |
| 974 | It also accepts the filling extensions described below in the | |
| 975 | .Ic bar | |
| 976 | command. It will also accept a | |
| 977 | .Ic color | |
| 978 | keyword that gives the color of the outline of the circle in double | |
| 979 | quotes and a | |
| 980 | .Ic fillcolor | |
| 981 | command that sets the color to fill the circle with similarly. Colors | |
| 982 | are only available when compatibility mode is off, and using a version | |
| 983 | of GNU pic that supports color. | |
| 984 | .Ed | |
| 985 | .Pp | |
| 986 | .Ic line | |
| 987 | .Op Ar line_description | |
| 988 | .Cm from | |
| 989 | .Op Ar coordinate_name | |
| 990 | .Ar expr , expr | |
| 991 | .Cm to | |
| 992 | .Op Ar coordinate_name | |
| 993 | .Ar expr , expr | |
| 994 | .Op Ar line_description | |
| 995 | .Pp | |
| 996 | .Ic arrow | |
| 997 | .Op Ar line_description | |
| 998 | .Cm from | |
| 999 | .Op Ar coordinate_name | |
| 1000 | .Ar expr , expr | |
| 1001 | .Cm to | |
| 1002 | .Op Ar coordinate_name | |
| 1003 | .Ar expr , expr | |
| 1004 | .Op Ar line_description | |
| 1005 | .Bd -filled -offset indent | |
| 1006 | This draws a line or arrow from the first point to the second using | |
| 1007 | the given style. The default line style is | |
| 1008 | .Li solid . | |
| 1009 | The | |
| 1010 | .Ar line_description | |
| 1011 | can be given either before the | |
| 1012 | .Cm from | |
| 1013 | or after the | |
| 1014 | .Cm to | |
| 1015 | clause. If both are given the second is used. It is possible to | |
| 1016 | specify one point in one coordinate system and one in another, note | |
| 1017 | that if both points are in a named coordinate system (even if they are | |
| 1018 | in the same named coordinate system), both points must have | |
| 1019 | .Ar coordinate_name | |
| 1020 | given. | |
| 1021 | .Ed | |
| 1022 | .Pp | |
| 1023 | .Pp | |
| 1024 | .Ic copy | |
| 1025 | .Op Qq Ar filename | |
| 1026 | .Op Cm until Qq Ar string | |
| 1027 | .Op Cm thru Ar macro | |
| 1028 | .Bd -filled -offset indent | |
| 1029 | The | |
| 1030 | .Ic copy | |
| 1031 | command imports data from another file into the current graph. The | |
| 1032 | form with only a filename given is a simple file inclusion; the | |
| 1033 | included file is simply read into the input stream and can contain | |
| 1034 | arbitrary | |
| 1035 | .Nm | |
| 1036 | commands. The more common case is that it is a number list; see | |
| 1037 | .Sx Number Lists | |
| 1038 | below. | |
| 1039 | .Pp | |
| 1040 | The second form takes lines from the file, splits them into words | |
| 1041 | delimited by one or more spaces, and calls the given macro with those | |
| 1042 | words as parameters. The macro may either be defined here, or be a | |
| 1043 | macro defined earlier. See | |
| 1044 | .Sx Macros | |
| 1045 | for more information on macros. | |
| 1046 | .Pp | |
| 1047 | The | |
| 1048 | .Ar filename | |
| 1049 | may be omitted if the | |
| 1050 | .Cm until | |
| 1051 | clause is present. If so the current file is treated as the input | |
| 1052 | file until | |
| 1053 | .Ar string | |
| 1054 | is encountered at the beginning of the line. | |
| 1055 | .Pp | |
| 1056 | .Ic copy | |
| 1057 | is one of the workhorses of | |
| 1058 | .Nm grap . | |
| 1059 | Check out the paper and | |
| 1060 | .Pa /usr/local/share/examples/grap | |
| 1061 | for more details. Confirm the location of the examples directory using the | |
| 1062 | .Fl v | |
| 1063 | flag. | |
| 1064 | .Ed | |
| 1065 | .Ic print | |
| 1066 | .Sm off | |
| 1067 | .Ar ( expr \(or string ) | |
| 1068 | .Sm on | |
| 1069 | .Bd -filled -offset indent | |
| 1070 | Prints its argument to the standard error. | |
| 1071 | .Ed | |
| 1072 | .Pp | |
| 1073 | .Ic sh Ar block | |
| 1074 | .Bd -filled -offset indent | |
| 1075 | This passes | |
| 1076 | .Ar block | |
| 1077 | to | |
| 1078 | .Xr sh 1 . | |
| 1079 | Unlike K&B | |
| 1080 | .Nm | |
| 1081 | no macro or variable expansion is done. I believe that this is also | |
| 1082 | true for GNU | |
| 1083 | .Xr pic | |
| 1084 | version 1.10. See the | |
| 1085 | .Sx Macros | |
| 1086 | section for information on defining blocks. | |
| 1087 | .Ed | |
| 1088 | .Pp | |
| 1089 | .Ic pic Ar pic_statement | |
| 1090 | .Bd -filled -offset indent | |
| 1091 | This issues the given | |
| 1092 | .Xr pic | |
| 1093 | statements in the enclosing | |
| 1094 | .Ic .PS | |
| 1095 | and | |
| 1096 | .Ic .PE | |
| 1097 | at the point where the command is issued. | |
| 1098 | .Pp | |
| 1099 | Statements that begin with a period are considered to be | |
| 1100 | .Xr troff statements | |
| 1101 | and are output in the enclosing | |
| 1102 | .Ic .PS | |
| 1103 | and | |
| 1104 | .Ic .PE | |
| 1105 | at the point where the command appears. | |
| 1106 | .Pp | |
| 1107 | For the purposes of relative placement of | |
| 1108 | .Xr pic | |
| 1109 | or | |
| 1110 | .Xr troff | |
| 1111 | commands, the frame is output immediately before the first plotted | |
| 1112 | object, or the | |
| 1113 | .Ic frame | |
| 1114 | statement, if any. If the user specifies | |
| 1115 | .Xr pic | |
| 1116 | or | |
| 1117 | .Xr troff | |
| 1118 | commands and neither any plotable object nor a | |
| 1119 | .Ic frame | |
| 1120 | command, the commands will not be output. | |
| 1121 | .Ed | |
| 1122 | .Pp | |
| 1123 | .Ic graph Ar Name pic_commands | |
| 1124 | .Bd -filled -offset indent | |
| 1125 | This command is used to position graphs with respect to each other. | |
| 1126 | The current graph is given the | |
| 1127 | .Xr pic | |
| 1128 | name | |
| 1129 | .Ar Name | |
| 1130 | (names used by | |
| 1131 | .Xr pic | |
| 1132 | begin with capital letters). Any | |
| 1133 | .Xr pic | |
| 1134 | commands following the graph are used to position the next graph. The | |
| 1135 | frame of the graph is available for use with | |
| 1136 | .Xr pic | |
| 1137 | name | |
| 1138 | .Li Frame. | |
| 1139 | The following places a second graph below the first: | |
| 1140 | .Bd -literal -offset indent-two | |
| 1141 | graph Linear | |
| 1142 | [ graph description ] | |
| 1143 | graph Exponential with .Frame.n at \\ | |
| 1144 | Linear.Frame.s - (0, .05) | |
| 1145 | [ graph description ] | |
| 1146 | .Ed | |
| 1147 | .Ed | |
| 1148 | .Pp | |
| 1149 | .Ar name = expr | |
| 1150 | .Bd -filled -offset indent | |
| 1151 | This assigns | |
| 1152 | .Ar expr | |
| 1153 | to the variable | |
| 1154 | .Ar name . | |
| 1155 | .Nm | |
| 1156 | has only numeric (double) variables. | |
| 1157 | .Pp | |
| 1158 | Assignment creates a variable if it does not exist. Variables persist | |
| 1159 | across graphs. Assignments can cascade; | |
| 1160 | .Li a = b = 35 | |
| 1161 | assigns 35 to | |
| 1162 | .Li a | |
| 1163 | and | |
| 1164 | .Li b . | |
| 1165 | .Ed | |
| 1166 | .Pp | |
| 1167 | .Ic bar | |
| 1168 | .Sm off | |
| 1169 | .No ( Cm up No \(or Cm right ) | |
| 1170 | .Sm on | |
| 1171 | .Op Ar coordinates_name | |
| 1172 | .Ar offset | |
| 1173 | .Cm ht | |
| 1174 | .Ar height | |
| 1175 | .Op Cm wid Ar width | |
| 1176 | .Op Cm base Ar base_offset | |
| 1177 | .Op Ar line_description | |
| 1178 | .Pp | |
| 1179 | .Ic bar | |
| 1180 | .Op Ar coordinates_name | |
| 1181 | .Ar expr , expr , | |
| 1182 | .Op Ar coordinates_name | |
| 1183 | .Ar expr , expr , | |
| 1184 | .Op Ar line_description | |
| 1185 | .Bd -filled -offset indent | |
| 1186 | The | |
| 1187 | .Ic bar | |
| 1188 | command facilitates drawing bar graphs. The first form of the | |
| 1189 | command describes the bar somewhat generally and has | |
| 1190 | .Nm | |
| 1191 | place it. | |
| 1192 | The bar may extend up or to the right, is centered on | |
| 1193 | .Ar offset | |
| 1194 | and extends up or right | |
| 1195 | .Ar height | |
| 1196 | units (in the given coordinate system). For example | |
| 1197 | .Bd -literal -offset indent-two | |
| 1198 | bar up 3 ht 2 | |
| 1199 | .Ed | |
| 1200 | .Pp | |
| 1201 | draws a 2 unit high bar sitting on the x axis, centered on x=3. By | |
| 1202 | default bars are 1 unit wide, but this can be changed with the | |
| 1203 | .Ic wid | |
| 1204 | keyword. By default bars sit on the base axis, i.e., bars directed up | |
| 1205 | will extend from y=0. That may be overridden by the | |
| 1206 | .Ic base | |
| 1207 | keyword. (The bar described above has corners (2.5, 0) and (3.5, 2).) | |
| 1208 | .Pp | |
| 1209 | The line description has been extended to include a | |
| 1210 | .Ic fill Ar expr | |
| 1211 | keyword that specifies the shading inside the bar. Bars may be drawn | |
| 1212 | in any line style. They support the | |
| 1213 | .Ic color | |
| 1214 | and | |
| 1215 | .Ic fillcolor | |
| 1216 | keywords described under | |
| 1217 | .Ic circle . | |
| 1218 | .Pp | |
| 1219 | The second form of the command draws a box with the two points as | |
| 1220 | corners. This can be used to draw boxes highlighting certain data as | |
| 1221 | well as bar graphs. Note that filled bars will cover data drawn under | |
| 1222 | them. | |
| 1223 | .Ed | |
| 1224 | .Ss Control Flow | |
| 1225 | .Pp | |
| 1226 | .Ic if Ar expr Ic then Ar block | |
| 1227 | .Op Ic else Ar block | |
| 1228 | .Bd -filled -offset indent | |
| 1229 | The | |
| 1230 | .Ic if | |
| 1231 | statement provides simple conditional execution. If | |
| 1232 | .Ar expr | |
| 1233 | is non-zero, the | |
| 1234 | .Ar block | |
| 1235 | after the | |
| 1236 | .Ic then | |
| 1237 | statement is executed. If not the | |
| 1238 | .Ar block | |
| 1239 | after the | |
| 1240 | .Ic else | |
| 1241 | is executed, if present. See | |
| 1242 | .Sx Macros | |
| 1243 | for the definition of blocks. Early versions of this implementation | |
| 1244 | of | |
| 1245 | .Nm | |
| 1246 | treated the blocks as macros that were defined and expanded in place. | |
| 1247 | This led to unnecessary confusion because explicit separators were | |
| 1248 | sometimes called for. Now, | |
| 1249 | .Nm | |
| 1250 | inserts a separator (;) after the last character in | |
| 1251 | .Ar block , | |
| 1252 | so constructs like | |
| 1253 | .Bd -literal | |
| 1254 | if (x == 3) { y = y + 1 } | |
| 1255 | x = x + 1 | |
| 1256 | ||
| 1257 | .Ed | |
| 1258 | behave as expected. A separator is also appended to the end of a | |
| 1259 | .Ic for | |
| 1260 | block. | |
| 1261 | .Ed | |
| 1262 | .Pp | |
| 1263 | .Ic for Ar name Ic from Ar from_expr Ic to Ar to_expr | |
| 1264 | .Oo | |
| 1265 | .Ic by | |
| 1266 | .Op No +\(or-\(or*\(or/ | |
| 1267 | .Ar by_expr | |
| 1268 | .Oc | |
| 1269 | .Ic do | |
| 1270 | .Ar block | |
| 1271 | .Bd -filled -offset indent | |
| 1272 | This command executes | |
| 1273 | .Ar block | |
| 1274 | iteratively. The variable | |
| 1275 | .Ar name | |
| 1276 | is set to | |
| 1277 | .Ar from_expr | |
| 1278 | and incremented by | |
| 1279 | .Ar by_expr | |
| 1280 | until it exceeds | |
| 1281 | .Ar to_expr . | |
| 1282 | The iteration has the semantics defined in the | |
| 1283 | .Ic ticks | |
| 1284 | command. The definition of | |
| 1285 | .Ar block | |
| 1286 | is discussed in | |
| 1287 | .Sx Macros . | |
| 1288 | See also the note about implicit separators in the description of the | |
| 1289 | .Ic if | |
| 1290 | command. | |
| 1291 | .Pp | |
| 1292 | An | |
| 1293 | .Ic = | |
| 1294 | can be used in place of | |
| 1295 | .Ic from . | |
| 1296 | .Ed | |
| 1297 | .Ss Expressions | |
| 1298 | .Pp | |
| 1299 | .Nm | |
| 1300 | supports most standard arithmetic operators: + - / * ^. The carat | |
| 1301 | (^) is exponentiation. In an | |
| 1302 | .Ic if | |
| 1303 | statement | |
| 1304 | .Nm | |
| 1305 | also supports the C logical operators ==, !=, | |
| 1306 | &&, || and unary !. Also in an | |
| 1307 | .Ic if , | |
| 1308 | == and != are overloaded for the comparison of | |
| 1309 | quoted strings. Parentheses are used for grouping. | |
| 1310 | .Pp | |
| 1311 | Assignment is not allowed in an expression in any context, except for | |
| 1312 | simple cascading of assignments. | |
| 1313 | .Li a = b = 35 | |
| 1314 | works as expected; | |
| 1315 | .Li a = 3.5 * (b = 10) | |
| 1316 | does not execute. | |
| 1317 | .Pp | |
| 1318 | .Nm | |
| 1319 | supports the following functions that take one argument: | |
| 1320 | .Ic log , exp , int , sin , cos , sqrt , rand . | |
| 1321 | The logarithms are base 10 and the trigonometric functions are in | |
| 1322 | radians. | |
| 1323 | .Ic eexp | |
| 1324 | returns Euler's number to the given power and | |
| 1325 | .Ic ln | |
| 1326 | returns the natural logarithm. The natural log and exponentiation | |
| 1327 | functions are extensions and are probably not available in other | |
| 1328 | .Nm | |
| 1329 | implementations. | |
| 1330 | .Pp | |
| 1331 | .Ic rand | |
| 1332 | returns a random number uniformly | |
| 1333 | distributed on [0,1). The following two-argument functions are supported: | |
| 1334 | .Ic atan2 , min , max . | |
| 1335 | .Ic atan2 | |
| 1336 | works just like | |
| 1337 | .Xr atan2 3 . | |
| 1338 | The random number generator can be seeded by calling | |
| 1339 | .Ic srand | |
| 1340 | with a single parameter (converted internally to an integer). Because | |
| 1341 | its return value is of no use, you must use | |
| 1342 | .Ic srand | |
| 1343 | as a separate statement, it is not part of a valid expression. | |
| 1344 | .Ic srand | |
| 1345 | is not portable. | |
| 1346 | .Pp | |
| 1347 | The | |
| 1348 | .Ic getpid | |
| 1349 | function takes no arguments and returns the process id. This may be | |
| 1350 | used to seed the random number generator, but do not expect | |
| 1351 | cryptographically random values to result. | |
| 1352 | .Pp | |
| 1353 | Other than string comparison, no expressions can use strings. One | |
| 1354 | string valued function exists: | |
| 1355 | .Ic sprintf ( Ar format , | |
| 1356 | .Oo | |
| 1357 | .Ar expr | |
| 1358 | .Op Ar \&, expr | |
| 1359 | .Oc | |
| 1360 | ). It operates like | |
| 1361 | .Xr sprintf 3 , | |
| 1362 | except returning the value. It can be used anywhere a quoted string | |
| 1363 | is used. If | |
| 1364 | .Nm | |
| 1365 | is run with | |
| 1366 | .Fl S , | |
| 1367 | the environment variable | |
| 1368 | .Ev GRAP_SAFER | |
| 1369 | is defined, or | |
| 1370 | .Nm | |
| 1371 | has been compiled for safer operation, the | |
| 1372 | .Ic sprintf | |
| 1373 | command will return the format string. This mode of operation is only | |
| 1374 | intended to be used only if | |
| 1375 | .Nm | |
| 1376 | is being used as part of a super-user enabled print system. | |
| 1377 | .Ss Macros | |
| 1378 | .Nm | |
| 1379 | has a simple but powerful macro facility. Macros are defined using | |
| 1380 | the | |
| 1381 | .Ic define | |
| 1382 | command : | |
| 1383 | .Pp | |
| 1384 | .Ic define Ar name block | |
| 1385 | .br | |
| 1386 | .Ic undefine Ar name | |
| 1387 | .Bd -filled -offset indent | |
| 1388 | Every occurrence of | |
| 1389 | .Ar name | |
| 1390 | in the program text is replaced by the contents of | |
| 1391 | .Ar block . | |
| 1392 | .Ar block | |
| 1393 | is defined by a series of statements in nested { }'s, or a series of | |
| 1394 | statements surrounded by the same letter. An example of the latter is | |
| 1395 | .Bd -literal -offset indent-two | |
| 1396 | define foo X coord x 1,3 X | |
| 1397 | .Ed | |
| 1398 | Each time | |
| 1399 | .Li foo | |
| 1400 | appears in the text, it will be replaced by | |
| 1401 | .Li coord x 1,3 . | |
| 1402 | Macros are literal, and can contain newlines. If a macro does not | |
| 1403 | span multiple lines, it should end in a semicolon to avoid parsing | |
| 1404 | errors. | |
| 1405 | .Pp | |
| 1406 | Macros can take parameters, too. If a macro call is followed by a | |
| 1407 | parenthesized, comma-separated list the values starting with $1 will | |
| 1408 | be replaced in the macro with the elements of the list. A $ not | |
| 1409 | followed by a digit is left unchanged. This parsing | |
| 1410 | is very rudimentary; no nesting or parentheses or escaping of commas | |
| 1411 | is allowed. Also, there is no way to say argument 1 followed by a | |
| 1412 | digit (${1}0 in sh(1)). | |
| 1413 | .Pp | |
| 1414 | The following will draw a line with slope 1. | |
| 1415 | .Bd -literal -offset indent-two | |
| 1416 | define foo { next at $1, $2 } | |
| 1417 | for i from 1 to 5 { foo(i,i) } | |
| 1418 | .Ed | |
| 1419 | Macros persist across graphs. The file | |
| 1420 | .Pa /usr/local/share/grap/grap.defines | |
| 1421 | contains simple macros for plotting common characters. The | |
| 1422 | .Ic undefine | |
| 1423 | command deletes a macro. | |
| 1424 | .Pp | |
| 1425 | See the directory | |
| 1426 | .Pa /usr/local/share/examples/grap | |
| 1427 | for more examples of macros. | |
| 1428 | Confirm the location of the examples directory using the | |
| 1429 | .Fl v | |
| 1430 | flag. | |
| 1431 | .Ed | |
| 1432 | .Ss Number Lists | |
| 1433 | .Pp | |
| 1434 | A whitespace-separated list of numbers is treated specially. The list | |
| 1435 | is taken to be points to be plotted using the default line style on | |
| 1436 | the default coordinate system. If more than two numbers are given, | |
| 1437 | the extra numbers are taken to be additional y values to plot at the | |
| 1438 | first x value. Number lists in DWB | |
| 1439 | .Nm | |
| 1440 | can be comma-separated, and this | |
| 1441 | .Nm | |
| 1442 | supports that as well. More precisely, numbers in number lists can be | |
| 1443 | separated by either whitespace, commas, or both. | |
| 1444 | .Bd -literal -offset indent | |
| 1445 | 1 2 3 | |
| 1446 | 4 5 6 | |
| 1447 | .Ed | |
| 1448 | .sp | |
| 1449 | Will plot points using the default line style at (1,2), (1,3),(4,5) | |
| 1450 | and (4,6). A simple way to plot a set of numbers in a file named | |
| 1451 | .Pa ./data | |
| 1452 | is: | |
| 1453 | .Bd -literal -offset indent | |
| 1454 | \&.G1 | |
| 1455 | copy "./data" | |
| 1456 | \&.G2 | |
| 1457 | .Ed | |
| 1458 | .Ss Pic Macros | |
| 1459 | .Pp | |
| 1460 | .Nm | |
| 1461 | defines pic macros that can be used in embedded pic code to place | |
| 1462 | elements in the graph. The macros are | |
| 1463 | .Ic x_gg , | |
| 1464 | .Ic y_gg , | |
| 1465 | and | |
| 1466 | .Ic xy_gg . | |
| 1467 | These macros define pic distances that correspond to the given | |
| 1468 | argument. They can be used to size boxes or to plot pic constructs on | |
| 1469 | the graph. To place a given construct on the graph, you should add | |
| 1470 | Frame.Origin to it. | |
| 1471 | Other coordinate spaces can be used by replacing | |
| 1472 | .Ic gg | |
| 1473 | with the name of the coordinate space. A coordinate space named | |
| 1474 | .Ic gg | |
| 1475 | cannot be reliably accessed by these macros. | |
| 1476 | .Pp | |
| 1477 | The macros are emitted immediately before the frame is drawn. | |
| 1478 | .Pp | |
| 1479 | DWB | |
| 1480 | .Nm | |
| 1481 | may use these as part of its implementation. This | |
| 1482 | .Nm | |
| 1483 | provides them only for compatibility. Note that these are very simple | |
| 1484 | macros, and may not do what you expect under complex conditions. | |
| 1485 | .Sh ENVIRONMENT VARIABLES | |
| 1486 | .Pp | |
| 1487 | If the environment variable | |
| 1488 | .Ev GRAP_DEFINES | |
| 1489 | is defined, | |
| 1490 | .Nm | |
| 1491 | will look for its defines file there. If that value is a relative path | |
| 1492 | name the path specified in the | |
| 1493 | .Fl M | |
| 1494 | option will be searched for it. | |
| 1495 | .Ev GRAP_DEFINES | |
| 1496 | overrides the compiled in location of the defines file, but may be | |
| 1497 | overridden by the | |
| 1498 | .Fl d | |
| 1499 | or | |
| 1500 | .Fl D | |
| 1501 | flags. | |
| 1502 | .Pp | |
| 1503 | If | |
| 1504 | .Ev GRAP_SAFER | |
| 1505 | is set, | |
| 1506 | .Ic sprintf | |
| 1507 | is disabled to prevent forcing | |
| 1508 | .Nm | |
| 1509 | to core dump or smash the stack. | |
| 1510 | .Sh FILES | |
| 1511 | .Pa /usr/local/share/grap/grap.defines | |
| 1512 | .Sh SEE ALSO | |
| 1513 | .Xr atan2 3 , | |
| 1514 | .Xr groff 1 , | |
| 1515 | .Xr pic 1 , | |
| 1516 | .Xr printf 3 , | |
| 1517 | .Xr sh 1 , | |
| 1518 | .Xr sprintf 3 , | |
| 1519 | .Xr troff 1 | |
| 1520 | .Pp | |
| 1521 | If documentation and examples have been installed, | |
| 1522 | .Nm | |
| 1523 | .Fl -version | |
| 1524 | or | |
| 1525 | .Nm | |
| 1526 | .Fl -help | |
| 1527 | will display the locations. | |
| 1528 | .Sh BUGS | |
| 1529 | .Pp | |
| 1530 | There are several small incompatibilities with K&R | |
| 1531 | .Nm grap . | |
| 1532 | They include the | |
| 1533 | .Ic sh | |
| 1534 | command not expanding variables and macros, and a more strict | |
| 1535 | adherence to parameter order in the internal commands. | |
| 1536 | .Pp | |
| 1537 | Although much improved, the error reporting code can still be | |
| 1538 | confused. Notably, an error in a macro is not detected until the | |
| 1539 | macro is used, and it produces unusual output in the error message. | |
| 1540 | .Pp | |
| 1541 | Iterating many times over a macro with no newlines can run | |
| 1542 | .Nm | |
| 1543 | out of memory. | |
| 1544 | .Sh AUTHOR | |
| 1545 | This implementation was done by | |
| 1546 | .An Ted Faber Ao faber@lunabase.org Ac Ns . | |
| 1547 | .An Bruce Lilly Ao blilly@erols.com Ac | |
| 1548 | contributed many bug fixes, including a considerable revamp of the | |
| 1549 | error reporting code. If you can actually find an error in your | |
| 1550 | .Nm | |
| 1551 | code, you can probably thank him. | |
| 1552 | .Nm | |
| 1553 | was designed and specified by | |
| 1554 | .An Brian Kernighan | |
| 1555 | and | |
| 1556 | .An Jon Bentley . |
| 0 | <?xml version="1.0" encoding="ISO-8859-1"?> | |
| 1 | <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" | |
| 2 | "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [ | |
| 3 | <!ENTITY lh '☞'> | |
| 4 | <!ENTITY rh '☜'> | |
| 5 | <!ENTITY CR '␍'> | |
| 6 | <!ENTITY fo '‹'> | |
| 7 | <!ENTITY fc '›'> | |
| 8 | <!ENTITY an '⎯'> | |
| 9 | <!ENTITY lb '⎩'> | |
| 10 | <!ENTITY lc '⎡'> | |
| 11 | <!ENTITY lf '⎣'> | |
| 12 | <!ENTITY lk '⎨'> | |
| 13 | <!ENTITY tlt '⎧'> | |
| 14 | <!ENTITY rb '⎭'> | |
| 15 | <!ENTITY rc '⎤'> | |
| 16 | <!ENTITY rf '⎦'> | |
| 17 | <!ENTITY rk '⎬'> | |
| 18 | <!ENTITY rt '⎫'> | |
| 19 | <!ENTITY bracerightmid '⎬'> | |
| 20 | <!ENTITY bracerightex '⎪'> | |
| 21 | <!ENTITY parenlefttp '⎛'> | |
| 22 | <!ENTITY parenleftbt '⎝'> | |
| 23 | <!ENTITY parenleftex '⎜'> | |
| 24 | <!ENTITY parenrighttp '⎞'> | |
| 25 | <!ENTITY parenrightbt '⎠'> | |
| 26 | <!ENTITY parenrightex '⎟'> | |
| 27 | <!ENTITY radicalex '‾'> | |
| 28 | <!ENTITY sqrtex '‾'> | |
| 29 | <!ENTITY jnodot 'í'> | |
| 30 | ]> | |
| 31 | <!-- lifted from man+troff by doclifter --> | |
| 32 | <refentry> | |
| 33 | <refentryinfo><date>01 April 2012</date></refentryinfo> | |
| 34 | <refmeta> | |
| 35 | <refentrytitle>GROFF_CHAR</refentrytitle> | |
| 36 | <manvolnum>7</manvolnum> | |
| 37 | <refmiscinfo class='date'>01 April 2012</refmiscinfo> | |
| 38 | <refmiscinfo class='source'>Groff Version 1.21</refmiscinfo> | |
| 39 | </refmeta> | |
| 40 | <refnamediv> | |
| 41 | <refname>groff_char</refname> | |
| 42 | <refpurpose>groff glyph names</refpurpose> | |
| 43 | </refnamediv> | |
| 44 | <!-- body begins here --> | |
| 45 | ||
| 46 | <refsect1 id='description'><title>DESCRIPTION</title> | |
| 47 | <!-- The lines above were designed to satisfy `apropos'. --> | |
| 48 | ||
| 49 | <!-- For best results, format this document with `groff' (GNU roff). --> | |
| 50 | ||
| 51 | ||
| 52 | ||
| 53 | <!-- Legal terms --> | |
| 54 | ||
| 55 | ||
| 56 | <!-- .ig | |
| 57 | groff_char(7) | |
| 58 | ||
| 59 | This file is part of groff (GNU roff). | |
| 60 | ||
| 61 | File position: <groff_src_top>/man/groff_char.man | |
| 62 | ||
| 63 | Copyright (C) 1989—2000, 2001, 2002, 2003, 2004, 2006, 2007, 2008, 2009 | |
| 64 | Free Software Foundation, Inc. | |
| 65 | written by Werner Lemberg <wl@gnu.org> | |
| 66 | with additions by Bernd Warken <bwarken@mayn.de> | |
| 67 | ||
| 68 | Permission is granted to copy, distribute and/or modify this document | |
| 69 | under the terms of the GNU Free Documentation License, Version 1.3 or | |
| 70 | any later version published by the Free Software Foundation; with the | |
| 71 | Invariant Sections being this .ig—section and AUTHOR, with no | |
| 72 | Front—Cover Texts, and with no Back—Cover Texts. | |
| 73 | ||
| 74 | A copy of the Free Documentation License is included as a file called | |
| 75 | FDL in the main directory of the groff source package. | |
| 76 | .. | |
| 77 | .ig | |
| 78 | A copy of the GNU Free Documentation License is also available in this | |
| 79 | Debian package as /usr/share/doc/groff/copyright. | |
| 80 | .. --> | |
| 81 | ||
| 82 | ||
| 83 | <!-- Setup --> | |
| 84 | ||
| 85 | ||
| 86 | <!-- cp 0 --> | |
| 87 | ||
| 88 | <!-- groff only | |
| 89 | .if 0 .ne 2v | |
| 90 | .if 0 .sv 2v --> | |
| 91 | ||
| 92 | ||
| 93 | <!-- non\-groff --> | |
| 94 | ||
| 95 | ||
| 96 | ||
| 97 | ||
| 98 | ||
| 99 | <!-- .SH DESCRIPTION --> | |
| 100 | ||
| 101 | ||
| 102 | <para>This manual page lists the standard | |
| 103 | <emphasis remap='B'>groff</emphasis> | |
| 104 | glyph names and the default input mapping, ­latin1. | |
| 105 | ||
| 106 | The glyphs in this document look different depending | |
| 107 | on which output device was chosen (with option | |
| 108 | <option>-T</option> | |
| 109 | for the | |
| 110 | <citerefentry><refentrytitle>man</refentrytitle><manvolnum>1</manvolnum></citerefentry> | |
| 111 | program or the roff formatter). | |
| 112 | ||
| 113 | Glyphs not available for the device that | |
| 114 | is being used to print or view this manual page are marked with | |
| 115 | `(N/A)'.</para> | |
| 116 | ||
| 117 | ||
| 118 | ||
| 119 | <para>In the actual version, | |
| 120 | <emphasis remap='B'>groff</emphasis> | |
| 121 | provides only ­8-bit characters for direct input and named entities | |
| 122 | for further glyphs. | |
| 123 | ||
| 124 | On ASCII platforms, input character codes in the range 0 to 127 (decimal) | |
| 125 | represent the usual ­7-bit ASCII characters, while codes between 127 | |
| 126 | and 255 are interpreted as the corresponding characters in the | |
| 127 | <emphasis remap='I'>­latin1</emphasis> | |
| 128 | (<emphasis remap='I'>­ISO-8859-1</emphasis>) | |
| 129 | code set by default. | |
| 130 | ||
| 131 | This mapping is contained in the file <emphasis remap='CW'>latin1.tmac</emphasis> | |
| 132 | and can be changed by loading a different input encoding. | |
| 133 | ||
| 134 | Note that some of the input characters are reserved by | |
| 135 | <emphasis remap='B'>groff</emphasis>, | |
| 136 | either for internal use or for special input purposes. | |
| 137 | ||
| 138 | On EBCDIC platforms, only code page | |
| 139 | <emphasis remap='I'>cp1047</emphasis> | |
| 140 | is supported (which contains the same characters as ­latin1; the | |
| 141 | input encoding file is called <emphasis remap='CW'>cp1047.tmac</emphasis>). | |
| 142 | ||
| 143 | Again, some input characters are reserved for internal and special purposes.</para> | |
| 144 | ||
| 145 | ||
| 146 | ||
| 147 | <para>All roff systems provide the concept of named glyphs. | |
| 148 | ||
| 149 | In traditional roff systems, only names of length 2 were used, while | |
| 150 | groff also provides support for longer names. | |
| 151 | ||
| 152 | It is strongly suggested that only named glyphs are used for all | |
| 153 | character representations outside of the printable ­7-bit ASCII range.</para> | |
| 154 | ||
| 155 | ||
| 156 | ||
| 157 | <para>Some of the predefined groff escape sequences (with names of length 1) | |
| 158 | also produce single glyphs; these exist for historical reasons or | |
| 159 | are printable versions of syntactical characters. | |
| 160 | ||
| 161 | They include `<emphasis remap='CW'>\\</emphasis>', `<emphasis remap='CW'>\´</emphasis>', `<emphasis remap='CW'>\`</emphasis>', `<emphasis remap='CW'>\-</emphasis>', | |
| 162 | `<emphasis remap='CW'>\.</emphasis>', and `<emphasis remap='CW'>\e</emphasis>'; see | |
| 163 | <citerefentry><refentrytitle>groff</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para> | |
| 164 | ||
| 165 | ||
| 166 | ||
| 167 | <para>In groff, all of these different types of characters and glyphs can be | |
| 168 | tested positively with the `<emphasis remap='CW'>.if c</emphasis>' conditional.</para> | |
| 169 | ||
| 170 | ||
| 171 | ||
| 172 | </refsect1> | |
| 173 | ||
| 174 | <refsect1 id='reference'><title>REFERENCE</title> | |
| 175 | ||
| 176 | <para>In this section, the glyphs in groff are specified in tabular | |
| 177 | form. | |
| 178 | ||
| 179 | The meaning of the columns is as follows.</para> | |
| 180 | ||
| 181 | ||
| 182 | <variablelist remap='TP'> | |
| 183 | <varlistentry> | |
| 184 | <term><emphasis remap='I'>Output</emphasis></term> | |
| 185 | <listitem> | |
| 186 | <para>shows how the glyph is printed for the current device; although | |
| 187 | this can have quite a different shape on other devices, it always | |
| 188 | represents the same glyph.</para> | |
| 189 | ||
| 190 | ||
| 191 | </listitem> | |
| 192 | </varlistentry> | |
| 193 | <varlistentry> | |
| 194 | <term><emphasis remap='I'>Input</emphasis></term> | |
| 195 | <listitem> | |
| 196 | <para>specifies how the glyph is input either directly by a key on the | |
| 197 | keyboard, or by a groff escape sequence.</para> | |
| 198 | ||
| 199 | ||
| 200 | </listitem> | |
| 201 | </varlistentry> | |
| 202 | <varlistentry> | |
| 203 | <term><emphasis remap='I'>Code</emphasis></term> | |
| 204 | <listitem> | |
| 205 | <para>applies to glyphs which can be input with a single character, and | |
| 206 | gives the ISO ­latin1 decimal code of that input character. | |
| 207 | ||
| 208 | Note that this code is equivalent to the lowest 256 Unicode characters, | |
| 209 | including ­7-bit ASCII in the range 0 to 127.</para> | |
| 210 | ||
| 211 | ||
| 212 | </listitem> | |
| 213 | </varlistentry> | |
| 214 | <varlistentry> | |
| 215 | <term><emphasis remap='I'>PostScript</emphasis></term> | |
| 216 | <listitem> | |
| 217 | <para>gives the usual PostScript name of the glyph.</para> | |
| 218 | ||
| 219 | ||
| 220 | </listitem> | |
| 221 | </varlistentry> | |
| 222 | <varlistentry> | |
| 223 | <term><emphasis remap='I'>Unicode</emphasis></term> | |
| 224 | <listitem> | |
| 225 | <para>is the glyph name used in composite glyph names.</para> | |
| 226 | ||
| 227 | ||
| 228 | ||
| 229 | ||
| 230 | </listitem> | |
| 231 | </varlistentry> | |
| 232 | </variablelist> | |
| 233 | ||
| 234 | <refsect2 id='x7bit_character_codes_32126'><title>7-bit Character Codes 32-126</title> | |
| 235 | ||
| 236 | ||
| 237 | <para>These are the basic glyphs having 7-bit ASCII code values assigned. | |
| 238 | ||
| 239 | They are identical to the printable characters of the | |
| 240 | character standards ­ISO-8859-1 (­latin1) and Unicode (range | |
| 241 | <emphasis remap='I'>Basic Latin</emphasis>). | |
| 242 | ||
| 243 | The glyph names used in composite glyph names are `u0020' up to `u007E'.</para> | |
| 244 | ||
| 245 | ||
| 246 | ||
| 247 | <para>Note that input characters in the range ­0-31 and character 127 are | |
| 248 | <emphasis remap='I'>not</emphasis> | |
| 249 | printable characters. | |
| 250 | ||
| 251 | Most of them are invalid input characters for | |
| 252 | <emphasis remap='B'>groff</emphasis> | |
| 253 | anyway, and the valid ones have special meaning. | |
| 254 | ||
| 255 | For EBCDIC, the printable characters are in the range ­66-255.</para> | |
| 256 | ||
| 257 | ||
| 258 | <variablelist remap='TP'> | |
| 259 | <varlistentry> | |
| 260 | <term>48-57</term> | |
| 261 | <listitem> | |
| 262 | <para>Decimal digits 0 to 9 (print as themselves).</para> | |
| 263 | ||
| 264 | ||
| 265 | </listitem> | |
| 266 | </varlistentry> | |
| 267 | <varlistentry> | |
| 268 | <term>65-90</term> | |
| 269 | <listitem> | |
| 270 | <para>Upper case letters A-Z (print as themselves).</para> | |
| 271 | ||
| 272 | ||
| 273 | </listitem> | |
| 274 | </varlistentry> | |
| 275 | <varlistentry> | |
| 276 | <term>97-122</term> | |
| 277 | <listitem> | |
| 278 | <para>Lower case letters a-z (print as themselves).</para> | |
| 279 | ||
| 280 | ||
| 281 | ||
| 282 | <para>Most of the remaining characters not in the just described ranges print as | |
| 283 | themselves; the only exceptions are the following characters:</para> | |
| 284 | ||
| 285 | ||
| 286 | </listitem> | |
| 287 | </varlistentry> | |
| 288 | <varlistentry> | |
| 289 | <term><emphasis remap='B'>`</emphasis></term> | |
| 290 | <listitem> | |
| 291 | <para>the ISO ­latin1 `Grave Accent' (code 96) prints as `, a left single | |
| 292 | quotation mark; the original character can be obtained with `<emphasis remap='CW'>\`</emphasis>'.</para> | |
| 293 | ||
| 294 | ||
| 295 | </listitem> | |
| 296 | </varlistentry> | |
| 297 | <varlistentry> | |
| 298 | <term><emphasis remap='B'>''</emphasis></term> | |
| 299 | <listitem> | |
| 300 | <para>the ISO ­latin1 `Apostrophe' (code 39) prints as ', a right single | |
| 301 | quotation mark; the original character can be obtained with `<emphasis remap='CW'>\(aq</emphasis>'.</para> | |
| 302 | ||
| 303 | ||
| 304 | </listitem> | |
| 305 | </varlistentry> | |
| 306 | <varlistentry> | |
| 307 | <term><emphasis remap='B'>-</emphasis></term> | |
| 308 | <listitem> | |
| 309 | <para>the ISO ­latin1 `Hyphen, Minus Sign' (code 45) prints as a hyphen; a | |
| 310 | minus sign can be obtained with `<emphasis remap='CW'>\-</emphasis>'.</para> | |
| 311 | ||
| 312 | ||
| 313 | </listitem> | |
| 314 | </varlistentry> | |
| 315 | <varlistentry> | |
| 316 | <term><emphasis remap='B'>~</emphasis></term> | |
| 317 | <listitem> | |
| 318 | <para>the ISO ­latin1 `Tilde' (code 126) is reduced in size to be usable as | |
| 319 | a diacritic; a larger glyph can be obtained with `<emphasis remap='CW'>\(ti</emphasis>'.</para> | |
| 320 | ||
| 321 | ||
| 322 | </listitem> | |
| 323 | </varlistentry> | |
| 324 | <varlistentry> | |
| 325 | <term><emphasis remap='B'>^</emphasis></term> | |
| 326 | <listitem> | |
| 327 | <para>the ISO ­latin1 `Circumflex Accent' (code 94) is reduced in size to be | |
| 328 | usable as a diacritic; a larger glyph can be obtained with `<emphasis remap='CW'>\(ha</emphasis>'.</para> | |
| 329 | ||
| 330 | <informaltable pgwide='0' frame='none'> | |
| 331 | <tgroup cols='5' align='center'> | |
| 332 | <colspec colname='c1'/> | |
| 333 | <colspec colname='c2'/> | |
| 334 | <colspec colname='c3'/> | |
| 335 | <colspec colname='c4'/> | |
| 336 | <colspec colname='c5'/> | |
| 337 | <tbody> | |
| 338 | <row rowsep='1'> | |
| 339 | <entry align='left'>Output </entry> | |
| 340 | <entry align='left'>Input </entry> | |
| 341 | <entry align='left'>Code</entry> | |
| 342 | <entry align='left'>PostScript</entry> | |
| 343 | <entry align='left'>Unicode </entry> | |
| 344 | <entry align='left'>Notes</entry> | |
| 345 | </row> | |
| 346 | <row> | |
| 347 | <entry align='left'>!</entry> | |
| 348 | <entry align='left'>!</entry> | |
| 349 | <entry align='left'>33</entry> | |
| 350 | <entry align='left'>exclam </entry> | |
| 351 | <entry align='left'>u0021</entry> | |
| 352 | <entry align='left'></entry> | |
| 353 | </row> | |
| 354 | <row> | |
| 355 | <entry align='left'>"</entry> | |
| 356 | <entry align='left'>"</entry> | |
| 357 | <entry align='left'>34</entry> | |
| 358 | <entry align='left'>quotedbl</entry> | |
| 359 | <entry align='left'>u0022</entry> | |
| 360 | <entry align='left'></entry> | |
| 361 | </row> | |
| 362 | <row> | |
| 363 | <entry align='left'>#</entry> | |
| 364 | <entry align='left'>#</entry> | |
| 365 | <entry align='left'>35</entry> | |
| 366 | <entry align='left'>numbersign</entry> | |
| 367 | <entry align='left'>u0023</entry> | |
| 368 | <entry align='left'></entry> | |
| 369 | </row> | |
| 370 | <row> | |
| 371 | <entry align='left'>$</entry> | |
| 372 | <entry align='left'>$</entry> | |
| 373 | <entry align='left'>36</entry> | |
| 374 | <entry align='left'>dollar </entry> | |
| 375 | <entry align='left'>u0024</entry> | |
| 376 | <entry align='left'></entry> | |
| 377 | </row> | |
| 378 | <row> | |
| 379 | <entry align='left'>%</entry> | |
| 380 | <entry align='left'>%</entry> | |
| 381 | <entry align='left'>37</entry> | |
| 382 | <entry align='left'>percent </entry> | |
| 383 | <entry align='left'>u0025</entry> | |
| 384 | <entry align='left'></entry> | |
| 385 | </row> | |
| 386 | <row> | |
| 387 | <entry align='left'>&</entry> | |
| 388 | <entry align='left'>&</entry> | |
| 389 | <entry align='left'>38</entry> | |
| 390 | <entry align='left'>ampersand</entry> | |
| 391 | <entry align='left'>u0026</entry> | |
| 392 | <entry align='left'></entry> | |
| 393 | </row> | |
| 394 | <row> | |
| 395 | <entry align='left'>'</entry> | |
| 396 | <entry align='left'>'</entry> | |
| 397 | <entry align='left'>39</entry> | |
| 398 | <entry align='left'>quoteright</entry> | |
| 399 | <entry align='left'>u0027</entry> | |
| 400 | <entry align='left'></entry> | |
| 401 | </row> | |
| 402 | <row> | |
| 403 | <entry align='left'>(</entry> | |
| 404 | <entry align='left'>(</entry> | |
| 405 | <entry align='left'>40</entry> | |
| 406 | <entry align='left'>parenleft</entry> | |
| 407 | <entry align='left'>u0028</entry> | |
| 408 | <entry align='left'></entry> | |
| 409 | </row> | |
| 410 | <row> | |
| 411 | <entry align='left'>)</entry> | |
| 412 | <entry align='left'>)</entry> | |
| 413 | <entry align='left'>41</entry> | |
| 414 | <entry align='left'>parenright</entry> | |
| 415 | <entry align='left'>u0029</entry> | |
| 416 | <entry align='left'></entry> | |
| 417 | </row> | |
| 418 | <row> | |
| 419 | <entry align='left'>*</entry> | |
| 420 | <entry align='left'>*</entry> | |
| 421 | <entry align='left'>42</entry> | |
| 422 | <entry align='left'>asterisk</entry> | |
| 423 | <entry align='left'>u002A</entry> | |
| 424 | <entry align='left'></entry> | |
| 425 | </row> | |
| 426 | <row> | |
| 427 | <entry align='left'>+</entry> | |
| 428 | <entry align='left'>+</entry> | |
| 429 | <entry align='left'>43</entry> | |
| 430 | <entry align='left'>plus </entry> | |
| 431 | <entry align='left'>u002B</entry> | |
| 432 | <entry align='left'></entry> | |
| 433 | </row> | |
| 434 | <row> | |
| 435 | <entry align='left'>,</entry> | |
| 436 | <entry align='left'>,</entry> | |
| 437 | <entry align='left'>44</entry> | |
| 438 | <entry align='left'>comma </entry> | |
| 439 | <entry align='left'>u002C</entry> | |
| 440 | <entry align='left'></entry> | |
| 441 | </row> | |
| 442 | <row> | |
| 443 | <entry align='left'>-</entry> | |
| 444 | <entry align='left'>-</entry> | |
| 445 | <entry align='left'>45</entry> | |
| 446 | <entry align='left'>hyphen </entry> | |
| 447 | <entry align='left'>u2010</entry> | |
| 448 | <entry align='left'></entry> | |
| 449 | </row> | |
| 450 | <row> | |
| 451 | <entry align='left'>.</entry> | |
| 452 | <entry align='left'>.</entry> | |
| 453 | <entry align='left'>46</entry> | |
| 454 | <entry align='left'>period </entry> | |
| 455 | <entry align='left'>u002E</entry> | |
| 456 | <entry align='left'></entry> | |
| 457 | </row> | |
| 458 | <row> | |
| 459 | <entry align='left'>/</entry> | |
| 460 | <entry align='left'>/</entry> | |
| 461 | <entry align='left'>47</entry> | |
| 462 | <entry align='left'>slash </entry> | |
| 463 | <entry align='left'>u002F</entry> | |
| 464 | <entry align='left'></entry> | |
| 465 | </row> | |
| 466 | <row> | |
| 467 | <entry align='left'>:</entry> | |
| 468 | <entry align='left'>:</entry> | |
| 469 | <entry align='left'>58</entry> | |
| 470 | <entry align='left'>colon </entry> | |
| 471 | <entry align='left'>u003A</entry> | |
| 472 | <entry align='left'></entry> | |
| 473 | </row> | |
| 474 | <row> | |
| 475 | <entry align='left'>;</entry> | |
| 476 | <entry align='left'>;</entry> | |
| 477 | <entry align='left'>59</entry> | |
| 478 | <entry align='left'>semicolon</entry> | |
| 479 | <entry align='left'>u003B</entry> | |
| 480 | <entry align='left'></entry> | |
| 481 | </row> | |
| 482 | <row> | |
| 483 | <entry align='left'><</entry> | |
| 484 | <entry align='left'><</entry> | |
| 485 | <entry align='left'>60</entry> | |
| 486 | <entry align='left'>less </entry> | |
| 487 | <entry align='left'>u003C</entry> | |
| 488 | <entry align='left'></entry> | |
| 489 | </row> | |
| 490 | <row> | |
| 491 | <entry align='left'>=</entry> | |
| 492 | <entry align='left'>=</entry> | |
| 493 | <entry align='left'>61</entry> | |
| 494 | <entry align='left'>equal </entry> | |
| 495 | <entry align='left'>u003D</entry> | |
| 496 | <entry align='left'></entry> | |
| 497 | </row> | |
| 498 | <row> | |
| 499 | <entry align='left'>></entry> | |
| 500 | <entry align='left'>></entry> | |
| 501 | <entry align='left'>62</entry> | |
| 502 | <entry align='left'>greater </entry> | |
| 503 | <entry align='left'>u003E</entry> | |
| 504 | <entry align='left'></entry> | |
| 505 | </row> | |
| 506 | <row> | |
| 507 | <entry align='left'>?</entry> | |
| 508 | <entry align='left'>?</entry> | |
| 509 | <entry align='left'>63</entry> | |
| 510 | <entry align='left'>question</entry> | |
| 511 | <entry align='left'>u003F</entry> | |
| 512 | <entry align='left'></entry> | |
| 513 | </row> | |
| 514 | <row> | |
| 515 | <entry align='left'>@</entry> | |
| 516 | <entry align='left'>@</entry> | |
| 517 | <entry align='left'>64</entry> | |
| 518 | <entry align='left'>at </entry> | |
| 519 | <entry align='left'>u0040</entry> | |
| 520 | <entry align='left'></entry> | |
| 521 | </row> | |
| 522 | <row> | |
| 523 | <entry align='left'>[</entry> | |
| 524 | <entry align='left'>[</entry> | |
| 525 | <entry align='left'>91</entry> | |
| 526 | <entry align='left'>bracketleft</entry> | |
| 527 | <entry align='left'>u005B</entry> | |
| 528 | <entry align='left'></entry> | |
| 529 | </row> | |
| 530 | <row> | |
| 531 | <entry align='left'>\</entry> | |
| 532 | <entry align='left'>\</entry> | |
| 533 | <entry align='left'>92</entry> | |
| 534 | <entry align='left'>backslash</entry> | |
| 535 | <entry align='left'>u005C</entry> | |
| 536 | <entry align='left'></entry> | |
| 537 | </row> | |
| 538 | <row> | |
| 539 | <entry align='left'>]</entry> | |
| 540 | <entry align='left'>]</entry> | |
| 541 | <entry align='left'>93</entry> | |
| 542 | <entry align='left'>bracketright</entry> | |
| 543 | <entry align='left'>u005D</entry> | |
| 544 | <entry align='left'></entry> | |
| 545 | </row> | |
| 546 | <row> | |
| 547 | <entry align='left'>^</entry> | |
| 548 | <entry align='left'>^</entry> | |
| 549 | <entry align='left'>94</entry> | |
| 550 | <entry align='left'>circumflex</entry> | |
| 551 | <entry align='left'>u005E</entry> | |
| 552 | <entry align='left'>circumflex accent</entry> | |
| 553 | </row> | |
| 554 | <row> | |
| 555 | <entry align='left'>_</entry> | |
| 556 | <entry align='left'>_</entry> | |
| 557 | <entry align='left'>95</entry> | |
| 558 | <entry align='left'>underscore</entry> | |
| 559 | <entry align='left'>u005F</entry> | |
| 560 | <entry align='left'></entry> | |
| 561 | </row> | |
| 562 | <row> | |
| 563 | <entry align='left'>`</entry> | |
| 564 | <entry align='left'>`</entry> | |
| 565 | <entry align='left'>96</entry> | |
| 566 | <entry align='left'>quoteleft</entry> | |
| 567 | <entry align='left'>u0060</entry> | |
| 568 | <entry align='left'></entry> | |
| 569 | </row> | |
| 570 | <row> | |
| 571 | <entry align='left'>{</entry> | |
| 572 | <entry align='left'>{</entry> | |
| 573 | <entry align='left'>123</entry> | |
| 574 | <entry align='left'>braceleft</entry> | |
| 575 | <entry align='left'>u007B</entry> | |
| 576 | <entry align='left'></entry> | |
| 577 | </row> | |
| 578 | <row> | |
| 579 | <entry align='left'>|</entry> | |
| 580 | <entry align='left'>|</entry> | |
| 581 | <entry align='left'>124</entry> | |
| 582 | <entry align='left'>bar </entry> | |
| 583 | <entry align='left'>u007C</entry> | |
| 584 | <entry align='left'></entry> | |
| 585 | </row> | |
| 586 | <row> | |
| 587 | <entry align='left'>}</entry> | |
| 588 | <entry align='left'>}</entry> | |
| 589 | <entry align='left'>125</entry> | |
| 590 | <entry align='left'>braceright</entry> | |
| 591 | <entry align='left'>u007D</entry> | |
| 592 | <entry align='left'></entry> | |
| 593 | </row> | |
| 594 | <row> | |
| 595 | <entry align='left'>~</entry> | |
| 596 | <entry align='left'>~</entry> | |
| 597 | <entry align='left'>126</entry> | |
| 598 | <entry align='left'>tilde </entry> | |
| 599 | <entry align='left'>u007E</entry> | |
| 600 | <entry align='left'>tilde accent</entry> | |
| 601 | </row> | |
| 602 | </tbody> | |
| 603 | </tgroup> | |
| 604 | </informaltable> | |
| 605 | ||
| 606 | ||
| 607 | ||
| 608 | ||
| 609 | ||
| 610 | </listitem> | |
| 611 | </varlistentry> | |
| 612 | </variablelist> | |
| 613 | </refsect2> | |
| 614 | ||
| 615 | <refsect2 id='x8bit_character_codes_160_to_255'><title>8-bit Character Codes 160 to 255</title> | |
| 616 | ||
| 617 | ||
| 618 | <para>They are interpreted as printable characters according to the | |
| 619 | <emphasis remap='I'>latin1</emphasis> | |
| 620 | (<emphasis remap='I'>ISO-8859-1</emphasis>) | |
| 621 | code set, being identical to the Unicode range | |
| 622 | <emphasis remap='I'>Latin-1 Supplement</emphasis>.</para> | |
| 623 | ||
| 624 | ||
| 625 | ||
| 626 | <para>Input characters in range 128-159 (on non-EBCDIC hosts) are not printable | |
| 627 | characters.</para> | |
| 628 | ||
| 629 | ||
| 630 | <variablelist remap='TP'> | |
| 631 | <varlistentry> | |
| 632 | <term>160</term> | |
| 633 | <listitem> | |
| 634 | ||
| 635 | <para>the ISO ­latin1 | |
| 636 | <emphasis remap='I'>no-break space</emphasis> | |
| 637 | is mapped to `<emphasis remap='CW'>\~</emphasis>', the stretchable space character.</para> | |
| 638 | ||
| 639 | ||
| 640 | </listitem> | |
| 641 | </varlistentry> | |
| 642 | <varlistentry> | |
| 643 | <term>173</term> | |
| 644 | <listitem> | |
| 645 | ||
| 646 | <para>the soft hyphen control character. | |
| 647 | ||
| 648 | <emphasis remap='B'>groff</emphasis> | |
| 649 | never uses this character for output (thus it is omitted in the | |
| 650 | table below); the input character 173 is mapped onto `<emphasis remap='CW'>\%</emphasis>'.</para> | |
| 651 | ||
| 652 | ||
| 653 | ||
| 654 | <para>The remaining ranges (­161-172, ­174-255) | |
| 655 | are printable characters that print as themselves. | |
| 656 | ||
| 657 | Although they can be specified directly with the keyboard on systems | |
| 658 | with a ­latin1 code page, it is better to use their glyph names; | |
| 659 | see next section.</para> | |
| 660 | ||
| 661 | <informaltable pgwide='0' frame='none'> | |
| 662 | <tgroup cols='5' align='center'> | |
| 663 | <colspec colname='c1'/> | |
| 664 | <colspec colname='c2'/> | |
| 665 | <colspec colname='c3'/> | |
| 666 | <colspec colname='c4'/> | |
| 667 | <colspec colname='c5'/> | |
| 668 | <tbody> | |
| 669 | <row rowsep='1'> | |
| 670 | <entry align='left'>Output </entry> | |
| 671 | <entry align='left'>Input </entry> | |
| 672 | <entry align='left'>Code</entry> | |
| 673 | <entry align='left'>PostScript</entry> | |
| 674 | <entry align='left'>Unicode</entry> | |
| 675 | <entry align='left'>Notes</entry> | |
| 676 | </row> | |
| 677 | <row> | |
| 678 | <entry align='left'>¡</entry> | |
| 679 | <entry align='left'>¡</entry> | |
| 680 | <entry align='left'>161</entry> | |
| 681 | <entry align='left'>exclamdown</entry> | |
| 682 | <entry align='left'>u00A1</entry> | |
| 683 | <entry align='left'>inverted exclamation mark</entry> | |
| 684 | </row> | |
| 685 | <row> | |
| 686 | <entry align='left'>¢</entry> | |
| 687 | <entry align='left'>¢</entry> | |
| 688 | <entry align='left'>162</entry> | |
| 689 | <entry align='left'>cent </entry> | |
| 690 | <entry align='left'>u00A2</entry> | |
| 691 | <entry align='left'></entry> | |
| 692 | </row> | |
| 693 | <row> | |
| 694 | <entry align='left'>£</entry> | |
| 695 | <entry align='left'>£</entry> | |
| 696 | <entry align='left'>163</entry> | |
| 697 | <entry align='left'>sterling</entry> | |
| 698 | <entry align='left'>u00A3</entry> | |
| 699 | <entry align='left'></entry> | |
| 700 | </row> | |
| 701 | <row> | |
| 702 | <entry align='left'>¤</entry> | |
| 703 | <entry align='left'>¤</entry> | |
| 704 | <entry align='left'>164</entry> | |
| 705 | <entry align='left'>currency</entry> | |
| 706 | <entry align='left'>u00A4</entry> | |
| 707 | <entry align='left'></entry> | |
| 708 | </row> | |
| 709 | <row> | |
| 710 | <entry align='left'>¥</entry> | |
| 711 | <entry align='left'>¥</entry> | |
| 712 | <entry align='left'>165</entry> | |
| 713 | <entry align='left'>yen </entry> | |
| 714 | <entry align='left'>u00A5</entry> | |
| 715 | <entry align='left'></entry> | |
| 716 | </row> | |
| 717 | <row> | |
| 718 | <entry align='left'>¦</entry> | |
| 719 | <entry align='left'>¦</entry> | |
| 720 | <entry align='left'>166</entry> | |
| 721 | <entry align='left'>brokenbar</entry> | |
| 722 | <entry align='left'>u00A6</entry> | |
| 723 | <entry align='left'></entry> | |
| 724 | </row> | |
| 725 | <row> | |
| 726 | <entry align='left'>§</entry> | |
| 727 | <entry align='left'>§</entry> | |
| 728 | <entry align='left'>167</entry> | |
| 729 | <entry align='left'>section </entry> | |
| 730 | <entry align='left'>u00A7</entry> | |
| 731 | <entry align='left'></entry> | |
| 732 | </row> | |
| 733 | <row> | |
| 734 | <entry align='left'>¨</entry> | |
| 735 | <entry align='left'>¨</entry> | |
| 736 | <entry align='left'>168</entry> | |
| 737 | <entry align='left'>dieresis</entry> | |
| 738 | <entry align='left'>u00A8</entry> | |
| 739 | <entry align='left'></entry> | |
| 740 | </row> | |
| 741 | <row> | |
| 742 | <entry align='left'>©</entry> | |
| 743 | <entry align='left'>©</entry> | |
| 744 | <entry align='left'>169</entry> | |
| 745 | <entry align='left'>copyright</entry> | |
| 746 | <entry align='left'>u00A9</entry> | |
| 747 | <entry align='left'></entry> | |
| 748 | </row> | |
| 749 | <row> | |
| 750 | <entry align='left'>ª</entry> | |
| 751 | <entry align='left'>ª</entry> | |
| 752 | <entry align='left'>170</entry> | |
| 753 | <entry align='left'>ordfeminine</entry> | |
| 754 | <entry align='left'>u00AA</entry> | |
| 755 | <entry align='left'></entry> | |
| 756 | </row> | |
| 757 | <row> | |
| 758 | <entry align='left'>«</entry> | |
| 759 | <entry align='left'>«</entry> | |
| 760 | <entry align='left'>171</entry> | |
| 761 | <entry align='left'>guillemotleft</entry> | |
| 762 | <entry align='left'>u00AB</entry> | |
| 763 | <entry align='left'></entry> | |
| 764 | </row> | |
| 765 | <row> | |
| 766 | <entry align='left'>¬</entry> | |
| 767 | <entry align='left'>¬</entry> | |
| 768 | <entry align='left'>172</entry> | |
| 769 | <entry align='left'>logicalnot</entry> | |
| 770 | <entry align='left'>u00AC</entry> | |
| 771 | <entry align='left'></entry> | |
| 772 | </row> | |
| 773 | <row> | |
| 774 | <entry align='left'>®</entry> | |
| 775 | <entry align='left'>®</entry> | |
| 776 | <entry align='left'>174</entry> | |
| 777 | <entry align='left'>registered</entry> | |
| 778 | <entry align='left'>u00AE</entry> | |
| 779 | <entry align='left'></entry> | |
| 780 | </row> | |
| 781 | <row> | |
| 782 | <entry align='left'>¯</entry> | |
| 783 | <entry align='left'>¯</entry> | |
| 784 | <entry align='left'>175</entry> | |
| 785 | <entry align='left'>macron </entry> | |
| 786 | <entry align='left'>u00AF</entry> | |
| 787 | <entry align='left'></entry> | |
| 788 | </row> | |
| 789 | <row> | |
| 790 | <entry align='left'>°</entry> | |
| 791 | <entry align='left'>°</entry> | |
| 792 | <entry align='left'>176</entry> | |
| 793 | <entry align='left'>degree </entry> | |
| 794 | <entry align='left'>u00B0</entry> | |
| 795 | <entry align='left'></entry> | |
| 796 | </row> | |
| 797 | <row> | |
| 798 | <entry align='left'>±</entry> | |
| 799 | <entry align='left'>±</entry> | |
| 800 | <entry align='left'>177</entry> | |
| 801 | <entry align='left'>plusminus</entry> | |
| 802 | <entry align='left'>u00B1</entry> | |
| 803 | <entry align='left'></entry> | |
| 804 | </row> | |
| 805 | <row> | |
| 806 | <entry align='left'>²</entry> | |
| 807 | <entry align='left'>²</entry> | |
| 808 | <entry align='left'>178</entry> | |
| 809 | <entry align='left'>twosuperior</entry> | |
| 810 | <entry align='left'>u00B2</entry> | |
| 811 | <entry align='left'></entry> | |
| 812 | </row> | |
| 813 | <row> | |
| 814 | <entry align='left'>³</entry> | |
| 815 | <entry align='left'>³</entry> | |
| 816 | <entry align='left'>179</entry> | |
| 817 | <entry align='left'>threesuperior</entry> | |
| 818 | <entry align='left'>u00B3</entry> | |
| 819 | <entry align='left'></entry> | |
| 820 | </row> | |
| 821 | <row> | |
| 822 | <entry align='left'>´</entry> | |
| 823 | <entry align='left'>´</entry> | |
| 824 | <entry align='left'>180</entry> | |
| 825 | <entry align='left'>acute </entry> | |
| 826 | <entry align='left'>u00B4</entry> | |
| 827 | <entry align='left'>acute accent</entry> | |
| 828 | </row> | |
| 829 | <row> | |
| 830 | <entry align='left'>µ</entry> | |
| 831 | <entry align='left'>µ</entry> | |
| 832 | <entry align='left'>181</entry> | |
| 833 | <entry align='left'>mu </entry> | |
| 834 | <entry align='left'>u00B5</entry> | |
| 835 | <entry align='left'>micro sign</entry> | |
| 836 | </row> | |
| 837 | <row> | |
| 838 | <entry align='left'>¶</entry> | |
| 839 | <entry align='left'>¶</entry> | |
| 840 | <entry align='left'>182</entry> | |
| 841 | <entry align='left'>paragraph</entry> | |
| 842 | <entry align='left'>u00B6</entry> | |
| 843 | <entry align='left'></entry> | |
| 844 | </row> | |
| 845 | <row> | |
| 846 | <entry align='left'>·</entry> | |
| 847 | <entry align='left'>·</entry> | |
| 848 | <entry align='left'>183</entry> | |
| 849 | <entry align='left'>periodcentered</entry> | |
| 850 | <entry align='left'>u00B7</entry> | |
| 851 | <entry align='left'></entry> | |
| 852 | </row> | |
| 853 | <row> | |
| 854 | <entry align='left'>¸</entry> | |
| 855 | <entry align='left'>¸</entry> | |
| 856 | <entry align='left'>184</entry> | |
| 857 | <entry align='left'>cedilla </entry> | |
| 858 | <entry align='left'>u00B8</entry> | |
| 859 | <entry align='left'></entry> | |
| 860 | </row> | |
| 861 | <row> | |
| 862 | <entry align='left'>¹</entry> | |
| 863 | <entry align='left'>¹</entry> | |
| 864 | <entry align='left'>185</entry> | |
| 865 | <entry align='left'>onesuperior</entry> | |
| 866 | <entry align='left'>u00B9</entry> | |
| 867 | <entry align='left'></entry> | |
| 868 | </row> | |
| 869 | <row> | |
| 870 | <entry align='left'>º</entry> | |
| 871 | <entry align='left'>º</entry> | |
| 872 | <entry align='left'>186</entry> | |
| 873 | <entry align='left'>ordmasculine</entry> | |
| 874 | <entry align='left'>u00BA</entry> | |
| 875 | <entry align='left'></entry> | |
| 876 | </row> | |
| 877 | <row> | |
| 878 | <entry align='left'>»</entry> | |
| 879 | <entry align='left'>»</entry> | |
| 880 | <entry align='left'>187</entry> | |
| 881 | <entry align='left'>guillemotright</entry> | |
| 882 | <entry align='left'>u00BB</entry> | |
| 883 | <entry align='left'></entry> | |
| 884 | </row> | |
| 885 | <row> | |
| 886 | <entry align='left'>¼</entry> | |
| 887 | <entry align='left'>¼</entry> | |
| 888 | <entry align='left'>188</entry> | |
| 889 | <entry align='left'>onequarter</entry> | |
| 890 | <entry align='left'>u00BC</entry> | |
| 891 | <entry align='left'></entry> | |
| 892 | </row> | |
| 893 | <row> | |
| 894 | <entry align='left'>½</entry> | |
| 895 | <entry align='left'>½</entry> | |
| 896 | <entry align='left'>189</entry> | |
| 897 | <entry align='left'>onehalf </entry> | |
| 898 | <entry align='left'>u00BD</entry> | |
| 899 | <entry align='left'></entry> | |
| 900 | </row> | |
| 901 | <row> | |
| 902 | <entry align='left'>¾</entry> | |
| 903 | <entry align='left'>¾</entry> | |
| 904 | <entry align='left'>190</entry> | |
| 905 | <entry align='left'>threequarters</entry> | |
| 906 | <entry align='left'>u00BE</entry> | |
| 907 | <entry align='left'></entry> | |
| 908 | </row> | |
| 909 | <row> | |
| 910 | <entry align='left'>¿</entry> | |
| 911 | <entry align='left'>¿</entry> | |
| 912 | <entry align='left'>191</entry> | |
| 913 | <entry align='left'>questiondown</entry> | |
| 914 | <entry align='left'>u00BF</entry> | |
| 915 | <entry align='left'></entry> | |
| 916 | </row> | |
| 917 | <row> | |
| 918 | <entry align='left'>À</entry> | |
| 919 | <entry align='left'>À</entry> | |
| 920 | <entry align='left'>192</entry> | |
| 921 | <entry align='left'>Agrave </entry> | |
| 922 | <entry align='left'>u0041_0300</entry> | |
| 923 | <entry align='left'></entry> | |
| 924 | </row> | |
| 925 | <row> | |
| 926 | <entry align='left'>Á</entry> | |
| 927 | <entry align='left'>Á</entry> | |
| 928 | <entry align='left'>193</entry> | |
| 929 | <entry align='left'>Aacute </entry> | |
| 930 | <entry align='left'>u0041_0301</entry> | |
| 931 | <entry align='left'></entry> | |
| 932 | </row> | |
| 933 | <row> | |
| 934 | <entry align='left'>Â</entry> | |
| 935 | <entry align='left'>Â</entry> | |
| 936 | <entry align='left'>194</entry> | |
| 937 | <entry align='left'>Acircumflex</entry> | |
| 938 | <entry align='left'>u0041_0302</entry> | |
| 939 | <entry align='left'></entry> | |
| 940 | </row> | |
| 941 | <row> | |
| 942 | <entry align='left'>Ã</entry> | |
| 943 | <entry align='left'>Ã</entry> | |
| 944 | <entry align='left'>195</entry> | |
| 945 | <entry align='left'>Atilde </entry> | |
| 946 | <entry align='left'>u0041_0303</entry> | |
| 947 | <entry align='left'></entry> | |
| 948 | </row> | |
| 949 | <row> | |
| 950 | <entry align='left'>Ä</entry> | |
| 951 | <entry align='left'>Ä</entry> | |
| 952 | <entry align='left'>196</entry> | |
| 953 | <entry align='left'>Adieresis</entry> | |
| 954 | <entry align='left'>u0041_0308</entry> | |
| 955 | <entry align='left'></entry> | |
| 956 | </row> | |
| 957 | <row> | |
| 958 | <entry align='left'>Å</entry> | |
| 959 | <entry align='left'>Å</entry> | |
| 960 | <entry align='left'>197</entry> | |
| 961 | <entry align='left'>Aring </entry> | |
| 962 | <entry align='left'>u0041_030A</entry> | |
| 963 | <entry align='left'></entry> | |
| 964 | </row> | |
| 965 | <row> | |
| 966 | <entry align='left'>Æ</entry> | |
| 967 | <entry align='left'>Æ</entry> | |
| 968 | <entry align='left'>198</entry> | |
| 969 | <entry align='left'>AE </entry> | |
| 970 | <entry align='left'>u00C6</entry> | |
| 971 | <entry align='left'></entry> | |
| 972 | </row> | |
| 973 | <row> | |
| 974 | <entry align='left'>Ç</entry> | |
| 975 | <entry align='left'>Ç</entry> | |
| 976 | <entry align='left'>199</entry> | |
| 977 | <entry align='left'>Ccedilla</entry> | |
| 978 | <entry align='left'>u0043_0327</entry> | |
| 979 | <entry align='left'></entry> | |
| 980 | </row> | |
| 981 | <row> | |
| 982 | <entry align='left'>È</entry> | |
| 983 | <entry align='left'>È</entry> | |
| 984 | <entry align='left'>200</entry> | |
| 985 | <entry align='left'>Egrave </entry> | |
| 986 | <entry align='left'>u0045_0300</entry> | |
| 987 | <entry align='left'></entry> | |
| 988 | </row> | |
| 989 | <row> | |
| 990 | <entry align='left'>É</entry> | |
| 991 | <entry align='left'>É</entry> | |
| 992 | <entry align='left'>201</entry> | |
| 993 | <entry align='left'>Eacute </entry> | |
| 994 | <entry align='left'>u0045_0301</entry> | |
| 995 | <entry align='left'></entry> | |
| 996 | </row> | |
| 997 | <row> | |
| 998 | <entry align='left'>Ê</entry> | |
| 999 | <entry align='left'>Ê</entry> | |
| 1000 | <entry align='left'>202</entry> | |
| 1001 | <entry align='left'>Ecircumflex</entry> | |
| 1002 | <entry align='left'>u0045_0302</entry> | |
| 1003 | <entry align='left'></entry> | |
| 1004 | </row> | |
| 1005 | <row> | |
| 1006 | <entry align='left'>Ë</entry> | |
| 1007 | <entry align='left'>Ë</entry> | |
| 1008 | <entry align='left'>203</entry> | |
| 1009 | <entry align='left'>Edieresis</entry> | |
| 1010 | <entry align='left'>u0045_0308</entry> | |
| 1011 | <entry align='left'></entry> | |
| 1012 | </row> | |
| 1013 | <row> | |
| 1014 | <entry align='left'>Ì</entry> | |
| 1015 | <entry align='left'>Ì</entry> | |
| 1016 | <entry align='left'>204</entry> | |
| 1017 | <entry align='left'>Igrave </entry> | |
| 1018 | <entry align='left'>u0049_0300</entry> | |
| 1019 | <entry align='left'></entry> | |
| 1020 | </row> | |
| 1021 | <row> | |
| 1022 | <entry align='left'>Í</entry> | |
| 1023 | <entry align='left'>Í</entry> | |
| 1024 | <entry align='left'>205</entry> | |
| 1025 | <entry align='left'>Iacute </entry> | |
| 1026 | <entry align='left'>u0049_0301</entry> | |
| 1027 | <entry align='left'></entry> | |
| 1028 | </row> | |
| 1029 | <row> | |
| 1030 | <entry align='left'>Î</entry> | |
| 1031 | <entry align='left'>Î</entry> | |
| 1032 | <entry align='left'>206</entry> | |
| 1033 | <entry align='left'>Icircumflex</entry> | |
| 1034 | <entry align='left'>u0049_0302</entry> | |
| 1035 | <entry align='left'></entry> | |
| 1036 | </row> | |
| 1037 | <row> | |
| 1038 | <entry align='left'>Ï</entry> | |
| 1039 | <entry align='left'>Ï</entry> | |
| 1040 | <entry align='left'>207</entry> | |
| 1041 | <entry align='left'>Idieresis</entry> | |
| 1042 | <entry align='left'>u0049_0308</entry> | |
| 1043 | <entry align='left'></entry> | |
| 1044 | </row> | |
| 1045 | <row> | |
| 1046 | <entry align='left'>Ð</entry> | |
| 1047 | <entry align='left'>Ð</entry> | |
| 1048 | <entry align='left'>208</entry> | |
| 1049 | <entry align='left'>Eth </entry> | |
| 1050 | <entry align='left'>u00D0</entry> | |
| 1051 | <entry align='left'></entry> | |
| 1052 | </row> | |
| 1053 | <row> | |
| 1054 | <entry align='left'>Ñ</entry> | |
| 1055 | <entry align='left'>Ñ</entry> | |
| 1056 | <entry align='left'>209</entry> | |
| 1057 | <entry align='left'>Ntilde </entry> | |
| 1058 | <entry align='left'>u004E_0303</entry> | |
| 1059 | <entry align='left'></entry> | |
| 1060 | </row> | |
| 1061 | <row> | |
| 1062 | <entry align='left'>Ò</entry> | |
| 1063 | <entry align='left'>Ò</entry> | |
| 1064 | <entry align='left'>210</entry> | |
| 1065 | <entry align='left'>Ograve </entry> | |
| 1066 | <entry align='left'>u004F_0300</entry> | |
| 1067 | <entry align='left'></entry> | |
| 1068 | </row> | |
| 1069 | <row> | |
| 1070 | <entry align='left'>Ó</entry> | |
| 1071 | <entry align='left'>Ó</entry> | |
| 1072 | <entry align='left'>211</entry> | |
| 1073 | <entry align='left'>Oacute </entry> | |
| 1074 | <entry align='left'>u004F_0301</entry> | |
| 1075 | <entry align='left'></entry> | |
| 1076 | </row> | |
| 1077 | <row> | |
| 1078 | <entry align='left'>Ô</entry> | |
| 1079 | <entry align='left'>Ô</entry> | |
| 1080 | <entry align='left'>212</entry> | |
| 1081 | <entry align='left'>Ocircumflex</entry> | |
| 1082 | <entry align='left'>u004F_0302</entry> | |
| 1083 | <entry align='left'></entry> | |
| 1084 | </row> | |
| 1085 | <row> | |
| 1086 | <entry align='left'>Õ</entry> | |
| 1087 | <entry align='left'>Õ</entry> | |
| 1088 | <entry align='left'>213</entry> | |
| 1089 | <entry align='left'>Otilde </entry> | |
| 1090 | <entry align='left'>u004F_0303</entry> | |
| 1091 | <entry align='left'></entry> | |
| 1092 | </row> | |
| 1093 | <row> | |
| 1094 | <entry align='left'>Ö</entry> | |
| 1095 | <entry align='left'>Ö</entry> | |
| 1096 | <entry align='left'>214</entry> | |
| 1097 | <entry align='left'>Odieresis</entry> | |
| 1098 | <entry align='left'>u004F_0308</entry> | |
| 1099 | <entry align='left'></entry> | |
| 1100 | </row> | |
| 1101 | <row> | |
| 1102 | <entry align='left'>×</entry> | |
| 1103 | <entry align='left'>×</entry> | |
| 1104 | <entry align='left'>215</entry> | |
| 1105 | <entry align='left'>multiply</entry> | |
| 1106 | <entry align='left'>u00D7</entry> | |
| 1107 | <entry align='left'></entry> | |
| 1108 | </row> | |
| 1109 | <row> | |
| 1110 | <entry align='left'>Ø</entry> | |
| 1111 | <entry align='left'>Ø</entry> | |
| 1112 | <entry align='left'>216</entry> | |
| 1113 | <entry align='left'>Oslash </entry> | |
| 1114 | <entry align='left'>u00D8</entry> | |
| 1115 | <entry align='left'></entry> | |
| 1116 | </row> | |
| 1117 | <row> | |
| 1118 | <entry align='left'>Ù</entry> | |
| 1119 | <entry align='left'>Ù</entry> | |
| 1120 | <entry align='left'>217</entry> | |
| 1121 | <entry align='left'>Ugrave </entry> | |
| 1122 | <entry align='left'>u0055_0300</entry> | |
| 1123 | <entry align='left'></entry> | |
| 1124 | </row> | |
| 1125 | <row> | |
| 1126 | <entry align='left'>Ú</entry> | |
| 1127 | <entry align='left'>Ú</entry> | |
| 1128 | <entry align='left'>218</entry> | |
| 1129 | <entry align='left'>Uacute </entry> | |
| 1130 | <entry align='left'>u0055_0301</entry> | |
| 1131 | <entry align='left'></entry> | |
| 1132 | </row> | |
| 1133 | <row> | |
| 1134 | <entry align='left'>Û</entry> | |
| 1135 | <entry align='left'>Û</entry> | |
| 1136 | <entry align='left'>219</entry> | |
| 1137 | <entry align='left'>Ucircumflex</entry> | |
| 1138 | <entry align='left'>u0055_0302</entry> | |
| 1139 | <entry align='left'></entry> | |
| 1140 | </row> | |
| 1141 | <row> | |
| 1142 | <entry align='left'>Ü</entry> | |
| 1143 | <entry align='left'>Ü</entry> | |
| 1144 | <entry align='left'>220</entry> | |
| 1145 | <entry align='left'>Udieresis</entry> | |
| 1146 | <entry align='left'>u0055_0308</entry> | |
| 1147 | <entry align='left'></entry> | |
| 1148 | </row> | |
| 1149 | <row> | |
| 1150 | <entry align='left'>Ý</entry> | |
| 1151 | <entry align='left'>Ý</entry> | |
| 1152 | <entry align='left'>221</entry> | |
| 1153 | <entry align='left'>Yacute </entry> | |
| 1154 | <entry align='left'>u0059_0301</entry> | |
| 1155 | <entry align='left'></entry> | |
| 1156 | </row> | |
| 1157 | <row> | |
| 1158 | <entry align='left'>Þ</entry> | |
| 1159 | <entry align='left'>Þ</entry> | |
| 1160 | <entry align='left'>222</entry> | |
| 1161 | <entry align='left'>Thorn </entry> | |
| 1162 | <entry align='left'>u00DE</entry> | |
| 1163 | <entry align='left'></entry> | |
| 1164 | </row> | |
| 1165 | <row> | |
| 1166 | <entry align='left'>ß</entry> | |
| 1167 | <entry align='left'>ß</entry> | |
| 1168 | <entry align='left'>223</entry> | |
| 1169 | <entry align='left'>germandbls</entry> | |
| 1170 | <entry align='left'>u00DF</entry> | |
| 1171 | <entry align='left'></entry> | |
| 1172 | </row> | |
| 1173 | <row> | |
| 1174 | <entry align='left'>à</entry> | |
| 1175 | <entry align='left'>à</entry> | |
| 1176 | <entry align='left'>224</entry> | |
| 1177 | <entry align='left'>agrave </entry> | |
| 1178 | <entry align='left'>u0061_0300</entry> | |
| 1179 | <entry align='left'></entry> | |
| 1180 | </row> | |
| 1181 | <row> | |
| 1182 | <entry align='left'>á</entry> | |
| 1183 | <entry align='left'>á</entry> | |
| 1184 | <entry align='left'>225</entry> | |
| 1185 | <entry align='left'>aacute </entry> | |
| 1186 | <entry align='left'>u0061_0301</entry> | |
| 1187 | <entry align='left'></entry> | |
| 1188 | </row> | |
| 1189 | <row> | |
| 1190 | <entry align='left'>â</entry> | |
| 1191 | <entry align='left'>â</entry> | |
| 1192 | <entry align='left'>226</entry> | |
| 1193 | <entry align='left'>acircumflex</entry> | |
| 1194 | <entry align='left'>u0061_0302</entry> | |
| 1195 | <entry align='left'></entry> | |
| 1196 | </row> | |
| 1197 | <row> | |
| 1198 | <entry align='left'>ã</entry> | |
| 1199 | <entry align='left'>ã</entry> | |
| 1200 | <entry align='left'>227</entry> | |
| 1201 | <entry align='left'>atilde </entry> | |
| 1202 | <entry align='left'>u0061_0303</entry> | |
| 1203 | <entry align='left'></entry> | |
| 1204 | </row> | |
| 1205 | <row> | |
| 1206 | <entry align='left'>ä</entry> | |
| 1207 | <entry align='left'>ä</entry> | |
| 1208 | <entry align='left'>228</entry> | |
| 1209 | <entry align='left'>adieresis</entry> | |
| 1210 | <entry align='left'>u0061_0308</entry> | |
| 1211 | <entry align='left'></entry> | |
| 1212 | </row> | |
| 1213 | <row> | |
| 1214 | <entry align='left'>å</entry> | |
| 1215 | <entry align='left'>å</entry> | |
| 1216 | <entry align='left'>229</entry> | |
| 1217 | <entry align='left'>aring </entry> | |
| 1218 | <entry align='left'>u0061_030A</entry> | |
| 1219 | <entry align='left'></entry> | |
| 1220 | </row> | |
| 1221 | <row> | |
| 1222 | <entry align='left'>æ</entry> | |
| 1223 | <entry align='left'>æ</entry> | |
| 1224 | <entry align='left'>230</entry> | |
| 1225 | <entry align='left'>ae </entry> | |
| 1226 | <entry align='left'>u00E6</entry> | |
| 1227 | <entry align='left'></entry> | |
| 1228 | </row> | |
| 1229 | <row> | |
| 1230 | <entry align='left'>ç</entry> | |
| 1231 | <entry align='left'>ç</entry> | |
| 1232 | <entry align='left'>231</entry> | |
| 1233 | <entry align='left'>ccedilla</entry> | |
| 1234 | <entry align='left'>u0063_0327</entry> | |
| 1235 | <entry align='left'></entry> | |
| 1236 | </row> | |
| 1237 | <row> | |
| 1238 | <entry align='left'>è</entry> | |
| 1239 | <entry align='left'>è</entry> | |
| 1240 | <entry align='left'>232</entry> | |
| 1241 | <entry align='left'>egrave </entry> | |
| 1242 | <entry align='left'>u0065_0300</entry> | |
| 1243 | <entry align='left'></entry> | |
| 1244 | </row> | |
| 1245 | <row> | |
| 1246 | <entry align='left'>é</entry> | |
| 1247 | <entry align='left'>é</entry> | |
| 1248 | <entry align='left'>233</entry> | |
| 1249 | <entry align='left'>eacute </entry> | |
| 1250 | <entry align='left'>u0065_0301</entry> | |
| 1251 | <entry align='left'></entry> | |
| 1252 | </row> | |
| 1253 | <row> | |
| 1254 | <entry align='left'>ê</entry> | |
| 1255 | <entry align='left'>ê</entry> | |
| 1256 | <entry align='left'>234</entry> | |
| 1257 | <entry align='left'>ecircumflex</entry> | |
| 1258 | <entry align='left'>u0065_0302</entry> | |
| 1259 | <entry align='left'></entry> | |
| 1260 | </row> | |
| 1261 | <row> | |
| 1262 | <entry align='left'>ë</entry> | |
| 1263 | <entry align='left'>ë</entry> | |
| 1264 | <entry align='left'>235</entry> | |
| 1265 | <entry align='left'>edieresis</entry> | |
| 1266 | <entry align='left'>u0065_0308</entry> | |
| 1267 | <entry align='left'></entry> | |
| 1268 | </row> | |
| 1269 | <row> | |
| 1270 | <entry align='left'>ì</entry> | |
| 1271 | <entry align='left'>ì</entry> | |
| 1272 | <entry align='left'>236</entry> | |
| 1273 | <entry align='left'>igrave </entry> | |
| 1274 | <entry align='left'>u0069_0300</entry> | |
| 1275 | <entry align='left'></entry> | |
| 1276 | </row> | |
| 1277 | <row> | |
| 1278 | <entry align='left'>í</entry> | |
| 1279 | <entry align='left'>í</entry> | |
| 1280 | <entry align='left'>237</entry> | |
| 1281 | <entry align='left'>iacute </entry> | |
| 1282 | <entry align='left'>u0069_0301</entry> | |
| 1283 | <entry align='left'></entry> | |
| 1284 | </row> | |
| 1285 | <row> | |
| 1286 | <entry align='left'>î</entry> | |
| 1287 | <entry align='left'>î</entry> | |
| 1288 | <entry align='left'>238</entry> | |
| 1289 | <entry align='left'>icircumflex</entry> | |
| 1290 | <entry align='left'>u0069_0302</entry> | |
| 1291 | <entry align='left'></entry> | |
| 1292 | </row> | |
| 1293 | <row> | |
| 1294 | <entry align='left'>ï</entry> | |
| 1295 | <entry align='left'>ï</entry> | |
| 1296 | <entry align='left'>239</entry> | |
| 1297 | <entry align='left'>idieresis</entry> | |
| 1298 | <entry align='left'>u0069_0308</entry> | |
| 1299 | <entry align='left'></entry> | |
| 1300 | </row> | |
| 1301 | <row> | |
| 1302 | <entry align='left'>ð</entry> | |
| 1303 | <entry align='left'>ð</entry> | |
| 1304 | <entry align='left'>240</entry> | |
| 1305 | <entry align='left'>eth </entry> | |
| 1306 | <entry align='left'>u00F0</entry> | |
| 1307 | <entry align='left'></entry> | |
| 1308 | </row> | |
| 1309 | <row> | |
| 1310 | <entry align='left'>ñ</entry> | |
| 1311 | <entry align='left'>ñ</entry> | |
| 1312 | <entry align='left'>241</entry> | |
| 1313 | <entry align='left'>ntilde </entry> | |
| 1314 | <entry align='left'>u006E_0303</entry> | |
| 1315 | <entry align='left'></entry> | |
| 1316 | </row> | |
| 1317 | <row> | |
| 1318 | <entry align='left'>ò</entry> | |
| 1319 | <entry align='left'>ò</entry> | |
| 1320 | <entry align='left'>242</entry> | |
| 1321 | <entry align='left'>ograve </entry> | |
| 1322 | <entry align='left'>u006F_0300</entry> | |
| 1323 | <entry align='left'></entry> | |
| 1324 | </row> | |
| 1325 | <row> | |
| 1326 | <entry align='left'>ó</entry> | |
| 1327 | <entry align='left'>ó</entry> | |
| 1328 | <entry align='left'>243</entry> | |
| 1329 | <entry align='left'>oacute </entry> | |
| 1330 | <entry align='left'>u006F_0301</entry> | |
| 1331 | <entry align='left'></entry> | |
| 1332 | </row> | |
| 1333 | <row> | |
| 1334 | <entry align='left'>ô</entry> | |
| 1335 | <entry align='left'>ô</entry> | |
| 1336 | <entry align='left'>244</entry> | |
| 1337 | <entry align='left'>ocircumflex</entry> | |
| 1338 | <entry align='left'>u006F_0302</entry> | |
| 1339 | <entry align='left'></entry> | |
| 1340 | </row> | |
| 1341 | <row> | |
| 1342 | <entry align='left'>õ</entry> | |
| 1343 | <entry align='left'>õ</entry> | |
| 1344 | <entry align='left'>245</entry> | |
| 1345 | <entry align='left'>otilde </entry> | |
| 1346 | <entry align='left'>u006F_0303</entry> | |
| 1347 | <entry align='left'></entry> | |
| 1348 | </row> | |
| 1349 | <row> | |
| 1350 | <entry align='left'>ö</entry> | |
| 1351 | <entry align='left'>ö</entry> | |
| 1352 | <entry align='left'>246</entry> | |
| 1353 | <entry align='left'>odieresis</entry> | |
| 1354 | <entry align='left'>u006F_0308</entry> | |
| 1355 | <entry align='left'></entry> | |
| 1356 | </row> | |
| 1357 | <row> | |
| 1358 | <entry align='left'>÷</entry> | |
| 1359 | <entry align='left'>÷</entry> | |
| 1360 | <entry align='left'>247</entry> | |
| 1361 | <entry align='left'>divide </entry> | |
| 1362 | <entry align='left'>u00F7</entry> | |
| 1363 | <entry align='left'></entry> | |
| 1364 | </row> | |
| 1365 | <row> | |
| 1366 | <entry align='left'>ø</entry> | |
| 1367 | <entry align='left'>ø</entry> | |
| 1368 | <entry align='left'>248</entry> | |
| 1369 | <entry align='left'>oslash </entry> | |
| 1370 | <entry align='left'>u00F8</entry> | |
| 1371 | <entry align='left'></entry> | |
| 1372 | </row> | |
| 1373 | <row> | |
| 1374 | <entry align='left'>ù</entry> | |
| 1375 | <entry align='left'>ù</entry> | |
| 1376 | <entry align='left'>249</entry> | |
| 1377 | <entry align='left'>ugrave </entry> | |
| 1378 | <entry align='left'>u0075_0300</entry> | |
| 1379 | <entry align='left'></entry> | |
| 1380 | </row> | |
| 1381 | <row> | |
| 1382 | <entry align='left'>ú</entry> | |
| 1383 | <entry align='left'>ú</entry> | |
| 1384 | <entry align='left'>250</entry> | |
| 1385 | <entry align='left'>uacute </entry> | |
| 1386 | <entry align='left'>u0075_0301</entry> | |
| 1387 | <entry align='left'></entry> | |
| 1388 | </row> | |
| 1389 | <row> | |
| 1390 | <entry align='left'>û</entry> | |
| 1391 | <entry align='left'>û</entry> | |
| 1392 | <entry align='left'>251</entry> | |
| 1393 | <entry align='left'>ucircumflex</entry> | |
| 1394 | <entry align='left'>u0075_0302</entry> | |
| 1395 | <entry align='left'></entry> | |
| 1396 | </row> | |
| 1397 | <row> | |
| 1398 | <entry align='left'>ü</entry> | |
| 1399 | <entry align='left'>ü</entry> | |
| 1400 | <entry align='left'>252</entry> | |
| 1401 | <entry align='left'>udieresis</entry> | |
| 1402 | <entry align='left'>u0075_0308</entry> | |
| 1403 | <entry align='left'></entry> | |
| 1404 | </row> | |
| 1405 | <row> | |
| 1406 | <entry align='left'>ý</entry> | |
| 1407 | <entry align='left'>ý</entry> | |
| 1408 | <entry align='left'>253</entry> | |
| 1409 | <entry align='left'>yacute </entry> | |
| 1410 | <entry align='left'>u0079_0301</entry> | |
| 1411 | <entry align='left'></entry> | |
| 1412 | </row> | |
| 1413 | <row> | |
| 1414 | <entry align='left'>þ</entry> | |
| 1415 | <entry align='left'>þ</entry> | |
| 1416 | <entry align='left'>254</entry> | |
| 1417 | <entry align='left'>thorn </entry> | |
| 1418 | <entry align='left'>u00FE</entry> | |
| 1419 | <entry align='left'></entry> | |
| 1420 | </row> | |
| 1421 | <row> | |
| 1422 | <entry align='left'>ÿ</entry> | |
| 1423 | <entry align='left'>ÿ</entry> | |
| 1424 | <entry align='left'>255</entry> | |
| 1425 | <entry align='left'>ydieresis</entry> | |
| 1426 | <entry align='left'>u0079_0308</entry> | |
| 1427 | <entry align='left'></entry> | |
| 1428 | </row> | |
| 1429 | </tbody> | |
| 1430 | </tgroup> | |
| 1431 | </informaltable> | |
| 1432 | ||
| 1433 | ||
| 1434 | ||
| 1435 | ||
| 1436 | ||
| 1437 | </listitem> | |
| 1438 | </varlistentry> | |
| 1439 | </variablelist> | |
| 1440 | </refsect2> | |
| 1441 | ||
| 1442 | <refsect2 id='named_glyphs'><title>Named Glyphs</title> | |
| 1443 | ||
| 1444 | ||
| 1445 | <para>Glyph names can be embedded into the document text by using escape | |
| 1446 | sequences. | |
| 1447 | ||
| 1448 | <citerefentry><refentrytitle>groff</refentrytitle><manvolnum>7</manvolnum></citerefentry> | |
| 1449 | describes how these escape sequences look. | |
| 1450 | ||
| 1451 | Glyph names can consist of quite arbitrary characters from the | |
| 1452 | ASCII or ­latin1 code set, not only alphanumeric characters. | |
| 1453 | ||
| 1454 | Here some examples:</para> | |
| 1455 | ||
| 1456 | <variablelist remap='TP'> | |
| 1457 | <varlistentry> | |
| 1458 | <term><emphasis remap='CW'>\(</emphasis><emphasis remap='I'>ch</emphasis></term> | |
| 1459 | <listitem> | |
| 1460 | <para>A glyph having the 2-character name | |
| 1461 | <emphasis remap='I'>ch</emphasis>.</para> | |
| 1462 | ||
| 1463 | </listitem> | |
| 1464 | </varlistentry> | |
| 1465 | <varlistentry> | |
| 1466 | <term><emphasis remap='CW'>\[</emphasis><emphasis remap='I'>char_name</emphasis><emphasis remap='CW'>]</emphasis></term> | |
| 1467 | <listitem> | |
| 1468 | <para>A glyph having the name | |
| 1469 | <emphasis remap='I'>char_name</emphasis> | |
| 1470 | (having length 1, 2, 3, . . .). | |
| 1471 | ||
| 1472 | Note that `<emphasis remap='I'>c</emphasis>' is not the same as | |
| 1473 | `<emphasis remap='CW'>\[</emphasis><emphasis remap='I'>c</emphasis><emphasis remap='CW'>]</emphasis>' (<emphasis remap='I'>c</emphasis> a single character): | |
| 1474 | The latter is internally mapped to glyph name `\<emphasis remap='I'>c</emphasis>'. | |
| 1475 | ||
| 1476 | By default, groff defines a single glyph name starting with a backslash, | |
| 1477 | namely ­`\-', which can be either accessed as `<emphasis remap='CW'>\-</emphasis>' or | |
| 1478 | `<emphasis remap='CW'>\[-]</emphasis>'.</para> | |
| 1479 | ||
| 1480 | </listitem> | |
| 1481 | </varlistentry> | |
| 1482 | <varlistentry> | |
| 1483 | <term><emphasis remap='CW'>\[</emphasis><emphasis remap='I'>base_glyph composite_1 composite_2 . . .</emphasis><emphasis remap='CW'>]</emphasis></term> | |
| 1484 | <listitem> | |
| 1485 | <para>A composite glyph; see below for a more detailed description.</para> | |
| 1486 | ||
| 1487 | ||
| 1488 | ||
| 1489 | <para>In groff, each ­8-bit input character can also referred to by the construct | |
| 1490 | `<emphasis remap='CW'>\[char</emphasis><emphasis remap='I'>n</emphasis><emphasis remap='CW'>]</emphasis>' where | |
| 1491 | <emphasis remap='I'>n</emphasis> | |
| 1492 | is the decimal code of the character, a number between 0 and 255 | |
| 1493 | without leading zeros (those entities are | |
| 1494 | <emphasis remap='I'>not</emphasis> | |
| 1495 | glyph names). | |
| 1496 | ||
| 1497 | They are normally mapped onto glyphs using the <emphasis remap='CW'>.trin</emphasis> request. | |
| 1498 | ||
| 1499 | Another special convention is the handling of glyphs with names directly | |
| 1500 | derived from a Unicode code point; this is discussed below. | |
| 1501 | ||
| 1502 | Moreover, new glyph names can be created by the <emphasis remap='CW'>.char</emphasis> request; see | |
| 1503 | <citerefentry><refentrytitle>groff</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para> | |
| 1504 | ||
| 1505 | ||
| 1506 | <para>In the following, a plus sign in the `Notes' column indicates that this | |
| 1507 | particular glyph name appears in the PS version of the original troff | |
| 1508 | documentation, CSTR 54.</para> | |
| 1509 | ||
| 1510 | ||
| 1511 | <para>Entries marked with `***' denote glyphs for mathematical purposes (mainly | |
| 1512 | used for DVI output). Normally, such glyphs have metrics which make them | |
| 1513 | unusable in normal text.</para> | |
| 1514 | ||
| 1515 | <informaltable pgwide='0' frame='none'> | |
| 1516 | <tgroup cols='5' align='center'> | |
| 1517 | <colspec colname='c1'/> | |
| 1518 | <colspec colname='c2'/> | |
| 1519 | <colspec colname='c3'/> | |
| 1520 | <colspec colname='c4'/> | |
| 1521 | <colspec colname='c5'/> | |
| 1522 | <tbody> | |
| 1523 | <row rowsep='1'> | |
| 1524 | <entry align='left'>Output </entry> | |
| 1525 | <entry align='left'>Input</entry> | |
| 1526 | <entry align='left'>PostScript</entry> | |
| 1527 | <entry align='left'>Unicode </entry> | |
| 1528 | <entry align='left'>Notes</entry> | |
| 1529 | </row> | |
| 1530 | <row> | |
| 1531 | <entry align='left'>Ð</entry> | |
| 1532 | <entry align='left'>\[-D]</entry> | |
| 1533 | <entry align='left'>Eth </entry> | |
| 1534 | <entry align='left'>u00D0 </entry> | |
| 1535 | <entry align='left'>uppercase eth</entry> | |
| 1536 | </row> | |
| 1537 | <row> | |
| 1538 | <entry align='left'>ð</entry> | |
| 1539 | <entry align='left'>\[Sd]</entry> | |
| 1540 | <entry align='left'>eth </entry> | |
| 1541 | <entry align='left'>u00F0 </entry> | |
| 1542 | <entry align='left'>lowercase eth</entry> | |
| 1543 | </row> | |
| 1544 | <row> | |
| 1545 | <entry align='left'>Þ</entry> | |
| 1546 | <entry align='left'>\[TP]</entry> | |
| 1547 | <entry align='left'>Thorn </entry> | |
| 1548 | <entry align='left'>u00DE </entry> | |
| 1549 | <entry align='left'>uppercase thorn</entry> | |
| 1550 | </row> | |
| 1551 | <row> | |
| 1552 | <entry align='left'>þ</entry> | |
| 1553 | <entry align='left'>\[Tp]</entry> | |
| 1554 | <entry align='left'>thorn </entry> | |
| 1555 | <entry align='left'>u00FE </entry> | |
| 1556 | <entry align='left'>lowercase thorn</entry> | |
| 1557 | </row> | |
| 1558 | <row> | |
| 1559 | <entry align='left'>ß</entry> | |
| 1560 | <entry align='left'>\[ss]</entry> | |
| 1561 | <entry align='left'>germandbls</entry> | |
| 1562 | <entry align='left'>u00DF </entry> | |
| 1563 | <entry align='left'>German sharp s</entry> | |
| 1564 | </row> | |
| 1565 | </tbody> | |
| 1566 | </tgroup> | |
| 1567 | </informaltable> | |
| 1568 | ||
| 1569 | ||
| 1570 | ||
| 1571 | ||
| 1572 | <para><emphasis remap='I'>Ligatures and Other Latin Glyphs</emphasis></para> | |
| 1573 | ||
| 1574 | <informaltable pgwide='0' frame='none'> | |
| 1575 | <tgroup cols='5' align='center'> | |
| 1576 | <colspec colname='c1'/> | |
| 1577 | <colspec colname='c2'/> | |
| 1578 | <colspec colname='c3'/> | |
| 1579 | <colspec colname='c4'/> | |
| 1580 | <colspec colname='c5'/> | |
| 1581 | <tbody> | |
| 1582 | <row rowsep='1'> | |
| 1583 | <entry align='left'>Output </entry> | |
| 1584 | <entry align='left'>Input</entry> | |
| 1585 | <entry align='left'>PostScript</entry> | |
| 1586 | <entry align='left'>Unicode </entry> | |
| 1587 | <entry align='left'>Notes</entry> | |
| 1588 | </row> | |
| 1589 | <row> | |
| 1590 | <entry align='left'>ff</entry> | |
| 1591 | <entry align='left'>\[ff]</entry> | |
| 1592 | <entry align='left'>ff </entry> | |
| 1593 | <entry align='left'>u0066_0066</entry> | |
| 1594 | <entry align='left'>ff ligature +</entry> | |
| 1595 | </row> | |
| 1596 | <row> | |
| 1597 | <entry align='left'>fi</entry> | |
| 1598 | <entry align='left'>\[fi]</entry> | |
| 1599 | <entry align='left'>fi </entry> | |
| 1600 | <entry align='left'>u0066_0069</entry> | |
| 1601 | <entry align='left'>fi ligature +</entry> | |
| 1602 | </row> | |
| 1603 | <row> | |
| 1604 | <entry align='left'>fl</entry> | |
| 1605 | <entry align='left'>\[fl]</entry> | |
| 1606 | <entry align='left'>fl </entry> | |
| 1607 | <entry align='left'>u0066_006C</entry> | |
| 1608 | <entry align='left'>fl ligature +</entry> | |
| 1609 | </row> | |
| 1610 | <row> | |
| 1611 | <entry align='left'>ffi</entry> | |
| 1612 | <entry align='left'>\[Fi]</entry> | |
| 1613 | <entry align='left'>ffi </entry> | |
| 1614 | <entry align='left'>u0066_0066_0069</entry> | |
| 1615 | <entry align='left'>ffi ligature +</entry> | |
| 1616 | </row> | |
| 1617 | <row> | |
| 1618 | <entry align='left'>ffl</entry> | |
| 1619 | <entry align='left'>\[Fl]</entry> | |
| 1620 | <entry align='left'>ffl </entry> | |
| 1621 | <entry align='left'>u0066_0066_006C</entry> | |
| 1622 | <entry align='left'>ffl ligature +</entry> | |
| 1623 | </row> | |
| 1624 | <row> | |
| 1625 | <entry align='left'>Ł</entry> | |
| 1626 | <entry align='left'>\[/L]</entry> | |
| 1627 | <entry align='left'>Lslash </entry> | |
| 1628 | <entry align='left'>u0141 </entry> | |
| 1629 | <entry align='left'>(Polish)</entry> | |
| 1630 | </row> | |
| 1631 | <row> | |
| 1632 | <entry align='left'>ł</entry> | |
| 1633 | <entry align='left'>\[/l]</entry> | |
| 1634 | <entry align='left'>lslash </entry> | |
| 1635 | <entry align='left'>u0142 </entry> | |
| 1636 | <entry align='left'>(Polish)</entry> | |
| 1637 | </row> | |
| 1638 | <row> | |
| 1639 | <entry align='left'>Ø</entry> | |
| 1640 | <entry align='left'>\[/O]</entry> | |
| 1641 | <entry align='left'>Oslash </entry> | |
| 1642 | <entry align='left'>u00D8 </entry> | |
| 1643 | <entry align='left'>(Scandinavian)</entry> | |
| 1644 | </row> | |
| 1645 | <row> | |
| 1646 | <entry align='left'>ø</entry> | |
| 1647 | <entry align='left'>\[/o]</entry> | |
| 1648 | <entry align='left'>oslash </entry> | |
| 1649 | <entry align='left'>u00F8 </entry> | |
| 1650 | <entry align='left'>(Scandinavian)</entry> | |
| 1651 | </row> | |
| 1652 | <row> | |
| 1653 | <entry align='left'>Æ</entry> | |
| 1654 | <entry align='left'>\[AE]</entry> | |
| 1655 | <entry align='left'>AE </entry> | |
| 1656 | <entry align='left'>u00C6</entry> | |
| 1657 | <entry align='left'></entry> | |
| 1658 | </row> | |
| 1659 | <row> | |
| 1660 | <entry align='left'>æ</entry> | |
| 1661 | <entry align='left'>\[ae]</entry> | |
| 1662 | <entry align='left'>ae </entry> | |
| 1663 | <entry align='left'>u00E6</entry> | |
| 1664 | <entry align='left'></entry> | |
| 1665 | </row> | |
| 1666 | <row> | |
| 1667 | <entry align='left'>Œ</entry> | |
| 1668 | <entry align='left'>\[OE]</entry> | |
| 1669 | <entry align='left'>OE </entry> | |
| 1670 | <entry align='left'>u0152</entry> | |
| 1671 | <entry align='left'></entry> | |
| 1672 | </row> | |
| 1673 | <row> | |
| 1674 | <entry align='left'>œ</entry> | |
| 1675 | <entry align='left'>\[oe]</entry> | |
| 1676 | <entry align='left'>oe </entry> | |
| 1677 | <entry align='left'>u0153</entry> | |
| 1678 | <entry align='left'></entry> | |
| 1679 | </row> | |
| 1680 | <row> | |
| 1681 | <entry align='left'>ij</entry> | |
| 1682 | <entry align='left'>\[IJ]</entry> | |
| 1683 | <entry align='left'>IJ </entry> | |
| 1684 | <entry align='left'>u0132 </entry> | |
| 1685 | <entry align='left'>(Dutch)</entry> | |
| 1686 | </row> | |
| 1687 | <row> | |
| 1688 | <entry align='left'>IJ</entry> | |
| 1689 | <entry align='left'>\[ij]</entry> | |
| 1690 | <entry align='left'>ij </entry> | |
| 1691 | <entry align='left'>u0133 </entry> | |
| 1692 | <entry align='left'>(Dutch)</entry> | |
| 1693 | </row> | |
| 1694 | <row> | |
| 1695 | <entry align='left'>ı</entry> | |
| 1696 | <entry align='left'>\[.i]</entry> | |
| 1697 | <entry align='left'>dotlessi</entry> | |
| 1698 | <entry align='left'>u0131 </entry> | |
| 1699 | <entry align='left'>(Turkish)</entry> | |
| 1700 | </row> | |
| 1701 | <row> | |
| 1702 | <entry align='left'>&jnodot;</entry> | |
| 1703 | <entry align='left'>\[.j]</entry> | |
| 1704 | <entry align='left'>dotlessj</entry> | |
| 1705 | <entry align='left'>--- </entry> | |
| 1706 | <entry align='left'>j without a dot</entry> | |
| 1707 | </row> | |
| 1708 | </tbody> | |
| 1709 | </tgroup> | |
| 1710 | </informaltable> | |
| 1711 | ||
| 1712 | ||
| 1713 | ||
| 1714 | ||
| 1715 | <para><emphasis remap='I'>Accented Characters</emphasis></para> | |
| 1716 | ||
| 1717 | <informaltable pgwide='0' frame='none'> | |
| 1718 | <tgroup cols='5' align='center'> | |
| 1719 | <colspec colname='c1'/> | |
| 1720 | <colspec colname='c2'/> | |
| 1721 | <colspec colname='c3'/> | |
| 1722 | <colspec colname='c4'/> | |
| 1723 | <colspec colname='c5'/> | |
| 1724 | <tbody> | |
| 1725 | <row rowsep='1'> | |
| 1726 | <entry align='left'>Output </entry> | |
| 1727 | <entry align='left'>Input</entry> | |
| 1728 | <entry align='left'>PostScript</entry> | |
| 1729 | <entry align='left'>Unicode </entry> | |
| 1730 | <entry align='left'>Notes</entry> | |
| 1731 | </row> | |
| 1732 | <row> | |
| 1733 | <entry align='left'>Á</entry> | |
| 1734 | <entry align='left'>\['A]</entry> | |
| 1735 | <entry align='left'>Aacute </entry> | |
| 1736 | <entry align='left'>u0041_0301</entry> | |
| 1737 | <entry align='left'></entry> | |
| 1738 | </row> | |
| 1739 | <row> | |
| 1740 | <entry align='left'>Ć</entry> | |
| 1741 | <entry align='left'>\['C]</entry> | |
| 1742 | <entry align='left'>Cacute </entry> | |
| 1743 | <entry align='left'>u0043_0301</entry> | |
| 1744 | <entry align='left'></entry> | |
| 1745 | </row> | |
| 1746 | <row> | |
| 1747 | <entry align='left'>É</entry> | |
| 1748 | <entry align='left'>\['E]</entry> | |
| 1749 | <entry align='left'>Eacute </entry> | |
| 1750 | <entry align='left'>u0045_0301</entry> | |
| 1751 | <entry align='left'></entry> | |
| 1752 | </row> | |
| 1753 | <row> | |
| 1754 | <entry align='left'>Í</entry> | |
| 1755 | <entry align='left'>\['I]</entry> | |
| 1756 | <entry align='left'>Iacute </entry> | |
| 1757 | <entry align='left'>u0049_0301</entry> | |
| 1758 | <entry align='left'></entry> | |
| 1759 | </row> | |
| 1760 | <row> | |
| 1761 | <entry align='left'>Ó</entry> | |
| 1762 | <entry align='left'>\['O]</entry> | |
| 1763 | <entry align='left'>Oacute </entry> | |
| 1764 | <entry align='left'>u004F_0301</entry> | |
| 1765 | <entry align='left'></entry> | |
| 1766 | </row> | |
| 1767 | <row> | |
| 1768 | <entry align='left'>Ú</entry> | |
| 1769 | <entry align='left'>\['U]</entry> | |
| 1770 | <entry align='left'>Uacute </entry> | |
| 1771 | <entry align='left'>u0055_0301</entry> | |
| 1772 | <entry align='left'></entry> | |
| 1773 | </row> | |
| 1774 | <row> | |
| 1775 | <entry align='left'>Ý</entry> | |
| 1776 | <entry align='left'>\['Y]</entry> | |
| 1777 | <entry align='left'>Yacute </entry> | |
| 1778 | <entry align='left'>u0059_0301</entry> | |
| 1779 | <entry align='left'></entry> | |
| 1780 | </row> | |
| 1781 | <row> | |
| 1782 | <entry align='left'>á</entry> | |
| 1783 | <entry align='left'>\['a]</entry> | |
| 1784 | <entry align='left'>aacute </entry> | |
| 1785 | <entry align='left'>u0061_0301</entry> | |
| 1786 | <entry align='left'></entry> | |
| 1787 | </row> | |
| 1788 | <row> | |
| 1789 | <entry align='left'>ć</entry> | |
| 1790 | <entry align='left'>\['c]</entry> | |
| 1791 | <entry align='left'>cacute </entry> | |
| 1792 | <entry align='left'>u0063_0301</entry> | |
| 1793 | <entry align='left'></entry> | |
| 1794 | </row> | |
| 1795 | <row> | |
| 1796 | <entry align='left'>é</entry> | |
| 1797 | <entry align='left'>\['e]</entry> | |
| 1798 | <entry align='left'>eacute </entry> | |
| 1799 | <entry align='left'>u0065_0301</entry> | |
| 1800 | <entry align='left'></entry> | |
| 1801 | </row> | |
| 1802 | <row> | |
| 1803 | <entry align='left'>í</entry> | |
| 1804 | <entry align='left'>\['i]</entry> | |
| 1805 | <entry align='left'>iacute </entry> | |
| 1806 | <entry align='left'>u0069_0301</entry> | |
| 1807 | <entry align='left'></entry> | |
| 1808 | </row> | |
| 1809 | <row> | |
| 1810 | <entry align='left'>ó</entry> | |
| 1811 | <entry align='left'>\['o]</entry> | |
| 1812 | <entry align='left'>oacute </entry> | |
| 1813 | <entry align='left'>u006F_0301</entry> | |
| 1814 | <entry align='left'></entry> | |
| 1815 | </row> | |
| 1816 | <row> | |
| 1817 | <entry align='left'>ú</entry> | |
| 1818 | <entry align='left'>\['u]</entry> | |
| 1819 | <entry align='left'>uacute </entry> | |
| 1820 | <entry align='left'>u0075_0301</entry> | |
| 1821 | <entry align='left'></entry> | |
| 1822 | </row> | |
| 1823 | <row> | |
| 1824 | <entry align='left'>ý</entry> | |
| 1825 | <entry align='left'>\['y]</entry> | |
| 1826 | <entry align='left'>yacute </entry> | |
| 1827 | <entry align='left'>u0079_0301</entry> | |
| 1828 | <entry align='left'></entry> | |
| 1829 | </row> | |
| 1830 | <row> | |
| 1831 | <entry align='left'>Ä</entry> | |
| 1832 | <entry align='left'>\[:A]</entry> | |
| 1833 | <entry align='left'>Adieresis</entry> | |
| 1834 | <entry align='left'>u0041_0308</entry> | |
| 1835 | <entry align='left'>A with umlaut</entry> | |
| 1836 | </row> | |
| 1837 | <row> | |
| 1838 | <entry align='left'>Ë</entry> | |
| 1839 | <entry align='left'>\[:E]</entry> | |
| 1840 | <entry align='left'>Edieresis</entry> | |
| 1841 | <entry align='left'>u0045_0308</entry> | |
| 1842 | <entry align='left'></entry> | |
| 1843 | </row> | |
| 1844 | <row> | |
| 1845 | <entry align='left'>Ï</entry> | |
| 1846 | <entry align='left'>\[:I]</entry> | |
| 1847 | <entry align='left'>Idieresis</entry> | |
| 1848 | <entry align='left'>u0049_0308</entry> | |
| 1849 | <entry align='left'></entry> | |
| 1850 | </row> | |
| 1851 | <row> | |
| 1852 | <entry align='left'>Ö</entry> | |
| 1853 | <entry align='left'>\[:O]</entry> | |
| 1854 | <entry align='left'>Odieresis</entry> | |
| 1855 | <entry align='left'>u004F_0308</entry> | |
| 1856 | <entry align='left'></entry> | |
| 1857 | </row> | |
| 1858 | <row> | |
| 1859 | <entry align='left'>Ü</entry> | |
| 1860 | <entry align='left'>\[:U]</entry> | |
| 1861 | <entry align='left'>Udieresis</entry> | |
| 1862 | <entry align='left'>u0055_0308</entry> | |
| 1863 | <entry align='left'></entry> | |
| 1864 | </row> | |
| 1865 | <row> | |
| 1866 | <entry align='left'>Ÿ</entry> | |
| 1867 | <entry align='left'>\[:Y]</entry> | |
| 1868 | <entry align='left'>Ydieresis</entry> | |
| 1869 | <entry align='left'>u0059_0308</entry> | |
| 1870 | <entry align='left'></entry> | |
| 1871 | </row> | |
| 1872 | <row> | |
| 1873 | <entry align='left'>ä</entry> | |
| 1874 | <entry align='left'>\[:a]</entry> | |
| 1875 | <entry align='left'>adieresis</entry> | |
| 1876 | <entry align='left'>u0061_0308</entry> | |
| 1877 | <entry align='left'></entry> | |
| 1878 | </row> | |
| 1879 | <row> | |
| 1880 | <entry align='left'>ë</entry> | |
| 1881 | <entry align='left'>\[:e]</entry> | |
| 1882 | <entry align='left'>edieresis</entry> | |
| 1883 | <entry align='left'>u0065_0308</entry> | |
| 1884 | <entry align='left'></entry> | |
| 1885 | </row> | |
| 1886 | <row> | |
| 1887 | <entry align='left'>ï</entry> | |
| 1888 | <entry align='left'>\[:i]</entry> | |
| 1889 | <entry align='left'>idieresis</entry> | |
| 1890 | <entry align='left'>u0069_0308</entry> | |
| 1891 | <entry align='left'></entry> | |
| 1892 | </row> | |
| 1893 | <row> | |
| 1894 | <entry align='left'>ö</entry> | |
| 1895 | <entry align='left'>\[:o]</entry> | |
| 1896 | <entry align='left'>odieresis</entry> | |
| 1897 | <entry align='left'>u006F_0308</entry> | |
| 1898 | <entry align='left'></entry> | |
| 1899 | </row> | |
| 1900 | <row> | |
| 1901 | <entry align='left'>ü</entry> | |
| 1902 | <entry align='left'>\[:u]</entry> | |
| 1903 | <entry align='left'>udieresis</entry> | |
| 1904 | <entry align='left'>u0075_0308</entry> | |
| 1905 | <entry align='left'></entry> | |
| 1906 | </row> | |
| 1907 | <row> | |
| 1908 | <entry align='left'>ÿ</entry> | |
| 1909 | <entry align='left'>\[:y]</entry> | |
| 1910 | <entry align='left'>ydieresis</entry> | |
| 1911 | <entry align='left'>u0079_0308</entry> | |
| 1912 | <entry align='left'></entry> | |
| 1913 | </row> | |
| 1914 | <row> | |
| 1915 | <entry align='left'>Â</entry> | |
| 1916 | <entry align='left'>\[^A]</entry> | |
| 1917 | <entry align='left'>Acircumflex</entry> | |
| 1918 | <entry align='left'>u0041_0302</entry> | |
| 1919 | <entry align='left'></entry> | |
| 1920 | </row> | |
| 1921 | <row> | |
| 1922 | <entry align='left'>Ê</entry> | |
| 1923 | <entry align='left'>\[^E]</entry> | |
| 1924 | <entry align='left'>Ecircumflex</entry> | |
| 1925 | <entry align='left'>u0045_0302</entry> | |
| 1926 | <entry align='left'></entry> | |
| 1927 | </row> | |
| 1928 | <row> | |
| 1929 | <entry align='left'>Î</entry> | |
| 1930 | <entry align='left'>\[^I]</entry> | |
| 1931 | <entry align='left'>Icircumflex</entry> | |
| 1932 | <entry align='left'>u0049_0302</entry> | |
| 1933 | <entry align='left'></entry> | |
| 1934 | </row> | |
| 1935 | <row> | |
| 1936 | <entry align='left'>Ô</entry> | |
| 1937 | <entry align='left'>\[^O]</entry> | |
| 1938 | <entry align='left'>Ocircumflex</entry> | |
| 1939 | <entry align='left'>u004F_0302</entry> | |
| 1940 | <entry align='left'></entry> | |
| 1941 | </row> | |
| 1942 | <row> | |
| 1943 | <entry align='left'>Û</entry> | |
| 1944 | <entry align='left'>\[^U]</entry> | |
| 1945 | <entry align='left'>Ucircumflex</entry> | |
| 1946 | <entry align='left'>u0055_0302</entry> | |
| 1947 | <entry align='left'></entry> | |
| 1948 | </row> | |
| 1949 | <row> | |
| 1950 | <entry align='left'>â</entry> | |
| 1951 | <entry align='left'>\[^a]</entry> | |
| 1952 | <entry align='left'>acircumflex</entry> | |
| 1953 | <entry align='left'>u0061_0302</entry> | |
| 1954 | <entry align='left'></entry> | |
| 1955 | </row> | |
| 1956 | <row> | |
| 1957 | <entry align='left'>ê</entry> | |
| 1958 | <entry align='left'>\[^e]</entry> | |
| 1959 | <entry align='left'>ecircumflex</entry> | |
| 1960 | <entry align='left'>u0065_0302</entry> | |
| 1961 | <entry align='left'></entry> | |
| 1962 | </row> | |
| 1963 | <row> | |
| 1964 | <entry align='left'>î</entry> | |
| 1965 | <entry align='left'>\[^i]</entry> | |
| 1966 | <entry align='left'>icircumflex</entry> | |
| 1967 | <entry align='left'>u0069_0302</entry> | |
| 1968 | <entry align='left'></entry> | |
| 1969 | </row> | |
| 1970 | <row> | |
| 1971 | <entry align='left'>ô</entry> | |
| 1972 | <entry align='left'>\[^o]</entry> | |
| 1973 | <entry align='left'>ocircumflex</entry> | |
| 1974 | <entry align='left'>u006F_0302</entry> | |
| 1975 | <entry align='left'></entry> | |
| 1976 | </row> | |
| 1977 | <row> | |
| 1978 | <entry align='left'>û</entry> | |
| 1979 | <entry align='left'>\[^u]</entry> | |
| 1980 | <entry align='left'>ucircumflex</entry> | |
| 1981 | <entry align='left'>u0075_0302</entry> | |
| 1982 | <entry align='left'></entry> | |
| 1983 | </row> | |
| 1984 | <row> | |
| 1985 | <entry align='left'>À</entry> | |
| 1986 | <entry align='left'>\[`A]</entry> | |
| 1987 | <entry align='left'>Agrave </entry> | |
| 1988 | <entry align='left'>u0041_0300</entry> | |
| 1989 | <entry align='left'></entry> | |
| 1990 | </row> | |
| 1991 | <row> | |
| 1992 | <entry align='left'>È</entry> | |
| 1993 | <entry align='left'>\[`E]</entry> | |
| 1994 | <entry align='left'>Egrave </entry> | |
| 1995 | <entry align='left'>u0045_0300</entry> | |
| 1996 | <entry align='left'></entry> | |
| 1997 | </row> | |
| 1998 | <row> | |
| 1999 | <entry align='left'>Ì</entry> | |
| 2000 | <entry align='left'>\[`I]</entry> | |
| 2001 | <entry align='left'>Igrave </entry> | |
| 2002 | <entry align='left'>u0049_0300</entry> | |
| 2003 | <entry align='left'></entry> | |
| 2004 | </row> | |
| 2005 | <row> | |
| 2006 | <entry align='left'>Ò</entry> | |
| 2007 | <entry align='left'>\[`O]</entry> | |
| 2008 | <entry align='left'>Ograve </entry> | |
| 2009 | <entry align='left'>u004F_0300</entry> | |
| 2010 | <entry align='left'></entry> | |
| 2011 | </row> | |
| 2012 | <row> | |
| 2013 | <entry align='left'>Ù</entry> | |
| 2014 | <entry align='left'>\[`U]</entry> | |
| 2015 | <entry align='left'>Ugrave </entry> | |
| 2016 | <entry align='left'>u0055_0300</entry> | |
| 2017 | <entry align='left'></entry> | |
| 2018 | </row> | |
| 2019 | <row> | |
| 2020 | <entry align='left'>à</entry> | |
| 2021 | <entry align='left'>\[`a]</entry> | |
| 2022 | <entry align='left'>agrave </entry> | |
| 2023 | <entry align='left'>u0061_0300</entry> | |
| 2024 | <entry align='left'></entry> | |
| 2025 | </row> | |
| 2026 | <row> | |
| 2027 | <entry align='left'>è</entry> | |
| 2028 | <entry align='left'>\[`e]</entry> | |
| 2029 | <entry align='left'>egrave </entry> | |
| 2030 | <entry align='left'>u0065_0300</entry> | |
| 2031 | <entry align='left'></entry> | |
| 2032 | </row> | |
| 2033 | <row> | |
| 2034 | <entry align='left'>ì</entry> | |
| 2035 | <entry align='left'>\[`i]</entry> | |
| 2036 | <entry align='left'>igrave </entry> | |
| 2037 | <entry align='left'>u0069_0300</entry> | |
| 2038 | <entry align='left'></entry> | |
| 2039 | </row> | |
| 2040 | <row> | |
| 2041 | <entry align='left'>ò</entry> | |
| 2042 | <entry align='left'>\[`o]</entry> | |
| 2043 | <entry align='left'>ograve </entry> | |
| 2044 | <entry align='left'>u006F_0300</entry> | |
| 2045 | <entry align='left'></entry> | |
| 2046 | </row> | |
| 2047 | <row> | |
| 2048 | <entry align='left'>ù</entry> | |
| 2049 | <entry align='left'>\[`u]</entry> | |
| 2050 | <entry align='left'>ugrave </entry> | |
| 2051 | <entry align='left'>u0075_0300</entry> | |
| 2052 | <entry align='left'></entry> | |
| 2053 | </row> | |
| 2054 | <row> | |
| 2055 | <entry align='left'>Ã</entry> | |
| 2056 | <entry align='left'>\[~A]</entry> | |
| 2057 | <entry align='left'>Atilde </entry> | |
| 2058 | <entry align='left'>u0041_0303</entry> | |
| 2059 | <entry align='left'></entry> | |
| 2060 | </row> | |
| 2061 | <row> | |
| 2062 | <entry align='left'>Ñ</entry> | |
| 2063 | <entry align='left'>\[~N]</entry> | |
| 2064 | <entry align='left'>Ntilde </entry> | |
| 2065 | <entry align='left'>u004E_0303</entry> | |
| 2066 | <entry align='left'></entry> | |
| 2067 | </row> | |
| 2068 | <row> | |
| 2069 | <entry align='left'>Õ</entry> | |
| 2070 | <entry align='left'>\[~O]</entry> | |
| 2071 | <entry align='left'>Otilde </entry> | |
| 2072 | <entry align='left'>u004F_0303</entry> | |
| 2073 | <entry align='left'></entry> | |
| 2074 | </row> | |
| 2075 | <row> | |
| 2076 | <entry align='left'>ã</entry> | |
| 2077 | <entry align='left'>\[~a]</entry> | |
| 2078 | <entry align='left'>atilde </entry> | |
| 2079 | <entry align='left'>u0061_0303</entry> | |
| 2080 | <entry align='left'></entry> | |
| 2081 | </row> | |
| 2082 | <row> | |
| 2083 | <entry align='left'>ñ</entry> | |
| 2084 | <entry align='left'>\[~n]</entry> | |
| 2085 | <entry align='left'>ntilde </entry> | |
| 2086 | <entry align='left'>u006E_0303</entry> | |
| 2087 | <entry align='left'></entry> | |
| 2088 | </row> | |
| 2089 | <row> | |
| 2090 | <entry align='left'>õ</entry> | |
| 2091 | <entry align='left'>\[~o]</entry> | |
| 2092 | <entry align='left'>otilde </entry> | |
| 2093 | <entry align='left'>u006F_0303</entry> | |
| 2094 | <entry align='left'></entry> | |
| 2095 | </row> | |
| 2096 | <row> | |
| 2097 | <entry align='left'>Š</entry> | |
| 2098 | <entry align='left'>\[vS]</entry> | |
| 2099 | <entry align='left'>Scaron </entry> | |
| 2100 | <entry align='left'>u0053_030C</entry> | |
| 2101 | <entry align='left'></entry> | |
| 2102 | </row> | |
| 2103 | <row> | |
| 2104 | <entry align='left'>š</entry> | |
| 2105 | <entry align='left'>\[vs]</entry> | |
| 2106 | <entry align='left'>scaron </entry> | |
| 2107 | <entry align='left'>u0073_030C</entry> | |
| 2108 | <entry align='left'></entry> | |
| 2109 | </row> | |
| 2110 | <row> | |
| 2111 | <entry align='left'>Ž</entry> | |
| 2112 | <entry align='left'>\[vZ]</entry> | |
| 2113 | <entry align='left'>Zcaron </entry> | |
| 2114 | <entry align='left'>u005A_030C</entry> | |
| 2115 | <entry align='left'></entry> | |
| 2116 | </row> | |
| 2117 | <row> | |
| 2118 | <entry align='left'>ž</entry> | |
| 2119 | <entry align='left'>\[vz]</entry> | |
| 2120 | <entry align='left'>zcaron </entry> | |
| 2121 | <entry align='left'>u007A_030C</entry> | |
| 2122 | <entry align='left'></entry> | |
| 2123 | </row> | |
| 2124 | <row> | |
| 2125 | <entry align='left'>Ç</entry> | |
| 2126 | <entry align='left'>\[,C]</entry> | |
| 2127 | <entry align='left'>Ccedilla</entry> | |
| 2128 | <entry align='left'>u0043_0327</entry> | |
| 2129 | <entry align='left'></entry> | |
| 2130 | </row> | |
| 2131 | <row> | |
| 2132 | <entry align='left'>ç</entry> | |
| 2133 | <entry align='left'>\[,c]</entry> | |
| 2134 | <entry align='left'>ccedilla</entry> | |
| 2135 | <entry align='left'>u0063_0327</entry> | |
| 2136 | <entry align='left'></entry> | |
| 2137 | </row> | |
| 2138 | <row> | |
| 2139 | <entry align='left'>Å</entry> | |
| 2140 | <entry align='left'>\[oA]</entry> | |
| 2141 | <entry align='left'>Aring </entry> | |
| 2142 | <entry align='left'>u0041_030A</entry> | |
| 2143 | <entry align='left'></entry> | |
| 2144 | </row> | |
| 2145 | <row> | |
| 2146 | <entry align='left'>å</entry> | |
| 2147 | <entry align='left'>\[oa]</entry> | |
| 2148 | <entry align='left'>aring </entry> | |
| 2149 | <entry align='left'>u0061_030A</entry> | |
| 2150 | <entry align='left'></entry> | |
| 2151 | </row> | |
| 2152 | </tbody> | |
| 2153 | </tgroup> | |
| 2154 | </informaltable> | |
| 2155 | ||
| 2156 | ||
| 2157 | ||
| 2158 | ||
| 2159 | <para><emphasis remap='I'>Accents</emphasis></para> | |
| 2160 | ||
| 2161 | <para>The | |
| 2162 | <emphasis remap='B'>composite</emphasis> | |
| 2163 | request is used to map most of the accents to non-spacing glyph names; | |
| 2164 | the values given in parentheses are the original (spacing) ones.</para> | |
| 2165 | ||
| 2166 | <informaltable pgwide='0' frame='none'> | |
| 2167 | <tgroup cols='5' align='center'> | |
| 2168 | <colspec colname='c1'/> | |
| 2169 | <colspec colname='c2'/> | |
| 2170 | <colspec colname='c3'/> | |
| 2171 | <colspec colname='c4'/> | |
| 2172 | <colspec colname='c5'/> | |
| 2173 | <tbody> | |
| 2174 | <row rowsep='1'> | |
| 2175 | <entry align='left'>Output </entry> | |
| 2176 | <entry align='left'>Input</entry> | |
| 2177 | <entry align='left'>PostScript</entry> | |
| 2178 | <entry align='left'>Unicode </entry> | |
| 2179 | <entry align='left'>Notes</entry> | |
| 2180 | </row> | |
| 2181 | <row> | |
| 2182 | <entry align='left'>˝</entry> | |
| 2183 | <entry align='left'>\[a"]</entry> | |
| 2184 | <entry align='left'>hungarumlaut </entry> | |
| 2185 | <entry align='left'>u030B (u02DD)</entry> | |
| 2186 | <entry align='left'>(Hungarian)</entry> | |
| 2187 | </row> | |
| 2188 | <row> | |
| 2189 | <entry align='left'>¯</entry> | |
| 2190 | <entry align='left'>\[a-]</entry> | |
| 2191 | <entry align='left'>macron </entry> | |
| 2192 | <entry align='left'>u0304 (u00AF)</entry> | |
| 2193 | <entry align='left'></entry> | |
| 2194 | </row> | |
| 2195 | <row> | |
| 2196 | <entry align='left'>˙</entry> | |
| 2197 | <entry align='left'>\[a.]</entry> | |
| 2198 | <entry align='left'>dotaccent </entry> | |
| 2199 | <entry align='left'>u0307 (u02D9)</entry> | |
| 2200 | <entry align='left'></entry> | |
| 2201 | </row> | |
| 2202 | <row> | |
| 2203 | <entry align='left'>ˆ</entry> | |
| 2204 | <entry align='left'>\[a^]</entry> | |
| 2205 | <entry align='left'>circumfle </entry> | |
| 2206 | <entry align='left'>u0302 (u005E)</entry> | |
| 2207 | <entry align='left'></entry> | |
| 2208 | </row> | |
| 2209 | <row> | |
| 2210 | <entry align='left'>´</entry> | |
| 2211 | <entry align='left'>\[aa]</entry> | |
| 2212 | <entry align='left'>acute </entry> | |
| 2213 | <entry align='left'>u0301 (u00B4)</entry> | |
| 2214 | <entry align='left'>+</entry> | |
| 2215 | </row> | |
| 2216 | <row> | |
| 2217 | <entry align='left'>`</entry> | |
| 2218 | <entry align='left'>\[ga]</entry> | |
| 2219 | <entry align='left'>grave </entry> | |
| 2220 | <entry align='left'>u0300 (u0060)</entry> | |
| 2221 | <entry align='left'>+</entry> | |
| 2222 | </row> | |
| 2223 | <row> | |
| 2224 | <entry align='left'>˘</entry> | |
| 2225 | <entry align='left'>\[ab]</entry> | |
| 2226 | <entry align='left'>breve </entry> | |
| 2227 | <entry align='left'>u0306 (u02D8)</entry> | |
| 2228 | <entry align='left'></entry> | |
| 2229 | </row> | |
| 2230 | <row> | |
| 2231 | <entry align='left'>¸</entry> | |
| 2232 | <entry align='left'>\[ac]</entry> | |
| 2233 | <entry align='left'>cedilla </entry> | |
| 2234 | <entry align='left'>u0327 (u00B8)</entry> | |
| 2235 | <entry align='left'></entry> | |
| 2236 | </row> | |
| 2237 | <row> | |
| 2238 | <entry align='left'>¨</entry> | |
| 2239 | <entry align='left'>\[ad]</entry> | |
| 2240 | <entry align='left'>dieresis </entry> | |
| 2241 | <entry align='left'>u0308 (u00A8)</entry> | |
| 2242 | <entry align='left'>umlaut</entry> | |
| 2243 | </row> | |
| 2244 | <row> | |
| 2245 | <entry align='left'>ˇ</entry> | |
| 2246 | <entry align='left'>\[ah]</entry> | |
| 2247 | <entry align='left'>caron </entry> | |
| 2248 | <entry align='left'>u030C (u02C7)</entry> | |
| 2249 | <entry align='left'></entry> | |
| 2250 | </row> | |
| 2251 | <row> | |
| 2252 | <entry align='left'>˚</entry> | |
| 2253 | <entry align='left'>\[ao]</entry> | |
| 2254 | <entry align='left'>ring </entry> | |
| 2255 | <entry align='left'>u030A (u02DA)</entry> | |
| 2256 | <entry align='left'>circle</entry> | |
| 2257 | </row> | |
| 2258 | <row> | |
| 2259 | <entry align='left'>˜</entry> | |
| 2260 | <entry align='left'>\[a~]</entry> | |
| 2261 | <entry align='left'>tilde </entry> | |
| 2262 | <entry align='left'>u0303 (u007E)</entry> | |
| 2263 | <entry align='left'></entry> | |
| 2264 | </row> | |
| 2265 | <row> | |
| 2266 | <entry align='left'>˛</entry> | |
| 2267 | <entry align='left'>\[ho]</entry> | |
| 2268 | <entry align='left'>ogonek </entry> | |
| 2269 | <entry align='left'>u0328 (u02DB)</entry> | |
| 2270 | <entry align='left'>hook</entry> | |
| 2271 | </row> | |
| 2272 | <row> | |
| 2273 | <entry align='left'>^</entry> | |
| 2274 | <entry align='left'>\[ha]</entry> | |
| 2275 | <entry align='left'>asciicircum</entry> | |
| 2276 | <entry align='left'>u005E </entry> | |
| 2277 | <entry align='left'>(spacing)</entry> | |
| 2278 | </row> | |
| 2279 | <row> | |
| 2280 | <entry align='left'>~</entry> | |
| 2281 | <entry align='left'>\[ti]</entry> | |
| 2282 | <entry align='left'>asciitilde</entry> | |
| 2283 | <entry align='left'>u007E </entry> | |
| 2284 | <entry align='left'>(spacing)</entry> | |
| 2285 | </row> | |
| 2286 | </tbody> | |
| 2287 | </tgroup> | |
| 2288 | </informaltable> | |
| 2289 | ||
| 2290 | ||
| 2291 | ||
| 2292 | ||
| 2293 | <para><emphasis remap='I'>Quotes</emphasis></para> | |
| 2294 | ||
| 2295 | <informaltable pgwide='0' frame='none'> | |
| 2296 | <tgroup cols='5' align='center'> | |
| 2297 | <colspec colname='c1'/> | |
| 2298 | <colspec colname='c2'/> | |
| 2299 | <colspec colname='c3'/> | |
| 2300 | <colspec colname='c4'/> | |
| 2301 | <colspec colname='c5'/> | |
| 2302 | <tbody> | |
| 2303 | <row rowsep='1'> | |
| 2304 | <entry align='left'>Output </entry> | |
| 2305 | <entry align='left'>Input</entry> | |
| 2306 | <entry align='left'>PostScript</entry> | |
| 2307 | <entry align='left'>Unicode</entry> | |
| 2308 | <entry align='left'>Notes</entry> | |
| 2309 | </row> | |
| 2310 | <row> | |
| 2311 | <entry align='left'>‚</entry> | |
| 2312 | <entry align='left'>\[Bq]</entry> | |
| 2313 | <entry align='left'>quotedblbase</entry> | |
| 2314 | <entry align='left'>u201E</entry> | |
| 2315 | <entry align='left'>low double comma quote</entry> | |
| 2316 | </row> | |
| 2317 | <row> | |
| 2318 | <entry align='left'>„</entry> | |
| 2319 | <entry align='left'>\[bq]</entry> | |
| 2320 | <entry align='left'>quotesinglbase</entry> | |
| 2321 | <entry align='left'>u201A</entry> | |
| 2322 | <entry align='left'>low single comma quote</entry> | |
| 2323 | </row> | |
| 2324 | <row> | |
| 2325 | <entry align='left'>“</entry> | |
| 2326 | <entry align='left'>\[lq]</entry> | |
| 2327 | <entry align='left'>quotedblleft</entry> | |
| 2328 | <entry align='left'>u201C</entry> | |
| 2329 | <entry align='left'></entry> | |
| 2330 | </row> | |
| 2331 | <row> | |
| 2332 | <entry align='left'>”</entry> | |
| 2333 | <entry align='left'>\[rq]</entry> | |
| 2334 | <entry align='left'>quotedblright</entry> | |
| 2335 | <entry align='left'>u201D</entry> | |
| 2336 | <entry align='left'></entry> | |
| 2337 | </row> | |
| 2338 | <row> | |
| 2339 | <entry align='left'>‘</entry> | |
| 2340 | <entry align='left'>\[oq]</entry> | |
| 2341 | <entry align='left'>quoteleft</entry> | |
| 2342 | <entry align='left'>u2018</entry> | |
| 2343 | <entry align='left'>single open quote</entry> | |
| 2344 | </row> | |
| 2345 | <row> | |
| 2346 | <entry align='left'>’</entry> | |
| 2347 | <entry align='left'>\[cq]</entry> | |
| 2348 | <entry align='left'>quoteright</entry> | |
| 2349 | <entry align='left'>u2019</entry> | |
| 2350 | <entry align='left'>single closing quote</entry> | |
| 2351 | </row> | |
| 2352 | <row> | |
| 2353 | <entry align='left'>''</entry> | |
| 2354 | <entry align='left'>\[aq]</entry> | |
| 2355 | <entry align='left'>quotesingle</entry> | |
| 2356 | <entry align='left'>u0027</entry> | |
| 2357 | <entry align='left'>apostrophe quote (ASCII 39)</entry> | |
| 2358 | </row> | |
| 2359 | <row> | |
| 2360 | <entry align='left'>"</entry> | |
| 2361 | <entry align='left'>\[dq]</entry> | |
| 2362 | <entry align='left'>quotedbl</entry> | |
| 2363 | <entry align='left'>u0022</entry> | |
| 2364 | <entry align='left'>double quote (ASCII 34)</entry> | |
| 2365 | </row> | |
| 2366 | <row> | |
| 2367 | <entry align='left'>«</entry> | |
| 2368 | <entry align='left'>\[Fo]</entry> | |
| 2369 | <entry align='left'>guillemotleft</entry> | |
| 2370 | <entry align='left'>u00AB</entry> | |
| 2371 | <entry align='left'></entry> | |
| 2372 | </row> | |
| 2373 | <row> | |
| 2374 | <entry align='left'>»</entry> | |
| 2375 | <entry align='left'>\[Fc]</entry> | |
| 2376 | <entry align='left'>guillemotright</entry> | |
| 2377 | <entry align='left'>u00BB</entry> | |
| 2378 | <entry align='left'></entry> | |
| 2379 | </row> | |
| 2380 | <row> | |
| 2381 | <entry align='left'>&fo;</entry> | |
| 2382 | <entry align='left'>\[fo]</entry> | |
| 2383 | <entry align='left'>guilsinglleft</entry> | |
| 2384 | <entry align='left'>u2039</entry> | |
| 2385 | <entry align='left'></entry> | |
| 2386 | </row> | |
| 2387 | <row> | |
| 2388 | <entry align='left'>&fc;</entry> | |
| 2389 | <entry align='left'>\[fc]</entry> | |
| 2390 | <entry align='left'>guilsinglright</entry> | |
| 2391 | <entry align='left'>u203A</entry> | |
| 2392 | <entry align='left'></entry> | |
| 2393 | </row> | |
| 2394 | </tbody> | |
| 2395 | </tgroup> | |
| 2396 | </informaltable> | |
| 2397 | ||
| 2398 | ||
| 2399 | ||
| 2400 | ||
| 2401 | <para><emphasis remap='I'>Punctuation</emphasis></para> | |
| 2402 | ||
| 2403 | <informaltable pgwide='0' frame='none'> | |
| 2404 | <tgroup cols='5' align='center'> | |
| 2405 | <colspec colname='c1'/> | |
| 2406 | <colspec colname='c2'/> | |
| 2407 | <colspec colname='c3'/> | |
| 2408 | <colspec colname='c4'/> | |
| 2409 | <colspec colname='c5'/> | |
| 2410 | <tbody> | |
| 2411 | <row rowsep='1'> | |
| 2412 | <entry align='left'>Output </entry> | |
| 2413 | <entry align='left'>Input</entry> | |
| 2414 | <entry align='left'>PostScript</entry> | |
| 2415 | <entry align='left'>Unicode Notes</entry> | |
| 2416 | <entry align='left'></entry> | |
| 2417 | </row> | |
| 2418 | <row> | |
| 2419 | <entry align='left'>¡</entry> | |
| 2420 | <entry align='left'>\[r!]</entry> | |
| 2421 | <entry align='left'>exclamdown</entry> | |
| 2422 | <entry align='left'>u00A1</entry> | |
| 2423 | <entry align='left'></entry> | |
| 2424 | </row> | |
| 2425 | <row> | |
| 2426 | <entry align='left'>¿</entry> | |
| 2427 | <entry align='left'>\[r?]</entry> | |
| 2428 | <entry align='left'>questiondown</entry> | |
| 2429 | <entry align='left'>u00BF</entry> | |
| 2430 | <entry align='left'></entry> | |
| 2431 | </row> | |
| 2432 | <row> | |
| 2433 | <entry align='left'>—</entry> | |
| 2434 | <entry align='left'>\[em]</entry> | |
| 2435 | <entry align='left'>emdash </entry> | |
| 2436 | <entry align='left'>u2014</entry> | |
| 2437 | <entry align='left'>+</entry> | |
| 2438 | </row> | |
| 2439 | <row> | |
| 2440 | <entry align='left'>–</entry> | |
| 2441 | <entry align='left'>\[en]</entry> | |
| 2442 | <entry align='left'>endash </entry> | |
| 2443 | <entry align='left'>u2013</entry> | |
| 2444 | <entry align='left'></entry> | |
| 2445 | </row> | |
| 2446 | <row> | |
| 2447 | <entry align='left'>‐</entry> | |
| 2448 | <entry align='left'>\[hy]</entry> | |
| 2449 | <entry align='left'>hyphen </entry> | |
| 2450 | <entry align='left'>u2010</entry> | |
| 2451 | <entry align='left'>+</entry> | |
| 2452 | </row> | |
| 2453 | </tbody> | |
| 2454 | </tgroup> | |
| 2455 | </informaltable> | |
| 2456 | ||
| 2457 | ||
| 2458 | ||
| 2459 | ||
| 2460 | <para><emphasis remap='I'>Brackets</emphasis></para> | |
| 2461 | ||
| 2462 | <para>The extensible bracket pieces are font-invariant glyphs. | |
| 2463 | ||
| 2464 | In classical troff only one glyph was available to vertically extend | |
| 2465 | brackets, braces, and parentheses: `bv'. | |
| 2466 | ||
| 2467 | We map it rather arbitrarily to u23AA.</para> | |
| 2468 | ||
| 2469 | ||
| 2470 | <para>Note that not all devices contain extensible bracket pieces which can | |
| 2471 | be piled up with `<emphasis remap='CW'>\b</emphasis>' due to the restrictions of the escape's | |
| 2472 | piling algorithm. | |
| 2473 | ||
| 2474 | A general solution to build brackets out of pieces is the following | |
| 2475 | macro:</para> | |
| 2476 | ||
| 2477 | ||
| 2478 | <literallayout remap='.nf'> | |
| 2479 | <emphasis remap='C'> | |
| 2480 | .\" Make a pile centered vertically 0.5em | |
| 2481 | .\" above the baseline. | |
| 2482 | .\" The first argument is placed at the top. | |
| 2483 | .\" The pile is returned in string `pile' | |
| 2484 | .eo | |
| 2485 | .de pile-make | |
| 2486 | . nr pile-wd 0 | |
| 2487 | . nr pile-ht 0 | |
| 2488 | . ds pile-args | |
| 2489 | . | |
| 2490 | . nr pile-# \n[.$] | |
| 2491 | . while \n[pile-#] \{\ | |
| 2492 | . nr pile-wd (\n[pile-wd] >? \w'\$[\n[pile-#]]') | |
| 2493 | . nr pile-ht +(\n[rst] - \n[rsb]) | |
| 2494 | . as pile-args \v'\n[rsb]u'\" | |
| 2495 | . as pile-args \Z'\$[\n[pile-#]]'\" | |
| 2496 | . as pile-args \v'-\n[rst]u'\" | |
| 2497 | . nr pile-# -1 | |
| 2498 | . \} | |
| 2499 | . | |
| 2500 | . ds pile \v'(-0.5m + (\n[pile-ht]u / 2u))'\" | |
| 2501 | . as pile \*[pile-args]\" | |
| 2502 | . as pile \v'((\n[pile-ht]u / 2u) + 0.5m)'\" | |
| 2503 | . as pile \h'\n[pile-wd]u'\" | |
| 2504 | .. | |
| 2505 | .ec | |
| 2506 | </emphasis> | |
| 2507 | </literallayout> <!-- .fi --> | |
| 2508 | ||
| 2509 | ||
| 2510 | <para>Another complication is the fact that some glyphs which represent bracket | |
| 2511 | pieces in original troff can be used for other mathematical symbols also, | |
| 2512 | for example `lf' and `rf' which provide the `floor' operator. | |
| 2513 | ||
| 2514 | Other devices (most notably for DVI output) don't unify such glyphs. | |
| 2515 | ||
| 2516 | For this reason, the four glyphs `lf', `rf', `lc', and `rc' are not | |
| 2517 | unified with similarly looking bracket pieces. | |
| 2518 | ||
| 2519 | In | |
| 2520 | <emphasis remap='B'>groff</emphasis>, | |
| 2521 | only glyphs with long names are guaranteed to pile up correctly for all | |
| 2522 | devices (provided those glyphs exist).</para> | |
| 2523 | ||
| 2524 | <informaltable pgwide='1' frame='none'> | |
| 2525 | <tgroup cols='5' align='center'> | |
| 2526 | <colspec colname='c1'/> | |
| 2527 | <colspec colname='c2'/> | |
| 2528 | <colspec colname='c3'/> | |
| 2529 | <colspec colname='c4'/> | |
| 2530 | <colspec colname='c5'/> | |
| 2531 | <tbody> | |
| 2532 | <row rowsep='1'> | |
| 2533 | <entry align='left'>Output </entry> | |
| 2534 | <entry align='left'>Input </entry> | |
| 2535 | <entry align='left'>PostScript</entry> | |
| 2536 | <entry align='left'>Unicode</entry> | |
| 2537 | <entry align='left'>Notes</entry> | |
| 2538 | </row> | |
| 2539 | <row> | |
| 2540 | <entry align='left'>[</entry> | |
| 2541 | <entry align='left'>\[lB] </entry> | |
| 2542 | <entry align='left'>bracketleft</entry> | |
| 2543 | <entry align='left'>u005B</entry> | |
| 2544 | <entry align='left'></entry> | |
| 2545 | </row> | |
| 2546 | <row> | |
| 2547 | <entry align='left'>]</entry> | |
| 2548 | <entry align='left'>\[rB] </entry> | |
| 2549 | <entry align='left'>bracketright</entry> | |
| 2550 | <entry align='left'>u005D</entry> | |
| 2551 | <entry align='left'></entry> | |
| 2552 | </row> | |
| 2553 | <row> | |
| 2554 | <entry align='left'>{</entry> | |
| 2555 | <entry align='left'>\[lC] </entry> | |
| 2556 | <entry align='left'>braceleft</entry> | |
| 2557 | <entry align='left'>u007B</entry> | |
| 2558 | <entry align='left'></entry> | |
| 2559 | </row> | |
| 2560 | <row> | |
| 2561 | <entry align='left'>}</entry> | |
| 2562 | <entry align='left'>\[rC] </entry> | |
| 2563 | <entry align='left'>braceright</entry> | |
| 2564 | <entry align='left'>u007D</entry> | |
| 2565 | <entry align='left'></entry> | |
| 2566 | </row> | |
| 2567 | <row> | |
| 2568 | <entry align='left'>⟨</entry> | |
| 2569 | <entry align='left'>\[la] </entry> | |
| 2570 | <entry align='left'>angleleft</entry> | |
| 2571 | <entry align='left'>u27E8</entry> | |
| 2572 | <entry align='left'>left angle bracket</entry> | |
| 2573 | </row> | |
| 2574 | <row> | |
| 2575 | <entry align='left'>⟩</entry> | |
| 2576 | <entry align='left'>\[ra] </entry> | |
| 2577 | <entry align='left'>angleright</entry> | |
| 2578 | <entry align='left'>u27E9</entry> | |
| 2579 | <entry align='left'>right angle bracket</entry> | |
| 2580 | </row> | |
| 2581 | <row> | |
| 2582 | <entry align='left'></entry> | |
| 2583 | <entry align='left'></entry> | |
| 2584 | <entry align='left'></entry> | |
| 2585 | <entry align='left'></entry> | |
| 2586 | <entry align='left'></entry> | |
| 2587 | </row> | |
| 2588 | <row> | |
| 2589 | <entry align='left'>|</entry> | |
| 2590 | <entry align='left'>\[bv] </entry> | |
| 2591 | <entry align='left'>braceex </entry> | |
| 2592 | <entry align='left'>u23AA</entry> | |
| 2593 | <entry align='left'>vertical extension *** +</entry> | |
| 2594 | </row> | |
| 2595 | <row> | |
| 2596 | <entry align='left'>│</entry> | |
| 2597 | <entry align='left'>\[braceex] </entry> | |
| 2598 | <entry align='left'>braceex </entry> | |
| 2599 | <entry align='left'>u23AA</entry> | |
| 2600 | <entry align='left'></entry> | |
| 2601 | </row> | |
| 2602 | <row> | |
| 2603 | <entry align='left'></entry> | |
| 2604 | <entry align='left'></entry> | |
| 2605 | <entry align='left'></entry> | |
| 2606 | <entry align='left'></entry> | |
| 2607 | <entry align='left'></entry> | |
| 2608 | </row> | |
| 2609 | <row> | |
| 2610 | <entry align='left'>│</entry> | |
| 2611 | <entry align='left'>\[bracketlefttp]</entry> | |
| 2612 | <entry align='left'>bracketlefttp</entry> | |
| 2613 | <entry align='left'>u23A1</entry> | |
| 2614 | <entry align='left'></entry> | |
| 2615 | </row> | |
| 2616 | <row> | |
| 2617 | <entry align='left'>│</entry> | |
| 2618 | <entry align='left'>\[bracketleftbt]</entry> | |
| 2619 | <entry align='left'>bracketleftbt</entry> | |
| 2620 | <entry align='left'>u23A3</entry> | |
| 2621 | <entry align='left'></entry> | |
| 2622 | </row> | |
| 2623 | <row> | |
| 2624 | <entry align='left'>│</entry> | |
| 2625 | <entry align='left'>\[bracketleftex]</entry> | |
| 2626 | <entry align='left'>bracketleftex</entry> | |
| 2627 | <entry align='left'>u23A2</entry> | |
| 2628 | <entry align='left'></entry> | |
| 2629 | </row> | |
| 2630 | <row> | |
| 2631 | <entry align='left'>│</entry> | |
| 2632 | <entry align='left'>\[bracketrighttp]</entry> | |
| 2633 | <entry align='left'>bracketrighttp</entry> | |
| 2634 | <entry align='left'>u23A4</entry> | |
| 2635 | <entry align='left'></entry> | |
| 2636 | </row> | |
| 2637 | <row> | |
| 2638 | <entry align='left'>│</entry> | |
| 2639 | <entry align='left'>\[bracketrightbt]</entry> | |
| 2640 | <entry align='left'>bracketrightbt</entry> | |
| 2641 | <entry align='left'>u23A6</entry> | |
| 2642 | <entry align='left'></entry> | |
| 2643 | </row> | |
| 2644 | <row> | |
| 2645 | <entry align='left'>│</entry> | |
| 2646 | <entry align='left'>\[bracketrightex]</entry> | |
| 2647 | <entry align='left'>bracketrightex</entry> | |
| 2648 | <entry align='left'>u23A5</entry> | |
| 2649 | <entry align='left'></entry> | |
| 2650 | </row> | |
| 2651 | <row> | |
| 2652 | <entry align='left'></entry> | |
| 2653 | <entry align='left'></entry> | |
| 2654 | <entry align='left'></entry> | |
| 2655 | <entry align='left'></entry> | |
| 2656 | <entry align='left'></entry> | |
| 2657 | </row> | |
| 2658 | <row> | |
| 2659 | <entry align='left'>&tlt;</entry> | |
| 2660 | <entry align='left'>\[lt] </entry> | |
| 2661 | <entry align='left'>bracelefttp</entry> | |
| 2662 | <entry align='left'>u23A7</entry> | |
| 2663 | <entry align='left'>+</entry> | |
| 2664 | </row> | |
| 2665 | <row> | |
| 2666 | <entry align='left'>│</entry> | |
| 2667 | <entry align='left'>\[bracelefttp] </entry> | |
| 2668 | <entry align='left'>bracelefttp</entry> | |
| 2669 | <entry align='left'>u23A7</entry> | |
| 2670 | <entry align='left'></entry> | |
| 2671 | </row> | |
| 2672 | <row> | |
| 2673 | <entry align='left'>&lk;</entry> | |
| 2674 | <entry align='left'>\[lk] </entry> | |
| 2675 | <entry align='left'>braceleftmid</entry> | |
| 2676 | <entry align='left'>u23A8</entry> | |
| 2677 | <entry align='left'>+</entry> | |
| 2678 | </row> | |
| 2679 | <row> | |
| 2680 | <entry align='left'>│</entry> | |
| 2681 | <entry align='left'>\[braceleftmid]</entry> | |
| 2682 | <entry align='left'>braceleftmid</entry> | |
| 2683 | <entry align='left'>u23A8</entry> | |
| 2684 | <entry align='left'></entry> | |
| 2685 | </row> | |
| 2686 | <row> | |
| 2687 | <entry align='left'>&lb;</entry> | |
| 2688 | <entry align='left'>\[lb] </entry> | |
| 2689 | <entry align='left'>braceleftbt</entry> | |
| 2690 | <entry align='left'>u23A9</entry> | |
| 2691 | <entry align='left'>+</entry> | |
| 2692 | </row> | |
| 2693 | <row> | |
| 2694 | <entry align='left'>│</entry> | |
| 2695 | <entry align='left'>\[braceleftbt] </entry> | |
| 2696 | <entry align='left'>braceleftbt</entry> | |
| 2697 | <entry align='left'>u23A9</entry> | |
| 2698 | <entry align='left'></entry> | |
| 2699 | </row> | |
| 2700 | <row> | |
| 2701 | <entry align='left'>│</entry> | |
| 2702 | <entry align='left'>\[braceleftex] </entry> | |
| 2703 | <entry align='left'>braceleftex</entry> | |
| 2704 | <entry align='left'>u23AA</entry> | |
| 2705 | <entry align='left'></entry> | |
| 2706 | </row> | |
| 2707 | <row> | |
| 2708 | <entry align='left'>&rt;</entry> | |
| 2709 | <entry align='left'>\[rt] </entry> | |
| 2710 | <entry align='left'>bracerighttp</entry> | |
| 2711 | <entry align='left'>u23AB</entry> | |
| 2712 | <entry align='left'>+</entry> | |
| 2713 | </row> | |
| 2714 | <row> | |
| 2715 | <entry align='left'>│</entry> | |
| 2716 | <entry align='left'>\[bracerighttp]</entry> | |
| 2717 | <entry align='left'>bracerighttp</entry> | |
| 2718 | <entry align='left'>u23AB</entry> | |
| 2719 | <entry align='left'></entry> | |
| 2720 | </row> | |
| 2721 | <row> | |
| 2722 | <entry align='left'>&rk;</entry> | |
| 2723 | <entry align='left'>\[rk] </entry> | |
| 2724 | <entry align='left'>bracerightmid</entry> | |
| 2725 | <entry align='left'>u23AC</entry> | |
| 2726 | <entry align='left'>+</entry> | |
| 2727 | </row> | |
| 2728 | <row> | |
| 2729 | <entry align='left'>&bracerightmid;</entry> | |
| 2730 | <entry align='left'>\[bracerightmid]</entry> | |
| 2731 | <entry align='left'>bracerightmid</entry> | |
| 2732 | <entry align='left'>u23AC</entry> | |
| 2733 | <entry align='left'></entry> | |
| 2734 | </row> | |
| 2735 | <row> | |
| 2736 | <entry align='left'>&rb;</entry> | |
| 2737 | <entry align='left'>\[rb] </entry> | |
| 2738 | <entry align='left'>bracerightbt</entry> | |
| 2739 | <entry align='left'>u23AD</entry> | |
| 2740 | <entry align='left'>+</entry> | |
| 2741 | </row> | |
| 2742 | <row> | |
| 2743 | <entry align='left'>&rb; </entry> | |
| 2744 | <entry align='left'>\[bracerightbt]</entry> | |
| 2745 | <entry align='left'>bracerightbt</entry> | |
| 2746 | <entry align='left'>u23AD</entry> | |
| 2747 | <entry align='left'></entry> | |
| 2748 | </row> | |
| 2749 | <row> | |
| 2750 | <entry align='left'>&bracerightex; </entry> | |
| 2751 | <entry align='left'>\[bracerightex]</entry> | |
| 2752 | <entry align='left'>bracerightex</entry> | |
| 2753 | <entry align='left'>u23AA</entry> | |
| 2754 | <entry align='left'></entry> | |
| 2755 | </row> | |
| 2756 | <!-- --> | |
| 2757 | <row> | |
| 2758 | <entry align='left'>&parenlefttp;</entry> | |
| 2759 | <entry align='left'>\[parenlefttp] </entry> | |
| 2760 | <entry align='left'>parenlefttp</entry> | |
| 2761 | <entry align='left'>u239B</entry> | |
| 2762 | <entry align='left'></entry> | |
| 2763 | </row> | |
| 2764 | <row> | |
| 2765 | <entry align='left'>&parenleftbt;</entry> | |
| 2766 | <entry align='left'>\[parenleftbt] </entry> | |
| 2767 | <entry align='left'>parenleftbt</entry> | |
| 2768 | <entry align='left'>u239D</entry> | |
| 2769 | <entry align='left'></entry> | |
| 2770 | </row> | |
| 2771 | <row> | |
| 2772 | <entry align='left'>&parenleftex;</entry> | |
| 2773 | <entry align='left'>\[parenleftex] </entry> | |
| 2774 | <entry align='left'>parenleftex</entry> | |
| 2775 | <entry align='left'>u239C</entry> | |
| 2776 | <entry align='left'></entry> | |
| 2777 | </row> | |
| 2778 | <row> | |
| 2779 | <entry align='left'>&parenrighttp;</entry> | |
| 2780 | <entry align='left'>\[parenrighttp]</entry> | |
| 2781 | <entry align='left'>parenrighttp</entry> | |
| 2782 | <entry align='left'>u239E</entry> | |
| 2783 | <entry align='left'></entry> | |
| 2784 | </row> | |
| 2785 | <row> | |
| 2786 | <entry align='left'>&parenrightbt;</entry> | |
| 2787 | <entry align='left'>\[parenrightbt]</entry> | |
| 2788 | <entry align='left'>parenrightbt</entry> | |
| 2789 | <entry align='left'>u23A0</entry> | |
| 2790 | <entry align='left'></entry> | |
| 2791 | </row> | |
| 2792 | <row> | |
| 2793 | <entry align='left'>&parenrightex;</entry> | |
| 2794 | <entry align='left'>\[parenrightex]</entry> | |
| 2795 | <entry align='left'>parenrightex</entry> | |
| 2796 | <entry align='left'>u239F</entry> | |
| 2797 | <entry align='left'></entry> | |
| 2798 | </row> | |
| 2799 | </tbody> | |
| 2800 | </tgroup> | |
| 2801 | </informaltable> | |
| 2802 | ||
| 2803 | ||
| 2804 | ||
| 2805 | ||
| 2806 | <para><emphasis remap='I'>Arrows</emphasis></para> | |
| 2807 | ||
| 2808 | <informaltable pgwide='1' frame='none'> | |
| 2809 | <tgroup cols='5' align='center'> | |
| 2810 | <colspec colname='c1'/> | |
| 2811 | <colspec colname='c2'/> | |
| 2812 | <colspec colname='c3'/> | |
| 2813 | <colspec colname='c4'/> | |
| 2814 | <colspec colname='c5'/> | |
| 2815 | <tbody> | |
| 2816 | <row rowsep='1'> | |
| 2817 | <entry align='left'>Output</entry> | |
| 2818 | <entry align='left'>Input</entry> | |
| 2819 | <entry align='left'>PostScript</entry> | |
| 2820 | <entry align='left'>Unicode</entry> | |
| 2821 | <entry align='left'>Notes</entry> | |
| 2822 | </row> | |
| 2823 | <row> | |
| 2824 | <entry align='left'>←</entry> | |
| 2825 | <entry align='left'>\[<-]</entry> | |
| 2826 | <entry align='left'>arrowleft</entry> | |
| 2827 | <entry align='left'>u2190</entry> | |
| 2828 | <entry align='left'>+</entry> | |
| 2829 | </row> | |
| 2830 | <row> | |
| 2831 | <entry align='left'>→</entry> | |
| 2832 | <entry align='left'>\[->]</entry> | |
| 2833 | <entry align='left'>arrowright</entry> | |
| 2834 | <entry align='left'>u2192</entry> | |
| 2835 | <entry align='left'>+</entry> | |
| 2836 | </row> | |
| 2837 | <row> | |
| 2838 | <entry align='left'>↔</entry> | |
| 2839 | <entry align='left'>\[<>]</entry> | |
| 2840 | <entry align='left'>arrowboth</entry> | |
| 2841 | <entry align='left'>u2194</entry> | |
| 2842 | <entry align='left'>(horizontal)</entry> | |
| 2843 | </row> | |
| 2844 | <row> | |
| 2845 | <entry align='left'>↓</entry> | |
| 2846 | <entry align='left'>\[da]</entry> | |
| 2847 | <entry align='left'>arrowdown</entry> | |
| 2848 | <entry align='left'>u2193</entry> | |
| 2849 | <entry align='left'>+</entry> | |
| 2850 | </row> | |
| 2851 | <row> | |
| 2852 | <entry align='left'>↑</entry> | |
| 2853 | <entry align='left'>\[ua]</entry> | |
| 2854 | <entry align='left'>arrowup </entry> | |
| 2855 | <entry align='left'>u2191</entry> | |
| 2856 | <entry align='left'>+</entry> | |
| 2857 | </row> | |
| 2858 | <row> | |
| 2859 | <entry align='left'>↕</entry> | |
| 2860 | <entry align='left'>\[va]</entry> | |
| 2861 | <entry align='left'>arrowupdn</entry> | |
| 2862 | <entry align='left'>u2195</entry> | |
| 2863 | <entry align='left'></entry> | |
| 2864 | </row> | |
| 2865 | <row> | |
| 2866 | <entry align='left'>⇐</entry> | |
| 2867 | <entry align='left'>\[lA]</entry> | |
| 2868 | <entry align='left'>arrowdblleft</entry> | |
| 2869 | <entry align='left'>u21D0</entry> | |
| 2870 | <entry align='left'></entry> | |
| 2871 | </row> | |
| 2872 | <row> | |
| 2873 | <entry align='left'>⇒</entry> | |
| 2874 | <entry align='left'>\[rA]</entry> | |
| 2875 | <entry align='left'>arrowdblright</entry> | |
| 2876 | <entry align='left'>u21D2</entry> | |
| 2877 | <entry align='left'></entry> | |
| 2878 | </row> | |
| 2879 | <row> | |
| 2880 | <entry align='left'>⇔</entry> | |
| 2881 | <entry align='left'>\[hA]</entry> | |
| 2882 | <entry align='left'>arrowdblboth</entry> | |
| 2883 | <entry align='left'>u21D4</entry> | |
| 2884 | <entry align='left'>(horizontal)</entry> | |
| 2885 | </row> | |
| 2886 | <row> | |
| 2887 | <entry align='left'>⇓</entry> | |
| 2888 | <entry align='left'>\[dA]</entry> | |
| 2889 | <entry align='left'>arrowdbldown</entry> | |
| 2890 | <entry align='left'>u21D3</entry> | |
| 2891 | <entry align='left'></entry> | |
| 2892 | </row> | |
| 2893 | <row> | |
| 2894 | <entry align='left'>⇑</entry> | |
| 2895 | <entry align='left'>\[uA]</entry> | |
| 2896 | <entry align='left'>arrowdblup</entry> | |
| 2897 | <entry align='left'>u21D1</entry> | |
| 2898 | <entry align='left'></entry> | |
| 2899 | </row> | |
| 2900 | <row> | |
| 2901 | <entry align='left'>⇕</entry> | |
| 2902 | <entry align='left'>\[vA]</entry> | |
| 2903 | <entry align='left'>uni21D5 </entry> | |
| 2904 | <entry align='left'>u21D5</entry> | |
| 2905 | <entry align='left'>vertical double-headed double arrow</entry> | |
| 2906 | </row> | |
| 2907 | <row> | |
| 2908 | <entry align='left'>&an;</entry> | |
| 2909 | <entry align='left'>\[an]</entry> | |
| 2910 | <entry align='left'>arrowhorizex</entry> | |
| 2911 | <entry align='left'>u23AF</entry> | |
| 2912 | <entry align='left'>horizontal arrow extension</entry> | |
| 2913 | </row> | |
| 2914 | </tbody> | |
| 2915 | </tgroup> | |
| 2916 | </informaltable> | |
| 2917 | ||
| 2918 | ||
| 2919 | ||
| 2920 | ||
| 2921 | <para><emphasis remap='I'>Lines</emphasis></para> | |
| 2922 | ||
| 2923 | <para>The font-invariant glyphs `br', `ul', and `rn' form corners; | |
| 2924 | they can be used to build boxes. | |
| 2925 | ||
| 2926 | Note that both the PostScript and the Unicode-derived names of | |
| 2927 | these three glyphs are just rough approximations.</para> | |
| 2928 | ||
| 2929 | ||
| 2930 | <para>`rn' also serves in classical troff as the horizontal extension of the | |
| 2931 | square root sign.</para> | |
| 2932 | ||
| 2933 | ||
| 2934 | <para>`ru' is a font-invariant glyph, namely a rule of length 0.5m.</para> | |
| 2935 | ||
| 2936 | <informaltable pgwide='1' frame='none'> | |
| 2937 | <tgroup cols='5' align='center'> | |
| 2938 | <colspec colname='c1'/> | |
| 2939 | <colspec colname='c2'/> | |
| 2940 | <colspec colname='c3'/> | |
| 2941 | <colspec colname='c4'/> | |
| 2942 | <colspec colname='c5'/> | |
| 2943 | <tbody> | |
| 2944 | <row rowsep='1'> | |
| 2945 | <entry align='left'>Output</entry> | |
| 2946 | <entry align='left'>Input</entry> | |
| 2947 | <entry align='left'>PostScript</entry> | |
| 2948 | <entry align='left'>Unicode</entry> | |
| 2949 | <entry align='left'>Notes</entry> | |
| 2950 | </row> | |
| 2951 | <row> | |
| 2952 | <entry align='left'>|</entry> | |
| 2953 | <entry align='left'>\[ba]</entry> | |
| 2954 | <entry align='left'>bar </entry> | |
| 2955 | <entry align='left'>u007C </entry> | |
| 2956 | <entry align='left'></entry> | |
| 2957 | </row> | |
| 2958 | <row> | |
| 2959 | <entry align='left'>│</entry> | |
| 2960 | <entry align='left'>\[br]</entry> | |
| 2961 | <entry align='left'>SF110000</entry> | |
| 2962 | <entry align='left'>u2502</entry> | |
| 2963 | <entry align='left'>box rule +</entry> | |
| 2964 | </row> | |
| 2965 | <row> | |
| 2966 | <entry align='left'>_</entry> | |
| 2967 | <entry align='left'>\[ul]</entry> | |
| 2968 | <entry align='left'>underscore</entry> | |
| 2969 | <entry align='left'>u005F</entry> | |
| 2970 | <entry align='left'>+</entry> | |
| 2971 | </row> | |
| 2972 | <row> | |
| 2973 | <entry align='left'>¯</entry> | |
| 2974 | <entry align='left'>\[rn]</entry> | |
| 2975 | <entry align='left'>overline</entry> | |
| 2976 | <entry align='left'>u203E</entry> | |
| 2977 | <entry align='left'>+</entry> | |
| 2978 | </row> | |
| 2979 | <row> | |
| 2980 | <entry align='left'>_</entry> | |
| 2981 | <entry align='left'>\[ru]</entry> | |
| 2982 | <entry align='left'>--- </entry> | |
| 2983 | <entry align='left'>---</entry> | |
| 2984 | <entry align='left'>baseline rule +</entry> | |
| 2985 | </row> | |
| 2986 | <row> | |
| 2987 | <entry align='left'>¦</entry> | |
| 2988 | <entry align='left'>\[bb]</entry> | |
| 2989 | <entry align='left'>brokenbar</entry> | |
| 2990 | <entry align='left'>u00A6</entry> | |
| 2991 | <entry align='left'></entry> | |
| 2992 | </row> | |
| 2993 | <row> | |
| 2994 | <entry align='left'>/</entry> | |
| 2995 | <entry align='left'>\[sl]</entry> | |
| 2996 | <entry align='left'>slash </entry> | |
| 2997 | <entry align='left'>u002F</entry> | |
| 2998 | <entry align='left'>+</entry> | |
| 2999 | </row> | |
| 3000 | <row> | |
| 3001 | <entry align='left'>\</entry> | |
| 3002 | <entry align='left'>\[rs]</entry> | |
| 3003 | <entry align='left'>backslash</entry> | |
| 3004 | <entry align='left'>u005C</entry> | |
| 3005 | <entry align='left'>reverse solidus</entry> | |
| 3006 | </row> | |
| 3007 | </tbody> | |
| 3008 | </tgroup> | |
| 3009 | </informaltable> | |
| 3010 | ||
| 3011 | ||
| 3012 | ||
| 3013 | <para>Use `<emphasis remap='CW'>\[radicalex]</emphasis>', not `<emphasis remap='CW'>\[overline]</emphasis>', for | |
| 3014 | continuation of square root</para> | |
| 3015 | ||
| 3016 | ||
| 3017 | <para><emphasis remap='I'>Text markers</emphasis></para> | |
| 3018 | ||
| 3019 | <informaltable pgwide='1' frame='none'> | |
| 3020 | <tgroup cols='5' align='center'> | |
| 3021 | <colspec colname='c1'/> | |
| 3022 | <colspec colname='c2'/> | |
| 3023 | <colspec colname='c3'/> | |
| 3024 | <colspec colname='c4'/> | |
| 3025 | <colspec colname='c5'/> | |
| 3026 | <tbody> | |
| 3027 | <row rowsep='1'> | |
| 3028 | <entry align='left'>Output</entry> | |
| 3029 | <entry align='left'>Input</entry> | |
| 3030 | <entry align='left'>PostScript</entry> | |
| 3031 | <entry align='left'>Unicode</entry> | |
| 3032 | <entry align='left'>Notes</entry> | |
| 3033 | </row> | |
| 3034 | <row> | |
| 3035 | <entry align='left'>○</entry> | |
| 3036 | <entry align='left'>\[ci]</entry> | |
| 3037 | <entry align='left'>circle </entry> | |
| 3038 | <entry align='left'>u25CB</entry> | |
| 3039 | <entry align='left'>+</entry> | |
| 3040 | </row> | |
| 3041 | <row> | |
| 3042 | <entry align='left'>•</entry> | |
| 3043 | <entry align='left'>\[bu]</entry> | |
| 3044 | <entry align='left'>bullet </entry> | |
| 3045 | <entry align='left'>u2022</entry> | |
| 3046 | <entry align='left'>+</entry> | |
| 3047 | </row> | |
| 3048 | <row> | |
| 3049 | <entry align='left'>‡</entry> | |
| 3050 | <entry align='left'>\[dd]</entry> | |
| 3051 | <entry align='left'>daggerdbl</entry> | |
| 3052 | <entry align='left'>u2021</entry> | |
| 3053 | <entry align='left'>double dagger sign +</entry> | |
| 3054 | </row> | |
| 3055 | <row> | |
| 3056 | <entry align='left'>†</entry> | |
| 3057 | <entry align='left'>\[dg]</entry> | |
| 3058 | <entry align='left'>dagger </entry> | |
| 3059 | <entry align='left'>u2020</entry> | |
| 3060 | <entry align='left'>+</entry> | |
| 3061 | </row> | |
| 3062 | <row> | |
| 3063 | <entry align='left'>◊</entry> | |
| 3064 | <entry align='left'>\[lz]</entry> | |
| 3065 | <entry align='left'>lozenge </entry> | |
| 3066 | <entry align='left'>u25CA</entry> | |
| 3067 | <entry align='left'></entry> | |
| 3068 | </row> | |
| 3069 | <row> | |
| 3070 | <entry align='left'>▪</entry> | |
| 3071 | <entry align='left'>\[sq]</entry> | |
| 3072 | <entry align='left'>uni25A1 </entry> | |
| 3073 | <entry align='left'>u25A1</entry> | |
| 3074 | <entry align='left'>white square +</entry> | |
| 3075 | </row> | |
| 3076 | <row> | |
| 3077 | <entry align='left'>¶</entry> | |
| 3078 | <entry align='left'>\[ps]</entry> | |
| 3079 | <entry align='left'>paragraph</entry> | |
| 3080 | <entry align='left'>u00B6</entry> | |
| 3081 | <entry align='left'></entry> | |
| 3082 | </row> | |
| 3083 | <row> | |
| 3084 | <entry align='left'>§</entry> | |
| 3085 | <entry align='left'>\[sc]</entry> | |
| 3086 | <entry align='left'>section </entry> | |
| 3087 | <entry align='left'>u00A7</entry> | |
| 3088 | <entry align='left'>+</entry> | |
| 3089 | </row> | |
| 3090 | <row> | |
| 3091 | <entry align='left'>&lh;</entry> | |
| 3092 | <entry align='left'>\[lh]</entry> | |
| 3093 | <entry align='left'>uni261C </entry> | |
| 3094 | <entry align='left'>u261C</entry> | |
| 3095 | <entry align='left'>hand pointing left +</entry> | |
| 3096 | </row> | |
| 3097 | <row> | |
| 3098 | <entry align='left'>&rh;</entry> | |
| 3099 | <entry align='left'>\[rh]</entry> | |
| 3100 | <entry align='left'>a14 </entry> | |
| 3101 | <entry align='left'>u261E</entry> | |
| 3102 | <entry align='left'>hand pointing right +</entry> | |
| 3103 | </row> | |
| 3104 | <row> | |
| 3105 | <entry align='left'>@</entry> | |
| 3106 | <entry align='left'>\[at]</entry> | |
| 3107 | <entry align='left'>at </entry> | |
| 3108 | <entry align='left'>u0040</entry> | |
| 3109 | <entry align='left'></entry> | |
| 3110 | </row> | |
| 3111 | <row> | |
| 3112 | <entry align='left'>#</entry> | |
| 3113 | <entry align='left'>\[sh]</entry> | |
| 3114 | <entry align='left'>numbersign</entry> | |
| 3115 | <entry align='left'>u0023</entry> | |
| 3116 | <entry align='left'></entry> | |
| 3117 | </row> | |
| 3118 | <row> | |
| 3119 | <entry align='left'>&CR;</entry> | |
| 3120 | <entry align='left'>\[CR]</entry> | |
| 3121 | <entry align='left'>carriagereturn</entry> | |
| 3122 | <entry align='left'>u21B5</entry> | |
| 3123 | <entry align='left'></entry> | |
| 3124 | </row> | |
| 3125 | <row> | |
| 3126 | <entry align='left'>✓</entry> | |
| 3127 | <entry align='left'>\[OK]</entry> | |
| 3128 | <entry align='left'>a19 </entry> | |
| 3129 | <entry align='left'>u2713</entry> | |
| 3130 | <entry align='left'>check mark, tick</entry> | |
| 3131 | </row> | |
| 3132 | </tbody> | |
| 3133 | </tgroup> | |
| 3134 | </informaltable> | |
| 3135 | ||
| 3136 | ||
| 3137 | ||
| 3138 | ||
| 3139 | <para><emphasis remap='I'>Legal Symbols</emphasis></para> | |
| 3140 | ||
| 3141 | <informaltable pgwide='1' frame='none'> | |
| 3142 | <tgroup cols='5' align='center'> | |
| 3143 | <colspec colname='c1'/> | |
| 3144 | <colspec colname='c2'/> | |
| 3145 | <colspec colname='c3'/> | |
| 3146 | <colspec colname='c4'/> | |
| 3147 | <colspec colname='c5'/> | |
| 3148 | <tbody> | |
| 3149 | <row rowsep='1'> | |
| 3150 | <entry align='left'>Output</entry> | |
| 3151 | <entry align='left'>Input</entry> | |
| 3152 | <entry align='left'>PostScript</entry> | |
| 3153 | <entry align='left'>Unicode</entry> | |
| 3154 | <entry align='left'>Notes</entry> | |
| 3155 | </row> | |
| 3156 | <row> | |
| 3157 | <entry align='left'>©</entry> | |
| 3158 | <entry align='left'>\[co]</entry> | |
| 3159 | <entry align='left'>copyright</entry> | |
| 3160 | <entry align='left'>u00A9</entry> | |
| 3161 | <entry align='left'>+</entry> | |
| 3162 | </row> | |
| 3163 | <row> | |
| 3164 | <entry align='left'>™</entry> | |
| 3165 | <entry align='left'>\[rg]</entry> | |
| 3166 | <entry align='left'>registered</entry> | |
| 3167 | <entry align='left'>u00AE</entry> | |
| 3168 | <entry align='left'>+</entry> | |
| 3169 | </row> | |
| 3170 | <row> | |
| 3171 | <entry align='left'>™</entry> | |
| 3172 | <entry align='left'>\[tm]</entry> | |
| 3173 | <entry align='left'>trademark</entry> | |
| 3174 | <entry align='left'>u2122</entry> | |
| 3175 | <entry align='left'></entry> | |
| 3176 | </row> | |
| 3177 | <row> | |
| 3178 | <entry align='left'>☎</entry> | |
| 3179 | <entry align='left'>\[bs]</entry> | |
| 3180 | <entry align='left'>--- </entry> | |
| 3181 | <entry align='left'>---</entry> | |
| 3182 | <entry align='left'>AT&T Bell Labs logo +</entry> | |
| 3183 | </row> | |
| 3184 | </tbody> | |
| 3185 | </tgroup> | |
| 3186 | </informaltable> | |
| 3187 | ||
| 3188 | ||
| 3189 | ||
| 3190 | <para>The Bell Labs logo is not supported in groff.</para> | |
| 3191 | ||
| 3192 | ||
| 3193 | <para><emphasis remap='I'>Currency symbols</emphasis></para> | |
| 3194 | ||
| 3195 | <informaltable pgwide='1' frame='none'> | |
| 3196 | <tgroup cols='5' align='center'> | |
| 3197 | <colspec colname='c1'/> | |
| 3198 | <colspec colname='c2'/> | |
| 3199 | <colspec colname='c3'/> | |
| 3200 | <colspec colname='c4'/> | |
| 3201 | <colspec colname='c5'/> | |
| 3202 | <tbody> | |
| 3203 | <row rowsep='1'> | |
| 3204 | <entry align='left'>Output </entry> | |
| 3205 | <entry align='left'>Input</entry> | |
| 3206 | <entry align='left'>PostScript</entry> | |
| 3207 | <entry align='left'>Unicode</entry> | |
| 3208 | <entry align='left'>Notes</entry> | |
| 3209 | </row> | |
| 3210 | <row> | |
| 3211 | <entry align='left'>$</entry> | |
| 3212 | <entry align='left'>\[Do]</entry> | |
| 3213 | <entry align='left'>dollar </entry> | |
| 3214 | <entry align='left'>u0024</entry> | |
| 3215 | <entry align='left'></entry> | |
| 3216 | </row> | |
| 3217 | <row> | |
| 3218 | <entry align='left'>¢</entry> | |
| 3219 | <entry align='left'>\[ct]</entry> | |
| 3220 | <entry align='left'>cent </entry> | |
| 3221 | <entry align='left'>u00A2</entry> | |
| 3222 | <entry align='left'>+</entry> | |
| 3223 | </row> | |
| 3224 | <row> | |
| 3225 | <entry align='left'>€</entry> | |
| 3226 | <entry align='left'>\[eu]</entry> | |
| 3227 | <entry align='left'>--- </entry> | |
| 3228 | <entry align='left'>u20AC</entry> | |
| 3229 | <entry align='left'>official Euro symbol</entry> | |
| 3230 | </row> | |
| 3231 | <row> | |
| 3232 | <entry align='left'>€</entry> | |
| 3233 | <entry align='left'>\[Eu]</entry> | |
| 3234 | <entry align='left'>Euro </entry> | |
| 3235 | <entry align='left'>u20AC</entry> | |
| 3236 | <entry align='left'>font-specific Euro glyph variant</entry> | |
| 3237 | </row> | |
| 3238 | <row> | |
| 3239 | <entry align='left'>¥</entry> | |
| 3240 | <entry align='left'>\[Ye]</entry> | |
| 3241 | <entry align='left'>yen </entry> | |
| 3242 | <entry align='left'>u00A5</entry> | |
| 3243 | <entry align='left'></entry> | |
| 3244 | </row> | |
| 3245 | <row> | |
| 3246 | <entry align='left'>£</entry> | |
| 3247 | <entry align='left'>\[Po]</entry> | |
| 3248 | <entry align='left'>sterling</entry> | |
| 3249 | <entry align='left'>u00A3</entry> | |
| 3250 | <entry align='left'>British currency sign</entry> | |
| 3251 | </row> | |
| 3252 | <row> | |
| 3253 | <entry align='left'>¤</entry> | |
| 3254 | <entry align='left'>\[Cs]</entry> | |
| 3255 | <entry align='left'>currency</entry> | |
| 3256 | <entry align='left'>u00A4</entry> | |
| 3257 | <entry align='left'>Scandinavian currency sign</entry> | |
| 3258 | </row> | |
| 3259 | <row> | |
| 3260 | <entry align='left'>ƒ</entry> | |
| 3261 | <entry align='left'>\[Fn]</entry> | |
| 3262 | <entry align='left'>florin </entry> | |
| 3263 | <entry align='left'>u0192</entry> | |
| 3264 | <entry align='left'>Dutch currency sign</entry> | |
| 3265 | </row> | |
| 3266 | </tbody> | |
| 3267 | </tgroup> | |
| 3268 | </informaltable> | |
| 3269 | ||
| 3270 | ||
| 3271 | ||
| 3272 | ||
| 3273 | <para><emphasis remap='I'>Units</emphasis></para> | |
| 3274 | ||
| 3275 | <informaltable pgwide='1' frame='none'> | |
| 3276 | <tgroup cols='5' align='center'> | |
| 3277 | <colspec colname='c1'/> | |
| 3278 | <colspec colname='c2'/> | |
| 3279 | <colspec colname='c3'/> | |
| 3280 | <colspec colname='c4'/> | |
| 3281 | <colspec colname='c5'/> | |
| 3282 | <tbody> | |
| 3283 | <row rowsep='1'> | |
| 3284 | <entry align='left'>Output </entry> | |
| 3285 | <entry align='left'>Input</entry> | |
| 3286 | <entry align='left'>PostScript</entry> | |
| 3287 | <entry align='left'>Unicode</entry> | |
| 3288 | <entry align='left'>Notes</entry> | |
| 3289 | </row> | |
| 3290 | <row> | |
| 3291 | <entry align='left'>°</entry> | |
| 3292 | <entry align='left'>\[de]</entry> | |
| 3293 | <entry align='left'>degree </entry> | |
| 3294 | <entry align='left'>u00B0</entry> | |
| 3295 | <entry align='left'>+</entry> | |
| 3296 | </row> | |
| 3297 | <row> | |
| 3298 | <entry align='left'>‰</entry> | |
| 3299 | <entry align='left'>\[%0]</entry> | |
| 3300 | <entry align='left'>perthousand</entry> | |
| 3301 | <entry align='left'>u2030</entry> | |
| 3302 | <entry align='left'>per thousand, per mille sign</entry> | |
| 3303 | </row> | |
| 3304 | <row> | |
| 3305 | <entry align='left'>′</entry> | |
| 3306 | <entry align='left'>\[fm]</entry> | |
| 3307 | <entry align='left'>minute </entry> | |
| 3308 | <entry align='left'>u2032</entry> | |
| 3309 | <entry align='left'>footmark, prime +</entry> | |
| 3310 | </row> | |
| 3311 | <row> | |
| 3312 | <entry align='left'>″</entry> | |
| 3313 | <entry align='left'>\[sd]</entry> | |
| 3314 | <entry align='left'>second </entry> | |
| 3315 | <entry align='left'>u2033</entry> | |
| 3316 | <entry align='left'></entry> | |
| 3317 | </row> | |
| 3318 | <row> | |
| 3319 | <entry align='left'>µ</entry> | |
| 3320 | <entry align='left'>\[mc]</entry> | |
| 3321 | <entry align='left'>mu </entry> | |
| 3322 | <entry align='left'>u00B5</entry> | |
| 3323 | <entry align='left'>micro sign</entry> | |
| 3324 | </row> | |
| 3325 | <row> | |
| 3326 | <entry align='left'>ª</entry> | |
| 3327 | <entry align='left'>\[Of]</entry> | |
| 3328 | <entry align='left'>ordfeminine</entry> | |
| 3329 | <entry align='left'>u00AA</entry> | |
| 3330 | <entry align='left'></entry> | |
| 3331 | </row> | |
| 3332 | <row> | |
| 3333 | <entry align='left'>º</entry> | |
| 3334 | <entry align='left'>\[Om]</entry> | |
| 3335 | <entry align='left'>ordmasculine</entry> | |
| 3336 | <entry align='left'>u00BA</entry> | |
| 3337 | <entry align='left'></entry> | |
| 3338 | </row> | |
| 3339 | </tbody> | |
| 3340 | </tgroup> | |
| 3341 | </informaltable> | |
| 3342 | ||
| 3343 | ||
| 3344 | ||
| 3345 | ||
| 3346 | <para><emphasis remap='I'>Logical Symbols</emphasis></para> | |
| 3347 | ||
| 3348 | <informaltable pgwide='1' frame='none'> | |
| 3349 | <tgroup cols='5' align='center'> | |
| 3350 | <colspec colname='c1'/> | |
| 3351 | <colspec colname='c2'/> | |
| 3352 | <colspec colname='c3'/> | |
| 3353 | <colspec colname='c4'/> | |
| 3354 | <colspec colname='c5'/> | |
| 3355 | <tbody> | |
| 3356 | <row rowsep='1'> | |
| 3357 | <entry align='left'>Output </entry> | |
| 3358 | <entry align='left'>Input</entry> | |
| 3359 | <entry align='left'>PostScript</entry> | |
| 3360 | <entry align='left'>Unicode</entry> | |
| 3361 | <entry align='left'>Notes</entry> | |
| 3362 | </row> | |
| 3363 | <row> | |
| 3364 | <entry align='left'>∧</entry> | |
| 3365 | <entry align='left'>\[AN]</entry> | |
| 3366 | <entry align='left'>logicaland</entry> | |
| 3367 | <entry align='left'>u2227</entry> | |
| 3368 | <entry align='left'></entry> | |
| 3369 | </row> | |
| 3370 | <row> | |
| 3371 | <entry align='left'>∨</entry> | |
| 3372 | <entry align='left'>\[OR]</entry> | |
| 3373 | <entry align='left'>logicalor</entry> | |
| 3374 | <entry align='left'>u2228</entry> | |
| 3375 | <entry align='left'></entry> | |
| 3376 | </row> | |
| 3377 | <row> | |
| 3378 | <entry align='left'>¬</entry> | |
| 3379 | <entry align='left'>\[no]</entry> | |
| 3380 | <entry align='left'>logicalnot</entry> | |
| 3381 | <entry align='left'>u00AC</entry> | |
| 3382 | <entry align='left'>+</entry> | |
| 3383 | </row> | |
| 3384 | <row> | |
| 3385 | <entry align='left'>¬</entry> | |
| 3386 | <entry align='left'>\[tno]</entry> | |
| 3387 | <entry align='left'>logicalnot</entry> | |
| 3388 | <entry align='left'>u00AC</entry> | |
| 3389 | <entry align='left'>text variant of `no'</entry> | |
| 3390 | </row> | |
| 3391 | <row> | |
| 3392 | <entry align='left'>∃</entry> | |
| 3393 | <entry align='left'>\[te]</entry> | |
| 3394 | <entry align='left'>existential</entry> | |
| 3395 | <entry align='left'>u2203</entry> | |
| 3396 | <entry align='left'>there exists</entry> | |
| 3397 | </row> | |
| 3398 | <row> | |
| 3399 | <entry align='left'>∀</entry> | |
| 3400 | <entry align='left'>\[fa]</entry> | |
| 3401 | <entry align='left'>universal</entry> | |
| 3402 | <entry align='left'>u2200</entry> | |
| 3403 | <entry align='left'>for all</entry> | |
| 3404 | </row> | |
| 3405 | <row> | |
| 3406 | <entry align='left'>϶</entry> | |
| 3407 | <entry align='left'>\[st]</entry> | |
| 3408 | <entry align='left'>suchthat</entry> | |
| 3409 | <entry align='left'>u220B</entry> | |
| 3410 | <entry align='left'></entry> | |
| 3411 | </row> | |
| 3412 | <row> | |
| 3413 | <entry align='left'>∴</entry> | |
| 3414 | <entry align='left'>\[3d]</entry> | |
| 3415 | <entry align='left'>therefore</entry> | |
| 3416 | <entry align='left'>u2234</entry> | |
| 3417 | <entry align='left'></entry> | |
| 3418 | </row> | |
| 3419 | <row> | |
| 3420 | <entry align='left'>∴</entry> | |
| 3421 | <entry align='left'>\[tf]</entry> | |
| 3422 | <entry align='left'>therefore</entry> | |
| 3423 | <entry align='left'>u2234</entry> | |
| 3424 | <entry align='left'></entry> | |
| 3425 | </row> | |
| 3426 | </tbody> | |
| 3427 | </tgroup> | |
| 3428 | </informaltable> | |
| 3429 | ||
| 3430 | ||
| 3431 | ||
| 3432 | ||
| 3433 | <para><emphasis remap='I'>Mathematical Symbols</emphasis></para> | |
| 3434 | ||
| 3435 | <informaltable pgwide='1' frame='none'> | |
| 3436 | <tgroup cols='5' align='center'> | |
| 3437 | <colspec colname='c1'/> | |
| 3438 | <colspec colname='c2'/> | |
| 3439 | <colspec colname='c3'/> | |
| 3440 | <colspec colname='c4'/> | |
| 3441 | <colspec colname='c5'/> | |
| 3442 | <tbody> | |
| 3443 | <row rowsep='1'> | |
| 3444 | <entry align='left'>Output </entry> | |
| 3445 | <entry align='left'>Input</entry> | |
| 3446 | <entry align='left'>PostScript</entry> | |
| 3447 | <entry align='left'>Unicode</entry> | |
| 3448 | <entry align='left'>Notes</entry> | |
| 3449 | <entry align='left'></entry> | |
| 3450 | </row> | |
| 3451 | <row> | |
| 3452 | <entry align='left'>½</entry> | |
| 3453 | <entry align='left'>\[12]</entry> | |
| 3454 | <entry align='left'>onehalf </entry> | |
| 3455 | <entry align='left'>u00BD "+"</entry> | |
| 3456 | <entry align='left'></entry> | |
| 3457 | <entry align='left'></entry> | |
| 3458 | </row> | |
| 3459 | <row> | |
| 3460 | <entry align='left'>¼</entry> | |
| 3461 | <entry align='left'>\[14]</entry> | |
| 3462 | <entry align='left'>onequarter</entry> | |
| 3463 | <entry align='left'>u00BC "+"</entry> | |
| 3464 | <entry align='left'></entry> | |
| 3465 | <entry align='left'></entry> | |
| 3466 | </row> | |
| 3467 | <row> | |
| 3468 | <entry align='left'>¾</entry> | |
| 3469 | <entry align='left'>\[34]</entry> | |
| 3470 | <entry align='left'>threequarters</entry> | |
| 3471 | <entry align='left'>u00BE "+"</entry> | |
| 3472 | <entry align='left'></entry> | |
| 3473 | <entry align='left'></entry> | |
| 3474 | </row> | |
| 3475 | <row> | |
| 3476 | <entry align='left'>⅛</entry> | |
| 3477 | <entry align='left'>\[18]</entry> | |
| 3478 | <entry align='left'>oneeighth</entry> | |
| 3479 | <entry align='left'>u215B</entry> | |
| 3480 | <entry align='left'></entry> | |
| 3481 | <entry align='left'></entry> | |
| 3482 | </row> | |
| 3483 | <row> | |
| 3484 | <entry align='left'>⅜</entry> | |
| 3485 | <entry align='left'>\[38]</entry> | |
| 3486 | <entry align='left'>threeeighths</entry> | |
| 3487 | <entry align='left'>u215C</entry> | |
| 3488 | <entry align='left'></entry> | |
| 3489 | <entry align='left'></entry> | |
| 3490 | </row> | |
| 3491 | <row> | |
| 3492 | <entry align='left'>⅝</entry> | |
| 3493 | <entry align='left'>\[58]</entry> | |
| 3494 | <entry align='left'>fiveeighths</entry> | |
| 3495 | <entry align='left'>u215D</entry> | |
| 3496 | <entry align='left'></entry> | |
| 3497 | <entry align='left'></entry> | |
| 3498 | </row> | |
| 3499 | <row> | |
| 3500 | <entry align='left'>⅞</entry> | |
| 3501 | <entry align='left'>\[78]</entry> | |
| 3502 | <entry align='left'>seveneighths</entry> | |
| 3503 | <entry align='left'>u215E</entry> | |
| 3504 | <entry align='left'></entry> | |
| 3505 | <entry align='left'></entry> | |
| 3506 | </row> | |
| 3507 | <row> | |
| 3508 | <entry align='left'>¹</entry> | |
| 3509 | <entry align='left'>\[S1]</entry> | |
| 3510 | <entry align='left'>onesuperior</entry> | |
| 3511 | <entry align='left'>u00B9</entry> | |
| 3512 | <entry align='left'></entry> | |
| 3513 | <entry align='left'></entry> | |
| 3514 | </row> | |
| 3515 | <row> | |
| 3516 | <entry align='left'>²</entry> | |
| 3517 | <entry align='left'>\[S2]</entry> | |
| 3518 | <entry align='left'>twosuperior</entry> | |
| 3519 | <entry align='left'>u00B2</entry> | |
| 3520 | <entry align='left'></entry> | |
| 3521 | <entry align='left'></entry> | |
| 3522 | </row> | |
| 3523 | <row> | |
| 3524 | <entry align='left'>³</entry> | |
| 3525 | <entry align='left'>\[S3]</entry> | |
| 3526 | <entry align='left'>threesuperior</entry> | |
| 3527 | <entry align='left'>u00B3</entry> | |
| 3528 | <entry align='left'></entry> | |
| 3529 | <entry align='left'></entry> | |
| 3530 | </row> | |
| 3531 | <row> | |
| 3532 | <entry align='left'></entry> | |
| 3533 | <entry align='left'></entry> | |
| 3534 | <entry align='left'></entry> | |
| 3535 | <entry align='left'></entry> | |
| 3536 | <entry align='left'></entry> | |
| 3537 | <entry align='left'></entry> | |
| 3538 | </row> | |
| 3539 | <row> | |
| 3540 | <entry align='left'>+</entry> | |
| 3541 | <entry align='left'>\[pl]</entry> | |
| 3542 | <entry align='left'>plus </entry> | |
| 3543 | <entry align='left'>u002B</entry> | |
| 3544 | <entry align='left'>plus in special font +</entry> | |
| 3545 | <entry align='left'></entry> | |
| 3546 | </row> | |
| 3547 | <row> | |
| 3548 | <entry align='left'>−</entry> | |
| 3549 | <entry align='left'>\[mi]</entry> | |
| 3550 | <entry align='left'>minus </entry> | |
| 3551 | <entry align='left'>u2212</entry> | |
| 3552 | <entry align='left'>minus in special font +</entry> | |
| 3553 | <entry align='left'></entry> | |
| 3554 | </row> | |
| 3555 | <row> | |
| 3556 | <entry align='left'>∓</entry> | |
| 3557 | <entry align='left'>\[-+]</entry> | |
| 3558 | <entry align='left'>uni2213 </entry> | |
| 3559 | <entry align='left'>u2213</entry> | |
| 3560 | <entry align='left'></entry> | |
| 3561 | <entry align='left'></entry> | |
| 3562 | </row> | |
| 3563 | <row> | |
| 3564 | <entry align='left'>±</entry> | |
| 3565 | <entry align='left'>\[+-]</entry> | |
| 3566 | <entry align='left'>plusminus</entry> | |
| 3567 | <entry align='left'>u00B1</entry> | |
| 3568 | <entry align='left'>+</entry> | |
| 3569 | <entry align='left'></entry> | |
| 3570 | </row> | |
| 3571 | <row> | |
| 3572 | <entry align='left'>±</entry> | |
| 3573 | <entry align='left'>\[t+-]</entry> | |
| 3574 | <entry align='left'>plusminus</entry> | |
| 3575 | <entry align='left'>u00B1</entry> | |
| 3576 | <entry align='left'>text variant of `+-'</entry> | |
| 3577 | <entry align='left'></entry> | |
| 3578 | </row> | |
| 3579 | <row> | |
| 3580 | <entry align='left'>·</entry> | |
| 3581 | <entry align='left'>\[pc]</entry> | |
| 3582 | <entry align='left'>periodcentered</entry> | |
| 3583 | <entry align='left'>u00B7</entry> | |
| 3584 | <entry align='left'></entry> | |
| 3585 | <entry align='left'></entry> | |
| 3586 | </row> | |
| 3587 | <row> | |
| 3588 | <entry align='left'>·</entry> | |
| 3589 | <entry align='left'>\[md]</entry> | |
| 3590 | <entry align='left'>dotmath </entry> | |
| 3591 | <entry align='left'>u22C5</entry> | |
| 3592 | <entry align='left'>multiplication dot</entry> | |
| 3593 | <entry align='left'></entry> | |
| 3594 | </row> | |
| 3595 | <row> | |
| 3596 | <entry align='left'>×</entry> | |
| 3597 | <entry align='left'>\[mu]</entry> | |
| 3598 | <entry align='left'>multiply</entry> | |
| 3599 | <entry align='left'>u00D7</entry> | |
| 3600 | <entry align='left'>+</entry> | |
| 3601 | <entry align='left'></entry> | |
| 3602 | </row> | |
| 3603 | <row> | |
| 3604 | <entry align='left'>™</entry> | |
| 3605 | <entry align='left'>\[tmu]</entry> | |
| 3606 | <entry align='left'>multiply</entry> | |
| 3607 | <entry align='left'>u00D7</entry> | |
| 3608 | <entry align='left'>text variant of `mu'</entry> | |
| 3609 | <entry align='left'></entry> | |
| 3610 | </row> | |
| 3611 | <row> | |
| 3612 | <entry align='left'>⊗</entry> | |
| 3613 | <entry align='left'>\[c*]</entry> | |
| 3614 | <entry align='left'>circlemultiply</entry> | |
| 3615 | <entry align='left'>u2297</entry> | |
| 3616 | <entry align='left'>multiply sign in a circle</entry> | |
| 3617 | <entry align='left'></entry> | |
| 3618 | </row> | |
| 3619 | <row> | |
| 3620 | <entry align='left'>⊕</entry> | |
| 3621 | <entry align='left'>\[c+]</entry> | |
| 3622 | <entry align='left'>circleplus</entry> | |
| 3623 | <entry align='left'>u2295</entry> | |
| 3624 | <entry align='left'>plus in a circle</entry> | |
| 3625 | <entry align='left'></entry> | |
| 3626 | </row> | |
| 3627 | <row> | |
| 3628 | <entry align='left'>÷</entry> | |
| 3629 | <entry align='left'>\[di]</entry> | |
| 3630 | <entry align='left'>divide </entry> | |
| 3631 | <entry align='left'>u00F7</entry> | |
| 3632 | <entry align='left'>division +</entry> | |
| 3633 | <entry align='left'></entry> | |
| 3634 | </row> | |
| 3635 | <row> | |
| 3636 | <entry align='left'>÷</entry> | |
| 3637 | <entry align='left'>\[tdi]</entry> | |
| 3638 | <entry align='left'>divide </entry> | |
| 3639 | <entry align='left'>u00F7</entry> | |
| 3640 | <entry align='left'>text variant of `di'</entry> | |
| 3641 | <entry align='left'></entry> | |
| 3642 | </row> | |
| 3643 | <row> | |
| 3644 | <entry align='left'>―</entry> | |
| 3645 | <entry align='left'>\[f/]</entry> | |
| 3646 | <entry align='left'>fraction</entry> | |
| 3647 | <entry align='left'>u2044</entry> | |
| 3648 | <entry align='left'>bar for fractions</entry> | |
| 3649 | <entry align='left'></entry> | |
| 3650 | </row> | |
| 3651 | <row> | |
| 3652 | <entry align='left'>∗</entry> | |
| 3653 | <entry align='left'>\[**]</entry> | |
| 3654 | <entry align='left'>asteriskmath</entry> | |
| 3655 | <entry align='left'>u2217</entry> | |
| 3656 | <entry align='left'>+</entry> | |
| 3657 | <entry align='left'></entry> | |
| 3658 | </row> | |
| 3659 | <row> | |
| 3660 | <entry align='left'></entry> | |
| 3661 | <entry align='left'></entry> | |
| 3662 | <entry align='left'></entry> | |
| 3663 | <entry align='left'></entry> | |
| 3664 | <entry align='left'></entry> | |
| 3665 | <entry align='left'></entry> | |
| 3666 | </row> | |
| 3667 | <row> | |
| 3668 | <entry align='left'>≤</entry> | |
| 3669 | <entry align='left'>\[<=]</entry> | |
| 3670 | <entry align='left'>lessequal</entry> | |
| 3671 | <entry align='left'>u2264</entry> | |
| 3672 | <entry align='left'>+</entry> | |
| 3673 | <entry align='left'></entry> | |
| 3674 | </row> | |
| 3675 | <row> | |
| 3676 | <entry align='left'>≥</entry> | |
| 3677 | <entry align='left'>\[>=]</entry> | |
| 3678 | <entry align='left'>greaterequal</entry> | |
| 3679 | <entry align='left'>u2265</entry> | |
| 3680 | <entry align='left'>+</entry> | |
| 3681 | <entry align='left'></entry> | |
| 3682 | </row> | |
| 3683 | <row> | |
| 3684 | <entry align='left'>≪</entry> | |
| 3685 | <entry align='left'>\[<<]</entry> | |
| 3686 | <entry align='left'>uni226A </entry> | |
| 3687 | <entry align='left'>u226A</entry> | |
| 3688 | <entry align='left'>much less</entry> | |
| 3689 | <entry align='left'></entry> | |
| 3690 | </row> | |
| 3691 | <row> | |
| 3692 | <entry align='left'>≫</entry> | |
| 3693 | <entry align='left'>\[>>]</entry> | |
| 3694 | <entry align='left'>uni226B </entry> | |
| 3695 | <entry align='left'>u226B</entry> | |
| 3696 | <entry align='left'>much greater</entry> | |
| 3697 | <entry align='left'></entry> | |
| 3698 | </row> | |
| 3699 | <row> | |
| 3700 | <entry align='left'>=</entry> | |
| 3701 | <entry align='left'>\[eq]</entry> | |
| 3702 | <entry align='left'>equal </entry> | |
| 3703 | <entry align='left'>u003D</entry> | |
| 3704 | <entry align='left'>equals in special font +</entry> | |
| 3705 | <entry align='left'></entry> | |
| 3706 | </row> | |
| 3707 | <row> | |
| 3708 | <entry align='left'>≠</entry> | |
| 3709 | <entry align='left'>\[!=]</entry> | |
| 3710 | <entry align='left'>notequal</entry> | |
| 3711 | <entry align='left'>u003D_0338</entry> | |
| 3712 | <entry align='left'>+</entry> | |
| 3713 | <entry align='left'></entry> | |
| 3714 | </row> | |
| 3715 | <row> | |
| 3716 | <entry align='left'>≡</entry> | |
| 3717 | <entry align='left'>\[==]</entry> | |
| 3718 | <entry align='left'>equivalence</entry> | |
| 3719 | <entry align='left'>u2261</entry> | |
| 3720 | <entry align='left'>+</entry> | |
| 3721 | <entry align='left'></entry> | |
| 3722 | </row> | |
| 3723 | <row> | |
| 3724 | <entry align='left'>≢</entry> | |
| 3725 | <entry align='left'>\[ne]</entry> | |
| 3726 | <entry align='left'>uni2262 </entry> | |
| 3727 | <entry align='left'>u2261_0338</entry> | |
| 3728 | <entry align='left'></entry> | |
| 3729 | <entry align='left'></entry> | |
| 3730 | </row> | |
| 3731 | <row> | |
| 3732 | <entry align='left'>≅</entry> | |
| 3733 | <entry align='left'>\[=~]</entry> | |
| 3734 | <entry align='left'>congruent</entry> | |
| 3735 | <entry align='left'>u2245</entry> | |
| 3736 | <entry align='left'>approx. equal</entry> | |
| 3737 | <entry align='left'></entry> | |
| 3738 | </row> | |
| 3739 | <row> | |
| 3740 | <entry align='left'>≈</entry> | |
| 3741 | <entry align='left'>\[|=]</entry> | |
| 3742 | <entry align='left'>uni2243 </entry> | |
| 3743 | <entry align='left'>u2243</entry> | |
| 3744 | <entry align='left'>asymptot. equal to +</entry> | |
| 3745 | <entry align='left'></entry> | |
| 3746 | </row> | |
| 3747 | <row> | |
| 3748 | <entry align='left'>∼</entry> | |
| 3749 | <entry align='left'>\[ap]</entry> | |
| 3750 | <entry align='left'>similar </entry> | |
| 3751 | <entry align='left'>u223C</entry> | |
| 3752 | <entry align='left'>+</entry> | |
| 3753 | <entry align='left'></entry> | |
| 3754 | </row> | |
| 3755 | <row> | |
| 3756 | <entry align='left'>≈</entry> | |
| 3757 | <entry align='left'>\[~~]</entry> | |
| 3758 | <entry align='left'>approxequal</entry> | |
| 3759 | <entry align='left'>u2248</entry> | |
| 3760 | <entry align='left'>almost equal to</entry> | |
| 3761 | <entry align='left'></entry> | |
| 3762 | </row> | |
| 3763 | <row> | |
| 3764 | <entry align='left'>≅</entry> | |
| 3765 | <entry align='left'>\[~=]</entry> | |
| 3766 | <entry align='left'>approxequal</entry> | |
| 3767 | <entry align='left'>u2248</entry> | |
| 3768 | <entry align='left'></entry> | |
| 3769 | <entry align='left'></entry> | |
| 3770 | </row> | |
| 3771 | <row> | |
| 3772 | <entry align='left'>∝</entry> | |
| 3773 | <entry align='left'>\[pt]</entry> | |
| 3774 | <entry align='left'>proportional</entry> | |
| 3775 | <entry align='left'>u221D</entry> | |
| 3776 | <entry align='left'>+</entry> | |
| 3777 | <entry align='left'></entry> | |
| 3778 | </row> | |
| 3779 | <row> | |
| 3780 | <entry align='left'></entry> | |
| 3781 | <entry align='left'></entry> | |
| 3782 | <entry align='left'></entry> | |
| 3783 | <entry align='left'></entry> | |
| 3784 | <entry align='left'></entry> | |
| 3785 | <entry align='left'></entry> | |
| 3786 | </row> | |
| 3787 | <row> | |
| 3788 | <entry align='left'>∅</entry> | |
| 3789 | <entry align='left'>\[es]</entry> | |
| 3790 | <entry align='left'>emptyset</entry> | |
| 3791 | <entry align='left'>u2205</entry> | |
| 3792 | <entry align='left'>+</entry> | |
| 3793 | <entry align='left'></entry> | |
| 3794 | </row> | |
| 3795 | <row> | |
| 3796 | <entry align='left'>∈</entry> | |
| 3797 | <entry align='left'>\[mo]</entry> | |
| 3798 | <entry align='left'>element </entry> | |
| 3799 | <entry align='left'>u2208</entry> | |
| 3800 | <entry align='left'>+</entry> | |
| 3801 | <entry align='left'></entry> | |
| 3802 | </row> | |
| 3803 | <row> | |
| 3804 | <entry align='left'>∉</entry> | |
| 3805 | <entry align='left'>\[nm]</entry> | |
| 3806 | <entry align='left'>notelement</entry> | |
| 3807 | <entry align='left'>u2208_0338</entry> | |
| 3808 | <entry align='left'></entry> | |
| 3809 | <entry align='left'></entry> | |
| 3810 | </row> | |
| 3811 | <row> | |
| 3812 | <entry align='left'>⊂</entry> | |
| 3813 | <entry align='left'>\[sb]</entry> | |
| 3814 | <entry align='left'>propersubset</entry> | |
| 3815 | <entry align='left'>u2282</entry> | |
| 3816 | <entry align='left'>+</entry> | |
| 3817 | <entry align='left'></entry> | |
| 3818 | </row> | |
| 3819 | <row> | |
| 3820 | <entry align='left'>⊄</entry> | |
| 3821 | <entry align='left'>\[nb]</entry> | |
| 3822 | <entry align='left'>notsubset</entry> | |
| 3823 | <entry align='left'>u2282_0338</entry> | |
| 3824 | <entry align='left'></entry> | |
| 3825 | <entry align='left'></entry> | |
| 3826 | </row> | |
| 3827 | <row> | |
| 3828 | <entry align='left'>⊃</entry> | |
| 3829 | <entry align='left'>\[sp]</entry> | |
| 3830 | <entry align='left'>propersuperset</entry> | |
| 3831 | <entry align='left'>u2283</entry> | |
| 3832 | <entry align='left'>+</entry> | |
| 3833 | <entry align='left'></entry> | |
| 3834 | </row> | |
| 3835 | <row> | |
| 3836 | <entry align='left'>⊅</entry> | |
| 3837 | <entry align='left'>\[nc]</entry> | |
| 3838 | <entry align='left'>uni2285 </entry> | |
| 3839 | <entry align='left'>u2283_0338</entry> | |
| 3840 | <entry align='left'>not superset</entry> | |
| 3841 | <entry align='left'></entry> | |
| 3842 | </row> | |
| 3843 | <row> | |
| 3844 | <entry align='left'>⊆</entry> | |
| 3845 | <entry align='left'>\[ib]</entry> | |
| 3846 | <entry align='left'>reflexsubset</entry> | |
| 3847 | <entry align='left'>u2286</entry> | |
| 3848 | <entry align='left'>+</entry> | |
| 3849 | <entry align='left'></entry> | |
| 3850 | </row> | |
| 3851 | <row> | |
| 3852 | <entry align='left'>⊇</entry> | |
| 3853 | <entry align='left'>\[ip]</entry> | |
| 3854 | <entry align='left'>reflexsuperset</entry> | |
| 3855 | <entry align='left'>u2287</entry> | |
| 3856 | <entry align='left'>+</entry> | |
| 3857 | <entry align='left'></entry> | |
| 3858 | </row> | |
| 3859 | <row> | |
| 3860 | <entry align='left'>∩</entry> | |
| 3861 | <entry align='left'>\[ca]</entry> | |
| 3862 | <entry align='left'>intersection</entry> | |
| 3863 | <entry align='left'>u2229</entry> | |
| 3864 | <entry align='left'>intersection, cap +</entry> | |
| 3865 | <entry align='left'></entry> | |
| 3866 | </row> | |
| 3867 | <row> | |
| 3868 | <entry align='left'>∪</entry> | |
| 3869 | <entry align='left'>\[cu]</entry> | |
| 3870 | <entry align='left'>union </entry> | |
| 3871 | <entry align='left'>u222A</entry> | |
| 3872 | <entry align='left'>union, cup +</entry> | |
| 3873 | <entry align='left'></entry> | |
| 3874 | </row> | |
| 3875 | <row> | |
| 3876 | <entry align='left'></entry> | |
| 3877 | <entry align='left'></entry> | |
| 3878 | <entry align='left'></entry> | |
| 3879 | <entry align='left'></entry> | |
| 3880 | <entry align='left'></entry> | |
| 3881 | <entry align='left'></entry> | |
| 3882 | </row> | |
| 3883 | <row> | |
| 3884 | <entry align='left'>∠</entry> | |
| 3885 | <entry align='left'>\[/_] </entry> | |
| 3886 | <entry align='left'>angle </entry> | |
| 3887 | <entry align='left'>u2220</entry> | |
| 3888 | <entry align='left'></entry> | |
| 3889 | <entry align='left'></entry> | |
| 3890 | </row> | |
| 3891 | <row> | |
| 3892 | <entry align='left'>⊥</entry> | |
| 3893 | <entry align='left'>\[pp] </entry> | |
| 3894 | <entry align='left'>perpendicular</entry> | |
| 3895 | <entry align='left'>u22A5</entry> | |
| 3896 | <entry align='left'></entry> | |
| 3897 | <entry align='left'></entry> | |
| 3898 | </row> | |
| 3899 | <row> | |
| 3900 | <entry align='left'>∫</entry> | |
| 3901 | <entry align='left'>\[is] </entry> | |
| 3902 | <entry align='left'>integral</entry> | |
| 3903 | <entry align='left'>u222B</entry> | |
| 3904 | <entry align='left'>+</entry> | |
| 3905 | <entry align='left'></entry> | |
| 3906 | </row> | |
| 3907 | <row> | |
| 3908 | <entry align='left'>∫</entry> | |
| 3909 | <entry align='left'>\[integral]</entry> | |
| 3910 | <entry align='left'>integral</entry> | |
| 3911 | <entry align='left'>u222B</entry> | |
| 3912 | <entry align='left'>***</entry> | |
| 3913 | <entry align='left'></entry> | |
| 3914 | </row> | |
| 3915 | <row> | |
| 3916 | <entry align='left'>∑</entry> | |
| 3917 | <entry align='left'>\[sum]</entry> | |
| 3918 | <entry align='left'></entry> | |
| 3919 | <entry align='left'>summation</entry> | |
| 3920 | <entry align='left'>u2211</entry> | |
| 3921 | <entry align='left'>***</entry> | |
| 3922 | </row> | |
| 3923 | <row> | |
| 3924 | <entry align='left'>∏</entry> | |
| 3925 | <entry align='left'>\[product]</entry> | |
| 3926 | <entry align='left'>product </entry> | |
| 3927 | <entry align='left'>u220F</entry> | |
| 3928 | <entry align='left'>***</entry> | |
| 3929 | <entry align='left'></entry> | |
| 3930 | </row> | |
| 3931 | <row> | |
| 3932 | <entry align='left'>∐</entry> | |
| 3933 | <entry align='left'>\[coproduct]</entry> | |
| 3934 | <entry align='left'>uni2210 </entry> | |
| 3935 | <entry align='left'>u2210</entry> | |
| 3936 | <entry align='left'>***</entry> | |
| 3937 | <entry align='left'></entry> | |
| 3938 | </row> | |
| 3939 | <row> | |
| 3940 | <entry align='left'>∇</entry> | |
| 3941 | <entry align='left'>\[gr] </entry> | |
| 3942 | <entry align='left'>gradient</entry> | |
| 3943 | <entry align='left'>u2207</entry> | |
| 3944 | <entry align='left'>+</entry> | |
| 3945 | <entry align='left'></entry> | |
| 3946 | </row> | |
| 3947 | <row> | |
| 3948 | <entry align='left'>√</entry> | |
| 3949 | <entry align='left'>\[sr] </entry> | |
| 3950 | <entry align='left'>radical </entry> | |
| 3951 | <entry align='left'>u221A</entry> | |
| 3952 | <entry align='left'>square root +</entry> | |
| 3953 | <entry align='left'></entry> | |
| 3954 | </row> | |
| 3955 | <row> | |
| 3956 | <entry align='left'>▪</entry> | |
| 3957 | <entry align='left'>\[sqrt]</entry> | |
| 3958 | <entry align='left'>radical </entry> | |
| 3959 | <entry align='left'>u221A</entry> | |
| 3960 | <entry align='left'>***</entry> | |
| 3961 | <entry align='left'></entry> | |
| 3962 | </row> | |
| 3963 | <row> | |
| 3964 | <entry align='left'>&radicalex;</entry> | |
| 3965 | <entry align='left'>\[radicalex]</entry> | |
| 3966 | <entry align='left'>radicalex</entry> | |
| 3967 | <entry align='left'>---</entry> | |
| 3968 | <entry align='left'>square root continuation</entry> | |
| 3969 | <entry align='left'></entry> | |
| 3970 | </row> | |
| 3971 | <row> | |
| 3972 | <entry align='left'>&sqrtex;</entry> | |
| 3973 | <entry align='left'>\[sqrtex]</entry> | |
| 3974 | <entry align='left'>radicalex</entry> | |
| 3975 | <entry align='left'>---</entry> | |
| 3976 | <entry align='left'>***</entry> | |
| 3977 | <entry align='left'></entry> | |
| 3978 | </row> | |
| 3979 | <row> | |
| 3980 | <entry align='left'></entry> | |
| 3981 | <entry align='left'></entry> | |
| 3982 | <entry align='left'></entry> | |
| 3983 | <entry align='left'></entry> | |
| 3984 | <entry align='left'></entry> | |
| 3985 | <entry align='left'></entry> | |
| 3986 | </row> | |
| 3987 | <row> | |
| 3988 | <entry align='left'>&lc;</entry> | |
| 3989 | <entry align='left'>\[lc] </entry> | |
| 3990 | <entry align='left'>uni2308 </entry> | |
| 3991 | <entry align='left'>u2308</entry> | |
| 3992 | <entry align='left'>left ceiling +</entry> | |
| 3993 | <entry align='left'></entry> | |
| 3994 | </row> | |
| 3995 | <row> | |
| 3996 | <entry align='left'>&rc;</entry> | |
| 3997 | <entry align='left'>\[rc] </entry> | |
| 3998 | <entry align='left'>uni2309 </entry> | |
| 3999 | <entry align='left'>u2309</entry> | |
| 4000 | <entry align='left'>right ceiling +</entry> | |
| 4001 | <entry align='left'></entry> | |
| 4002 | </row> | |
| 4003 | <row> | |
| 4004 | <entry align='left'>&lf;</entry> | |
| 4005 | <entry align='left'>\[lf] </entry> | |
| 4006 | <entry align='left'>uni230A </entry> | |
| 4007 | <entry align='left'>u230A</entry> | |
| 4008 | <entry align='left'>left floor +</entry> | |
| 4009 | <entry align='left'></entry> | |
| 4010 | </row> | |
| 4011 | <row> | |
| 4012 | <entry align='left'>&rf;</entry> | |
| 4013 | <entry align='left'>\[rf] </entry> | |
| 4014 | <entry align='left'>uni230B </entry> | |
| 4015 | <entry align='left'>u230B</entry> | |
| 4016 | <entry align='left'>right floor +</entry> | |
| 4017 | <entry align='left'></entry> | |
| 4018 | </row> | |
| 4019 | <row> | |
| 4020 | <entry align='left'></entry> | |
| 4021 | <entry align='left'></entry> | |
| 4022 | <entry align='left'></entry> | |
| 4023 | <entry align='left'></entry> | |
| 4024 | <entry align='left'></entry> | |
| 4025 | <entry align='left'></entry> | |
| 4026 | </row> | |
| 4027 | <row> | |
| 4028 | <entry align='left'>∞</entry> | |
| 4029 | <entry align='left'>\[if] </entry> | |
| 4030 | <entry align='left'>infinity</entry> | |
| 4031 | <entry align='left'>u221E</entry> | |
| 4032 | <entry align='left'>+</entry> | |
| 4033 | <entry align='left'></entry> | |
| 4034 | </row> | |
| 4035 | <row> | |
| 4036 | <entry align='left'>ℵ</entry> | |
| 4037 | <entry align='left'>\[Ah] </entry> | |
| 4038 | <entry align='left'>aleph </entry> | |
| 4039 | <entry align='left'>u2135</entry> | |
| 4040 | <entry align='left'></entry> | |
| 4041 | <entry align='left'></entry> | |
| 4042 | </row> | |
| 4043 | <row> | |
| 4044 | <entry align='left'>ℑ</entry> | |
| 4045 | <entry align='left'>\[Im] </entry> | |
| 4046 | <entry align='left'>Ifraktur</entry> | |
| 4047 | <entry align='left'>u2111</entry> | |
| 4048 | <entry align='left'>Gothic I, imaginary</entry> | |
| 4049 | <entry align='left'></entry> | |
| 4050 | </row> | |
| 4051 | <row> | |
| 4052 | <entry align='left'>ℜ</entry> | |
| 4053 | <entry align='left'>\[Re] </entry> | |
| 4054 | <entry align='left'>Rfraktur</entry> | |
| 4055 | <entry align='left'>u211C</entry> | |
| 4056 | <entry align='left'>Gothic R, real</entry> | |
| 4057 | <entry align='left'></entry> | |
| 4058 | </row> | |
| 4059 | <row> | |
| 4060 | <entry align='left'>℘</entry> | |
| 4061 | <entry align='left'>\[wp] </entry> | |
| 4062 | <entry align='left'>weierstrass</entry> | |
| 4063 | <entry align='left'>u2118</entry> | |
| 4064 | <entry align='left'>Weierstrass p</entry> | |
| 4065 | <entry align='left'></entry> | |
| 4066 | </row> | |
| 4067 | <row> | |
| 4068 | <entry align='left'>∂</entry> | |
| 4069 | <entry align='left'>\[pd] </entry> | |
| 4070 | <entry align='left'>partialdiff</entry> | |
| 4071 | <entry align='left'>u2202</entry> | |
| 4072 | <entry align='left'>partial differentiation +</entry> | |
| 4073 | <entry align='left'></entry> | |
| 4074 | </row> | |
| 4075 | <row> | |
| 4076 | <entry align='left'>ℏ</entry> | |
| 4077 | <entry align='left'>\[-h] </entry> | |
| 4078 | <entry align='left'>uni210F </entry> | |
| 4079 | <entry align='left'>u210F</entry> | |
| 4080 | <entry align='left'>Planck constant / 2pi</entry> | |
| 4081 | <entry align='left'></entry> | |
| 4082 | </row> | |
| 4083 | <row> | |
| 4084 | <entry align='left'>ℏ</entry> | |
| 4085 | <entry align='left'>\[hbar]</entry> | |
| 4086 | <entry align='left'>uni210F </entry> | |
| 4087 | <entry align='left'>u210F</entry> | |
| 4088 | <entry align='left'></entry> | |
| 4089 | <entry align='left'></entry> | |
| 4090 | </row> | |
| 4091 | </tbody> | |
| 4092 | </tgroup> | |
| 4093 | </informaltable> | |
| 4094 | ||
| 4095 | ||
| 4096 | ||
| 4097 | ||
| 4098 | <para><emphasis remap='I'>Greek glyphs</emphasis></para> | |
| 4099 | ||
| 4100 | <para>These glyphs are intended for technical use, not for real Greek; normally, | |
| 4101 | the uppercase letters have upright shape, and the lowercase ones are | |
| 4102 | slanted. | |
| 4103 | ||
| 4104 | There is a problem with the mapping of letter phi to Unicode. | |
| 4105 | ||
| 4106 | Prior to Unicode version 3.0, the difference between U+03C6, GREEK | |
| 4107 | SMALL LETTER PHI, and U+03D5, GREEK PHI SYMBOL, was not clearly described; | |
| 4108 | only the glyph shapes in the Unicode book could be used as a reference. | |
| 4109 | ||
| 4110 | Starting with Unicode 3.0, the reference glyphs have been exchanged and | |
| 4111 | described verbally also: In mathematical context, U+03D5 is the stroked | |
| 4112 | variant and U+03C6 the curly glyph. | |
| 4113 | ||
| 4114 | Unfortunately, most font vendors didn't update their fonts to | |
| 4115 | this (incompatible) change in Unicode. | |
| 4116 | ||
| 4117 | At the time of this writing (January 2006), it is not clear yet whether | |
| 4118 | the Adobe Glyph Names `phi' and `phi1' also change its meaning if used for | |
| 4119 | mathematics, thus compatibility problems are likely to happen – being | |
| 4120 | conservative, groff currently assumes that `phi' in a PostScript symbol | |
| 4121 | font is the stroked version.</para> | |
| 4122 | ||
| 4123 | <para>In groff, symbol `<emphasis remap='CW'>\[*f]</emphasis>' always denotes the stroked version of | |
| 4124 | phi, and `<emphasis remap='CW'>\[+f]</emphasis>' the curly variant.</para> | |
| 4125 | ||
| 4126 | <informaltable pgwide='1' frame='none'> | |
| 4127 | <tgroup cols='5' align='center'> | |
| 4128 | <colspec colname='c1'/> | |
| 4129 | <colspec colname='c2'/> | |
| 4130 | <colspec colname='c3'/> | |
| 4131 | <colspec colname='c4'/> | |
| 4132 | <colspec colname='c5'/> | |
| 4133 | <tbody> | |
| 4134 | <row rowsep='1'> | |
| 4135 | <entry align='left'>Output </entry> | |
| 4136 | <entry align='left'>Input</entry> | |
| 4137 | <entry align='left'>PostScript</entry> | |
| 4138 | <entry align='left'>Unicode</entry> | |
| 4139 | <entry align='left'>Notes</entry> | |
| 4140 | </row> | |
| 4141 | <row> | |
| 4142 | <entry align='left'>&Agr;</entry> | |
| 4143 | <entry align='left'>\[*A]</entry> | |
| 4144 | <entry align='left'>Alpha</entry> | |
| 4145 | <entry align='left'>u0391</entry> | |
| 4146 | <entry align='left'>+</entry> | |
| 4147 | </row> | |
| 4148 | <row> | |
| 4149 | <entry align='left'>&Bgr;</entry> | |
| 4150 | <entry align='left'>\[*B]</entry> | |
| 4151 | <entry align='left'>Beta</entry> | |
| 4152 | <entry align='left'>u0392</entry> | |
| 4153 | <entry align='left'>+</entry> | |
| 4154 | </row> | |
| 4155 | <row> | |
| 4156 | <entry align='left'>&Ggr;</entry> | |
| 4157 | <entry align='left'>\[*G]</entry> | |
| 4158 | <entry align='left'>Gamma</entry> | |
| 4159 | <entry align='left'>u0393</entry> | |
| 4160 | <entry align='left'>+</entry> | |
| 4161 | </row> | |
| 4162 | <row> | |
| 4163 | <entry align='left'>&Dgr;</entry> | |
| 4164 | <entry align='left'>\[*D]</entry> | |
| 4165 | <entry align='left'>Delta</entry> | |
| 4166 | <entry align='left'>u0394</entry> | |
| 4167 | <entry align='left'>+</entry> | |
| 4168 | </row> | |
| 4169 | <row> | |
| 4170 | <entry align='left'>&Egr;</entry> | |
| 4171 | <entry align='left'>\[*E]</entry> | |
| 4172 | <entry align='left'>Epsilon</entry> | |
| 4173 | <entry align='left'>u0395</entry> | |
| 4174 | <entry align='left'>+</entry> | |
| 4175 | </row> | |
| 4176 | <row> | |
| 4177 | <entry align='left'>&Zgr;</entry> | |
| 4178 | <entry align='left'>\[*Z]</entry> | |
| 4179 | <entry align='left'>Zeta</entry> | |
| 4180 | <entry align='left'>u0396</entry> | |
| 4181 | <entry align='left'>+</entry> | |
| 4182 | </row> | |
| 4183 | <row> | |
| 4184 | <entry align='left'>&EEgr;</entry> | |
| 4185 | <entry align='left'>\[*Y]</entry> | |
| 4186 | <entry align='left'>Eta</entry> | |
| 4187 | <entry align='left'>u0397</entry> | |
| 4188 | <entry align='left'>+</entry> | |
| 4189 | </row> | |
| 4190 | <row> | |
| 4191 | <entry align='left'>&THgr;</entry> | |
| 4192 | <entry align='left'>\[*H]</entry> | |
| 4193 | <entry align='left'>Theta</entry> | |
| 4194 | <entry align='left'>u0398</entry> | |
| 4195 | <entry align='left'>+</entry> | |
| 4196 | </row> | |
| 4197 | <row> | |
| 4198 | <entry align='left'>&Igr;</entry> | |
| 4199 | <entry align='left'>\[*I]</entry> | |
| 4200 | <entry align='left'>Iota</entry> | |
| 4201 | <entry align='left'>u0399</entry> | |
| 4202 | <entry align='left'>+</entry> | |
| 4203 | </row> | |
| 4204 | <row> | |
| 4205 | <entry align='left'>&Kgr;</entry> | |
| 4206 | <entry align='left'>\[*K]</entry> | |
| 4207 | <entry align='left'>Kappa</entry> | |
| 4208 | <entry align='left'>u039A</entry> | |
| 4209 | <entry align='left'>+</entry> | |
| 4210 | </row> | |
| 4211 | <row> | |
| 4212 | <entry align='left'>&Lgr;</entry> | |
| 4213 | <entry align='left'>\[*L]</entry> | |
| 4214 | <entry align='left'>Lambda</entry> | |
| 4215 | <entry align='left'>u039B</entry> | |
| 4216 | <entry align='left'>+</entry> | |
| 4217 | </row> | |
| 4218 | <row> | |
| 4219 | <entry align='left'>&Mgr;</entry> | |
| 4220 | <entry align='left'>\[*M]</entry> | |
| 4221 | <entry align='left'>Mu</entry> | |
| 4222 | <entry align='left'>u039C</entry> | |
| 4223 | <entry align='left'>+</entry> | |
| 4224 | </row> | |
| 4225 | <row> | |
| 4226 | <entry align='left'>&Ngr;</entry> | |
| 4227 | <entry align='left'>\[*N]</entry> | |
| 4228 | <entry align='left'>Nu</entry> | |
| 4229 | <entry align='left'>u039D</entry> | |
| 4230 | <entry align='left'>+</entry> | |
| 4231 | </row> | |
| 4232 | <row> | |
| 4233 | <entry align='left'>Ξ</entry> | |
| 4234 | <entry align='left'>\[*C]</entry> | |
| 4235 | <entry align='left'>Xi</entry> | |
| 4236 | <entry align='left'>u039E</entry> | |
| 4237 | <entry align='left'>+</entry> | |
| 4238 | </row> | |
| 4239 | <row> | |
| 4240 | <entry align='left'>&Ogr;</entry> | |
| 4241 | <entry align='left'>\[*O]</entry> | |
| 4242 | <entry align='left'>Omicron</entry> | |
| 4243 | <entry align='left'>u039F</entry> | |
| 4244 | <entry align='left'>+</entry> | |
| 4245 | </row> | |
| 4246 | <row> | |
| 4247 | <entry align='left'>&Pgr;</entry> | |
| 4248 | <entry align='left'>\[*P]</entry> | |
| 4249 | <entry align='left'>Pi</entry> | |
| 4250 | <entry align='left'>u03A0</entry> | |
| 4251 | <entry align='left'>+</entry> | |
| 4252 | </row> | |
| 4253 | <row> | |
| 4254 | <entry align='left'>&Rgr;</entry> | |
| 4255 | <entry align='left'>\[*R]</entry> | |
| 4256 | <entry align='left'>Rho</entry> | |
| 4257 | <entry align='left'>u03A1</entry> | |
| 4258 | <entry align='left'>+</entry> | |
| 4259 | </row> | |
| 4260 | <row> | |
| 4261 | <entry align='left'>&Sgr;</entry> | |
| 4262 | <entry align='left'>\[*S]</entry> | |
| 4263 | <entry align='left'>Sigma</entry> | |
| 4264 | <entry align='left'>u03A3</entry> | |
| 4265 | <entry align='left'>+</entry> | |
| 4266 | </row> | |
| 4267 | <row> | |
| 4268 | <entry align='left'>&Tgr;</entry> | |
| 4269 | <entry align='left'>\[*T]</entry> | |
| 4270 | <entry align='left'>Tau</entry> | |
| 4271 | <entry align='left'>u03A4</entry> | |
| 4272 | <entry align='left'>+</entry> | |
| 4273 | </row> | |
| 4274 | <row> | |
| 4275 | <entry align='left'>&Ugr;</entry> | |
| 4276 | <entry align='left'>\[*U]</entry> | |
| 4277 | <entry align='left'>Upsilon</entry> | |
| 4278 | <entry align='left'>u03A5</entry> | |
| 4279 | <entry align='left'>+</entry> | |
| 4280 | </row> | |
| 4281 | <row> | |
| 4282 | <entry align='left'>&PHgr;</entry> | |
| 4283 | <entry align='left'>\[*F]</entry> | |
| 4284 | <entry align='left'>Phi</entry> | |
| 4285 | <entry align='left'>u03A6</entry> | |
| 4286 | <entry align='left'>+</entry> | |
| 4287 | </row> | |
| 4288 | <row> | |
| 4289 | <entry align='left'>&KHgr;</entry> | |
| 4290 | <entry align='left'>\[*X]</entry> | |
| 4291 | <entry align='left'>Chi</entry> | |
| 4292 | <entry align='left'>u03A7</entry> | |
| 4293 | <entry align='left'>+</entry> | |
| 4294 | </row> | |
| 4295 | <row> | |
| 4296 | <entry align='left'>&PSgr;</entry> | |
| 4297 | <entry align='left'>\[*Q]</entry> | |
| 4298 | <entry align='left'>Psi</entry> | |
| 4299 | <entry align='left'>u03A8</entry> | |
| 4300 | <entry align='left'>+</entry> | |
| 4301 | </row> | |
| 4302 | <row> | |
| 4303 | <entry align='left'>&OHgr;</entry> | |
| 4304 | <entry align='left'>\[*W]</entry> | |
| 4305 | <entry align='left'>Omega</entry> | |
| 4306 | <entry align='left'>u03A9</entry> | |
| 4307 | <entry align='left'>+</entry> | |
| 4308 | </row> | |
| 4309 | <row> | |
| 4310 | <entry align='left'>&agr;</entry> | |
| 4311 | <entry align='left'>\[*a]</entry> | |
| 4312 | <entry align='left'>alpha</entry> | |
| 4313 | <entry align='left'>u03B1</entry> | |
| 4314 | <entry align='left'>+</entry> | |
| 4315 | </row> | |
| 4316 | <row> | |
| 4317 | <entry align='left'>&bgr;</entry> | |
| 4318 | <entry align='left'>\[*b]</entry> | |
| 4319 | <entry align='left'>beta</entry> | |
| 4320 | <entry align='left'>u03B2</entry> | |
| 4321 | <entry align='left'>+</entry> | |
| 4322 | </row> | |
| 4323 | <row> | |
| 4324 | <entry align='left'>&ggr;</entry> | |
| 4325 | <entry align='left'>\[*g]</entry> | |
| 4326 | <entry align='left'>gamma</entry> | |
| 4327 | <entry align='left'>u03B3</entry> | |
| 4328 | <entry align='left'>+</entry> | |
| 4329 | </row> | |
| 4330 | <row> | |
| 4331 | <entry align='left'>&dgr;</entry> | |
| 4332 | <entry align='left'>\[*d]</entry> | |
| 4333 | <entry align='left'>delta</entry> | |
| 4334 | <entry align='left'>u03B4</entry> | |
| 4335 | <entry align='left'>+</entry> | |
| 4336 | </row> | |
| 4337 | <row> | |
| 4338 | <entry align='left'>&egr;</entry> | |
| 4339 | <entry align='left'>\[*e]</entry> | |
| 4340 | <entry align='left'>epsilon</entry> | |
| 4341 | <entry align='left'>u03B5</entry> | |
| 4342 | <entry align='left'>+</entry> | |
| 4343 | </row> | |
| 4344 | <row> | |
| 4345 | <entry align='left'>&zgr;</entry> | |
| 4346 | <entry align='left'>\[*z]</entry> | |
| 4347 | <entry align='left'>zeta</entry> | |
| 4348 | <entry align='left'>u03B6</entry> | |
| 4349 | <entry align='left'>+</entry> | |
| 4350 | </row> | |
| 4351 | <row> | |
| 4352 | <entry align='left'>&eegr;</entry> | |
| 4353 | <entry align='left'>\[*y]</entry> | |
| 4354 | <entry align='left'>eta</entry> | |
| 4355 | <entry align='left'>u03B7</entry> | |
| 4356 | <entry align='left'>+</entry> | |
| 4357 | </row> | |
| 4358 | <row> | |
| 4359 | <entry align='left'>&thgr;</entry> | |
| 4360 | <entry align='left'>\[*h]</entry> | |
| 4361 | <entry align='left'>theta</entry> | |
| 4362 | <entry align='left'>u03B8</entry> | |
| 4363 | <entry align='left'>+</entry> | |
| 4364 | </row> | |
| 4365 | <row> | |
| 4366 | <entry align='left'>&igr;</entry> | |
| 4367 | <entry align='left'>\[*i]</entry> | |
| 4368 | <entry align='left'>iota</entry> | |
| 4369 | <entry align='left'>u03B9</entry> | |
| 4370 | <entry align='left'>+</entry> | |
| 4371 | </row> | |
| 4372 | <row> | |
| 4373 | <entry align='left'>&kgr;</entry> | |
| 4374 | <entry align='left'>\[*k]</entry> | |
| 4375 | <entry align='left'>kappa</entry> | |
| 4376 | <entry align='left'>u03BA</entry> | |
| 4377 | <entry align='left'>+</entry> | |
| 4378 | </row> | |
| 4379 | <row> | |
| 4380 | <entry align='left'>&lgr;</entry> | |
| 4381 | <entry align='left'>\[*l]</entry> | |
| 4382 | <entry align='left'>lambda</entry> | |
| 4383 | <entry align='left'>u03BB</entry> | |
| 4384 | <entry align='left'>+</entry> | |
| 4385 | </row> | |
| 4386 | <row> | |
| 4387 | <entry align='left'>&mgr;</entry> | |
| 4388 | <entry align='left'>\[*m]</entry> | |
| 4389 | <entry align='left'>mu</entry> | |
| 4390 | <entry align='left'>u03BC</entry> | |
| 4391 | <entry align='left'>+</entry> | |
| 4392 | </row> | |
| 4393 | <row> | |
| 4394 | <entry align='left'>&ngr;</entry> | |
| 4395 | <entry align='left'>\[*n]</entry> | |
| 4396 | <entry align='left'>nu</entry> | |
| 4397 | <entry align='left'>u03BD</entry> | |
| 4398 | <entry align='left'>+</entry> | |
| 4399 | </row> | |
| 4400 | <row> | |
| 4401 | <entry align='left'>ξ</entry> | |
| 4402 | <entry align='left'>\[*c]</entry> | |
| 4403 | <entry align='left'>xi</entry> | |
| 4404 | <entry align='left'>u03BE</entry> | |
| 4405 | <entry align='left'>+</entry> | |
| 4406 | </row> | |
| 4407 | <row> | |
| 4408 | <entry align='left'>&ogr;</entry> | |
| 4409 | <entry align='left'>\[*o]</entry> | |
| 4410 | <entry align='left'>omicron</entry> | |
| 4411 | <entry align='left'>u03BF</entry> | |
| 4412 | <entry align='left'>+</entry> | |
| 4413 | </row> | |
| 4414 | <row> | |
| 4415 | <entry align='left'>&pgr;</entry> | |
| 4416 | <entry align='left'>\[*p]</entry> | |
| 4417 | <entry align='left'>pi</entry> | |
| 4418 | <entry align='left'>u03C0</entry> | |
| 4419 | <entry align='left'>+</entry> | |
| 4420 | </row> | |
| 4421 | <row> | |
| 4422 | <entry align='left'>&rgr;</entry> | |
| 4423 | <entry align='left'>\[*r]</entry> | |
| 4424 | <entry align='left'>rho</entry> | |
| 4425 | <entry align='left'>u03C1</entry> | |
| 4426 | <entry align='left'>+</entry> | |
| 4427 | </row> | |
| 4428 | <row> | |
| 4429 | <entry align='left'>&sfgr;</entry> | |
| 4430 | <entry align='left'>\[ts]</entry> | |
| 4431 | <entry align='left'>sigma1</entry> | |
| 4432 | <entry align='left'>u03C2</entry> | |
| 4433 | <entry align='left'>terminal sigma +</entry> | |
| 4434 | </row> | |
| 4435 | <row> | |
| 4436 | <entry align='left'>&sgr;</entry> | |
| 4437 | <entry align='left'>\[*s]</entry> | |
| 4438 | <entry align='left'>sigma</entry> | |
| 4439 | <entry align='left'>u03C3</entry> | |
| 4440 | <entry align='left'>+</entry> | |
| 4441 | </row> | |
| 4442 | <row> | |
| 4443 | <entry align='left'>&tgr;</entry> | |
| 4444 | <entry align='left'>\[*t]</entry> | |
| 4445 | <entry align='left'>tau</entry> | |
| 4446 | <entry align='left'>u03C4</entry> | |
| 4447 | <entry align='left'>+</entry> | |
| 4448 | </row> | |
| 4449 | <row> | |
| 4450 | <entry align='left'>&ugr;</entry> | |
| 4451 | <entry align='left'>\[*u]</entry> | |
| 4452 | <entry align='left'>upsilon</entry> | |
| 4453 | <entry align='left'>u03C5</entry> | |
| 4454 | <entry align='left'>+</entry> | |
| 4455 | </row> | |
| 4456 | <row> | |
| 4457 | <entry align='left'>&phgr;</entry> | |
| 4458 | <entry align='left'>\[*f]</entry> | |
| 4459 | <entry align='left'>phi</entry> | |
| 4460 | <entry align='left'>u03D5</entry> | |
| 4461 | <entry align='left'>(stroked glyph) +</entry> | |
| 4462 | </row> | |
| 4463 | <row> | |
| 4464 | <entry align='left'>&khgr;</entry> | |
| 4465 | <entry align='left'>\[*x]</entry> | |
| 4466 | <entry align='left'>chi</entry> | |
| 4467 | <entry align='left'>u03C7</entry> | |
| 4468 | <entry align='left'>+</entry> | |
| 4469 | </row> | |
| 4470 | <row> | |
| 4471 | <entry align='left'>&psgr;</entry> | |
| 4472 | <entry align='left'>\[*q]</entry> | |
| 4473 | <entry align='left'>psi</entry> | |
| 4474 | <entry align='left'>u03C8</entry> | |
| 4475 | <entry align='left'>+</entry> | |
| 4476 | </row> | |
| 4477 | <row> | |
| 4478 | <entry align='left'>&ohgr;</entry> | |
| 4479 | <entry align='left'>\[*w]</entry> | |
| 4480 | <entry align='left'>omega</entry> | |
| 4481 | <entry align='left'>u03C9</entry> | |
| 4482 | <entry align='left'>+</entry> | |
| 4483 | </row> | |
| 4484 | <row> | |
| 4485 | <entry align='left'>&b.thetas;</entry> | |
| 4486 | <entry align='left'>\[+h]</entry> | |
| 4487 | <entry align='left'>theta1</entry> | |
| 4488 | <entry align='left'>u03D1</entry> | |
| 4489 | <entry align='left'>variant theta</entry> | |
| 4490 | </row> | |
| 4491 | <row> | |
| 4492 | <entry align='left'>&b.phiv;</entry> | |
| 4493 | <entry align='left'>\[+f]</entry> | |
| 4494 | <entry align='left'>phi1</entry> | |
| 4495 | <entry align='left'>u03C6</entry> | |
| 4496 | <entry align='left'>variant phi (curly shape)</entry> | |
| 4497 | </row> | |
| 4498 | <row> | |
| 4499 | <entry align='left'>&b.omega;</entry> | |
| 4500 | <entry align='left'>\[+p]</entry> | |
| 4501 | <entry align='left'>omega1</entry> | |
| 4502 | <entry align='left'>u03D6</entry> | |
| 4503 | <entry align='left'>variant pi, looking like omega</entry> | |
| 4504 | </row> | |
| 4505 | <row> | |
| 4506 | <entry align='left'>&b.epsiv;</entry> | |
| 4507 | <entry align='left'>\[+e]</entry> | |
| 4508 | <entry align='left'>uni03F5</entry> | |
| 4509 | <entry align='left'>u03F5</entry> | |
| 4510 | <entry align='left'>variant epsilon</entry> | |
| 4511 | </row> | |
| 4512 | </tbody> | |
| 4513 | </tgroup> | |
| 4514 | </informaltable> | |
| 4515 | ||
| 4516 | ||
| 4517 | ||
| 4518 | ||
| 4519 | <para><emphasis remap='I'>Card symbols</emphasis></para> | |
| 4520 | ||
| 4521 | <informaltable pgwide='1' frame='none'> | |
| 4522 | <tgroup cols='5' align='center'> | |
| 4523 | <colspec colname='c1'/> | |
| 4524 | <colspec colname='c2'/> | |
| 4525 | <colspec colname='c3'/> | |
| 4526 | <colspec colname='c4'/> | |
| 4527 | <colspec colname='c5'/> | |
| 4528 | <tbody> | |
| 4529 | <row rowsep='1'> | |
| 4530 | <entry align='left'>Output </entry> | |
| 4531 | <entry align='left'>Input </entry> | |
| 4532 | <entry align='left'>PostScript</entry> | |
| 4533 | <entry align='left'>Unicode</entry> | |
| 4534 | <entry align='left'>Notes</entry> | |
| 4535 | </row> | |
| 4536 | <row> | |
| 4537 | <entry align='left'>♣ </entry> | |
| 4538 | <entry align='left'>\[CL] </entry> | |
| 4539 | <entry align='left'>club </entry> | |
| 4540 | <entry align='left'>u2663</entry> | |
| 4541 | <entry align='left'>black club suit</entry> | |
| 4542 | </row> | |
| 4543 | <row> | |
| 4544 | <entry align='left'>♠ </entry> | |
| 4545 | <entry align='left'>\[SP] </entry> | |
| 4546 | <entry align='left'>spade </entry> | |
| 4547 | <entry align='left'>u2660</entry> | |
| 4548 | <entry align='left'>black spade suit</entry> | |
| 4549 | </row> | |
| 4550 | <row> | |
| 4551 | <entry align='left'>♥ </entry> | |
| 4552 | <entry align='left'>\[HE] </entry> | |
| 4553 | <entry align='left'>heart </entry> | |
| 4554 | <entry align='left'>u2665</entry> | |
| 4555 | <entry align='left'>black heart suit</entry> | |
| 4556 | </row> | |
| 4557 | <row> | |
| 4558 | <entry align='left'>੥</entry> | |
| 4559 | <entry align='left'>\[u2661]</entry> | |
| 4560 | <entry align='left'>uni2661 </entry> | |
| 4561 | <entry align='left'>u2661</entry> | |
| 4562 | <entry align='left'>white heart suit</entry> | |
| 4563 | </row> | |
| 4564 | <row> | |
| 4565 | <entry align='left'>♦ </entry> | |
| 4566 | <entry align='left'>\[DI] </entry> | |
| 4567 | <entry align='left'>diamond </entry> | |
| 4568 | <entry align='left'>u2666</entry> | |
| 4569 | <entry align='left'>black diamond suit</entry> | |
| 4570 | </row> | |
| 4571 | <row> | |
| 4572 | <entry align='left'>੦</entry> | |
| 4573 | <entry align='left'>\[u2662]</entry> | |
| 4574 | <entry align='left'>uni2662 </entry> | |
| 4575 | <entry align='left'>u2662</entry> | |
| 4576 | <entry align='left'>white diamond suit</entry> | |
| 4577 | </row> | |
| 4578 | </tbody> | |
| 4579 | </tgroup> | |
| 4580 | </informaltable> | |
| 4581 | ||
| 4582 | ||
| 4583 | ||
| 4584 | ||
| 4585 | ||
| 4586 | </listitem> | |
| 4587 | </varlistentry> | |
| 4588 | </variablelist> | |
| 4589 | </refsect2> | |
| 4590 | </refsect1> | |
| 4591 | ||
| 4592 | <refsect1 id='author'><title>AUTHOR</title> | |
| 4593 | ||
| 4594 | <para>Copyright © 1989-2000, 2001, 2002, 2003, | |
| 4595 | 2004, 2006, 2008, 2009 Free Software Foundation, Inc.</para> | |
| 4596 | ||
| 4597 | ||
| 4598 | <para>This document is distributed under the terms of the FDL (GNU Free | |
| 4599 | Documentation License) version 1.3 or later. | |
| 4600 | ||
| 4601 | You should have received a copy of the FDL on your system, it is also | |
| 4602 | available on-line at the | |
| 4603 | <ulink url='http://www.gnu.org/copyleft/fdl.html'> | |
| 4604 | GNU copyleft site | |
| 4605 | </ulink></para> | |
| 4606 | ||
| 4607 | ||
| 4608 | <para>This document is part of | |
| 4609 | <emphasis remap='I'>groff</emphasis>, | |
| 4610 | the GNU roff distribution. | |
| 4611 | ||
| 4612 | It was written by | |
| 4613 | <ulink url='mailto:jjc@jclark.com'> | |
| 4614 | James Clark | |
| 4615 | </ulink> | |
| 4616 | with additions by | |
| 4617 | <ulink url='mailto:wl@gnu.org'> | |
| 4618 | Werner Lemberg | |
| 4619 | </ulink> | |
| 4620 | and | |
| 4621 | <ulink url='mailto:bwarken@mayn.de'> | |
| 4622 | Bernd Warken | |
| 4623 | </ulink></para> | |
| 4624 | ||
| 4625 | ||
| 4626 | ||
| 4627 | </refsect1> | |
| 4628 | ||
| 4629 | <refsect1 id='see_also'><title>SEE ALSO</title> | |
| 4630 | ||
| 4631 | <variablelist remap='TP'> | |
| 4632 | <varlistentry> | |
| 4633 | <term><citerefentry><refentrytitle>groff</refentrytitle><manvolnum>1</manvolnum></citerefentry></term> | |
| 4634 | <listitem> | |
| 4635 | <para>the GNU roff formatter</para> | |
| 4636 | ||
| 4637 | </listitem> | |
| 4638 | </varlistentry> | |
| 4639 | <varlistentry> | |
| 4640 | <term><citerefentry><refentrytitle>groff</refentrytitle><manvolnum>7</manvolnum></citerefentry></term> | |
| 4641 | <listitem> | |
| 4642 | <para>a short reference of the groff formatting language</para> | |
| 4643 | ||
| 4644 | ||
| 4645 | ||
| 4646 | <para><emphasis remap='I'>An extension to the troff character set for Europe</emphasis>, | |
| 4647 | E.G. Keizer, K.J. Simonsen, J. Akkerhuis; EUUG Newsletter, Volume 9, | |
| 4648 | No. 2, Summer 1989</para> | |
| 4649 | ||
| 4650 | ||
| 4651 | ||
| 4652 | <para><ulink url='http://www.unicode.org'> | |
| 4653 | The Unicode Standard | |
| 4654 | </ulink></para> | |
| 4655 | ||
| 4656 | <!-- cp 0 --> | |
| 4657 | ||
| 4658 | ||
| 4659 | <!-- Emacs settings --> | |
| 4660 | ||
| 4661 | <!-- Local Variables: | |
| 4662 | mode: nroff | |
| 4663 | End: --> | |
| 4664 | </listitem> | |
| 4665 | </varlistentry> | |
| 4666 | </variablelist> | |
| 4667 | </refsect1> | |
| 4668 | </refentry> | |
| 4669 |
| 0 | .TH GROFF_CHAR 7 "01 April 2012" "Groff Version 1.21" | |
| 1 | .SH NAME | |
| 2 | groff_char \- groff glyph names | |
| 3 | .SH DESCRIPTION | |
| 4 | .\" The lines above were designed to satisfy `apropos'. | |
| 5 | . | |
| 6 | .\" For best results, format this document with `groff' (GNU roff). | |
| 7 | . | |
| 8 | . | |
| 9 | .\" -------------------------------------------------------------------- | |
| 10 | .\" Legal terms | |
| 11 | .\" -------------------------------------------------------------------- | |
| 12 | . | |
| 13 | .ig | |
| 14 | groff_char(7) | |
| 15 | ||
| 16 | This file is part of groff (GNU roff). | |
| 17 | ||
| 18 | File position: <groff_src_top>/man/groff_char.man | |
| 19 | ||
| 20 | Copyright (C) 1989-2000, 2001, 2002, 2003, 2004, 2006, 2007, 2008, 2009 | |
| 21 | Free Software Foundation, Inc. | |
| 22 | written by Werner Lemberg <wl@gnu.org> | |
| 23 | with additions by Bernd Warken <bwarken@mayn.de> | |
| 24 | ||
| 25 | Permission is granted to copy, distribute and/or modify this document | |
| 26 | under the terms of the GNU Free Documentation License, Version 1.3 or | |
| 27 | any later version published by the Free Software Foundation; with the | |
| 28 | Invariant Sections being this .ig-section and AUTHOR, with no | |
| 29 | Front-Cover Texts, and with no Back-Cover Texts. | |
| 30 | ||
| 31 | A copy of the Free Documentation License is included as a file called | |
| 32 | FDL in the main directory of the groff source package. | |
| 33 | .. | |
| 34 | .ig | |
| 35 | A copy of the GNU Free Documentation License is also available in this | |
| 36 | Debian package as /usr/share/doc/groff/copyright. | |
| 37 | .. | |
| 38 | . | |
| 39 | .\" -------------------------------------------------------------------- | |
| 40 | .\" Setup | |
| 41 | .\" -------------------------------------------------------------------- | |
| 42 | . | |
| 43 | .do nr groff_char_C \n[.C] | |
| 44 | .cp 0 | |
| 45 | . | |
| 46 | .\" groff only | |
| 47 | .\".if \n(.g .ne 2v | |
| 48 | .\".if \n(.g .sv 2v | |
| 49 | . | |
| 50 | .ds aq \(aq | |
| 51 | . | |
| 52 | .\" non-groff | |
| 53 | .if !\n(.g .if '\(aq'' .ds aq \' | |
| 54 | . | |
| 55 | .nr Sp 2n | |
| 56 | . | |
| 57 | .do if !r ECFONTS .do fspecial CR R | |
| 58 | . | |
| 59 | . | |
| 60 | .\" -------------------------------------------------------------------- | |
| 61 | .\" .SH DESCRIPTION | |
| 62 | .\" -------------------------------------------------------------------- | |
| 63 | . | |
| 64 | This manual page lists the standard | |
| 65 | .B groff | |
| 66 | glyph names and the default input mapping, \%latin1. | |
| 67 | . | |
| 68 | The glyphs in this document look different depending | |
| 69 | on which output device was chosen (with option | |
| 70 | .B \-T | |
| 71 | for the | |
| 72 | .BR man (1) | |
| 73 | program or the roff formatter). | |
| 74 | . | |
| 75 | Glyphs not available for the device that | |
| 76 | is being used to print or view this manual page are marked with | |
| 77 | .ie \n(.g `(N/A)'; the device currently used is `\*(.T'. | |
| 78 | .el `(N/A)'. | |
| 79 | . | |
| 80 | . | |
| 81 | .P | |
| 82 | In the actual version, | |
| 83 | .B groff | |
| 84 | provides only \%8-bit characters for direct input and named entities | |
| 85 | for further glyphs. | |
| 86 | . | |
| 87 | On ASCII platforms, input character codes in the range 0 to 127 (decimal) | |
| 88 | represent the usual \%7-bit ASCII characters, while codes between 127 | |
| 89 | and 255 are interpreted as the corresponding characters in the | |
| 90 | .I \%latin1 | |
| 91 | .RI ( \%ISO-8859-1 ) | |
| 92 | code set by default. | |
| 93 | . | |
| 94 | This mapping is contained in the file \f(CWlatin1.tmac\fP | |
| 95 | and can be changed by loading a different input encoding. | |
| 96 | . | |
| 97 | Note that some of the input characters are reserved by | |
| 98 | .BR groff , | |
| 99 | either for internal use or for special input purposes. | |
| 100 | . | |
| 101 | On EBCDIC platforms, only code page | |
| 102 | .I cp1047 | |
| 103 | is supported (which contains the same characters as \%latin1; the | |
| 104 | input encoding file is called \f(CWcp1047.tmac\fP). | |
| 105 | . | |
| 106 | Again, some input characters are reserved for internal and special purposes. | |
| 107 | . | |
| 108 | . | |
| 109 | .P | |
| 110 | All roff systems provide the concept of named glyphs. | |
| 111 | . | |
| 112 | In traditional roff systems, only names of length\ 2 were used, while | |
| 113 | groff also provides support for longer names. | |
| 114 | . | |
| 115 | It is strongly suggested that only named glyphs are used for all | |
| 116 | character representations outside of the printable \%7-bit ASCII range. | |
| 117 | . | |
| 118 | . | |
| 119 | .P | |
| 120 | Some of the predefined groff escape sequences (with names of length\ 1) | |
| 121 | also produce single glyphs; these exist for historical reasons or | |
| 122 | are printable versions of syntactical characters. | |
| 123 | . | |
| 124 | They include `\f(CW\e\e\fP', `\f(CW\e\'\fP', `\f(CW\e`\fP', `\f(CW\e-\fP', | |
| 125 | `\f(CW\e.\fP', and `\f(CW\ee\fP'; see | |
| 126 | .BR groff (7). | |
| 127 | . | |
| 128 | . | |
| 129 | .P | |
| 130 | In groff, all of these different types of characters and glyphs can be | |
| 131 | tested positively with the `\f(CW.if\ c\fP' conditional. | |
| 132 | . | |
| 133 | . | |
| 134 | .\" -------------------------------------------------------------------- | |
| 135 | .SH REFERENCE | |
| 136 | .\" -------------------------------------------------------------------- | |
| 137 | . | |
| 138 | In this section, the glyphs in groff are specified in tabular | |
| 139 | form. | |
| 140 | . | |
| 141 | The meaning of the columns is as follows. | |
| 142 | . | |
| 143 | . | |
| 144 | .TP | |
| 145 | .I "Output" | |
| 146 | shows how the glyph is printed for the current device; although | |
| 147 | this can have quite a different shape on other devices, it always | |
| 148 | represents the same glyph. | |
| 149 | . | |
| 150 | . | |
| 151 | .TP | |
| 152 | .I "Input" | |
| 153 | specifies how the glyph is input either directly by a key on the | |
| 154 | keyboard, or by a groff escape sequence. | |
| 155 | . | |
| 156 | . | |
| 157 | .TP | |
| 158 | .I "Code" | |
| 159 | applies to glyphs which can be input with a single character, and | |
| 160 | gives the ISO \%latin1 decimal code of that input character. | |
| 161 | . | |
| 162 | Note that this code is equivalent to the lowest 256 Unicode characters, | |
| 163 | including \%7-bit ASCII in the range 0 to\ 127. | |
| 164 | . | |
| 165 | . | |
| 166 | .TP | |
| 167 | .I "PostScript" | |
| 168 | gives the usual PostScript name of the glyph. | |
| 169 | . | |
| 170 | . | |
| 171 | .TP | |
| 172 | .I "Unicode" | |
| 173 | is the glyph name used in composite glyph names. | |
| 174 | . | |
| 175 | . | |
| 176 | . | |
| 177 | .\" -------------------------------------------------------------------- | |
| 178 | .SS "7-bit Character Codes 32-126" | |
| 179 | .\" -------------------------------------------------------------------- | |
| 180 | . | |
| 181 | These are the basic glyphs having 7-bit ASCII code values assigned. | |
| 182 | . | |
| 183 | They are identical to the printable characters of the | |
| 184 | character standards \%ISO-8859-1 (\%latin1) and Unicode (range | |
| 185 | .IR "Basic Latin" ). | |
| 186 | . | |
| 187 | The glyph names used in composite glyph names are `u0020' up to `u007E'. | |
| 188 | . | |
| 189 | . | |
| 190 | .P | |
| 191 | Note that input characters in the range \%0\-31 and character 127 are | |
| 192 | .I not | |
| 193 | printable characters. | |
| 194 | . | |
| 195 | Most of them are invalid input characters for | |
| 196 | .B groff | |
| 197 | anyway, and the valid ones have special meaning. | |
| 198 | . | |
| 199 | For EBCDIC, the printable characters are in the range \%66\-255. | |
| 200 | . | |
| 201 | . | |
| 202 | .TP | |
| 203 | 48\-57 | |
| 204 | Decimal digits 0 to\ 9 (print as themselves). | |
| 205 | . | |
| 206 | . | |
| 207 | .TP | |
| 208 | 65\-90 | |
| 209 | Upper case letters A\-Z (print as themselves). | |
| 210 | . | |
| 211 | . | |
| 212 | .TP | |
| 213 | 97\-122 | |
| 214 | Lower case letters a\-z (print as themselves). | |
| 215 | . | |
| 216 | . | |
| 217 | .P | |
| 218 | Most of the remaining characters not in the just described ranges print as | |
| 219 | themselves; the only exceptions are the following characters: | |
| 220 | . | |
| 221 | . | |
| 222 | .TP | |
| 223 | .B \` | |
| 224 | the ISO \%latin1 `Grave Accent' (code\ 96) prints as `, a left single | |
| 225 | quotation mark; the original character can be obtained with `\f(CW\e`\fP'. | |
| 226 | . | |
| 227 | . | |
| 228 | .TP | |
| 229 | .B \*(aq | |
| 230 | the ISO \%latin1 `Apostrophe' (code\ 39) prints as ', a right single | |
| 231 | quotation mark; the original character can be obtained with `\f(CW\e(aq\fP'. | |
| 232 | . | |
| 233 | . | |
| 234 | .TP | |
| 235 | .B - | |
| 236 | the ISO \%latin1 `Hyphen, Minus Sign' (code\ 45) prints as a hyphen; a | |
| 237 | minus sign can be obtained with `\f(CW\e-\fP'. | |
| 238 | . | |
| 239 | . | |
| 240 | .TP | |
| 241 | .B ~ | |
| 242 | the ISO \%latin1 `Tilde' (code\ 126) is reduced in size to be usable as | |
| 243 | a diacritic; a larger glyph can be obtained with `\f(CW\e(ti\fP'. | |
| 244 | . | |
| 245 | . | |
| 246 | .TP | |
| 247 | .B ^ | |
| 248 | the ISO \%latin1 `Circumflex Accent' (code\ 94) is reduced in size to be | |
| 249 | usable as a diacritic; a larger glyph can be obtained with `\f(CW\e(ha\fP'. | |
| 250 | . | |
| 251 | . | |
| 252 | .P | |
| 253 | .TS | |
| 254 | l l l l l. | |
| 255 | Output Input Code PostScript Unicode Notes | |
| 256 | _ | |
| 257 | \[char33] \[char33] 33 exclam u0021 | |
| 258 | \[char34] \[char34] 34 quotedbl u0022 | |
| 259 | \[char35] \[char35] 35 numbersign u0023 | |
| 260 | \[char36] \[char36] 36 dollar u0024 | |
| 261 | \[char37] \[char37] 37 percent u0025 | |
| 262 | \[char38] \[char38] 38 ampersand u0026 | |
| 263 | \[char39] \[char39] 39 quoteright u0027 | |
| 264 | \[char40] \[char40] 40 parenleft u0028 | |
| 265 | \[char41] \[char41] 41 parenright u0029 | |
| 266 | \[char42] \[char42] 42 asterisk u002A | |
| 267 | \[char43] \[char43] 43 plus u002B | |
| 268 | \[char44] \[char44] 44 comma u002C | |
| 269 | \[char45] \[char45] 45 hyphen u2010 | |
| 270 | \[char46] \[char46] 46 period u002E | |
| 271 | \[char47] \[char47] 47 slash u002F | |
| 272 | \[char58] \[char58] 58 colon u003A | |
| 273 | \[char59] \[char59] 59 semicolon u003B | |
| 274 | \[char60] \[char60] 60 less u003C | |
| 275 | \[char61] \[char61] 61 equal u003D | |
| 276 | \[char62] \[char62] 62 greater u003E | |
| 277 | \[char63] \[char63] 63 question u003F | |
| 278 | \[char64] \[char64] 64 at u0040 | |
| 279 | \[char91] \[char91] 91 bracketleft u005B | |
| 280 | \[char92] \[char92] 92 backslash u005C | |
| 281 | \[char93] \[char93] 93 bracketright u005D | |
| 282 | \[char94] \[char94] 94 circumflex u005E circumflex accent | |
| 283 | \[char95] \[char95] 95 underscore u005F | |
| 284 | \[char96] \[char96] 96 quoteleft u0060 | |
| 285 | \[char123] \[char123] 123 braceleft u007B | |
| 286 | \[char124] \[char124] 124 bar u007C | |
| 287 | \[char125] \[char125] 125 braceright u007D | |
| 288 | \[char126] \[char126] 126 tilde u007E tilde accent | |
| 289 | .TE | |
| 290 | . | |
| 291 | . | |
| 292 | .\" -------------------------------------------------------------------- | |
| 293 | .SS "8-bit Character Codes 160 to 255" | |
| 294 | .\" -------------------------------------------------------------------- | |
| 295 | . | |
| 296 | They are interpreted as printable characters according to the | |
| 297 | .I latin1 | |
| 298 | .RI ( ISO-8859-1 ) | |
| 299 | code set, being identical to the Unicode range | |
| 300 | .IR "Latin-1 Supplement" . | |
| 301 | . | |
| 302 | . | |
| 303 | .P | |
| 304 | Input characters in range 128-159 (on non-EBCDIC hosts) are not printable | |
| 305 | characters. | |
| 306 | . | |
| 307 | . | |
| 308 | .TP | |
| 309 | 160 | |
| 310 | . | |
| 311 | the ISO \%latin1 | |
| 312 | .I no-break space | |
| 313 | is mapped to `\f(CW\e~\fP', the stretchable space character. | |
| 314 | . | |
| 315 | . | |
| 316 | .TP | |
| 317 | 173 | |
| 318 | . | |
| 319 | the soft hyphen control character. | |
| 320 | . | |
| 321 | .B groff | |
| 322 | never uses this character for output (thus it is omitted in the | |
| 323 | table below); the input character\ 173 is mapped onto `\f(CW\e%\fP'. | |
| 324 | . | |
| 325 | . | |
| 326 | .P | |
| 327 | The remaining ranges (\%161\-172, \%174\-255) | |
| 328 | are printable characters that print as themselves. | |
| 329 | . | |
| 330 | Although they can be specified directly with the keyboard on systems | |
| 331 | with a \%latin1 code page, it is better to use their glyph names; | |
| 332 | see next section. | |
| 333 | . | |
| 334 | .P | |
| 335 | .TS | |
| 336 | l l l l l. | |
| 337 | Output Input Code PostScript Unicode Notes | |
| 338 | _ | |
| 339 | \[char161] \[char161] 161 exclamdown u00A1 inverted exclamation mark | |
| 340 | \[char162] \[char162] 162 cent u00A2 | |
| 341 | \[char163] \[char163] 163 sterling u00A3 | |
| 342 | \[char164] \[char164] 164 currency u00A4 | |
| 343 | \[char165] \[char165] 165 yen u00A5 | |
| 344 | \[char166] \[char166] 166 brokenbar u00A6 | |
| 345 | \[char167] \[char167] 167 section u00A7 | |
| 346 | \[char168] \[char168] 168 dieresis u00A8 | |
| 347 | \[char169] \[char169] 169 copyright u00A9 | |
| 348 | \[char170] \[char170] 170 ordfeminine u00AA | |
| 349 | \[char171] \[char171] 171 guillemotleft u00AB | |
| 350 | \[char172] \[char172] 172 logicalnot u00AC | |
| 351 | \[char174] \[char174] 174 registered u00AE | |
| 352 | \[char175] \[char175] 175 macron u00AF | |
| 353 | \[char176] \[char176] 176 degree u00B0 | |
| 354 | \[char177] \[char177] 177 plusminus u00B1 | |
| 355 | \[char178] \[char178] 178 twosuperior u00B2 | |
| 356 | \[char179] \[char179] 179 threesuperior u00B3 | |
| 357 | \[char180] \[char180] 180 acute u00B4 acute accent | |
| 358 | \[char181] \[char181] 181 mu u00B5 micro sign | |
| 359 | \[char182] \[char182] 182 paragraph u00B6 | |
| 360 | \[char183] \[char183] 183 periodcentered u00B7 | |
| 361 | \[char184] \[char184] 184 cedilla u00B8 | |
| 362 | \[char185] \[char185] 185 onesuperior u00B9 | |
| 363 | \[char186] \[char186] 186 ordmasculine u00BA | |
| 364 | \[char187] \[char187] 187 guillemotright u00BB | |
| 365 | \[char188] \[char188] 188 onequarter u00BC | |
| 366 | \[char189] \[char189] 189 onehalf u00BD | |
| 367 | \[char190] \[char190] 190 threequarters u00BE | |
| 368 | \[char191] \[char191] 191 questiondown u00BF | |
| 369 | \[char192] \[char192] 192 Agrave u0041_0300 | |
| 370 | \[char193] \[char193] 193 Aacute u0041_0301 | |
| 371 | \[char194] \[char194] 194 Acircumflex u0041_0302 | |
| 372 | \[char195] \[char195] 195 Atilde u0041_0303 | |
| 373 | \[char196] \[char196] 196 Adieresis u0041_0308 | |
| 374 | \[char197] \[char197] 197 Aring u0041_030A | |
| 375 | \[char198] \[char198] 198 AE u00C6 | |
| 376 | \[char199] \[char199] 199 Ccedilla u0043_0327 | |
| 377 | \[char200] \[char200] 200 Egrave u0045_0300 | |
| 378 | \[char201] \[char201] 201 Eacute u0045_0301 | |
| 379 | \[char202] \[char202] 202 Ecircumflex u0045_0302 | |
| 380 | \[char203] \[char203] 203 Edieresis u0045_0308 | |
| 381 | \[char204] \[char204] 204 Igrave u0049_0300 | |
| 382 | \[char205] \[char205] 205 Iacute u0049_0301 | |
| 383 | \[char206] \[char206] 206 Icircumflex u0049_0302 | |
| 384 | \[char207] \[char207] 207 Idieresis u0049_0308 | |
| 385 | \[char208] \[char208] 208 Eth u00D0 | |
| 386 | \[char209] \[char209] 209 Ntilde u004E_0303 | |
| 387 | \[char210] \[char210] 210 Ograve u004F_0300 | |
| 388 | \[char211] \[char211] 211 Oacute u004F_0301 | |
| 389 | \[char212] \[char212] 212 Ocircumflex u004F_0302 | |
| 390 | \[char213] \[char213] 213 Otilde u004F_0303 | |
| 391 | \[char214] \[char214] 214 Odieresis u004F_0308 | |
| 392 | \[char215] \[char215] 215 multiply u00D7 | |
| 393 | \[char216] \[char216] 216 Oslash u00D8 | |
| 394 | \[char217] \[char217] 217 Ugrave u0055_0300 | |
| 395 | \[char218] \[char218] 218 Uacute u0055_0301 | |
| 396 | \[char219] \[char219] 219 Ucircumflex u0055_0302 | |
| 397 | \[char220] \[char220] 220 Udieresis u0055_0308 | |
| 398 | \[char221] \[char221] 221 Yacute u0059_0301 | |
| 399 | \[char222] \[char222] 222 Thorn u00DE | |
| 400 | \[char223] \[char223] 223 germandbls u00DF | |
| 401 | \[char224] \[char224] 224 agrave u0061_0300 | |
| 402 | \[char225] \[char225] 225 aacute u0061_0301 | |
| 403 | \[char226] \[char226] 226 acircumflex u0061_0302 | |
| 404 | \[char227] \[char227] 227 atilde u0061_0303 | |
| 405 | \[char228] \[char228] 228 adieresis u0061_0308 | |
| 406 | \[char229] \[char229] 229 aring u0061_030A | |
| 407 | \[char230] \[char230] 230 ae u00E6 | |
| 408 | \[char231] \[char231] 231 ccedilla u0063_0327 | |
| 409 | \[char232] \[char232] 232 egrave u0065_0300 | |
| 410 | \[char233] \[char233] 233 eacute u0065_0301 | |
| 411 | \[char234] \[char234] 234 ecircumflex u0065_0302 | |
| 412 | \[char235] \[char235] 235 edieresis u0065_0308 | |
| 413 | \[char236] \[char236] 236 igrave u0069_0300 | |
| 414 | \[char237] \[char237] 237 iacute u0069_0301 | |
| 415 | \[char238] \[char238] 238 icircumflex u0069_0302 | |
| 416 | \[char239] \[char239] 239 idieresis u0069_0308 | |
| 417 | \[char240] \[char240] 240 eth u00F0 | |
| 418 | \[char241] \[char241] 241 ntilde u006E_0303 | |
| 419 | \[char242] \[char242] 242 ograve u006F_0300 | |
| 420 | \[char243] \[char243] 243 oacute u006F_0301 | |
| 421 | \[char244] \[char244] 244 ocircumflex u006F_0302 | |
| 422 | \[char245] \[char245] 245 otilde u006F_0303 | |
| 423 | \[char246] \[char246] 246 odieresis u006F_0308 | |
| 424 | \[char247] \[char247] 247 divide u00F7 | |
| 425 | \[char248] \[char248] 248 oslash u00F8 | |
| 426 | \[char249] \[char249] 249 ugrave u0075_0300 | |
| 427 | \[char250] \[char250] 250 uacute u0075_0301 | |
| 428 | \[char251] \[char251] 251 ucircumflex u0075_0302 | |
| 429 | \[char252] \[char252] 252 udieresis u0075_0308 | |
| 430 | \[char253] \[char253] 253 yacute u0079_0301 | |
| 431 | \[char254] \[char254] 254 thorn u00FE | |
| 432 | \[char255] \[char255] 255 ydieresis u0079_0308 | |
| 433 | .TE | |
| 434 | . | |
| 435 | . | |
| 436 | .\" -------------------------------------------------------------------- | |
| 437 | .SS "Named Glyphs" | |
| 438 | .\" -------------------------------------------------------------------- | |
| 439 | . | |
| 440 | Glyph names can be embedded into the document text by using escape | |
| 441 | sequences. | |
| 442 | . | |
| 443 | .BR groff (7) | |
| 444 | describes how these escape sequences look. | |
| 445 | . | |
| 446 | Glyph names can consist of quite arbitrary characters from the | |
| 447 | ASCII or \%latin1 code set, not only alphanumeric characters. | |
| 448 | . | |
| 449 | Here some examples: | |
| 450 | . | |
| 451 | .TP | |
| 452 | \f(CW\e(\fP\fIch\fP | |
| 453 | A glyph having the 2-character name | |
| 454 | .IR ch . | |
| 455 | . | |
| 456 | .TP | |
| 457 | \f(CW\e[\fP\fIchar_name\fP\f(CW]\fP | |
| 458 | A glyph having the name | |
| 459 | .I char_name | |
| 460 | (having length 1, 2, 3, .\|.\|.). | |
| 461 | . | |
| 462 | Note that `\fIc\fP' is not the same as | |
| 463 | `\f(CW\e[\fP\fIc\fP\f(CW]\fP' (\fIc\fP\ a single character): | |
| 464 | The latter is internally mapped to glyph name `\e\fIc\fP'. | |
| 465 | . | |
| 466 | By default, groff defines a single glyph name starting with a backslash, | |
| 467 | namely \%`\e-', which can be either accessed as `\f(CW\e\-\fP' or | |
| 468 | `\f(CW\e[-]\fP'. | |
| 469 | . | |
| 470 | .TP | |
| 471 | \f(CW\e[\fP\fIbase_glyph composite_1 composite_2 .\|.\|.\fP\f(CW]\fP | |
| 472 | A composite glyph; see below for a more detailed description. | |
| 473 | . | |
| 474 | . | |
| 475 | .P | |
| 476 | In groff, each \%8-bit input character can also referred to by the construct | |
| 477 | `\f(CW\e[char\fP\fIn\fP\f(CW]\fP' where | |
| 478 | .I n | |
| 479 | is the decimal code of the character, a number between 0 and\ 255 | |
| 480 | without leading zeros (those entities are | |
| 481 | .I not | |
| 482 | glyph names). | |
| 483 | . | |
| 484 | They are normally mapped onto glyphs using the \f(CW.trin\fP request. | |
| 485 | . | |
| 486 | Another special convention is the handling of glyphs with names directly | |
| 487 | derived from a Unicode code point; this is discussed below. | |
| 488 | . | |
| 489 | Moreover, new glyph names can be created by the \f(CW.char\fP request; see | |
| 490 | .BR groff (7). | |
| 491 | . | |
| 492 | .P | |
| 493 | In the following, a plus sign in the `Notes' column indicates that this | |
| 494 | particular glyph name appears in the PS version of the original troff | |
| 495 | documentation, CSTR\ 54. | |
| 496 | . | |
| 497 | .P | |
| 498 | Entries marked with `***' denote glyphs for mathematical purposes (mainly | |
| 499 | used for DVI output). Normally, such glyphs have metrics which make them | |
| 500 | unusable in normal text. | |
| 501 | . | |
| 502 | . | |
| 503 | .P | |
| 504 | .TS | |
| 505 | l l l l l. | |
| 506 | Output Input PostScript Unicode Notes | |
| 507 | _ | |
| 508 | \[-D] \e[-D] Eth u00D0 uppercase eth | |
| 509 | \[Sd] \e[Sd] eth u00F0 lowercase eth | |
| 510 | \[TP] \e[TP] Thorn u00DE uppercase thorn | |
| 511 | \[Tp] \e[Tp] thorn u00FE lowercase thorn | |
| 512 | \[ss] \e[ss] germandbls u00DF German sharp s | |
| 513 | .TE | |
| 514 | . | |
| 515 | .P | |
| 516 | .I Ligatures and Other Latin Glyphs | |
| 517 | .P | |
| 518 | .TS | |
| 519 | l l l l l. | |
| 520 | Output Input PostScript Unicode Notes | |
| 521 | _ | |
| 522 | \[ff] \e[ff] ff u0066_0066 ff ligature + | |
| 523 | \[fi] \e[fi] fi u0066_0069 fi ligature + | |
| 524 | \[fl] \e[fl] fl u0066_006C fl ligature + | |
| 525 | \[Fi] \e[Fi] ffi u0066_0066_0069 ffi ligature + | |
| 526 | \[Fl] \e[Fl] ffl u0066_0066_006C ffl ligature + | |
| 527 | \[/L] \e[/L] Lslash u0141 (Polish) | |
| 528 | \[/l] \e[/l] lslash u0142 (Polish) | |
| 529 | \[/O] \e[/O] Oslash u00D8 (Scandinavian) | |
| 530 | \[/o] \e[/o] oslash u00F8 (Scandinavian) | |
| 531 | \[AE] \e[AE] AE u00C6 | |
| 532 | \[ae] \e[ae] ae u00E6 | |
| 533 | \[OE] \e[OE] OE u0152 | |
| 534 | \[oe] \e[oe] oe u0153 | |
| 535 | \[IJ] \e[IJ] IJ u0132 (Dutch) | |
| 536 | \[ij] \e[ij] ij u0133 (Dutch) | |
| 537 | \[.i] \e[.i] dotlessi u0131 (Turkish) | |
| 538 | \[.j] \e[.j] dotlessj --- j without a dot | |
| 539 | .TE | |
| 540 | . | |
| 541 | .P | |
| 542 | .I Accented Characters | |
| 543 | .P | |
| 544 | .TS | |
| 545 | l l l l l. | |
| 546 | Output Input PostScript Unicode Notes | |
| 547 | _ | |
| 548 | \['A] \e['A] Aacute u0041_0301 | |
| 549 | \['C] \e['C] Cacute u0043_0301 | |
| 550 | \['E] \e['E] Eacute u0045_0301 | |
| 551 | \['I] \e['I] Iacute u0049_0301 | |
| 552 | \['O] \e['O] Oacute u004F_0301 | |
| 553 | \['U] \e['U] Uacute u0055_0301 | |
| 554 | \['Y] \e['Y] Yacute u0059_0301 | |
| 555 | \['a] \e['a] aacute u0061_0301 | |
| 556 | \['c] \e['c] cacute u0063_0301 | |
| 557 | \['e] \e['e] eacute u0065_0301 | |
| 558 | \['i] \e['i] iacute u0069_0301 | |
| 559 | \['o] \e['o] oacute u006F_0301 | |
| 560 | \['u] \e['u] uacute u0075_0301 | |
| 561 | \['y] \e['y] yacute u0079_0301 | |
| 562 | \[:A] \e[:A] Adieresis u0041_0308 A with umlaut | |
| 563 | \[:E] \e[:E] Edieresis u0045_0308 | |
| 564 | \[:I] \e[:I] Idieresis u0049_0308 | |
| 565 | \[:O] \e[:O] Odieresis u004F_0308 | |
| 566 | \[:U] \e[:U] Udieresis u0055_0308 | |
| 567 | \[:Y] \e[:Y] Ydieresis u0059_0308 | |
| 568 | \[:a] \e[:a] adieresis u0061_0308 | |
| 569 | \[:e] \e[:e] edieresis u0065_0308 | |
| 570 | \[:i] \e[:i] idieresis u0069_0308 | |
| 571 | \[:o] \e[:o] odieresis u006F_0308 | |
| 572 | \[:u] \e[:u] udieresis u0075_0308 | |
| 573 | \[:y] \e[:y] ydieresis u0079_0308 | |
| 574 | \[^A] \e[^A] Acircumflex u0041_0302 | |
| 575 | \[^E] \e[^E] Ecircumflex u0045_0302 | |
| 576 | \[^I] \e[^I] Icircumflex u0049_0302 | |
| 577 | \[^O] \e[^O] Ocircumflex u004F_0302 | |
| 578 | \[^U] \e[^U] Ucircumflex u0055_0302 | |
| 579 | \[^a] \e[^a] acircumflex u0061_0302 | |
| 580 | \[^e] \e[^e] ecircumflex u0065_0302 | |
| 581 | \[^i] \e[^i] icircumflex u0069_0302 | |
| 582 | \[^o] \e[^o] ocircumflex u006F_0302 | |
| 583 | \[^u] \e[^u] ucircumflex u0075_0302 | |
| 584 | \[`A] \e[`A] Agrave u0041_0300 | |
| 585 | \[`E] \e[`E] Egrave u0045_0300 | |
| 586 | \[`I] \e[`I] Igrave u0049_0300 | |
| 587 | \[`O] \e[`O] Ograve u004F_0300 | |
| 588 | \[`U] \e[`U] Ugrave u0055_0300 | |
| 589 | \[`a] \e[`a] agrave u0061_0300 | |
| 590 | \[`e] \e[`e] egrave u0065_0300 | |
| 591 | \[`i] \e[`i] igrave u0069_0300 | |
| 592 | \[`o] \e[`o] ograve u006F_0300 | |
| 593 | \[`u] \e[`u] ugrave u0075_0300 | |
| 594 | \[~A] \e[~A] Atilde u0041_0303 | |
| 595 | \[~N] \e[~N] Ntilde u004E_0303 | |
| 596 | \[~O] \e[~O] Otilde u004F_0303 | |
| 597 | \[~a] \e[~a] atilde u0061_0303 | |
| 598 | \[~n] \e[~n] ntilde u006E_0303 | |
| 599 | \[~o] \e[~o] otilde u006F_0303 | |
| 600 | \[vS] \e[vS] Scaron u0053_030C | |
| 601 | \[vs] \e[vs] scaron u0073_030C | |
| 602 | \[vZ] \e[vZ] Zcaron u005A_030C | |
| 603 | \[vz] \e[vz] zcaron u007A_030C | |
| 604 | \[,C] \e[,C] Ccedilla u0043_0327 | |
| 605 | \[,c] \e[,c] ccedilla u0063_0327 | |
| 606 | \[oA] \e[oA] Aring u0041_030A | |
| 607 | \[oa] \e[oa] aring u0061_030A | |
| 608 | .TE | |
| 609 | . | |
| 610 | .P | |
| 611 | .I Accents | |
| 612 | .P | |
| 613 | The | |
| 614 | .B composite | |
| 615 | request is used to map most of the accents to non-spacing glyph names; | |
| 616 | the values given in parentheses are the original (spacing) ones. | |
| 617 | . | |
| 618 | .P | |
| 619 | .TS | |
| 620 | l l l l l. | |
| 621 | Output Input PostScript Unicode Notes | |
| 622 | _ | |
| 623 | \[a"] \e[a"] hungarumlaut u030B (u02DD) (Hungarian) | |
| 624 | \[a-] \e[a-] macron u0304 (u00AF) | |
| 625 | \[a.] \e[a.] dotaccent u0307 (u02D9) | |
| 626 | \[a^] \e[a^] circumfle u0302 (u005E) | |
| 627 | \[aa] \e[aa] acute u0301 (u00B4) + | |
| 628 | \[ga] \e[ga] grave u0300 (u0060) + | |
| 629 | \[ab] \e[ab] breve u0306 (u02D8) | |
| 630 | \[ac] \e[ac] cedilla u0327 (u00B8) | |
| 631 | \[ad] \e[ad] dieresis u0308 (u00A8) umlaut | |
| 632 | \[ah] \e[ah] caron u030C (u02C7) | |
| 633 | \[ao] \e[ao] ring u030A (u02DA) circle | |
| 634 | \[a~] \e[a~] tilde u0303 (u007E) | |
| 635 | \[ho] \e[ho] ogonek u0328 (u02DB) hook | |
| 636 | \[ha] \e[ha] asciicircum u005E (spacing) | |
| 637 | \[ti] \e[ti] asciitilde u007E (spacing) | |
| 638 | .TE | |
| 639 | . | |
| 640 | .P | |
| 641 | .I Quotes | |
| 642 | .P | |
| 643 | .TS | |
| 644 | l l l l l. | |
| 645 | Output Input PostScript Unicode Notes | |
| 646 | _ | |
| 647 | \[Bq] \e[Bq] quotedblbase u201E low double comma quote | |
| 648 | \[bq] \e[bq] quotesinglbase u201A low single comma quote | |
| 649 | \[lq] \e[lq] quotedblleft u201C | |
| 650 | \[rq] \e[rq] quotedblright u201D | |
| 651 | \[oq] \e[oq] quoteleft u2018 single open quote | |
| 652 | \[cq] \e[cq] quoteright u2019 single closing quote | |
| 653 | \[aq] \e[aq] quotesingle u0027 apostrophe quote (ASCII 39) | |
| 654 | \[dq] \e[dq] quotedbl u0022 double quote (ASCII 34) | |
| 655 | \[Fo] \e[Fo] guillemotleft u00AB | |
| 656 | \[Fc] \e[Fc] guillemotright u00BB | |
| 657 | \[fo] \e[fo] guilsinglleft u2039 | |
| 658 | \[fc] \e[fc] guilsinglright u203A | |
| 659 | .TE | |
| 660 | . | |
| 661 | .P | |
| 662 | .I Punctuation | |
| 663 | .P | |
| 664 | .TS | |
| 665 | l l l l l. | |
| 666 | Output Input PostScript Unicode Notes | |
| 667 | _ | |
| 668 | \[r!] \e[r!] exclamdown u00A1 | |
| 669 | \[r?] \e[r?] questiondown u00BF | |
| 670 | \[em] \e[em] emdash u2014 + | |
| 671 | \[en] \e[en] endash u2013 | |
| 672 | \[hy] \e[hy] hyphen u2010 + | |
| 673 | .TE | |
| 674 | . | |
| 675 | .P | |
| 676 | .I Brackets | |
| 677 | .P | |
| 678 | The extensible bracket pieces are font-invariant glyphs. | |
| 679 | . | |
| 680 | In classical troff only one glyph was available to vertically extend | |
| 681 | brackets, braces, and parentheses: `bv'. | |
| 682 | . | |
| 683 | We map it rather arbitrarily to u23AA. | |
| 684 | . | |
| 685 | .P | |
| 686 | Note that not all devices contain extensible bracket pieces which can | |
| 687 | be piled up with `\f(CW\eb\fP' due to the restrictions of the escape's | |
| 688 | piling algorithm. | |
| 689 | . | |
| 690 | A general solution to build brackets out of pieces is the following | |
| 691 | macro: | |
| 692 | . | |
| 693 | .P | |
| 694 | .nf | |
| 695 | .RS | |
| 696 | .ft C | |
| 697 | \&.\e" Make a pile centered vertically 0.5em | |
| 698 | \&.\e" above the baseline. | |
| 699 | \&.\e" The first argument is placed at the top. | |
| 700 | \&.\e" The pile is returned in string `pile' | |
| 701 | \&.eo | |
| 702 | \&.de pile-make | |
| 703 | \&. nr pile-wd 0 | |
| 704 | \&. nr pile-ht 0 | |
| 705 | \&. ds pile-args | |
| 706 | \&. | |
| 707 | \&. nr pile-# \en[.$] | |
| 708 | \&. while \en[pile-#] \e{\e | |
| 709 | \&. nr pile-wd (\en[pile-wd] >? \ew'\e$[\en[pile-#]]') | |
| 710 | \&. nr pile-ht +(\en[rst] - \en[rsb]) | |
| 711 | \&. as pile-args \ev'\en[rsb]u'\e" | |
| 712 | \&. as pile-args \eZ'\e$[\en[pile-#]]'\e" | |
| 713 | \&. as pile-args \ev'-\en[rst]u'\e" | |
| 714 | \&. nr pile-# -1 | |
| 715 | \&. \e} | |
| 716 | \&. | |
| 717 | \&. ds pile \ev'(-0.5m + (\en[pile-ht]u / 2u))'\e" | |
| 718 | \&. as pile \e*[pile-args]\e" | |
| 719 | \&. as pile \ev'((\en[pile-ht]u / 2u) + 0.5m)'\e" | |
| 720 | \&. as pile \eh'\en[pile-wd]u'\e" | |
| 721 | \&.. | |
| 722 | \&.ec | |
| 723 | .ft | |
| 724 | .RE | |
| 725 | .fi | |
| 726 | . | |
| 727 | .P | |
| 728 | Another complication is the fact that some glyphs which represent bracket | |
| 729 | pieces in original troff can be used for other mathematical symbols also, | |
| 730 | for example `lf' and `rf' which provide the `floor' operator. | |
| 731 | . | |
| 732 | Other devices (most notably for DVI output) don't unify such glyphs. | |
| 733 | . | |
| 734 | For this reason, the four glyphs `lf', `rf', `lc', and `rc' are not | |
| 735 | unified with similarly looking bracket pieces. | |
| 736 | . | |
| 737 | In | |
| 738 | .BR groff , | |
| 739 | only glyphs with long names are guaranteed to pile up correctly for all | |
| 740 | devices (provided those glyphs exist). | |
| 741 | . | |
| 742 | .P | |
| 743 | ||
| 744 | .TS | |
| 745 | expand; | |
| 746 | l l l l l. | |
| 747 | Output Input PostScript Unicode Notes | |
| 748 | _ | |
| 749 | \[lB] \e[lB] bracketleft u005B | |
| 750 | \[rB] \e[rB] bracketright u005D | |
| 751 | \[lC] \e[lC] braceleft u007B | |
| 752 | \[rC] \e[rC] braceright u007D | |
| 753 | \[la] \e[la] angleleft u27E8 left angle bracket | |
| 754 | \[ra] \e[ra] angleright u27E9 right angle bracket | |
| 755 | ||
| 756 | \[bv] \e[bv] braceex u23AA vertical extension *** + | |
| 757 | \[br] \e[braceex] braceex u23AA | |
| 758 | ||
| 759 | \[br] \e[bracketlefttp] bracketlefttp u23A1 | |
| 760 | \[br] \e[bracketleftbt] bracketleftbt u23A3 | |
| 761 | \[br] \e[bracketleftex] bracketleftex u23A2 | |
| 762 | \[br] \e[bracketrighttp] bracketrighttp u23A4 | |
| 763 | \[br] \e[bracketrightbt] bracketrightbt u23A6 | |
| 764 | \[br] \e[bracketrightex] bracketrightex u23A5 | |
| 765 | ||
| 766 | \[lt] \e[lt] bracelefttp u23A7 + | |
| 767 | \[br] \e[bracelefttp] bracelefttp u23A7 | |
| 768 | \[lk] \e[lk] braceleftmid u23A8 + | |
| 769 | \[br] \e[braceleftmid] braceleftmid u23A8 | |
| 770 | \[lb] \e[lb] braceleftbt u23A9 + | |
| 771 | \[br] \e[braceleftbt] braceleftbt u23A9 | |
| 772 | \[br] \e[braceleftex] braceleftex u23AA | |
| 773 | \[rt] \e[rt] bracerighttp u23AB + | |
| 774 | \[br] \e[bracerighttp] bracerighttp u23AB | |
| 775 | \[rk] \e[rk] bracerightmid u23AC + | |
| 776 | \[bracerightmid] \e[bracerightmid] bracerightmid u23AC | |
| 777 | \[rb] \e[rb] bracerightbt u23AD + | |
| 778 | \[bracerightbt] \e[bracerightbt] bracerightbt u23AD | |
| 779 | \[bracerightex] \e[bracerightex] bracerightex u23AA | |
| 780 | . | |
| 781 | \[parenlefttp] \e[parenlefttp] parenlefttp u239B | |
| 782 | \[parenleftbt] \e[parenleftbt] parenleftbt u239D | |
| 783 | \[parenleftex] \e[parenleftex] parenleftex u239C | |
| 784 | \[parenrighttp] \e[parenrighttp] parenrighttp u239E | |
| 785 | \[parenrightbt] \e[parenrightbt] parenrightbt u23A0 | |
| 786 | \[parenrightex] \e[parenrightex] parenrightex u239F | |
| 787 | .TE | |
| 788 | . | |
| 789 | .P | |
| 790 | .I Arrows | |
| 791 | .P | |
| 792 | .TS | |
| 793 | expand; | |
| 794 | l l l l l. | |
| 795 | Output Input PostScript Unicode Notes | |
| 796 | _ | |
| 797 | \[<-] \e[<-] arrowleft u2190 + | |
| 798 | \[->] \e[->] arrowright u2192 + | |
| 799 | \[<>] \e[<>] arrowboth u2194 (horizontal) | |
| 800 | \[da] \e[da] arrowdown u2193 + | |
| 801 | \[ua] \e[ua] arrowup u2191 + | |
| 802 | \[va] \e[va] arrowupdn u2195 | |
| 803 | \[lA] \e[lA] arrowdblleft u21D0 | |
| 804 | \[rA] \e[rA] arrowdblright u21D2 | |
| 805 | \[hA] \e[hA] arrowdblboth u21D4 (horizontal) | |
| 806 | \[dA] \e[dA] arrowdbldown u21D3 | |
| 807 | \[uA] \e[uA] arrowdblup u21D1 | |
| 808 | \[vA] \e[vA] uni21D5 u21D5 vertical double-headed double arrow | |
| 809 | \[an] \e[an] arrowhorizex u23AF horizontal arrow extension | |
| 810 | .TE | |
| 811 | . | |
| 812 | .P | |
| 813 | .I Lines | |
| 814 | .P | |
| 815 | The font-invariant glyphs `br', `ul', and `rn' form corners; | |
| 816 | they can be used to build boxes. | |
| 817 | . | |
| 818 | Note that both the PostScript and the Unicode-derived names of | |
| 819 | these three glyphs are just rough approximations. | |
| 820 | . | |
| 821 | .P | |
| 822 | `rn' also serves in classical troff as the horizontal extension of the | |
| 823 | square root sign. | |
| 824 | . | |
| 825 | .P | |
| 826 | `ru' is a font-invariant glyph, namely a rule of length 0.5m. | |
| 827 | . | |
| 828 | .P | |
| 829 | .TS | |
| 830 | expand; | |
| 831 | l l l l l. | |
| 832 | Output Input PostScript Unicode Notes | |
| 833 | _ | |
| 834 | \[ba] \e[ba] bar u007C | |
| 835 | \[br] \e[br] SF110000 u2502 box rule + | |
| 836 | \[ul] \e[ul] underscore u005F + | |
| 837 | \[rn] \e[rn] overline u203E + | |
| 838 | \[ru] \e[ru] --- --- baseline rule + | |
| 839 | \[bb] \e[bb] brokenbar u00A6 | |
| 840 | \[sl] \e[sl] slash u002F + | |
| 841 | \[rs] \e[rs] backslash u005C reverse solidus | |
| 842 | .TE | |
| 843 | .P | |
| 844 | Use `\f(CW\e[radicalex]\fP', not `\f(CW\e[overline]\fP', for | |
| 845 | continuation of square root | |
| 846 | . | |
| 847 | .P | |
| 848 | .I Text markers | |
| 849 | .P | |
| 850 | .TS | |
| 851 | expand; | |
| 852 | l l l l l. | |
| 853 | Output Input PostScript Unicode Notes | |
| 854 | _ | |
| 855 | \[ci] \e[ci] circle u25CB + | |
| 856 | \[bu] \e[bu] bullet u2022 + | |
| 857 | \[dd] \e[dd] daggerdbl u2021 double dagger sign + | |
| 858 | \[dg] \e[dg] dagger u2020 + | |
| 859 | \[lz] \e[lz] lozenge u25CA | |
| 860 | \[sq] \e[sq] uni25A1 u25A1 white square + | |
| 861 | \[ps] \e[ps] paragraph u00B6 | |
| 862 | \[sc] \e[sc] section u00A7 + | |
| 863 | \[lh] \e[lh] uni261C u261C hand pointing left + | |
| 864 | \[rh] \e[rh] a14 u261E hand pointing right + | |
| 865 | \[at] \e[at] at u0040 | |
| 866 | \[sh] \e[sh] numbersign u0023 | |
| 867 | \[CR] \e[CR] carriagereturn u21B5 | |
| 868 | \[OK] \e[OK] a19 u2713 check mark, tick | |
| 869 | .TE | |
| 870 | . | |
| 871 | .P | |
| 872 | .I Legal Symbols | |
| 873 | .P | |
| 874 | .TS | |
| 875 | expand; | |
| 876 | l l l l l. | |
| 877 | Output Input PostScript Unicode Notes | |
| 878 | _ | |
| 879 | \[co] \e[co] copyright u00A9 + | |
| 880 | \[rg] \e[rg] registered u00AE + | |
| 881 | \[tm] \e[tm] trademark u2122 | |
| 882 | \[bs] \e[bs] --- --- AT&T Bell Labs logo + | |
| 883 | .TE | |
| 884 | .P | |
| 885 | The Bell Labs logo is not supported in groff. | |
| 886 | . | |
| 887 | .P | |
| 888 | .I Currency symbols | |
| 889 | .P | |
| 890 | .TS | |
| 891 | expand; | |
| 892 | l l l l l. | |
| 893 | Output Input PostScript Unicode Notes | |
| 894 | _ | |
| 895 | \[Do] \e[Do] dollar u0024 | |
| 896 | \[ct] \e[ct] cent u00A2 + | |
| 897 | \[eu] \e[eu] --- u20AC official Euro symbol | |
| 898 | \[Eu] \e[Eu] Euro u20AC font-specific Euro glyph variant | |
| 899 | \[Ye] \e[Ye] yen u00A5 | |
| 900 | \[Po] \e[Po] sterling u00A3 British currency sign | |
| 901 | \[Cs] \e[Cs] currency u00A4 Scandinavian currency sign | |
| 902 | \[Fn] \e[Fn] florin u0192 Dutch currency sign | |
| 903 | .TE | |
| 904 | . | |
| 905 | .P | |
| 906 | .I Units | |
| 907 | .P | |
| 908 | .TS | |
| 909 | expand; | |
| 910 | l l l l l. | |
| 911 | Output Input PostScript Unicode Notes | |
| 912 | _ | |
| 913 | \[de] \e[de] degree u00B0 + | |
| 914 | \[%0] \e[%0] perthousand u2030 per thousand, per mille sign | |
| 915 | \[fm] \e[fm] minute u2032 footmark, prime + | |
| 916 | \[sd] \e[sd] second u2033 | |
| 917 | \[mc] \e[mc] mu u00B5 micro sign | |
| 918 | \[Of] \e[Of] ordfeminine u00AA | |
| 919 | \[Om] \e[Om] ordmasculine u00BA | |
| 920 | .TE | |
| 921 | . | |
| 922 | .P | |
| 923 | .I Logical Symbols | |
| 924 | .P | |
| 925 | .TS | |
| 926 | expand; | |
| 927 | l l l l l. | |
| 928 | Output Input PostScript Unicode Notes | |
| 929 | _ | |
| 930 | \[AN] \e[AN] logicaland u2227 | |
| 931 | \[OR] \e[OR] logicalor u2228 | |
| 932 | \[no] \e[no] logicalnot u00AC + | |
| 933 | \[tno] \e[tno] logicalnot u00AC text variant of `no' | |
| 934 | \[te] \e[te] existential u2203 there exists | |
| 935 | \[fa] \e[fa] universal u2200 for all | |
| 936 | \[st] \e[st] suchthat u220B | |
| 937 | \[3d] \e[3d] therefore u2234 | |
| 938 | \[tf] \e[tf] therefore u2234 | |
| 939 | .TE | |
| 940 | . | |
| 941 | .P | |
| 942 | .I Mathematical Symbols | |
| 943 | .P | |
| 944 | .TS | |
| 945 | expand; | |
| 946 | l l l l l. | |
| 947 | Output Input PostScript Unicode Notes | |
| 948 | _ | |
| 949 | \[12] \e[12] onehalf u00BD "+" | |
| 950 | \[14] \e[14] onequarter u00BC "+" | |
| 951 | \[34] \e[34] threequarters u00BE "+" | |
| 952 | \[18] \e[18] oneeighth u215B | |
| 953 | \[38] \e[38] threeeighths u215C | |
| 954 | \[58] \e[58] fiveeighths u215D | |
| 955 | \[78] \e[78] seveneighths u215E | |
| 956 | \[S1] \e[S1] onesuperior u00B9 | |
| 957 | \[S2] \e[S2] twosuperior u00B2 | |
| 958 | \[S3] \e[S3] threesuperior u00B3 | |
| 959 | ||
| 960 | \[pl] \e[pl] plus u002B plus in special font + | |
| 961 | \[mi] \e[mi] minus u2212 minus in special font + | |
| 962 | \[-+] \e[-+] uni2213 u2213 | |
| 963 | \[+-] \e[+-] plusminus u00B1 + | |
| 964 | \[t+-] \e[t+-] plusminus u00B1 text variant of `+\-' | |
| 965 | \[pc] \e[pc] periodcentered u00B7 | |
| 966 | \[md] \e[md] dotmath u22C5 multiplication dot | |
| 967 | \[mu] \e[mu] multiply u00D7 + | |
| 968 | \[tm] \e[tmu] multiply u00D7 text variant of `mu' | |
| 969 | \[c*] \e[c*] circlemultiply u2297 multiply sign in a circle | |
| 970 | \[c+] \e[c+] circleplus u2295 plus in a circle | |
| 971 | \[di] \e[di] divide u00F7 division + | |
| 972 | \[tdi] \e[tdi] divide u00F7 text variant of `di' | |
| 973 | \[f/] \e[f/] fraction u2044 bar for fractions | |
| 974 | \[**] \e[**] asteriskmath u2217 + | |
| 975 | ||
| 976 | \[<=] \e[<=] lessequal u2264 + | |
| 977 | \[>=] \e[>=] greaterequal u2265 + | |
| 978 | \[<<] \e[<<] uni226A u226A much less | |
| 979 | \[>>] \e[>>] uni226B u226B much greater | |
| 980 | \[eq] \e[eq] equal u003D equals in special font + | |
| 981 | \[!=] \e[!=] notequal u003D_0338 + | |
| 982 | \[==] \e[==] equivalence u2261 + | |
| 983 | \[ne] \e[ne] uni2262 u2261_0338 | |
| 984 | \[=~] \e[=~] congruent u2245 approx.\& equal | |
| 985 | \[|=] \e[|=] uni2243 u2243 asymptot.\& equal to + | |
| 986 | \[ap] \e[ap] similar u223C + | |
| 987 | \[~~] \e[~~] approxequal u2248 almost equal to | |
| 988 | \[~=] \e[~=] approxequal u2248 | |
| 989 | \[pt] \e[pt] proportional u221D + | |
| 990 | ||
| 991 | \[es] \e[es] emptyset u2205 + | |
| 992 | \[mo] \e[mo] element u2208 + | |
| 993 | \[nm] \e[nm] notelement u2208_0338 | |
| 994 | \[sb] \e[sb] propersubset u2282 + | |
| 995 | \[nb] \e[nb] notsubset u2282_0338 | |
| 996 | \[sp] \e[sp] propersuperset u2283 + | |
| 997 | \[nc] \e[nc] uni2285 u2283_0338 not superset | |
| 998 | \[ib] \e[ib] reflexsubset u2286 + | |
| 999 | \[ip] \e[ip] reflexsuperset u2287 + | |
| 1000 | \[ca] \e[ca] intersection u2229 intersection, cap + | |
| 1001 | \[cu] \e[cu] union u222A union, cup + | |
| 1002 | ||
| 1003 | \[/_] \e[/_] angle u2220 | |
| 1004 | \[pp] \e[pp] perpendicular u22A5 | |
| 1005 | \[is] \e[is] integral u222B + | |
| 1006 | \[integral] \e[integral] integral u222B *** | |
| 1007 | \[sum] \e[sum] summation u2211 *** | |
| 1008 | \[product] \e[product] product u220F *** | |
| 1009 | \[coproduct] \e[coproduct] uni2210 u2210 *** | |
| 1010 | \[gr] \e[gr] gradient u2207 + | |
| 1011 | \[sr] \e[sr] radical u221A square root + | |
| 1012 | \[sq] \e[sqrt] radical u221A *** | |
| 1013 | \[radicalex] \e[radicalex] radicalex --- square root continuation | |
| 1014 | \[sqrtex] \e[sqrtex] radicalex --- *** | |
| 1015 | ||
| 1016 | \[lc] \e[lc] uni2308 u2308 left ceiling + | |
| 1017 | \[rc] \e[rc] uni2309 u2309 right ceiling + | |
| 1018 | \[lf] \e[lf] uni230A u230A left floor + | |
| 1019 | \[rf] \e[rf] uni230B u230B right floor + | |
| 1020 | ||
| 1021 | \[if] \e[if] infinity u221E + | |
| 1022 | \[Ah] \e[Ah] aleph u2135 | |
| 1023 | \[Im] \e[Im] Ifraktur u2111 Gothic I, imaginary | |
| 1024 | \[Re] \e[Re] Rfraktur u211C Gothic R, real | |
| 1025 | \[wp] \e[wp] weierstrass u2118 Weierstrass p | |
| 1026 | \[pd] \e[pd] partialdiff u2202 partial differentiation + | |
| 1027 | \[-h] \e[-h] uni210F u210F Planck constant / 2pi | |
| 1028 | \[hbar] \e[hbar] uni210F u210F | |
| 1029 | .TE | |
| 1030 | . | |
| 1031 | .P | |
| 1032 | .I Greek glyphs | |
| 1033 | .P | |
| 1034 | These glyphs are intended for technical use, not for real Greek; normally, | |
| 1035 | the uppercase letters have upright shape, and the lowercase ones are | |
| 1036 | slanted. | |
| 1037 | . | |
| 1038 | There is a problem with the mapping of letter phi to Unicode. | |
| 1039 | . | |
| 1040 | Prior to Unicode version\ 3.0, the difference between U+03C6, GREEK | |
| 1041 | SMALL LETTER PHI, and U+03D5, GREEK PHI SYMBOL, was not clearly described; | |
| 1042 | only the glyph shapes in the Unicode book could be used as a reference. | |
| 1043 | . | |
| 1044 | Starting with Unicode\ 3.0, the reference glyphs have been exchanged and | |
| 1045 | described verbally also: In mathematical context, U+03D5 is the stroked | |
| 1046 | variant and U+03C6 the curly glyph. | |
| 1047 | . | |
| 1048 | Unfortunately, most font vendors didn't update their fonts to | |
| 1049 | this (incompatible) change in Unicode. | |
| 1050 | . | |
| 1051 | At the time of this writing (January 2006), it is not clear yet whether | |
| 1052 | the Adobe Glyph Names `phi' and `phi1' also change its meaning if used for | |
| 1053 | mathematics, thus compatibility problems are likely to happen \(en being | |
| 1054 | conservative, groff currently assumes that `phi' in a PostScript symbol | |
| 1055 | font is the stroked version. | |
| 1056 | .P | |
| 1057 | In groff, symbol `\f(CW\e[*f]\fP' always denotes the stroked version of | |
| 1058 | phi, and `\f(CW\e[+f]\fP' the curly variant. | |
| 1059 | .P | |
| 1060 | .TS | |
| 1061 | expand; | |
| 1062 | l l l l l. | |
| 1063 | Output Input PostScript Unicode Notes | |
| 1064 | _ | |
| 1065 | \[*A] \e[*A] Alpha u0391 + | |
| 1066 | \[*B] \e[*B] Beta u0392 + | |
| 1067 | \[*G] \e[*G] Gamma u0393 + | |
| 1068 | \[*D] \e[*D] Delta u0394 + | |
| 1069 | \[*E] \e[*E] Epsilon u0395 + | |
| 1070 | \[*Z] \e[*Z] Zeta u0396 + | |
| 1071 | \[*Y] \e[*Y] Eta u0397 + | |
| 1072 | \[*H] \e[*H] Theta u0398 + | |
| 1073 | \[*I] \e[*I] Iota u0399 + | |
| 1074 | \[*K] \e[*K] Kappa u039A + | |
| 1075 | \[*L] \e[*L] Lambda u039B + | |
| 1076 | \[*M] \e[*M] Mu u039C + | |
| 1077 | \[*N] \e[*N] Nu u039D + | |
| 1078 | \[*C] \e[*C] Xi u039E + | |
| 1079 | \[*O] \e[*O] Omicron u039F + | |
| 1080 | \[*P] \e[*P] Pi u03A0 + | |
| 1081 | \[*R] \e[*R] Rho u03A1 + | |
| 1082 | \[*S] \e[*S] Sigma u03A3 + | |
| 1083 | \[*T] \e[*T] Tau u03A4 + | |
| 1084 | \[*U] \e[*U] Upsilon u03A5 + | |
| 1085 | \[*F] \e[*F] Phi u03A6 + | |
| 1086 | \[*X] \e[*X] Chi u03A7 + | |
| 1087 | \[*Q] \e[*Q] Psi u03A8 + | |
| 1088 | \[*W] \e[*W] Omega u03A9 + | |
| 1089 | \[*a] \e[*a] alpha u03B1 + | |
| 1090 | \[*b] \e[*b] beta u03B2 + | |
| 1091 | \[*g] \e[*g] gamma u03B3 + | |
| 1092 | \[*d] \e[*d] delta u03B4 + | |
| 1093 | \[*e] \e[*e] epsilon u03B5 + | |
| 1094 | \[*z] \e[*z] zeta u03B6 + | |
| 1095 | \[*y] \e[*y] eta u03B7 + | |
| 1096 | \[*h] \e[*h] theta u03B8 + | |
| 1097 | \[*i] \e[*i] iota u03B9 + | |
| 1098 | \[*k] \e[*k] kappa u03BA + | |
| 1099 | \[*l] \e[*l] lambda u03BB + | |
| 1100 | \[*m] \e[*m] mu u03BC + | |
| 1101 | \[*n] \e[*n] nu u03BD + | |
| 1102 | \[*c] \e[*c] xi u03BE + | |
| 1103 | \[*o] \e[*o] omicron u03BF + | |
| 1104 | \[*p] \e[*p] pi u03C0 + | |
| 1105 | \[*r] \e[*r] rho u03C1 + | |
| 1106 | \[ts] \e[ts] sigma1 u03C2 terminal sigma + | |
| 1107 | \[*s] \e[*s] sigma u03C3 + | |
| 1108 | \[*t] \e[*t] tau u03C4 + | |
| 1109 | \[*u] \e[*u] upsilon u03C5 + | |
| 1110 | \[*f] \e[*f] phi u03D5 (stroked glyph) + | |
| 1111 | \[*x] \e[*x] chi u03C7 + | |
| 1112 | \[*q] \e[*q] psi u03C8 + | |
| 1113 | \[*w] \e[*w] omega u03C9 + | |
| 1114 | \[+h] \e[+h] theta1 u03D1 variant theta | |
| 1115 | \[+f] \e[+f] phi1 u03C6 variant phi (curly shape) | |
| 1116 | \[+p] \e[+p] omega1 u03D6 variant pi, looking like omega | |
| 1117 | \[+e] \e[+e] uni03F5 u03F5 variant epsilon | |
| 1118 | .TE | |
| 1119 | . | |
| 1120 | .P | |
| 1121 | .I Card symbols | |
| 1122 | .P | |
| 1123 | .TS | |
| 1124 | expand; | |
| 1125 | l l l l l. | |
| 1126 | Output Input PostScript Unicode Notes | |
| 1127 | _ | |
| 1128 | \[CL] \e[CL] club u2663 black club suit | |
| 1129 | \[SP] \e[SP] spade u2660 black spade suit | |
| 1130 | \[HE] \e[HE] heart u2665 black heart suit | |
| 1131 | \[u2661] \e[u2661] uni2661 u2661 white heart suit | |
| 1132 | \[DI] \e[DI] diamond u2666 black diamond suit | |
| 1133 | \[u2662] \e[u2662] uni2662 u2662 white diamond suit | |
| 1134 | .TE | |
| 1135 | . | |
| 1136 | . | |
| 1137 | .\" -------------------------------------------------------------------- | |
| 1138 | .SH "AUTHOR" | |
| 1139 | .\" -------------------------------------------------------------------- | |
| 1140 | . | |
| 1141 | Copyright \(co 1989-2000, 2001, 2002, 2003, | |
| 1142 | 2004, 2006, 2008, 2009 Free Software Foundation, Inc. | |
| 1143 | . | |
| 1144 | .P | |
| 1145 | This document is distributed under the terms of the FDL (GNU Free | |
| 1146 | Documentation License) version 1.3 or later. | |
| 1147 | . | |
| 1148 | You should have received a copy of the FDL on your system, it is also | |
| 1149 | available on-line at the | |
| 1150 | .UR http://\:www.gnu.org/\:copyleft/\:fdl.html | |
| 1151 | GNU copyleft site | |
| 1152 | .UE . | |
| 1153 | . | |
| 1154 | .P | |
| 1155 | This document is part of | |
| 1156 | .IR groff , | |
| 1157 | the GNU roff distribution. | |
| 1158 | . | |
| 1159 | It was written by | |
| 1160 | .MT jjc@jclark.com | |
| 1161 | James Clark | |
| 1162 | .ME | |
| 1163 | with additions by | |
| 1164 | .MT wl@gnu.org | |
| 1165 | Werner Lemberg | |
| 1166 | .ME | |
| 1167 | and | |
| 1168 | .MT bwarken@mayn.de | |
| 1169 | Bernd Warken | |
| 1170 | .ME . | |
| 1171 | . | |
| 1172 | . | |
| 1173 | .\" -------------------------------------------------------------------- | |
| 1174 | .SH "SEE ALSO" | |
| 1175 | .\" -------------------------------------------------------------------- | |
| 1176 | . | |
| 1177 | .TP | |
| 1178 | .BR groff (1) | |
| 1179 | the GNU roff formatter | |
| 1180 | . | |
| 1181 | .TP | |
| 1182 | .BR groff (7) | |
| 1183 | a short reference of the groff formatting language | |
| 1184 | . | |
| 1185 | . | |
| 1186 | .P | |
| 1187 | .IR "An extension to the troff character set for Europe" , | |
| 1188 | E.G. Keizer, K.J. Simonsen, J. Akkerhuis; EUUG Newsletter, Volume 9, | |
| 1189 | No. 2, Summer 1989 | |
| 1190 | . | |
| 1191 | . | |
| 1192 | .P | |
| 1193 | .UR http://\:www.unicode.org | |
| 1194 | The Unicode Standard | |
| 1195 | .UE | |
| 1196 | . | |
| 1197 | .cp \n[groff_char_C] | |
| 1198 | . | |
| 1199 | .\" -------------------------------------------------------------------- | |
| 1200 | .\" Emacs settings | |
| 1201 | .\" -------------------------------------------------------------------- | |
| 1202 | .\" Local Variables: | |
| 1203 | .\" mode: nroff | |
| 1204 | .\" End: |
| 0 | <?xml version="1.0" encoding="ISO-8859-1"?> | |
| 1 | <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" | |
| 2 | "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"> | |
| 3 | <!-- lifted from man+troff by doclifter --> | |
| 4 | <refentry> | |
| 5 | <!-- Copyright (c) 2001\-2003 The Open Group, All Rights Reserved --> | |
| 6 | <refentryinfo><date>2003</date></refentryinfo> | |
| 7 | <refmeta> | |
| 8 | <refentrytitle>PAX</refentrytitle> | |
| 9 | <manvolnum>P</manvolnum> | |
| 10 | <refmiscinfo class='date'>2003</refmiscinfo> | |
| 11 | <refmiscinfo class='source'>IEEE/The Open Group</refmiscinfo> | |
| 12 | <refmiscinfo class='manual'>POSIX Programmer's Manual</refmiscinfo> | |
| 13 | </refmeta> | |
| 14 | <refnamediv> | |
| 15 | <refname>pax</refname> | |
| 16 | <refpurpose>portable archive interchange</refpurpose> | |
| 17 | </refnamediv> | |
| 18 | <!-- body begins here --> | |
| 19 | <refsynopsisdiv id='synopsis'> | |
| 20 | <cmdsynopsis> | |
| 21 | <command>pax</command> <arg choice='opt'>-cdnv </arg> | |
| 22 | <group choice='opt'><arg choice='plain'>-H </arg><arg choice='plain'>-L </arg></group> | |
| 23 | <arg choice='opt'>-f <replaceable>archive</replaceable></arg> | |
| 24 | <arg choice='opt' rep='repeat'>-s <replaceable>replstr</replaceable></arg> | |
| 25 | <arg choice='opt' rep='repeat'><replaceable>pattern</replaceable></arg> | |
| 26 | </cmdsynopsis> | |
| 27 | <cmdsynopsis> | |
| 28 | <command>pax</command> <arg choice='plain'>-r </arg> | |
| 29 | <arg choice='opt'>-cdiknuv </arg> | |
| 30 | <group choice='opt'><arg choice='plain'>-H </arg><arg choice='plain'>-L </arg></group> | |
| 31 | <arg choice='opt'>-f <replaceable>archive</replaceable></arg> | |
| 32 | <arg choice='opt' rep='repeat'>-o <replaceable>options</replaceable></arg> | |
| 33 | <arg choice='opt' rep='repeat'>-p <replaceable>string</replaceable></arg> | |
| 34 | ||
| 35 | <sbr/> | |
| 36 | <arg choice='opt' rep='repeat'>-s <replaceable>replstr</replaceable></arg> | |
| 37 | <arg choice='opt' rep='repeat'><replaceable>pattern</replaceable></arg> | |
| 38 | </cmdsynopsis> | |
| 39 | <cmdsynopsis> | |
| 40 | <command>pax</command> <arg choice='plain'>-w </arg> | |
| 41 | <arg choice='opt'>-dituvX </arg> | |
| 42 | <group choice='opt'><arg choice='plain'>-H </arg><arg choice='plain'>-L </arg></group> | |
| 43 | <arg choice='opt'>-b <replaceable>blksize</replaceable></arg> | |
| 44 | <arg choice='opt'>-a </arg> | |
| 45 | <arg choice='opt'>-f <replaceable>archive</replaceable></arg> | |
| 46 | <arg choice='opt' rep='repeat'>-o <replaceable>options</replaceable></arg> | |
| 47 | ||
| 48 | <sbr/> | |
| 49 | <arg choice='opt' rep='repeat'>-s <replaceable>replstr</replaceable></arg> | |
| 50 | <arg choice='opt'>-x <replaceable>format</replaceable></arg> | |
| 51 | <arg choice='opt' rep='repeat'><replaceable>file</replaceable></arg> | |
| 52 | </cmdsynopsis> | |
| 53 | <cmdsynopsis> | |
| 54 | <command>pax</command> <arg choice='plain'>-r </arg> | |
| 55 | <arg choice='plain'>-w </arg> | |
| 56 | <arg choice='opt'>-diklntuvX </arg> | |
| 57 | <group choice='opt'><arg choice='plain'>-H </arg><arg choice='plain'>-L </arg></group> | |
| 58 | <arg choice='opt' rep='repeat'>-p <replaceable>string</replaceable></arg> | |
| 59 | <arg choice='opt' rep='repeat'>-s <replaceable>replstr</replaceable></arg> | |
| 60 | ||
| 61 | <sbr/> | |
| 62 | <arg choice='opt' rep='repeat'><replaceable>file</replaceable></arg> | |
| 63 | <arg choice='plain'><replaceable>directory</replaceable></arg> | |
| 64 | <sbr/> | |
| 65 | </cmdsynopsis> | |
| 66 | </refsynopsisdiv> | |
| 67 | ||
| 68 | ||
| 69 | <refsect1 id='description'><title>DESCRIPTION</title> | |
| 70 | <para>The <command>pax</command> utility shall read, write, and write lists of the members | |
| 71 | of archive files and copy directory hierarchies. A | |
| 72 | variety of archive formats shall be supported; see the <option>-x</option> <replaceable>format</replaceable> | |
| 73 | option.</para> | |
| 74 | ||
| 75 | <para>The action to be taken depends on the presence of the <option>-r</option> and | |
| 76 | <option>-w</option> options. The four combinations of <option>-r</option> and | |
| 77 | <option>-w</option> are referred to as the four modes of operation: <emphasis remap='B'>list</emphasis>, | |
| 78 | <emphasis remap='B'>read</emphasis>, <emphasis remap='B'>write</emphasis>, and <emphasis remap='B'>copy</emphasis> modes, | |
| 79 | corresponding respectively to the four forms shown in the SYNOPSIS | |
| 80 | section.</para> | |
| 81 | <variablelist remap='TP'> | |
| 82 | <varlistentry> | |
| 83 | <term><emphasis remap='B'>list</emphasis></term> | |
| 84 | <listitem> | |
| 85 | <para>In <emphasis remap='B'>list</emphasis> mode (when neither <option>-r</option> nor <option>-w</option> are specified), | |
| 86 | <command>pax</command> shall write the names of the members of | |
| 87 | the archive file read from the standard input, with pathnames matching | |
| 88 | the specified patterns, to standard output. If a named file | |
| 89 | is of type directory, the file hierarchy rooted at that file shall | |
| 90 | be listed as well.</para> | |
| 91 | </listitem> | |
| 92 | </varlistentry> | |
| 93 | <varlistentry> | |
| 94 | <term><emphasis remap='B'>read</emphasis></term> | |
| 95 | <listitem> | |
| 96 | <para>In <emphasis remap='B'>read</emphasis> mode (when <option>-r</option> is specified, but <option>-w</option> is not), | |
| 97 | <command>pax</command> shall extract the members of the archive | |
| 98 | file read from the standard input, with pathnames matching the specified | |
| 99 | patterns. If an extracted file is of type directory, the | |
| 100 | file hierarchy rooted at that file shall be extracted as well. The | |
| 101 | extracted files shall be created performing pathname resolution | |
| 102 | with the directory in which <command>pax</command> was invoked as the current working | |
| 103 | directory.</para> | |
| 104 | ||
| 105 | <para>If an attempt is made to extract a directory when the directory already | |
| 106 | exists, this shall not be considered an error. If an | |
| 107 | attempt is made to extract a FIFO when the FIFO already exists, this | |
| 108 | shall not be considered an error.</para> | |
| 109 | ||
| 110 | <para>The ownership, access, and modification times, and file mode of the | |
| 111 | restored files are discussed under the <option>-p</option> option.</para> | |
| 112 | </listitem> | |
| 113 | </varlistentry> | |
| 114 | <varlistentry> | |
| 115 | <term><emphasis remap='B'>write</emphasis></term> | |
| 116 | <listitem> | |
| 117 | <para>In <emphasis remap='B'>write</emphasis> mode (when <option>-w</option> is specified, but <option>-r</option> is not), | |
| 118 | <command>pax</command> shall write the contents of the | |
| 119 | <emphasis remap='I'>file</emphasis> operands to the standard output in an archive format. If | |
| 120 | no <emphasis remap='I'>file</emphasis> operands are specified, a list of files to | |
| 121 | copy, one per line, shall be read from the standard input. A file | |
| 122 | of type directory shall include all of the files in the file | |
| 123 | hierarchy rooted at the file.</para> | |
| 124 | </listitem> | |
| 125 | </varlistentry> | |
| 126 | <varlistentry> | |
| 127 | <term><emphasis remap='B'>copy</emphasis></term> | |
| 128 | <listitem> | |
| 129 | <para>In <emphasis remap='B'>copy</emphasis> mode (when both <option>-r</option> and <option>-w</option> are specified), | |
| 130 | <command>pax</command> shall copy the <emphasis remap='I'>file</emphasis> operands to the | |
| 131 | destination directory.</para> | |
| 132 | ||
| 133 | <para>If no <emphasis remap='I'>file</emphasis> operands are specified, a list of files to copy, | |
| 134 | one per line, shall be read from the standard input. A file | |
| 135 | of type directory shall include all of the files in the file hierarchy | |
| 136 | rooted at the file.</para> | |
| 137 | ||
| 138 | <para>The effect of the <emphasis remap='B'>copy</emphasis> shall be as if the copied files were | |
| 139 | written to an archive file and then subsequently extracted, | |
| 140 | except that there may be hard links between the original and the copied | |
| 141 | files. If the destination directory is a subdirectory of | |
| 142 | one of the files to be copied, the results are unspecified. If the | |
| 143 | destination directory is a file of a type not defined by the | |
| 144 | System Interfaces volume of IEEE Std 1003.1-2001, the results are | |
| 145 | implementation-defined; otherwise, it shall be an error | |
| 146 | for the file named by the <emphasis remap='I'>directory</emphasis> operand not to exist, not | |
| 147 | be writable by the user, or not be a file of type | |
| 148 | directory.</para> | |
| 149 | ||
| 150 | ||
| 151 | <para>In <emphasis remap='B'>read</emphasis> or <emphasis remap='B'>copy</emphasis> modes, if intermediate directories are | |
| 152 | necessary to extract an archive member, <command>pax</command> shall | |
| 153 | perform actions equivalent to the <emphasis remap='I'>mkdir</emphasis>() function defined in | |
| 154 | the System Interfaces | |
| 155 | volume of IEEE Std 1003.1-2001, called with the following arguments:</para> | |
| 156 | <variablelist remap='IP'> | |
| 157 | <varlistentry> | |
| 158 | <term> *</term> | |
| 159 | <listitem> | |
| 160 | <para>The intermediate directory used as the <emphasis remap='I'>path</emphasis> argument</para> | |
| 161 | ||
| 162 | </listitem> | |
| 163 | </varlistentry> | |
| 164 | <varlistentry> | |
| 165 | <term> *</term> | |
| 166 | <listitem> | |
| 167 | <para>The value of the bitwise-inclusive OR of S_IRWXU, S_IRWXG, and S_IRWXO | |
| 168 | as the <emphasis remap='I'>mode</emphasis> argument</para> | |
| 169 | ||
| 170 | ||
| 171 | <para>If any specified <emphasis remap='I'>pattern</emphasis> or <emphasis remap='I'>file</emphasis> operands are not matched | |
| 172 | by at least one file or archive member, <command>pax</command> shall | |
| 173 | write a diagnostic message to standard error for each one that did | |
| 174 | not match and exit with a non-zero exit status.</para> | |
| 175 | ||
| 176 | <para>The archive formats described in the EXTENDED DESCRIPTION section | |
| 177 | shall be automatically detected on input. The default output | |
| 178 | archive format shall be implementation-defined.</para> | |
| 179 | ||
| 180 | <para>A single archive can span multiple files. The <command>pax</command> utility shall | |
| 181 | determine, in an implementation-defined manner, what file | |
| 182 | to read or write as the next file.</para> | |
| 183 | ||
| 184 | <para>If the selected archive format supports the specification of linked | |
| 185 | files, it shall be an error if these files cannot be linked | |
| 186 | when the archive is extracted. For archive formats that do not store | |
| 187 | file contents with each name that causes a hard link, if the | |
| 188 | file that contains the data is not extracted during this <command>pax</command> | |
| 189 | session, either the data shall be restored from the original | |
| 190 | file, or a diagnostic message shall be displayed with the name of | |
| 191 | a file that can be used to extract the data. In traversing | |
| 192 | directories, <command>pax</command> shall detect infinite loops; that is, entering | |
| 193 | a previously visited directory that is an ancestor of the | |
| 194 | last file visited. When it detects an infinite loop, <command>pax</command> shall | |
| 195 | write a diagnostic message to standard error and shall | |
| 196 | terminate.</para> | |
| 197 | </listitem> | |
| 198 | </varlistentry> | |
| 199 | </variablelist> | |
| 200 | </listitem> | |
| 201 | </varlistentry> | |
| 202 | </variablelist> | |
| 203 | </refsect1> | |
| 204 | ||
| 205 | <refsect1 id='options'><title>OPTIONS</title> | |
| 206 | <para>The <command>pax</command> utility shall conform to the Base Definitions volume | |
| 207 | of IEEE Std 1003.1-2001, Section 12.2, Utility Syntax Guidelines, | |
| 208 | except that the order of presentation of the | |
| 209 | <option>-o</option>, <option>-p</option>, and <option>-s</option> options is significant.</para> | |
| 210 | ||
| 211 | <para>The following options shall be supported:</para> | |
| 212 | <variablelist remap='TP'> | |
| 213 | <varlistentry> | |
| 214 | <term><option>-r</option></term> | |
| 215 | <listitem> | |
| 216 | <para>Read an archive file from standard input.</para> | |
| 217 | </listitem> | |
| 218 | </varlistentry> | |
| 219 | <varlistentry> | |
| 220 | <term><option>-w</option></term> | |
| 221 | <listitem> | |
| 222 | <para>Write files to the standard output in the specified archive format.</para> | |
| 223 | </listitem> | |
| 224 | </varlistentry> | |
| 225 | <varlistentry> | |
| 226 | <term><option>-a</option></term> | |
| 227 | <listitem> | |
| 228 | <para>Append files to the end of the archive. It is implementation-defined | |
| 229 | which devices on the system support appending. Additional | |
| 230 | file formats unspecified by this volume of IEEE Std 1003.1-2001 | |
| 231 | may impose restrictions on appending.</para> | |
| 232 | </listitem> | |
| 233 | </varlistentry> | |
| 234 | <varlistentry> | |
| 235 | <term><option>-b </option> <emphasis remap='I'>blocksize</emphasis></term> | |
| 236 | <listitem> | |
| 237 | <para>Block the output at a positive decimal integer number of bytes per | |
| 238 | write to the archive file. Devices and archive formats may | |
| 239 | impose restrictions on blocking. Blocking shall be automatically determined | |
| 240 | on input. Conforming applications shall not specify a | |
| 241 | <emphasis remap='I'>blocksize</emphasis> value larger than 32256. Default blocking when creating | |
| 242 | archives depends on the archive format. (See the <option>-x</option> | |
| 243 | option below.)</para> | |
| 244 | </listitem> | |
| 245 | </varlistentry> | |
| 246 | <varlistentry> | |
| 247 | <term><option>-c</option></term> | |
| 248 | <listitem> | |
| 249 | <para>Match all file or archive members except those specified by the <emphasis remap='I'>pattern</emphasis> | |
| 250 | or <emphasis remap='I'>file</emphasis> operands.</para> | |
| 251 | </listitem> | |
| 252 | </varlistentry> | |
| 253 | <varlistentry> | |
| 254 | <term><option>-d</option></term> | |
| 255 | <listitem> | |
| 256 | <para>Cause files of type directory being copied or archived or archive | |
| 257 | members of type directory being extracted or listed to match | |
| 258 | only the file or archive member itself and not the file hierarchy | |
| 259 | rooted at the file.</para> | |
| 260 | </listitem> | |
| 261 | </varlistentry> | |
| 262 | <varlistentry> | |
| 263 | <term><option>-f </option> <emphasis remap='I'>archive</emphasis></term> | |
| 264 | <listitem> | |
| 265 | <para>Specify the pathname of the input or output archive, overriding the | |
| 266 | default standard input (in <emphasis remap='B'>list</emphasis> or <emphasis remap='B'>read</emphasis> | |
| 267 | modes) or standard output ( <emphasis remap='B'>write</emphasis> mode).</para> | |
| 268 | </listitem> | |
| 269 | </varlistentry> | |
| 270 | <varlistentry> | |
| 271 | <term><option>-H</option></term> | |
| 272 | <listitem> | |
| 273 | <para>If a symbolic link referencing a file of type directory is specified | |
| 274 | on the command line, <command>pax</command> shall archive the file | |
| 275 | hierarchy rooted in the file referenced by the link, using the name | |
| 276 | of the link as the root of the file hierarchy. Otherwise, if a | |
| 277 | symbolic link referencing a file of any other file type which <command>pax</command> | |
| 278 | can normally archive is specified on the command line, | |
| 279 | then <command>pax</command> shall archive the file referenced by the link, using | |
| 280 | the name of the link. The default behavior shall be to archive | |
| 281 | the symbolic link itself.</para> | |
| 282 | </listitem> | |
| 283 | </varlistentry> | |
| 284 | <varlistentry> | |
| 285 | <term><option>-i</option></term> | |
| 286 | <listitem> | |
| 287 | <para>Interactively rename files or archive members. For each archive member | |
| 288 | matching a <emphasis remap='I'>pattern</emphasis> operand or file matching a | |
| 289 | <emphasis remap='I'>file</emphasis> operand, a prompt shall be written to the file <filename>/dev/tty</filename>. | |
| 290 | The prompt shall contain the name of the file or | |
| 291 | archive member, but the format is otherwise unspecified. A line shall | |
| 292 | then be read from <filename>/dev/tty</filename>. If this line is blank, the | |
| 293 | file or archive member shall be skipped. If this line consists of | |
| 294 | a single period, the file or archive member shall be processed | |
| 295 | with no modification to its name. Otherwise, its name shall be replaced | |
| 296 | with the contents of the line. The <command>pax</command> utility shall | |
| 297 | immediately exit with a non-zero exit status if end-of-file is encountered | |
| 298 | when reading a response or if <filename>/dev/tty</filename> cannot be | |
| 299 | opened for reading and writing.</para> | |
| 300 | ||
| 301 | <para>The results of extracting a hard link to a file that has been renamed | |
| 302 | during extraction are unspecified.</para> | |
| 303 | </listitem> | |
| 304 | </varlistentry> | |
| 305 | <varlistentry> | |
| 306 | <term><option>-k</option></term> | |
| 307 | <listitem> | |
| 308 | <para>Prevent the overwriting of existing files.</para> | |
| 309 | </listitem> | |
| 310 | </varlistentry> | |
| 311 | <varlistentry> | |
| 312 | <term><option>-l</option></term> | |
| 313 | <listitem> | |
| 314 | <para>(The letter ell.) In <emphasis remap='B'>copy</emphasis> mode, hard links shall be made between | |
| 315 | the source and destination file hierarchies whenever | |
| 316 | possible. If specified in conjunction with <option>-H</option> or <option>-L</option>, when | |
| 317 | a symbolic link is encountered, the hard link created in | |
| 318 | the destination file hierarchy shall be to the file referenced by | |
| 319 | the symbolic link. If specified when neither <option>-H</option> nor | |
| 320 | <option>-L</option> is specified, when a symbolic link is encountered, the implementation | |
| 321 | shall create a hard link to the symbolic link in | |
| 322 | the source file hierarchy or copy the symbolic link to the destination.</para> | |
| 323 | </listitem> | |
| 324 | </varlistentry> | |
| 325 | <varlistentry> | |
| 326 | <term><option>-L</option></term> | |
| 327 | <listitem> | |
| 328 | <para>If a symbolic link referencing a file of type directory is specified | |
| 329 | on the command line or encountered during the traversal of | |
| 330 | a file hierarchy, <command>pax</command> shall archive the file hierarchy rooted | |
| 331 | in the file referenced by the link, using the name of the link | |
| 332 | as the root of the file hierarchy. Otherwise, if a symbolic link referencing | |
| 333 | a file of any other file type which <command>pax</command> can | |
| 334 | normally archive is specified on the command line or encountered during | |
| 335 | the traversal of a file hierarchy, <command>pax</command> shall archive | |
| 336 | the file referenced by the link, using the name of the link. The default | |
| 337 | behavior shall be to archive the symbolic link | |
| 338 | itself.</para> | |
| 339 | </listitem> | |
| 340 | </varlistentry> | |
| 341 | <varlistentry> | |
| 342 | <term><option>-n</option></term> | |
| 343 | <listitem> | |
| 344 | <para>Select the first archive member that matches each <emphasis remap='I'>pattern</emphasis> operand. | |
| 345 | No more than one archive member shall be matched for | |
| 346 | each pattern (although members of type directory shall still match | |
| 347 | the file hierarchy rooted at that file).</para> | |
| 348 | </listitem> | |
| 349 | </varlistentry> | |
| 350 | <varlistentry> | |
| 351 | <term><option>-o </option> <emphasis remap='I'>options</emphasis></term> | |
| 352 | <listitem> | |
| 353 | <para>Provide information to the implementation to modify the algorithm | |
| 354 | for extracting or writing files. The value of <emphasis remap='I'>options</emphasis> | |
| 355 | shall consist of one or more comma-separated keywords of the form:</para> | |
| 356 | ||
| 357 | <literallayout remap='.nf'> | |
| 358 | ||
| 359 | <emphasis remap='I'>keyword</emphasis><emphasis remap='B'>[[</emphasis><emphasis remap='B'>:</emphasis><emphasis remap='B'>]</emphasis><emphasis remap='B'>=</emphasis><emphasis remap='I'>value</emphasis><emphasis remap='B'>][</emphasis><emphasis remap='B'>,</emphasis><emphasis remap='I'>keyword</emphasis><emphasis remap='B'>[[</emphasis><emphasis remap='B'>:</emphasis><emphasis remap='B'>]</emphasis><emphasis remap='B'>=</emphasis><emphasis remap='I'>value</emphasis><emphasis remap='B'>]</emphasis><emphasis remap='B'>, ...</emphasis><emphasis remap='B'>]</emphasis> | |
| 360 | </literallayout> <!-- .fi --> | |
| 361 | ||
| 362 | <para>Some keywords apply only to certain file formats, as indicated with | |
| 363 | each description. Use of keywords that are inapplicable to | |
| 364 | the file format being processed produces undefined results.</para> | |
| 365 | ||
| 366 | <para>Keywords in the <emphasis remap='I'>options</emphasis> argument shall be a string that would | |
| 367 | be a valid portable filename as described in the Base | |
| 368 | Definitions volume of IEEE Std 1003.1-2001, Section 3.276, Portable | |
| 369 | Filename Character Set.</para> | |
| 370 | </listitem> | |
| 371 | </varlistentry> | |
| 372 | <varlistentry> | |
| 373 | <term><emphasis remap='B'>Note:</emphasis></term> | |
| 374 | <listitem> | |
| 375 | <blockquote remap='RS'> | |
| 376 | <para>Keywords are not expected to be filenames, merely to follow the same | |
| 377 | character composition rules as portable filenames. | |
| 378 | </para></blockquote> <!-- remap='RE' --> | |
| 379 | ||
| 380 | ||
| 381 | <para>Keywords can be preceded with white space. The <emphasis remap='I'>value</emphasis> field shall | |
| 382 | consist of zero or more characters; within <emphasis remap='I'>value</emphasis>, | |
| 383 | the application shall precede any literal comma with a backslash, | |
| 384 | which shall be ignored, but preserves the comma as part of | |
| 385 | <emphasis remap='I'>value</emphasis>. A comma as the final character, or a comma followed solely | |
| 386 | by white space as the final characters, in <emphasis remap='I'>options</emphasis> | |
| 387 | shall be ignored. Multiple <option>-o</option> options can be specified; if keywords | |
| 388 | given to these multiple <option>-o</option> options conflict, the | |
| 389 | keywords and values appearing later in command line sequence shall | |
| 390 | take precedence and the earlier shall be silently ignored. The | |
| 391 | following keyword values of <emphasis remap='I'>options</emphasis> shall be supported for the | |
| 392 | file formats as indicated:</para> | |
| 393 | </listitem> | |
| 394 | </varlistentry> | |
| 395 | <varlistentry> | |
| 396 | <term><emphasis remap='B'>delete</emphasis>=<emphasis remap='I'>pattern</emphasis></term> | |
| 397 | <listitem> | |
| 398 | <blockquote remap='RS'> | |
| 399 | ||
| 400 | <para>(Applicable only to the <option>-x</option> <replaceable>pax</replaceable> format.) When used in <emphasis remap='B'>write</emphasis> | |
| 401 | or <emphasis remap='B'>copy</emphasis> mode, <command>pax</command> shall omit from | |
| 402 | extended header records that it produces any keywords matching the | |
| 403 | string pattern. When used in <emphasis remap='B'>read</emphasis> or <emphasis remap='B'>list</emphasis> mode, | |
| 404 | <command>pax</command> shall ignore any keywords matching the string pattern in | |
| 405 | the extended header records. In both cases, matching shall be | |
| 406 | performed using the pattern matching notation described in <emphasis remap='I'>Patterns | |
| 407 | Matching a Single | |
| 408 | Character</emphasis> and <emphasis remap='I'>Patterns Matching Multiple Characters</emphasis> . For | |
| 409 | example:</para> | |
| 410 | ||
| 411 | <literallayout remap='.nf'> | |
| 412 | ||
| 413 | <option>-o</option> <replaceable>delete</replaceable><emphasis remap='B'>=</emphasis><emphasis remap='I'>security</emphasis><emphasis remap='B'>.* | |
| 414 | </emphasis> | |
| 415 | </literallayout> <!-- .fi --> | |
| 416 | ||
| 417 | <para>would suppress security-related information. See pax Extended Header | |
| 418 | for extended header record | |
| 419 | keyword usage. | |
| 420 | </para></blockquote> <!-- remap='RE' --> | |
| 421 | </listitem> | |
| 422 | </varlistentry> | |
| 423 | <varlistentry> | |
| 424 | <term><emphasis remap='B'>exthdr.name</emphasis>=<emphasis remap='I'>string</emphasis></term> | |
| 425 | <listitem> | |
| 426 | <blockquote remap='RS'> | |
| 427 | ||
| 428 | <para>(Applicable only to the <option>-x</option> <replaceable>pax</replaceable> format.) This keyword allows | |
| 429 | user control over the name that is written into the | |
| 430 | <emphasis remap='B'>ustar</emphasis> header blocks for the extended header produced under the | |
| 431 | circumstances described in pax | |
| 432 | Header Block . The name shall be the contents of <emphasis remap='I'>string</emphasis>, after | |
| 433 | the following character substitutions have been made:</para> | |
| 434 | ||
| 435 | <informaltable pgwide='0' frame='none'> | |
| 436 | <tgroup cols='6' align='center'> | |
| 437 | <colspec colname='c1'/> | |
| 438 | <colspec colname='c2'/> | |
| 439 | <colspec colname='c3'/> | |
| 440 | <colspec colname='c4'/> | |
| 441 | <colspec colname='c5'/> | |
| 442 | <colspec colname='c6'/> | |
| 443 | <tbody> | |
| 444 | <row> | |
| 445 | <entry align='center'><emphasis remap='I'>string</emphasis></entry> | |
| 446 | <entry align='right'><!-- na --> | |
| 447 | <para><emphasis remap='B'> </emphasis> | |
| 448 | <!-- ad --></para></entry> | |
| 449 | </row> | |
| 450 | <row> | |
| 451 | <entry align='center'><emphasis remap='B'>Includes:</emphasis></entry> | |
| 452 | <entry align='right'><!-- na --> | |
| 453 | <emphasis remap='B'>Replaced By:</emphasis> | |
| 454 | <!-- ad --></entry> | |
| 455 | </row> | |
| 456 | <row> | |
| 457 | <entry align='center'>%d</entry> | |
| 458 | <entry align='right'><!-- na --> | |
| 459 | The directory name of the file, equivalent to the result of the <emphasis remap='I'>dirname</emphasis> utility on the translated pathname. | |
| 460 | <!-- ad --></entry> | |
| 461 | </row> | |
| 462 | <row> | |
| 463 | <entry align='center'>%f</entry> | |
| 464 | <entry align='right'><!-- na --> | |
| 465 | The filename of the file, equivalent to the result of the <emphasis remap='I'>basename</emphasis> utility on the translated pathname. | |
| 466 | <!-- ad --></entry> | |
| 467 | </row> | |
| 468 | <row> | |
| 469 | <entry align='center'>%p</entry> | |
| 470 | <entry align='right'><!-- na --> | |
| 471 | The process ID of the <command>pax</command> process. | |
| 472 | <!-- ad --></entry> | |
| 473 | </row> | |
| 474 | <row> | |
| 475 | <entry align='center'>%%</entry> | |
| 476 | <entry align='right'><!-- na --> | |
| 477 | A <emphasis remap='B'>'%'</emphasis> character. | |
| 478 | <!-- ad --></entry> | |
| 479 | </row> | |
| 480 | </tbody> | |
| 481 | </tgroup> | |
| 482 | </informaltable> | |
| 483 | ||
| 484 | ||
| 485 | ||
| 486 | <para>Any other <emphasis remap='B'>'%'</emphasis> characters in <emphasis remap='I'>string</emphasis> produce undefined results.</para> | |
| 487 | ||
| 488 | <para>If no <option>-o</option> <replaceable>exthdr.name=</replaceable> <emphasis remap='I'>string</emphasis> is specified, <command>pax</command> | |
| 489 | shall use the following default value:</para> | |
| 490 | ||
| 491 | <literallayout remap='.nf'> | |
| 492 | ||
| 493 | <emphasis remap='B'>%d/PaxHeaders.%p/%f | |
| 494 | </emphasis> | |
| 495 | </literallayout> <!-- .fi --> | |
| 496 | </blockquote> <!-- remap='RE' --> | |
| 497 | </listitem> | |
| 498 | </varlistentry> | |
| 499 | <varlistentry> | |
| 500 | <term><emphasis remap='B'>globexthdr.name</emphasis>=<emphasis remap='I'>string</emphasis></term> | |
| 501 | <listitem> | |
| 502 | <blockquote remap='RS'> | |
| 503 | ||
| 504 | <para>(Applicable only to the <option>-x</option> <replaceable>pax</replaceable> format.) When used in <emphasis remap='B'>write</emphasis> | |
| 505 | or <emphasis remap='B'>copy</emphasis> mode with the appropriate options, | |
| 506 | <command>pax</command> shall create global extended header records with <emphasis remap='B'>ustar</emphasis> | |
| 507 | header blocks that will be treated as regular files by | |
| 508 | previous versions of <command>pax</command>. This keyword allows user control over | |
| 509 | the name that is written into the <emphasis remap='B'>ustar</emphasis> header blocks | |
| 510 | for global extended header records. The name shall be the contents | |
| 511 | of string, after the following character substitutions have been | |
| 512 | made:</para> | |
| 513 | ||
| 514 | <informaltable pgwide='0' frame='none'> | |
| 515 | <tgroup cols='6' align='center'> | |
| 516 | <colspec colname='c1'/> | |
| 517 | <colspec colname='c2'/> | |
| 518 | <colspec colname='c3'/> | |
| 519 | <colspec colname='c4'/> | |
| 520 | <colspec colname='c5'/> | |
| 521 | <colspec colname='c6'/> | |
| 522 | <tbody> | |
| 523 | <row> | |
| 524 | <entry align='center'><emphasis remap='I'>string</emphasis></entry> | |
| 525 | <entry align='right'><!-- na --> | |
| 526 | <para><emphasis remap='B'> </emphasis> | |
| 527 | <!-- ad --></para></entry> | |
| 528 | </row> | |
| 529 | <row> | |
| 530 | <entry align='center'><emphasis remap='B'>Includes:</emphasis></entry> | |
| 531 | <entry align='right'><!-- na --> | |
| 532 | <emphasis remap='B'>Replaced By:</emphasis> | |
| 533 | <!-- ad --></entry> | |
| 534 | </row> | |
| 535 | <row> | |
| 536 | <entry align='center'>%n</entry> | |
| 537 | <entry align='right'><!-- na --> | |
| 538 | An integer that represents the sequence number of the global extended header record in the archive, starting at 1. | |
| 539 | <!-- ad --></entry> | |
| 540 | </row> | |
| 541 | <row> | |
| 542 | <entry align='center'>%p</entry> | |
| 543 | <entry align='right'><!-- na --> | |
| 544 | The process ID of the <command>pax</command> process. | |
| 545 | <!-- ad --></entry> | |
| 546 | </row> | |
| 547 | <row> | |
| 548 | <entry align='center'>%%</entry> | |
| 549 | <entry align='right'><!-- na --> | |
| 550 | A <emphasis remap='B'>'%'</emphasis> character. | |
| 551 | <!-- ad --></entry> | |
| 552 | </row> | |
| 553 | </tbody> | |
| 554 | </tgroup> | |
| 555 | </informaltable> | |
| 556 | ||
| 557 | ||
| 558 | ||
| 559 | <para>Any other <emphasis remap='B'>'%'</emphasis> characters in <emphasis remap='I'>string</emphasis> produce undefined results.</para> | |
| 560 | ||
| 561 | <para>If no <option>-o</option> <replaceable>globexthdr.name=</replaceable> <emphasis remap='I'>string</emphasis> is specified, <command>pax</command> | |
| 562 | shall use the following default value:</para> | |
| 563 | ||
| 564 | <literallayout remap='.nf'> | |
| 565 | ||
| 566 | <emphasis remap='B'>$TMPDIR/GlobalHead.%p.%n | |
| 567 | </emphasis> | |
| 568 | </literallayout> <!-- .fi --> | |
| 569 | ||
| 570 | <para>where $ <envar>TMPDIR</envar> represents the value of the <envar>TMPDIR</envar> environment | |
| 571 | variable. If <envar>TMPDIR</envar> is not set, <command>pax</command> | |
| 572 | shall use <filename>/tmp</filename>. | |
| 573 | </para></blockquote> <!-- remap='RE' --> | |
| 574 | </listitem> | |
| 575 | </varlistentry> | |
| 576 | <varlistentry> | |
| 577 | <term><emphasis remap='B'>invalid</emphasis>=<emphasis remap='I'>action</emphasis></term> | |
| 578 | <listitem> | |
| 579 | <blockquote remap='RS'> | |
| 580 | ||
| 581 | <para>(Applicable only to the <option>-x</option> <replaceable>pax</replaceable> format.) This keyword allows | |
| 582 | user control over the action <command>pax</command> takes upon | |
| 583 | encountering values in an extended header record that, in <emphasis remap='B'>read</emphasis> | |
| 584 | or <emphasis remap='B'>copy</emphasis> mode, are invalid in the destination hierarchy | |
| 585 | or, in <emphasis remap='B'>list</emphasis> mode, cannot be written in the codeset and current | |
| 586 | locale of the implementation. The following are invalid | |
| 587 | values that shall be recognized by <command>pax</command>:</para> | |
| 588 | <variablelist remap='IP'> | |
| 589 | <varlistentry> | |
| 590 | <term> *</term> | |
| 591 | <listitem> | |
| 592 | <para>In <emphasis remap='B'>read</emphasis> or <emphasis remap='B'>copy</emphasis> mode, a filename or link name that contains | |
| 593 | character encodings invalid in the destination | |
| 594 | hierarchy. (For example, the name may contain embedded NULs.)</para> | |
| 595 | ||
| 596 | </listitem> | |
| 597 | </varlistentry> | |
| 598 | <varlistentry> | |
| 599 | <term> *</term> | |
| 600 | <listitem> | |
| 601 | <para>In <emphasis remap='B'>read</emphasis> or <emphasis remap='B'>copy</emphasis> mode, a filename or link name that is | |
| 602 | longer than the maximum allowed in the destination hierarchy | |
| 603 | (for either a pathname component or the entire pathname).</para> | |
| 604 | ||
| 605 | </listitem> | |
| 606 | </varlistentry> | |
| 607 | <varlistentry> | |
| 608 | <term> *</term> | |
| 609 | <listitem> | |
| 610 | <para>In <emphasis remap='B'>list</emphasis> mode, any character string value (filename, link name, | |
| 611 | user name, and so on) that cannot be written in the | |
| 612 | codeset and current locale of the implementation.</para> | |
| 613 | ||
| 614 | </listitem> | |
| 615 | </varlistentry> | |
| 616 | </variablelist> | |
| 617 | ||
| 618 | <para>The following mutually-exclusive values of the <emphasis remap='I'>action</emphasis> argument | |
| 619 | are supported:</para> | |
| 620 | <variablelist remap='TP'> | |
| 621 | <varlistentry> | |
| 622 | <term><emphasis remap='B'>bypass</emphasis></term> | |
| 623 | <listitem> | |
| 624 | <blockquote remap='RS'> | |
| 625 | <para>In <emphasis remap='B'>read</emphasis> or <emphasis remap='B'>copy</emphasis> mode, <command>pax</command> shall bypass the file, | |
| 626 | causing no change to the destination hierarchy. In | |
| 627 | <emphasis remap='B'>list</emphasis> mode, <command>pax</command> shall write all requested valid values | |
| 628 | for the file, but its method for writing invalid values is | |
| 629 | unspecified. | |
| 630 | </para></blockquote> <!-- remap='RE' --> | |
| 631 | </listitem> | |
| 632 | </varlistentry> | |
| 633 | <varlistentry> | |
| 634 | <term><emphasis remap='B'>rename</emphasis></term> | |
| 635 | <listitem> | |
| 636 | <blockquote remap='RS'> | |
| 637 | <para>In <emphasis remap='B'>read</emphasis> or <emphasis remap='B'>copy</emphasis> mode, <command>pax</command> shall act as if the <option>-i</option> | |
| 638 | option were in effect for each file with invalid | |
| 639 | filename or link name values, allowing the user to provide a replacement | |
| 640 | name interactively. In <emphasis remap='B'>list</emphasis> mode, <command>pax</command> shall | |
| 641 | behave identically to the <emphasis remap='B'>bypass</emphasis> action. | |
| 642 | </para></blockquote> <!-- remap='RE' --> | |
| 643 | </listitem> | |
| 644 | </varlistentry> | |
| 645 | <varlistentry> | |
| 646 | <term><emphasis remap='B'>UTF-8</emphasis></term> | |
| 647 | <listitem> | |
| 648 | <blockquote remap='RS'> | |
| 649 | <para>When used in <emphasis remap='B'>read</emphasis>, <emphasis remap='B'>copy</emphasis>, or <emphasis remap='B'>list</emphasis> mode and a filename, | |
| 650 | link name, owner name, or any other field in an | |
| 651 | extended header record cannot be translated from the <command>pax</command> UTF-8 | |
| 652 | codeset format to the codeset and current locale of the | |
| 653 | implementation, <command>pax</command> shall use the actual UTF-8 encoding for | |
| 654 | the name. | |
| 655 | </para></blockquote> <!-- remap='RE' --> | |
| 656 | </listitem> | |
| 657 | </varlistentry> | |
| 658 | <varlistentry> | |
| 659 | <term><emphasis remap='B'>write</emphasis></term> | |
| 660 | <listitem> | |
| 661 | <blockquote remap='RS'> | |
| 662 | <para>In <emphasis remap='B'>read</emphasis> or <emphasis remap='B'>copy</emphasis> mode, <command>pax</command> shall write the file, | |
| 663 | translating or truncating the name, regardless of whether | |
| 664 | this may overwrite an existing file with a valid name. In <emphasis remap='B'>list</emphasis> | |
| 665 | mode, <command>pax</command> shall behave identically to the | |
| 666 | <emphasis remap='B'>bypass</emphasis> action. | |
| 667 | </para></blockquote> <!-- remap='RE' --> | |
| 668 | ||
| 669 | ||
| 670 | <para>If no <option>-o</option> <replaceable>invalid=</replaceable> option is specified, <command>pax</command> shall | |
| 671 | act as if <option>-o</option> <replaceable>invalid=</replaceable> <emphasis remap='B'>bypass</emphasis> were | |
| 672 | specified. Any overwriting of existing files that may be allowed by | |
| 673 | the <option>-o</option> <replaceable>invalid=</replaceable> actions shall be subject to | |
| 674 | permission ( <option>-p</option>) and modification time ( <option>-u</option>) restrictions, | |
| 675 | and shall be suppressed if the <option>-k</option> option is also | |
| 676 | specified.</para> | |
| 677 | </listitem> | |
| 678 | </varlistentry> | |
| 679 | </variablelist> | |
| 680 | </blockquote> <!-- remap='RE' --> | |
| 681 | </listitem> | |
| 682 | </varlistentry> | |
| 683 | <varlistentry> | |
| 684 | <term><emphasis remap='B'>linkdata</emphasis></term> | |
| 685 | <listitem> | |
| 686 | <blockquote remap='RS'> | |
| 687 | ||
| 688 | <para>(Applicable only to the <option>-x</option> <replaceable>pax</replaceable> format.) In <emphasis remap='B'>write</emphasis> | |
| 689 | mode, <command>pax</command> shall write the contents of a file to the | |
| 690 | archive even when that file is merely a hard link to a file whose | |
| 691 | contents have already been written to the archive. | |
| 692 | </para></blockquote> <!-- remap='RE' --> | |
| 693 | </listitem> | |
| 694 | </varlistentry> | |
| 695 | <varlistentry> | |
| 696 | <term><emphasis remap='B'>listopt</emphasis>=<emphasis remap='I'>format</emphasis></term> | |
| 697 | <listitem> | |
| 698 | <blockquote remap='RS'> | |
| 699 | ||
| 700 | <para>This keyword specifies the output format of the table of contents | |
| 701 | produced when the <option>-v</option> option is specified in <emphasis remap='B'>list</emphasis> | |
| 702 | mode. See List Mode Format Specifications . To avoid ambiguity, the | |
| 703 | <emphasis remap='B'>listopt=</emphasis> <emphasis remap='I'>format</emphasis> | |
| 704 | shall be the only or final <emphasis remap='B'>keyword=</emphasis> <emphasis remap='I'>value</emphasis> pair in a <option>-o</option> | |
| 705 | option-argument; all characters in the remainder of the | |
| 706 | option-argument shall be considered part of the format string. When | |
| 707 | multiple <option>-o</option> <replaceable>listopt=</replaceable> <emphasis remap='I'>format</emphasis> options are | |
| 708 | specified, the format strings shall be considered a single, concatenated | |
| 709 | string, evaluated in command line order. | |
| 710 | </para></blockquote> <!-- remap='RE' --> | |
| 711 | </listitem> | |
| 712 | </varlistentry> | |
| 713 | <varlistentry> | |
| 714 | <term><emphasis remap='B'>times</emphasis></term> | |
| 715 | <listitem> | |
| 716 | <blockquote remap='RS'> | |
| 717 | ||
| 718 | <para>(Applicable only to the <option>-x</option> <replaceable>pax</replaceable> format.) When used in <emphasis remap='B'>write</emphasis> | |
| 719 | or <emphasis remap='B'>copy</emphasis> mode, <command>pax</command> shall include | |
| 720 | <emphasis remap='B'>atime</emphasis>, <emphasis remap='B'>ctime</emphasis>, and <emphasis remap='B'>mtime</emphasis> extended header records | |
| 721 | for each file. See pax Extended | |
| 722 | Header File Times . | |
| 723 | </para></blockquote> <!-- remap='RE' --> | |
| 724 | ||
| 725 | ||
| 726 | <para>In addition to these keywords, if the <option>-x</option> <replaceable>pax</replaceable> format is | |
| 727 | specified, any of the keywords and values defined in pax Extended | |
| 728 | Header , including implementation extensions, can be used in <option>-o</option> | |
| 729 | option-arguments, | |
| 730 | in either of two modes:</para> | |
| 731 | </listitem> | |
| 732 | </varlistentry> | |
| 733 | <varlistentry> | |
| 734 | <term><emphasis remap='B'>keyword</emphasis>=<emphasis remap='I'>value</emphasis></term> | |
| 735 | <listitem> | |
| 736 | <blockquote remap='RS'> | |
| 737 | ||
| 738 | <para>When used in <emphasis remap='B'>write</emphasis> or <emphasis remap='B'>copy</emphasis> mode, these keyword/value pairs | |
| 739 | shall be included at the beginning of the archive as | |
| 740 | <emphasis remap='B'>typeflag</emphasis> <emphasis remap='B'>g</emphasis> global extended header records. When used in | |
| 741 | <emphasis remap='B'>read</emphasis> or <emphasis remap='B'>list</emphasis> mode, these keyword/value pairs | |
| 742 | shall act as if they had been at the beginning of the archive as <emphasis remap='B'>typeflag</emphasis> | |
| 743 | <emphasis remap='B'>g</emphasis> global extended header records. | |
| 744 | </para></blockquote> <!-- remap='RE' --> | |
| 745 | </listitem> | |
| 746 | </varlistentry> | |
| 747 | <varlistentry> | |
| 748 | <term><emphasis remap='B'>keyword</emphasis>:=<emphasis remap='I'>value</emphasis></term> | |
| 749 | <listitem> | |
| 750 | <blockquote remap='RS'> | |
| 751 | ||
| 752 | <para>When used in <emphasis remap='B'>write</emphasis> or <emphasis remap='B'>copy</emphasis> mode, these keyword/value pairs | |
| 753 | shall be included as records at the beginning of a | |
| 754 | <emphasis remap='B'>typeflag</emphasis> <emphasis remap='B'>x</emphasis> extended header for each file. (This shall | |
| 755 | be equivalent to the equal-sign form except that it creates no | |
| 756 | <emphasis remap='B'>typeflag</emphasis> <emphasis remap='B'>g</emphasis> global extended header records.) When used | |
| 757 | in <emphasis remap='B'>read</emphasis> or <emphasis remap='B'>list</emphasis> mode, these keyword/value pairs | |
| 758 | shall act as if they were included as records at the end of each extended | |
| 759 | header; thus, they shall override any global or | |
| 760 | file-specific extended header record keywords of the same names. For | |
| 761 | example, in the command:</para> | |
| 762 | ||
| 763 | <literallayout remap='.nf'> | |
| 764 | ||
| 765 | <userinput>pax -r -o " | |
| 766 | gname:=mygroup, | |
| 767 | " <archive | |
| 768 | </userinput> | |
| 769 | </literallayout> <!-- .fi --> | |
| 770 | ||
| 771 | <para>the group name will be forced to a new value for all files read from | |
| 772 | the archive. | |
| 773 | </para></blockquote> <!-- remap='RE' --> | |
| 774 | ||
| 775 | ||
| 776 | <para>The precedence of <option>-o</option> keywords over various fields in the archive | |
| 777 | is described in pax Extended | |
| 778 | Header Keyword Precedence .</para> | |
| 779 | </listitem> | |
| 780 | </varlistentry> | |
| 781 | <varlistentry> | |
| 782 | <term><option>-p </option> <emphasis remap='I'>string</emphasis></term> | |
| 783 | <listitem> | |
| 784 | <para>Specify one or more file characteristic options (privileges). The | |
| 785 | <emphasis remap='I'>string</emphasis> option-argument shall be a string specifying | |
| 786 | file characteristics to be retained or discarded on extraction. The | |
| 787 | string shall consist of the specification characters <emphasis remap='B'>a</emphasis> | |
| 788 | , <emphasis remap='B'>e</emphasis> , <emphasis remap='B'>m</emphasis> , <emphasis remap='B'>o</emphasis> , and <emphasis remap='B'>p</emphasis> . Other implementation-defined | |
| 789 | characters can be included. Multiple | |
| 790 | characteristics can be concatenated within the same string and multiple | |
| 791 | <option>-p</option> options can be specified. The meaning of the | |
| 792 | specification characters are as follows:</para> | |
| 793 | </listitem> | |
| 794 | </varlistentry> | |
| 795 | <varlistentry> | |
| 796 | <term><emphasis remap='B'>a</emphasis></term> | |
| 797 | <listitem> | |
| 798 | <blockquote remap='RS'> | |
| 799 | <para>Do not preserve file access times. | |
| 800 | </para></blockquote> <!-- remap='RE' --> | |
| 801 | </listitem> | |
| 802 | </varlistentry> | |
| 803 | <varlistentry> | |
| 804 | <term><emphasis remap='B'>e</emphasis></term> | |
| 805 | <listitem> | |
| 806 | <blockquote remap='RS'> | |
| 807 | <para>Preserve the user ID, group ID, file mode bits (see the Base Definitions | |
| 808 | volume of IEEE Std 1003.1-2001, Section 3.168, File Mode Bits), | |
| 809 | access time, modification time, and any other | |
| 810 | implementation-defined file characteristics. | |
| 811 | </para></blockquote> <!-- remap='RE' --> | |
| 812 | </listitem> | |
| 813 | </varlistentry> | |
| 814 | <varlistentry> | |
| 815 | <term><emphasis remap='B'>m</emphasis></term> | |
| 816 | <listitem> | |
| 817 | <blockquote remap='RS'> | |
| 818 | <para>Do not preserve file modification times. | |
| 819 | </para></blockquote> <!-- remap='RE' --> | |
| 820 | </listitem> | |
| 821 | </varlistentry> | |
| 822 | <varlistentry> | |
| 823 | <term><emphasis remap='B'>o</emphasis></term> | |
| 824 | <listitem> | |
| 825 | <blockquote remap='RS'> | |
| 826 | <para>Preserve the user ID and group ID. | |
| 827 | </para></blockquote> <!-- remap='RE' --> | |
| 828 | </listitem> | |
| 829 | </varlistentry> | |
| 830 | <varlistentry> | |
| 831 | <term><emphasis remap='B'>p</emphasis></term> | |
| 832 | <listitem> | |
| 833 | <blockquote remap='RS'> | |
| 834 | <para>Preserve the file mode bits. Other implementation-defined file mode | |
| 835 | attributes may be preserved. | |
| 836 | </para></blockquote> <!-- remap='RE' --> | |
| 837 | ||
| 838 | ||
| 839 | <para>In the preceding list, "preserve" indicates that an attribute stored | |
| 840 | in the archive shall be given to the extracted file, | |
| 841 | subject to the permissions of the invoking process. The access and | |
| 842 | modification times of the file shall be preserved unless | |
| 843 | otherwise specified with the <option>-p</option> option or not stored in the | |
| 844 | archive. All attributes that are not preserved shall be | |
| 845 | determined as part of the normal file creation action (see <emphasis remap='I'>File | |
| 846 | Read, Write, and | |
| 847 | Creation</emphasis> ).</para> | |
| 848 | ||
| 849 | <para>If neither the <emphasis remap='B'>e</emphasis> nor the <emphasis remap='B'>o</emphasis> specification character is | |
| 850 | specified, or the user ID and group ID are not preserved | |
| 851 | for any reason, <command>pax</command> shall not set the S_ISUID and S_ISGID bits | |
| 852 | of the file mode.</para> | |
| 853 | ||
| 854 | <para>If the preservation of any of these items fails for any reason, <command>pax</command> | |
| 855 | shall write a diagnostic message to standard error. | |
| 856 | Failure to preserve these items shall affect the final exit status, | |
| 857 | but shall not cause the extracted file to be deleted.</para> | |
| 858 | ||
| 859 | <para>If file characteristic letters in any of the <emphasis remap='I'>string</emphasis> option-arguments | |
| 860 | are duplicated or conflict with each other, the ones | |
| 861 | given last shall take precedence. For example, if <option>-p</option> <replaceable>eme</replaceable> | |
| 862 | is specified, file modification times are preserved.</para> | |
| 863 | </listitem> | |
| 864 | </varlistentry> | |
| 865 | <varlistentry> | |
| 866 | <term><option>-s </option> <emphasis remap='I'>replstr</emphasis></term> | |
| 867 | <listitem> | |
| 868 | <para>Modify file or archive member names named by <emphasis remap='I'>pattern</emphasis> or <emphasis remap='I'>file</emphasis> | |
| 869 | operands according to the substitution expression | |
| 870 | <emphasis remap='I'>replstr</emphasis>, using the syntax of the <emphasis remap='I'>ed</emphasis> utility. The concepts | |
| 871 | of "address" and | |
| 872 | "line" are meaningless in the context of the <command>pax</command> utility, and | |
| 873 | shall not be supplied. The format shall be:</para> | |
| 874 | ||
| 875 | <literallayout remap='.nf'> | |
| 876 | ||
| 877 | <option>-s /</option><emphasis remap='I'>old</emphasis><emphasis remap='B'>/</emphasis><emphasis remap='I'>new</emphasis><emphasis remap='B'>/</emphasis><emphasis remap='B'>[</emphasis><emphasis remap='B'>gp</emphasis><emphasis remap='B'>]</emphasis> | |
| 878 | </literallayout> <!-- .fi --> | |
| 879 | ||
| 880 | <para>where as in <emphasis remap='I'>ed</emphasis>, <emphasis remap='I'>old</emphasis> is a basic regular expression and | |
| 881 | <emphasis remap='I'>new</emphasis> can contain an | |
| 882 | ampersand, <emphasis remap='B'>'\n'</emphasis> (where <emphasis remap='I'>n</emphasis> is a digit) backreferences, | |
| 883 | or subexpression matching. The <emphasis remap='I'>old</emphasis> string shall also be | |
| 884 | permitted to contain <newline>s.</para> | |
| 885 | ||
| 886 | <para>Any non-null character can be used as a delimiter ( <emphasis remap='B'>'/'</emphasis> shown | |
| 887 | here). Multiple <option>-s</option> expressions can be specified; | |
| 888 | the expressions shall be applied in the order specified, terminating | |
| 889 | with the first successful substitution. The optional trailing | |
| 890 | <emphasis remap='B'>'g'</emphasis> is as defined in the <emphasis remap='I'>ed</emphasis> utility. The optional trailing | |
| 891 | <emphasis remap='B'>'p'</emphasis> shall | |
| 892 | cause successful substitutions to be written to standard error. File | |
| 893 | or archive member names that substitute to the empty string | |
| 894 | shall be ignored when reading and writing archives.</para> | |
| 895 | </listitem> | |
| 896 | </varlistentry> | |
| 897 | <varlistentry> | |
| 898 | <term><option>-t</option></term> | |
| 899 | <listitem> | |
| 900 | <para>When reading files from the file system, and if the user has the permissions | |
| 901 | required by <emphasis remap='I'>utime</emphasis>() to do so, set the access time of each file | |
| 902 | read to the access time that it had before | |
| 903 | being read by <command>pax</command>.</para> | |
| 904 | </listitem> | |
| 905 | </varlistentry> | |
| 906 | <varlistentry> | |
| 907 | <term><option>-u</option></term> | |
| 908 | <listitem> | |
| 909 | <para>Ignore files that are older (having a less recent file modification | |
| 910 | time) than a pre-existing file or archive member with the | |
| 911 | same name. In <emphasis remap='B'>read</emphasis> mode, an archive member with the same name | |
| 912 | as a file in the file system shall be extracted if the archive | |
| 913 | member is newer than the file. In <emphasis remap='B'>write</emphasis> mode, an archive file | |
| 914 | member with the same name as a file in the file system shall | |
| 915 | be superseded if the file is newer than the archive member. If <option>-a</option> | |
| 916 | is also specified, this is accomplished by appending to | |
| 917 | the archive; otherwise, it is unspecified whether this is accomplished | |
| 918 | by actual replacement in the archive or by appending to the | |
| 919 | archive. In <emphasis remap='B'>copy</emphasis> mode, the file in the destination hierarchy | |
| 920 | shall be replaced by the file in the source hierarchy or by a | |
| 921 | link to the file in the source hierarchy if the file in the source | |
| 922 | hierarchy is newer.</para> | |
| 923 | </listitem> | |
| 924 | </varlistentry> | |
| 925 | <varlistentry> | |
| 926 | <term><option>-v</option></term> | |
| 927 | <listitem> | |
| 928 | <para>In <emphasis remap='B'>list</emphasis> mode, produce a verbose table of contents (see the STDOUT | |
| 929 | section). Otherwise, write archive member pathnames to | |
| 930 | standard error (see the STDERR section).</para> | |
| 931 | </listitem> | |
| 932 | </varlistentry> | |
| 933 | <varlistentry> | |
| 934 | <term><option>-x </option> <emphasis remap='I'>format</emphasis></term> | |
| 935 | <listitem> | |
| 936 | <para>Specify the output archive format. The <command>pax</command> utility shall support | |
| 937 | the following formats:</para> | |
| 938 | </listitem> | |
| 939 | </varlistentry> | |
| 940 | <varlistentry> | |
| 941 | <term><emphasis remap='B'>cpio</emphasis></term> | |
| 942 | <listitem> | |
| 943 | <blockquote remap='RS'> | |
| 944 | <para>The <emphasis remap='B'>cpio</emphasis> interchange format; see the EXTENDED DESCRIPTION section. | |
| 945 | The default <emphasis remap='I'>blocksize</emphasis> for this format for | |
| 946 | character special archive files shall be 5120. Implementations shall | |
| 947 | support all <emphasis remap='I'>blocksize</emphasis> values less than or equal to | |
| 948 | 32256 that are multiples of 512. | |
| 949 | </para></blockquote> <!-- remap='RE' --> | |
| 950 | </listitem> | |
| 951 | </varlistentry> | |
| 952 | <varlistentry> | |
| 953 | <term><command>pax</command></term> | |
| 954 | <listitem> | |
| 955 | <blockquote remap='RS'> | |
| 956 | <para>The <command>pax</command> interchange format; see the EXTENDED DESCRIPTION section. | |
| 957 | The default <emphasis remap='I'>blocksize</emphasis> for this format for | |
| 958 | character special archive files shall be 5120. Implementations shall | |
| 959 | support all <emphasis remap='I'>blocksize</emphasis> values less than or equal to | |
| 960 | 32256 that are multiples of 512. | |
| 961 | </para></blockquote> <!-- remap='RE' --> | |
| 962 | </listitem> | |
| 963 | </varlistentry> | |
| 964 | <varlistentry> | |
| 965 | <term><emphasis remap='B'>ustar</emphasis></term> | |
| 966 | <listitem> | |
| 967 | <blockquote remap='RS'> | |
| 968 | <para>The <emphasis remap='B'>tar</emphasis> interchange format; see the EXTENDED DESCRIPTION section. | |
| 969 | The default <emphasis remap='I'>blocksize</emphasis> for this format for | |
| 970 | character special archive files shall be 10240. Implementations shall | |
| 971 | support all <emphasis remap='I'>blocksize</emphasis> values less than or equal to | |
| 972 | 32256 that are multiples of 512. | |
| 973 | </para></blockquote> <!-- remap='RE' --> | |
| 974 | ||
| 975 | ||
| 976 | <para>Implementation-defined formats shall specify a default block size | |
| 977 | as well as any other block sizes supported for character | |
| 978 | special archive files.</para> | |
| 979 | ||
| 980 | <para>Any attempt to append to an archive file in a format different from | |
| 981 | the existing archive format shall cause <command>pax</command> to exit | |
| 982 | immediately with a non-zero exit status.</para> | |
| 983 | ||
| 984 | <para>In <emphasis remap='B'>copy</emphasis> mode, if no <option>-x</option> format is specified, <command>pax</command> | |
| 985 | shall behave as if <option>-x</option> <replaceable>pax</replaceable> were specified.</para> | |
| 986 | </listitem> | |
| 987 | </varlistentry> | |
| 988 | <varlistentry> | |
| 989 | <term><option>-X</option></term> | |
| 990 | <listitem> | |
| 991 | <para>When traversing the file hierarchy specified by a pathname, <command>pax</command> | |
| 992 | shall not descend into directories that have a different | |
| 993 | device ID ( <emphasis remap='I'>st_dev</emphasis>; see the System Interfaces volume of IEEE Std 1003.1-2001, | |
| 994 | <emphasis remap='I'>stat</emphasis>()).</para> | |
| 995 | ||
| 996 | ||
| 997 | <para>The options that operate on the names of files or archive members | |
| 998 | ( <option>-c</option>, <option>-i</option>, <option>-n</option>, <option>-s</option>, <option>-u</option>, and | |
| 999 | <option>-v</option>) shall interact as follows. In <emphasis remap='B'>read</emphasis> mode, the archive | |
| 1000 | members shall be selected based on the user-specified | |
| 1001 | <emphasis remap='I'>pattern</emphasis> operands as modified by the <option>-c</option>, <option>-n</option>, and | |
| 1002 | <option>-u</option> options. Then, any <option>-s</option> and <option>-i</option> options | |
| 1003 | shall modify, in that order, the names of the selected files. The | |
| 1004 | <option>-v</option> option shall write names resulting from these | |
| 1005 | modifications.</para> | |
| 1006 | ||
| 1007 | <para>In <emphasis remap='B'>write</emphasis> mode, the files shall be selected based on the user-specified | |
| 1008 | pathnames as modified by the <option>-n</option> and | |
| 1009 | <option>-u</option> options. Then, any <option>-s</option> and <option>-i</option> options shall modify, | |
| 1010 | in that order, the names of these selected files. The | |
| 1011 | <option>-v</option> option shall write names resulting from these modifications.</para> | |
| 1012 | ||
| 1013 | <para>If both the <option>-u</option> and <option>-n</option> options are specified, <command>pax</command> | |
| 1014 | shall not consider a file selected unless it is newer than | |
| 1015 | the file to which it is compared.</para> | |
| 1016 | </listitem> | |
| 1017 | </varlistentry> | |
| 1018 | </variablelist> | |
| 1019 | ||
| 1020 | <refsect2 id='list_mode_format_specifications'><title>List Mode Format Specifications</title> | |
| 1021 | ||
| 1022 | <para>In <emphasis remap='B'>list</emphasis> mode with the <option>-o</option> <replaceable>listopt=</replaceable> <emphasis remap='I'>format</emphasis> option, | |
| 1023 | the <emphasis remap='I'>format</emphasis> argument shall be applied for | |
| 1024 | each selected file. The <command>pax</command> utility shall append a <newline> | |
| 1025 | to the <emphasis remap='B'>listopt</emphasis> output for each selected file. The | |
| 1026 | <emphasis remap='I'>format</emphasis> argument shall be used as the <emphasis remap='I'>format</emphasis> string described | |
| 1027 | in the Base Definitions volume of | |
| 1028 | IEEE Std 1003.1-2001, Chapter 5, File Format Notation, with the | |
| 1029 | exceptions 1. | |
| 1030 | through 5. defined in the EXTENDED DESCRIPTION section of <emphasis remap='I'>printf</emphasis>, | |
| 1031 | plus the following | |
| 1032 | exceptions:</para> | |
| 1033 | <variablelist remap='TP'> | |
| 1034 | <varlistentry> | |
| 1035 | <term>6.</term> | |
| 1036 | <listitem> | |
| 1037 | <para>The sequence ( <emphasis remap='I'>keyword</emphasis>) can occur before a format conversion | |
| 1038 | specifier. The conversion argument is defined by the value | |
| 1039 | of <emphasis remap='I'>keyword</emphasis>. The implementation shall support the following keywords:</para> | |
| 1040 | <variablelist remap='IP'> | |
| 1041 | <varlistentry> | |
| 1042 | <term> *</term> | |
| 1043 | <listitem> | |
| 1044 | <para>Any of the Field Name entries in ustar Header Block and Octet-Oriented | |
| 1045 | cpio | |
| 1046 | Archive Entry . The implementation may support the <emphasis remap='I'>cpio</emphasis> keywords | |
| 1047 | without the leading <emphasis remap='B'>c_</emphasis> in addition to the form | |
| 1048 | required by Values for cpio c_mode Field .</para> | |
| 1049 | ||
| 1050 | </listitem> | |
| 1051 | </varlistentry> | |
| 1052 | <varlistentry> | |
| 1053 | <term> *</term> | |
| 1054 | <listitem> | |
| 1055 | <para>Any keyword defined for the extended header in pax Extended Header | |
| 1056 | .</para> | |
| 1057 | ||
| 1058 | </listitem> | |
| 1059 | </varlistentry> | |
| 1060 | <varlistentry> | |
| 1061 | <term> *</term> | |
| 1062 | <listitem> | |
| 1063 | <para>Any keyword provided as an implementation-defined extension within | |
| 1064 | the extended header defined in pax Extended Header .</para> | |
| 1065 | ||
| 1066 | </listitem> | |
| 1067 | </varlistentry> | |
| 1068 | </variablelist> | |
| 1069 | ||
| 1070 | <para>For example, the sequence <emphasis remap='B'>"%(charset)s"</emphasis> is the string value | |
| 1071 | of the name of the character set in the extended | |
| 1072 | header.</para> | |
| 1073 | ||
| 1074 | <para>The result of the keyword conversion argument shall be the value from | |
| 1075 | the applicable header field or extended header, without | |
| 1076 | any trailing NULs.</para> | |
| 1077 | ||
| 1078 | <para>All keyword values used as conversion arguments shall be translated | |
| 1079 | from the UTF-8 encoding to the character set appropriate for | |
| 1080 | the local file system, user database, and so on, as applicable.</para> | |
| 1081 | </listitem> | |
| 1082 | </varlistentry> | |
| 1083 | <varlistentry> | |
| 1084 | <term>7.</term> | |
| 1085 | <listitem> | |
| 1086 | <para>An additional conversion specifier character, <emphasis remap='B'>T</emphasis> , shall be used | |
| 1087 | to specify time formats. The <emphasis remap='B'>T</emphasis> conversion | |
| 1088 | specifier character can be preceded by the sequence ( <emphasis remap='I'>keyword=</emphasis> | |
| 1089 | <emphasis remap='I'>subformat</emphasis>), where <emphasis remap='I'>subformat</emphasis> is a date format as | |
| 1090 | defined by <emphasis remap='I'>date</emphasis> operands. The default <emphasis remap='I'>keyword</emphasis> shall be | |
| 1091 | <emphasis remap='B'>mtime</emphasis> and the | |
| 1092 | default subformat shall be:</para> | |
| 1093 | ||
| 1094 | <literallayout remap='.nf'> | |
| 1095 | ||
| 1096 | <emphasis remap='B'>%b %e %H:%M %Y | |
| 1097 | </emphasis> | |
| 1098 | </literallayout> <!-- .fi --> | |
| 1099 | </listitem> | |
| 1100 | </varlistentry> | |
| 1101 | <varlistentry> | |
| 1102 | <term>8.</term> | |
| 1103 | <listitem> | |
| 1104 | <para>An additional conversion specifier character, <emphasis remap='B'>M</emphasis> , shall be used | |
| 1105 | to specify the file mode string as defined in <emphasis remap='I'>ls</emphasis> Standard Output. | |
| 1106 | If ( <emphasis remap='I'>keyword</emphasis>) is omitted, the <emphasis remap='B'>mode</emphasis> keyword shall be used. | |
| 1107 | For | |
| 1108 | example, <emphasis remap='B'>%.1M</emphasis> writes the single character corresponding to the | |
| 1109 | <<emphasis remap='I'>entry type</emphasis>> field of the <emphasis remap='I'>ls</emphasis> <option>-l</option> command.</para> | |
| 1110 | </listitem> | |
| 1111 | </varlistentry> | |
| 1112 | <varlistentry> | |
| 1113 | <term>9.</term> | |
| 1114 | <listitem> | |
| 1115 | <para>An additional conversion specifier character, <emphasis remap='B'>D</emphasis> , shall be used | |
| 1116 | to specify the device for block or special files, if | |
| 1117 | applicable, in an implementation-defined format. If not applicable, | |
| 1118 | and ( <emphasis remap='I'>keyword</emphasis>) is specified, then this conversion shall | |
| 1119 | be equivalent to <emphasis remap='B'>%(</emphasis><emphasis remap='I'>keyword</emphasis><emphasis remap='B'>)u</emphasis>. If not applicable, | |
| 1120 | and ( <emphasis remap='I'>keyword</emphasis>) is omitted, then this conversion | |
| 1121 | shall be equivalent to <space>.</para> | |
| 1122 | </listitem> | |
| 1123 | </varlistentry> | |
| 1124 | <varlistentry> | |
| 1125 | <term>10.</term> | |
| 1126 | <listitem> | |
| 1127 | <para>An additional conversion specifier character, <emphasis remap='B'>F</emphasis> , shall be used | |
| 1128 | to specify a pathname. The <emphasis remap='B'>F</emphasis> conversion | |
| 1129 | character can be preceded by a sequence of comma-separated keywords:</para> | |
| 1130 | ||
| 1131 | <literallayout remap='.nf'> | |
| 1132 | ||
| 1133 | <emphasis remap='B'>(</emphasis><emphasis remap='I'>keyword</emphasis><emphasis remap='B'>[</emphasis><emphasis remap='B'>,</emphasis><emphasis remap='I'>keyword</emphasis><emphasis remap='B'>]</emphasis> <emphasis remap='B'>... ) | |
| 1134 | </emphasis> | |
| 1135 | </literallayout> <!-- .fi --> | |
| 1136 | ||
| 1137 | <para>The values for all the keywords that are non-null shall be concatenated | |
| 1138 | together, each separated by a <emphasis remap='B'>'/'</emphasis> . The default | |
| 1139 | shall be ( <emphasis remap='B'>path</emphasis>) if the keyword <emphasis remap='B'>path</emphasis> is defined; otherwise, | |
| 1140 | the default shall be ( <emphasis remap='B'>prefix</emphasis>, <emphasis remap='B'>name</emphasis>).</para> | |
| 1141 | </listitem> | |
| 1142 | </varlistentry> | |
| 1143 | <varlistentry> | |
| 1144 | <term>11.</term> | |
| 1145 | <listitem> | |
| 1146 | <para>An additional conversion specifier character, <emphasis remap='B'>L</emphasis> , shall be used | |
| 1147 | to specify a symbolic line expansion. If the current | |
| 1148 | file is a symbolic link, then <emphasis remap='B'>%L</emphasis> shall expand to:</para> | |
| 1149 | ||
| 1150 | <literallayout remap='.nf'> | |
| 1151 | ||
| 1152 | <emphasis remap='B'>"%s -> %s", <</emphasis><emphasis remap='I'>value of keyword</emphasis><emphasis remap='B'>>, <</emphasis><emphasis remap='I'>contents of link</emphasis><emphasis remap='B'>> | |
| 1153 | </emphasis> | |
| 1154 | </literallayout> <!-- .fi --> | |
| 1155 | ||
| 1156 | <para>Otherwise, the <emphasis remap='B'>%L</emphasis> conversion specification shall be the equivalent | |
| 1157 | of <emphasis remap='B'>%F</emphasis> .</para> | |
| 1158 | ||
| 1159 | </listitem> | |
| 1160 | </varlistentry> | |
| 1161 | </variablelist> | |
| 1162 | </refsect2> | |
| 1163 | </refsect1> | |
| 1164 | ||
| 1165 | <refsect1 id='operands'><title>OPERANDS</title> | |
| 1166 | <para>The following operands shall be supported:</para> | |
| 1167 | <variablelist remap='TP'> | |
| 1168 | <varlistentry> | |
| 1169 | <term><emphasis remap='I'>directory</emphasis></term> | |
| 1170 | <listitem> | |
| 1171 | <para>The destination directory pathname for <emphasis remap='B'>copy</emphasis> mode.</para> | |
| 1172 | </listitem> | |
| 1173 | </varlistentry> | |
| 1174 | <varlistentry> | |
| 1175 | <term><emphasis remap='I'>file</emphasis></term> | |
| 1176 | <listitem> | |
| 1177 | <para>A pathname of a file to be copied or archived.</para> | |
| 1178 | </listitem> | |
| 1179 | </varlistentry> | |
| 1180 | <varlistentry> | |
| 1181 | <term><emphasis remap='I'>pattern</emphasis></term> | |
| 1182 | <listitem> | |
| 1183 | <para>A pattern matching one or more pathnames of archive members. A pattern | |
| 1184 | must be given in the name-generating notation of the | |
| 1185 | pattern matching notation in <emphasis remap='I'>Pattern Matching Notation</emphasis> , including | |
| 1186 | the filename | |
| 1187 | expansion rules in <emphasis remap='I'>Patterns Used for Filename Expansion</emphasis> . The | |
| 1188 | default, if no | |
| 1189 | <emphasis remap='I'>pattern</emphasis> is specified, is to select all members in the archive.</para> | |
| 1190 | ||
| 1191 | </listitem> | |
| 1192 | </varlistentry> | |
| 1193 | </variablelist> | |
| 1194 | </refsect1> | |
| 1195 | ||
| 1196 | <refsect1 id='stdin'><title>STDIN</title> | |
| 1197 | <para>In <emphasis remap='B'>write</emphasis> mode, the standard input shall be used only if no <emphasis remap='I'>file</emphasis> | |
| 1198 | operands are specified. It shall be a text file | |
| 1199 | containing a list of pathnames, one per line, without leading or trailing | |
| 1200 | <blank>s.</para> | |
| 1201 | ||
| 1202 | <para>In <emphasis remap='B'>list</emphasis> and <emphasis remap='B'>read</emphasis> modes, if <option>-f</option> is not specified, | |
| 1203 | the standard input shall be an archive file.</para> | |
| 1204 | ||
| 1205 | <para>Otherwise, the standard input shall not be used.</para> | |
| 1206 | </refsect1> | |
| 1207 | ||
| 1208 | <refsect1 id='input_files'><title>INPUT FILES</title> | |
| 1209 | <para>The input file named by the <emphasis remap='I'>archive</emphasis> option-argument, or standard | |
| 1210 | input when the archive is read from there, shall be a | |
| 1211 | file formatted according to one of the specifications in the EXTENDED | |
| 1212 | DESCRIPTION section or some other implementation-defined | |
| 1213 | format.</para> | |
| 1214 | ||
| 1215 | <para>The file <filename>/dev/tty</filename> shall be used to write prompts and read responses.</para> | |
| 1216 | </refsect1> | |
| 1217 | ||
| 1218 | <refsect1 id='environment_variables'><title>ENVIRONMENT VARIABLES</title> | |
| 1219 | <para>The following environment variables shall affect the execution of | |
| 1220 | <command>pax</command>:</para> | |
| 1221 | <variablelist remap='TP'> | |
| 1222 | <varlistentry> | |
| 1223 | <term><envar>LANG</envar></term> | |
| 1224 | <listitem> | |
| 1225 | <para>Provide a default value for the internationalization variables that | |
| 1226 | are unset or null. (See the Base Definitions volume of | |
| 1227 | IEEE Std 1003.1-2001, Section 8.2, Internationalization Variables | |
| 1228 | for | |
| 1229 | the precedence of internationalization variables used to determine | |
| 1230 | the values of locale categories.)</para> | |
| 1231 | </listitem> | |
| 1232 | </varlistentry> | |
| 1233 | <varlistentry> | |
| 1234 | <term><envar>LC_ALL</envar></term> | |
| 1235 | <listitem> | |
| 1236 | <para>If set to a non-empty string value, override the values of all the | |
| 1237 | other internationalization variables.</para> | |
| 1238 | </listitem> | |
| 1239 | </varlistentry> | |
| 1240 | <varlistentry> | |
| 1241 | <term><emphasis remap='I'>LC_COLLATE</emphasis></term> | |
| 1242 | <listitem> | |
| 1243 | ||
| 1244 | <para>Determine the locale for the behavior of ranges, equivalence classes, | |
| 1245 | and multi-character collating elements used in the pattern | |
| 1246 | matching expressions for the <emphasis remap='I'>pattern</emphasis> operand, the basic regular | |
| 1247 | expression for the <option>-s</option> option, and the extended | |
| 1248 | regular expression defined for the <emphasis remap='B'>yesexpr</emphasis> locale keyword in | |
| 1249 | the <envar>LC_MESSAGES</envar> category.</para> | |
| 1250 | </listitem> | |
| 1251 | </varlistentry> | |
| 1252 | <varlistentry> | |
| 1253 | <term><emphasis remap='I'>LC_CTYPE</emphasis></term> | |
| 1254 | <listitem> | |
| 1255 | <para>Determine the locale for the interpretation of sequences of bytes | |
| 1256 | of text data as characters (for example, single-byte as | |
| 1257 | opposed to multi-byte characters in arguments and input files), the | |
| 1258 | behavior of character classes used in the extended regular | |
| 1259 | expression defined for the <emphasis remap='B'>yesexpr</emphasis> locale keyword in the <envar>LC_MESSAGES</envar> | |
| 1260 | category, and pattern matching.</para> | |
| 1261 | </listitem> | |
| 1262 | </varlistentry> | |
| 1263 | <varlistentry> | |
| 1264 | <term><envar>LC_MESSAGES</envar></term> | |
| 1265 | <listitem> | |
| 1266 | <para>Determine the locale for the processing of affirmative responses that | |
| 1267 | should be used to affect the format and contents of | |
| 1268 | diagnostic messages written to standard error.</para> | |
| 1269 | </listitem> | |
| 1270 | </varlistentry> | |
| 1271 | <varlistentry> | |
| 1272 | <term><emphasis remap='I'>LC_TIME</emphasis></term> | |
| 1273 | <listitem> | |
| 1274 | <para>Determine the format and contents of date and time strings when the | |
| 1275 | <option>-v</option> option is specified.</para> | |
| 1276 | </listitem> | |
| 1277 | </varlistentry> | |
| 1278 | <varlistentry> | |
| 1279 | <term><envar>NLSPATH</envar></term> | |
| 1280 | <listitem> | |
| 1281 | <para>Determine the location of message catalogs for the processing of <emphasis remap='I'>LC_MESSAGES | |
| 1282 | .</emphasis></para> | |
| 1283 | </listitem> | |
| 1284 | </varlistentry> | |
| 1285 | <varlistentry> | |
| 1286 | <term><envar>TMPDIR</envar></term> | |
| 1287 | <listitem> | |
| 1288 | <para>Determine the pathname that provides part of the default global extended | |
| 1289 | header record file, as described for the <option>-o</option> | |
| 1290 | <replaceable>globexthdr=</replaceable> keyword in the OPTIONS section.</para> | |
| 1291 | </listitem> | |
| 1292 | </varlistentry> | |
| 1293 | <varlistentry> | |
| 1294 | <term><envar>TZ</envar></term> | |
| 1295 | <listitem> | |
| 1296 | <para>Determine the timezone used to calculate date and time strings when | |
| 1297 | the <option>-v</option> option is specified. If <envar>TZ</envar> is unset or | |
| 1298 | null, an unspecified default timezone shall be used.</para> | |
| 1299 | ||
| 1300 | </listitem> | |
| 1301 | </varlistentry> | |
| 1302 | </variablelist> | |
| 1303 | </refsect1> | |
| 1304 | ||
| 1305 | <refsect1 id='asynchronous_events'><title>ASYNCHRONOUS EVENTS</title> | |
| 1306 | <para>Default.</para> | |
| 1307 | </refsect1> | |
| 1308 | ||
| 1309 | <refsect1 id='stdout'><title>STDOUT</title> | |
| 1310 | <para>In <emphasis remap='B'>write</emphasis> mode, if <option>-f</option> is not specified, the standard output | |
| 1311 | shall be the archive formatted according to one of the | |
| 1312 | specifications in the EXTENDED DESCRIPTION section, or some other | |
| 1313 | implementation-defined format (see <option>-x</option> <replaceable>format</replaceable>).</para> | |
| 1314 | ||
| 1315 | <para>In <emphasis remap='B'>list</emphasis> mode, when the <option>-o</option> <replaceable>listopt</replaceable>= <emphasis remap='I'>format</emphasis> | |
| 1316 | has been specified, the selected archive members shall be | |
| 1317 | written to standard output using the format described under List Mode | |
| 1318 | Format Specifications . In | |
| 1319 | <emphasis remap='B'>list</emphasis> mode without the <option>-o</option> <replaceable>listopt</replaceable>= <emphasis remap='I'>format</emphasis> option, | |
| 1320 | the table of contents of the selected archive members | |
| 1321 | shall be written to standard output using the following format:</para> | |
| 1322 | ||
| 1323 | <literallayout remap='.nf'> | |
| 1324 | ||
| 1325 | <emphasis remap='B'>"%s\n", <</emphasis><emphasis remap='I'>pathname</emphasis><emphasis remap='B'>> | |
| 1326 | </emphasis> | |
| 1327 | </literallayout> <!-- .fi --> | |
| 1328 | ||
| 1329 | <para>If the <option>-v</option> option is specified in <emphasis remap='B'>list</emphasis> mode, the table | |
| 1330 | of contents of the selected archive members shall be written | |
| 1331 | to standard output using the following formats.</para> | |
| 1332 | ||
| 1333 | <para>For pathnames representing hard links to previous members of the archive:</para> | |
| 1334 | ||
| 1335 | <literallayout remap='.nf'> | |
| 1336 | ||
| 1337 | <emphasis remap='B'>"%s == %s\n", <</emphasis><emphasis remap='I'>ls</emphasis> <option>-l</option> <replaceable>listing</replaceable><emphasis remap='B'>>, <</emphasis><emphasis remap='I'>linkname</emphasis><emphasis remap='B'>> | |
| 1338 | </emphasis> | |
| 1339 | </literallayout> <!-- .fi --> | |
| 1340 | ||
| 1341 | <para>For all other pathnames:</para> | |
| 1342 | ||
| 1343 | <literallayout remap='.nf'> | |
| 1344 | ||
| 1345 | <emphasis remap='B'>"%s\n", <</emphasis><emphasis remap='I'>ls</emphasis> <option>-l</option> <replaceable>listing</replaceable><emphasis remap='B'>> | |
| 1346 | </emphasis> | |
| 1347 | </literallayout> <!-- .fi --> | |
| 1348 | ||
| 1349 | <para>where <<emphasis remap='I'>ls </emphasis> -l <emphasis remap='I'>listing</emphasis>> shall be the format specified | |
| 1350 | by the <emphasis remap='I'>ls</emphasis> utility with the <option>-l</option> option. When writing pathnames | |
| 1351 | in this format, it is unspecified | |
| 1352 | what is written for fields for which the underlying archive format | |
| 1353 | does not have the correct information, although the correct | |
| 1354 | number of <blank>-separated fields shall be written.</para> | |
| 1355 | ||
| 1356 | <para>In <emphasis remap='B'>list</emphasis> mode, standard output shall not be buffered more than | |
| 1357 | a line at a time.</para> | |
| 1358 | </refsect1> | |
| 1359 | ||
| 1360 | <refsect1 id='stderr'><title>STDERR</title> | |
| 1361 | <para>If <option>-v</option> is specified in <emphasis remap='B'>read</emphasis>, <emphasis remap='B'>write</emphasis>, or <emphasis remap='B'>copy</emphasis> | |
| 1362 | modes, <command>pax</command> shall write the pathnames it processes | |
| 1363 | to the standard error output using the following format:</para> | |
| 1364 | ||
| 1365 | <literallayout remap='.nf'> | |
| 1366 | ||
| 1367 | <emphasis remap='B'>"%s\n", <</emphasis><emphasis remap='I'>pathname</emphasis><emphasis remap='B'>> | |
| 1368 | </emphasis> | |
| 1369 | </literallayout> <!-- .fi --> | |
| 1370 | ||
| 1371 | <para>These pathnames shall be written as soon as processing is begun on | |
| 1372 | the file or archive member, and shall be flushed to standard | |
| 1373 | error. The trailing <newline>, which shall not be buffered, is written | |
| 1374 | when the file has been read or written.</para> | |
| 1375 | ||
| 1376 | <para>If the <option>-s</option> option is specified, and the replacement string has | |
| 1377 | a trailing <emphasis remap='B'>'p'</emphasis> , substitutions shall be written to | |
| 1378 | standard error in the following format:</para> | |
| 1379 | ||
| 1380 | <literallayout remap='.nf'> | |
| 1381 | ||
| 1382 | <emphasis remap='B'>"%s >> %s\n", <</emphasis><emphasis remap='I'>original pathname</emphasis><emphasis remap='B'>>, <</emphasis><emphasis remap='I'>new pathname</emphasis><emphasis remap='B'>> | |
| 1383 | </emphasis> | |
| 1384 | </literallayout> <!-- .fi --> | |
| 1385 | ||
| 1386 | <para>In all operating modes of <command>pax</command>, optional messages of unspecified | |
| 1387 | format concerning the input archive format and volume | |
| 1388 | number, the number of files, blocks, volumes, and media parts as well | |
| 1389 | as other diagnostic messages may be written to standard | |
| 1390 | error.</para> | |
| 1391 | ||
| 1392 | <para>In all formats, for both standard output and standard error, it is | |
| 1393 | unspecified how non-printable characters in pathnames or link | |
| 1394 | names are written.</para> | |
| 1395 | ||
| 1396 | <para>When <command>pax</command> is in <emphasis remap='B'>read</emphasis> mode or <emphasis remap='B'>list</emphasis> mode, using the | |
| 1397 | <option>-x</option> <replaceable>pax</replaceable> archive format, and a filename, link | |
| 1398 | name, owner name, or any other field in an extended header record | |
| 1399 | cannot be translated from the <command>pax</command> UTF-8 codeset format to | |
| 1400 | the codeset and current locale of the implementation, <command>pax</command> shall | |
| 1401 | write a diagnostic message to standard error, shall process | |
| 1402 | the file as described for the <option>-o</option> <replaceable>invalid=</replaceable> option, and | |
| 1403 | then shall process the next file in the archive.</para> | |
| 1404 | </refsect1> | |
| 1405 | ||
| 1406 | <refsect1 id='output_files'><title>OUTPUT FILES</title> | |
| 1407 | <para>In <emphasis remap='B'>read</emphasis> mode, the extracted output files shall be of the archived | |
| 1408 | file type. In <emphasis remap='B'>copy</emphasis> mode, the copied output files | |
| 1409 | shall be the type of the file being copied. In either mode, existing | |
| 1410 | files in the destination hierarchy shall be overwritten only | |
| 1411 | when all permission ( <option>-p</option>), modification time ( <option>-u</option>), and | |
| 1412 | invalid-value ( <option>-o</option> <replaceable>invalid</replaceable>=) tests allow | |
| 1413 | it.</para> | |
| 1414 | ||
| 1415 | <para>In <emphasis remap='B'>write</emphasis> mode, the output file named by the <option>-f</option> option-argument | |
| 1416 | shall be a file formatted according to one of the | |
| 1417 | specifications in the EXTENDED DESCRIPTION section, or some other | |
| 1418 | implementation-defined format.</para> | |
| 1419 | </refsect1> | |
| 1420 | ||
| 1421 | <refsect1 id='extended_description'><title>EXTENDED DESCRIPTION</title> | |
| 1422 | ||
| 1423 | <refsect2 id='pax_interchange_format'><title>pax Interchange Format</title> | |
| 1424 | ||
| 1425 | <para>A <command>pax</command> archive tape or file produced in the <option>-x</option> <replaceable>pax</replaceable> | |
| 1426 | format shall contain a series of blocks. The physical | |
| 1427 | layout of the archive shall be identical to the <emphasis remap='B'>ustar</emphasis> format | |
| 1428 | described in ustar Interchange | |
| 1429 | Format . Each file archived shall be represented by the following | |
| 1430 | sequence:</para> | |
| 1431 | <variablelist remap='IP'> | |
| 1432 | <varlistentry> | |
| 1433 | <term> *</term> | |
| 1434 | <listitem> | |
| 1435 | <para>An optional header block with extended header records. This header | |
| 1436 | block is of the form described in pax Header Block , with a <emphasis remap='I'>typeflag</emphasis> | |
| 1437 | value of <emphasis remap='B'>x</emphasis> or <emphasis remap='B'>g</emphasis>. The extended header records, | |
| 1438 | described in pax Extended Header , shall be included as the data for | |
| 1439 | this header block.</para> | |
| 1440 | ||
| 1441 | </listitem> | |
| 1442 | </varlistentry> | |
| 1443 | <varlistentry> | |
| 1444 | <term> *</term> | |
| 1445 | <listitem> | |
| 1446 | <para>A header block that describes the file. Any fields in the preceding | |
| 1447 | optional extended header shall override the associated | |
| 1448 | fields in this header block for this file.</para> | |
| 1449 | ||
| 1450 | </listitem> | |
| 1451 | </varlistentry> | |
| 1452 | <varlistentry> | |
| 1453 | <term> *</term> | |
| 1454 | <listitem> | |
| 1455 | <para>Zero or more blocks that contain the contents of the file.</para> | |
| 1456 | ||
| 1457 | ||
| 1458 | <para>At the end of the archive file there shall be two 512-byte blocks | |
| 1459 | filled with binary zeros, interpreted as an end-of-archive | |
| 1460 | indicator.</para> | |
| 1461 | ||
| 1462 | <para>A schematic of an example archive with global extended header records | |
| 1463 | and two actual files is shown in pax | |
| 1464 | Format Archive Example . In the example, the second file in the archive | |
| 1465 | has no extended header preceding it, presumably because | |
| 1466 | it has no need for extended attributes.</para> | |
| 1467 | ||
| 1468 | <variablelist remap='TP'> | |
| 1469 | <varlistentry> | |
| 1470 | <term><blockquote remap='RS'></term> | |
| 1471 | <listitem> | |
| 1472 | <para><emphasis remap='B'>Figure: pax Format Archive Example</emphasis></para> | |
| 1473 | </listitem> | |
| 1474 | </varlistentry> | |
| 1475 | </variablelist> | |
| 1476 | </blockquote> <!-- remap='RE' --> | |
| 1477 | </listitem> | |
| 1478 | </varlistentry> | |
| 1479 | </variablelist> | |
| 1480 | </refsect2> | |
| 1481 | ||
| 1482 | <refsect2 id='pax_header_block'><title>pax Header Block</title> | |
| 1483 | ||
| 1484 | <para>The <command>pax</command> header block shall be identical to the <emphasis remap='B'>ustar</emphasis> header | |
| 1485 | block described in ustar | |
| 1486 | Interchange Format , except that two additional <emphasis remap='I'>typeflag</emphasis> values | |
| 1487 | are defined:</para> | |
| 1488 | <variablelist remap='TP'> | |
| 1489 | <varlistentry> | |
| 1490 | <term><emphasis remap='B'>x</emphasis></term> | |
| 1491 | <listitem> | |
| 1492 | <para>Represents extended header records for the following file in the archive | |
| 1493 | (which shall have its own <emphasis remap='B'>ustar</emphasis> header block). | |
| 1494 | The format of these extended header records shall be as described | |
| 1495 | in pax Extended Header .</para> | |
| 1496 | </listitem> | |
| 1497 | </varlistentry> | |
| 1498 | <varlistentry> | |
| 1499 | <term><emphasis remap='B'>g</emphasis></term> | |
| 1500 | <listitem> | |
| 1501 | <para>Represents global extended header records for the following files | |
| 1502 | in the archive. The format of these extended header records | |
| 1503 | shall be as described in pax Extended Header . Each value shall affect | |
| 1504 | all subsequent files that do | |
| 1505 | not override that value in their own extended header record and until | |
| 1506 | another global extended header record is reached that | |
| 1507 | provides another value for the same field. The <emphasis remap='I'>typeflag</emphasis> <emphasis remap='B'>g</emphasis> | |
| 1508 | global headers should not be used with interchange media | |
| 1509 | that could suffer partial data loss in transporting the archive.</para> | |
| 1510 | ||
| 1511 | ||
| 1512 | <para>For both of these types, the <emphasis remap='I'>size</emphasis> field shall be the size of | |
| 1513 | the extended header records in octets. The other fields in | |
| 1514 | the header block are not meaningful to this version of the <command>pax</command> | |
| 1515 | utility. However, if this archive is read by a <command>pax</command> | |
| 1516 | utility conforming to the ISO POSIX-2:1993 standard, the header block | |
| 1517 | fields are used to create a regular file that contains | |
| 1518 | the extended header records as data. Therefore, header block field | |
| 1519 | values should be selected to provide reasonable file access to | |
| 1520 | this regular file.</para> | |
| 1521 | ||
| 1522 | <para>A further difference from the <emphasis remap='B'>ustar</emphasis> header block is that data | |
| 1523 | blocks for files of <emphasis remap='I'>typeflag</emphasis> 1 (the digit one) (hard | |
| 1524 | link) may be included, which means that the size field may be greater | |
| 1525 | than zero. Archives created by <command>pax</command> <option>-o</option> | |
| 1526 | <replaceable>linkdata</replaceable> shall include these data blocks with the hard links.</para> | |
| 1527 | </listitem> | |
| 1528 | </varlistentry> | |
| 1529 | </variablelist> | |
| 1530 | </refsect2> | |
| 1531 | ||
| 1532 | <refsect2 id='pax_extended_header'><title>pax Extended Header</title> | |
| 1533 | ||
| 1534 | <para>A <command>pax</command> extended header contains values that are inappropriate | |
| 1535 | for the <emphasis remap='B'>ustar</emphasis> header block because of limitations in | |
| 1536 | that format: fields requiring a character encoding other than that | |
| 1537 | described in the ISO/IEC 646:1991 standard, fields | |
| 1538 | representing file attributes not described in the <emphasis remap='B'>ustar</emphasis> header, | |
| 1539 | and fields whose format or length do not fit the | |
| 1540 | requirements of the <emphasis remap='B'>ustar</emphasis> header. The values in an extended | |
| 1541 | header add attributes to the following file (or files; see the | |
| 1542 | description of the <emphasis remap='I'>typeflag</emphasis> <emphasis remap='B'>g</emphasis> header block) or override | |
| 1543 | values in the following header block(s), as indicated in the | |
| 1544 | following list of keywords.</para> | |
| 1545 | ||
| 1546 | <para>An extended header shall consist of one or more records, each constructed | |
| 1547 | as follows:</para> | |
| 1548 | ||
| 1549 | <literallayout remap='.nf'> | |
| 1550 | ||
| 1551 | <emphasis remap='B'>"%d %s=%s\n", <</emphasis><emphasis remap='I'>length</emphasis><emphasis remap='B'>>, <</emphasis><emphasis remap='I'>keyword</emphasis><emphasis remap='B'>>, <</emphasis><emphasis remap='I'>value</emphasis><emphasis remap='B'>> | |
| 1552 | </emphasis> | |
| 1553 | </literallayout> <!-- .fi --> | |
| 1554 | ||
| 1555 | <para>The extended header records shall be encoded according to the ISO/IEC 10646-1:2000 | |
| 1556 | standard (UTF-8). The | |
| 1557 | <<emphasis remap='I'>length</emphasis>> field, <blank>, equals sign, and <newline> shown shall | |
| 1558 | be limited to the portable character set, | |
| 1559 | as encoded in UTF-8. The <<emphasis remap='I'>keyword</emphasis>> and <<emphasis remap='I'>value</emphasis>> fields | |
| 1560 | can be any UTF-8 characters. The | |
| 1561 | <<emphasis remap='I'>length</emphasis>> field shall be the decimal length of the extended header | |
| 1562 | record in octets, including the trailing | |
| 1563 | <newline>.</para> | |
| 1564 | ||
| 1565 | <para>The <<emphasis remap='I'>keyword</emphasis>> field shall be one of the entries from the following | |
| 1566 | list or a keyword provided as an implementation | |
| 1567 | extension. Keywords consisting entirely of lowercase letters, digits, | |
| 1568 | and periods are reserved for future standardization. A | |
| 1569 | keyword shall not include an equals sign. (In the following list, | |
| 1570 | the notations "file(s)" or "block(s)" is used to acknowledge | |
| 1571 | that a keyword affects the following single file after a <emphasis remap='I'>typeflag</emphasis> | |
| 1572 | <emphasis remap='B'>x</emphasis> extended header, but possibly multiple files | |
| 1573 | after <emphasis remap='I'>typeflag</emphasis> <emphasis remap='B'>g</emphasis>. Any requirements in the list for <command>pax</command> | |
| 1574 | to include a record when in <emphasis remap='B'>write</emphasis> or <emphasis remap='B'>copy</emphasis> | |
| 1575 | mode shall apply only when such a record has not already been provided | |
| 1576 | through the use of the <option>-o</option> option. When used in | |
| 1577 | <emphasis remap='B'>copy</emphasis> mode, <command>pax</command> shall behave as if an archive had been | |
| 1578 | created with applicable extended header records and then | |
| 1579 | extracted.)</para> | |
| 1580 | <variablelist remap='TP'> | |
| 1581 | <varlistentry> | |
| 1582 | <term><emphasis remap='B'>atime</emphasis></term> | |
| 1583 | <listitem> | |
| 1584 | <para>The file access time for the following file(s), equivalent to the | |
| 1585 | value of the <emphasis remap='I'>st_atime</emphasis> member of the <emphasis remap='B'>stat</emphasis> | |
| 1586 | structure for a file, as described by the <emphasis remap='I'>stat</emphasis>() function. The | |
| 1587 | access time shall be | |
| 1588 | restored if the process has the appropriate privilege required to | |
| 1589 | do so. The format of the <<emphasis remap='I'>value</emphasis>> shall be as | |
| 1590 | described in pax Extended Header File Times .</para> | |
| 1591 | </listitem> | |
| 1592 | </varlistentry> | |
| 1593 | <varlistentry> | |
| 1594 | <term><emphasis remap='B'>charset</emphasis></term> | |
| 1595 | <listitem> | |
| 1596 | <para>The name of the character set used to encode the data in the following | |
| 1597 | file(s). The entries in the following table are defined | |
| 1598 | to refer to known standards; additional names may be agreed on between | |
| 1599 | the originator and recipient.</para> | |
| 1600 | ||
| 1601 | <informaltable pgwide='0' frame='none'> | |
| 1602 | <tgroup cols='6' align='center'> | |
| 1603 | <colspec colname='c1'/> | |
| 1604 | <colspec colname='c2'/> | |
| 1605 | <colspec colname='c3'/> | |
| 1606 | <colspec colname='c4'/> | |
| 1607 | <colspec colname='c5'/> | |
| 1608 | <colspec colname='c6'/> | |
| 1609 | <tbody> | |
| 1610 | <row> | |
| 1611 | <entry align='center'><emphasis remap='B'><value></emphasis></entry> | |
| 1612 | <entry align='right'><emphasis remap='B'>Formal Standard</emphasis></entry> | |
| 1613 | </row> | |
| 1614 | <row> | |
| 1615 | <entry align='center'>ISO-IR 646 1990</entry> | |
| 1616 | <entry align='right'>ISO/IEC 646:1990</entry> | |
| 1617 | </row> | |
| 1618 | <row> | |
| 1619 | <entry align='center'>ISO-IR 8859 1 1998</entry> | |
| 1620 | <entry align='right'>ISO/IEC 8859-1:1998</entry> | |
| 1621 | </row> | |
| 1622 | <row> | |
| 1623 | <entry align='center'>ISO-IR 8859 2 1999</entry> | |
| 1624 | <entry align='right'>ISO/IEC 8859-2:1999</entry> | |
| 1625 | </row> | |
| 1626 | <row> | |
| 1627 | <entry align='center'>ISO-IR 8859 3 1999</entry> | |
| 1628 | <entry align='right'>ISO/IEC 8859-3:1999</entry> | |
| 1629 | </row> | |
| 1630 | <row> | |
| 1631 | <entry align='center'>ISO-IR 8859 4 1998</entry> | |
| 1632 | <entry align='right'>ISO/IEC 8859-4:1998</entry> | |
| 1633 | </row> | |
| 1634 | <row> | |
| 1635 | <entry align='center'>ISO-IR 8859 5 1999</entry> | |
| 1636 | <entry align='right'>ISO/IEC 8859-5:1999</entry> | |
| 1637 | </row> | |
| 1638 | <row> | |
| 1639 | <entry align='center'>ISO-IR 8859 6 1999</entry> | |
| 1640 | <entry align='right'>ISO/IEC 8859-6:1999</entry> | |
| 1641 | </row> | |
| 1642 | <row> | |
| 1643 | <entry align='center'>ISO-IR 8859 7 1987</entry> | |
| 1644 | <entry align='right'>ISO/IEC 8859-7:1987</entry> | |
| 1645 | </row> | |
| 1646 | <row> | |
| 1647 | <entry align='center'>ISO-IR 8859 8 1999</entry> | |
| 1648 | <entry align='right'>ISO/IEC 8859-8:1999</entry> | |
| 1649 | </row> | |
| 1650 | <row> | |
| 1651 | <entry align='center'>ISO-IR 8859 9 1999</entry> | |
| 1652 | <entry align='right'>ISO/IEC 8859-9:1999</entry> | |
| 1653 | </row> | |
| 1654 | <row> | |
| 1655 | <entry align='center'>ISO-IR 8859 10 1998</entry> | |
| 1656 | <entry align='right'>ISO/IEC 8859-10:1998</entry> | |
| 1657 | </row> | |
| 1658 | <row> | |
| 1659 | <entry align='center'>ISO-IR 8859 13 1998</entry> | |
| 1660 | <entry align='right'>ISO/IEC 8859-13:1998</entry> | |
| 1661 | </row> | |
| 1662 | <row> | |
| 1663 | <entry align='center'>ISO-IR 8859 14 1998</entry> | |
| 1664 | <entry align='right'>ISO/IEC 8859-14:1998</entry> | |
| 1665 | </row> | |
| 1666 | <row> | |
| 1667 | <entry align='center'>ISO-IR 8859 15 1999</entry> | |
| 1668 | <entry align='right'>ISO/IEC 8859-15:1999</entry> | |
| 1669 | </row> | |
| 1670 | <row> | |
| 1671 | <entry align='center'>ISO-IR 10646 2000</entry> | |
| 1672 | <entry align='right'>ISO/IEC 10646:2000</entry> | |
| 1673 | </row> | |
| 1674 | <row> | |
| 1675 | <entry align='center'>ISO-IR 10646 2000 UTF-8</entry> | |
| 1676 | <entry align='right'>ISO/IEC 10646, UTF-8 encoding</entry> | |
| 1677 | </row> | |
| 1678 | <row> | |
| 1679 | <entry align='center'>BINARY</entry> | |
| 1680 | <entry align='right'>None.</entry> | |
| 1681 | </row> | |
| 1682 | </tbody> | |
| 1683 | </tgroup> | |
| 1684 | </informaltable> | |
| 1685 | ||
| 1686 | ||
| 1687 | ||
| 1688 | <para>The encoding is included in an extended header for information only; | |
| 1689 | when <command>pax</command> is used as described in | |
| 1690 | IEEE Std 1003.1-2001, it shall not translate the file data into | |
| 1691 | any other encoding. The <emphasis remap='B'>BINARY</emphasis> entry indicates | |
| 1692 | unencoded binary data.</para> | |
| 1693 | ||
| 1694 | <para>When used in <emphasis remap='B'>write</emphasis> or <emphasis remap='B'>copy</emphasis> mode, it is implementation-defined | |
| 1695 | whether <command>pax</command> includes a <emphasis remap='B'>charset</emphasis> | |
| 1696 | extended header record for a file.</para> | |
| 1697 | </listitem> | |
| 1698 | </varlistentry> | |
| 1699 | <varlistentry> | |
| 1700 | <term><emphasis remap='B'>comment</emphasis></term> | |
| 1701 | <listitem> | |
| 1702 | <para>A series of characters used as a comment. All characters in the <<emphasis remap='I'>value</emphasis>> | |
| 1703 | field shall be ignored by <command>pax</command>.</para> | |
| 1704 | </listitem> | |
| 1705 | </varlistentry> | |
| 1706 | <varlistentry> | |
| 1707 | <term><emphasis remap='B'>ctime</emphasis></term> | |
| 1708 | <listitem> | |
| 1709 | <para>The file creation time for the following file(s), equivalent to the | |
| 1710 | value of the <emphasis remap='I'>st_ctime</emphasis> member of the <emphasis remap='B'>stat</emphasis> | |
| 1711 | structure for a file, as described by the <emphasis remap='I'>stat</emphasis>() function. The | |
| 1712 | creation time shall be | |
| 1713 | restored if the process has the appropriate privilege required to | |
| 1714 | do so. The format of the <<emphasis remap='I'>value</emphasis>> shall be as | |
| 1715 | described in pax Extended Header File Times .</para> | |
| 1716 | </listitem> | |
| 1717 | </varlistentry> | |
| 1718 | <varlistentry> | |
| 1719 | <term><emphasis remap='B'>gid</emphasis></term> | |
| 1720 | <listitem> | |
| 1721 | <para>The group ID of the group that owns the file, expressed as a decimal | |
| 1722 | number using digits from the ISO/IEC 646:1991 | |
| 1723 | standard. This record shall override the <emphasis remap='I'>gid</emphasis> field in the following | |
| 1724 | header block(s). When used in <emphasis remap='B'>write</emphasis> or | |
| 1725 | <emphasis remap='B'>copy</emphasis> mode, <command>pax</command> shall include a <emphasis remap='I'>gid</emphasis> extended header | |
| 1726 | record for each file whose group ID is greater than 2097151 | |
| 1727 | (octal 7777777).</para> | |
| 1728 | </listitem> | |
| 1729 | </varlistentry> | |
| 1730 | <varlistentry> | |
| 1731 | <term><emphasis remap='B'>gname</emphasis></term> | |
| 1732 | <listitem> | |
| 1733 | <para>The group of the file(s), formatted as a group name in the group database. | |
| 1734 | This record shall override the <emphasis remap='I'>gid</emphasis> and | |
| 1735 | <emphasis remap='I'>gname</emphasis> fields in the following header block(s), and any <emphasis remap='I'>gid</emphasis> | |
| 1736 | extended header record. When used in <emphasis remap='B'>read</emphasis>, | |
| 1737 | <emphasis remap='B'>copy</emphasis>, or <emphasis remap='B'>list</emphasis> mode, <command>pax</command> shall translate the name | |
| 1738 | from the UTF-8 encoding in the header record to the character | |
| 1739 | set appropriate for the group database on the receiving system. If | |
| 1740 | any of the UTF-8 characters cannot be translated, and if the | |
| 1741 | <option>-o</option> <replaceable>invalid=</replaceable> UTF-8 option is not specified, the results | |
| 1742 | are implementation-defined. When used in <emphasis remap='B'>write</emphasis> or | |
| 1743 | <emphasis remap='B'>copy</emphasis> mode, <command>pax</command> shall include a <emphasis remap='B'>gname</emphasis> extended header | |
| 1744 | record for each file whose group name cannot be | |
| 1745 | represented entirely with the letters and digits of the portable character | |
| 1746 | set.</para> | |
| 1747 | </listitem> | |
| 1748 | </varlistentry> | |
| 1749 | <varlistentry> | |
| 1750 | <term><emphasis remap='B'>linkpath</emphasis></term> | |
| 1751 | <listitem> | |
| 1752 | <para>The pathname of a link being created to another file, of any type, | |
| 1753 | previously archived. This record shall override the | |
| 1754 | <emphasis remap='I'>linkname</emphasis> field in the following <emphasis remap='B'>ustar</emphasis> header block(s). | |
| 1755 | The following <emphasis remap='B'>ustar</emphasis> header block shall determine the | |
| 1756 | type of link created. If <emphasis remap='I'>typeflag</emphasis> of the following header block | |
| 1757 | is 1, it shall be a hard link. If <emphasis remap='I'>typeflag</emphasis> is 2, it | |
| 1758 | shall be a symbolic link and the <emphasis remap='B'>linkpath</emphasis> value shall be the | |
| 1759 | contents of the symbolic link. The <command>pax</command> utility shall | |
| 1760 | translate the name of the link (contents of the symbolic link) from | |
| 1761 | the UTF-8 encoding to the character set appropriate for the | |
| 1762 | local file system. When used in <emphasis remap='B'>write</emphasis> or <emphasis remap='B'>copy</emphasis> mode, <command>pax</command> | |
| 1763 | shall include a <emphasis remap='B'>linkpath</emphasis> extended header record | |
| 1764 | for each link whose pathname cannot be represented entirely with the | |
| 1765 | members of the portable character set other than NUL.</para> | |
| 1766 | </listitem> | |
| 1767 | </varlistentry> | |
| 1768 | <varlistentry> | |
| 1769 | <term><emphasis remap='B'>mtime</emphasis></term> | |
| 1770 | <listitem> | |
| 1771 | <para>The file modification time of the following file(s), equivalent to | |
| 1772 | the value of the <emphasis remap='I'>st_mtime</emphasis> member of the <emphasis remap='B'>stat</emphasis> | |
| 1773 | structure for a file, as described in the <emphasis remap='I'>stat</emphasis>() function. This | |
| 1774 | record shall override | |
| 1775 | the <emphasis remap='I'>mtime</emphasis> field in the following header block(s). The modification | |
| 1776 | time shall be restored if the process has the appropriate | |
| 1777 | privilege required to do so. The format of the <<emphasis remap='I'>value</emphasis>> shall | |
| 1778 | be as described in pax | |
| 1779 | Extended Header File Times .</para> | |
| 1780 | </listitem> | |
| 1781 | </varlistentry> | |
| 1782 | <varlistentry> | |
| 1783 | <term><emphasis remap='B'>path</emphasis></term> | |
| 1784 | <listitem> | |
| 1785 | <para>The pathname of the following file(s). This record shall override | |
| 1786 | the <emphasis remap='I'>name</emphasis> and <emphasis remap='I'>prefix</emphasis> fields in the following | |
| 1787 | header block(s). The <command>pax</command> utility shall translate the pathname | |
| 1788 | of the file from the UTF-8 encoding to the character set | |
| 1789 | appropriate for the local file system.</para> | |
| 1790 | ||
| 1791 | <para>When used in <emphasis remap='B'>write</emphasis> or <emphasis remap='B'>copy</emphasis> mode, <command>pax</command> shall include | |
| 1792 | a <emphasis remap='I'>path</emphasis> extended header record for each file whose | |
| 1793 | pathname cannot be represented entirely with the members of the portable | |
| 1794 | character set other than NUL.</para> | |
| 1795 | </listitem> | |
| 1796 | </varlistentry> | |
| 1797 | <varlistentry> | |
| 1798 | <term><emphasis remap='B'>realtime.</emphasis><emphasis remap='I'>any</emphasis></term> | |
| 1799 | <listitem> | |
| 1800 | <para>The keywords prefixed by "realtime." are reserved for future standardization.</para> | |
| 1801 | </listitem> | |
| 1802 | </varlistentry> | |
| 1803 | <varlistentry> | |
| 1804 | <term><emphasis remap='B'>security.</emphasis><emphasis remap='I'>any</emphasis></term> | |
| 1805 | <listitem> | |
| 1806 | <para>The keywords prefixed by "security." are reserved for future standardization.</para> | |
| 1807 | </listitem> | |
| 1808 | </varlistentry> | |
| 1809 | <varlistentry> | |
| 1810 | <term><emphasis remap='B'>size</emphasis></term> | |
| 1811 | <listitem> | |
| 1812 | <para>The size of the file in octets, expressed as a decimal number using | |
| 1813 | digits from the ISO/IEC 646:1991 standard. This record | |
| 1814 | shall override the <emphasis remap='I'>size</emphasis> field in the following header block(s). | |
| 1815 | When used in <emphasis remap='B'>write</emphasis> or <emphasis remap='B'>copy</emphasis> mode, <command>pax</command> | |
| 1816 | shall include a <emphasis remap='I'>size</emphasis> extended header record for each file with | |
| 1817 | a size value greater than 8589934591 (octal | |
| 1818 | 77777777777).</para> | |
| 1819 | </listitem> | |
| 1820 | </varlistentry> | |
| 1821 | <varlistentry> | |
| 1822 | <term><emphasis remap='B'>uid</emphasis></term> | |
| 1823 | <listitem> | |
| 1824 | <para>The user ID of the file owner, expressed as a decimal number using | |
| 1825 | digits from the ISO/IEC 646:1991 standard. This record | |
| 1826 | shall override the <emphasis remap='I'>uid</emphasis> field in the following header block(s). | |
| 1827 | When used in <emphasis remap='B'>write</emphasis> or <emphasis remap='B'>copy</emphasis> mode, <command>pax</command> | |
| 1828 | shall include a <emphasis remap='I'>uid</emphasis> extended header record for each file whose | |
| 1829 | owner ID is greater than 2097151 (octal 7777777).</para> | |
| 1830 | </listitem> | |
| 1831 | </varlistentry> | |
| 1832 | <varlistentry> | |
| 1833 | <term><emphasis remap='B'>uname</emphasis></term> | |
| 1834 | <listitem> | |
| 1835 | <para>The owner of the following file(s), formatted as a user name in the | |
| 1836 | user database. This record shall override the <emphasis remap='I'>uid</emphasis> | |
| 1837 | and <emphasis remap='I'>uname</emphasis> fields in the following header block(s), and any <emphasis remap='I'>uid</emphasis> | |
| 1838 | extended header record. When used in <emphasis remap='B'>read</emphasis>, | |
| 1839 | <emphasis remap='B'>copy</emphasis>, or <emphasis remap='B'>list</emphasis> mode, <command>pax</command> shall translate the name | |
| 1840 | from the UTF-8 encoding in the header record to the character | |
| 1841 | set appropriate for the user database on the receiving system. If | |
| 1842 | any of the UTF-8 characters cannot be translated, and if the | |
| 1843 | <option>-o</option> <replaceable>invalid=</replaceable> UTF-8 option is not specified, the results | |
| 1844 | are implementation-defined. When used in <emphasis remap='B'>write</emphasis> or | |
| 1845 | <emphasis remap='B'>copy</emphasis> mode, <command>pax</command> shall include a <emphasis remap='B'>uname</emphasis> extended header | |
| 1846 | record for each file whose user name cannot be | |
| 1847 | represented entirely with the letters and digits of the portable character | |
| 1848 | set.</para> | |
| 1849 | ||
| 1850 | ||
| 1851 | <para>If the <<emphasis remap='I'>value</emphasis>> field is zero length, it shall delete any header | |
| 1852 | block field, previously entered extended header | |
| 1853 | value, or global extended header value of the same name.</para> | |
| 1854 | ||
| 1855 | <para>If a keyword in an extended header record (or in a <option>-o</option> option-argument) | |
| 1856 | overrides or deletes a corresponding field in the | |
| 1857 | <emphasis remap='B'>ustar</emphasis> header block, <command>pax</command> shall ignore the contents of that | |
| 1858 | header block field.</para> | |
| 1859 | ||
| 1860 | <para>Unlike the <emphasis remap='B'>ustar</emphasis> header block fields, NULs shall not delimit | |
| 1861 | <<emphasis remap='I'>value</emphasis>>s; all characters within the | |
| 1862 | <<emphasis remap='I'>value</emphasis>> field shall be considered data for the field. None of | |
| 1863 | the length limitations of the <emphasis remap='B'>ustar</emphasis> header block | |
| 1864 | fields in ustar Header Block shall apply to the extended header records.</para> | |
| 1865 | </listitem> | |
| 1866 | </varlistentry> | |
| 1867 | </variablelist> | |
| 1868 | </refsect2> | |
| 1869 | ||
| 1870 | <refsect2 id='pax_extended_header_keyword_precedence'><title>pax Extended Header Keyword Precedence</title> | |
| 1871 | ||
| 1872 | <para>This section describes the precedence in which the various header | |
| 1873 | records and fields and command line options are selected to | |
| 1874 | apply to a file in the archive. When <command>pax</command> is used in <emphasis remap='B'>read</emphasis> | |
| 1875 | or <emphasis remap='B'>list</emphasis> modes, it shall determine a file attribute in | |
| 1876 | the following sequence:</para> | |
| 1877 | <variablelist remap='IP'> | |
| 1878 | <varlistentry> | |
| 1879 | <term> 1.</term> | |
| 1880 | <listitem> | |
| 1881 | <para>If <option>-o</option> <replaceable>delete=</replaceable> <emphasis remap='I'>keyword-prefix</emphasis> is used, the affected | |
| 1882 | attributes shall be determined from step 7., if | |
| 1883 | applicable, or ignored otherwise.</para> | |
| 1884 | ||
| 1885 | </listitem> | |
| 1886 | </varlistentry> | |
| 1887 | <varlistentry> | |
| 1888 | <term> 2.</term> | |
| 1889 | <listitem> | |
| 1890 | <para>If <option>-o</option> <replaceable>keyword</replaceable>:= is used, the affected attributes shall | |
| 1891 | be ignored.</para> | |
| 1892 | ||
| 1893 | </listitem> | |
| 1894 | </varlistentry> | |
| 1895 | <varlistentry> | |
| 1896 | <term> 3.</term> | |
| 1897 | <listitem> | |
| 1898 | <para>If <option>-o</option> <replaceable>keyword</replaceable> <emphasis remap='B'>:=</emphasis> <emphasis remap='I'>value</emphasis> is used, the affected | |
| 1899 | attribute shall be assigned the value.</para> | |
| 1900 | ||
| 1901 | </listitem> | |
| 1902 | </varlistentry> | |
| 1903 | <varlistentry> | |
| 1904 | <term> 4.</term> | |
| 1905 | <listitem> | |
| 1906 | <para>If there is a <emphasis remap='I'>typeflag</emphasis> <emphasis remap='B'>x</emphasis> extended header record, the affected | |
| 1907 | attribute shall be assigned the | |
| 1908 | <<emphasis remap='I'>value</emphasis>>. When extended header records conflict, the last one | |
| 1909 | given in the header shall take precedence.</para> | |
| 1910 | ||
| 1911 | </listitem> | |
| 1912 | </varlistentry> | |
| 1913 | <varlistentry> | |
| 1914 | <term> 5.</term> | |
| 1915 | <listitem> | |
| 1916 | <para>If <option>-o</option> <replaceable>keyword</replaceable> <emphasis remap='B'>=</emphasis> <emphasis remap='I'>value</emphasis> is used, the affected | |
| 1917 | attribute shall be assigned the value.</para> | |
| 1918 | ||
| 1919 | </listitem> | |
| 1920 | </varlistentry> | |
| 1921 | <varlistentry> | |
| 1922 | <term> 6.</term> | |
| 1923 | <listitem> | |
| 1924 | <para>If there is a <emphasis remap='I'>typeflag</emphasis> <emphasis remap='B'>g</emphasis> global extended header record, | |
| 1925 | the affected attribute shall be assigned the | |
| 1926 | <<emphasis remap='I'>value</emphasis>>. When global extended header records conflict, the last | |
| 1927 | one given in the global header shall take | |
| 1928 | precedence.</para> | |
| 1929 | ||
| 1930 | </listitem> | |
| 1931 | </varlistentry> | |
| 1932 | <varlistentry> | |
| 1933 | <term> 7.</term> | |
| 1934 | <listitem> | |
| 1935 | <para>Otherwise, the attribute shall be determined from the <emphasis remap='B'>ustar</emphasis> | |
| 1936 | header block.</para> | |
| 1937 | ||
| 1938 | </listitem> | |
| 1939 | </varlistentry> | |
| 1940 | </variablelist> | |
| 1941 | </refsect2> | |
| 1942 | ||
| 1943 | <refsect2 id='pax_extended_header_file_times'><title>pax Extended Header File Times</title> | |
| 1944 | ||
| 1945 | <para>The <command>pax</command> utility shall write an <emphasis remap='B'>mtime</emphasis> record for each file | |
| 1946 | in <emphasis remap='B'>write</emphasis> or <emphasis remap='B'>copy</emphasis> modes if the file's | |
| 1947 | modification time cannot be represented exactly in the <emphasis remap='B'>ustar</emphasis> | |
| 1948 | header logical record described in ustar Interchange Format . This | |
| 1949 | can occur if the time is out of <emphasis remap='B'>ustar</emphasis> range, or if the file | |
| 1950 | system | |
| 1951 | of the underlying implementation supports non-integer time granularities | |
| 1952 | and the time is not an integer. All of these time records | |
| 1953 | shall be formatted as a decimal representation of the time in seconds | |
| 1954 | since the Epoch. If a period ( <emphasis remap='B'>'.'</emphasis> ) decimal point | |
| 1955 | character is present, the digits to the right of the point shall represent | |
| 1956 | the units of a subsecond timing granularity, where the | |
| 1957 | first digit is tenths of a second and each subsequent digit is a tenth | |
| 1958 | of the previous digit. In <emphasis remap='B'>read</emphasis> or <emphasis remap='B'>copy</emphasis> mode, | |
| 1959 | the <command>pax</command> utility shall truncate the time of a file to the greatest | |
| 1960 | value that is not greater than the input header file time. | |
| 1961 | In <emphasis remap='B'>write</emphasis> or <emphasis remap='B'>copy</emphasis> mode, the <command>pax</command> utility shall output | |
| 1962 | a time exactly if it can be represented exactly as a | |
| 1963 | decimal number, and otherwise shall generate only enough digits so | |
| 1964 | that the same time shall be recovered if the file is extracted | |
| 1965 | on a system whose underlying implementation supports the same time | |
| 1966 | granularity.</para> | |
| 1967 | </refsect2> | |
| 1968 | ||
| 1969 | <refsect2 id='ustar_interchange_format'><title>ustar Interchange Format</title> | |
| 1970 | ||
| 1971 | <para>A <emphasis remap='B'>ustar</emphasis> archive tape or file shall contain a series of logical | |
| 1972 | records. Each logical record shall be a fixed-size logical | |
| 1973 | record of 512 octets (see below). Although this format may be thought | |
| 1974 | of as being stored on 9-track industry-standard 12.7 mm (0.5 | |
| 1975 | in) magnetic tape, other types of transportable media are not excluded. | |
| 1976 | Each file archived shall be represented by a header logical | |
| 1977 | record that describes the file, followed by zero or more logical records | |
| 1978 | that give the contents of the file. At the end of the | |
| 1979 | archive file there shall be two 512-octet logical records filled with | |
| 1980 | binary zeros, interpreted as an end-of-archive indicator.</para> | |
| 1981 | ||
| 1982 | <para>The logical records may be grouped for physical I/O operations, as | |
| 1983 | described under the <option>-b</option> <replaceable>blocksize</replaceable> and <option>-x</option> | |
| 1984 | <replaceable>ustar</replaceable> options. Each group of logical records may be written | |
| 1985 | with a single operation equivalent to the <emphasis remap='I'>write</emphasis>() function. | |
| 1986 | On magnetic tape, the result of this write shall be a single tape | |
| 1987 | physical | |
| 1988 | block. The last physical block shall always be the full size, so logical | |
| 1989 | records after the two zero logical records may contain | |
| 1990 | undefined data.</para> | |
| 1991 | ||
| 1992 | <para>The header logical record shall be structured as shown in the following | |
| 1993 | table. All lengths and offsets are in decimal.</para> | |
| 1994 | <!-- br --> | |
| 1995 | ||
| 1996 | <blockquote remap='RS'> | |
| 1997 | <para></para> | |
| 1998 | ||
| 1999 | <table pgwide='0' frame='none'> | |
| 2000 | <title>Table: ustar Header Block</title> | |
| 2001 | <tgroup cols='7' align='center'> | |
| 2002 | <colspec colname='c1'/> | |
| 2003 | <colspec colname='c2'/> | |
| 2004 | <colspec colname='c3'/> | |
| 2005 | <colspec colname='c4'/> | |
| 2006 | <colspec colname='c5'/> | |
| 2007 | <colspec colname='c6'/> | |
| 2008 | <colspec colname='c7'/> | |
| 2009 | <tbody> | |
| 2010 | <row> | |
| 2011 | <entry align='center'><emphasis remap='B'>Field Name</emphasis></entry> | |
| 2012 | <entry align='right'><emphasis remap='B'>Octet Offset</emphasis></entry> | |
| 2013 | <entry align='right' namest='c3' nameend='c4'><emphasis remap='B'>Length (in Octets)</emphasis></entry> | |
| 2014 | </row> | |
| 2015 | <row> | |
| 2016 | <entry align='center'><emphasis remap='I'>name</emphasis></entry> | |
| 2017 | <entry align='right'>0</entry> | |
| 2018 | <entry align='right' namest='c3' nameend='c4'>100</entry> | |
| 2019 | </row> | |
| 2020 | <row> | |
| 2021 | <entry align='center'><emphasis remap='I'>mode</emphasis></entry> | |
| 2022 | <entry align='right'>100</entry> | |
| 2023 | <entry align='right' namest='c3' nameend='c4'>8</entry> | |
| 2024 | </row> | |
| 2025 | <row> | |
| 2026 | <entry align='center'><emphasis remap='I'>uid</emphasis></entry> | |
| 2027 | <entry align='right'>108</entry> | |
| 2028 | <entry align='right' namest='c3' nameend='c4'>8</entry> | |
| 2029 | </row> | |
| 2030 | <row> | |
| 2031 | <entry align='center'><emphasis remap='I'>gid</emphasis></entry> | |
| 2032 | <entry align='right'>116</entry> | |
| 2033 | <entry align='right' namest='c3' nameend='c4'>8</entry> | |
| 2034 | </row> | |
| 2035 | <row> | |
| 2036 | <entry align='center'><emphasis remap='I'>size</emphasis></entry> | |
| 2037 | <entry align='right'>124</entry> | |
| 2038 | <entry align='right' namest='c3' nameend='c4'>12</entry> | |
| 2039 | </row> | |
| 2040 | <row> | |
| 2041 | <entry align='center'><emphasis remap='I'>mtime</emphasis></entry> | |
| 2042 | <entry align='right'>136</entry> | |
| 2043 | <entry align='right' namest='c3' nameend='c4'>12</entry> | |
| 2044 | </row> | |
| 2045 | <row> | |
| 2046 | <entry align='center'><emphasis remap='I'>chksum</emphasis></entry> | |
| 2047 | <entry align='right'>148</entry> | |
| 2048 | <entry align='right' namest='c3' nameend='c4'>8</entry> | |
| 2049 | </row> | |
| 2050 | <row> | |
| 2051 | <entry align='center'><emphasis remap='I'>typeflag</emphasis></entry> | |
| 2052 | <entry align='right'>156</entry> | |
| 2053 | <entry align='right' namest='c3' nameend='c4'>1</entry> | |
| 2054 | </row> | |
| 2055 | <row> | |
| 2056 | <entry align='center'><emphasis remap='I'>linkname</emphasis></entry> | |
| 2057 | <entry align='right'>157</entry> | |
| 2058 | <entry align='right' namest='c3' nameend='c4'>100</entry> | |
| 2059 | </row> | |
| 2060 | <row> | |
| 2061 | <entry align='center'><emphasis remap='I'>magic</emphasis></entry> | |
| 2062 | <entry align='right'>257</entry> | |
| 2063 | <entry align='right' namest='c3' nameend='c4'>6</entry> | |
| 2064 | </row> | |
| 2065 | <row> | |
| 2066 | <entry align='center'><emphasis remap='I'>version</emphasis></entry> | |
| 2067 | <entry align='right'>263</entry> | |
| 2068 | <entry align='right' namest='c3' nameend='c4'>2</entry> | |
| 2069 | </row> | |
| 2070 | <row> | |
| 2071 | <entry align='center'><emphasis remap='I'>uname</emphasis></entry> | |
| 2072 | <entry align='right'>265</entry> | |
| 2073 | <entry align='right' namest='c3' nameend='c4'>32</entry> | |
| 2074 | </row> | |
| 2075 | <row> | |
| 2076 | <entry align='center'><emphasis remap='I'>gname</emphasis></entry> | |
| 2077 | <entry align='right'>297</entry> | |
| 2078 | <entry align='right' namest='c3' nameend='c4'>32</entry> | |
| 2079 | </row> | |
| 2080 | <row> | |
| 2081 | <entry align='center'><emphasis remap='I'>devmajor</emphasis></entry> | |
| 2082 | <entry align='right'>329</entry> | |
| 2083 | <entry align='right' namest='c3' nameend='c4'>8</entry> | |
| 2084 | </row> | |
| 2085 | <row> | |
| 2086 | <entry align='center'><emphasis remap='I'>devminor</emphasis></entry> | |
| 2087 | <entry align='right'>337</entry> | |
| 2088 | <entry align='right' namest='c3' nameend='c4'>8</entry> | |
| 2089 | </row> | |
| 2090 | <row> | |
| 2091 | <entry align='center'><emphasis remap='I'>prefix</emphasis></entry> | |
| 2092 | <entry align='right'>345</entry> | |
| 2093 | <entry align='right' namest='c3' nameend='c4'>155</entry> | |
| 2094 | </row> | |
| 2095 | </tbody> | |
| 2096 | </tgroup> | |
| 2097 | </table> | |
| 2098 | ||
| 2099 | ||
| 2100 | </blockquote> <!-- remap='RE' --> | |
| 2101 | ||
| 2102 | <para>All characters in the header logical record shall be represented in | |
| 2103 | the coded character set of the ISO/IEC 646:1991 | |
| 2104 | standard. For maximum portability between implementations, names should | |
| 2105 | be selected from characters represented by the portable | |
| 2106 | filename character set as octets with the most significant bit zero. | |
| 2107 | If an implementation supports the use of characters outside of | |
| 2108 | slash and the portable filename character set in names for files, | |
| 2109 | users, and groups, one or more implementation-defined encodings | |
| 2110 | of these characters shall be provided for interchange purposes.</para> | |
| 2111 | ||
| 2112 | <para>However, the <command>pax</command> utility shall never create filenames on the | |
| 2113 | local system that cannot be accessed via the procedures | |
| 2114 | described in IEEE Std 1003.1-2001. If a filename is found on the | |
| 2115 | medium that would create an invalid filename, it is | |
| 2116 | implementation-defined whether the data from the file is stored on | |
| 2117 | the file hierarchy and under what name it is stored. The | |
| 2118 | <command>pax</command> utility may choose to ignore these files as long as it produces | |
| 2119 | an error indicating that the file is being ignored.</para> | |
| 2120 | ||
| 2121 | <para>Each field within the header logical record is contiguous; that is, | |
| 2122 | there is no padding used. Each character on the archive | |
| 2123 | medium shall be stored contiguously.</para> | |
| 2124 | ||
| 2125 | <para>The fields <emphasis remap='I'>magic</emphasis>, <emphasis remap='I'>uname</emphasis>, and <emphasis remap='I'>gname</emphasis> are character | |
| 2126 | strings each terminated by a NUL character. The fields | |
| 2127 | <emphasis remap='I'>name</emphasis>, <emphasis remap='I'>linkname</emphasis>, and <emphasis remap='I'>prefix</emphasis> are NUL-terminated character | |
| 2128 | strings except when all characters in the array | |
| 2129 | contain non-NUL characters including the last character. The <emphasis remap='I'>version</emphasis> | |
| 2130 | field is two octets containing the characters | |
| 2131 | <emphasis remap='B'>"00"</emphasis> (zero-zero). The <emphasis remap='I'>typeflag</emphasis> contains a single character. | |
| 2132 | All other fields are leading zero-filled octal numbers | |
| 2133 | using digits from the ISO/IEC 646:1991 standard IRV. Each numeric | |
| 2134 | field is terminated by one or more <space> or NUL | |
| 2135 | characters.</para> | |
| 2136 | ||
| 2137 | <para>The <emphasis remap='I'>name</emphasis> and the <emphasis remap='I'>prefix</emphasis> fields shall produce the pathname | |
| 2138 | of the file. A new pathname shall be formed, if | |
| 2139 | <emphasis remap='I'>prefix</emphasis> is not an empty string (its first character is not NUL), | |
| 2140 | by concatenating <emphasis remap='I'>prefix</emphasis> (up to the first NUL | |
| 2141 | character), a slash character, and <emphasis remap='I'>name</emphasis>; otherwise, <emphasis remap='I'>name</emphasis> | |
| 2142 | is used alone. In either case, <emphasis remap='I'>name</emphasis> is terminated at | |
| 2143 | the first NUL character. If <emphasis remap='I'>prefix</emphasis> begins with a NUL character, | |
| 2144 | it shall be ignored. In this manner, pathnames of at most | |
| 2145 | 256 characters can be supported. If a pathname does not fit in the | |
| 2146 | space provided, <command>pax</command> shall notify the user of the error, | |
| 2147 | and shall not store any part of the file-header or data-on the medium.</para> | |
| 2148 | ||
| 2149 | <para>The <emphasis remap='I'>linkname</emphasis> field, described below, shall not use the <emphasis remap='I'>prefix</emphasis> | |
| 2150 | to produce a pathname. As such, a <emphasis remap='I'>linkname</emphasis> is | |
| 2151 | limited to 100 characters. If the name does not fit in the space provided, | |
| 2152 | <command>pax</command> shall notify the user of the error, and shall | |
| 2153 | not attempt to store the link on the medium.</para> | |
| 2154 | ||
| 2155 | <para>The <emphasis remap='I'>mode</emphasis> field provides 12 bits encoded in the ISO/IEC 646:1991 | |
| 2156 | standard octal digit representation. The encoded | |
| 2157 | bits shall represent the following values:</para> | |
| 2158 | <!-- br --> | |
| 2159 | ||
| 2160 | <blockquote remap='RS'> | |
| 2161 | <para></para> | |
| 2162 | ||
| 2163 | <table pgwide='0' frame='none'> | |
| 2164 | <title>Table: ustar <emphasis remap='I'>mode</emphasis> Field</title> | |
| 2165 | <tgroup cols='7' align='center'> | |
| 2166 | <colspec colname='c1'/> | |
| 2167 | <colspec colname='c2'/> | |
| 2168 | <colspec colname='c3'/> | |
| 2169 | <colspec colname='c4'/> | |
| 2170 | <colspec colname='c5'/> | |
| 2171 | <colspec colname='c6'/> | |
| 2172 | <colspec colname='c7'/> | |
| 2173 | <tbody> | |
| 2174 | <row> | |
| 2175 | <entry align='center'><emphasis remap='B'>Bit Value</emphasis></entry> | |
| 2176 | <entry align='right'><emphasis remap='B'>IEEE Std 1003.1-2001 Bit</emphasis></entry> | |
| 2177 | <entry align='right' namest='c3' nameend='c4'><!-- na --> | |
| 2178 | <para><emphasis remap='B'>Description</emphasis> | |
| 2179 | <!-- ad --></para></entry> | |
| 2180 | </row> | |
| 2181 | <row> | |
| 2182 | <entry align='center'>04000</entry> | |
| 2183 | <entry align='right'>S_ISUID</entry> | |
| 2184 | <entry align='right' namest='c3' nameend='c4'><!-- na --> | |
| 2185 | Set UID on execution. | |
| 2186 | <!-- ad --></entry> | |
| 2187 | </row> | |
| 2188 | <row> | |
| 2189 | <entry align='center'>02000</entry> | |
| 2190 | <entry align='right'>S_ISGID</entry> | |
| 2191 | <entry align='right' namest='c3' nameend='c4'><!-- na --> | |
| 2192 | Set GID on execution. | |
| 2193 | <!-- ad --></entry> | |
| 2194 | </row> | |
| 2195 | <row> | |
| 2196 | <entry align='center'>01000</entry> | |
| 2197 | <entry align='right'><reserved></entry> | |
| 2198 | <entry align='right' namest='c3' nameend='c4'><!-- na --> | |
| 2199 | Reserved for future standardization. | |
| 2200 | <!-- ad --></entry> | |
| 2201 | </row> | |
| 2202 | <row> | |
| 2203 | <entry align='center'>00400</entry> | |
| 2204 | <entry align='right'>S_IRUSR</entry> | |
| 2205 | <entry align='right' namest='c3' nameend='c4'><!-- na --> | |
| 2206 | Read permission for file owner class. | |
| 2207 | <!-- ad --></entry> | |
| 2208 | </row> | |
| 2209 | <row> | |
| 2210 | <entry align='center'>00200</entry> | |
| 2211 | <entry align='right'>S_IWUSR</entry> | |
| 2212 | <entry align='right' namest='c3' nameend='c4'><!-- na --> | |
| 2213 | Write permission for file owner class. | |
| 2214 | <!-- ad --></entry> | |
| 2215 | </row> | |
| 2216 | <row> | |
| 2217 | <entry align='center'>00100</entry> | |
| 2218 | <entry align='right'>S_IXUSR</entry> | |
| 2219 | <entry align='right' namest='c3' nameend='c4'><!-- na --> | |
| 2220 | Execute/search permission for file owner class. | |
| 2221 | <!-- ad --></entry> | |
| 2222 | </row> | |
| 2223 | <row> | |
| 2224 | <entry align='center'>00040</entry> | |
| 2225 | <entry align='right'>S_IRGRP</entry> | |
| 2226 | <entry align='right' namest='c3' nameend='c4'><!-- na --> | |
| 2227 | Read permission for file group class. | |
| 2228 | <!-- ad --></entry> | |
| 2229 | </row> | |
| 2230 | <row> | |
| 2231 | <entry align='center'>00020</entry> | |
| 2232 | <entry align='right'>S_IWGRP</entry> | |
| 2233 | <entry align='right' namest='c3' nameend='c4'><!-- na --> | |
| 2234 | Write permission for file group class. | |
| 2235 | <!-- ad --></entry> | |
| 2236 | </row> | |
| 2237 | <row> | |
| 2238 | <entry align='center'>00010</entry> | |
| 2239 | <entry align='right'>S_IXGRP</entry> | |
| 2240 | <entry align='right' namest='c3' nameend='c4'><!-- na --> | |
| 2241 | Execute/search permission for file group class. | |
| 2242 | <!-- ad --></entry> | |
| 2243 | </row> | |
| 2244 | <row> | |
| 2245 | <entry align='center'>00004</entry> | |
| 2246 | <entry align='right'>S_IROTH</entry> | |
| 2247 | <entry align='right' namest='c3' nameend='c4'><!-- na --> | |
| 2248 | Read permission for file other class. | |
| 2249 | <!-- ad --></entry> | |
| 2250 | </row> | |
| 2251 | <row> | |
| 2252 | <entry align='center'>00002</entry> | |
| 2253 | <entry align='right'>S_IWOTH</entry> | |
| 2254 | <entry align='right' namest='c3' nameend='c4'><!-- na --> | |
| 2255 | Write permission for file other class. | |
| 2256 | <!-- ad --></entry> | |
| 2257 | </row> | |
| 2258 | <row> | |
| 2259 | <entry align='center'>00001</entry> | |
| 2260 | <entry align='right'>S_IXOTH</entry> | |
| 2261 | <entry align='right' namest='c3' nameend='c4'><!-- na --> | |
| 2262 | Execute/search permission for file other class. | |
| 2263 | <!-- ad --></entry> | |
| 2264 | </row> | |
| 2265 | </tbody> | |
| 2266 | </tgroup> | |
| 2267 | </table> | |
| 2268 | ||
| 2269 | ||
| 2270 | </blockquote> <!-- remap='RE' --> | |
| 2271 | ||
| 2272 | <para>When appropriate privilege is required to set one of these mode bits, | |
| 2273 | and the user restoring the files from the archive does not | |
| 2274 | have the appropriate privilege, the mode bits for which the user does | |
| 2275 | not have appropriate privilege shall be ignored. Some of the | |
| 2276 | mode bits in the archive format are not mentioned elsewhere in this | |
| 2277 | volume of IEEE Std 1003.1-2001. If the implementation | |
| 2278 | does not support those bits, they may be ignored.</para> | |
| 2279 | ||
| 2280 | <para>The <emphasis remap='I'>uid</emphasis> and <emphasis remap='I'>gid</emphasis> fields are the user and group ID of the | |
| 2281 | owner and group of the file, respectively.</para> | |
| 2282 | ||
| 2283 | <para>The <emphasis remap='I'>size</emphasis> field is the size of the file in octets. If the <emphasis remap='I'>typeflag</emphasis> | |
| 2284 | field is set to specify a file to be of type 1 | |
| 2285 | (a link) or 2 (a symbolic link), the <emphasis remap='I'>size</emphasis> field shall be specified | |
| 2286 | as zero. If the <emphasis remap='I'>typeflag</emphasis> field is set to specify a | |
| 2287 | file of type 5 (directory), the <emphasis remap='I'>size</emphasis> field shall be interpreted | |
| 2288 | as described under the definition of that record type. No | |
| 2289 | data logical records are stored for types 1, 2, or 5. If the <emphasis remap='I'>typeflag</emphasis> | |
| 2290 | field is set to 3 (character special file), 4 (block | |
| 2291 | special file), or 6 (FIFO), the meaning of the <emphasis remap='I'>size</emphasis> field is | |
| 2292 | unspecified by this volume of IEEE Std 1003.1-2001, | |
| 2293 | and no data logical records shall be stored on the medium. Additionally, | |
| 2294 | for type 6, the <emphasis remap='I'>size</emphasis> field shall be ignored when | |
| 2295 | reading. If the <emphasis remap='I'>typeflag</emphasis> field is set to any other value, the | |
| 2296 | number of logical records written following the header shall | |
| 2297 | be ( <emphasis remap='I'>size</emphasis>+511)/512, ignoring any fraction in the result of the | |
| 2298 | division.</para> | |
| 2299 | ||
| 2300 | <para>The <emphasis remap='I'>mtime</emphasis> field shall be the modification time of the file at | |
| 2301 | the time it was archived. It is the ISO/IEC 646:1991 | |
| 2302 | standard representation of the octal value of the modification time | |
| 2303 | obtained from the <emphasis remap='I'>stat</emphasis>() function.</para> | |
| 2304 | ||
| 2305 | <para>The <emphasis remap='I'>chksum</emphasis> field shall be the ISO/IEC 646:1991 standard IRV | |
| 2306 | representation of the octal value of the simple sum of | |
| 2307 | all octets in the header logical record. Each octet in the header | |
| 2308 | shall be treated as an unsigned value. These values shall be | |
| 2309 | added to an unsigned integer, initialized to zero, the precision of | |
| 2310 | which is not less than 17 bits. When calculating the checksum, | |
| 2311 | the <emphasis remap='I'>chksum</emphasis> field is treated as if it were all spaces.</para> | |
| 2312 | ||
| 2313 | <para>The <emphasis remap='I'>typeflag</emphasis> field specifies the type of file archived. If a | |
| 2314 | particular implementation does not recognize the type, or | |
| 2315 | the user does not have appropriate privilege to create that type, | |
| 2316 | the file shall be extracted as if it were a regular file if the | |
| 2317 | file type is defined to have a meaning for the <emphasis remap='I'>size</emphasis> field that | |
| 2318 | could cause data logical records to be written on the medium | |
| 2319 | (see the previous description for <emphasis remap='I'>size</emphasis>). If conversion to a | |
| 2320 | regular file occurs, the <command>pax</command> utility shall produce an | |
| 2321 | error indicating that the conversion took place. All of the <emphasis remap='I'>typeflag</emphasis> | |
| 2322 | fields shall be coded in the ISO/IEC 646:1991 | |
| 2323 | standard IRV:</para> | |
| 2324 | <variablelist remap='TP'> | |
| 2325 | <varlistentry> | |
| 2326 | <term><literal>0</literal></term> | |
| 2327 | <listitem> | |
| 2328 | <para>Represents a regular file. For backwards-compatibility, a <emphasis remap='I'>typeflag</emphasis> | |
| 2329 | value of binary zero ( <emphasis remap='B'>'\0'</emphasis> ) should be | |
| 2330 | recognized as meaning a regular file when extracting files from the | |
| 2331 | archive. Archives written with this version of the archive file | |
| 2332 | format create regular files with a <emphasis remap='I'>typeflag</emphasis> value of the ISO/IEC 646:1991 | |
| 2333 | standard IRV <emphasis remap='B'>'0'</emphasis> .</para> | |
| 2334 | </listitem> | |
| 2335 | </varlistentry> | |
| 2336 | <varlistentry> | |
| 2337 | <term><literal>1</literal></term> | |
| 2338 | <listitem> | |
| 2339 | <para>Represents a file linked to another file, of any type, previously | |
| 2340 | archived. Such files are identified by each file having the | |
| 2341 | same device and file serial number. The linked-to name is specified | |
| 2342 | in the <emphasis remap='I'>linkname</emphasis> field with a NUL-character terminator if | |
| 2343 | it is less than 100 octets in length.</para> | |
| 2344 | </listitem> | |
| 2345 | </varlistentry> | |
| 2346 | <varlistentry> | |
| 2347 | <term><literal>2</literal></term> | |
| 2348 | <listitem> | |
| 2349 | <para>Represents a symbolic link. The contents of the symbolic link shall | |
| 2350 | be stored in the <emphasis remap='I'>linkname</emphasis> field.</para> | |
| 2351 | </listitem> | |
| 2352 | </varlistentry> | |
| 2353 | <varlistentry> | |
| 2354 | <term><emphasis remap='B'>3,4</emphasis></term> | |
| 2355 | <listitem> | |
| 2356 | <para>Represent character special files and block special files respectively. | |
| 2357 | In this case the <emphasis remap='I'>devmajor</emphasis> and <emphasis remap='I'>devminor</emphasis> | |
| 2358 | fields shall contain information defining the device, the format of | |
| 2359 | which is unspecified by this volume of | |
| 2360 | IEEE Std 1003.1-2001. Implementations may map the device specifications | |
| 2361 | to their own local specification or may ignore | |
| 2362 | the entry.</para> | |
| 2363 | </listitem> | |
| 2364 | </varlistentry> | |
| 2365 | <varlistentry> | |
| 2366 | <term><literal>5</literal></term> | |
| 2367 | <listitem> | |
| 2368 | <para>Specifies a directory or subdirectory. On systems where disk allocation | |
| 2369 | is performed on a directory basis, the <emphasis remap='I'>size</emphasis> | |
| 2370 | field shall contain the maximum number of octets (which may be rounded | |
| 2371 | to the nearest disk block allocation unit) that the | |
| 2372 | directory may hold. A <emphasis remap='I'>size</emphasis> field of zero indicates no such limiting. | |
| 2373 | Systems that do not support limiting in this manner | |
| 2374 | should ignore the <emphasis remap='I'>size</emphasis> field.</para> | |
| 2375 | </listitem> | |
| 2376 | </varlistentry> | |
| 2377 | <varlistentry> | |
| 2378 | <term><literal>6</literal></term> | |
| 2379 | <listitem> | |
| 2380 | <para>Specifies a FIFO special file. Note that the archiving of a FIFO file | |
| 2381 | archives the existence of this file and not its | |
| 2382 | contents.</para> | |
| 2383 | </listitem> | |
| 2384 | </varlistentry> | |
| 2385 | <varlistentry> | |
| 2386 | <term><literal>7</literal></term> | |
| 2387 | <listitem> | |
| 2388 | <para>Reserved to represent a file to which an implementation has associated | |
| 2389 | some high-performance attribute. Implementations without | |
| 2390 | such extensions should treat this file as a regular file (type 0).</para> | |
| 2391 | </listitem> | |
| 2392 | </varlistentry> | |
| 2393 | <varlistentry> | |
| 2394 | <term><emphasis remap='B'>A-Z</emphasis></term> | |
| 2395 | <listitem> | |
| 2396 | <para>The letters <emphasis remap='B'>'A'</emphasis> to <emphasis remap='B'>'Z'</emphasis> , inclusive, are reserved for custom | |
| 2397 | implementations. All other values are reserved | |
| 2398 | for future versions of IEEE Std 1003.1-2001.</para> | |
| 2399 | ||
| 2400 | ||
| 2401 | <para>Attempts to archive a socket using <emphasis remap='B'>ustar</emphasis> interchange format | |
| 2402 | shall produce a diagnostic message. Handling of other file | |
| 2403 | types is implementation-defined.</para> | |
| 2404 | ||
| 2405 | <para>The <emphasis remap='I'>magic</emphasis> field is the specification that this archive was output | |
| 2406 | in this archive format. If this field contains | |
| 2407 | <emphasis remap='B'>ustar</emphasis> (the five characters from the ISO/IEC 646:1991 standard | |
| 2408 | IRV shown followed by NUL), the <emphasis remap='I'>uname</emphasis> and | |
| 2409 | <emphasis remap='I'>gname</emphasis> fields shall contain the ISO/IEC 646:1991 standard IRV | |
| 2410 | representation of the owner and group of the file, | |
| 2411 | respectively (truncated to fit, if necessary). When the file is restored | |
| 2412 | by a privileged, protection-preserving version of the | |
| 2413 | utility, the user and group databases shall be scanned for these names. | |
| 2414 | If found, the user and group IDs contained within these | |
| 2415 | files shall be used rather than the values contained within the <emphasis remap='I'>uid</emphasis> | |
| 2416 | and <emphasis remap='I'>gid</emphasis> fields.</para> | |
| 2417 | </listitem> | |
| 2418 | </varlistentry> | |
| 2419 | </variablelist> | |
| 2420 | </refsect2> | |
| 2421 | ||
| 2422 | <refsect2 id='cpio_interchange_format'><title>cpio Interchange Format</title> | |
| 2423 | ||
| 2424 | <para>The octet-oriented <emphasis remap='B'>cpio</emphasis> archive format shall be a series of | |
| 2425 | entries, each comprising a header that describes the file, | |
| 2426 | the name of the file, and then the contents of the file.</para> | |
| 2427 | ||
| 2428 | <para>An archive may be recorded as a series of fixed-size blocks of octets. | |
| 2429 | This blocking shall be used only to make physical I/O | |
| 2430 | more efficient. The last group of blocks shall always be at the full | |
| 2431 | size.</para> | |
| 2432 | ||
| 2433 | <para>For the octet-oriented <emphasis remap='B'>cpio</emphasis> archive format, the individual entry | |
| 2434 | information shall be in the order indicated and | |
| 2435 | described by the following table; see also the <emphasis remap='I'><cpio.h></emphasis> header.</para> | |
| 2436 | <!-- br --> | |
| 2437 | ||
| 2438 | <blockquote remap='RS'> | |
| 2439 | <para></para> | |
| 2440 | ||
| 2441 | <table pgwide='0' frame='none'> | |
| 2442 | <title>Table: Octet-Oriented cpio Archive Entry</title> | |
| 2443 | <tgroup cols='7' align='center'> | |
| 2444 | <colspec colname='c1'/> | |
| 2445 | <colspec colname='c2'/> | |
| 2446 | <colspec colname='c3'/> | |
| 2447 | <colspec colname='c4'/> | |
| 2448 | <colspec colname='c5'/> | |
| 2449 | <colspec colname='c6'/> | |
| 2450 | <colspec colname='c7'/> | |
| 2451 | <tbody> | |
| 2452 | <row> | |
| 2453 | <entry align='center'><emphasis remap='B'>Header Field Name</emphasis></entry> | |
| 2454 | <entry align='right'><emphasis remap='B'>Length (in Octets)</emphasis></entry> | |
| 2455 | <entry align='right' namest='c3' nameend='c4'><emphasis remap='B'>Interpreted as</emphasis></entry> | |
| 2456 | </row> | |
| 2457 | <row> | |
| 2458 | <entry align='center'><emphasis remap='I'>c_magic</emphasis></entry> | |
| 2459 | <entry align='right'>6</entry> | |
| 2460 | <entry align='right' namest='c3' nameend='c4'>Octal number</entry> | |
| 2461 | </row> | |
| 2462 | <row> | |
| 2463 | <entry align='center'><emphasis remap='I'>c_dev</emphasis></entry> | |
| 2464 | <entry align='right'>6</entry> | |
| 2465 | <entry align='right' namest='c3' nameend='c4'>Octal number</entry> | |
| 2466 | </row> | |
| 2467 | <row> | |
| 2468 | <entry align='center'><emphasis remap='I'>c_ino</emphasis></entry> | |
| 2469 | <entry align='right'>6</entry> | |
| 2470 | <entry align='right' namest='c3' nameend='c4'>Octal number</entry> | |
| 2471 | </row> | |
| 2472 | <row> | |
| 2473 | <entry align='center'><emphasis remap='I'>c_mode</emphasis></entry> | |
| 2474 | <entry align='right'>6</entry> | |
| 2475 | <entry align='right' namest='c3' nameend='c4'>Octal number</entry> | |
| 2476 | </row> | |
| 2477 | <row> | |
| 2478 | <entry align='center'><emphasis remap='I'>c_uid</emphasis></entry> | |
| 2479 | <entry align='right'>6</entry> | |
| 2480 | <entry align='right' namest='c3' nameend='c4'>Octal number</entry> | |
| 2481 | </row> | |
| 2482 | <row> | |
| 2483 | <entry align='center'><emphasis remap='I'>c_gid</emphasis></entry> | |
| 2484 | <entry align='right'>6</entry> | |
| 2485 | <entry align='right' namest='c3' nameend='c4'>Octal number</entry> | |
| 2486 | </row> | |
| 2487 | <row> | |
| 2488 | <entry align='center'><emphasis remap='I'>c_nlink</emphasis></entry> | |
| 2489 | <entry align='right'>6</entry> | |
| 2490 | <entry align='right' namest='c3' nameend='c4'>Octal number</entry> | |
| 2491 | </row> | |
| 2492 | <row> | |
| 2493 | <entry align='center'><emphasis remap='I'>c_rdev</emphasis></entry> | |
| 2494 | <entry align='right'>6</entry> | |
| 2495 | <entry align='right' namest='c3' nameend='c4'>Octal number</entry> | |
| 2496 | </row> | |
| 2497 | <row> | |
| 2498 | <entry align='center'><emphasis remap='I'>c_mtime</emphasis></entry> | |
| 2499 | <entry align='right'>11</entry> | |
| 2500 | <entry align='right' namest='c3' nameend='c4'>Octal number</entry> | |
| 2501 | </row> | |
| 2502 | <row> | |
| 2503 | <entry align='center'><emphasis remap='I'>c_namesize</emphasis></entry> | |
| 2504 | <entry align='right'>6</entry> | |
| 2505 | <entry align='right' namest='c3' nameend='c4'>Octal number</entry> | |
| 2506 | </row> | |
| 2507 | <row> | |
| 2508 | <entry align='center'><emphasis remap='I'>c_filesize</emphasis></entry> | |
| 2509 | <entry align='right'>11</entry> | |
| 2510 | <entry align='right' namest='c3' nameend='c4'>Octal number</entry> | |
| 2511 | </row> | |
| 2512 | <row> | |
| 2513 | <entry align='center'><emphasis remap='B'>Filename Field Name</emphasis></entry> | |
| 2514 | <entry align='right'><emphasis remap='B'>Length</emphasis></entry> | |
| 2515 | <entry align='right' namest='c3' nameend='c4'><emphasis remap='B'>Interpreted as</emphasis></entry> | |
| 2516 | </row> | |
| 2517 | <row> | |
| 2518 | <entry align='center'><emphasis remap='I'>c_name</emphasis></entry> | |
| 2519 | <entry align='right'><emphasis remap='I'>c_namesize</emphasis></entry> | |
| 2520 | <entry align='right' namest='c3' nameend='c4'>Pathname string</entry> | |
| 2521 | </row> | |
| 2522 | <row> | |
| 2523 | <entry align='center'><emphasis remap='B'>File Data Field Name</emphasis></entry> | |
| 2524 | <entry align='right'><emphasis remap='B'>Length</emphasis></entry> | |
| 2525 | <entry align='right' namest='c3' nameend='c4'><emphasis remap='B'>Interpreted as</emphasis></entry> | |
| 2526 | </row> | |
| 2527 | <row> | |
| 2528 | <entry align='center'><emphasis remap='I'>c_filedata</emphasis></entry> | |
| 2529 | <entry align='right'><emphasis remap='I'>c_filesize</emphasis></entry> | |
| 2530 | <entry align='right' namest='c3' nameend='c4'>Data</entry> | |
| 2531 | </row> | |
| 2532 | </tbody> | |
| 2533 | </tgroup> | |
| 2534 | </table> | |
| 2535 | ||
| 2536 | ||
| 2537 | </blockquote> <!-- remap='RE' --> | |
| 2538 | </refsect2> | |
| 2539 | ||
| 2540 | <refsect2 id='cpio_header'><title>cpio Header</title> | |
| 2541 | ||
| 2542 | <para>For each file in the archive, a header as defined previously shall | |
| 2543 | be written. The information in the header fields is written | |
| 2544 | as streams of the ISO/IEC 646:1991 standard characters interpreted | |
| 2545 | as octal numbers. The octal numbers shall be extended to | |
| 2546 | the necessary length by appending the ISO/IEC 646:1991 standard IRV | |
| 2547 | zeros at the most-significant-digit end of the number; the | |
| 2548 | result is written to the most-significant digit of the stream of octets | |
| 2549 | first. The fields shall be interpreted as follows:</para> | |
| 2550 | <variablelist remap='TP'> | |
| 2551 | <varlistentry> | |
| 2552 | <term><emphasis remap='I'>c_magic</emphasis></term> | |
| 2553 | <listitem> | |
| 2554 | <para>Identify the archive as being a transportable archive by containing | |
| 2555 | the identifying value <emphasis remap='B'>"070707"</emphasis> .</para> | |
| 2556 | </listitem> | |
| 2557 | </varlistentry> | |
| 2558 | <varlistentry> | |
| 2559 | <term><emphasis remap='I'>c_dev</emphasis>, <emphasis remap='I'>c_ino</emphasis></term> | |
| 2560 | <listitem> | |
| 2561 | <para>Contains values that uniquely identify the file within the archive | |
| 2562 | (that is, no files contain the same pair of <emphasis remap='I'>c_dev</emphasis> and | |
| 2563 | <emphasis remap='I'>c_ino</emphasis> values unless they are links to the same file). The values | |
| 2564 | shall be determined in an unspecified manner.</para> | |
| 2565 | </listitem> | |
| 2566 | </varlistentry> | |
| 2567 | <varlistentry> | |
| 2568 | <term><emphasis remap='I'>c_mode</emphasis></term> | |
| 2569 | <listitem> | |
| 2570 | <para>Contains the file type and access permissions as defined in the following | |
| 2571 | table.</para> | |
| 2572 | <!-- br --> | |
| 2573 | ||
| 2574 | <blockquote remap='RS'> | |
| 2575 | <para></para> | |
| 2576 | ||
| 2577 | <table pgwide='0' frame='none'> | |
| 2578 | <title>Table: Values for cpio c_mode Field</title> | |
| 2579 | <tgroup cols='7' align='center'> | |
| 2580 | <colspec colname='c1'/> | |
| 2581 | <colspec colname='c2'/> | |
| 2582 | <colspec colname='c3'/> | |
| 2583 | <colspec colname='c4'/> | |
| 2584 | <colspec colname='c5'/> | |
| 2585 | <colspec colname='c6'/> | |
| 2586 | <colspec colname='c7'/> | |
| 2587 | <tbody> | |
| 2588 | <row> | |
| 2589 | <entry align='center'><emphasis remap='B'>File Permissions Name</emphasis></entry> | |
| 2590 | <entry align='right'><emphasis remap='B'>Value</emphasis></entry> | |
| 2591 | <entry align='right' namest='c3' nameend='c4'><emphasis remap='B'>Indicates</emphasis></entry> | |
| 2592 | </row> | |
| 2593 | <row> | |
| 2594 | <entry align='center'>C_IRUSR</entry> | |
| 2595 | <entry align='right'>000400</entry> | |
| 2596 | <entry align='right' namest='c3' nameend='c4'>Read by owner</entry> | |
| 2597 | </row> | |
| 2598 | <row> | |
| 2599 | <entry align='center'>C_IWUSR</entry> | |
| 2600 | <entry align='right'>000200</entry> | |
| 2601 | <entry align='right' namest='c3' nameend='c4'>Write by owner</entry> | |
| 2602 | </row> | |
| 2603 | <row> | |
| 2604 | <entry align='center'>C_IXUSR</entry> | |
| 2605 | <entry align='right'>000100</entry> | |
| 2606 | <entry align='right' namest='c3' nameend='c4'>Execute by owner</entry> | |
| 2607 | </row> | |
| 2608 | <row> | |
| 2609 | <entry align='center'>C_IRGRP</entry> | |
| 2610 | <entry align='right'>000040</entry> | |
| 2611 | <entry align='right' namest='c3' nameend='c4'>Read by group</entry> | |
| 2612 | </row> | |
| 2613 | <row> | |
| 2614 | <entry align='center'>C_IWGRP</entry> | |
| 2615 | <entry align='right'>000020</entry> | |
| 2616 | <entry align='right' namest='c3' nameend='c4'>Write by group</entry> | |
| 2617 | </row> | |
| 2618 | <row> | |
| 2619 | <entry align='center'>C_IXGRP</entry> | |
| 2620 | <entry align='right'>000010</entry> | |
| 2621 | <entry align='right' namest='c3' nameend='c4'>Execute by group</entry> | |
| 2622 | </row> | |
| 2623 | <row> | |
| 2624 | <entry align='center'>C_IROTH</entry> | |
| 2625 | <entry align='right'>000004</entry> | |
| 2626 | <entry align='right' namest='c3' nameend='c4'>Read by others</entry> | |
| 2627 | </row> | |
| 2628 | <row> | |
| 2629 | <entry align='center'>C_IWOTH</entry> | |
| 2630 | <entry align='right'>000002</entry> | |
| 2631 | <entry align='right' namest='c3' nameend='c4'>Write by others</entry> | |
| 2632 | </row> | |
| 2633 | <row> | |
| 2634 | <entry align='center'>C_IXOTH</entry> | |
| 2635 | <entry align='right'>000001</entry> | |
| 2636 | <entry align='right' namest='c3' nameend='c4'>Execute by others</entry> | |
| 2637 | </row> | |
| 2638 | <row> | |
| 2639 | <entry align='center'>C_ISUID</entry> | |
| 2640 | <entry align='right'>004000</entry> | |
| 2641 | <entry align='right' namest='c3' nameend='c4'>Set <emphasis remap='I'>uid</emphasis></entry> | |
| 2642 | </row> | |
| 2643 | <row> | |
| 2644 | <entry align='center'>C_ISGID</entry> | |
| 2645 | <entry align='right'>002000</entry> | |
| 2646 | <entry align='right' namest='c3' nameend='c4'>Set <emphasis remap='I'>gid</emphasis></entry> | |
| 2647 | </row> | |
| 2648 | <row> | |
| 2649 | <entry align='center'>C_ISVTX</entry> | |
| 2650 | <entry align='right'>001000</entry> | |
| 2651 | <entry align='right' namest='c3' nameend='c4'>Reserved</entry> | |
| 2652 | </row> | |
| 2653 | <row> | |
| 2654 | <entry align='center'><emphasis remap='B'>File Type Name</emphasis></entry> | |
| 2655 | <entry align='right'><emphasis remap='B'>Value</emphasis></entry> | |
| 2656 | <entry align='right' namest='c3' nameend='c4'><emphasis remap='B'>Indicates</emphasis></entry> | |
| 2657 | </row> | |
| 2658 | <row> | |
| 2659 | <entry align='center'>C_ISDIR</entry> | |
| 2660 | <entry align='right'>040000</entry> | |
| 2661 | <entry align='right' namest='c3' nameend='c4'>Directory</entry> | |
| 2662 | </row> | |
| 2663 | <row> | |
| 2664 | <entry align='center'>C_ISFIFO</entry> | |
| 2665 | <entry align='right'>010000</entry> | |
| 2666 | <entry align='right' namest='c3' nameend='c4'>FIFO</entry> | |
| 2667 | </row> | |
| 2668 | <row> | |
| 2669 | <entry align='center'>C_ISREG</entry> | |
| 2670 | <entry align='right'>0100000</entry> | |
| 2671 | <entry align='right' namest='c3' nameend='c4'>Regular file</entry> | |
| 2672 | </row> | |
| 2673 | <row> | |
| 2674 | <entry align='center'>C_ISLNK</entry> | |
| 2675 | <entry align='right'>0120000</entry> | |
| 2676 | <entry align='right' namest='c3' nameend='c4'>Symbolic link</entry> | |
| 2677 | </row> | |
| 2678 | <row> | |
| 2679 | <entry align='center'>C_ISBLK</entry> | |
| 2680 | <entry align='right'>060000</entry> | |
| 2681 | <entry align='right' namest='c3' nameend='c4'>Block special file</entry> | |
| 2682 | </row> | |
| 2683 | <row> | |
| 2684 | <entry align='center'>C_ISCHR</entry> | |
| 2685 | <entry align='right'>020000</entry> | |
| 2686 | <entry align='right' namest='c3' nameend='c4'>Character special file</entry> | |
| 2687 | </row> | |
| 2688 | <row> | |
| 2689 | <entry align='center'>C_ISSOCK</entry> | |
| 2690 | <entry align='right'>0140000</entry> | |
| 2691 | <entry align='right' namest='c3' nameend='c4'>Socket</entry> | |
| 2692 | </row> | |
| 2693 | <row> | |
| 2694 | <entry align='center'>C_ISCTG</entry> | |
| 2695 | <entry align='right'>0110000</entry> | |
| 2696 | <entry align='right' namest='c3' nameend='c4'>Reserved</entry> | |
| 2697 | </row> | |
| 2698 | </tbody> | |
| 2699 | </tgroup> | |
| 2700 | </table> | |
| 2701 | ||
| 2702 | ||
| 2703 | </blockquote> <!-- remap='RE' --> | |
| 2704 | ||
| 2705 | <para>Directories, FIFOs, symbolic links, and regular files shall be supported | |
| 2706 | on a system conforming to this volume of | |
| 2707 | IEEE Std 1003.1-2001; additional values defined previously are reserved | |
| 2708 | for compatibility with existing systems. | |
| 2709 | Additional file types may be supported; however, such files should | |
| 2710 | not be written to archives intended to be transported to other | |
| 2711 | systems.</para> | |
| 2712 | </listitem> | |
| 2713 | </varlistentry> | |
| 2714 | <varlistentry> | |
| 2715 | <term><emphasis remap='I'>c_uid</emphasis></term> | |
| 2716 | <listitem> | |
| 2717 | <para>Contains the user ID of the owner.</para> | |
| 2718 | </listitem> | |
| 2719 | </varlistentry> | |
| 2720 | <varlistentry> | |
| 2721 | <term><emphasis remap='I'>c_gid</emphasis></term> | |
| 2722 | <listitem> | |
| 2723 | <para>Contains the group ID of the group.</para> | |
| 2724 | </listitem> | |
| 2725 | </varlistentry> | |
| 2726 | <varlistentry> | |
| 2727 | <term><emphasis remap='I'>c_nlink</emphasis></term> | |
| 2728 | <listitem> | |
| 2729 | <para>Contains the number of links referencing the file at the time the | |
| 2730 | archive was created.</para> | |
| 2731 | </listitem> | |
| 2732 | </varlistentry> | |
| 2733 | <varlistentry> | |
| 2734 | <term><emphasis remap='I'>c_rdev</emphasis></term> | |
| 2735 | <listitem> | |
| 2736 | <para>Contains implementation-defined information for character or block | |
| 2737 | special files.</para> | |
| 2738 | </listitem> | |
| 2739 | </varlistentry> | |
| 2740 | <varlistentry> | |
| 2741 | <term><emphasis remap='I'>c_mtime</emphasis></term> | |
| 2742 | <listitem> | |
| 2743 | <para>Contains the latest time of modification of the file at the time the | |
| 2744 | archive was created.</para> | |
| 2745 | </listitem> | |
| 2746 | </varlistentry> | |
| 2747 | <varlistentry> | |
| 2748 | <term><emphasis remap='I'>c_namesize</emphasis></term> | |
| 2749 | <listitem> | |
| 2750 | <para>Contains the length of the pathname, including the terminating NUL | |
| 2751 | character.</para> | |
| 2752 | </listitem> | |
| 2753 | </varlistentry> | |
| 2754 | <varlistentry> | |
| 2755 | <term><emphasis remap='I'>c_filesize</emphasis></term> | |
| 2756 | <listitem> | |
| 2757 | <para>Contains the length of the file in octets. This shall be the length | |
| 2758 | of the data section following the header structure.</para> | |
| 2759 | ||
| 2760 | </listitem> | |
| 2761 | </varlistentry> | |
| 2762 | </variablelist> | |
| 2763 | </refsect2> | |
| 2764 | ||
| 2765 | <refsect2 id='cpio_filename'><title>cpio Filename</title> | |
| 2766 | ||
| 2767 | <para>The <emphasis remap='I'>c_name</emphasis> field shall contain the pathname of the file. The | |
| 2768 | length of this field in octets is the value of | |
| 2769 | <emphasis remap='I'>c_namesize</emphasis>.</para> | |
| 2770 | ||
| 2771 | <para>If a filename is found on the medium that would create an invalid | |
| 2772 | pathname, it is implementation-defined whether the data from | |
| 2773 | the file is stored on the file hierarchy and under what name it is | |
| 2774 | stored.</para> | |
| 2775 | ||
| 2776 | <para>All characters shall be represented in the ISO/IEC 646:1991 standard | |
| 2777 | IRV. For maximum portability between implementations, | |
| 2778 | names should be selected from characters represented by the portable | |
| 2779 | filename character set as octets with the most significant bit | |
| 2780 | zero. If an implementation supports the use of characters outside | |
| 2781 | the portable filename character set in names for files, users, | |
| 2782 | and groups, one or more implementation-defined encodings of these | |
| 2783 | characters shall be provided for interchange purposes. However, | |
| 2784 | the <command>pax</command> utility shall never create filenames on the local system | |
| 2785 | that cannot be accessed via the procedures described | |
| 2786 | previously in this volume of IEEE Std 1003.1-2001. If a filename | |
| 2787 | is found on the medium that would create an invalid | |
| 2788 | filename, it is implementation-defined whether the data from the file | |
| 2789 | is stored on the local file system and under what name it is | |
| 2790 | stored. The <command>pax</command> utility may choose to ignore these files as | |
| 2791 | long as it produces an error indicating that the file is being | |
| 2792 | ignored.</para> | |
| 2793 | </refsect2> | |
| 2794 | ||
| 2795 | <refsect2 id='cpio_file_data'><title>cpio File Data</title> | |
| 2796 | ||
| 2797 | <para>Following <emphasis remap='I'>c_name</emphasis>, there shall be <emphasis remap='I'>c_filesize</emphasis> octets of | |
| 2798 | data. Interpretation of such data occurs in a manner | |
| 2799 | dependent on the file. If <emphasis remap='I'>c_filesize</emphasis> is zero, no data shall | |
| 2800 | be contained in <emphasis remap='I'>c_filedata</emphasis>.</para> | |
| 2801 | ||
| 2802 | <para>When restoring from an archive:</para> | |
| 2803 | <variablelist remap='IP'> | |
| 2804 | <varlistentry> | |
| 2805 | <term> *</term> | |
| 2806 | <listitem> | |
| 2807 | <para>If the user does not have the appropriate privilege to create a file | |
| 2808 | of the specified type, <command>pax</command> shall ignore the entry | |
| 2809 | and write an error message to standard error.</para> | |
| 2810 | ||
| 2811 | </listitem> | |
| 2812 | </varlistentry> | |
| 2813 | <varlistentry> | |
| 2814 | <term> *</term> | |
| 2815 | <listitem> | |
| 2816 | <para>Only regular files have data to be restored. Presuming a regular file | |
| 2817 | meets any selection criteria that might be imposed on the | |
| 2818 | format-reading utility by the user, such data shall be restored.</para> | |
| 2819 | ||
| 2820 | </listitem> | |
| 2821 | </varlistentry> | |
| 2822 | <varlistentry> | |
| 2823 | <term> *</term> | |
| 2824 | <listitem> | |
| 2825 | <para>If a user does not have appropriate privilege to set a particular | |
| 2826 | mode flag, the flag shall be ignored. Some of the mode flags | |
| 2827 | in the archive format are not mentioned elsewhere in this volume of | |
| 2828 | IEEE Std 1003.1-2001. If the implementation does not | |
| 2829 | support those flags, they may be ignored.</para> | |
| 2830 | ||
| 2831 | </listitem> | |
| 2832 | </varlistentry> | |
| 2833 | </variablelist> | |
| 2834 | </refsect2> | |
| 2835 | ||
| 2836 | <refsect2 id='cpio_special_entries'><title>cpio Special Entries</title> | |
| 2837 | ||
| 2838 | <para>FIFO special files, directories, and the trailer shall be recorded | |
| 2839 | with <emphasis remap='I'>c_filesize</emphasis> equal to zero. For other special | |
| 2840 | files, <emphasis remap='I'>c_filesize</emphasis> is unspecified by this volume of IEEE Std 1003.1-2001. | |
| 2841 | The header for the next file entry in the | |
| 2842 | archive shall be written directly after the last octet of the file | |
| 2843 | entry preceding it. A header denoting the filename | |
| 2844 | <emphasis remap='B'>TRAILER!!!</emphasis> shall indicate the end of the archive; the contents | |
| 2845 | of octets in the last block of the archive following such a | |
| 2846 | header are undefined.</para> | |
| 2847 | </refsect2> | |
| 2848 | </refsect1> | |
| 2849 | ||
| 2850 | <refsect1 id='exit_status'><title>EXIT STATUS</title> | |
| 2851 | <para>The following exit values shall be returned:</para> | |
| 2852 | <variablelist remap='TP'> | |
| 2853 | <varlistentry> | |
| 2854 | <term> 0</term> | |
| 2855 | <listitem> | |
| 2856 | <para>All files were processed successfully.</para> | |
| 2857 | </listitem> | |
| 2858 | </varlistentry> | |
| 2859 | <varlistentry> | |
| 2860 | <term>>0</term> | |
| 2861 | <listitem> | |
| 2862 | <para>An error occurred.</para> | |
| 2863 | ||
| 2864 | </listitem> | |
| 2865 | </varlistentry> | |
| 2866 | </variablelist> | |
| 2867 | </refsect1> | |
| 2868 | ||
| 2869 | <refsect1 id='consequences_of_errors'><title>CONSEQUENCES OF ERRORS</title> | |
| 2870 | <para>If <command>pax</command> cannot create a file or a link when reading an archive | |
| 2871 | or cannot find a file when writing an archive, or cannot | |
| 2872 | preserve the user ID, group ID, or file mode when the <option>-p</option> option | |
| 2873 | is specified, a diagnostic message shall be written to | |
| 2874 | standard error and a non-zero exit status shall be returned, but processing | |
| 2875 | shall continue. In the case where <command>pax</command> cannot | |
| 2876 | create a link to a file, <command>pax</command> shall not, by default, create a | |
| 2877 | second copy of the file.</para> | |
| 2878 | ||
| 2879 | <para>If the extraction of a file from an archive is prematurely terminated | |
| 2880 | by a signal or error, <command>pax</command> may have only partially | |
| 2881 | extracted the file or (if the <option>-n</option> option was not specified) may | |
| 2882 | have extracted a file of the same name as that specified by | |
| 2883 | the user, but which is not the file the user wanted. Additionally, | |
| 2884 | the file modes of extracted directories may have additional bits | |
| 2885 | from the S_IRWXU mask set as well as incorrect modification and access | |
| 2886 | times.</para> | |
| 2887 | ||
| 2888 | <para><emphasis remap='I'>The following sections are informative.</emphasis></para> | |
| 2889 | </refsect1> | |
| 2890 | ||
| 2891 | <refsect1 id='application_usage'><title>APPLICATION USAGE</title> | |
| 2892 | <para>The <option>-p</option> (privileges) option was invented to reconcile differences | |
| 2893 | between historical <emphasis remap='I'>tar</emphasis> and <emphasis remap='I'>cpio</emphasis> | |
| 2894 | implementations. In particular, the two utilities use <option>-m</option> in | |
| 2895 | diametrically opposed ways. The <option>-p</option> option also provides a | |
| 2896 | consistent means of extending the ways in which future file attributes | |
| 2897 | can be addressed, such as for enhanced security systems or | |
| 2898 | high-performance files. Although it may seem complex, there are really | |
| 2899 | two modes that are most commonly used:</para> | |
| 2900 | <variablelist remap='TP'> | |
| 2901 | <varlistentry> | |
| 2902 | <term><option>-p e</option></term> | |
| 2903 | <listitem> | |
| 2904 | <para>``Preserve everything". This would be used by the historical superuser, | |
| 2905 | someone with all the appropriate privileges, to | |
| 2906 | preserve all aspects of the files as they are recorded in the archive. | |
| 2907 | The <emphasis remap='B'>e</emphasis> flag is the sum of <emphasis remap='B'>o</emphasis> and <emphasis remap='B'>p</emphasis>, and | |
| 2908 | other implementation-defined attributes.</para> | |
| 2909 | </listitem> | |
| 2910 | </varlistentry> | |
| 2911 | <varlistentry> | |
| 2912 | <term><option>-p p</option></term> | |
| 2913 | <listitem> | |
| 2914 | <para>``Preserve" the file mode bits. This would be used by the user with | |
| 2915 | regular privileges who wished to preserve aspects of the | |
| 2916 | file other than the ownership. The file times are preserved by default, | |
| 2917 | but two other flags are offered to disable these and use | |
| 2918 | the time of extraction.</para> | |
| 2919 | ||
| 2920 | ||
| 2921 | <para>The one pathname per line format of standard input precludes pathnames | |
| 2922 | containing <newline>s. Although such pathnames | |
| 2923 | violate the portable filename guidelines, they may exist and their | |
| 2924 | presence may inhibit usage of <command>pax</command> within shell scripts. | |
| 2925 | This problem is inherited from historical archive programs. The problem | |
| 2926 | can be avoided by listing filename arguments on the command | |
| 2927 | line instead of on standard input.</para> | |
| 2928 | ||
| 2929 | <para>It is almost certain that appropriate privileges are required for | |
| 2930 | <command>pax</command> to accomplish parts of this volume of | |
| 2931 | IEEE Std 1003.1-2001. Specifically, creating files of type block | |
| 2932 | special or character special, restoring file access | |
| 2933 | times unless the files are owned by the user (the <option>-t</option> option), | |
| 2934 | or preserving file owner, group, and mode (the <option>-p</option> | |
| 2935 | option) all probably require appropriate privileges.</para> | |
| 2936 | ||
| 2937 | <para>In <emphasis remap='B'>read</emphasis> mode, implementations are permitted to overwrite files | |
| 2938 | when the archive has multiple members with the same name. | |
| 2939 | This may fail if permissions on the first version of the file do not | |
| 2940 | permit it to be overwritten.</para> | |
| 2941 | ||
| 2942 | <para>The <emphasis remap='B'>cpio</emphasis> and <emphasis remap='B'>ustar</emphasis> formats can only support files up to | |
| 2943 | 8589934592 bytes (8 * 2^30) in size.</para> | |
| 2944 | </listitem> | |
| 2945 | </varlistentry> | |
| 2946 | </variablelist> | |
| 2947 | </refsect1> | |
| 2948 | ||
| 2949 | <refsect1 id='examples'><title>EXAMPLES</title> | |
| 2950 | <para>The following command:</para> | |
| 2951 | ||
| 2952 | <literallayout remap='.nf'> | |
| 2953 | ||
| 2954 | <userinput>pax -w -f /dev/rmt/1m . | |
| 2955 | </userinput> | |
| 2956 | </literallayout> <!-- .fi --> | |
| 2957 | ||
| 2958 | <para>copies the contents of the current directory to tape drive 1, medium | |
| 2959 | density (assuming historical System V device naming | |
| 2960 | procedures-the historical BSD device name would be <filename>/dev/rmt9</filename>).</para> | |
| 2961 | ||
| 2962 | <para>The following commands:</para> | |
| 2963 | ||
| 2964 | <literallayout remap='.nf'> | |
| 2965 | ||
| 2966 | <emphasis remap='B'>mkdir</emphasis> <emphasis remap='I'>newdir</emphasis><userinput>pax -rw</userinput> <emphasis remap='I'>olddir newdir</emphasis> | |
| 2967 | </literallayout> <!-- .fi --> | |
| 2968 | ||
| 2969 | <para>copy the <emphasis remap='I'>olddir</emphasis> directory hierarchy to <emphasis remap='I'>newdir</emphasis>.</para> | |
| 2970 | ||
| 2971 | <literallayout remap='.nf'> | |
| 2972 | ||
| 2973 | <userinput>pax -r -s ',^//*usr//*,,' -f a.pax | |
| 2974 | </userinput> | |
| 2975 | </literallayout> <!-- .fi --> | |
| 2976 | ||
| 2977 | <para>reads the archive <emphasis remap='B'>a.pax</emphasis>, with all files rooted in <filename>/usr</filename> | |
| 2978 | in the archive extracted relative to the current | |
| 2979 | directory.</para> | |
| 2980 | ||
| 2981 | <para>Using the option:</para> | |
| 2982 | ||
| 2983 | <literallayout remap='.nf'> | |
| 2984 | ||
| 2985 | <option>-o listopt="%M %(atime)T %(size)D %(name)s" | |
| 2986 | </option> | |
| 2987 | </literallayout> <!-- .fi --> | |
| 2988 | ||
| 2989 | <para>overrides the default output description in Standard Output and instead | |
| 2990 | writes:</para> | |
| 2991 | ||
| 2992 | <literallayout remap='.nf'> | |
| 2993 | ||
| 2994 | <option>-rw-rw--- Jan 12 15:53 1492 /usr/foo/bar | |
| 2995 | </option> | |
| 2996 | </literallayout> <!-- .fi --> | |
| 2997 | ||
| 2998 | <para>Using the options:</para> | |
| 2999 | ||
| 3000 | <literallayout remap='.nf'> | |
| 3001 | ||
| 3002 | <option>-o listopt='%L\t%(size)D\n%.7' \ | |
| 3003 | -o listopt='(name)s\n%(ctime)T\n%T' | |
| 3004 | </option> | |
| 3005 | </literallayout> <!-- .fi --> | |
| 3006 | ||
| 3007 | <para>overrides the default output description in Standard Output and instead | |
| 3008 | writes:</para> | |
| 3009 | ||
| 3010 | <literallayout remap='.nf'> | |
| 3011 | ||
| 3012 | <filename>/usr/foo/bar -> /tmp 1492 | |
| 3013 | /usr/fo | |
| 3014 | Jan 12 1991 | |
| 3015 | Jan 31 15:53 | |
| 3016 | </filename> | |
| 3017 | </literallayout> <!-- .fi --> | |
| 3018 | </refsect1> | |
| 3019 | ||
| 3020 | <refsect1 id='rationale'><title>RATIONALE</title> | |
| 3021 | <para>The <command>pax</command> utility was new for the ISO POSIX-2:1993 standard. | |
| 3022 | It represents a peaceful compromise between advocates of | |
| 3023 | the historical <emphasis remap='I'>tar</emphasis> and <emphasis remap='I'>cpio</emphasis> utilities.</para> | |
| 3024 | ||
| 3025 | <para>A fundamental difference between <emphasis remap='I'>cpio</emphasis> and <emphasis remap='I'>tar</emphasis> was in the | |
| 3026 | way directories were treated. The <emphasis remap='I'>cpio</emphasis> utility did | |
| 3027 | not treat directories differently from other files, and to select | |
| 3028 | a directory and its contents required that each file in the | |
| 3029 | hierarchy be explicitly specified. For <emphasis remap='I'>tar</emphasis>, a directory matched | |
| 3030 | every file in the file hierarchy it rooted.</para> | |
| 3031 | ||
| 3032 | <para>The <command>pax</command> utility offers both interfaces; by default, directories | |
| 3033 | map into the file hierarchy they root. The <option>-d</option> | |
| 3034 | option causes <command>pax</command> to skip any file not explicitly referenced, | |
| 3035 | as <emphasis remap='I'>cpio</emphasis> historically did. The <emphasis remap='I'>tar</emphasis> <emphasis remap='B'>-</emphasis> | |
| 3036 | <emphasis remap='I'>style</emphasis> behavior was chosen as the default because it was believed | |
| 3037 | that this was the more common usage and because <emphasis remap='I'>tar</emphasis> | |
| 3038 | is the more commonly available interface, as it was historically provided | |
| 3039 | on both System V and BSD implementations.</para> | |
| 3040 | ||
| 3041 | <para>The data interchange format specification in this volume of IEEE Std 1003.1-2001 | |
| 3042 | requires that processes with | |
| 3043 | "appropriate privileges" shall always restore the ownership and permissions | |
| 3044 | of extracted files exactly as archived. If viewed | |
| 3045 | from the historic equivalence between superuser and "appropriate privileges", | |
| 3046 | there are two problems with this requirement. | |
| 3047 | First, users running as superusers may unknowingly set dangerous permissions | |
| 3048 | on extracted files. Second, it is needlessly limiting, | |
| 3049 | in that superusers cannot extract files and own them as superuser | |
| 3050 | unless the archive was created by the superuser. (It should be | |
| 3051 | noted that restoration of ownerships and permissions for the superuser, | |
| 3052 | by default, is historical practice in <emphasis remap='I'>cpio</emphasis>, but not | |
| 3053 | in <emphasis remap='I'>tar</emphasis>.) In order to avoid these two problems, the <command>pax</command> | |
| 3054 | specification has an additional "privilege" mechanism, the | |
| 3055 | <option>-p</option> option. Only a <command>pax</command> invocation with the privileges needed, | |
| 3056 | and which has the <option>-p</option> option set using the | |
| 3057 | <emphasis remap='B'>e</emphasis> specification character, has the "appropriate privilege" to | |
| 3058 | restore full ownership and permission information.</para> | |
| 3059 | ||
| 3060 | <para>Note also that this volume of IEEE Std 1003.1-2001 requires that | |
| 3061 | the file ownership and access permissions shall be | |
| 3062 | set, on extraction, in the same fashion as the <emphasis remap='I'>creat</emphasis>() function | |
| 3063 | when provided with the | |
| 3064 | mode stored in the archive. This means that the file creation mask | |
| 3065 | of the user is applied to the file permissions.</para> | |
| 3066 | ||
| 3067 | <para>Users should note that directories may be created by <command>pax</command> while | |
| 3068 | extracting files with permissions that are different from | |
| 3069 | those that existed at the time the archive was created. When extracting | |
| 3070 | sensitive information into a directory hierarchy that no | |
| 3071 | longer exists, users are encouraged to set their file creation mask | |
| 3072 | appropriately to protect these files during extraction.</para> | |
| 3073 | ||
| 3074 | <para>The table of contents output is written to standard output to facilitate | |
| 3075 | pipeline processing.</para> | |
| 3076 | ||
| 3077 | <para>An early proposal had hard links displaying for all pathnames. This | |
| 3078 | was removed because it complicates the output of the case | |
| 3079 | where <option>-v</option> is not specified and does not match historical <emphasis remap='I'>cpio</emphasis> | |
| 3080 | usage. The hard-link information is available in the | |
| 3081 | <option>-v</option> display.</para> | |
| 3082 | ||
| 3083 | <para>The description of the <option>-l</option> option allows implementations to make | |
| 3084 | hard links to symbolic links. | |
| 3085 | IEEE Std 1003.1-2001 does not specify any way to create a hard link | |
| 3086 | to a symbolic link, but many implementations provide | |
| 3087 | this capability as an extension. If there are hard links to symbolic | |
| 3088 | links when an archive is created, the implementation is | |
| 3089 | required to archive the hard link in the archive (unless <option>-H</option> | |
| 3090 | or <option>-L</option> is specified). When in <emphasis remap='B'>read</emphasis> mode and in | |
| 3091 | <emphasis remap='B'>copy</emphasis> mode, implementations supporting hard links to symbolic | |
| 3092 | links should use them when appropriate.</para> | |
| 3093 | ||
| 3094 | <para>The archive formats inherited from the POSIX.1-1990 standard have | |
| 3095 | certain restrictions that have been brought along from | |
| 3096 | historical usage. For example, there are restrictions on the length | |
| 3097 | of pathnames stored in the archive. When <command>pax</command> is used in | |
| 3098 | <emphasis remap='B'>copy</emphasis>( <option>-rw</option>) mode (copying directory hierarchies), the ability | |
| 3099 | to use extensions from the <option>-x</option> <replaceable>pax</replaceable> format | |
| 3100 | overcomes these restrictions.</para> | |
| 3101 | ||
| 3102 | <para>The default <emphasis remap='I'>blocksize</emphasis> value of 5120 bytes for <emphasis remap='I'>cpio</emphasis> was | |
| 3103 | selected because it is one of the standard block-size | |
| 3104 | values for <emphasis remap='I'>cpio</emphasis>, set when the <option>-B</option> option is specified. | |
| 3105 | (The other default block-size value for <emphasis remap='I'>cpio</emphasis> is 512 | |
| 3106 | bytes, and this was considered to be too small.) The default block | |
| 3107 | value of 10240 bytes for <emphasis remap='I'>tar</emphasis> was selected because that is | |
| 3108 | the standard block-size value for BSD <emphasis remap='I'>tar</emphasis>. The maximum block | |
| 3109 | size of 32256 bytes (2**15-512 bytes) | |
| 3110 | is the largest multiple of 512 bytes that fits into a signed 16-bit | |
| 3111 | tape controller transfer register. There are known limitations | |
| 3112 | in some historical systems that would prevent larger blocks from being | |
| 3113 | accepted. Historical values were chosen to improve | |
| 3114 | compatibility with historical scripts using <emphasis remap='I'>dd</emphasis> or similar utilities | |
| 3115 | to manipulate | |
| 3116 | archives. Also, default block sizes for any file type other than character | |
| 3117 | special file has been deleted from this volume of | |
| 3118 | IEEE Std 1003.1-2001 as unimportant and not likely to affect the | |
| 3119 | structure of the resulting archive.</para> | |
| 3120 | ||
| 3121 | <para>Implementations are permitted to modify the block-size value based | |
| 3122 | on the archive format or the device to which the archive is | |
| 3123 | being written. This is to provide implementations with the opportunity | |
| 3124 | to take advantage of special types of devices, and it should | |
| 3125 | not be used without a great deal of consideration as it almost certainly | |
| 3126 | decreases archive portability.</para> | |
| 3127 | ||
| 3128 | <para>The intended use of the <option>-n</option> option was to permit extraction of | |
| 3129 | one or more files from the archive without processing the | |
| 3130 | entire archive. This was viewed by the standard developers as offering | |
| 3131 | significant performance advantages over historical | |
| 3132 | implementations. The <option>-n</option> option in early proposals had three | |
| 3133 | effects; the first was to cause special characters in patterns | |
| 3134 | to not be treated specially. The second was to cause only the first | |
| 3135 | file that matched a pattern to be extracted. The third was to | |
| 3136 | cause <command>pax</command> to write a diagnostic message to standard error when | |
| 3137 | no file was found matching a specified pattern. Only the | |
| 3138 | second behavior is retained by this volume of IEEE Std 1003.1-2001, | |
| 3139 | for many reasons. First, it is in general not | |
| 3140 | acceptable for a single option to have multiple effects. Second, the | |
| 3141 | ability to make pattern matching characters act as normal | |
| 3142 | characters is useful for parts of <command>pax</command> other than file extraction. | |
| 3143 | Third, a finer degree of control over the special | |
| 3144 | characters is useful because users may wish to normalize only a single | |
| 3145 | special character in a single filename. Fourth, given a more | |
| 3146 | general escape mechanism, the previous behavior of the <option>-n</option> option | |
| 3147 | can be easily obtained using the <option>-s</option> option or a <emphasis remap='I'>sed</emphasis> script. | |
| 3148 | Finally, writing a diagnostic message when a pattern specified by | |
| 3149 | the user is | |
| 3150 | unmatched by any file is useful behavior in all cases.</para> | |
| 3151 | ||
| 3152 | <para>In this version, the <option>-n</option> was removed from the <emphasis remap='B'>copy</emphasis> mode | |
| 3153 | synopsis of <command>pax</command>; it is inapplicable because there | |
| 3154 | are no pattern operands specified in this mode.</para> | |
| 3155 | ||
| 3156 | <para>There is another method than <command>pax</command> for copying subtrees in IEEE Std 1003.1-2001 | |
| 3157 | described as part of the <emphasis remap='I'>cp</emphasis> utility. Both methods are historical | |
| 3158 | practice: <emphasis remap='I'>cp</emphasis> | |
| 3159 | provides a simpler, more intuitive interface, while <command>pax</command> offers | |
| 3160 | a finer granularity of control. Each provides additional | |
| 3161 | functionality to the other; in particular, <command>pax</command> maintains the | |
| 3162 | hard-link structure of the hierarchy while <emphasis remap='I'>cp</emphasis> does not. It is | |
| 3163 | the intention of the standard developers that the results be similar | |
| 3164 | (using | |
| 3165 | appropriate option combinations in both utilities). The results are | |
| 3166 | not required to be identical; there seemed insufficient gain to | |
| 3167 | applications to balance the difficulty of implementations having to | |
| 3168 | guarantee that the results would be exactly identical.</para> | |
| 3169 | ||
| 3170 | <para>A single archive may span more than one file. It is suggested that | |
| 3171 | implementations provide informative messages to the user on | |
| 3172 | standard error whenever the archive file is changed.</para> | |
| 3173 | ||
| 3174 | <para>The <option>-d</option> option (do not create intermediate directories not listed | |
| 3175 | in the archive) found in early proposals was originally | |
| 3176 | provided as a complement to the historic <option>-d</option> option of <emphasis remap='I'>cpio</emphasis>. | |
| 3177 | It has been deleted.</para> | |
| 3178 | ||
| 3179 | <para>The <option>-s</option> option in early proposals specified a subset of the substitution | |
| 3180 | command from the <emphasis remap='I'>ed</emphasis> utility. As there was no reason for only | |
| 3181 | a subset to be supported, the <option>-s</option> option is now | |
| 3182 | compatible with the current <emphasis remap='I'>ed</emphasis> specification. Since the delimiter | |
| 3183 | can be any non-null | |
| 3184 | character, the following usage with single spaces is valid:</para> | |
| 3185 | ||
| 3186 | <literallayout remap='.nf'> | |
| 3187 | ||
| 3188 | <userinput>pax -s " foo bar " ... | |
| 3189 | </userinput> | |
| 3190 | </literallayout> <!-- .fi --> | |
| 3191 | ||
| 3192 | <para>The <option>-t</option> description is worded so as to note that this may cause | |
| 3193 | the access time update caused by some other activity | |
| 3194 | (which occurs while the file is being read) to be overwritten.</para> | |
| 3195 | ||
| 3196 | <para>The default behavior of <command>pax</command> with regard to file modification | |
| 3197 | times is the same as historical implementations of | |
| 3198 | <emphasis remap='I'>tar</emphasis>. It is not the historical behavior of <emphasis remap='I'>cpio</emphasis>.</para> | |
| 3199 | ||
| 3200 | <para>Because the <option>-i</option> option uses <filename>/dev/tty</filename>, utilities without | |
| 3201 | a controlling terminal are not able to use this option.</para> | |
| 3202 | ||
| 3203 | <para>The <option>-y</option> option, found in early proposals, has been deleted because | |
| 3204 | a line containing a single period for the <option>-i</option> | |
| 3205 | option has equivalent functionality. The special lines for the <option>-i</option> | |
| 3206 | option (a single period and the empty line) are historical | |
| 3207 | practice in <emphasis remap='I'>cpio</emphasis>.</para> | |
| 3208 | ||
| 3209 | <para>In early drafts, a <option>-e</option> <replaceable>charmap</replaceable> option was included to increase | |
| 3210 | portability of files between systems using different | |
| 3211 | coded character sets. This option was omitted because it was apparent | |
| 3212 | that consensus could not be formed for it. In this version, | |
| 3213 | the use of UTF-8 should be an adequate substitute.</para> | |
| 3214 | ||
| 3215 | <para>The <option>-k</option> option was added to address international concerns about | |
| 3216 | the dangers involved in the character set transformations | |
| 3217 | of <option>-e</option> (if the target character set were different from the source, | |
| 3218 | the filenames might be transformed into names matching | |
| 3219 | existing files) and also was made more general to protect files transferred | |
| 3220 | between file systems with different {NAME_MAX} values | |
| 3221 | (truncating a filename on a smaller system might also inadvertently | |
| 3222 | overwrite existing files). As stated, it prevents any | |
| 3223 | overwriting, even if the target file is older than the source. This | |
| 3224 | version adds more granularity of options to solve this problem | |
| 3225 | by introducing the <option>-o</option> <replaceable>invalid=</replaceable> option-specifically the | |
| 3226 | UTF-8 action. (Note that an existing file that is named with a | |
| 3227 | UTF-8 encoding is still subject to overwriting in this case. The <option>-k</option> | |
| 3228 | option closes that loophole.)</para> | |
| 3229 | ||
| 3230 | <para>Some of the file characteristics referenced in this volume of IEEE Std 1003.1-2001 | |
| 3231 | might not be supported by some | |
| 3232 | archive formats. For example, neither the <emphasis remap='B'>tar</emphasis> nor <emphasis remap='B'>cpio</emphasis> | |
| 3233 | formats contain the file access time. For this reason, the | |
| 3234 | <emphasis remap='B'>e</emphasis> specification character has been provided, intended to cause | |
| 3235 | all file characteristics specified in the archive to be | |
| 3236 | retained.</para> | |
| 3237 | ||
| 3238 | <para>It is required that extracted directories, by default, have their | |
| 3239 | access and modification times and permissions set to the | |
| 3240 | values specified in the archive. This has obvious problems in that | |
| 3241 | the directories are almost certainly modified after being | |
| 3242 | extracted and that directory permissions may not permit file creation. | |
| 3243 | One possible solution is to create directories with the mode | |
| 3244 | specified in the archive, as modified by the <emphasis remap='I'>umask</emphasis> of the user, | |
| 3245 | with sufficient | |
| 3246 | permissions to allow file creation. After all files have been extracted, | |
| 3247 | <command>pax</command> would then reset the access and modification | |
| 3248 | times and permissions as necessary.</para> | |
| 3249 | ||
| 3250 | <para>The list-mode formatting description borrows heavily from the one | |
| 3251 | defined by the <emphasis remap='I'>printf</emphasis> utility. However, since there is no separate | |
| 3252 | operand list to get conversion arguments, | |
| 3253 | the format was extended to allow specifying the name of the conversion | |
| 3254 | argument as part of the conversion specification.</para> | |
| 3255 | ||
| 3256 | <para>The <emphasis remap='B'>T</emphasis> conversion specifier allows time fields to be displayed | |
| 3257 | in any of the date formats. Unlike the <emphasis remap='I'>ls</emphasis> utility, <command>pax</command> | |
| 3258 | does not adjust the format when the date is less than six months in | |
| 3259 | the | |
| 3260 | past. This makes parsing the output more predictable.</para> | |
| 3261 | ||
| 3262 | <para>The <emphasis remap='B'>D</emphasis> conversion specifier handles the ability to display the | |
| 3263 | major/minor or file size, as with <emphasis remap='I'>ls</emphasis>, by using <emphasis remap='B'>%-8(</emphasis><emphasis remap='I'>size</emphasis><emphasis remap='B'>)D</emphasis>.</para> | |
| 3264 | ||
| 3265 | <para>The <emphasis remap='B'>L</emphasis> conversion specifier handles the <emphasis remap='I'>ls</emphasis> display for | |
| 3266 | symbolic links.</para> | |
| 3267 | ||
| 3268 | <para>Conversion specifiers were added to generate existing known types | |
| 3269 | used for <emphasis remap='I'>ls</emphasis>.</para> | |
| 3270 | ||
| 3271 | <refsect2 id='pax_interchange_format2'><title>pax Interchange Format</title> | |
| 3272 | ||
| 3273 | <para>The new POSIX data interchange format was developed primarily to satisfy | |
| 3274 | international concerns that the <emphasis remap='B'>ustar</emphasis> and | |
| 3275 | <emphasis remap='B'>cpio</emphasis> formats did not provide for file, user, and group names | |
| 3276 | encoded in characters outside a subset of the | |
| 3277 | ISO/IEC 646:1991 standard. The standard developers realized that | |
| 3278 | this new POSIX data interchange format should be very | |
| 3279 | extensible because there were other requirements they foresaw in the | |
| 3280 | near future:</para> | |
| 3281 | <variablelist remap='IP'> | |
| 3282 | <varlistentry> | |
| 3283 | <term> *</term> | |
| 3284 | <listitem> | |
| 3285 | <para>Support international character encodings and locale information</para> | |
| 3286 | ||
| 3287 | </listitem> | |
| 3288 | </varlistentry> | |
| 3289 | <varlistentry> | |
| 3290 | <term> *</term> | |
| 3291 | <listitem> | |
| 3292 | <para>Support security information (ACLs, and so on)</para> | |
| 3293 | ||
| 3294 | </listitem> | |
| 3295 | </varlistentry> | |
| 3296 | <varlistentry> | |
| 3297 | <term> *</term> | |
| 3298 | <listitem> | |
| 3299 | <para>Support future file types, such as realtime or contiguous files</para> | |
| 3300 | ||
| 3301 | </listitem> | |
| 3302 | </varlistentry> | |
| 3303 | <varlistentry> | |
| 3304 | <term> *</term> | |
| 3305 | <listitem> | |
| 3306 | <para>Include data areas for implementation use</para> | |
| 3307 | ||
| 3308 | </listitem> | |
| 3309 | </varlistentry> | |
| 3310 | <varlistentry> | |
| 3311 | <term> *</term> | |
| 3312 | <listitem> | |
| 3313 | <para>Support systems with words larger than 32 bits and timers with subsecond | |
| 3314 | granularity</para> | |
| 3315 | ||
| 3316 | ||
| 3317 | <para>The following were not goals for this format because these are better | |
| 3318 | handled by separate utilities or are inappropriate for a | |
| 3319 | portable format:</para> | |
| 3320 | </listitem> | |
| 3321 | </varlistentry> | |
| 3322 | <varlistentry> | |
| 3323 | <term> *</term> | |
| 3324 | <listitem> | |
| 3325 | <para>Encryption</para> | |
| 3326 | ||
| 3327 | </listitem> | |
| 3328 | </varlistentry> | |
| 3329 | <varlistentry> | |
| 3330 | <term> *</term> | |
| 3331 | <listitem> | |
| 3332 | <para>Compression</para> | |
| 3333 | ||
| 3334 | </listitem> | |
| 3335 | </varlistentry> | |
| 3336 | <varlistentry> | |
| 3337 | <term> *</term> | |
| 3338 | <listitem> | |
| 3339 | <para>Data translation between locales and codesets</para> | |
| 3340 | ||
| 3341 | </listitem> | |
| 3342 | </varlistentry> | |
| 3343 | <varlistentry> | |
| 3344 | <term> *</term> | |
| 3345 | <listitem> | |
| 3346 | <para><emphasis remap='I'>inode</emphasis> storage</para> | |
| 3347 | ||
| 3348 | ||
| 3349 | <para>The format chosen to support the goals is an extension of the <emphasis remap='B'>ustar</emphasis> | |
| 3350 | format. Of the two formats previously available, only | |
| 3351 | the <emphasis remap='B'>ustar</emphasis> format was selected for extensions because:</para> | |
| 3352 | </listitem> | |
| 3353 | </varlistentry> | |
| 3354 | <varlistentry> | |
| 3355 | <term> *</term> | |
| 3356 | <listitem> | |
| 3357 | <para>It was easier to extend in an upwards-compatible way. It offered version | |
| 3358 | flags and header block type fields with room for future | |
| 3359 | standardization. The <emphasis remap='B'>cpio</emphasis> format, while possessing a more flexible | |
| 3360 | file naming methodology, could not be extended without | |
| 3361 | breaking some theoretical implementation or using a dummy filename | |
| 3362 | that could be a legitimate filename.</para> | |
| 3363 | ||
| 3364 | </listitem> | |
| 3365 | </varlistentry> | |
| 3366 | <varlistentry> | |
| 3367 | <term> *</term> | |
| 3368 | <listitem> | |
| 3369 | <para>Industry experience since the original " <emphasis remap='I'>tar</emphasis> wars" fought in | |
| 3370 | developing the ISO POSIX-1 standard has clearly been | |
| 3371 | in favor of the <emphasis remap='B'>ustar</emphasis> format, which is generally the default | |
| 3372 | output format selected for <command>pax</command> implementations on new | |
| 3373 | systems.</para> | |
| 3374 | ||
| 3375 | ||
| 3376 | <para>The new format was designed with one additional goal in mind: reasonable | |
| 3377 | behavior when an older <emphasis remap='I'>tar</emphasis> or <command>pax</command> utility | |
| 3378 | happened to read an archive. Since the POSIX.1-1990 standard mandated | |
| 3379 | that a "format-reading utility" had to treat unrecognized | |
| 3380 | <emphasis remap='I'>typeflag</emphasis> values as regular files, this allowed the format to | |
| 3381 | include all the extended information in a pseudo-regular file | |
| 3382 | that preceded each real file. An option is given that allows the archive | |
| 3383 | creator to set up reasonable names for these files on the | |
| 3384 | older systems. Also, the normative text suggests that reasonable file | |
| 3385 | access values be used for this <emphasis remap='B'>ustar</emphasis> header block. | |
| 3386 | Making these header files inaccessible for convenient reading and | |
| 3387 | deleting would not be reasonable. File permissions of 600 or 700 | |
| 3388 | are suggested.</para> | |
| 3389 | ||
| 3390 | <para>The <emphasis remap='B'>ustar</emphasis> <emphasis remap='I'>typeflag</emphasis> field was used to accommodate the additional | |
| 3391 | functionality of the new format rather than magic | |
| 3392 | or version because the POSIX.1-1990 standard (and, by reference, the | |
| 3393 | previous version of <command>pax</command>), mandated the behavior of the | |
| 3394 | format-reading utility when it encountered an unknown <emphasis remap='I'>typeflag</emphasis>, | |
| 3395 | but was silent about the other two fields.</para> | |
| 3396 | ||
| 3397 | <para>Early proposals of the first revision to IEEE Std 1003.1-2001 contained | |
| 3398 | a proposed archive format that was based on | |
| 3399 | compatibility with the standard for tape files (ISO 1001, similar | |
| 3400 | to the format used historically on many mainframes and | |
| 3401 | minicomputers). This format was overly complex and required considerable | |
| 3402 | overhead in volume and header records. Furthermore, the | |
| 3403 | standard developers felt that it would not be acceptable to the community | |
| 3404 | of POSIX developers, so it was later changed to be a | |
| 3405 | format more closely related to historical practice on POSIX systems.</para> | |
| 3406 | ||
| 3407 | <para>The prefix and name split of pathnames in <emphasis remap='B'>ustar</emphasis> was replaced | |
| 3408 | by the single path extended header record for | |
| 3409 | simplicity.</para> | |
| 3410 | ||
| 3411 | <para>The concept of a global extended header ( <emphasis remap='I'>typeflag</emphasis> <emphasis remap='B'>g</emphasis>) | |
| 3412 | was controversial. If this were applied to an archive being | |
| 3413 | recorded on magnetic tape, a few unreadable blocks at the beginning | |
| 3414 | of the tape could be a serious problem; a utility attempting to | |
| 3415 | extract as many files as possible from a damaged archive could lose | |
| 3416 | a large percentage of file header information in this case. | |
| 3417 | However, if the archive were on a reliable medium, such as a CD-ROM, | |
| 3418 | the global extended header offers considerable potential size | |
| 3419 | reductions by eliminating redundant information. Thus, the text warns | |
| 3420 | against using the global method for unreliable media and | |
| 3421 | provides a method for implanting global information in the extended | |
| 3422 | header for each file, rather than in the <emphasis remap='I'>typeflag</emphasis> | |
| 3423 | <emphasis remap='B'>g</emphasis> records.</para> | |
| 3424 | ||
| 3425 | <para>No facility for data translation or filtering on a per-file basis | |
| 3426 | is included because the standard developers could not invent | |
| 3427 | an interface that would allow this in an efficient manner. If a filter, | |
| 3428 | such as encryption or compression, is to be applied to all | |
| 3429 | the files, it is more efficient to apply the filter to the entire | |
| 3430 | archive as a single file. The standard developers considered | |
| 3431 | interfaces that would invoke a shell script for each file going into | |
| 3432 | or out of the archive, but the system overhead in this | |
| 3433 | approach was considered to be too high.</para> | |
| 3434 | ||
| 3435 | <para>One such approach would be to have <emphasis remap='B'>filter=</emphasis> records that give | |
| 3436 | a pathname for an executable. When the program is invoked, | |
| 3437 | the file and archive would be open for standard input/output and all | |
| 3438 | the header fields would be available as environment variables | |
| 3439 | or command-line arguments. The standard developers did discuss such | |
| 3440 | schemes, but they were omitted from | |
| 3441 | IEEE Std 1003.1-2001 due to concerns about excessive overhead. Also, | |
| 3442 | the program itself would need to be in the archive | |
| 3443 | if it were to be used portably.</para> | |
| 3444 | ||
| 3445 | <para>There is currently no portable means of identifying the character | |
| 3446 | set(s) used for a file in the file system. Therefore, | |
| 3447 | <command>pax</command> has not been given a mechanism to generate charset records | |
| 3448 | automatically. The only portable means of doing this is for | |
| 3449 | the user to write the archive using the <option>-o</option> <replaceable>charset=</replaceable> <emphasis remap='I'>string</emphasis> | |
| 3450 | command line option. This assumes that all of the | |
| 3451 | files in the archive use the same encoding. The "implementation-defined" | |
| 3452 | text is included to allow for a system that can identify | |
| 3453 | the encodings used for each of its files.</para> | |
| 3454 | ||
| 3455 | <para>The table of standards that accompanies the charset record description | |
| 3456 | is acknowledged to be very limited. Only a limited number | |
| 3457 | of character set standards is reasonable for maximal interchange. | |
| 3458 | Any character set is, of course, possible by prior agreement. It | |
| 3459 | was suggested that EBCDIC be listed, but it was omitted because it | |
| 3460 | is not defined by a formal standard. Formal standards, and then | |
| 3461 | only those with reasonably large followings, can be included here, | |
| 3462 | simply as a matter of practicality. The <<emphasis remap='I'>value</emphasis>>s | |
| 3463 | represent names of officially registered character sets in the format | |
| 3464 | required by the ISO 2375:1985 standard.</para> | |
| 3465 | ||
| 3466 | <para>The normal comma or <blank>-separated list rules are not followed | |
| 3467 | in the case of keyword options to allow ease of argument | |
| 3468 | parsing for <emphasis remap='I'>getopts</emphasis>.</para> | |
| 3469 | ||
| 3470 | <para>Further information on character encodings is in pax Archive Character | |
| 3471 | Set Encoding/Decoding | |
| 3472 | .</para> | |
| 3473 | ||
| 3474 | <para>The standard developers have reserved keyword name space for vendor | |
| 3475 | extensions. It is suggested that the format to be used | |
| 3476 | is:</para> | |
| 3477 | ||
| 3478 | <literallayout remap='.nf'> | |
| 3479 | ||
| 3480 | <emphasis remap='I'>VENDOR.keyword</emphasis> | |
| 3481 | </literallayout> <!-- .fi --> | |
| 3482 | ||
| 3483 | <para>where <emphasis remap='I'>VENDOR</emphasis> is the name of the vendor or organization in all | |
| 3484 | uppercase letters. It is further suggested that the keyword | |
| 3485 | following the period be named differently than any of the standard | |
| 3486 | keywords so that it could be used for future standardization, if | |
| 3487 | appropriate, by omitting the <emphasis remap='I'>VENDOR</emphasis> prefix.</para> | |
| 3488 | ||
| 3489 | <para>The <<emphasis remap='I'>length</emphasis>> field in the extended header record was included | |
| 3490 | to make it simpler to step through the records, even | |
| 3491 | if a record contains an unknown format (to a particular <command>pax</command>) | |
| 3492 | with complex interactions of special characters. It also | |
| 3493 | provides a minor integrity checkpoint within the records to aid a | |
| 3494 | program attempting to recover files from a damaged archive.</para> | |
| 3495 | ||
| 3496 | <para>There are no extended header versions of the <emphasis remap='I'>devmajor</emphasis> and <emphasis remap='I'>devminor</emphasis> | |
| 3497 | fields because the unspecified format | |
| 3498 | <emphasis remap='B'>ustar</emphasis> header field should be sufficient. If they are not, vendor-specific | |
| 3499 | extended keywords (such as <emphasis remap='I'>VENDOR.devmajor</emphasis>) | |
| 3500 | should be used.</para> | |
| 3501 | ||
| 3502 | <para>Device and <emphasis remap='I'>i</emphasis>-number labeling of files was not adopted from <emphasis remap='I'>cpio</emphasis>; | |
| 3503 | files are interchanged strictly on a symbolic | |
| 3504 | name basis, as in <emphasis remap='B'>ustar</emphasis>.</para> | |
| 3505 | ||
| 3506 | <para>Just as with the <emphasis remap='B'>ustar</emphasis> format descriptions, the new format makes | |
| 3507 | no special arrangements for multi-volume archives. Each | |
| 3508 | of the <command>pax</command> archive types is assumed to be inside a single POSIX | |
| 3509 | file and splitting that file over multiple volumes | |
| 3510 | (diskettes, tape cartridges, and so on), processing their labels, | |
| 3511 | and mounting each in the proper sequence are considered to be | |
| 3512 | implementation details that cannot be described portably.</para> | |
| 3513 | ||
| 3514 | <para>The <command>pax</command> format is intended for interchange, not only for backup | |
| 3515 | on a single (family of) systems. It is not as densely | |
| 3516 | packed as might be possible for backup:</para> | |
| 3517 | </listitem> | |
| 3518 | </varlistentry> | |
| 3519 | <varlistentry> | |
| 3520 | <term> *</term> | |
| 3521 | <listitem> | |
| 3522 | <para>It contains information as coded characters that could be coded in | |
| 3523 | binary.</para> | |
| 3524 | ||
| 3525 | </listitem> | |
| 3526 | </varlistentry> | |
| 3527 | <varlistentry> | |
| 3528 | <term> *</term> | |
| 3529 | <listitem> | |
| 3530 | <para>It identifies extended records with name fields that could be omitted | |
| 3531 | in favor of a fixed-field layout.</para> | |
| 3532 | ||
| 3533 | </listitem> | |
| 3534 | </varlistentry> | |
| 3535 | <varlistentry> | |
| 3536 | <term> *</term> | |
| 3537 | <listitem> | |
| 3538 | <para>It translates names into a portable character set and identifies locale-related | |
| 3539 | information, both of which are probably | |
| 3540 | unnecessary for backup.</para> | |
| 3541 | ||
| 3542 | ||
| 3543 | <para>The requirements on restoring from an archive are slightly different | |
| 3544 | from the historical wording, allowing for non-monolithic | |
| 3545 | privilege to bring forward as much as possible. In particular, attributes | |
| 3546 | such as "high performance file" might be broadly but | |
| 3547 | not universally granted while set-user-ID or <emphasis remap='I'>chown</emphasis>() might be | |
| 3548 | much more restricted. | |
| 3549 | There is no implication in IEEE Std 1003.1-2001 that the security | |
| 3550 | information be honored after it is restored to the file | |
| 3551 | hierarchy, in spite of what might be improperly inferred by the silence | |
| 3552 | on that topic. That is a topic for another standard.</para> | |
| 3553 | ||
| 3554 | <para>Links are recorded in the fashion described here because a link can | |
| 3555 | be to any file type. It is desirable in general to be able | |
| 3556 | to restore part of an archive selectively and restore all of those | |
| 3557 | files completely. If the data is not associated with each link, | |
| 3558 | it is not possible to do this. However, the data associated with a | |
| 3559 | file can be large, and when selective restoration is not needed, | |
| 3560 | this can be a significant burden. The archive is structured so that | |
| 3561 | files that have no associated data can always be restored by | |
| 3562 | the name of any link name of any link, and the user may choose whether | |
| 3563 | data is recorded with each instance of a file that contains | |
| 3564 | data. The format permits mixing of both types of links in a single | |
| 3565 | archive; this can be done for special needs, and <command>pax</command> is | |
| 3566 | expected to interpret such archives on input properly, despite the | |
| 3567 | fact that there is no <command>pax</command> option that would force this | |
| 3568 | mixed case on output. (When <option>-o</option> <replaceable>linkdata</replaceable> is used, the output | |
| 3569 | must contain the duplicate data, but the implementation | |
| 3570 | is free to include it or omit it when <option>-o</option> <replaceable>linkdata</replaceable> is not | |
| 3571 | used.)</para> | |
| 3572 | ||
| 3573 | <para>The time values are included as extended header records for those | |
| 3574 | implementations needing more than the eleven octal digits | |
| 3575 | allowed by the <emphasis remap='B'>ustar</emphasis> format. Portable file timestamps cannot | |
| 3576 | be negative. If <command>pax</command> encounters a file with a negative | |
| 3577 | timestamp in <emphasis remap='B'>copy</emphasis> or <emphasis remap='B'>write</emphasis> mode, it can reject the file, | |
| 3578 | substitute a non-negative timestamp, or generate a | |
| 3579 | non-portable timestamp with a leading <emphasis remap='B'>'-'</emphasis> . Even though some | |
| 3580 | implementations can support finer file-time granularities | |
| 3581 | than seconds, the normative text requires support only for seconds | |
| 3582 | since the Epoch because the ISO POSIX-1 standard states | |
| 3583 | them that way. The <emphasis remap='B'>ustar</emphasis> format includes only <emphasis remap='I'>mtime</emphasis>; the | |
| 3584 | new format adds <emphasis remap='I'>atime</emphasis> and <emphasis remap='I'>ctime</emphasis> for symmetry. | |
| 3585 | The <emphasis remap='I'>atime</emphasis> access time restored to the file system will be affected | |
| 3586 | by the <option>-p</option> <replaceable>a</replaceable> and <option>-p</option> <replaceable>e</replaceable> options. | |
| 3587 | The <emphasis remap='I'>ctime</emphasis> creation time (actually <emphasis remap='I'>inode</emphasis> modification time) | |
| 3588 | is described with "appropriate privilege" so that it can | |
| 3589 | be ignored when writing to the file system. POSIX does not provide | |
| 3590 | a portable means to change file creation time. Nothing is | |
| 3591 | intended to prevent a non-portable implementation of <command>pax</command> from | |
| 3592 | restoring the value.</para> | |
| 3593 | ||
| 3594 | <para>The <emphasis remap='I'>gid</emphasis>, <emphasis remap='I'>size</emphasis>, and <emphasis remap='I'>uid</emphasis> extended header records were | |
| 3595 | included to allow expansion beyond the sizes specified | |
| 3596 | in the regular <emphasis remap='I'>tar</emphasis> header. New file system architectures are | |
| 3597 | emerging that will exhaust the 12-digit size field. There are | |
| 3598 | probably not many systems requiring more than 8 digits for user and | |
| 3599 | group IDs, but the extended header values were included for | |
| 3600 | completeness, allowing overrides for all of the decimal values in | |
| 3601 | the <emphasis remap='I'>tar</emphasis> header.</para> | |
| 3602 | ||
| 3603 | <para>The standard developers intended to describe the effective results | |
| 3604 | of <command>pax</command> with regard to file ownerships and permissions; | |
| 3605 | implementations are not restricted in timing or sequencing the restoration | |
| 3606 | of such, provided the results are as specified.</para> | |
| 3607 | ||
| 3608 | <para>Much of the text describing the extended headers refers to use in | |
| 3609 | " <emphasis remap='B'>write</emphasis> or <emphasis remap='B'>copy</emphasis> modes". The <emphasis remap='B'>copy</emphasis> mode | |
| 3610 | references are due to the normative text: "The effect of the copy | |
| 3611 | shall be as if the copied files were written to an archive file | |
| 3612 | and then subsequently extracted ...". There is certainly no way to | |
| 3613 | test whether <command>pax</command> is actually generating the extended | |
| 3614 | headers in <emphasis remap='B'>copy</emphasis> mode, but the effects must be as if it had.</para> | |
| 3615 | </listitem> | |
| 3616 | </varlistentry> | |
| 3617 | </variablelist> | |
| 3618 | </refsect2> | |
| 3619 | ||
| 3620 | <refsect2 id='pax_archive_character_set_encodingdecodi'><title>pax Archive Character Set Encoding/Decoding</title> | |
| 3621 | ||
| 3622 | <para>There is a need to exchange archives of files between systems of different | |
| 3623 | native codesets. Filenames, group names, and user | |
| 3624 | names must be preserved to the fullest extent possible when an archive | |
| 3625 | is read on the receiving platform. Translation of the | |
| 3626 | contents of files is not within the scope of the <command>pax</command> utility.</para> | |
| 3627 | ||
| 3628 | <para>There will also be the need to represent characters that are not available | |
| 3629 | on the receiving platform. These unsupported | |
| 3630 | characters cannot be automatically folded to the local set of characters | |
| 3631 | due to the chance of collisions. This could result in | |
| 3632 | overwriting previous extracted files from the archive or pre-existing | |
| 3633 | files on the system.</para> | |
| 3634 | ||
| 3635 | <para>For these reasons, the codeset used to represent characters within | |
| 3636 | the extended header records of the <command>pax</command> archive must be | |
| 3637 | sufficiently rich to handle all commonly used character sets. The | |
| 3638 | fields requiring translation include, at a minimum, filenames, | |
| 3639 | user names, group names, and link pathnames. Implementations may wish | |
| 3640 | to have localized extended keywords that use non-portable | |
| 3641 | characters.</para> | |
| 3642 | ||
| 3643 | <para>The standard developers considered the following options:</para> | |
| 3644 | <variablelist remap='IP'> | |
| 3645 | <varlistentry> | |
| 3646 | <term> *</term> | |
| 3647 | <listitem> | |
| 3648 | <para>The archive creator specifies the well-defined name of the source | |
| 3649 | codeset. The receiver must then recognize the codeset name and | |
| 3650 | perform the appropriate translations to the destination codeset.</para> | |
| 3651 | ||
| 3652 | </listitem> | |
| 3653 | </varlistentry> | |
| 3654 | <varlistentry> | |
| 3655 | <term> *</term> | |
| 3656 | <listitem> | |
| 3657 | <para>The archive creator includes within the archive the character mapping | |
| 3658 | table for the source codeset used to encode extended | |
| 3659 | header records. The receiver must then read the character mapping | |
| 3660 | table and perform the appropriate translations to the destination | |
| 3661 | codeset.</para> | |
| 3662 | ||
| 3663 | </listitem> | |
| 3664 | </varlistentry> | |
| 3665 | <varlistentry> | |
| 3666 | <term> *</term> | |
| 3667 | <listitem> | |
| 3668 | <para>The archive creator translates the extended header records in the | |
| 3669 | source codeset into a canonical form. The receiver must then | |
| 3670 | perform the appropriate translations to the destination codeset.</para> | |
| 3671 | ||
| 3672 | ||
| 3673 | <para>The approach that incorporates the name of the source codeset poses | |
| 3674 | the problem of codeset name registration, and makes the | |
| 3675 | archive useless to <command>pax</command> archive decoders that do not recognize | |
| 3676 | that codeset.</para> | |
| 3677 | ||
| 3678 | <para>Because parts of an archive may be corrupted, the standard developers | |
| 3679 | felt that including the character map of the source | |
| 3680 | codeset was too fragile. The loss of this one key component could | |
| 3681 | result in making the entire archive useless. (The difference | |
| 3682 | between this and the global extended header decision was that the | |
| 3683 | latter has a workaround-duplicating extended header records on | |
| 3684 | unreliable media-but this would be too burdensome for large character | |
| 3685 | set maps.)</para> | |
| 3686 | ||
| 3687 | <para>Both of the above approaches also put an undue burden on the <command>pax</command> | |
| 3688 | archive receiver to handle the cross-product of all | |
| 3689 | source and destination codesets.</para> | |
| 3690 | ||
| 3691 | <para>To simplify the translation from the source codeset to the canonical | |
| 3692 | form and from the canonical form to the destination | |
| 3693 | codeset, the standard developers decided that the internal representation | |
| 3694 | should be a stateless encoding. A stateless encoding is | |
| 3695 | one where each codepoint has the same meaning, without regard to the | |
| 3696 | decoder being in a specific state. An example of a stateful | |
| 3697 | encoding would be the Japanese Shift-JIS; an example of a stateless | |
| 3698 | encoding would be the ISO/IEC 646:1991 standard | |
| 3699 | (equivalent to 7-bit ASCII).</para> | |
| 3700 | ||
| 3701 | <para>For these reasons, the standard developers decided to adopt a canonical | |
| 3702 | format for the representation of file information | |
| 3703 | strings. The obvious, well-endorsed candidate is the ISO/IEC 10646-1:2000 | |
| 3704 | standard (based in part on Unicode), which can be | |
| 3705 | used to represent the characters of virtually all standardized character | |
| 3706 | sets. The standard developers initially agreed upon using | |
| 3707 | UCS2 (16-bit Unicode) as the internal representation. This repertoire | |
| 3708 | of characters provides a sufficiently rich set to represent | |
| 3709 | all commonly-used codesets.</para> | |
| 3710 | ||
| 3711 | <para>However, the standard developers found that the 16-bit Unicode representation | |
| 3712 | had some problems. It forced the issue of | |
| 3713 | standardizing byte ordering. The 2-byte length of each character made | |
| 3714 | the extended header records twice as long for the case of | |
| 3715 | strings coded entirely from historical 7-bit ASCII. For these reasons, | |
| 3716 | the standard developers chose the UTF-8 defined in the | |
| 3717 | ISO/IEC 10646-1:2000 standard. This multi-byte representation encodes | |
| 3718 | UCS2 or UCS4 characters reliably and deterministically, | |
| 3719 | eliminating the need for a canonical byte ordering. In addition, NUL | |
| 3720 | octets and other characters possibly confusing to POSIX file | |
| 3721 | systems do not appear, except to represent themselves. It was realized | |
| 3722 | that certain national codesets take up more space after the | |
| 3723 | encoding, due to their placement within the UCS range; it was felt | |
| 3724 | that the usefulness of the encoding of the names outweighs the | |
| 3725 | disadvantage of size increase for file, user, and group names.</para> | |
| 3726 | ||
| 3727 | <para>The encoding of UTF-8 is as follows:</para> | |
| 3728 | ||
| 3729 | <literallayout remap='.nf'> | |
| 3730 | ||
| 3731 | <emphasis remap='B'>UCS4 Hex Encoding UTF-8 Binary Encoding | |
| 3732 | ||
| 3733 | ||
| 3734 | 00000000-0000007F 0xxxxxxx | |
| 3735 | 00000080-000007FF 110xxxxx 10xxxxxx | |
| 3736 | 00000800-0000FFFF 1110xxxx 10xxxxxx 10xxxxxx | |
| 3737 | 00010000-001FFFFF 11110xxx 10xxxxxx 10xxxxxx 10xxxxxx | |
| 3738 | 00200000-03FFFFFF 111110xx 10xxxxxx 10xxxxxx 10xxxxxx 10xxxxxx | |
| 3739 | 04000000-7FFFFFFF 1111110x 10xxxxxx 10xxxxxx 10xxxxxx 10xxxxxx 10xxxxxx | |
| 3740 | </emphasis> | |
| 3741 | </literallayout> <!-- .fi --> | |
| 3742 | ||
| 3743 | <para>where each <emphasis remap='B'>'x'</emphasis> represents a bit value from the character being | |
| 3744 | translated.</para> | |
| 3745 | </listitem> | |
| 3746 | </varlistentry> | |
| 3747 | </variablelist> | |
| 3748 | </refsect2> | |
| 3749 | ||
| 3750 | <refsect2 id='ustar_interchange_format2'><title>ustar Interchange Format</title> | |
| 3751 | ||
| 3752 | <para>The description of the <emphasis remap='B'>ustar</emphasis> format reflects numerous enhancements | |
| 3753 | over pre-1988 versions of the historical <emphasis remap='I'>tar</emphasis> | |
| 3754 | utility. The goal of these changes was not only to provide the functional | |
| 3755 | enhancements desired, but also to retain compatibility | |
| 3756 | between new and old versions. This compatibility has been retained. | |
| 3757 | Archives written using the old archive format are compatible | |
| 3758 | with the new format.</para> | |
| 3759 | ||
| 3760 | <para>Implementors should be aware that the previous file format did not | |
| 3761 | include a mechanism to archive directory type files. For this | |
| 3762 | reason, the convention of using a filename ending with slash was adopted | |
| 3763 | to specify a directory on the archive.</para> | |
| 3764 | ||
| 3765 | <para>The total size of the <emphasis remap='I'>name</emphasis> and <emphasis remap='I'>prefix</emphasis> fields have been | |
| 3766 | set to meet the minimum requirements for {PATH_MAX}. If a | |
| 3767 | pathname will fit within the <emphasis remap='I'>name</emphasis> field, it is recommended that | |
| 3768 | the pathname be stored there without the use of the | |
| 3769 | <emphasis remap='I'>prefix</emphasis> field. Although the name field is known to be too small | |
| 3770 | to contain {PATH_MAX} characters, the value was not changed | |
| 3771 | in this version of the archive file format to retain backwards-compatibility, | |
| 3772 | and instead the prefix was introduced. Also, because | |
| 3773 | of the earlier version of the format, there is no way to remove the | |
| 3774 | restriction on the <emphasis remap='I'>linkname</emphasis> field being limited in size | |
| 3775 | to just that of the <emphasis remap='I'>name</emphasis> field.</para> | |
| 3776 | ||
| 3777 | <para>The <emphasis remap='I'>size</emphasis> field is required to be meaningful in all implementation | |
| 3778 | extensions, although it could be zero. This is required | |
| 3779 | so that the data blocks can always be properly counted.</para> | |
| 3780 | ||
| 3781 | <para>It is suggested that if device special files need to be represented | |
| 3782 | that cannot be represented in the standard format, that one | |
| 3783 | of the extension types ( <emphasis remap='B'>A</emphasis>- <emphasis remap='B'>Z</emphasis>) be used, and that the additional | |
| 3784 | information for the special file be represented as | |
| 3785 | data and be reflected in the <emphasis remap='I'>size</emphasis> field.</para> | |
| 3786 | ||
| 3787 | <para>Attempting to restore a special file type, where it is converted to | |
| 3788 | ordinary data and conflicts with an existing filename, need | |
| 3789 | not be specially detected by the utility. If run as an ordinary user, | |
| 3790 | <command>pax</command> should not be able to overwrite the entries in, | |
| 3791 | for example, <filename>/dev</filename> in any case (whether the file is converted | |
| 3792 | to another type or not). If run as a privileged user, it should | |
| 3793 | be able to do so, and it would be considered a bug if it did not. | |
| 3794 | The same is true of ordinary data files and similarly named | |
| 3795 | special files; it is impossible to anticipate the needs of the user | |
| 3796 | (who could really intend to overwrite the file), so the | |
| 3797 | behavior should be predictable (and thus regular) and rely on the | |
| 3798 | protection system as required.</para> | |
| 3799 | ||
| 3800 | <para>The value 7 in the <emphasis remap='I'>typeflag</emphasis> field is intended to define how | |
| 3801 | contiguous files can be stored in a <emphasis remap='B'>ustar</emphasis> archive. | |
| 3802 | IEEE Std 1003.1-2001 does not require the contiguous file extension, | |
| 3803 | but does define a standard way of archiving such | |
| 3804 | files so that all conforming systems can interpret these file types | |
| 3805 | in a meaningful and consistent manner. On a system that does | |
| 3806 | not support extended file types, the <command>pax</command> utility should do the | |
| 3807 | best it can with the file and go on to the next.</para> | |
| 3808 | ||
| 3809 | <para>The file protection modes are those conventionally used by the <emphasis remap='I'>ls</emphasis> | |
| 3810 | utility. This is | |
| 3811 | extended beyond the usage in the ISO POSIX-2 standard to support | |
| 3812 | the "shared text" or "sticky" bit. It is intended that | |
| 3813 | the conformance document should not document anything beyond the existence | |
| 3814 | of and support of such a mode. Further extensions are | |
| 3815 | expected to these bits, particularly with overloading the set-user-ID | |
| 3816 | and set-group-ID flags.</para> | |
| 3817 | </refsect2> | |
| 3818 | ||
| 3819 | <refsect2 id='cpio_interchange_format2'><title>cpio Interchange Format</title> | |
| 3820 | ||
| 3821 | <para>The reference to appropriate privilege in the <emphasis remap='B'>cpio</emphasis> format refers | |
| 3822 | to an error on standard output; the <emphasis remap='B'>ustar</emphasis> format | |
| 3823 | does not make comparable statements.</para> | |
| 3824 | ||
| 3825 | <para>The model for this format was the historical System V <emphasis remap='I'>cpio</emphasis> <option>-c</option> | |
| 3826 | data interchange format. This model documents the | |
| 3827 | portable version of the <emphasis remap='B'>cpio</emphasis> format and not the binary version. | |
| 3828 | It has the flexibility to transfer data of any type | |
| 3829 | described within IEEE Std 1003.1-2001, yet is extensible to transfer | |
| 3830 | data types specific to extensions beyond | |
| 3831 | IEEE Std 1003.1-2001 (for example, contiguous files). Because it | |
| 3832 | describes existing practice, there is no question of | |
| 3833 | maintaining upwards-compatibility.</para> | |
| 3834 | </refsect2> | |
| 3835 | ||
| 3836 | <refsect2 id='cpio_header2'><title>cpio Header</title> | |
| 3837 | ||
| 3838 | <para>There has been some concern that the size of the <emphasis remap='I'>c_ino</emphasis> field | |
| 3839 | of the header is too small to handle those systems that have | |
| 3840 | very large <emphasis remap='I'>inode</emphasis> numbers. However, the <emphasis remap='I'>c_ino</emphasis> field in | |
| 3841 | the header is used strictly as a hard-link resolution mechanism | |
| 3842 | for archives. It is not necessarily the same value as the <emphasis remap='I'>inode</emphasis> | |
| 3843 | number of the file in the location from which that file is | |
| 3844 | extracted.</para> | |
| 3845 | ||
| 3846 | <para>The name <emphasis remap='I'>c_magic</emphasis> is based on historical usage.</para> | |
| 3847 | </refsect2> | |
| 3848 | ||
| 3849 | <refsect2 id='cpio_filename2'><title>cpio Filename</title> | |
| 3850 | ||
| 3851 | <para>For most historical implementations of the <emphasis remap='I'>cpio</emphasis> utility, {PATH_MAX} | |
| 3852 | octets can be used to describe the pathname without | |
| 3853 | the addition of any other header fields (the NUL character would be | |
| 3854 | included in this count). {PATH_MAX} is the minimum value for | |
| 3855 | pathname size, documented as 256 bytes. However, an implementation | |
| 3856 | may use <emphasis remap='I'>c_namesize</emphasis> to determine the exact length of the | |
| 3857 | pathname. With the current description of the <emphasis remap='I'><cpio.h></emphasis> header, | |
| 3858 | this pathname | |
| 3859 | size can be as large as a number that is described in six octal digits.</para> | |
| 3860 | ||
| 3861 | <para>Two values are documented under the <emphasis remap='I'>c_mode</emphasis> field values to provide | |
| 3862 | for extensibility for known file types:</para> | |
| 3863 | <variablelist remap='TP'> | |
| 3864 | <varlistentry> | |
| 3865 | <term><emphasis remap='B'>0110 000</emphasis></term> | |
| 3866 | <listitem> | |
| 3867 | <para>Reserved for contiguous files. The implementation may treat the rest | |
| 3868 | of the information for this archive like a regular file. | |
| 3869 | If this file type is undefined, the implementation may create the | |
| 3870 | file as a regular file.</para> | |
| 3871 | ||
| 3872 | ||
| 3873 | <para>This provides for extensibility of the <emphasis remap='B'>cpio</emphasis> format while allowing | |
| 3874 | for the ability to read old archives. Files of an | |
| 3875 | unknown type may be read as "regular files" on some implementations. | |
| 3876 | On a system that does not support extended file types, the | |
| 3877 | <command>pax</command> utility should do the best it can with the file and go on | |
| 3878 | to the next.</para> | |
| 3879 | </listitem> | |
| 3880 | </varlistentry> | |
| 3881 | </variablelist> | |
| 3882 | </refsect2> | |
| 3883 | </refsect1> | |
| 3884 | ||
| 3885 | <refsect1 id='future_directions'><title>FUTURE DIRECTIONS</title> | |
| 3886 | <para>None.</para> | |
| 3887 | </refsect1> | |
| 3888 | ||
| 3889 | <refsect1 id='see_also'><title>SEE ALSO</title> | |
| 3890 | <para><emphasis remap='I'>Shell Command Language</emphasis> , <emphasis remap='I'>cp</emphasis> , <emphasis remap='I'>ed</emphasis> , <emphasis remap='I'>getopts</emphasis> | |
| 3891 | , <emphasis remap='I'>ls</emphasis> , <emphasis remap='I'>printf</emphasis>() , the Base Definitions volume of IEEE Std 1003.1-2001, | |
| 3892 | <emphasis remap='I'><cpio.h></emphasis>, the System Interfaces volume of IEEE Std 1003.1-2001, | |
| 3893 | <emphasis remap='I'>chown</emphasis>(), <emphasis remap='I'>creat</emphasis>(), <emphasis remap='I'>mkdir</emphasis>(), <emphasis remap='I'>mkfifo</emphasis>(), <emphasis remap='I'>stat</emphasis>(), | |
| 3894 | <emphasis remap='I'>utime</emphasis>(), <emphasis remap='I'>write</emphasis>()</para> | |
| 3895 | </refsect1> | |
| 3896 | ||
| 3897 | <refsect1 id='copyright'><title>COPYRIGHT</title> | |
| 3898 | <para>Portions of this text are reprinted and reproduced in electronic form | |
| 3899 | from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology | |
| 3900 | -- Portable Operating System Interface (POSIX), The Open Group Base | |
| 3901 | Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of | |
| 3902 | Electrical and Electronics Engineers, Inc and The Open Group. In the | |
| 3903 | event of any discrepancy between this version and the original IEEE and | |
| 3904 | The Open Group Standard, the original IEEE and The Open Group Standard | |
| 3905 | is the referee document. The original Standard can be obtained online at | |
| 3906 | <ulink url='http://www.opengroup.org/unix/online.html'>http://www.opengroup.org/unix/online.html</ulink> .</para> | |
| 3907 | </refsect1> | |
| 3908 | </refentry> | |
| 3909 |
| 0 | .\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved | |
| 1 | .TH "PAX" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" | |
| 2 | .\" pax | |
| 3 | .SH NAME | |
| 4 | pax \- portable archive interchange | |
| 5 | .SH SYNOPSIS | |
| 6 | .nf | |
| 7 | \fBpax\fP \ | |
| 8 | \fB[\fP\fB-cdnv\fP\fB]\fP \ | |
| 9 | \fB[\fP\fB-H|-L\fP\fB]\fP \ | |
| 10 | \fB[\fP\fB-f\fP \fIarchive\fP\fB]\fP \ | |
| 11 | \fB[\fP\fB-s\fP \fIreplstr\fP\fP\fB]\fP\fB...\fP \ | |
| 12 | \fB[\fP\fIpattern\fP\fB...\fP\fB]\fP | |
| 13 | .br | |
| 14 | .sp | |
| 15 | \fBpax -r\fP \ | |
| 16 | \fB[\fP\fB-cdiknuv\fP\fB]\fP \ | |
| 17 | \fB[\fP\fB-H|-L\fP\fB]\fP \ | |
| 18 | \fB[\fP\fB-f\fP \fIarchive\fP\fB]\fP \ | |
| 19 | \fB[\fP\fB-o\fP \fIoptions\fP\fB]\fP\fB...\fP \ | |
| 20 | \fB[\fP\fB-p\fP \fIstring\fP\fB]\fP\fB...\fP | |
| 21 | .br | |
| 22 | \ \ \ \ \ \ \fB[\fP\fB-s\fP \fIreplstr\fP\fB]\fP\fB...\fP \ | |
| 23 | \fB[\fP\fIpattern\fP\fB...\fP\fB]\fP\fB | |
| 24 | .br | |
| 25 | .sp | |
| 26 | pax -w\fP \ | |
| 27 | \fB[\fP\fB-dituvX\fP\fB]\fP \ | |
| 28 | \fB[\fP\fB-H|-L\fP\fB]\fP \ | |
| 29 | \fB[\fP\fB-b\fP \fIblksize\fP\fB]\fP \ | |
| 30 | \fB[\fP\fB-a\fP\fB]\fP \ | |
| 31 | \fB[\fP\fB-f\fP \fIarchive\fP\fB]\fP \ | |
| 32 | \fB[\fP\fB-o\fP \fIoptions\fP\fB]\fP\fB...\fP | |
| 33 | .br | |
| 34 | \ \ \ \ \ \ \fB[\fP\fB-s\fP \fIreplstr\fP\fB]\fP\fB...\fP \ | |
| 35 | \fB[\fP\fB-x\fP \fIformat\fP\fB]\fP \ | |
| 36 | \fB[\fP\fIfile\fP\fB...\fP\fB]\fP\fB | |
| 37 | .br | |
| 38 | .sp | |
| 39 | pax -r -w\fP \ | |
| 40 | \fB[\fP\fB-diklntuvX\fP\fB]\fP \ | |
| 41 | \fB[\fP\fB-H|-L\fP\fB]\fP \ | |
| 42 | \fB[\fP\fB-p\fP \fIstring\fP\fB]\fP\fB...\fP \ | |
| 43 | \fB[\fP\fB-s\fP \fIreplstr\fP\fB]\fP\fB... | |
| 44 | .br | |
| 45 | \ \ \ \ \ \ \fB[\fP\fIfile\fP\fB...\fP\fB]\fP \ | |
| 46 | \fIdirectory\fP | |
| 47 | .br | |
| 48 | .fi | |
| 49 | .SH DESCRIPTION | |
| 50 | .LP | |
| 51 | The \fIpax\fP utility shall read, write, and write lists of the members | |
| 52 | of archive files and copy directory hierarchies. A | |
| 53 | variety of archive formats shall be supported; see the \fB-x\fP \fIformat\fP | |
| 54 | option. | |
| 55 | .LP | |
| 56 | The action to be taken depends on the presence of the \fB-r\fP and | |
| 57 | \fB-w\fP options. The four combinations of \fB-r\fP and | |
| 58 | \fB-w\fP are referred to as the four modes of operation: \fBlist\fP, | |
| 59 | \fBread\fP, \fBwrite\fP, and \fBcopy\fP modes, | |
| 60 | corresponding respectively to the four forms shown in the SYNOPSIS | |
| 61 | section. | |
| 62 | .TP 7 | |
| 63 | \fBlist\fP | |
| 64 | In \fBlist\fP mode (when neither \fB-r\fP nor \fB-w\fP are specified), | |
| 65 | \fIpax\fP shall write the names of the members of | |
| 66 | the archive file read from the standard input, with pathnames matching | |
| 67 | the specified patterns, to standard output. If a named file | |
| 68 | is of type directory, the file hierarchy rooted at that file shall | |
| 69 | be listed as well. | |
| 70 | .TP 7 | |
| 71 | \fBread\fP | |
| 72 | In \fBread\fP mode (when \fB-r\fP is specified, but \fB-w\fP is not), | |
| 73 | \fIpax\fP shall extract the members of the archive | |
| 74 | file read from the standard input, with pathnames matching the specified | |
| 75 | patterns. If an extracted file is of type directory, the | |
| 76 | file hierarchy rooted at that file shall be extracted as well. The | |
| 77 | extracted files shall be created performing pathname resolution | |
| 78 | with the directory in which \fIpax\fP was invoked as the current working | |
| 79 | directory. | |
| 80 | .LP | |
| 81 | If an attempt is made to extract a directory when the directory already | |
| 82 | exists, this shall not be considered an error. If an | |
| 83 | attempt is made to extract a FIFO when the FIFO already exists, this | |
| 84 | shall not be considered an error. | |
| 85 | .LP | |
| 86 | The ownership, access, and modification times, and file mode of the | |
| 87 | restored files are discussed under the \fB-p\fP option. | |
| 88 | .TP 7 | |
| 89 | \fBwrite\fP | |
| 90 | In \fBwrite\fP mode (when \fB-w\fP is specified, but \fB-r\fP is not), | |
| 91 | \fIpax\fP shall write the contents of the | |
| 92 | \fIfile\fP operands to the standard output in an archive format. If | |
| 93 | no \fIfile\fP operands are specified, a list of files to | |
| 94 | copy, one per line, shall be read from the standard input. A file | |
| 95 | of type directory shall include all of the files in the file | |
| 96 | hierarchy rooted at the file. | |
| 97 | .TP 7 | |
| 98 | \fBcopy\fP | |
| 99 | In \fBcopy\fP mode (when both \fB-r\fP and \fB-w\fP are specified), | |
| 100 | \fIpax\fP shall copy the \fIfile\fP operands to the | |
| 101 | destination directory. | |
| 102 | .LP | |
| 103 | If no \fIfile\fP operands are specified, a list of files to copy, | |
| 104 | one per line, shall be read from the standard input. A file | |
| 105 | of type directory shall include all of the files in the file hierarchy | |
| 106 | rooted at the file. | |
| 107 | .LP | |
| 108 | The effect of the \fBcopy\fP shall be as if the copied files were | |
| 109 | written to an archive file and then subsequently extracted, | |
| 110 | except that there may be hard links between the original and the copied | |
| 111 | files. If the destination directory is a subdirectory of | |
| 112 | one of the files to be copied, the results are unspecified. If the | |
| 113 | destination directory is a file of a type not defined by the | |
| 114 | System Interfaces volume of IEEE\ Std\ 1003.1-2001, the results are | |
| 115 | implementation-defined; otherwise, it shall be an error | |
| 116 | for the file named by the \fIdirectory\fP operand not to exist, not | |
| 117 | be writable by the user, or not be a file of type | |
| 118 | directory. | |
| 119 | .sp | |
| 120 | .LP | |
| 121 | In \fBread\fP or \fBcopy\fP modes, if intermediate directories are | |
| 122 | necessary to extract an archive member, \fIpax\fP shall | |
| 123 | perform actions equivalent to the \fImkdir\fP() function defined in | |
| 124 | the System Interfaces | |
| 125 | volume of IEEE\ Std\ 1003.1-2001, called with the following arguments: | |
| 126 | .IP " *" 3 | |
| 127 | The intermediate directory used as the \fIpath\fP argument | |
| 128 | .LP | |
| 129 | .IP " *" 3 | |
| 130 | The value of the bitwise-inclusive OR of S_IRWXU, S_IRWXG, and S_IRWXO | |
| 131 | as the \fImode\fP argument | |
| 132 | .LP | |
| 133 | .LP | |
| 134 | If any specified \fIpattern\fP or \fIfile\fP operands are not matched | |
| 135 | by at least one file or archive member, \fIpax\fP shall | |
| 136 | write a diagnostic message to standard error for each one that did | |
| 137 | not match and exit with a non-zero exit status. | |
| 138 | .LP | |
| 139 | The archive formats described in the EXTENDED DESCRIPTION section | |
| 140 | shall be automatically detected on input. The default output | |
| 141 | archive format shall be implementation-defined. | |
| 142 | .LP | |
| 143 | A single archive can span multiple files. The \fIpax\fP utility shall | |
| 144 | determine, in an implementation-defined manner, what file | |
| 145 | to read or write as the next file. | |
| 146 | .LP | |
| 147 | If the selected archive format supports the specification of linked | |
| 148 | files, it shall be an error if these files cannot be linked | |
| 149 | when the archive is extracted. For archive formats that do not store | |
| 150 | file contents with each name that causes a hard link, if the | |
| 151 | file that contains the data is not extracted during this \fIpax\fP | |
| 152 | session, either the data shall be restored from the original | |
| 153 | file, or a diagnostic message shall be displayed with the name of | |
| 154 | a file that can be used to extract the data. In traversing | |
| 155 | directories, \fIpax\fP shall detect infinite loops; that is, entering | |
| 156 | a previously visited directory that is an ancestor of the | |
| 157 | last file visited. When it detects an infinite loop, \fIpax\fP shall | |
| 158 | write a diagnostic message to standard error and shall | |
| 159 | terminate. | |
| 160 | .SH OPTIONS | |
| 161 | .LP | |
| 162 | The \fIpax\fP utility shall conform to the Base Definitions volume | |
| 163 | of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines, | |
| 164 | except that the order of presentation of the | |
| 165 | \fB-o\fP, \fB-p\fP, and \fB-s\fP options is significant. | |
| 166 | .LP | |
| 167 | The following options shall be supported: | |
| 168 | .TP 7 | |
| 169 | \fB-r\fP | |
| 170 | Read an archive file from standard input. | |
| 171 | .TP 7 | |
| 172 | \fB-w\fP | |
| 173 | Write files to the standard output in the specified archive format. | |
| 174 | .TP 7 | |
| 175 | \fB-a\fP | |
| 176 | Append files to the end of the archive. It is implementation-defined | |
| 177 | which devices on the system support appending. Additional | |
| 178 | file formats unspecified by this volume of IEEE\ Std\ 1003.1-2001 | |
| 179 | may impose restrictions on appending. | |
| 180 | .TP 7 | |
| 181 | \fB-b\ \fP \fIblocksize\fP | |
| 182 | Block the output at a positive decimal integer number of bytes per | |
| 183 | write to the archive file. Devices and archive formats may | |
| 184 | impose restrictions on blocking. Blocking shall be automatically determined | |
| 185 | on input. Conforming applications shall not specify a | |
| 186 | \fIblocksize\fP value larger than 32256. Default blocking when creating | |
| 187 | archives depends on the archive format. (See the \fB-x\fP | |
| 188 | option below.) | |
| 189 | .TP 7 | |
| 190 | \fB-c\fP | |
| 191 | Match all file or archive members except those specified by the \fIpattern\fP | |
| 192 | or \fIfile\fP operands. | |
| 193 | .TP 7 | |
| 194 | \fB-d\fP | |
| 195 | Cause files of type directory being copied or archived or archive | |
| 196 | members of type directory being extracted or listed to match | |
| 197 | only the file or archive member itself and not the file hierarchy | |
| 198 | rooted at the file. | |
| 199 | .TP 7 | |
| 200 | \fB-f\ \fP \fIarchive\fP | |
| 201 | Specify the pathname of the input or output archive, overriding the | |
| 202 | default standard input (in \fBlist\fP or \fBread\fP | |
| 203 | modes) or standard output ( \fBwrite\fP mode). | |
| 204 | .TP 7 | |
| 205 | \fB-H\fP | |
| 206 | If a symbolic link referencing a file of type directory is specified | |
| 207 | on the command line, \fIpax\fP shall archive the file | |
| 208 | hierarchy rooted in the file referenced by the link, using the name | |
| 209 | of the link as the root of the file hierarchy. Otherwise, if a | |
| 210 | symbolic link referencing a file of any other file type which \fIpax\fP | |
| 211 | can normally archive is specified on the command line, | |
| 212 | then \fIpax\fP shall archive the file referenced by the link, using | |
| 213 | the name of the link. The default behavior shall be to archive | |
| 214 | the symbolic link itself. | |
| 215 | .TP 7 | |
| 216 | \fB-i\fP | |
| 217 | Interactively rename files or archive members. For each archive member | |
| 218 | matching a \fIpattern\fP operand or file matching a | |
| 219 | \fIfile\fP operand, a prompt shall be written to the file \fB/dev/tty\fP. | |
| 220 | The prompt shall contain the name of the file or | |
| 221 | archive member, but the format is otherwise unspecified. A line shall | |
| 222 | then be read from \fB/dev/tty\fP. If this line is blank, the | |
| 223 | file or archive member shall be skipped. If this line consists of | |
| 224 | a single period, the file or archive member shall be processed | |
| 225 | with no modification to its name. Otherwise, its name shall be replaced | |
| 226 | with the contents of the line. The \fIpax\fP utility shall | |
| 227 | immediately exit with a non-zero exit status if end-of-file is encountered | |
| 228 | when reading a response or if \fB/dev/tty\fP cannot be | |
| 229 | opened for reading and writing. | |
| 230 | .LP | |
| 231 | The results of extracting a hard link to a file that has been renamed | |
| 232 | during extraction are unspecified. | |
| 233 | .TP 7 | |
| 234 | \fB-k\fP | |
| 235 | Prevent the overwriting of existing files. | |
| 236 | .TP 7 | |
| 237 | \fB-l\fP | |
| 238 | (The letter ell.) In \fBcopy\fP mode, hard links shall be made between | |
| 239 | the source and destination file hierarchies whenever | |
| 240 | possible. If specified in conjunction with \fB-H\fP or \fB-L\fP, when | |
| 241 | a symbolic link is encountered, the hard link created in | |
| 242 | the destination file hierarchy shall be to the file referenced by | |
| 243 | the symbolic link. If specified when neither \fB-H\fP nor | |
| 244 | \fB-L\fP is specified, when a symbolic link is encountered, the implementation | |
| 245 | shall create a hard link to the symbolic link in | |
| 246 | the source file hierarchy or copy the symbolic link to the destination. | |
| 247 | .TP 7 | |
| 248 | \fB-L\fP | |
| 249 | If a symbolic link referencing a file of type directory is specified | |
| 250 | on the command line or encountered during the traversal of | |
| 251 | a file hierarchy, \fIpax\fP shall archive the file hierarchy rooted | |
| 252 | in the file referenced by the link, using the name of the link | |
| 253 | as the root of the file hierarchy. Otherwise, if a symbolic link referencing | |
| 254 | a file of any other file type which \fIpax\fP can | |
| 255 | normally archive is specified on the command line or encountered during | |
| 256 | the traversal of a file hierarchy, \fIpax\fP shall archive | |
| 257 | the file referenced by the link, using the name of the link. The default | |
| 258 | behavior shall be to archive the symbolic link | |
| 259 | itself. | |
| 260 | .TP 7 | |
| 261 | \fB-n\fP | |
| 262 | Select the first archive member that matches each \fIpattern\fP operand. | |
| 263 | No more than one archive member shall be matched for | |
| 264 | each pattern (although members of type directory shall still match | |
| 265 | the file hierarchy rooted at that file). | |
| 266 | .TP 7 | |
| 267 | \fB-o\ \fP \fIoptions\fP | |
| 268 | Provide information to the implementation to modify the algorithm | |
| 269 | for extracting or writing files. The value of \fIoptions\fP | |
| 270 | shall consist of one or more comma-separated keywords of the form: | |
| 271 | .sp | |
| 272 | .RS | |
| 273 | .nf | |
| 274 | ||
| 275 | \fIkeyword\fP\fB[[\fP\fB:\fP\fB]\fP\fB=\fP\fIvalue\fP\fB][\fP\fB,\fP\fIkeyword\fP\fB[[\fP\fB:\fP\fB]\fP\fB=\fP\fIvalue\fP\fB]\fP\fB, ...\fP\fB]\fP | |
| 276 | .fi | |
| 277 | .RE | |
| 278 | .LP | |
| 279 | Some keywords apply only to certain file formats, as indicated with | |
| 280 | each description. Use of keywords that are inapplicable to | |
| 281 | the file format being processed produces undefined results. | |
| 282 | .LP | |
| 283 | Keywords in the \fIoptions\fP argument shall be a string that would | |
| 284 | be a valid portable filename as described in the Base | |
| 285 | Definitions volume of IEEE\ Std\ 1003.1-2001, Section 3.276, Portable | |
| 286 | Filename Character Set. | |
| 287 | .TP 7 | |
| 288 | \fBNote:\fP | |
| 289 | .RS | |
| 290 | Keywords are not expected to be filenames, merely to follow the same | |
| 291 | character composition rules as portable filenames. | |
| 292 | .RE | |
| 293 | .sp | |
| 294 | .LP | |
| 295 | Keywords can be preceded with white space. The \fIvalue\fP field shall | |
| 296 | consist of zero or more characters; within \fIvalue\fP, | |
| 297 | the application shall precede any literal comma with a backslash, | |
| 298 | which shall be ignored, but preserves the comma as part of | |
| 299 | \fIvalue\fP. A comma as the final character, or a comma followed solely | |
| 300 | by white space as the final characters, in \fIoptions\fP | |
| 301 | shall be ignored. Multiple \fB-o\fP options can be specified; if keywords | |
| 302 | given to these multiple \fB-o\fP options conflict, the | |
| 303 | keywords and values appearing later in command line sequence shall | |
| 304 | take precedence and the earlier shall be silently ignored. The | |
| 305 | following keyword values of \fIoptions\fP shall be supported for the | |
| 306 | file formats as indicated: | |
| 307 | .TP 7 | |
| 308 | \fBdelete\fP=\fIpattern\fP | |
| 309 | .RS | |
| 310 | .sp | |
| 311 | (Applicable only to the \fB-x\fP \fBpax\fP format.) When used in \fBwrite\fP | |
| 312 | or \fBcopy\fP mode, \fIpax\fP shall omit from | |
| 313 | extended header records that it produces any keywords matching the | |
| 314 | string pattern. When used in \fBread\fP or \fBlist\fP mode, | |
| 315 | \fIpax\fP shall ignore any keywords matching the string pattern in | |
| 316 | the extended header records. In both cases, matching shall be | |
| 317 | performed using the pattern matching notation described in \fIPatterns | |
| 318 | Matching a Single | |
| 319 | Character\fP and \fIPatterns Matching Multiple Characters\fP . For | |
| 320 | example: | |
| 321 | .sp | |
| 322 | .RS | |
| 323 | .nf | |
| 324 | ||
| 325 | \fB-o\fP \fBdelete\fP\fB=\fP\fIsecurity\fP\fB.* | |
| 326 | \fP | |
| 327 | .fi | |
| 328 | .RE | |
| 329 | .LP | |
| 330 | would suppress security-related information. See pax Extended Header | |
| 331 | for extended header record | |
| 332 | keyword usage. | |
| 333 | .RE | |
| 334 | .TP 7 | |
| 335 | \fBexthdr.name\fP=\fIstring\fP | |
| 336 | .RS | |
| 337 | .sp | |
| 338 | (Applicable only to the \fB-x\fP \fBpax\fP format.) This keyword allows | |
| 339 | user control over the name that is written into the | |
| 340 | \fBustar\fP header blocks for the extended header produced under the | |
| 341 | circumstances described in pax | |
| 342 | Header Block . The name shall be the contents of \fIstring\fP, after | |
| 343 | the following character substitutions have been made: | |
| 344 | .TS C | |
| 345 | center; l lw(40). | |
| 346 | \fB\fIstring\fP\fP T{ | |
| 347 | .na | |
| 348 | \fB\ \fP | |
| 349 | .ad | |
| 350 | T} | |
| 351 | \fBIncludes:\fP T{ | |
| 352 | .na | |
| 353 | \fBReplaced By:\fP | |
| 354 | .ad | |
| 355 | T} | |
| 356 | %d T{ | |
| 357 | .na | |
| 358 | The directory name of the file, equivalent to the result of the \fIdirname\fP utility on the translated pathname. | |
| 359 | .ad | |
| 360 | T} | |
| 361 | %f T{ | |
| 362 | .na | |
| 363 | The filename of the file, equivalent to the result of the \fIbasename\fP utility on the translated pathname. | |
| 364 | .ad | |
| 365 | T} | |
| 366 | %p T{ | |
| 367 | .na | |
| 368 | The process ID of the \fIpax\fP process. | |
| 369 | .ad | |
| 370 | T} | |
| 371 | %% T{ | |
| 372 | .na | |
| 373 | A \fB'%'\fP character. | |
| 374 | .ad | |
| 375 | T} | |
| 376 | .TE | |
| 377 | .LP | |
| 378 | Any other \fB'%'\fP characters in \fIstring\fP produce undefined results. | |
| 379 | .LP | |
| 380 | If no \fB-o\fP \fBexthdr.name=\fP \fIstring\fP is specified, \fIpax\fP | |
| 381 | shall use the following default value: | |
| 382 | .sp | |
| 383 | .RS | |
| 384 | .nf | |
| 385 | ||
| 386 | \fB%d/PaxHeaders.%p/%f | |
| 387 | \fP | |
| 388 | .fi | |
| 389 | .RE | |
| 390 | .RE | |
| 391 | .TP 7 | |
| 392 | \fBglobexthdr.name\fP=\fIstring\fP | |
| 393 | .RS | |
| 394 | .sp | |
| 395 | (Applicable only to the \fB-x\fP \fBpax\fP format.) When used in \fBwrite\fP | |
| 396 | or \fBcopy\fP mode with the appropriate options, | |
| 397 | \fIpax\fP shall create global extended header records with \fBustar\fP | |
| 398 | header blocks that will be treated as regular files by | |
| 399 | previous versions of \fIpax\fP. This keyword allows user control over | |
| 400 | the name that is written into the \fBustar\fP header blocks | |
| 401 | for global extended header records. The name shall be the contents | |
| 402 | of string, after the following character substitutions have been | |
| 403 | made: | |
| 404 | .TS C | |
| 405 | center; l lw(40). | |
| 406 | \fB\fIstring\fP\fP T{ | |
| 407 | .na | |
| 408 | \fB\ \fP | |
| 409 | .ad | |
| 410 | T} | |
| 411 | \fBIncludes:\fP T{ | |
| 412 | .na | |
| 413 | \fBReplaced By:\fP | |
| 414 | .ad | |
| 415 | T} | |
| 416 | %n T{ | |
| 417 | .na | |
| 418 | An integer that represents the sequence number of the global extended header record in the archive, starting at 1. | |
| 419 | .ad | |
| 420 | T} | |
| 421 | %p T{ | |
| 422 | .na | |
| 423 | The process ID of the \fIpax\fP process. | |
| 424 | .ad | |
| 425 | T} | |
| 426 | %% T{ | |
| 427 | .na | |
| 428 | A \fB'%'\fP character. | |
| 429 | .ad | |
| 430 | T} | |
| 431 | .TE | |
| 432 | .LP | |
| 433 | Any other \fB'%'\fP characters in \fIstring\fP produce undefined results. | |
| 434 | .LP | |
| 435 | If no \fB-o\fP \fBglobexthdr.name=\fP \fIstring\fP is specified, \fIpax\fP | |
| 436 | shall use the following default value: | |
| 437 | .sp | |
| 438 | .RS | |
| 439 | .nf | |
| 440 | ||
| 441 | \fB$TMPDIR/GlobalHead.%p.%n | |
| 442 | \fP | |
| 443 | .fi | |
| 444 | .RE | |
| 445 | .LP | |
| 446 | where $ \fITMPDIR\fP represents the value of the \fITMPDIR\fP environment | |
| 447 | variable. If \fITMPDIR\fP is not set, \fIpax\fP | |
| 448 | shall use \fB/tmp\fP. | |
| 449 | .RE | |
| 450 | .TP 7 | |
| 451 | \fBinvalid\fP=\fIaction\fP | |
| 452 | .RS | |
| 453 | .sp | |
| 454 | (Applicable only to the \fB-x\fP \fBpax\fP format.) This keyword allows | |
| 455 | user control over the action \fIpax\fP takes upon | |
| 456 | encountering values in an extended header record that, in \fBread\fP | |
| 457 | or \fBcopy\fP mode, are invalid in the destination hierarchy | |
| 458 | or, in \fBlist\fP mode, cannot be written in the codeset and current | |
| 459 | locale of the implementation. The following are invalid | |
| 460 | values that shall be recognized by \fIpax\fP: | |
| 461 | .RS | |
| 462 | .IP " *" 3 | |
| 463 | In \fBread\fP or \fBcopy\fP mode, a filename or link name that contains | |
| 464 | character encodings invalid in the destination | |
| 465 | hierarchy. (For example, the name may contain embedded NULs.) | |
| 466 | .LP | |
| 467 | .IP " *" 3 | |
| 468 | In \fBread\fP or \fBcopy\fP mode, a filename or link name that is | |
| 469 | longer than the maximum allowed in the destination hierarchy | |
| 470 | (for either a pathname component or the entire pathname). | |
| 471 | .LP | |
| 472 | .IP " *" 3 | |
| 473 | In \fBlist\fP mode, any character string value (filename, link name, | |
| 474 | user name, and so on) that cannot be written in the | |
| 475 | codeset and current locale of the implementation. | |
| 476 | .LP | |
| 477 | .RE | |
| 478 | .LP | |
| 479 | The following mutually-exclusive values of the \fIaction\fP argument | |
| 480 | are supported: | |
| 481 | .TP 7 | |
| 482 | \fBbypass\fP | |
| 483 | .RS | |
| 484 | In \fBread\fP or \fBcopy\fP mode, \fIpax\fP shall bypass the file, | |
| 485 | causing no change to the destination hierarchy. In | |
| 486 | \fBlist\fP mode, \fIpax\fP shall write all requested valid values | |
| 487 | for the file, but its method for writing invalid values is | |
| 488 | unspecified. | |
| 489 | .RE | |
| 490 | .TP 7 | |
| 491 | \fBrename\fP | |
| 492 | .RS | |
| 493 | In \fBread\fP or \fBcopy\fP mode, \fIpax\fP shall act as if the \fB-i\fP | |
| 494 | option were in effect for each file with invalid | |
| 495 | filename or link name values, allowing the user to provide a replacement | |
| 496 | name interactively. In \fBlist\fP mode, \fIpax\fP shall | |
| 497 | behave identically to the \fBbypass\fP action. | |
| 498 | .RE | |
| 499 | .TP 7 | |
| 500 | \fBUTF-8\fP | |
| 501 | .RS | |
| 502 | When used in \fBread\fP, \fBcopy\fP, or \fBlist\fP mode and a filename, | |
| 503 | link name, owner name, or any other field in an | |
| 504 | extended header record cannot be translated from the \fBpax\fP UTF-8 | |
| 505 | codeset format to the codeset and current locale of the | |
| 506 | implementation, \fIpax\fP shall use the actual UTF-8 encoding for | |
| 507 | the name. | |
| 508 | .RE | |
| 509 | .TP 7 | |
| 510 | \fBwrite\fP | |
| 511 | .RS | |
| 512 | In \fBread\fP or \fBcopy\fP mode, \fIpax\fP shall write the file, | |
| 513 | translating or truncating the name, regardless of whether | |
| 514 | this may overwrite an existing file with a valid name. In \fBlist\fP | |
| 515 | mode, \fIpax\fP shall behave identically to the | |
| 516 | \fBbypass\fP action. | |
| 517 | .RE | |
| 518 | .sp | |
| 519 | .LP | |
| 520 | If no \fB-o\fP \fBinvalid=\fP option is specified, \fIpax\fP shall | |
| 521 | act as if \fB-o\fP \fBinvalid=\fP \fBbypass\fP were | |
| 522 | specified. Any overwriting of existing files that may be allowed by | |
| 523 | the \fB-o\fP \fBinvalid=\fP actions shall be subject to | |
| 524 | permission ( \fB-p\fP) and modification time ( \fB-u\fP) restrictions, | |
| 525 | and shall be suppressed if the \fB-k\fP option is also | |
| 526 | specified. | |
| 527 | .RE | |
| 528 | .TP 7 | |
| 529 | \fBlinkdata\fP | |
| 530 | .RS | |
| 531 | .sp | |
| 532 | (Applicable only to the \fB-x\fP \fBpax\fP format.) In \fBwrite\fP | |
| 533 | mode, \fIpax\fP shall write the contents of a file to the | |
| 534 | archive even when that file is merely a hard link to a file whose | |
| 535 | contents have already been written to the archive. | |
| 536 | .RE | |
| 537 | .TP 7 | |
| 538 | \fBlistopt\fP=\fIformat\fP | |
| 539 | .RS | |
| 540 | .sp | |
| 541 | This keyword specifies the output format of the table of contents | |
| 542 | produced when the \fB-v\fP option is specified in \fBlist\fP | |
| 543 | mode. See List Mode Format Specifications . To avoid ambiguity, the | |
| 544 | \fBlistopt=\fP \fIformat\fP | |
| 545 | shall be the only or final \fBkeyword=\fP \fIvalue\fP pair in a \fB-o\fP | |
| 546 | option-argument; all characters in the remainder of the | |
| 547 | option-argument shall be considered part of the format string. When | |
| 548 | multiple \fB-o\fP \fBlistopt=\fP \fIformat\fP options are | |
| 549 | specified, the format strings shall be considered a single, concatenated | |
| 550 | string, evaluated in command line order. | |
| 551 | .RE | |
| 552 | .TP 7 | |
| 553 | \fBtimes\fP | |
| 554 | .RS | |
| 555 | .sp | |
| 556 | (Applicable only to the \fB-x\fP \fIpax\fP format.) When used in \fBwrite\fP | |
| 557 | or \fBcopy\fP mode, \fIpax\fP shall include | |
| 558 | \fBatime\fP, \fBctime\fP, and \fBmtime\fP extended header records | |
| 559 | for each file. See pax Extended | |
| 560 | Header File Times . | |
| 561 | .RE | |
| 562 | .sp | |
| 563 | .LP | |
| 564 | In addition to these keywords, if the \fB-x\fP \fIpax\fP format is | |
| 565 | specified, any of the keywords and values defined in pax Extended | |
| 566 | Header , including implementation extensions, can be used in \fB-o\fP | |
| 567 | option-arguments, | |
| 568 | in either of two modes: | |
| 569 | .TP 7 | |
| 570 | \fBkeyword\fP=\fIvalue\fP | |
| 571 | .RS | |
| 572 | .sp | |
| 573 | When used in \fBwrite\fP or \fBcopy\fP mode, these keyword/value pairs | |
| 574 | shall be included at the beginning of the archive as | |
| 575 | \fBtypeflag\fP \fBg\fP global extended header records. When used in | |
| 576 | \fBread\fP or \fBlist\fP mode, these keyword/value pairs | |
| 577 | shall act as if they had been at the beginning of the archive as \fBtypeflag\fP | |
| 578 | \fBg\fP global extended header records. | |
| 579 | .RE | |
| 580 | .TP 7 | |
| 581 | \fBkeyword\fP:=\fIvalue\fP | |
| 582 | .RS | |
| 583 | .sp | |
| 584 | When used in \fBwrite\fP or \fBcopy\fP mode, these keyword/value pairs | |
| 585 | shall be included as records at the beginning of a | |
| 586 | \fBtypeflag\fP \fBx\fP extended header for each file. (This shall | |
| 587 | be equivalent to the equal-sign form except that it creates no | |
| 588 | \fBtypeflag\fP \fBg\fP global extended header records.) When used | |
| 589 | in \fBread\fP or \fBlist\fP mode, these keyword/value pairs | |
| 590 | shall act as if they were included as records at the end of each extended | |
| 591 | header; thus, they shall override any global or | |
| 592 | file-specific extended header record keywords of the same names. For | |
| 593 | example, in the command: | |
| 594 | .sp | |
| 595 | .RS | |
| 596 | .nf | |
| 597 | ||
| 598 | \fBpax -r -o " | |
| 599 | gname:=mygroup, | |
| 600 | " <archive | |
| 601 | \fP | |
| 602 | .fi | |
| 603 | .RE | |
| 604 | .LP | |
| 605 | the group name will be forced to a new value for all files read from | |
| 606 | the archive. | |
| 607 | .RE | |
| 608 | .sp | |
| 609 | .LP | |
| 610 | The precedence of \fB-o\fP keywords over various fields in the archive | |
| 611 | is described in pax Extended | |
| 612 | Header Keyword Precedence . | |
| 613 | .TP 7 | |
| 614 | \fB-p\ \fP \fIstring\fP | |
| 615 | Specify one or more file characteristic options (privileges). The | |
| 616 | \fIstring\fP option-argument shall be a string specifying | |
| 617 | file characteristics to be retained or discarded on extraction. The | |
| 618 | string shall consist of the specification characters \fBa\fP | |
| 619 | , \fBe\fP , \fBm\fP , \fBo\fP , and \fBp\fP . Other implementation-defined | |
| 620 | characters can be included. Multiple | |
| 621 | characteristics can be concatenated within the same string and multiple | |
| 622 | \fB-p\fP options can be specified. The meaning of the | |
| 623 | specification characters are as follows: | |
| 624 | .TP 7 | |
| 625 | \fBa\fP | |
| 626 | .RS | |
| 627 | Do not preserve file access times. | |
| 628 | .RE | |
| 629 | .TP 7 | |
| 630 | \fBe\fP | |
| 631 | .RS | |
| 632 | Preserve the user ID, group ID, file mode bits (see the Base Definitions | |
| 633 | volume of IEEE\ Std\ 1003.1-2001, Section 3.168, File Mode Bits), | |
| 634 | access time, modification time, and any other | |
| 635 | implementation-defined file characteristics. | |
| 636 | .RE | |
| 637 | .TP 7 | |
| 638 | \fBm\fP | |
| 639 | .RS | |
| 640 | Do not preserve file modification times. | |
| 641 | .RE | |
| 642 | .TP 7 | |
| 643 | \fBo\fP | |
| 644 | .RS | |
| 645 | Preserve the user ID and group ID. | |
| 646 | .RE | |
| 647 | .TP 7 | |
| 648 | \fBp\fP | |
| 649 | .RS | |
| 650 | Preserve the file mode bits. Other implementation-defined file mode | |
| 651 | attributes may be preserved. | |
| 652 | .RE | |
| 653 | .sp | |
| 654 | .LP | |
| 655 | In the preceding list, "preserve" indicates that an attribute stored | |
| 656 | in the archive shall be given to the extracted file, | |
| 657 | subject to the permissions of the invoking process. The access and | |
| 658 | modification times of the file shall be preserved unless | |
| 659 | otherwise specified with the \fB-p\fP option or not stored in the | |
| 660 | archive. All attributes that are not preserved shall be | |
| 661 | determined as part of the normal file creation action (see \fIFile | |
| 662 | Read, Write, and | |
| 663 | Creation\fP ). | |
| 664 | .LP | |
| 665 | If neither the \fBe\fP nor the \fBo\fP specification character is | |
| 666 | specified, or the user ID and group ID are not preserved | |
| 667 | for any reason, \fIpax\fP shall not set the S_ISUID and S_ISGID bits | |
| 668 | of the file mode. | |
| 669 | .LP | |
| 670 | If the preservation of any of these items fails for any reason, \fIpax\fP | |
| 671 | shall write a diagnostic message to standard error. | |
| 672 | Failure to preserve these items shall affect the final exit status, | |
| 673 | but shall not cause the extracted file to be deleted. | |
| 674 | .LP | |
| 675 | If file characteristic letters in any of the \fIstring\fP option-arguments | |
| 676 | are duplicated or conflict with each other, the ones | |
| 677 | given last shall take precedence. For example, if \fB-p\fP \fBeme\fP | |
| 678 | is specified, file modification times are preserved. | |
| 679 | .TP 7 | |
| 680 | \fB-s\ \fP \fIreplstr\fP | |
| 681 | Modify file or archive member names named by \fIpattern\fP or \fIfile\fP | |
| 682 | operands according to the substitution expression | |
| 683 | \fIreplstr\fP, using the syntax of the \fIed\fP utility. The concepts | |
| 684 | of "address" and | |
| 685 | "line" are meaningless in the context of the \fIpax\fP utility, and | |
| 686 | shall not be supplied. The format shall be: | |
| 687 | .sp | |
| 688 | .RS | |
| 689 | .nf | |
| 690 | ||
| 691 | \fB-s /\fP\fIold\fP\fB/\fP\fInew\fP\fB/\fP\fB[\fP\fBgp\fP\fB]\fP | |
| 692 | .fi | |
| 693 | .RE | |
| 694 | .LP | |
| 695 | where as in \fIed\fP, \fIold\fP is a basic regular expression and | |
| 696 | \fInew\fP can contain an | |
| 697 | ampersand, \fB'\\n'\fP (where \fIn\fP is a digit) backreferences, | |
| 698 | or subexpression matching. The \fIold\fP string shall also be | |
| 699 | permitted to contain <newline>s. | |
| 700 | .LP | |
| 701 | Any non-null character can be used as a delimiter ( \fB'/'\fP shown | |
| 702 | here). Multiple \fB-s\fP expressions can be specified; | |
| 703 | the expressions shall be applied in the order specified, terminating | |
| 704 | with the first successful substitution. The optional trailing | |
| 705 | \fB'g'\fP is as defined in the \fIed\fP utility. The optional trailing | |
| 706 | \fB'p'\fP shall | |
| 707 | cause successful substitutions to be written to standard error. File | |
| 708 | or archive member names that substitute to the empty string | |
| 709 | shall be ignored when reading and writing archives. | |
| 710 | .TP 7 | |
| 711 | \fB-t\fP | |
| 712 | When reading files from the file system, and if the user has the permissions | |
| 713 | required by \fIutime\fP() to do so, set the access time of each file | |
| 714 | read to the access time that it had before | |
| 715 | being read by \fIpax\fP. | |
| 716 | .TP 7 | |
| 717 | \fB-u\fP | |
| 718 | Ignore files that are older (having a less recent file modification | |
| 719 | time) than a pre-existing file or archive member with the | |
| 720 | same name. In \fBread\fP mode, an archive member with the same name | |
| 721 | as a file in the file system shall be extracted if the archive | |
| 722 | member is newer than the file. In \fBwrite\fP mode, an archive file | |
| 723 | member with the same name as a file in the file system shall | |
| 724 | be superseded if the file is newer than the archive member. If \fB-a\fP | |
| 725 | is also specified, this is accomplished by appending to | |
| 726 | the archive; otherwise, it is unspecified whether this is accomplished | |
| 727 | by actual replacement in the archive or by appending to the | |
| 728 | archive. In \fBcopy\fP mode, the file in the destination hierarchy | |
| 729 | shall be replaced by the file in the source hierarchy or by a | |
| 730 | link to the file in the source hierarchy if the file in the source | |
| 731 | hierarchy is newer. | |
| 732 | .TP 7 | |
| 733 | \fB-v\fP | |
| 734 | In \fBlist\fP mode, produce a verbose table of contents (see the STDOUT | |
| 735 | section). Otherwise, write archive member pathnames to | |
| 736 | standard error (see the STDERR section). | |
| 737 | .TP 7 | |
| 738 | \fB-x\ \fP \fIformat\fP | |
| 739 | Specify the output archive format. The \fIpax\fP utility shall support | |
| 740 | the following formats: | |
| 741 | .TP 7 | |
| 742 | \fBcpio\fP | |
| 743 | .RS | |
| 744 | The \fBcpio\fP interchange format; see the EXTENDED DESCRIPTION section. | |
| 745 | The default \fIblocksize\fP for this format for | |
| 746 | character special archive files shall be 5120. Implementations shall | |
| 747 | support all \fIblocksize\fP values less than or equal to | |
| 748 | 32256 that are multiples of 512. | |
| 749 | .RE | |
| 750 | .TP 7 | |
| 751 | \fBpax\fP | |
| 752 | .RS | |
| 753 | The \fBpax\fP interchange format; see the EXTENDED DESCRIPTION section. | |
| 754 | The default \fIblocksize\fP for this format for | |
| 755 | character special archive files shall be 5120. Implementations shall | |
| 756 | support all \fIblocksize\fP values less than or equal to | |
| 757 | 32256 that are multiples of 512. | |
| 758 | .RE | |
| 759 | .TP 7 | |
| 760 | \fBustar\fP | |
| 761 | .RS | |
| 762 | The \fBtar\fP interchange format; see the EXTENDED DESCRIPTION section. | |
| 763 | The default \fIblocksize\fP for this format for | |
| 764 | character special archive files shall be 10240. Implementations shall | |
| 765 | support all \fIblocksize\fP values less than or equal to | |
| 766 | 32256 that are multiples of 512. | |
| 767 | .RE | |
| 768 | .sp | |
| 769 | .LP | |
| 770 | Implementation-defined formats shall specify a default block size | |
| 771 | as well as any other block sizes supported for character | |
| 772 | special archive files. | |
| 773 | .LP | |
| 774 | Any attempt to append to an archive file in a format different from | |
| 775 | the existing archive format shall cause \fIpax\fP to exit | |
| 776 | immediately with a non-zero exit status. | |
| 777 | .LP | |
| 778 | In \fBcopy\fP mode, if no \fB-x\fP format is specified, \fIpax\fP | |
| 779 | shall behave as if \fB-x\fP \fIpax\fP were specified. | |
| 780 | .TP 7 | |
| 781 | \fB-X\fP | |
| 782 | When traversing the file hierarchy specified by a pathname, \fIpax\fP | |
| 783 | shall not descend into directories that have a different | |
| 784 | device ID ( \fIst_dev\fP; see the System Interfaces volume of IEEE\ Std\ 1003.1-2001, | |
| 785 | \fIstat\fP()). | |
| 786 | .sp | |
| 787 | .LP | |
| 788 | The options that operate on the names of files or archive members | |
| 789 | ( \fB-c\fP, \fB-i\fP, \fB-n\fP, \fB-s\fP, \fB-u\fP, and | |
| 790 | \fB-v\fP) shall interact as follows. In \fBread\fP mode, the archive | |
| 791 | members shall be selected based on the user-specified | |
| 792 | \fIpattern\fP operands as modified by the \fB-c\fP, \fB-n\fP, and | |
| 793 | \fB-u\fP options. Then, any \fB-s\fP and \fB-i\fP options | |
| 794 | shall modify, in that order, the names of the selected files. The | |
| 795 | \fB-v\fP option shall write names resulting from these | |
| 796 | modifications. | |
| 797 | .LP | |
| 798 | In \fBwrite\fP mode, the files shall be selected based on the user-specified | |
| 799 | pathnames as modified by the \fB-n\fP and | |
| 800 | \fB-u\fP options. Then, any \fB-s\fP and \fB-i\fP options shall modify, | |
| 801 | in that order, the names of these selected files. The | |
| 802 | \fB-v\fP option shall write names resulting from these modifications. | |
| 803 | .LP | |
| 804 | If both the \fB-u\fP and \fB-n\fP options are specified, \fIpax\fP | |
| 805 | shall not consider a file selected unless it is newer than | |
| 806 | the file to which it is compared. | |
| 807 | .SS List Mode Format Specifications | |
| 808 | .LP | |
| 809 | In \fBlist\fP mode with the \fB-o\fP \fBlistopt=\fP \fIformat\fP option, | |
| 810 | the \fIformat\fP argument shall be applied for | |
| 811 | each selected file. The \fIpax\fP utility shall append a <newline> | |
| 812 | to the \fBlistopt\fP output for each selected file. The | |
| 813 | \fIformat\fP argument shall be used as the \fIformat\fP string described | |
| 814 | in the Base Definitions volume of | |
| 815 | IEEE\ Std\ 1003.1-2001, Chapter 5, File Format Notation, with the | |
| 816 | exceptions 1. | |
| 817 | through 5. defined in the EXTENDED DESCRIPTION section of \fIprintf\fP, | |
| 818 | plus the following | |
| 819 | exceptions: | |
| 820 | .TP 7 | |
| 821 | 6. | |
| 822 | The sequence ( \fIkeyword\fP) can occur before a format conversion | |
| 823 | specifier. The conversion argument is defined by the value | |
| 824 | of \fIkeyword\fP. The implementation shall support the following keywords: | |
| 825 | .RS | |
| 826 | .IP " *" 3 | |
| 827 | Any of the Field Name entries in ustar Header Block and Octet-Oriented | |
| 828 | cpio | |
| 829 | Archive Entry . The implementation may support the \fIcpio\fP keywords | |
| 830 | without the leading \fBc_\fP in addition to the form | |
| 831 | required by Values for cpio c_mode Field . | |
| 832 | .LP | |
| 833 | .IP " *" 3 | |
| 834 | Any keyword defined for the extended header in pax Extended Header | |
| 835 | \&. | |
| 836 | .LP | |
| 837 | .IP " *" 3 | |
| 838 | Any keyword provided as an implementation-defined extension within | |
| 839 | the extended header defined in pax Extended Header . | |
| 840 | .LP | |
| 841 | .RE | |
| 842 | .LP | |
| 843 | For example, the sequence \fB"%(charset)s"\fP is the string value | |
| 844 | of the name of the character set in the extended | |
| 845 | header. | |
| 846 | .LP | |
| 847 | The result of the keyword conversion argument shall be the value from | |
| 848 | the applicable header field or extended header, without | |
| 849 | any trailing NULs. | |
| 850 | .LP | |
| 851 | All keyword values used as conversion arguments shall be translated | |
| 852 | from the UTF-8 encoding to the character set appropriate for | |
| 853 | the local file system, user database, and so on, as applicable. | |
| 854 | .TP 7 | |
| 855 | 7. | |
| 856 | An additional conversion specifier character, \fBT\fP , shall be used | |
| 857 | to specify time formats. The \fBT\fP conversion | |
| 858 | specifier character can be preceded by the sequence ( \fIkeyword=\fP | |
| 859 | \fIsubformat\fP), where \fIsubformat\fP is a date format as | |
| 860 | defined by \fIdate\fP operands. The default \fIkeyword\fP shall be | |
| 861 | \fBmtime\fP and the | |
| 862 | default subformat shall be: | |
| 863 | .sp | |
| 864 | .RS | |
| 865 | .nf | |
| 866 | ||
| 867 | \fB%b %e %H:%M %Y | |
| 868 | \fP | |
| 869 | .fi | |
| 870 | .RE | |
| 871 | .TP 7 | |
| 872 | 8. | |
| 873 | An additional conversion specifier character, \fBM\fP , shall be used | |
| 874 | to specify the file mode string as defined in \fIls\fP Standard Output. | |
| 875 | If ( \fIkeyword\fP) is omitted, the \fBmode\fP keyword shall be used. | |
| 876 | For | |
| 877 | example, \fB%.1M\fP writes the single character corresponding to the | |
| 878 | <\fIentry\ type\fP> field of the \fIls\fP \fB-l\fP command. | |
| 879 | .TP 7 | |
| 880 | 9. | |
| 881 | An additional conversion specifier character, \fBD\fP , shall be used | |
| 882 | to specify the device for block or special files, if | |
| 883 | applicable, in an implementation-defined format. If not applicable, | |
| 884 | and ( \fIkeyword\fP) is specified, then this conversion shall | |
| 885 | be equivalent to \fB%(\fP\fIkeyword\fP\fB)u\fP. If not applicable, | |
| 886 | and ( \fIkeyword\fP) is omitted, then this conversion | |
| 887 | shall be equivalent to <space>. | |
| 888 | .TP 7 | |
| 889 | 10. | |
| 890 | An additional conversion specifier character, \fBF\fP , shall be used | |
| 891 | to specify a pathname. The \fBF\fP conversion | |
| 892 | character can be preceded by a sequence of comma-separated keywords: | |
| 893 | .sp | |
| 894 | .RS | |
| 895 | .nf | |
| 896 | ||
| 897 | \fB(\fP\fIkeyword\fP\fB[\fP\fB,\fP\fIkeyword\fP\fB]\fP \fB... ) | |
| 898 | \fP | |
| 899 | .fi | |
| 900 | .RE | |
| 901 | .LP | |
| 902 | The values for all the keywords that are non-null shall be concatenated | |
| 903 | together, each separated by a \fB'/'\fP . The default | |
| 904 | shall be ( \fBpath\fP) if the keyword \fBpath\fP is defined; otherwise, | |
| 905 | the default shall be ( \fBprefix\fP, \fBname\fP). | |
| 906 | .TP 7 | |
| 907 | 11. | |
| 908 | An additional conversion specifier character, \fBL\fP , shall be used | |
| 909 | to specify a symbolic line expansion. If the current | |
| 910 | file is a symbolic link, then \fB%L\fP shall expand to: | |
| 911 | .sp | |
| 912 | .RS | |
| 913 | .nf | |
| 914 | ||
| 915 | \fB"%s -> %s", <\fP\fIvalue of keyword\fP\fB>, <\fP\fIcontents of link\fP\fB> | |
| 916 | \fP | |
| 917 | .fi | |
| 918 | .RE | |
| 919 | .LP | |
| 920 | Otherwise, the \fB%L\fP conversion specification shall be the equivalent | |
| 921 | of \fB%F\fP . | |
| 922 | .sp | |
| 923 | .SH OPERANDS | |
| 924 | .LP | |
| 925 | The following operands shall be supported: | |
| 926 | .TP 7 | |
| 927 | \fIdirectory\fP | |
| 928 | The destination directory pathname for \fBcopy\fP mode. | |
| 929 | .TP 7 | |
| 930 | \fIfile\fP | |
| 931 | A pathname of a file to be copied or archived. | |
| 932 | .TP 7 | |
| 933 | \fIpattern\fP | |
| 934 | A pattern matching one or more pathnames of archive members. A pattern | |
| 935 | must be given in the name-generating notation of the | |
| 936 | pattern matching notation in \fIPattern Matching Notation\fP , including | |
| 937 | the filename | |
| 938 | expansion rules in \fIPatterns Used for Filename Expansion\fP . The | |
| 939 | default, if no | |
| 940 | \fIpattern\fP is specified, is to select all members in the archive. | |
| 941 | .sp | |
| 942 | .SH STDIN | |
| 943 | .LP | |
| 944 | In \fBwrite\fP mode, the standard input shall be used only if no \fIfile\fP | |
| 945 | operands are specified. It shall be a text file | |
| 946 | containing a list of pathnames, one per line, without leading or trailing | |
| 947 | <blank>s. | |
| 948 | .LP | |
| 949 | In \fBlist\fP and \fBread\fP modes, if \fB-f\fP is not specified, | |
| 950 | the standard input shall be an archive file. | |
| 951 | .LP | |
| 952 | Otherwise, the standard input shall not be used. | |
| 953 | .SH INPUT FILES | |
| 954 | .LP | |
| 955 | The input file named by the \fIarchive\fP option-argument, or standard | |
| 956 | input when the archive is read from there, shall be a | |
| 957 | file formatted according to one of the specifications in the EXTENDED | |
| 958 | DESCRIPTION section or some other implementation-defined | |
| 959 | format. | |
| 960 | .LP | |
| 961 | The file \fB/dev/tty\fP shall be used to write prompts and read responses. | |
| 962 | .SH ENVIRONMENT VARIABLES | |
| 963 | .LP | |
| 964 | The following environment variables shall affect the execution of | |
| 965 | \fIpax\fP: | |
| 966 | .TP 7 | |
| 967 | \fILANG\fP | |
| 968 | Provide a default value for the internationalization variables that | |
| 969 | are unset or null. (See the Base Definitions volume of | |
| 970 | IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables | |
| 971 | for | |
| 972 | the precedence of internationalization variables used to determine | |
| 973 | the values of locale categories.) | |
| 974 | .TP 7 | |
| 975 | \fILC_ALL\fP | |
| 976 | If set to a non-empty string value, override the values of all the | |
| 977 | other internationalization variables. | |
| 978 | .TP 7 | |
| 979 | \fILC_COLLATE\fP | |
| 980 | .sp | |
| 981 | Determine the locale for the behavior of ranges, equivalence classes, | |
| 982 | and multi-character collating elements used in the pattern | |
| 983 | matching expressions for the \fIpattern\fP operand, the basic regular | |
| 984 | expression for the \fB-s\fP option, and the extended | |
| 985 | regular expression defined for the \fByesexpr\fP locale keyword in | |
| 986 | the \fILC_MESSAGES\fP category. | |
| 987 | .TP 7 | |
| 988 | \fILC_CTYPE\fP | |
| 989 | Determine the locale for the interpretation of sequences of bytes | |
| 990 | of text data as characters (for example, single-byte as | |
| 991 | opposed to multi-byte characters in arguments and input files), the | |
| 992 | behavior of character classes used in the extended regular | |
| 993 | expression defined for the \fByesexpr\fP locale keyword in the \fILC_MESSAGES\fP | |
| 994 | category, and pattern matching. | |
| 995 | .TP 7 | |
| 996 | \fILC_MESSAGES\fP | |
| 997 | Determine the locale for the processing of affirmative responses that | |
| 998 | should be used to affect the format and contents of | |
| 999 | diagnostic messages written to standard error. | |
| 1000 | .TP 7 | |
| 1001 | \fILC_TIME\fP | |
| 1002 | Determine the format and contents of date and time strings when the | |
| 1003 | \fB-v\fP option is specified. | |
| 1004 | .TP 7 | |
| 1005 | \fINLSPATH\fP | |
| 1006 | Determine the location of message catalogs for the processing of \fILC_MESSAGES | |
| 1007 | \&.\fP | |
| 1008 | .TP 7 | |
| 1009 | \fITMPDIR\fP | |
| 1010 | Determine the pathname that provides part of the default global extended | |
| 1011 | header record file, as described for the \fB-o\fP | |
| 1012 | \fBglobexthdr=\fP keyword in the OPTIONS section. | |
| 1013 | .TP 7 | |
| 1014 | \fITZ\fP | |
| 1015 | Determine the timezone used to calculate date and time strings when | |
| 1016 | the \fB-v\fP option is specified. If \fITZ\fP is unset or | |
| 1017 | null, an unspecified default timezone shall be used. | |
| 1018 | .sp | |
| 1019 | .SH ASYNCHRONOUS EVENTS | |
| 1020 | .LP | |
| 1021 | Default. | |
| 1022 | .SH STDOUT | |
| 1023 | .LP | |
| 1024 | In \fBwrite\fP mode, if \fB-f\fP is not specified, the standard output | |
| 1025 | shall be the archive formatted according to one of the | |
| 1026 | specifications in the EXTENDED DESCRIPTION section, or some other | |
| 1027 | implementation-defined format (see \fB-x\fP \fIformat\fP). | |
| 1028 | .LP | |
| 1029 | In \fBlist\fP mode, when the \fB-o\fP \fBlistopt\fP= \fIformat\fP | |
| 1030 | has been specified, the selected archive members shall be | |
| 1031 | written to standard output using the format described under List Mode | |
| 1032 | Format Specifications . In | |
| 1033 | \fBlist\fP mode without the \fB-o\fP \fBlistopt\fP= \fIformat\fP option, | |
| 1034 | the table of contents of the selected archive members | |
| 1035 | shall be written to standard output using the following format: | |
| 1036 | .sp | |
| 1037 | .RS | |
| 1038 | .nf | |
| 1039 | ||
| 1040 | \fB"%s\\n", <\fP\fIpathname\fP\fB> | |
| 1041 | \fP | |
| 1042 | .fi | |
| 1043 | .RE | |
| 1044 | .LP | |
| 1045 | If the \fB-v\fP option is specified in \fBlist\fP mode, the table | |
| 1046 | of contents of the selected archive members shall be written | |
| 1047 | to standard output using the following formats. | |
| 1048 | .LP | |
| 1049 | For pathnames representing hard links to previous members of the archive: | |
| 1050 | .sp | |
| 1051 | .RS | |
| 1052 | .nf | |
| 1053 | ||
| 1054 | \fB"%s == %s\\n", <\fP\fIls\fP \fB-l\fP \fIlisting\fP\fB>, <\fP\fIlinkname\fP\fB> | |
| 1055 | \fP | |
| 1056 | .fi | |
| 1057 | .RE | |
| 1058 | .LP | |
| 1059 | For all other pathnames: | |
| 1060 | .sp | |
| 1061 | .RS | |
| 1062 | .nf | |
| 1063 | ||
| 1064 | \fB"%s\\n", <\fP\fIls\fP \fB-l\fP \fIlisting\fP\fB> | |
| 1065 | \fP | |
| 1066 | .fi | |
| 1067 | .RE | |
| 1068 | .LP | |
| 1069 | where <\fIls\ \fP -l\ \fIlisting\fP> shall be the format specified | |
| 1070 | by the \fIls\fP utility with the \fB-l\fP option. When writing pathnames | |
| 1071 | in this format, it is unspecified | |
| 1072 | what is written for fields for which the underlying archive format | |
| 1073 | does not have the correct information, although the correct | |
| 1074 | number of <blank>-separated fields shall be written. | |
| 1075 | .LP | |
| 1076 | In \fBlist\fP mode, standard output shall not be buffered more than | |
| 1077 | a line at a time. | |
| 1078 | .SH STDERR | |
| 1079 | .LP | |
| 1080 | If \fB-v\fP is specified in \fBread\fP, \fBwrite\fP, or \fBcopy\fP | |
| 1081 | modes, \fIpax\fP shall write the pathnames it processes | |
| 1082 | to the standard error output using the following format: | |
| 1083 | .sp | |
| 1084 | .RS | |
| 1085 | .nf | |
| 1086 | ||
| 1087 | \fB"%s\\n", <\fP\fIpathname\fP\fB> | |
| 1088 | \fP | |
| 1089 | .fi | |
| 1090 | .RE | |
| 1091 | .LP | |
| 1092 | These pathnames shall be written as soon as processing is begun on | |
| 1093 | the file or archive member, and shall be flushed to standard | |
| 1094 | error. The trailing <newline>, which shall not be buffered, is written | |
| 1095 | when the file has been read or written. | |
| 1096 | .LP | |
| 1097 | If the \fB-s\fP option is specified, and the replacement string has | |
| 1098 | a trailing \fB'p'\fP , substitutions shall be written to | |
| 1099 | standard error in the following format: | |
| 1100 | .sp | |
| 1101 | .RS | |
| 1102 | .nf | |
| 1103 | ||
| 1104 | \fB"%s >> %s\\n", <\fP\fIoriginal pathname\fP\fB>, <\fP\fInew pathname\fP\fB> | |
| 1105 | \fP | |
| 1106 | .fi | |
| 1107 | .RE | |
| 1108 | .LP | |
| 1109 | In all operating modes of \fIpax\fP, optional messages of unspecified | |
| 1110 | format concerning the input archive format and volume | |
| 1111 | number, the number of files, blocks, volumes, and media parts as well | |
| 1112 | as other diagnostic messages may be written to standard | |
| 1113 | error. | |
| 1114 | .LP | |
| 1115 | In all formats, for both standard output and standard error, it is | |
| 1116 | unspecified how non-printable characters in pathnames or link | |
| 1117 | names are written. | |
| 1118 | .LP | |
| 1119 | When \fIpax\fP is in \fBread\fP mode or \fBlist\fP mode, using the | |
| 1120 | \fB-x\fP \fBpax\fP archive format, and a filename, link | |
| 1121 | name, owner name, or any other field in an extended header record | |
| 1122 | cannot be translated from the \fBpax\fP UTF-8 codeset format to | |
| 1123 | the codeset and current locale of the implementation, \fIpax\fP shall | |
| 1124 | write a diagnostic message to standard error, shall process | |
| 1125 | the file as described for the \fB-o\fP \fBinvalid=\fP option, and | |
| 1126 | then shall process the next file in the archive. | |
| 1127 | .SH OUTPUT FILES | |
| 1128 | .LP | |
| 1129 | In \fBread\fP mode, the extracted output files shall be of the archived | |
| 1130 | file type. In \fBcopy\fP mode, the copied output files | |
| 1131 | shall be the type of the file being copied. In either mode, existing | |
| 1132 | files in the destination hierarchy shall be overwritten only | |
| 1133 | when all permission ( \fB-p\fP), modification time ( \fB-u\fP), and | |
| 1134 | invalid-value ( \fB-o\fP \fBinvalid\fP=) tests allow | |
| 1135 | it. | |
| 1136 | .LP | |
| 1137 | In \fBwrite\fP mode, the output file named by the \fB-f\fP option-argument | |
| 1138 | shall be a file formatted according to one of the | |
| 1139 | specifications in the EXTENDED DESCRIPTION section, or some other | |
| 1140 | implementation-defined format. | |
| 1141 | .SH EXTENDED DESCRIPTION | |
| 1142 | .SS pax Interchange Format | |
| 1143 | .LP | |
| 1144 | A \fIpax\fP archive tape or file produced in the \fB-x\fP \fBpax\fP | |
| 1145 | format shall contain a series of blocks. The physical | |
| 1146 | layout of the archive shall be identical to the \fBustar\fP format | |
| 1147 | described in ustar Interchange | |
| 1148 | Format . Each file archived shall be represented by the following | |
| 1149 | sequence: | |
| 1150 | .IP " *" 3 | |
| 1151 | An optional header block with extended header records. This header | |
| 1152 | block is of the form described in pax Header Block , with a \fItypeflag\fP | |
| 1153 | value of \fBx\fP or \fBg\fP. The extended header records, | |
| 1154 | described in pax Extended Header , shall be included as the data for | |
| 1155 | this header block. | |
| 1156 | .LP | |
| 1157 | .IP " *" 3 | |
| 1158 | A header block that describes the file. Any fields in the preceding | |
| 1159 | optional extended header shall override the associated | |
| 1160 | fields in this header block for this file. | |
| 1161 | .LP | |
| 1162 | .IP " *" 3 | |
| 1163 | Zero or more blocks that contain the contents of the file. | |
| 1164 | .LP | |
| 1165 | .LP | |
| 1166 | At the end of the archive file there shall be two 512-byte blocks | |
| 1167 | filled with binary zeros, interpreted as an end-of-archive | |
| 1168 | indicator. | |
| 1169 | .LP | |
| 1170 | A schematic of an example archive with global extended header records | |
| 1171 | and two actual files is shown in pax | |
| 1172 | Format Archive Example . In the example, the second file in the archive | |
| 1173 | has no extended header preceding it, presumably because | |
| 1174 | it has no need for extended attributes. | |
| 1175 | .TP 7 | |
| 1176 | .sp | |
| 1177 | .RS | |
| 1178 | \fBFigure: pax Format Archive Example\fP | |
| 1179 | .RE | |
| 1180 | .SS pax Header Block | |
| 1181 | .LP | |
| 1182 | The \fBpax\fP header block shall be identical to the \fBustar\fP header | |
| 1183 | block described in ustar | |
| 1184 | Interchange Format , except that two additional \fItypeflag\fP values | |
| 1185 | are defined: | |
| 1186 | .TP 7 | |
| 1187 | \fBx\fP | |
| 1188 | Represents extended header records for the following file in the archive | |
| 1189 | (which shall have its own \fBustar\fP header block). | |
| 1190 | The format of these extended header records shall be as described | |
| 1191 | in pax Extended Header . | |
| 1192 | .TP 7 | |
| 1193 | \fBg\fP | |
| 1194 | Represents global extended header records for the following files | |
| 1195 | in the archive. The format of these extended header records | |
| 1196 | shall be as described in pax Extended Header . Each value shall affect | |
| 1197 | all subsequent files that do | |
| 1198 | not override that value in their own extended header record and until | |
| 1199 | another global extended header record is reached that | |
| 1200 | provides another value for the same field. The \fItypeflag\fP \fBg\fP | |
| 1201 | global headers should not be used with interchange media | |
| 1202 | that could suffer partial data loss in transporting the archive. | |
| 1203 | .sp | |
| 1204 | .LP | |
| 1205 | For both of these types, the \fIsize\fP field shall be the size of | |
| 1206 | the extended header records in octets. The other fields in | |
| 1207 | the header block are not meaningful to this version of the \fIpax\fP | |
| 1208 | utility. However, if this archive is read by a \fIpax\fP | |
| 1209 | utility conforming to the ISO\ POSIX-2:1993 standard, the header block | |
| 1210 | fields are used to create a regular file that contains | |
| 1211 | the extended header records as data. Therefore, header block field | |
| 1212 | values should be selected to provide reasonable file access to | |
| 1213 | this regular file. | |
| 1214 | .LP | |
| 1215 | A further difference from the \fBustar\fP header block is that data | |
| 1216 | blocks for files of \fItypeflag\fP 1 (the digit one) (hard | |
| 1217 | link) may be included, which means that the size field may be greater | |
| 1218 | than zero. Archives created by \fIpax\fP \fB-o\fP | |
| 1219 | \fBlinkdata\fP shall include these data blocks with the hard links. | |
| 1220 | .SS pax Extended Header | |
| 1221 | .LP | |
| 1222 | A \fBpax\fP extended header contains values that are inappropriate | |
| 1223 | for the \fBustar\fP header block because of limitations in | |
| 1224 | that format: fields requiring a character encoding other than that | |
| 1225 | described in the ISO/IEC\ 646:1991 standard, fields | |
| 1226 | representing file attributes not described in the \fBustar\fP header, | |
| 1227 | and fields whose format or length do not fit the | |
| 1228 | requirements of the \fBustar\fP header. The values in an extended | |
| 1229 | header add attributes to the following file (or files; see the | |
| 1230 | description of the \fItypeflag\fP \fBg\fP header block) or override | |
| 1231 | values in the following header block(s), as indicated in the | |
| 1232 | following list of keywords. | |
| 1233 | .LP | |
| 1234 | An extended header shall consist of one or more records, each constructed | |
| 1235 | as follows: | |
| 1236 | .sp | |
| 1237 | .RS | |
| 1238 | .nf | |
| 1239 | ||
| 1240 | \fB"%d %s=%s\\n", <\fP\fIlength\fP\fB>, <\fP\fIkeyword\fP\fB>, <\fP\fIvalue\fP\fB> | |
| 1241 | \fP | |
| 1242 | .fi | |
| 1243 | .RE | |
| 1244 | .LP | |
| 1245 | The extended header records shall be encoded according to the ISO/IEC\ 10646-1:2000 | |
| 1246 | standard (UTF-8). The | |
| 1247 | <\fIlength\fP> field, <blank>, equals sign, and <newline> shown shall | |
| 1248 | be limited to the portable character set, | |
| 1249 | as encoded in UTF-8. The <\fIkeyword\fP> and <\fIvalue\fP> fields | |
| 1250 | can be any UTF-8 characters. The | |
| 1251 | <\fIlength\fP> field shall be the decimal length of the extended header | |
| 1252 | record in octets, including the trailing | |
| 1253 | <newline>. | |
| 1254 | .LP | |
| 1255 | The <\fIkeyword\fP> field shall be one of the entries from the following | |
| 1256 | list or a keyword provided as an implementation | |
| 1257 | extension. Keywords consisting entirely of lowercase letters, digits, | |
| 1258 | and periods are reserved for future standardization. A | |
| 1259 | keyword shall not include an equals sign. (In the following list, | |
| 1260 | the notations "file(s)" or "block(s)" is used to acknowledge | |
| 1261 | that a keyword affects the following single file after a \fItypeflag\fP | |
| 1262 | \fBx\fP extended header, but possibly multiple files | |
| 1263 | after \fItypeflag\fP \fBg\fP. Any requirements in the list for \fIpax\fP | |
| 1264 | to include a record when in \fBwrite\fP or \fBcopy\fP | |
| 1265 | mode shall apply only when such a record has not already been provided | |
| 1266 | through the use of the \fB-o\fP option. When used in | |
| 1267 | \fBcopy\fP mode, \fIpax\fP shall behave as if an archive had been | |
| 1268 | created with applicable extended header records and then | |
| 1269 | extracted.) | |
| 1270 | .TP 7 | |
| 1271 | \fBatime\fP | |
| 1272 | The file access time for the following file(s), equivalent to the | |
| 1273 | value of the \fIst_atime\fP member of the \fBstat\fP | |
| 1274 | structure for a file, as described by the \fIstat\fP() function. The | |
| 1275 | access time shall be | |
| 1276 | restored if the process has the appropriate privilege required to | |
| 1277 | do so. The format of the <\fIvalue\fP> shall be as | |
| 1278 | described in pax Extended Header File Times . | |
| 1279 | .TP 7 | |
| 1280 | \fBcharset\fP | |
| 1281 | The name of the character set used to encode the data in the following | |
| 1282 | file(s). The entries in the following table are defined | |
| 1283 | to refer to known standards; additional names may be agreed on between | |
| 1284 | the originator and recipient. | |
| 1285 | .TS C | |
| 1286 | center; l2 l. | |
| 1287 | \fB<value>\fP \fBFormal Standard\fP | |
| 1288 | ISO-IR 646 1990 ISO/IEC 646:1990 | |
| 1289 | ISO-IR 8859 1 1998 ISO/IEC 8859-1:1998 | |
| 1290 | ISO-IR 8859 2 1999 ISO/IEC 8859-2:1999 | |
| 1291 | ISO-IR 8859 3 1999 ISO/IEC 8859-3:1999 | |
| 1292 | ISO-IR 8859 4 1998 ISO/IEC 8859-4:1998 | |
| 1293 | ISO-IR 8859 5 1999 ISO/IEC 8859-5:1999 | |
| 1294 | ISO-IR 8859 6 1999 ISO/IEC 8859-6:1999 | |
| 1295 | ISO-IR 8859 7 1987 ISO/IEC 8859-7:1987 | |
| 1296 | ISO-IR 8859 8 1999 ISO/IEC 8859-8:1999 | |
| 1297 | ISO-IR 8859 9 1999 ISO/IEC 8859-9:1999 | |
| 1298 | ISO-IR 8859 10 1998 ISO/IEC 8859-10:1998 | |
| 1299 | ISO-IR 8859 13 1998 ISO/IEC 8859-13:1998 | |
| 1300 | ISO-IR 8859 14 1998 ISO/IEC 8859-14:1998 | |
| 1301 | ISO-IR 8859 15 1999 ISO/IEC 8859-15:1999 | |
| 1302 | ISO-IR 10646 2000 ISO/IEC 10646:2000 | |
| 1303 | ISO-IR 10646 2000 UTF-8 ISO/IEC 10646, UTF-8 encoding | |
| 1304 | BINARY None. | |
| 1305 | .TE | |
| 1306 | .LP | |
| 1307 | The encoding is included in an extended header for information only; | |
| 1308 | when \fIpax\fP is used as described in | |
| 1309 | IEEE\ Std\ 1003.1-2001, it shall not translate the file data into | |
| 1310 | any other encoding. The \fBBINARY\fP entry indicates | |
| 1311 | unencoded binary data. | |
| 1312 | .LP | |
| 1313 | When used in \fBwrite\fP or \fBcopy\fP mode, it is implementation-defined | |
| 1314 | whether \fIpax\fP includes a \fBcharset\fP | |
| 1315 | extended header record for a file. | |
| 1316 | .TP 7 | |
| 1317 | \fBcomment\fP | |
| 1318 | A series of characters used as a comment. All characters in the <\fIvalue\fP> | |
| 1319 | field shall be ignored by \fIpax\fP. | |
| 1320 | .TP 7 | |
| 1321 | \fBctime\fP | |
| 1322 | The file creation time for the following file(s), equivalent to the | |
| 1323 | value of the \fIst_ctime\fP member of the \fBstat\fP | |
| 1324 | structure for a file, as described by the \fIstat\fP() function. The | |
| 1325 | creation time shall be | |
| 1326 | restored if the process has the appropriate privilege required to | |
| 1327 | do so. The format of the <\fIvalue\fP> shall be as | |
| 1328 | described in pax Extended Header File Times . | |
| 1329 | .TP 7 | |
| 1330 | \fBgid\fP | |
| 1331 | The group ID of the group that owns the file, expressed as a decimal | |
| 1332 | number using digits from the ISO/IEC\ 646:1991 | |
| 1333 | standard. This record shall override the \fIgid\fP field in the following | |
| 1334 | header block(s). When used in \fBwrite\fP or | |
| 1335 | \fBcopy\fP mode, \fIpax\fP shall include a \fIgid\fP extended header | |
| 1336 | record for each file whose group ID is greater than 2097151 | |
| 1337 | (octal 7777777). | |
| 1338 | .TP 7 | |
| 1339 | \fBgname\fP | |
| 1340 | The group of the file(s), formatted as a group name in the group database. | |
| 1341 | This record shall override the \fIgid\fP and | |
| 1342 | \fIgname\fP fields in the following header block(s), and any \fIgid\fP | |
| 1343 | extended header record. When used in \fBread\fP, | |
| 1344 | \fBcopy\fP, or \fBlist\fP mode, \fIpax\fP shall translate the name | |
| 1345 | from the UTF-8 encoding in the header record to the character | |
| 1346 | set appropriate for the group database on the receiving system. If | |
| 1347 | any of the UTF-8 characters cannot be translated, and if the | |
| 1348 | \fB-o\fP \fBinvalid=\fP UTF-8 option is not specified, the results | |
| 1349 | are implementation-defined. When used in \fBwrite\fP or | |
| 1350 | \fBcopy\fP mode, \fIpax\fP shall include a \fBgname\fP extended header | |
| 1351 | record for each file whose group name cannot be | |
| 1352 | represented entirely with the letters and digits of the portable character | |
| 1353 | set. | |
| 1354 | .TP 7 | |
| 1355 | \fBlinkpath\fP | |
| 1356 | The pathname of a link being created to another file, of any type, | |
| 1357 | previously archived. This record shall override the | |
| 1358 | \fIlinkname\fP field in the following \fBustar\fP header block(s). | |
| 1359 | The following \fBustar\fP header block shall determine the | |
| 1360 | type of link created. If \fItypeflag\fP of the following header block | |
| 1361 | is 1, it shall be a hard link. If \fItypeflag\fP is 2, it | |
| 1362 | shall be a symbolic link and the \fBlinkpath\fP value shall be the | |
| 1363 | contents of the symbolic link. The \fIpax\fP utility shall | |
| 1364 | translate the name of the link (contents of the symbolic link) from | |
| 1365 | the UTF-8 encoding to the character set appropriate for the | |
| 1366 | local file system. When used in \fBwrite\fP or \fBcopy\fP mode, \fIpax\fP | |
| 1367 | shall include a \fBlinkpath\fP extended header record | |
| 1368 | for each link whose pathname cannot be represented entirely with the | |
| 1369 | members of the portable character set other than NUL. | |
| 1370 | .TP 7 | |
| 1371 | \fBmtime\fP | |
| 1372 | The file modification time of the following file(s), equivalent to | |
| 1373 | the value of the \fIst_mtime\fP member of the \fBstat\fP | |
| 1374 | structure for a file, as described in the \fIstat\fP() function. This | |
| 1375 | record shall override | |
| 1376 | the \fImtime\fP field in the following header block(s). The modification | |
| 1377 | time shall be restored if the process has the appropriate | |
| 1378 | privilege required to do so. The format of the <\fIvalue\fP> shall | |
| 1379 | be as described in pax | |
| 1380 | Extended Header File Times . | |
| 1381 | .TP 7 | |
| 1382 | \fBpath\fP | |
| 1383 | The pathname of the following file(s). This record shall override | |
| 1384 | the \fIname\fP and \fIprefix\fP fields in the following | |
| 1385 | header block(s). The \fIpax\fP utility shall translate the pathname | |
| 1386 | of the file from the UTF-8 encoding to the character set | |
| 1387 | appropriate for the local file system. | |
| 1388 | .LP | |
| 1389 | When used in \fBwrite\fP or \fBcopy\fP mode, \fIpax\fP shall include | |
| 1390 | a \fIpath\fP extended header record for each file whose | |
| 1391 | pathname cannot be represented entirely with the members of the portable | |
| 1392 | character set other than NUL. | |
| 1393 | .TP 7 | |
| 1394 | \fBrealtime.\fP\fIany\fP | |
| 1395 | The keywords prefixed by "realtime." are reserved for future standardization. | |
| 1396 | .TP 7 | |
| 1397 | \fBsecurity.\fP\fIany\fP | |
| 1398 | The keywords prefixed by "security." are reserved for future standardization. | |
| 1399 | .TP 7 | |
| 1400 | \fBsize\fP | |
| 1401 | The size of the file in octets, expressed as a decimal number using | |
| 1402 | digits from the ISO/IEC\ 646:1991 standard. This record | |
| 1403 | shall override the \fIsize\fP field in the following header block(s). | |
| 1404 | When used in \fBwrite\fP or \fBcopy\fP mode, \fIpax\fP | |
| 1405 | shall include a \fIsize\fP extended header record for each file with | |
| 1406 | a size value greater than 8589934591 (octal | |
| 1407 | 77777777777). | |
| 1408 | .TP 7 | |
| 1409 | \fBuid\fP | |
| 1410 | The user ID of the file owner, expressed as a decimal number using | |
| 1411 | digits from the ISO/IEC\ 646:1991 standard. This record | |
| 1412 | shall override the \fIuid\fP field in the following header block(s). | |
| 1413 | When used in \fBwrite\fP or \fBcopy\fP mode, \fIpax\fP | |
| 1414 | shall include a \fIuid\fP extended header record for each file whose | |
| 1415 | owner ID is greater than 2097151 (octal 7777777). | |
| 1416 | .TP 7 | |
| 1417 | \fBuname\fP | |
| 1418 | The owner of the following file(s), formatted as a user name in the | |
| 1419 | user database. This record shall override the \fIuid\fP | |
| 1420 | and \fIuname\fP fields in the following header block(s), and any \fIuid\fP | |
| 1421 | extended header record. When used in \fBread\fP, | |
| 1422 | \fBcopy\fP, or \fBlist\fP mode, \fIpax\fP shall translate the name | |
| 1423 | from the UTF-8 encoding in the header record to the character | |
| 1424 | set appropriate for the user database on the receiving system. If | |
| 1425 | any of the UTF-8 characters cannot be translated, and if the | |
| 1426 | \fB-o\fP \fBinvalid=\fP UTF-8 option is not specified, the results | |
| 1427 | are implementation-defined. When used in \fBwrite\fP or | |
| 1428 | \fBcopy\fP mode, \fIpax\fP shall include a \fBuname\fP extended header | |
| 1429 | record for each file whose user name cannot be | |
| 1430 | represented entirely with the letters and digits of the portable character | |
| 1431 | set. | |
| 1432 | .sp | |
| 1433 | .LP | |
| 1434 | If the <\fIvalue\fP> field is zero length, it shall delete any header | |
| 1435 | block field, previously entered extended header | |
| 1436 | value, or global extended header value of the same name. | |
| 1437 | .LP | |
| 1438 | If a keyword in an extended header record (or in a \fB-o\fP option-argument) | |
| 1439 | overrides or deletes a corresponding field in the | |
| 1440 | \fBustar\fP header block, \fIpax\fP shall ignore the contents of that | |
| 1441 | header block field. | |
| 1442 | .LP | |
| 1443 | Unlike the \fBustar\fP header block fields, NULs shall not delimit | |
| 1444 | <\fIvalue\fP>s; all characters within the | |
| 1445 | <\fIvalue\fP> field shall be considered data for the field. None of | |
| 1446 | the length limitations of the \fBustar\fP header block | |
| 1447 | fields in ustar Header Block shall apply to the extended header records. | |
| 1448 | .SS pax Extended Header Keyword Precedence | |
| 1449 | .LP | |
| 1450 | This section describes the precedence in which the various header | |
| 1451 | records and fields and command line options are selected to | |
| 1452 | apply to a file in the archive. When \fIpax\fP is used in \fBread\fP | |
| 1453 | or \fBlist\fP modes, it shall determine a file attribute in | |
| 1454 | the following sequence: | |
| 1455 | .IP " 1." 4 | |
| 1456 | If \fB-o\fP \fBdelete=\fP \fIkeyword-prefix\fP is used, the affected | |
| 1457 | attributes shall be determined from step 7., if | |
| 1458 | applicable, or ignored otherwise. | |
| 1459 | .LP | |
| 1460 | .IP " 2." 4 | |
| 1461 | If \fB-o\fP \fIkeyword\fP:= is used, the affected attributes shall | |
| 1462 | be ignored. | |
| 1463 | .LP | |
| 1464 | .IP " 3." 4 | |
| 1465 | If \fB-o\fP \fIkeyword\fP \fB:=\fP \fIvalue\fP is used, the affected | |
| 1466 | attribute shall be assigned the value. | |
| 1467 | .LP | |
| 1468 | .IP " 4." 4 | |
| 1469 | If there is a \fItypeflag\fP \fBx\fP extended header record, the affected | |
| 1470 | attribute shall be assigned the | |
| 1471 | <\fIvalue\fP>. When extended header records conflict, the last one | |
| 1472 | given in the header shall take precedence. | |
| 1473 | .LP | |
| 1474 | .IP " 5." 4 | |
| 1475 | If \fB-o\fP \fIkeyword\fP \fB=\fP \fIvalue\fP is used, the affected | |
| 1476 | attribute shall be assigned the value. | |
| 1477 | .LP | |
| 1478 | .IP " 6." 4 | |
| 1479 | If there is a \fItypeflag\fP \fBg\fP global extended header record, | |
| 1480 | the affected attribute shall be assigned the | |
| 1481 | <\fIvalue\fP>. When global extended header records conflict, the last | |
| 1482 | one given in the global header shall take | |
| 1483 | precedence. | |
| 1484 | .LP | |
| 1485 | .IP " 7." 4 | |
| 1486 | Otherwise, the attribute shall be determined from the \fBustar\fP | |
| 1487 | header block. | |
| 1488 | .LP | |
| 1489 | .SS pax Extended Header File Times | |
| 1490 | .LP | |
| 1491 | The \fIpax\fP utility shall write an \fBmtime\fP record for each file | |
| 1492 | in \fBwrite\fP or \fBcopy\fP modes if the file's | |
| 1493 | modification time cannot be represented exactly in the \fBustar\fP | |
| 1494 | header logical record described in ustar Interchange Format . This | |
| 1495 | can occur if the time is out of \fBustar\fP range, or if the file | |
| 1496 | system | |
| 1497 | of the underlying implementation supports non-integer time granularities | |
| 1498 | and the time is not an integer. All of these time records | |
| 1499 | shall be formatted as a decimal representation of the time in seconds | |
| 1500 | since the Epoch. If a period ( \fB'.'\fP ) decimal point | |
| 1501 | character is present, the digits to the right of the point shall represent | |
| 1502 | the units of a subsecond timing granularity, where the | |
| 1503 | first digit is tenths of a second and each subsequent digit is a tenth | |
| 1504 | of the previous digit. In \fBread\fP or \fBcopy\fP mode, | |
| 1505 | the \fIpax\fP utility shall truncate the time of a file to the greatest | |
| 1506 | value that is not greater than the input header file time. | |
| 1507 | In \fBwrite\fP or \fBcopy\fP mode, the \fIpax\fP utility shall output | |
| 1508 | a time exactly if it can be represented exactly as a | |
| 1509 | decimal number, and otherwise shall generate only enough digits so | |
| 1510 | that the same time shall be recovered if the file is extracted | |
| 1511 | on a system whose underlying implementation supports the same time | |
| 1512 | granularity. | |
| 1513 | .SS ustar Interchange Format | |
| 1514 | .LP | |
| 1515 | A \fBustar\fP archive tape or file shall contain a series of logical | |
| 1516 | records. Each logical record shall be a fixed-size logical | |
| 1517 | record of 512 octets (see below). Although this format may be thought | |
| 1518 | of as being stored on 9-track industry-standard 12.7 mm (0.5 | |
| 1519 | in) magnetic tape, other types of transportable media are not excluded. | |
| 1520 | Each file archived shall be represented by a header logical | |
| 1521 | record that describes the file, followed by zero or more logical records | |
| 1522 | that give the contents of the file. At the end of the | |
| 1523 | archive file there shall be two 512-octet logical records filled with | |
| 1524 | binary zeros, interpreted as an end-of-archive indicator. | |
| 1525 | .LP | |
| 1526 | The logical records may be grouped for physical I/O operations, as | |
| 1527 | described under the \fB-b\fP \fIblocksize\fP and \fB-x\fP | |
| 1528 | \fBustar\fP options. Each group of logical records may be written | |
| 1529 | with a single operation equivalent to the \fIwrite\fP() function. | |
| 1530 | On magnetic tape, the result of this write shall be a single tape | |
| 1531 | physical | |
| 1532 | block. The last physical block shall always be the full size, so logical | |
| 1533 | records after the two zero logical records may contain | |
| 1534 | undefined data. | |
| 1535 | .LP | |
| 1536 | The header logical record shall be structured as shown in the following | |
| 1537 | table. All lengths and offsets are in decimal. | |
| 1538 | .br | |
| 1539 | .sp | |
| 1540 | .RS | |
| 1541 | \fBTable: ustar Header Block\fP | |
| 1542 | .TS C | |
| 1543 | center; l l l. | |
| 1544 | \fBField Name\fP \fBOctet Offset\fP \fBLength (in Octets)\fP | |
| 1545 | \fIname\fP 0 100 | |
| 1546 | \fImode\fP 100 8 | |
| 1547 | \fIuid\fP 108 8 | |
| 1548 | \fIgid\fP 116 8 | |
| 1549 | \fIsize\fP 124 12 | |
| 1550 | \fImtime\fP 136 12 | |
| 1551 | \fIchksum\fP 148 8 | |
| 1552 | \fItypeflag\fP 156 1 | |
| 1553 | \fIlinkname\fP 157 100 | |
| 1554 | \fImagic\fP 257 6 | |
| 1555 | \fIversion\fP 263 2 | |
| 1556 | \fIuname\fP 265 32 | |
| 1557 | \fIgname\fP 297 32 | |
| 1558 | \fIdevmajor\fP 329 8 | |
| 1559 | \fIdevminor\fP 337 8 | |
| 1560 | \fIprefix\fP 345 155 | |
| 1561 | .TE | |
| 1562 | .RE | |
| 1563 | .LP | |
| 1564 | All characters in the header logical record shall be represented in | |
| 1565 | the coded character set of the ISO/IEC\ 646:1991 | |
| 1566 | standard. For maximum portability between implementations, names should | |
| 1567 | be selected from characters represented by the portable | |
| 1568 | filename character set as octets with the most significant bit zero. | |
| 1569 | If an implementation supports the use of characters outside of | |
| 1570 | slash and the portable filename character set in names for files, | |
| 1571 | users, and groups, one or more implementation-defined encodings | |
| 1572 | of these characters shall be provided for interchange purposes. | |
| 1573 | .LP | |
| 1574 | However, the \fIpax\fP utility shall never create filenames on the | |
| 1575 | local system that cannot be accessed via the procedures | |
| 1576 | described in IEEE\ Std\ 1003.1-2001. If a filename is found on the | |
| 1577 | medium that would create an invalid filename, it is | |
| 1578 | implementation-defined whether the data from the file is stored on | |
| 1579 | the file hierarchy and under what name it is stored. The | |
| 1580 | \fIpax\fP utility may choose to ignore these files as long as it produces | |
| 1581 | an error indicating that the file is being ignored. | |
| 1582 | .LP | |
| 1583 | Each field within the header logical record is contiguous; that is, | |
| 1584 | there is no padding used. Each character on the archive | |
| 1585 | medium shall be stored contiguously. | |
| 1586 | .LP | |
| 1587 | The fields \fImagic\fP, \fIuname\fP, and \fIgname\fP are character | |
| 1588 | strings each terminated by a NUL character. The fields | |
| 1589 | \fIname\fP, \fIlinkname\fP, and \fIprefix\fP are NUL-terminated character | |
| 1590 | strings except when all characters in the array | |
| 1591 | contain non-NUL characters including the last character. The \fIversion\fP | |
| 1592 | field is two octets containing the characters | |
| 1593 | \fB"00"\fP (zero-zero). The \fItypeflag\fP contains a single character. | |
| 1594 | All other fields are leading zero-filled octal numbers | |
| 1595 | using digits from the ISO/IEC\ 646:1991 standard IRV. Each numeric | |
| 1596 | field is terminated by one or more <space> or NUL | |
| 1597 | characters. | |
| 1598 | .LP | |
| 1599 | The \fIname\fP and the \fIprefix\fP fields shall produce the pathname | |
| 1600 | of the file. A new pathname shall be formed, if | |
| 1601 | \fIprefix\fP is not an empty string (its first character is not NUL), | |
| 1602 | by concatenating \fIprefix\fP (up to the first NUL | |
| 1603 | character), a slash character, and \fIname\fP; otherwise, \fIname\fP | |
| 1604 | is used alone. In either case, \fIname\fP is terminated at | |
| 1605 | the first NUL character. If \fIprefix\fP begins with a NUL character, | |
| 1606 | it shall be ignored. In this manner, pathnames of at most | |
| 1607 | 256 characters can be supported. If a pathname does not fit in the | |
| 1608 | space provided, \fIpax\fP shall notify the user of the error, | |
| 1609 | and shall not store any part of the file-header or data-on the medium. | |
| 1610 | .LP | |
| 1611 | The \fIlinkname\fP field, described below, shall not use the \fIprefix\fP | |
| 1612 | to produce a pathname. As such, a \fIlinkname\fP is | |
| 1613 | limited to 100 characters. If the name does not fit in the space provided, | |
| 1614 | \fIpax\fP shall notify the user of the error, and shall | |
| 1615 | not attempt to store the link on the medium. | |
| 1616 | .LP | |
| 1617 | The \fImode\fP field provides 12 bits encoded in the ISO/IEC\ 646:1991 | |
| 1618 | standard octal digit representation. The encoded | |
| 1619 | bits shall represent the following values: | |
| 1620 | .br | |
| 1621 | .sp | |
| 1622 | .RS | |
| 1623 | \fBTable: ustar \fImode\fP Field\fP | |
| 1624 | .TS C | |
| 1625 | center; l1 l1 lw(37). | |
| 1626 | \fBBit Value\fP \fBIEEE\ Std\ 1003.1-2001 Bit\fP T{ | |
| 1627 | .na | |
| 1628 | \fBDescription\fP | |
| 1629 | .ad | |
| 1630 | T} | |
| 1631 | 04000 S_ISUID T{ | |
| 1632 | .na | |
| 1633 | Set UID on execution. | |
| 1634 | .ad | |
| 1635 | T} | |
| 1636 | 02000 S_ISGID T{ | |
| 1637 | .na | |
| 1638 | Set GID on execution. | |
| 1639 | .ad | |
| 1640 | T} | |
| 1641 | 01000 <reserved> T{ | |
| 1642 | .na | |
| 1643 | Reserved for future standardization. | |
| 1644 | .ad | |
| 1645 | T} | |
| 1646 | 00400 S_IRUSR T{ | |
| 1647 | .na | |
| 1648 | Read permission for file owner class. | |
| 1649 | .ad | |
| 1650 | T} | |
| 1651 | 00200 S_IWUSR T{ | |
| 1652 | .na | |
| 1653 | Write permission for file owner class. | |
| 1654 | .ad | |
| 1655 | T} | |
| 1656 | 00100 S_IXUSR T{ | |
| 1657 | .na | |
| 1658 | Execute/search permission for file owner class. | |
| 1659 | .ad | |
| 1660 | T} | |
| 1661 | 00040 S_IRGRP T{ | |
| 1662 | .na | |
| 1663 | Read permission for file group class. | |
| 1664 | .ad | |
| 1665 | T} | |
| 1666 | 00020 S_IWGRP T{ | |
| 1667 | .na | |
| 1668 | Write permission for file group class. | |
| 1669 | .ad | |
| 1670 | T} | |
| 1671 | 00010 S_IXGRP T{ | |
| 1672 | .na | |
| 1673 | Execute/search permission for file group class. | |
| 1674 | .ad | |
| 1675 | T} | |
| 1676 | 00004 S_IROTH T{ | |
| 1677 | .na | |
| 1678 | Read permission for file other class. | |
| 1679 | .ad | |
| 1680 | T} | |
| 1681 | 00002 S_IWOTH T{ | |
| 1682 | .na | |
| 1683 | Write permission for file other class. | |
| 1684 | .ad | |
| 1685 | T} | |
| 1686 | 00001 S_IXOTH T{ | |
| 1687 | .na | |
| 1688 | Execute/search permission for file other class. | |
| 1689 | .ad | |
| 1690 | T} | |
| 1691 | .TE | |
| 1692 | .RE | |
| 1693 | .LP | |
| 1694 | When appropriate privilege is required to set one of these mode bits, | |
| 1695 | and the user restoring the files from the archive does not | |
| 1696 | have the appropriate privilege, the mode bits for which the user does | |
| 1697 | not have appropriate privilege shall be ignored. Some of the | |
| 1698 | mode bits in the archive format are not mentioned elsewhere in this | |
| 1699 | volume of IEEE\ Std\ 1003.1-2001. If the implementation | |
| 1700 | does not support those bits, they may be ignored. | |
| 1701 | .LP | |
| 1702 | The \fIuid\fP and \fIgid\fP fields are the user and group ID of the | |
| 1703 | owner and group of the file, respectively. | |
| 1704 | .LP | |
| 1705 | The \fIsize\fP field is the size of the file in octets. If the \fItypeflag\fP | |
| 1706 | field is set to specify a file to be of type 1 | |
| 1707 | (a link) or 2 (a symbolic link), the \fIsize\fP field shall be specified | |
| 1708 | as zero. If the \fItypeflag\fP field is set to specify a | |
| 1709 | file of type 5 (directory), the \fIsize\fP field shall be interpreted | |
| 1710 | as described under the definition of that record type. No | |
| 1711 | data logical records are stored for types 1, 2, or 5. If the \fItypeflag\fP | |
| 1712 | field is set to 3 (character special file), 4 (block | |
| 1713 | special file), or 6 (FIFO), the meaning of the \fIsize\fP field is | |
| 1714 | unspecified by this volume of IEEE\ Std\ 1003.1-2001, | |
| 1715 | and no data logical records shall be stored on the medium. Additionally, | |
| 1716 | for type 6, the \fIsize\fP field shall be ignored when | |
| 1717 | reading. If the \fItypeflag\fP field is set to any other value, the | |
| 1718 | number of logical records written following the header shall | |
| 1719 | be ( \fIsize\fP+511)/512, ignoring any fraction in the result of the | |
| 1720 | division. | |
| 1721 | .LP | |
| 1722 | The \fImtime\fP field shall be the modification time of the file at | |
| 1723 | the time it was archived. It is the ISO/IEC\ 646:1991 | |
| 1724 | standard representation of the octal value of the modification time | |
| 1725 | obtained from the \fIstat\fP() function. | |
| 1726 | .LP | |
| 1727 | The \fIchksum\fP field shall be the ISO/IEC\ 646:1991 standard IRV | |
| 1728 | representation of the octal value of the simple sum of | |
| 1729 | all octets in the header logical record. Each octet in the header | |
| 1730 | shall be treated as an unsigned value. These values shall be | |
| 1731 | added to an unsigned integer, initialized to zero, the precision of | |
| 1732 | which is not less than 17 bits. When calculating the checksum, | |
| 1733 | the \fIchksum\fP field is treated as if it were all spaces. | |
| 1734 | .LP | |
| 1735 | The \fItypeflag\fP field specifies the type of file archived. If a | |
| 1736 | particular implementation does not recognize the type, or | |
| 1737 | the user does not have appropriate privilege to create that type, | |
| 1738 | the file shall be extracted as if it were a regular file if the | |
| 1739 | file type is defined to have a meaning for the \fIsize\fP field that | |
| 1740 | could cause data logical records to be written on the medium | |
| 1741 | (see the previous description for \fIsize\fP). If conversion to a | |
| 1742 | regular file occurs, the \fIpax\fP utility shall produce an | |
| 1743 | error indicating that the conversion took place. All of the \fItypeflag\fP | |
| 1744 | fields shall be coded in the ISO/IEC\ 646:1991 | |
| 1745 | standard IRV: | |
| 1746 | .TP 7 | |
| 1747 | \fB0\fP | |
| 1748 | Represents a regular file. For backwards-compatibility, a \fItypeflag\fP | |
| 1749 | value of binary zero ( \fB'\\0'\fP ) should be | |
| 1750 | recognized as meaning a regular file when extracting files from the | |
| 1751 | archive. Archives written with this version of the archive file | |
| 1752 | format create regular files with a \fItypeflag\fP value of the ISO/IEC\ 646:1991 | |
| 1753 | standard IRV \fB'0'\fP . | |
| 1754 | .TP 7 | |
| 1755 | \fB1\fP | |
| 1756 | Represents a file linked to another file, of any type, previously | |
| 1757 | archived. Such files are identified by each file having the | |
| 1758 | same device and file serial number. The linked-to name is specified | |
| 1759 | in the \fIlinkname\fP field with a NUL-character terminator if | |
| 1760 | it is less than 100 octets in length. | |
| 1761 | .TP 7 | |
| 1762 | \fB2\fP | |
| 1763 | Represents a symbolic link. The contents of the symbolic link shall | |
| 1764 | be stored in the \fIlinkname\fP field. | |
| 1765 | .TP 7 | |
| 1766 | \fB3,4\fP | |
| 1767 | Represent character special files and block special files respectively. | |
| 1768 | In this case the \fIdevmajor\fP and \fIdevminor\fP | |
| 1769 | fields shall contain information defining the device, the format of | |
| 1770 | which is unspecified by this volume of | |
| 1771 | IEEE\ Std\ 1003.1-2001. Implementations may map the device specifications | |
| 1772 | to their own local specification or may ignore | |
| 1773 | the entry. | |
| 1774 | .TP 7 | |
| 1775 | \fB5\fP | |
| 1776 | Specifies a directory or subdirectory. On systems where disk allocation | |
| 1777 | is performed on a directory basis, the \fIsize\fP | |
| 1778 | field shall contain the maximum number of octets (which may be rounded | |
| 1779 | to the nearest disk block allocation unit) that the | |
| 1780 | directory may hold. A \fIsize\fP field of zero indicates no such limiting. | |
| 1781 | Systems that do not support limiting in this manner | |
| 1782 | should ignore the \fIsize\fP field. | |
| 1783 | .TP 7 | |
| 1784 | \fB6\fP | |
| 1785 | Specifies a FIFO special file. Note that the archiving of a FIFO file | |
| 1786 | archives the existence of this file and not its | |
| 1787 | contents. | |
| 1788 | .TP 7 | |
| 1789 | \fB7\fP | |
| 1790 | Reserved to represent a file to which an implementation has associated | |
| 1791 | some high-performance attribute. Implementations without | |
| 1792 | such extensions should treat this file as a regular file (type 0). | |
| 1793 | .TP 7 | |
| 1794 | \fBA-Z\fP | |
| 1795 | The letters \fB'A'\fP to \fB'Z'\fP , inclusive, are reserved for custom | |
| 1796 | implementations. All other values are reserved | |
| 1797 | for future versions of IEEE\ Std\ 1003.1-2001. | |
| 1798 | .sp | |
| 1799 | .LP | |
| 1800 | Attempts to archive a socket using \fBustar\fP interchange format | |
| 1801 | shall produce a diagnostic message. Handling of other file | |
| 1802 | types is implementation-defined. | |
| 1803 | .LP | |
| 1804 | The \fImagic\fP field is the specification that this archive was output | |
| 1805 | in this archive format. If this field contains | |
| 1806 | \fBustar\fP (the five characters from the ISO/IEC\ 646:1991 standard | |
| 1807 | IRV shown followed by NUL), the \fIuname\fP and | |
| 1808 | \fIgname\fP fields shall contain the ISO/IEC\ 646:1991 standard IRV | |
| 1809 | representation of the owner and group of the file, | |
| 1810 | respectively (truncated to fit, if necessary). When the file is restored | |
| 1811 | by a privileged, protection-preserving version of the | |
| 1812 | utility, the user and group databases shall be scanned for these names. | |
| 1813 | If found, the user and group IDs contained within these | |
| 1814 | files shall be used rather than the values contained within the \fIuid\fP | |
| 1815 | and \fIgid\fP fields. | |
| 1816 | .SS cpio Interchange Format | |
| 1817 | .LP | |
| 1818 | The octet-oriented \fBcpio\fP archive format shall be a series of | |
| 1819 | entries, each comprising a header that describes the file, | |
| 1820 | the name of the file, and then the contents of the file. | |
| 1821 | .LP | |
| 1822 | An archive may be recorded as a series of fixed-size blocks of octets. | |
| 1823 | This blocking shall be used only to make physical I/O | |
| 1824 | more efficient. The last group of blocks shall always be at the full | |
| 1825 | size. | |
| 1826 | .LP | |
| 1827 | For the octet-oriented \fBcpio\fP archive format, the individual entry | |
| 1828 | information shall be in the order indicated and | |
| 1829 | described by the following table; see also the \fI<cpio.h>\fP header. | |
| 1830 | .br | |
| 1831 | .sp | |
| 1832 | .RS | |
| 1833 | \fBTable: Octet-Oriented cpio Archive Entry\fP | |
| 1834 | .TS C | |
| 1835 | center; l2 l2 l. | |
| 1836 | \fBHeader Field Name\fP \fBLength (in Octets)\fP \fBInterpreted as\fP | |
| 1837 | \fIc_magic\fP 6 Octal number | |
| 1838 | \fIc_dev\fP 6 Octal number | |
| 1839 | \fIc_ino\fP 6 Octal number | |
| 1840 | \fIc_mode\fP 6 Octal number | |
| 1841 | \fIc_uid\fP 6 Octal number | |
| 1842 | \fIc_gid\fP 6 Octal number | |
| 1843 | \fIc_nlink\fP 6 Octal number | |
| 1844 | \fIc_rdev\fP 6 Octal number | |
| 1845 | \fIc_mtime\fP 11 Octal number | |
| 1846 | \fIc_namesize\fP 6 Octal number | |
| 1847 | \fIc_filesize\fP 11 Octal number | |
| 1848 | \fBFilename Field Name\fP \fBLength\fP \fBInterpreted as\fP | |
| 1849 | \fIc_name\fP \fIc_namesize\fP Pathname string | |
| 1850 | \fBFile Data Field Name\fP \fBLength\fP \fBInterpreted as\fP | |
| 1851 | \fIc_filedata\fP \fIc_filesize\fP Data | |
| 1852 | .TE | |
| 1853 | .RE | |
| 1854 | .SS cpio Header | |
| 1855 | .LP | |
| 1856 | For each file in the archive, a header as defined previously shall | |
| 1857 | be written. The information in the header fields is written | |
| 1858 | as streams of the ISO/IEC\ 646:1991 standard characters interpreted | |
| 1859 | as octal numbers. The octal numbers shall be extended to | |
| 1860 | the necessary length by appending the ISO/IEC\ 646:1991 standard IRV | |
| 1861 | zeros at the most-significant-digit end of the number; the | |
| 1862 | result is written to the most-significant digit of the stream of octets | |
| 1863 | first. The fields shall be interpreted as follows: | |
| 1864 | .TP 7 | |
| 1865 | \fIc_magic\fP | |
| 1866 | Identify the archive as being a transportable archive by containing | |
| 1867 | the identifying value \fB"070707"\fP . | |
| 1868 | .TP 7 | |
| 1869 | \fIc_dev\fP,\ \fIc_ino\fP | |
| 1870 | Contains values that uniquely identify the file within the archive | |
| 1871 | (that is, no files contain the same pair of \fIc_dev\fP and | |
| 1872 | \fIc_ino\fP values unless they are links to the same file). The values | |
| 1873 | shall be determined in an unspecified manner. | |
| 1874 | .TP 7 | |
| 1875 | \fIc_mode\fP | |
| 1876 | Contains the file type and access permissions as defined in the following | |
| 1877 | table. | |
| 1878 | .br | |
| 1879 | .sp | |
| 1880 | .RS | |
| 1881 | \fBTable: Values for cpio c_mode Field\fP | |
| 1882 | .TS C | |
| 1883 | center; l2 l2 l. | |
| 1884 | \fBFile Permissions Name\fP \fBValue\fP \fBIndicates\fP | |
| 1885 | C_IRUSR 000400 Read by owner | |
| 1886 | C_IWUSR 000200 Write by owner | |
| 1887 | C_IXUSR 000100 Execute by owner | |
| 1888 | C_IRGRP 000040 Read by group | |
| 1889 | C_IWGRP 000020 Write by group | |
| 1890 | C_IXGRP 000010 Execute by group | |
| 1891 | C_IROTH 000004 Read by others | |
| 1892 | C_IWOTH 000002 Write by others | |
| 1893 | C_IXOTH 000001 Execute by others | |
| 1894 | C_ISUID 004000 Set \fIuid\fP | |
| 1895 | C_ISGID 002000 Set \fIgid\fP | |
| 1896 | C_ISVTX 001000 Reserved | |
| 1897 | \fBFile Type Name\fP \fBValue\fP \fBIndicates\fP | |
| 1898 | C_ISDIR 040000 Directory | |
| 1899 | C_ISFIFO 010000 FIFO | |
| 1900 | C_ISREG 0100000 Regular file | |
| 1901 | C_ISLNK 0120000 Symbolic link | |
| 1902 | C_ISBLK 060000 Block special file | |
| 1903 | C_ISCHR 020000 Character special file | |
| 1904 | C_ISSOCK 0140000 Socket | |
| 1905 | C_ISCTG 0110000 Reserved | |
| 1906 | .TE | |
| 1907 | .RE | |
| 1908 | .LP | |
| 1909 | Directories, FIFOs, symbolic links, and regular files shall be supported | |
| 1910 | on a system conforming to this volume of | |
| 1911 | IEEE\ Std\ 1003.1-2001; additional values defined previously are reserved | |
| 1912 | for compatibility with existing systems. | |
| 1913 | Additional file types may be supported; however, such files should | |
| 1914 | not be written to archives intended to be transported to other | |
| 1915 | systems. | |
| 1916 | .TP 7 | |
| 1917 | \fIc_uid\fP | |
| 1918 | Contains the user ID of the owner. | |
| 1919 | .TP 7 | |
| 1920 | \fIc_gid\fP | |
| 1921 | Contains the group ID of the group. | |
| 1922 | .TP 7 | |
| 1923 | \fIc_nlink\fP | |
| 1924 | Contains the number of links referencing the file at the time the | |
| 1925 | archive was created. | |
| 1926 | .TP 7 | |
| 1927 | \fIc_rdev\fP | |
| 1928 | Contains implementation-defined information for character or block | |
| 1929 | special files. | |
| 1930 | .TP 7 | |
| 1931 | \fIc_mtime\fP | |
| 1932 | Contains the latest time of modification of the file at the time the | |
| 1933 | archive was created. | |
| 1934 | .TP 7 | |
| 1935 | \fIc_namesize\fP | |
| 1936 | Contains the length of the pathname, including the terminating NUL | |
| 1937 | character. | |
| 1938 | .TP 7 | |
| 1939 | \fIc_filesize\fP | |
| 1940 | Contains the length of the file in octets. This shall be the length | |
| 1941 | of the data section following the header structure. | |
| 1942 | .sp | |
| 1943 | .SS cpio Filename | |
| 1944 | .LP | |
| 1945 | The \fIc_name\fP field shall contain the pathname of the file. The | |
| 1946 | length of this field in octets is the value of | |
| 1947 | \fIc_namesize\fP. | |
| 1948 | .LP | |
| 1949 | If a filename is found on the medium that would create an invalid | |
| 1950 | pathname, it is implementation-defined whether the data from | |
| 1951 | the file is stored on the file hierarchy and under what name it is | |
| 1952 | stored. | |
| 1953 | .LP | |
| 1954 | All characters shall be represented in the ISO/IEC\ 646:1991 standard | |
| 1955 | IRV. For maximum portability between implementations, | |
| 1956 | names should be selected from characters represented by the portable | |
| 1957 | filename character set as octets with the most significant bit | |
| 1958 | zero. If an implementation supports the use of characters outside | |
| 1959 | the portable filename character set in names for files, users, | |
| 1960 | and groups, one or more implementation-defined encodings of these | |
| 1961 | characters shall be provided for interchange purposes. However, | |
| 1962 | the \fIpax\fP utility shall never create filenames on the local system | |
| 1963 | that cannot be accessed via the procedures described | |
| 1964 | previously in this volume of IEEE\ Std\ 1003.1-2001. If a filename | |
| 1965 | is found on the medium that would create an invalid | |
| 1966 | filename, it is implementation-defined whether the data from the file | |
| 1967 | is stored on the local file system and under what name it is | |
| 1968 | stored. The \fIpax\fP utility may choose to ignore these files as | |
| 1969 | long as it produces an error indicating that the file is being | |
| 1970 | ignored. | |
| 1971 | .SS cpio File Data | |
| 1972 | .LP | |
| 1973 | Following \fIc_name\fP, there shall be \fIc_filesize\fP octets of | |
| 1974 | data. Interpretation of such data occurs in a manner | |
| 1975 | dependent on the file. If \fIc_filesize\fP is zero, no data shall | |
| 1976 | be contained in \fIc_filedata\fP. | |
| 1977 | .LP | |
| 1978 | When restoring from an archive: | |
| 1979 | .IP " *" 3 | |
| 1980 | If the user does not have the appropriate privilege to create a file | |
| 1981 | of the specified type, \fIpax\fP shall ignore the entry | |
| 1982 | and write an error message to standard error. | |
| 1983 | .LP | |
| 1984 | .IP " *" 3 | |
| 1985 | Only regular files have data to be restored. Presuming a regular file | |
| 1986 | meets any selection criteria that might be imposed on the | |
| 1987 | format-reading utility by the user, such data shall be restored. | |
| 1988 | .LP | |
| 1989 | .IP " *" 3 | |
| 1990 | If a user does not have appropriate privilege to set a particular | |
| 1991 | mode flag, the flag shall be ignored. Some of the mode flags | |
| 1992 | in the archive format are not mentioned elsewhere in this volume of | |
| 1993 | IEEE\ Std\ 1003.1-2001. If the implementation does not | |
| 1994 | support those flags, they may be ignored. | |
| 1995 | .LP | |
| 1996 | .SS cpio Special Entries | |
| 1997 | .LP | |
| 1998 | FIFO special files, directories, and the trailer shall be recorded | |
| 1999 | with \fIc_filesize\fP equal to zero. For other special | |
| 2000 | files, \fIc_filesize\fP is unspecified by this volume of IEEE\ Std\ 1003.1-2001. | |
| 2001 | The header for the next file entry in the | |
| 2002 | archive shall be written directly after the last octet of the file | |
| 2003 | entry preceding it. A header denoting the filename | |
| 2004 | \fBTRAILER!!!\fP shall indicate the end of the archive; the contents | |
| 2005 | of octets in the last block of the archive following such a | |
| 2006 | header are undefined. | |
| 2007 | .SH EXIT STATUS | |
| 2008 | .LP | |
| 2009 | The following exit values shall be returned: | |
| 2010 | .TP 7 | |
| 2011 | \ 0 | |
| 2012 | All files were processed successfully. | |
| 2013 | .TP 7 | |
| 2014 | >0 | |
| 2015 | An error occurred. | |
| 2016 | .sp | |
| 2017 | .SH CONSEQUENCES OF ERRORS | |
| 2018 | .LP | |
| 2019 | If \fIpax\fP cannot create a file or a link when reading an archive | |
| 2020 | or cannot find a file when writing an archive, or cannot | |
| 2021 | preserve the user ID, group ID, or file mode when the \fB-p\fP option | |
| 2022 | is specified, a diagnostic message shall be written to | |
| 2023 | standard error and a non-zero exit status shall be returned, but processing | |
| 2024 | shall continue. In the case where \fIpax\fP cannot | |
| 2025 | create a link to a file, \fIpax\fP shall not, by default, create a | |
| 2026 | second copy of the file. | |
| 2027 | .LP | |
| 2028 | If the extraction of a file from an archive is prematurely terminated | |
| 2029 | by a signal or error, \fIpax\fP may have only partially | |
| 2030 | extracted the file or (if the \fB-n\fP option was not specified) may | |
| 2031 | have extracted a file of the same name as that specified by | |
| 2032 | the user, but which is not the file the user wanted. Additionally, | |
| 2033 | the file modes of extracted directories may have additional bits | |
| 2034 | from the S_IRWXU mask set as well as incorrect modification and access | |
| 2035 | times. | |
| 2036 | .LP | |
| 2037 | \fIThe following sections are informative.\fP | |
| 2038 | .SH APPLICATION USAGE | |
| 2039 | .LP | |
| 2040 | The \fB-p\fP (privileges) option was invented to reconcile differences | |
| 2041 | between historical \fItar\fP and \fIcpio\fP | |
| 2042 | implementations. In particular, the two utilities use \fB-m\fP in | |
| 2043 | diametrically opposed ways. The \fB-p\fP option also provides a | |
| 2044 | consistent means of extending the ways in which future file attributes | |
| 2045 | can be addressed, such as for enhanced security systems or | |
| 2046 | high-performance files. Although it may seem complex, there are really | |
| 2047 | two modes that are most commonly used: | |
| 2048 | .TP 7 | |
| 2049 | \fB-p\ e\fP | |
| 2050 | ``Preserve everything". This would be used by the historical superuser, | |
| 2051 | someone with all the appropriate privileges, to | |
| 2052 | preserve all aspects of the files as they are recorded in the archive. | |
| 2053 | The \fBe\fP flag is the sum of \fBo\fP and \fBp\fP, and | |
| 2054 | other implementation-defined attributes. | |
| 2055 | .TP 7 | |
| 2056 | \fB-p\ p\fP | |
| 2057 | ``Preserve" the file mode bits. This would be used by the user with | |
| 2058 | regular privileges who wished to preserve aspects of the | |
| 2059 | file other than the ownership. The file times are preserved by default, | |
| 2060 | but two other flags are offered to disable these and use | |
| 2061 | the time of extraction. | |
| 2062 | .sp | |
| 2063 | .LP | |
| 2064 | The one pathname per line format of standard input precludes pathnames | |
| 2065 | containing <newline>s. Although such pathnames | |
| 2066 | violate the portable filename guidelines, they may exist and their | |
| 2067 | presence may inhibit usage of \fIpax\fP within shell scripts. | |
| 2068 | This problem is inherited from historical archive programs. The problem | |
| 2069 | can be avoided by listing filename arguments on the command | |
| 2070 | line instead of on standard input. | |
| 2071 | .LP | |
| 2072 | It is almost certain that appropriate privileges are required for | |
| 2073 | \fIpax\fP to accomplish parts of this volume of | |
| 2074 | IEEE\ Std\ 1003.1-2001. Specifically, creating files of type block | |
| 2075 | special or character special, restoring file access | |
| 2076 | times unless the files are owned by the user (the \fB-t\fP option), | |
| 2077 | or preserving file owner, group, and mode (the \fB-p\fP | |
| 2078 | option) all probably require appropriate privileges. | |
| 2079 | .LP | |
| 2080 | In \fBread\fP mode, implementations are permitted to overwrite files | |
| 2081 | when the archive has multiple members with the same name. | |
| 2082 | This may fail if permissions on the first version of the file do not | |
| 2083 | permit it to be overwritten. | |
| 2084 | .LP | |
| 2085 | The \fBcpio\fP and \fBustar\fP formats can only support files up to | |
| 2086 | 8589934592 bytes (8 * 2^30) in size. | |
| 2087 | .SH EXAMPLES | |
| 2088 | .LP | |
| 2089 | The following command: | |
| 2090 | .sp | |
| 2091 | .RS | |
| 2092 | .nf | |
| 2093 | ||
| 2094 | \fBpax -w -f /dev/rmt/1m . | |
| 2095 | \fP | |
| 2096 | .fi | |
| 2097 | .RE | |
| 2098 | .LP | |
| 2099 | copies the contents of the current directory to tape drive 1, medium | |
| 2100 | density (assuming historical System V device naming | |
| 2101 | procedures-the historical BSD device name would be \fB/dev/rmt9\fP). | |
| 2102 | .LP | |
| 2103 | The following commands: | |
| 2104 | .sp | |
| 2105 | .RS | |
| 2106 | .nf | |
| 2107 | ||
| 2108 | \fBmkdir\fP \fInewdir\fP\fBpax -rw\fP \fIolddir newdir\fP | |
| 2109 | .fi | |
| 2110 | .RE | |
| 2111 | .LP | |
| 2112 | copy the \fIolddir\fP directory hierarchy to \fInewdir\fP. | |
| 2113 | .sp | |
| 2114 | .RS | |
| 2115 | .nf | |
| 2116 | ||
| 2117 | \fBpax -r -s ',^//*usr//*,,' -f a.pax | |
| 2118 | \fP | |
| 2119 | .fi | |
| 2120 | .RE | |
| 2121 | .LP | |
| 2122 | reads the archive \fBa.pax\fP, with all files rooted in \fB/usr\fP | |
| 2123 | in the archive extracted relative to the current | |
| 2124 | directory. | |
| 2125 | .LP | |
| 2126 | Using the option: | |
| 2127 | .sp | |
| 2128 | .RS | |
| 2129 | .nf | |
| 2130 | ||
| 2131 | \fB-o listopt="%M %(atime)T %(size)D %(name)s" | |
| 2132 | \fP | |
| 2133 | .fi | |
| 2134 | .RE | |
| 2135 | .LP | |
| 2136 | overrides the default output description in Standard Output and instead | |
| 2137 | writes: | |
| 2138 | .sp | |
| 2139 | .RS | |
| 2140 | .nf | |
| 2141 | ||
| 2142 | \fB-rw-rw--- Jan 12 15:53 1492 /usr/foo/bar | |
| 2143 | \fP | |
| 2144 | .fi | |
| 2145 | .RE | |
| 2146 | .LP | |
| 2147 | Using the options: | |
| 2148 | .sp | |
| 2149 | .RS | |
| 2150 | .nf | |
| 2151 | ||
| 2152 | \fB-o listopt='%L\\t%(size)D\\n%.7' \\ | |
| 2153 | -o listopt='(name)s\\n%(ctime)T\\n%T' | |
| 2154 | \fP | |
| 2155 | .fi | |
| 2156 | .RE | |
| 2157 | .LP | |
| 2158 | overrides the default output description in Standard Output and instead | |
| 2159 | writes: | |
| 2160 | .sp | |
| 2161 | .RS | |
| 2162 | .nf | |
| 2163 | ||
| 2164 | \fB/usr/foo/bar -> /tmp 1492 | |
| 2165 | /usr/fo | |
| 2166 | Jan 12 1991 | |
| 2167 | Jan 31 15:53 | |
| 2168 | \fP | |
| 2169 | .fi | |
| 2170 | .RE | |
| 2171 | .SH RATIONALE | |
| 2172 | .LP | |
| 2173 | The \fIpax\fP utility was new for the ISO\ POSIX-2:1993 standard. | |
| 2174 | It represents a peaceful compromise between advocates of | |
| 2175 | the historical \fItar\fP and \fIcpio\fP utilities. | |
| 2176 | .LP | |
| 2177 | A fundamental difference between \fIcpio\fP and \fItar\fP was in the | |
| 2178 | way directories were treated. The \fIcpio\fP utility did | |
| 2179 | not treat directories differently from other files, and to select | |
| 2180 | a directory and its contents required that each file in the | |
| 2181 | hierarchy be explicitly specified. For \fItar\fP, a directory matched | |
| 2182 | every file in the file hierarchy it rooted. | |
| 2183 | .LP | |
| 2184 | The \fIpax\fP utility offers both interfaces; by default, directories | |
| 2185 | map into the file hierarchy they root. The \fB-d\fP | |
| 2186 | option causes \fIpax\fP to skip any file not explicitly referenced, | |
| 2187 | as \fIcpio\fP historically did. The \fItar\fP \fB-\fP | |
| 2188 | \fIstyle\fP behavior was chosen as the default because it was believed | |
| 2189 | that this was the more common usage and because \fItar\fP | |
| 2190 | is the more commonly available interface, as it was historically provided | |
| 2191 | on both System V and BSD implementations. | |
| 2192 | .LP | |
| 2193 | The data interchange format specification in this volume of IEEE\ Std\ 1003.1-2001 | |
| 2194 | requires that processes with | |
| 2195 | "appropriate privileges" shall always restore the ownership and permissions | |
| 2196 | of extracted files exactly as archived. If viewed | |
| 2197 | from the historic equivalence between superuser and "appropriate privileges", | |
| 2198 | there are two problems with this requirement. | |
| 2199 | First, users running as superusers may unknowingly set dangerous permissions | |
| 2200 | on extracted files. Second, it is needlessly limiting, | |
| 2201 | in that superusers cannot extract files and own them as superuser | |
| 2202 | unless the archive was created by the superuser. (It should be | |
| 2203 | noted that restoration of ownerships and permissions for the superuser, | |
| 2204 | by default, is historical practice in \fIcpio\fP, but not | |
| 2205 | in \fItar\fP.) In order to avoid these two problems, the \fIpax\fP | |
| 2206 | specification has an additional "privilege" mechanism, the | |
| 2207 | \fB-p\fP option. Only a \fIpax\fP invocation with the privileges needed, | |
| 2208 | and which has the \fB-p\fP option set using the | |
| 2209 | \fBe\fP specification character, has the "appropriate privilege" to | |
| 2210 | restore full ownership and permission information. | |
| 2211 | .LP | |
| 2212 | Note also that this volume of IEEE\ Std\ 1003.1-2001 requires that | |
| 2213 | the file ownership and access permissions shall be | |
| 2214 | set, on extraction, in the same fashion as the \fIcreat\fP() function | |
| 2215 | when provided with the | |
| 2216 | mode stored in the archive. This means that the file creation mask | |
| 2217 | of the user is applied to the file permissions. | |
| 2218 | .LP | |
| 2219 | Users should note that directories may be created by \fIpax\fP while | |
| 2220 | extracting files with permissions that are different from | |
| 2221 | those that existed at the time the archive was created. When extracting | |
| 2222 | sensitive information into a directory hierarchy that no | |
| 2223 | longer exists, users are encouraged to set their file creation mask | |
| 2224 | appropriately to protect these files during extraction. | |
| 2225 | .LP | |
| 2226 | The table of contents output is written to standard output to facilitate | |
| 2227 | pipeline processing. | |
| 2228 | .LP | |
| 2229 | An early proposal had hard links displaying for all pathnames. This | |
| 2230 | was removed because it complicates the output of the case | |
| 2231 | where \fB-v\fP is not specified and does not match historical \fIcpio\fP | |
| 2232 | usage. The hard-link information is available in the | |
| 2233 | \fB-v\fP display. | |
| 2234 | .LP | |
| 2235 | The description of the \fB-l\fP option allows implementations to make | |
| 2236 | hard links to symbolic links. | |
| 2237 | IEEE\ Std\ 1003.1-2001 does not specify any way to create a hard link | |
| 2238 | to a symbolic link, but many implementations provide | |
| 2239 | this capability as an extension. If there are hard links to symbolic | |
| 2240 | links when an archive is created, the implementation is | |
| 2241 | required to archive the hard link in the archive (unless \fB-H\fP | |
| 2242 | or \fB-L\fP is specified). When in \fBread\fP mode and in | |
| 2243 | \fBcopy\fP mode, implementations supporting hard links to symbolic | |
| 2244 | links should use them when appropriate. | |
| 2245 | .LP | |
| 2246 | The archive formats inherited from the POSIX.1-1990 standard have | |
| 2247 | certain restrictions that have been brought along from | |
| 2248 | historical usage. For example, there are restrictions on the length | |
| 2249 | of pathnames stored in the archive. When \fIpax\fP is used in | |
| 2250 | \fBcopy\fP( \fB-rw\fP) mode (copying directory hierarchies), the ability | |
| 2251 | to use extensions from the \fB-x\fP \fBpax\fP format | |
| 2252 | overcomes these restrictions. | |
| 2253 | .LP | |
| 2254 | The default \fIblocksize\fP value of 5120 bytes for \fIcpio\fP was | |
| 2255 | selected because it is one of the standard block-size | |
| 2256 | values for \fIcpio\fP, set when the \fB-B\fP option is specified. | |
| 2257 | (The other default block-size value for \fIcpio\fP is 512 | |
| 2258 | bytes, and this was considered to be too small.) The default block | |
| 2259 | value of 10240 bytes for \fItar\fP was selected because that is | |
| 2260 | the standard block-size value for BSD \fItar\fP. The maximum block | |
| 2261 | size of 32256 bytes (2**15-512 bytes) | |
| 2262 | is the largest multiple of 512 bytes that fits into a signed 16-bit | |
| 2263 | tape controller transfer register. There are known limitations | |
| 2264 | in some historical systems that would prevent larger blocks from being | |
| 2265 | accepted. Historical values were chosen to improve | |
| 2266 | compatibility with historical scripts using \fIdd\fP or similar utilities | |
| 2267 | to manipulate | |
| 2268 | archives. Also, default block sizes for any file type other than character | |
| 2269 | special file has been deleted from this volume of | |
| 2270 | IEEE\ Std\ 1003.1-2001 as unimportant and not likely to affect the | |
| 2271 | structure of the resulting archive. | |
| 2272 | .LP | |
| 2273 | Implementations are permitted to modify the block-size value based | |
| 2274 | on the archive format or the device to which the archive is | |
| 2275 | being written. This is to provide implementations with the opportunity | |
| 2276 | to take advantage of special types of devices, and it should | |
| 2277 | not be used without a great deal of consideration as it almost certainly | |
| 2278 | decreases archive portability. | |
| 2279 | .LP | |
| 2280 | The intended use of the \fB-n\fP option was to permit extraction of | |
| 2281 | one or more files from the archive without processing the | |
| 2282 | entire archive. This was viewed by the standard developers as offering | |
| 2283 | significant performance advantages over historical | |
| 2284 | implementations. The \fB-n\fP option in early proposals had three | |
| 2285 | effects; the first was to cause special characters in patterns | |
| 2286 | to not be treated specially. The second was to cause only the first | |
| 2287 | file that matched a pattern to be extracted. The third was to | |
| 2288 | cause \fIpax\fP to write a diagnostic message to standard error when | |
| 2289 | no file was found matching a specified pattern. Only the | |
| 2290 | second behavior is retained by this volume of IEEE\ Std\ 1003.1-2001, | |
| 2291 | for many reasons. First, it is in general not | |
| 2292 | acceptable for a single option to have multiple effects. Second, the | |
| 2293 | ability to make pattern matching characters act as normal | |
| 2294 | characters is useful for parts of \fIpax\fP other than file extraction. | |
| 2295 | Third, a finer degree of control over the special | |
| 2296 | characters is useful because users may wish to normalize only a single | |
| 2297 | special character in a single filename. Fourth, given a more | |
| 2298 | general escape mechanism, the previous behavior of the \fB-n\fP option | |
| 2299 | can be easily obtained using the \fB-s\fP option or a \fIsed\fP script. | |
| 2300 | Finally, writing a diagnostic message when a pattern specified by | |
| 2301 | the user is | |
| 2302 | unmatched by any file is useful behavior in all cases. | |
| 2303 | .LP | |
| 2304 | In this version, the \fB-n\fP was removed from the \fBcopy\fP mode | |
| 2305 | synopsis of \fIpax\fP; it is inapplicable because there | |
| 2306 | are no pattern operands specified in this mode. | |
| 2307 | .LP | |
| 2308 | There is another method than \fIpax\fP for copying subtrees in IEEE\ Std\ 1003.1-2001 | |
| 2309 | described as part of the \fIcp\fP utility. Both methods are historical | |
| 2310 | practice: \fIcp\fP | |
| 2311 | provides a simpler, more intuitive interface, while \fIpax\fP offers | |
| 2312 | a finer granularity of control. Each provides additional | |
| 2313 | functionality to the other; in particular, \fIpax\fP maintains the | |
| 2314 | hard-link structure of the hierarchy while \fIcp\fP does not. It is | |
| 2315 | the intention of the standard developers that the results be similar | |
| 2316 | (using | |
| 2317 | appropriate option combinations in both utilities). The results are | |
| 2318 | not required to be identical; there seemed insufficient gain to | |
| 2319 | applications to balance the difficulty of implementations having to | |
| 2320 | guarantee that the results would be exactly identical. | |
| 2321 | .LP | |
| 2322 | A single archive may span more than one file. It is suggested that | |
| 2323 | implementations provide informative messages to the user on | |
| 2324 | standard error whenever the archive file is changed. | |
| 2325 | .LP | |
| 2326 | The \fB-d\fP option (do not create intermediate directories not listed | |
| 2327 | in the archive) found in early proposals was originally | |
| 2328 | provided as a complement to the historic \fB-d\fP option of \fIcpio\fP. | |
| 2329 | It has been deleted. | |
| 2330 | .LP | |
| 2331 | The \fB-s\fP option in early proposals specified a subset of the substitution | |
| 2332 | command from the \fIed\fP utility. As there was no reason for only | |
| 2333 | a subset to be supported, the \fB-s\fP option is now | |
| 2334 | compatible with the current \fIed\fP specification. Since the delimiter | |
| 2335 | can be any non-null | |
| 2336 | character, the following usage with single spaces is valid: | |
| 2337 | .sp | |
| 2338 | .RS | |
| 2339 | .nf | |
| 2340 | ||
| 2341 | \fBpax -s " foo bar " ... | |
| 2342 | \fP | |
| 2343 | .fi | |
| 2344 | .RE | |
| 2345 | .LP | |
| 2346 | The \fB-t\fP description is worded so as to note that this may cause | |
| 2347 | the access time update caused by some other activity | |
| 2348 | (which occurs while the file is being read) to be overwritten. | |
| 2349 | .LP | |
| 2350 | The default behavior of \fIpax\fP with regard to file modification | |
| 2351 | times is the same as historical implementations of | |
| 2352 | \fItar\fP. It is not the historical behavior of \fIcpio\fP. | |
| 2353 | .LP | |
| 2354 | Because the \fB-i\fP option uses \fB/dev/tty\fP, utilities without | |
| 2355 | a controlling terminal are not able to use this option. | |
| 2356 | .LP | |
| 2357 | The \fB-y\fP option, found in early proposals, has been deleted because | |
| 2358 | a line containing a single period for the \fB-i\fP | |
| 2359 | option has equivalent functionality. The special lines for the \fB-i\fP | |
| 2360 | option (a single period and the empty line) are historical | |
| 2361 | practice in \fIcpio\fP. | |
| 2362 | .LP | |
| 2363 | In early drafts, a \fB-e\fP \fIcharmap\fP option was included to increase | |
| 2364 | portability of files between systems using different | |
| 2365 | coded character sets. This option was omitted because it was apparent | |
| 2366 | that consensus could not be formed for it. In this version, | |
| 2367 | the use of UTF-8 should be an adequate substitute. | |
| 2368 | .LP | |
| 2369 | The \fB-k\fP option was added to address international concerns about | |
| 2370 | the dangers involved in the character set transformations | |
| 2371 | of \fB-e\fP (if the target character set were different from the source, | |
| 2372 | the filenames might be transformed into names matching | |
| 2373 | existing files) and also was made more general to protect files transferred | |
| 2374 | between file systems with different {NAME_MAX} values | |
| 2375 | (truncating a filename on a smaller system might also inadvertently | |
| 2376 | overwrite existing files). As stated, it prevents any | |
| 2377 | overwriting, even if the target file is older than the source. This | |
| 2378 | version adds more granularity of options to solve this problem | |
| 2379 | by introducing the \fB-o\fP \fBinvalid=\fP option-specifically the | |
| 2380 | UTF-8 action. (Note that an existing file that is named with a | |
| 2381 | UTF-8 encoding is still subject to overwriting in this case. The \fB-k\fP | |
| 2382 | option closes that loophole.) | |
| 2383 | .LP | |
| 2384 | Some of the file characteristics referenced in this volume of IEEE\ Std\ 1003.1-2001 | |
| 2385 | might not be supported by some | |
| 2386 | archive formats. For example, neither the \fBtar\fP nor \fBcpio\fP | |
| 2387 | formats contain the file access time. For this reason, the | |
| 2388 | \fBe\fP specification character has been provided, intended to cause | |
| 2389 | all file characteristics specified in the archive to be | |
| 2390 | retained. | |
| 2391 | .LP | |
| 2392 | It is required that extracted directories, by default, have their | |
| 2393 | access and modification times and permissions set to the | |
| 2394 | values specified in the archive. This has obvious problems in that | |
| 2395 | the directories are almost certainly modified after being | |
| 2396 | extracted and that directory permissions may not permit file creation. | |
| 2397 | One possible solution is to create directories with the mode | |
| 2398 | specified in the archive, as modified by the \fIumask\fP of the user, | |
| 2399 | with sufficient | |
| 2400 | permissions to allow file creation. After all files have been extracted, | |
| 2401 | \fIpax\fP would then reset the access and modification | |
| 2402 | times and permissions as necessary. | |
| 2403 | .LP | |
| 2404 | The list-mode formatting description borrows heavily from the one | |
| 2405 | defined by the \fIprintf\fP utility. However, since there is no separate | |
| 2406 | operand list to get conversion arguments, | |
| 2407 | the format was extended to allow specifying the name of the conversion | |
| 2408 | argument as part of the conversion specification. | |
| 2409 | .LP | |
| 2410 | The \fBT\fP conversion specifier allows time fields to be displayed | |
| 2411 | in any of the date formats. Unlike the \fIls\fP utility, \fIpax\fP | |
| 2412 | does not adjust the format when the date is less than six months in | |
| 2413 | the | |
| 2414 | past. This makes parsing the output more predictable. | |
| 2415 | .LP | |
| 2416 | The \fBD\fP conversion specifier handles the ability to display the | |
| 2417 | major/minor or file size, as with \fIls\fP, by using \fB%-8(\fP\fIsize\fP\fB)D\fP. | |
| 2418 | .LP | |
| 2419 | The \fBL\fP conversion specifier handles the \fIls\fP display for | |
| 2420 | symbolic links. | |
| 2421 | .LP | |
| 2422 | Conversion specifiers were added to generate existing known types | |
| 2423 | used for \fIls\fP. | |
| 2424 | .SS pax Interchange Format | |
| 2425 | .LP | |
| 2426 | The new POSIX data interchange format was developed primarily to satisfy | |
| 2427 | international concerns that the \fBustar\fP and | |
| 2428 | \fBcpio\fP formats did not provide for file, user, and group names | |
| 2429 | encoded in characters outside a subset of the | |
| 2430 | ISO/IEC\ 646:1991 standard. The standard developers realized that | |
| 2431 | this new POSIX data interchange format should be very | |
| 2432 | extensible because there were other requirements they foresaw in the | |
| 2433 | near future: | |
| 2434 | .IP " *" 3 | |
| 2435 | Support international character encodings and locale information | |
| 2436 | .LP | |
| 2437 | .IP " *" 3 | |
| 2438 | Support security information (ACLs, and so on) | |
| 2439 | .LP | |
| 2440 | .IP " *" 3 | |
| 2441 | Support future file types, such as realtime or contiguous files | |
| 2442 | .LP | |
| 2443 | .IP " *" 3 | |
| 2444 | Include data areas for implementation use | |
| 2445 | .LP | |
| 2446 | .IP " *" 3 | |
| 2447 | Support systems with words larger than 32 bits and timers with subsecond | |
| 2448 | granularity | |
| 2449 | .LP | |
| 2450 | .LP | |
| 2451 | The following were not goals for this format because these are better | |
| 2452 | handled by separate utilities or are inappropriate for a | |
| 2453 | portable format: | |
| 2454 | .IP " *" 3 | |
| 2455 | Encryption | |
| 2456 | .LP | |
| 2457 | .IP " *" 3 | |
| 2458 | Compression | |
| 2459 | .LP | |
| 2460 | .IP " *" 3 | |
| 2461 | Data translation between locales and codesets | |
| 2462 | .LP | |
| 2463 | .IP " *" 3 | |
| 2464 | \fIinode\fP storage | |
| 2465 | .LP | |
| 2466 | .LP | |
| 2467 | The format chosen to support the goals is an extension of the \fBustar\fP | |
| 2468 | format. Of the two formats previously available, only | |
| 2469 | the \fBustar\fP format was selected for extensions because: | |
| 2470 | .IP " *" 3 | |
| 2471 | It was easier to extend in an upwards-compatible way. It offered version | |
| 2472 | flags and header block type fields with room for future | |
| 2473 | standardization. The \fBcpio\fP format, while possessing a more flexible | |
| 2474 | file naming methodology, could not be extended without | |
| 2475 | breaking some theoretical implementation or using a dummy filename | |
| 2476 | that could be a legitimate filename. | |
| 2477 | .LP | |
| 2478 | .IP " *" 3 | |
| 2479 | Industry experience since the original " \fItar\fP wars" fought in | |
| 2480 | developing the ISO\ POSIX-1 standard has clearly been | |
| 2481 | in favor of the \fBustar\fP format, which is generally the default | |
| 2482 | output format selected for \fIpax\fP implementations on new | |
| 2483 | systems. | |
| 2484 | .LP | |
| 2485 | .LP | |
| 2486 | The new format was designed with one additional goal in mind: reasonable | |
| 2487 | behavior when an older \fItar\fP or \fIpax\fP utility | |
| 2488 | happened to read an archive. Since the POSIX.1-1990 standard mandated | |
| 2489 | that a "format-reading utility" had to treat unrecognized | |
| 2490 | \fItypeflag\fP values as regular files, this allowed the format to | |
| 2491 | include all the extended information in a pseudo-regular file | |
| 2492 | that preceded each real file. An option is given that allows the archive | |
| 2493 | creator to set up reasonable names for these files on the | |
| 2494 | older systems. Also, the normative text suggests that reasonable file | |
| 2495 | access values be used for this \fBustar\fP header block. | |
| 2496 | Making these header files inaccessible for convenient reading and | |
| 2497 | deleting would not be reasonable. File permissions of 600 or 700 | |
| 2498 | are suggested. | |
| 2499 | .LP | |
| 2500 | The \fBustar\fP \fItypeflag\fP field was used to accommodate the additional | |
| 2501 | functionality of the new format rather than magic | |
| 2502 | or version because the POSIX.1-1990 standard (and, by reference, the | |
| 2503 | previous version of \fIpax\fP), mandated the behavior of the | |
| 2504 | format-reading utility when it encountered an unknown \fItypeflag\fP, | |
| 2505 | but was silent about the other two fields. | |
| 2506 | .LP | |
| 2507 | Early proposals of the first revision to IEEE\ Std\ 1003.1-2001 contained | |
| 2508 | a proposed archive format that was based on | |
| 2509 | compatibility with the standard for tape files (ISO\ 1001, similar | |
| 2510 | to the format used historically on many mainframes and | |
| 2511 | minicomputers). This format was overly complex and required considerable | |
| 2512 | overhead in volume and header records. Furthermore, the | |
| 2513 | standard developers felt that it would not be acceptable to the community | |
| 2514 | of POSIX developers, so it was later changed to be a | |
| 2515 | format more closely related to historical practice on POSIX systems. | |
| 2516 | .LP | |
| 2517 | The prefix and name split of pathnames in \fBustar\fP was replaced | |
| 2518 | by the single path extended header record for | |
| 2519 | simplicity. | |
| 2520 | .LP | |
| 2521 | The concept of a global extended header ( \fItypeflag\fP \fBg\fP) | |
| 2522 | was controversial. If this were applied to an archive being | |
| 2523 | recorded on magnetic tape, a few unreadable blocks at the beginning | |
| 2524 | of the tape could be a serious problem; a utility attempting to | |
| 2525 | extract as many files as possible from a damaged archive could lose | |
| 2526 | a large percentage of file header information in this case. | |
| 2527 | However, if the archive were on a reliable medium, such as a CD-ROM, | |
| 2528 | the global extended header offers considerable potential size | |
| 2529 | reductions by eliminating redundant information. Thus, the text warns | |
| 2530 | against using the global method for unreliable media and | |
| 2531 | provides a method for implanting global information in the extended | |
| 2532 | header for each file, rather than in the \fItypeflag\fP | |
| 2533 | \fBg\fP records. | |
| 2534 | .LP | |
| 2535 | No facility for data translation or filtering on a per-file basis | |
| 2536 | is included because the standard developers could not invent | |
| 2537 | an interface that would allow this in an efficient manner. If a filter, | |
| 2538 | such as encryption or compression, is to be applied to all | |
| 2539 | the files, it is more efficient to apply the filter to the entire | |
| 2540 | archive as a single file. The standard developers considered | |
| 2541 | interfaces that would invoke a shell script for each file going into | |
| 2542 | or out of the archive, but the system overhead in this | |
| 2543 | approach was considered to be too high. | |
| 2544 | .LP | |
| 2545 | One such approach would be to have \fBfilter=\fP records that give | |
| 2546 | a pathname for an executable. When the program is invoked, | |
| 2547 | the file and archive would be open for standard input/output and all | |
| 2548 | the header fields would be available as environment variables | |
| 2549 | or command-line arguments. The standard developers did discuss such | |
| 2550 | schemes, but they were omitted from | |
| 2551 | IEEE\ Std\ 1003.1-2001 due to concerns about excessive overhead. Also, | |
| 2552 | the program itself would need to be in the archive | |
| 2553 | if it were to be used portably. | |
| 2554 | .LP | |
| 2555 | There is currently no portable means of identifying the character | |
| 2556 | set(s) used for a file in the file system. Therefore, | |
| 2557 | \fIpax\fP has not been given a mechanism to generate charset records | |
| 2558 | automatically. The only portable means of doing this is for | |
| 2559 | the user to write the archive using the \fB-o\fP \fBcharset=\fP \fIstring\fP | |
| 2560 | command line option. This assumes that all of the | |
| 2561 | files in the archive use the same encoding. The "implementation-defined" | |
| 2562 | text is included to allow for a system that can identify | |
| 2563 | the encodings used for each of its files. | |
| 2564 | .LP | |
| 2565 | The table of standards that accompanies the charset record description | |
| 2566 | is acknowledged to be very limited. Only a limited number | |
| 2567 | of character set standards is reasonable for maximal interchange. | |
| 2568 | Any character set is, of course, possible by prior agreement. It | |
| 2569 | was suggested that EBCDIC be listed, but it was omitted because it | |
| 2570 | is not defined by a formal standard. Formal standards, and then | |
| 2571 | only those with reasonably large followings, can be included here, | |
| 2572 | simply as a matter of practicality. The <\fIvalue\fP>s | |
| 2573 | represent names of officially registered character sets in the format | |
| 2574 | required by the ISO\ 2375:1985 standard. | |
| 2575 | .LP | |
| 2576 | The normal comma or <blank>-separated list rules are not followed | |
| 2577 | in the case of keyword options to allow ease of argument | |
| 2578 | parsing for \fIgetopts\fP. | |
| 2579 | .LP | |
| 2580 | Further information on character encodings is in pax Archive Character | |
| 2581 | Set Encoding/Decoding | |
| 2582 | \&. | |
| 2583 | .LP | |
| 2584 | The standard developers have reserved keyword name space for vendor | |
| 2585 | extensions. It is suggested that the format to be used | |
| 2586 | is: | |
| 2587 | .sp | |
| 2588 | .RS | |
| 2589 | .nf | |
| 2590 | ||
| 2591 | \fIVENDOR.keyword\fP | |
| 2592 | .fi | |
| 2593 | .RE | |
| 2594 | .LP | |
| 2595 | where \fIVENDOR\fP is the name of the vendor or organization in all | |
| 2596 | uppercase letters. It is further suggested that the keyword | |
| 2597 | following the period be named differently than any of the standard | |
| 2598 | keywords so that it could be used for future standardization, if | |
| 2599 | appropriate, by omitting the \fIVENDOR\fP prefix. | |
| 2600 | .LP | |
| 2601 | The <\fIlength\fP> field in the extended header record was included | |
| 2602 | to make it simpler to step through the records, even | |
| 2603 | if a record contains an unknown format (to a particular \fIpax\fP) | |
| 2604 | with complex interactions of special characters. It also | |
| 2605 | provides a minor integrity checkpoint within the records to aid a | |
| 2606 | program attempting to recover files from a damaged archive. | |
| 2607 | .LP | |
| 2608 | There are no extended header versions of the \fIdevmajor\fP and \fIdevminor\fP | |
| 2609 | fields because the unspecified format | |
| 2610 | \fBustar\fP header field should be sufficient. If they are not, vendor-specific | |
| 2611 | extended keywords (such as \fIVENDOR.devmajor\fP) | |
| 2612 | should be used. | |
| 2613 | .LP | |
| 2614 | Device and \fIi\fP-number labeling of files was not adopted from \fIcpio\fP; | |
| 2615 | files are interchanged strictly on a symbolic | |
| 2616 | name basis, as in \fBustar\fP. | |
| 2617 | .LP | |
| 2618 | Just as with the \fBustar\fP format descriptions, the new format makes | |
| 2619 | no special arrangements for multi-volume archives. Each | |
| 2620 | of the \fIpax\fP archive types is assumed to be inside a single POSIX | |
| 2621 | file and splitting that file over multiple volumes | |
| 2622 | (diskettes, tape cartridges, and so on), processing their labels, | |
| 2623 | and mounting each in the proper sequence are considered to be | |
| 2624 | implementation details that cannot be described portably. | |
| 2625 | .LP | |
| 2626 | The \fBpax\fP format is intended for interchange, not only for backup | |
| 2627 | on a single (family of) systems. It is not as densely | |
| 2628 | packed as might be possible for backup: | |
| 2629 | .IP " *" 3 | |
| 2630 | It contains information as coded characters that could be coded in | |
| 2631 | binary. | |
| 2632 | .LP | |
| 2633 | .IP " *" 3 | |
| 2634 | It identifies extended records with name fields that could be omitted | |
| 2635 | in favor of a fixed-field layout. | |
| 2636 | .LP | |
| 2637 | .IP " *" 3 | |
| 2638 | It translates names into a portable character set and identifies locale-related | |
| 2639 | information, both of which are probably | |
| 2640 | unnecessary for backup. | |
| 2641 | .LP | |
| 2642 | .LP | |
| 2643 | The requirements on restoring from an archive are slightly different | |
| 2644 | from the historical wording, allowing for non-monolithic | |
| 2645 | privilege to bring forward as much as possible. In particular, attributes | |
| 2646 | such as "high performance file" might be broadly but | |
| 2647 | not universally granted while set-user-ID or \fIchown\fP() might be | |
| 2648 | much more restricted. | |
| 2649 | There is no implication in IEEE\ Std\ 1003.1-2001 that the security | |
| 2650 | information be honored after it is restored to the file | |
| 2651 | hierarchy, in spite of what might be improperly inferred by the silence | |
| 2652 | on that topic. That is a topic for another standard. | |
| 2653 | .LP | |
| 2654 | Links are recorded in the fashion described here because a link can | |
| 2655 | be to any file type. It is desirable in general to be able | |
| 2656 | to restore part of an archive selectively and restore all of those | |
| 2657 | files completely. If the data is not associated with each link, | |
| 2658 | it is not possible to do this. However, the data associated with a | |
| 2659 | file can be large, and when selective restoration is not needed, | |
| 2660 | this can be a significant burden. The archive is structured so that | |
| 2661 | files that have no associated data can always be restored by | |
| 2662 | the name of any link name of any link, and the user may choose whether | |
| 2663 | data is recorded with each instance of a file that contains | |
| 2664 | data. The format permits mixing of both types of links in a single | |
| 2665 | archive; this can be done for special needs, and \fIpax\fP is | |
| 2666 | expected to interpret such archives on input properly, despite the | |
| 2667 | fact that there is no \fIpax\fP option that would force this | |
| 2668 | mixed case on output. (When \fB-o\fP \fBlinkdata\fP is used, the output | |
| 2669 | must contain the duplicate data, but the implementation | |
| 2670 | is free to include it or omit it when \fB-o\fP \fBlinkdata\fP is not | |
| 2671 | used.) | |
| 2672 | .LP | |
| 2673 | The time values are included as extended header records for those | |
| 2674 | implementations needing more than the eleven octal digits | |
| 2675 | allowed by the \fBustar\fP format. Portable file timestamps cannot | |
| 2676 | be negative. If \fIpax\fP encounters a file with a negative | |
| 2677 | timestamp in \fBcopy\fP or \fBwrite\fP mode, it can reject the file, | |
| 2678 | substitute a non-negative timestamp, or generate a | |
| 2679 | non-portable timestamp with a leading \fB'-'\fP . Even though some | |
| 2680 | implementations can support finer file-time granularities | |
| 2681 | than seconds, the normative text requires support only for seconds | |
| 2682 | since the Epoch because the ISO\ POSIX-1 standard states | |
| 2683 | them that way. The \fBustar\fP format includes only \fImtime\fP; the | |
| 2684 | new format adds \fIatime\fP and \fIctime\fP for symmetry. | |
| 2685 | The \fIatime\fP access time restored to the file system will be affected | |
| 2686 | by the \fB-p\fP \fBa\fP and \fB-p\fP \fBe\fP options. | |
| 2687 | The \fIctime\fP creation time (actually \fIinode\fP modification time) | |
| 2688 | is described with "appropriate privilege" so that it can | |
| 2689 | be ignored when writing to the file system. POSIX does not provide | |
| 2690 | a portable means to change file creation time. Nothing is | |
| 2691 | intended to prevent a non-portable implementation of \fIpax\fP from | |
| 2692 | restoring the value. | |
| 2693 | .LP | |
| 2694 | The \fIgid\fP, \fIsize\fP, and \fIuid\fP extended header records were | |
| 2695 | included to allow expansion beyond the sizes specified | |
| 2696 | in the regular \fItar\fP header. New file system architectures are | |
| 2697 | emerging that will exhaust the 12-digit size field. There are | |
| 2698 | probably not many systems requiring more than 8 digits for user and | |
| 2699 | group IDs, but the extended header values were included for | |
| 2700 | completeness, allowing overrides for all of the decimal values in | |
| 2701 | the \fItar\fP header. | |
| 2702 | .LP | |
| 2703 | The standard developers intended to describe the effective results | |
| 2704 | of \fIpax\fP with regard to file ownerships and permissions; | |
| 2705 | implementations are not restricted in timing or sequencing the restoration | |
| 2706 | of such, provided the results are as specified. | |
| 2707 | .LP | |
| 2708 | Much of the text describing the extended headers refers to use in | |
| 2709 | " \fBwrite\fP or \fBcopy\fP modes". The \fBcopy\fP mode | |
| 2710 | references are due to the normative text: "The effect of the copy | |
| 2711 | shall be as if the copied files were written to an archive file | |
| 2712 | and then subsequently extracted ...". There is certainly no way to | |
| 2713 | test whether \fIpax\fP is actually generating the extended | |
| 2714 | headers in \fBcopy\fP mode, but the effects must be as if it had. | |
| 2715 | .SS pax Archive Character Set Encoding/Decoding | |
| 2716 | .LP | |
| 2717 | There is a need to exchange archives of files between systems of different | |
| 2718 | native codesets. Filenames, group names, and user | |
| 2719 | names must be preserved to the fullest extent possible when an archive | |
| 2720 | is read on the receiving platform. Translation of the | |
| 2721 | contents of files is not within the scope of the \fIpax\fP utility. | |
| 2722 | .LP | |
| 2723 | There will also be the need to represent characters that are not available | |
| 2724 | on the receiving platform. These unsupported | |
| 2725 | characters cannot be automatically folded to the local set of characters | |
| 2726 | due to the chance of collisions. This could result in | |
| 2727 | overwriting previous extracted files from the archive or pre-existing | |
| 2728 | files on the system. | |
| 2729 | .LP | |
| 2730 | For these reasons, the codeset used to represent characters within | |
| 2731 | the extended header records of the \fIpax\fP archive must be | |
| 2732 | sufficiently rich to handle all commonly used character sets. The | |
| 2733 | fields requiring translation include, at a minimum, filenames, | |
| 2734 | user names, group names, and link pathnames. Implementations may wish | |
| 2735 | to have localized extended keywords that use non-portable | |
| 2736 | characters. | |
| 2737 | .LP | |
| 2738 | The standard developers considered the following options: | |
| 2739 | .IP " *" 3 | |
| 2740 | The archive creator specifies the well-defined name of the source | |
| 2741 | codeset. The receiver must then recognize the codeset name and | |
| 2742 | perform the appropriate translations to the destination codeset. | |
| 2743 | .LP | |
| 2744 | .IP " *" 3 | |
| 2745 | The archive creator includes within the archive the character mapping | |
| 2746 | table for the source codeset used to encode extended | |
| 2747 | header records. The receiver must then read the character mapping | |
| 2748 | table and perform the appropriate translations to the destination | |
| 2749 | codeset. | |
| 2750 | .LP | |
| 2751 | .IP " *" 3 | |
| 2752 | The archive creator translates the extended header records in the | |
| 2753 | source codeset into a canonical form. The receiver must then | |
| 2754 | perform the appropriate translations to the destination codeset. | |
| 2755 | .LP | |
| 2756 | .LP | |
| 2757 | The approach that incorporates the name of the source codeset poses | |
| 2758 | the problem of codeset name registration, and makes the | |
| 2759 | archive useless to \fIpax\fP archive decoders that do not recognize | |
| 2760 | that codeset. | |
| 2761 | .LP | |
| 2762 | Because parts of an archive may be corrupted, the standard developers | |
| 2763 | felt that including the character map of the source | |
| 2764 | codeset was too fragile. The loss of this one key component could | |
| 2765 | result in making the entire archive useless. (The difference | |
| 2766 | between this and the global extended header decision was that the | |
| 2767 | latter has a workaround-duplicating extended header records on | |
| 2768 | unreliable media-but this would be too burdensome for large character | |
| 2769 | set maps.) | |
| 2770 | .LP | |
| 2771 | Both of the above approaches also put an undue burden on the \fIpax\fP | |
| 2772 | archive receiver to handle the cross-product of all | |
| 2773 | source and destination codesets. | |
| 2774 | .LP | |
| 2775 | To simplify the translation from the source codeset to the canonical | |
| 2776 | form and from the canonical form to the destination | |
| 2777 | codeset, the standard developers decided that the internal representation | |
| 2778 | should be a stateless encoding. A stateless encoding is | |
| 2779 | one where each codepoint has the same meaning, without regard to the | |
| 2780 | decoder being in a specific state. An example of a stateful | |
| 2781 | encoding would be the Japanese Shift-JIS; an example of a stateless | |
| 2782 | encoding would be the ISO/IEC\ 646:1991 standard | |
| 2783 | (equivalent to 7-bit ASCII). | |
| 2784 | .LP | |
| 2785 | For these reasons, the standard developers decided to adopt a canonical | |
| 2786 | format for the representation of file information | |
| 2787 | strings. The obvious, well-endorsed candidate is the ISO/IEC\ 10646-1:2000 | |
| 2788 | standard (based in part on Unicode), which can be | |
| 2789 | used to represent the characters of virtually all standardized character | |
| 2790 | sets. The standard developers initially agreed upon using | |
| 2791 | UCS2 (16-bit Unicode) as the internal representation. This repertoire | |
| 2792 | of characters provides a sufficiently rich set to represent | |
| 2793 | all commonly-used codesets. | |
| 2794 | .LP | |
| 2795 | However, the standard developers found that the 16-bit Unicode representation | |
| 2796 | had some problems. It forced the issue of | |
| 2797 | standardizing byte ordering. The 2-byte length of each character made | |
| 2798 | the extended header records twice as long for the case of | |
| 2799 | strings coded entirely from historical 7-bit ASCII. For these reasons, | |
| 2800 | the standard developers chose the UTF-8 defined in the | |
| 2801 | ISO/IEC\ 10646-1:2000 standard. This multi-byte representation encodes | |
| 2802 | UCS2 or UCS4 characters reliably and deterministically, | |
| 2803 | eliminating the need for a canonical byte ordering. In addition, NUL | |
| 2804 | octets and other characters possibly confusing to POSIX file | |
| 2805 | systems do not appear, except to represent themselves. It was realized | |
| 2806 | that certain national codesets take up more space after the | |
| 2807 | encoding, due to their placement within the UCS range; it was felt | |
| 2808 | that the usefulness of the encoding of the names outweighs the | |
| 2809 | disadvantage of size increase for file, user, and group names. | |
| 2810 | .LP | |
| 2811 | The encoding of UTF-8 is as follows: | |
| 2812 | .sp | |
| 2813 | .RS | |
| 2814 | .nf | |
| 2815 | ||
| 2816 | \fBUCS4 Hex Encoding UTF-8 Binary Encoding | |
| 2817 | .sp | |
| 2818 | ||
| 2819 | 00000000-0000007F 0xxxxxxx | |
| 2820 | 00000080-000007FF 110xxxxx 10xxxxxx | |
| 2821 | 00000800-0000FFFF 1110xxxx 10xxxxxx 10xxxxxx | |
| 2822 | 00010000-001FFFFF 11110xxx 10xxxxxx 10xxxxxx 10xxxxxx | |
| 2823 | 00200000-03FFFFFF 111110xx 10xxxxxx 10xxxxxx 10xxxxxx 10xxxxxx | |
| 2824 | 04000000-7FFFFFFF 1111110x 10xxxxxx 10xxxxxx 10xxxxxx 10xxxxxx 10xxxxxx | |
| 2825 | \fP | |
| 2826 | .fi | |
| 2827 | .RE | |
| 2828 | .LP | |
| 2829 | where each \fB'x'\fP represents a bit value from the character being | |
| 2830 | translated. | |
| 2831 | .SS ustar Interchange Format | |
| 2832 | .LP | |
| 2833 | The description of the \fBustar\fP format reflects numerous enhancements | |
| 2834 | over pre-1988 versions of the historical \fItar\fP | |
| 2835 | utility. The goal of these changes was not only to provide the functional | |
| 2836 | enhancements desired, but also to retain compatibility | |
| 2837 | between new and old versions. This compatibility has been retained. | |
| 2838 | Archives written using the old archive format are compatible | |
| 2839 | with the new format. | |
| 2840 | .LP | |
| 2841 | Implementors should be aware that the previous file format did not | |
| 2842 | include a mechanism to archive directory type files. For this | |
| 2843 | reason, the convention of using a filename ending with slash was adopted | |
| 2844 | to specify a directory on the archive. | |
| 2845 | .LP | |
| 2846 | The total size of the \fIname\fP and \fIprefix\fP fields have been | |
| 2847 | set to meet the minimum requirements for {PATH_MAX}. If a | |
| 2848 | pathname will fit within the \fIname\fP field, it is recommended that | |
| 2849 | the pathname be stored there without the use of the | |
| 2850 | \fIprefix\fP field. Although the name field is known to be too small | |
| 2851 | to contain {PATH_MAX} characters, the value was not changed | |
| 2852 | in this version of the archive file format to retain backwards-compatibility, | |
| 2853 | and instead the prefix was introduced. Also, because | |
| 2854 | of the earlier version of the format, there is no way to remove the | |
| 2855 | restriction on the \fIlinkname\fP field being limited in size | |
| 2856 | to just that of the \fIname\fP field. | |
| 2857 | .LP | |
| 2858 | The \fIsize\fP field is required to be meaningful in all implementation | |
| 2859 | extensions, although it could be zero. This is required | |
| 2860 | so that the data blocks can always be properly counted. | |
| 2861 | .LP | |
| 2862 | It is suggested that if device special files need to be represented | |
| 2863 | that cannot be represented in the standard format, that one | |
| 2864 | of the extension types ( \fBA\fP- \fBZ\fP) be used, and that the additional | |
| 2865 | information for the special file be represented as | |
| 2866 | data and be reflected in the \fIsize\fP field. | |
| 2867 | .LP | |
| 2868 | Attempting to restore a special file type, where it is converted to | |
| 2869 | ordinary data and conflicts with an existing filename, need | |
| 2870 | not be specially detected by the utility. If run as an ordinary user, | |
| 2871 | \fIpax\fP should not be able to overwrite the entries in, | |
| 2872 | for example, \fB/dev\fP in any case (whether the file is converted | |
| 2873 | to another type or not). If run as a privileged user, it should | |
| 2874 | be able to do so, and it would be considered a bug if it did not. | |
| 2875 | The same is true of ordinary data files and similarly named | |
| 2876 | special files; it is impossible to anticipate the needs of the user | |
| 2877 | (who could really intend to overwrite the file), so the | |
| 2878 | behavior should be predictable (and thus regular) and rely on the | |
| 2879 | protection system as required. | |
| 2880 | .LP | |
| 2881 | The value 7 in the \fItypeflag\fP field is intended to define how | |
| 2882 | contiguous files can be stored in a \fBustar\fP archive. | |
| 2883 | IEEE\ Std\ 1003.1-2001 does not require the contiguous file extension, | |
| 2884 | but does define a standard way of archiving such | |
| 2885 | files so that all conforming systems can interpret these file types | |
| 2886 | in a meaningful and consistent manner. On a system that does | |
| 2887 | not support extended file types, the \fIpax\fP utility should do the | |
| 2888 | best it can with the file and go on to the next. | |
| 2889 | .LP | |
| 2890 | The file protection modes are those conventionally used by the \fIls\fP | |
| 2891 | utility. This is | |
| 2892 | extended beyond the usage in the ISO\ POSIX-2 standard to support | |
| 2893 | the "shared text" or "sticky" bit. It is intended that | |
| 2894 | the conformance document should not document anything beyond the existence | |
| 2895 | of and support of such a mode. Further extensions are | |
| 2896 | expected to these bits, particularly with overloading the set-user-ID | |
| 2897 | and set-group-ID flags. | |
| 2898 | .SS cpio Interchange Format | |
| 2899 | .LP | |
| 2900 | The reference to appropriate privilege in the \fBcpio\fP format refers | |
| 2901 | to an error on standard output; the \fBustar\fP format | |
| 2902 | does not make comparable statements. | |
| 2903 | .LP | |
| 2904 | The model for this format was the historical System V \fIcpio\fP \fB-c\fP | |
| 2905 | data interchange format. This model documents the | |
| 2906 | portable version of the \fBcpio\fP format and not the binary version. | |
| 2907 | It has the flexibility to transfer data of any type | |
| 2908 | described within IEEE\ Std\ 1003.1-2001, yet is extensible to transfer | |
| 2909 | data types specific to extensions beyond | |
| 2910 | IEEE\ Std\ 1003.1-2001 (for example, contiguous files). Because it | |
| 2911 | describes existing practice, there is no question of | |
| 2912 | maintaining upwards-compatibility. | |
| 2913 | .SS cpio Header | |
| 2914 | .LP | |
| 2915 | There has been some concern that the size of the \fIc_ino\fP field | |
| 2916 | of the header is too small to handle those systems that have | |
| 2917 | very large \fIinode\fP numbers. However, the \fIc_ino\fP field in | |
| 2918 | the header is used strictly as a hard-link resolution mechanism | |
| 2919 | for archives. It is not necessarily the same value as the \fIinode\fP | |
| 2920 | number of the file in the location from which that file is | |
| 2921 | extracted. | |
| 2922 | .LP | |
| 2923 | The name \fIc_magic\fP is based on historical usage. | |
| 2924 | .SS cpio Filename | |
| 2925 | .LP | |
| 2926 | For most historical implementations of the \fIcpio\fP utility, {PATH_MAX} | |
| 2927 | octets can be used to describe the pathname without | |
| 2928 | the addition of any other header fields (the NUL character would be | |
| 2929 | included in this count). {PATH_MAX} is the minimum value for | |
| 2930 | pathname size, documented as 256 bytes. However, an implementation | |
| 2931 | may use \fIc_namesize\fP to determine the exact length of the | |
| 2932 | pathname. With the current description of the \fI<cpio.h>\fP header, | |
| 2933 | this pathname | |
| 2934 | size can be as large as a number that is described in six octal digits. | |
| 2935 | .LP | |
| 2936 | Two values are documented under the \fIc_mode\fP field values to provide | |
| 2937 | for extensibility for known file types: | |
| 2938 | .TP 7 | |
| 2939 | \fB0110\ 000\fP | |
| 2940 | Reserved for contiguous files. The implementation may treat the rest | |
| 2941 | of the information for this archive like a regular file. | |
| 2942 | If this file type is undefined, the implementation may create the | |
| 2943 | file as a regular file. | |
| 2944 | .sp | |
| 2945 | .LP | |
| 2946 | This provides for extensibility of the \fBcpio\fP format while allowing | |
| 2947 | for the ability to read old archives. Files of an | |
| 2948 | unknown type may be read as "regular files" on some implementations. | |
| 2949 | On a system that does not support extended file types, the | |
| 2950 | \fIpax\fP utility should do the best it can with the file and go on | |
| 2951 | to the next. | |
| 2952 | .SH FUTURE DIRECTIONS | |
| 2953 | .LP | |
| 2954 | None. | |
| 2955 | .SH SEE ALSO | |
| 2956 | .LP | |
| 2957 | \fIShell Command Language\fP , \fIcp\fP , \fIed\fP , \fIgetopts\fP | |
| 2958 | , \fIls\fP , \fIprintf\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, | |
| 2959 | \fI<cpio.h>\fP, the System Interfaces volume of IEEE\ Std\ 1003.1-2001, | |
| 2960 | \fIchown\fP(), \fIcreat\fP(), \fImkdir\fP(), \fImkfifo\fP(), \fIstat\fP(), | |
| 2961 | \fIutime\fP(), \fIwrite\fP() | |
| 2962 | .SH COPYRIGHT | |
| 2963 | Portions of this text are reprinted and reproduced in electronic form | |
| 2964 | from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology | |
| 2965 | -- Portable Operating System Interface (POSIX), The Open Group Base | |
| 2966 | Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of | |
| 2967 | Electrical and Electronics Engineers, Inc and The Open Group. In the | |
| 2968 | event of any discrepancy between this version and the original IEEE and | |
| 2969 | The Open Group Standard, the original IEEE and The Open Group Standard | |
| 2970 | is the referee document. The original Standard can be obtained online at | |
| 2971 | http://www.opengroup.org/unix/online.html . |
| 0 | <?xml version="1.0" encoding="ISO-8859-1"?> | |
| 1 | <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" | |
| 2 | "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"> | |
| 3 | <!-- lifted from man+troff by doclifter --> | |
| 4 | <refentry> | |
| 5 | <refentryinfo><date>2011-09-28</date></refentryinfo> | |
| 6 | <refmeta> | |
| 7 | <refentrytitle>PRINTF</refentrytitle> | |
| 8 | <manvolnum>3</manvolnum> | |
| 9 | <refmiscinfo class='date'>2011-09-28</refmiscinfo> | |
| 10 | <refmiscinfo class='source'>GNU</refmiscinfo> | |
| 11 | <refmiscinfo class='manual'>Linux Programmer's Manual</refmiscinfo> | |
| 12 | </refmeta> | |
| 13 | <refnamediv> | |
| 14 | <refname>printf</refname> | |
| 15 | <refname>fprintf</refname> | |
| 16 | <refname>sprintf</refname> | |
| 17 | <refname>snprintf</refname> | |
| 18 | <refname>vprintf</refname> | |
| 19 | <refname>vfprintf</refname> | |
| 20 | <refname>vsprintf</refname> | |
| 21 | <refname>vsnprintf</refname> | |
| 22 | <refpurpose>formatted output conversion</refpurpose> | |
| 23 | </refnamediv> | |
| 24 | <!-- body begins here --> | |
| 25 | ||
| 26 | <refsect1 id='description'><title>DESCRIPTION</title> | |
| 27 | <para>This is a stripped manpage intended to test a common evaluation case | |
| 28 | of the \w conditiol in groff.</para> | |
| 29 | </refsect1> | |
| 30 | ||
| 31 | <refsect1 id='example'><title>EXAMPLE</title> | |
| 32 | <para>To print pi to five decimal places:</para> | |
| 33 | </refsect1> | |
| 34 | </refentry> | |
| 35 |
| 0 | .TH PRINTF 3 2011-09-28 "GNU" "Linux Programmer's Manual" | |
| 1 | .SH NAME | |
| 2 | printf, fprintf, sprintf, snprintf, vprintf, vfprintf, vsprintf, | |
| 3 | vsnprintf \- formatted output conversion | |
| 4 | .SH DESCRIPTION | |
| 5 | This is a stripped manpage intended to test a common evaluation case | |
| 6 | of the \\w conditiol in groff. | |
| 7 | .SH EXAMPLE | |
| 8 | .if \w'\*(Pi'=0 .ds Pi pi | |
| 9 | To print \*(Pi to five decimal places: |
| 0 | <?xml version="1.0" encoding="ISO-8859-1"?> | |
| 1 | <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" | |
| 2 | "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"> | |
| 3 | <!-- lifted from mdoc+troff by doclifter --> | |
| 4 | <refentry> | |
| 5 | <!-- Seriously reduced subsection of sudoers.5 to test .Bl \-literal --> | |
| 6 | ||
| 7 | ||
| 8 | <refmeta> | |
| 9 | <refentrytitle>SUDOERS</refentrytitle> | |
| 10 | <manvolnum>5</manvolnum> | |
| 11 | </refmeta> | |
| 12 | ||
| 13 | <refnamediv id='purpose'> | |
| 14 | <refname> sudoers </refname> | |
| 15 | <refpurpose> default sudo security policy module </refpurpose> | |
| 16 | </refnamediv> | |
| 17 | <!-- body begins here --> | |
| 18 | ||
| 19 | <refsect1 id='description'><title>DESCRIPTION</title> | |
| 20 | ||
| 21 | <para>Would match any file name beginning with a letter.</para> | |
| 22 | ||
| 23 | <para>Note that a forward slash | |
| 24 | (Ql /) | |
| 25 | will | |
| 26 | <emphasis remap="Sy">not</emphasis> | |
| 27 | be matched by | |
| 28 | wildcards used in the path name. | |
| 29 | This is to make a path like:</para> | |
| 30 | <programlisting remap='Bd'> | |
| 31 | <filename>/usr/bin/*</filename> | |
| 32 | </programlisting> <!-- remap='Ed (block)' --> | |
| 33 | ||
| 34 | <para>match | |
| 35 | <filename>/usr/bin/who</filename> | |
| 36 | but not | |
| 37 | <filename>/usr/bin/X11/xterm</filename>.</para> | |
| 38 | </refsect1> | |
| 39 | </refentry> | |
| 40 |
| 0 | .\" Seriously reduced subsection of sudoers.5 to test .Bl -literal | |
| 1 | .Dd July 16, 2012 | |
| 2 | .Dt SUDOERS 5 | |
| 3 | .Os Sudo 1.8.6p3 | |
| 4 | .Sh NAME | |
| 5 | .Nm sudoers | |
| 6 | .Nd default sudo security policy module | |
| 7 | .Sh DESCRIPTION | |
| 8 | .Pp | |
| 9 | Would match any file name beginning with a letter. | |
| 10 | .Pp | |
| 11 | Note that a forward slash | |
| 12 | .Pq Ql / | |
| 13 | will | |
| 14 | .Sy not | |
| 15 | be matched by | |
| 16 | wildcards used in the path name. | |
| 17 | This is to make a path like: | |
| 18 | .Bd -literal -offset 4n | |
| 19 | /usr/bin/* | |
| 20 | .Ed | |
| 21 | .Pp | |
| 22 | match | |
| 23 | .Pa /usr/bin/who | |
| 24 | but not | |
| 25 | .Pa /usr/bin/X11/xterm . |
| 0 | <?xml version="1.0" encoding="ISO-8859-1"?> | |
| 1 | <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" | |
| 2 | "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"> | |
| 3 | <!-- lifted from mdoc+troff by doclifter --> | |
| 4 | <refentry> | |
| 5 | ||
| 6 | ||
| 7 | <refmeta> | |
| 8 | <refentrytitle>MORE(1)</refentrytitle> | |
| 9 | <manvolnum></manvolnum> | |
| 10 | </refmeta> | |
| 11 | ||
| 12 | <refnamediv id='purpose'> | |
| 13 | <refname> more </refname> | |
| 14 | <refpurpose> file perusal filter for crt viewing </refpurpose> | |
| 15 | </refnamediv> | |
| 16 | <!-- body begins here --> | |
| 17 | ||
| 18 | <refsect1 id='description'><title>DESCRIPTION</title> | |
| 19 | <para>This is a partial manual page stripped down to exhibit translation of | |
| 20 | the Xo and Xc macros.</para> | |
| 21 | <variablelist remap='Bl -tag -width Ic'> | |
| 22 | <varlistentry> | |
| 23 | <term><command remap='Ic'>h</command> or <command remap='Ic'>?</command></term> | |
| 24 | <listitem> | |
| 25 | <para>Help: display a summary of these commands. | |
| 26 | If you forget all the other commands, remember this one.</para> | |
| 27 | </listitem> | |
| 28 | </varlistentry> | |
| 29 | <varlistentry> | |
| 30 | <term><command remap='Ic'>SPACE</command></term> | |
| 31 | <listitem> | |
| 32 | <para>Display next k lines of text. Defaults to current screen size.</para> | |
| 33 | </listitem> | |
| 34 | </varlistentry> | |
| 35 | <varlistentry> | |
| 36 | <term><command remap='Ic'>z</command></term> | |
| 37 | <listitem> | |
| 38 | <para>Display next k lines of text. Defaults to current screen size. Argument | |
| 39 | becomes new default.</para> | |
| 40 | </listitem> | |
| 41 | </varlistentry> | |
| 42 | <varlistentry> | |
| 43 | <term><command remap='Ic'>RETURN</command></term> | |
| 44 | <listitem> | |
| 45 | <para>Display next k lines of text. Defaults to 1. Argument becomes new | |
| 46 | default.</para> | |
| 47 | </listitem> | |
| 48 | </varlistentry> | |
| 49 | <varlistentry> | |
| 50 | <term><command remap='Ic'>d</command> or <command remap='Ic'>^D</command></term> | |
| 51 | <listitem> | |
| 52 | <para>Scroll k lines. Default is current scroll size, initially 11. Argument | |
| 53 | becomes new default.</para> | |
| 54 | </listitem> | |
| 55 | </varlistentry> | |
| 56 | <varlistentry> | |
| 57 | <term><command remap='Ic'>q</command> or <command remap='Ic'>Q</command> or <command remap='Ic'>INTERRUPT</command></term> | |
| 58 | <listitem> | |
| 59 | <para>Exit.</para> | |
| 60 | </listitem> | |
| 61 | </varlistentry> | |
| 62 | </variablelist> | |
| 63 | </refsect1> | |
| 64 | </refentry> | |
| 65 |
| 0 | .Dt MORE(1) "" "User Commands" | |
| 1 | .Os util-linux | |
| 2 | .Sh NAME | |
| 3 | .Nm more | |
| 4 | .Nd file perusal filter for crt viewing | |
| 5 | .Sh DESCRIPTION | |
| 6 | This is a partial manual page stripped down to exhibit translation of | |
| 7 | the Xo and Xc macros. | |
| 8 | .Bl -tag -width Ic | |
| 9 | .It Ic h No or Ic ? | |
| 10 | Help: display a summary of these commands. | |
| 11 | If you forget all the other commands, remember this one. | |
| 12 | .It Ic SPACE | |
| 13 | Display next k lines of text. Defaults to current screen size. | |
| 14 | .It Ic z | |
| 15 | Display next k lines of text. Defaults to current screen size. Argument | |
| 16 | becomes new default. | |
| 17 | .It Ic RETURN | |
| 18 | Display next k lines of text. Defaults to 1. Argument becomes new | |
| 19 | default. | |
| 20 | .It Ic d No or Ic \&^D | |
| 21 | Scroll k lines. Default is current scroll size, initially 11. Argument | |
| 22 | becomes new default. | |
| 23 | .It Xo | |
| 24 | .Ic q | |
| 25 | .No or | |
| 26 | .Ic Q | |
| 27 | .No or | |
| 28 | .Ic INTERRUPT | |
| 29 | .Xc | |
| 30 | Exit. | |
| 31 | .El |