1.\" $OpenBSD: mdoc.7,v 1.184 2024/06/17 15:35:33 schwarze Exp $ 2.\" 3.\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv> 4.\" Copyright (c) 2010, 2011, 2013-2020 Ingo Schwarze <schwarze@openbsd.org> 5.\" 6.\" Permission to use, copy, modify, and distribute this software for any 7.\" purpose with or without fee is hereby granted, provided that the above 8.\" copyright notice and this permission notice appear in all copies. 9.\" 10.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 11.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 12.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 13.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 14.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 15.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 16.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 17.\" 18.Dd $Mdocdate: June 17 2024 $ 19.Dt MDOC 7 20.Os 21.Sh NAME 22.Nm mdoc 23.Nd semantic markup language for formatting manual pages 24.Sh DESCRIPTION 25The 26.Nm mdoc 27language supports authoring of manual pages for the 28.Xr man 1 29utility by allowing semantic annotations of words, phrases, 30page sections and complete manual pages. 31Such annotations are used by formatting tools to achieve a uniform 32presentation across all manuals written in 33.Nm , 34and to support hyperlinking if supported by the output medium. 35.Pp 36This reference document describes the structure of manual pages 37and the syntax and usage of the 38.Nm 39language. 40The reference implementation of a parsing and formatting tool is 41.Xr mandoc 1 ; 42the 43.Sx COMPATIBILITY 44section describes compatibility with other implementations. 45.Pp 46In an 47.Nm 48document, lines beginning with the control character 49.Sq \&. 50are called 51.Dq macro lines . 52The first word is the macro name. 53It consists of two or three letters. 54Most macro names begin with a capital letter. 55For a list of available macros, see 56.Sx MACRO OVERVIEW . 57The words following the macro name are arguments to the macro, optionally 58including the names of other, callable macros; see 59.Sx MACRO SYNTAX 60for details. 61.Pp 62Lines not beginning with the control character are called 63.Dq text lines . 64They provide free-form text to be printed; the formatting of the text 65depends on the respective processing context: 66.Bd -literal -offset indent 67\&.Sh Macro lines change control state. 68Text lines are interpreted within the current state. 69.Ed 70.Pp 71Many aspects of the basic syntax of the 72.Nm 73language are based on the 74.Xr roff 7 75language; see the 76.Em LANGUAGE SYNTAX 77and 78.Em MACRO SYNTAX 79sections in the 80.Xr roff 7 81manual for details, in particular regarding 82comments, escape sequences, whitespace, and quoting. 83However, using 84.Xr roff 7 85requests in 86.Nm 87documents is discouraged; 88.Xr mandoc 1 89supports some of them merely for backward compatibility. 90.Sh MANUAL STRUCTURE 91A well-formed 92.Nm 93document consists of a document prologue followed by one or more 94sections. 95.Pp 96The prologue, which consists of the 97.Ic \&Dd , 98.Ic \&Dt , 99and 100.Ic \&Os 101macros in that order, is required for every document. 102.Pp 103The first section (sections are denoted by 104.Ic \&Sh ) 105must be the NAME section, consisting of at least one 106.Ic \&Nm 107followed by 108.Ic \&Nd . 109.Pp 110Following that, convention dictates specifying at least the 111.Em SYNOPSIS 112and 113.Em DESCRIPTION 114sections, although this varies between manual sections. 115.Pp 116The following is a well-formed skeleton 117.Nm 118file for a utility 119.Qq progname : 120.Bd -literal -offset indent 121\&.Dd $\&Mdocdate$ 122\&.Dt PROGNAME section 123\&.Os 124\&.Sh NAME 125\&.Nm progname 126\&.Nd one line about what it does 127\&.\e\(dq .Sh LIBRARY 128\&.\e\(dq For sections 2, 3, and 9 only. 129\&.\e\(dq Not used in OpenBSD. 130\&.Sh SYNOPSIS 131\&.Nm progname 132\&.Op Fl options 133\&.Ar 134\&.Sh DESCRIPTION 135The 136\&.Nm 137utility processes files ... 138\&.\e\(dq .Sh CONTEXT 139\&.\e\(dq For section 9 functions only. 140\&.\e\(dq .Sh IMPLEMENTATION NOTES 141\&.\e\(dq Not used in OpenBSD. 142\&.\e\(dq .Sh RETURN VALUES 143\&.\e\(dq For sections 2, 3, and 9 function return values only. 144\&.\e\(dq .Sh ENVIRONMENT 145\&.\e\(dq For sections 1, 6, 7, and 8 only. 146\&.\e\(dq .Sh FILES 147\&.\e\(dq .Sh EXIT STATUS 148\&.\e\(dq For sections 1, 6, and 8 only. 149\&.\e\(dq .Sh EXAMPLES 150\&.\e\(dq .Sh DIAGNOSTICS 151\&.\e\(dq For sections 1, 4, 6, 7, 8, and 9 printf/stderr messages only. 152\&.\e\(dq .Sh ERRORS 153\&.\e\(dq For sections 2, 3, 4, and 9 errno settings only. 154\&.\e\(dq .Sh SEE ALSO 155\&.\e\(dq .Xr foobar 1 156\&.\e\(dq .Sh STANDARDS 157\&.\e\(dq .Sh HISTORY 158\&.\e\(dq .Sh AUTHORS 159\&.\e\(dq .Sh CAVEATS 160\&.\e\(dq .Sh BUGS 161\&.\e\(dq .Sh SECURITY CONSIDERATIONS 162\&.\e\(dq Not used in OpenBSD. 163.Ed 164.Pp 165The sections in an 166.Nm 167document are conventionally ordered as they appear above. 168Sections should be composed as follows: 169.Bl -ohang -offset Ds 170.It Em NAME 171The name(s) and a one line description of the documented material. 172The syntax for this as follows: 173.Bd -literal -offset indent 174\&.Nm name0 , 175\&.Nm name1 , 176\&.Nm name2 177\&.Nd a one line description 178.Ed 179.Pp 180Multiple 181.Sq \&Nm 182names should be separated by commas. 183.Pp 184The 185.Ic \&Nm 186macro(s) must precede the 187.Ic \&Nd 188macro. 189.Pp 190See 191.Ic \&Nm 192and 193.Ic \&Nd . 194.It Em LIBRARY 195The name of the library containing the documented material, which is 196assumed to be a function in a section 2, 3, or 9 manual. 197The syntax for this is as follows: 198.Bd -literal -offset indent 199\&.Lb libarm 200.Ed 201.Pp 202See 203.Ic \&Lb . 204.It Em SYNOPSIS 205Documents the utility invocation syntax, function call syntax, or device 206configuration. 207.Pp 208For the first, utilities (sections 1, 6, and 8), this is 209generally structured as follows: 210.Bd -literal -offset indent 211\&.Nm bar 212\&.Op Fl v 213\&.Op Fl o Ar file 214\&.Op Ar 215\&.Nm foo 216\&.Op Fl v 217\&.Op Fl o Ar file 218\&.Op Ar 219.Ed 220.Pp 221Commands should be ordered alphabetically. 222.Pp 223For the second, function calls (sections 2, 3, 9): 224.Bd -literal -offset indent 225\&.In header.h 226\&.Vt extern const char *global; 227\&.Ft "char *" 228\&.Fn foo "const char *src" 229\&.Ft "char *" 230\&.Fn bar "const char *src" 231.Ed 232.Pp 233Ordering of 234.Ic \&In , 235.Ic \&Vt , 236.Ic \&Fn , 237and 238.Ic \&Fo 239macros should follow C header-file conventions. 240.Pp 241And for the third, configurations (section 4): 242.Bd -literal -offset indent 243\&.Cd \(dqit* at isa? port 0x2e\(dq 244\&.Cd \(dqit* at isa? port 0x4e\(dq 245.Ed 246.Pp 247Manuals not in these sections generally don't need a 248.Em SYNOPSIS . 249.Pp 250Some macros are displayed differently in the 251.Em SYNOPSIS 252section, particularly 253.Ic \&Nm , 254.Ic \&Cd , 255.Ic \&Fd , 256.Ic \&Fn , 257.Ic \&Fo , 258.Ic \&In , 259.Ic \&Vt , 260and 261.Ic \&Ft . 262All of these macros are output on their own line. 263If two such dissimilar macros are pairwise invoked (except for 264.Ic \&Ft 265before 266.Ic \&Fo 267or 268.Ic \&Fn ) , 269they are separated by a vertical space, unless in the case of 270.Ic \&Fo , 271.Ic \&Fn , 272and 273.Ic \&Ft , 274which are always separated by vertical space. 275.Pp 276When text and macros following an 277.Ic \&Nm 278macro starting an input line span multiple output lines, 279all output lines but the first will be indented to align 280with the text immediately following the 281.Ic \&Nm 282macro, up to the next 283.Ic \&Nm , 284.Ic \&Sh , 285or 286.Ic \&Ss 287macro or the end of an enclosing block, whichever comes first. 288.It Em DESCRIPTION 289This begins with an expansion of the brief, one line description in 290.Em NAME : 291.Bd -literal -offset indent 292The 293\&.Nm 294utility does this, that, and the other. 295.Ed 296.Pp 297It usually follows with a breakdown of the options (if documenting a 298command), such as: 299.Bd -literal -offset indent 300The options are as follows: 301\&.Bl \-tag \-width Ds 302\&.It Fl v 303Print verbose information. 304\&.El 305.Ed 306.Pp 307List the options in alphabetical order, 308uppercase before lowercase for each letter and 309with no regard to whether an option takes an argument. 310Put digits in ascending order before all letter options. 311.Pp 312Manuals not documenting a command won't include the above fragment. 313.Pp 314Since the 315.Em DESCRIPTION 316section usually contains most of the text of a manual, longer manuals 317often use the 318.Ic \&Ss 319macro to form subsections. 320In very long manuals, the 321.Em DESCRIPTION 322may be split into multiple sections, each started by an 323.Ic \&Sh 324macro followed by a non-standard section name, and each having 325several subsections, like in the present 326.Nm 327manual. 328.It Em CONTEXT 329This section lists the contexts in which functions can be called in section 9. 330The contexts are autoconf, process, or interrupt. 331.It Em IMPLEMENTATION NOTES 332Implementation-specific notes should be kept here. 333This is useful when implementing standard functions that may have side 334effects or notable algorithmic implications. 335.It Em RETURN VALUES 336This section documents the 337return values of functions in sections 2, 3, and 9. 338.Pp 339See 340.Ic \&Rv . 341.It Em ENVIRONMENT 342Lists the environment variables used by the utility, 343and explains the syntax and semantics of their values. 344The 345.Xr environ 7 346manual provides examples of typical content and formatting. 347.Pp 348See 349.Ic \&Ev . 350.It Em FILES 351Documents files used. 352It's helpful to document both the file name and a short description of how 353the file is used (created, modified, etc.). 354.Pp 355See 356.Ic \&Pa . 357.It Em EXIT STATUS 358This section documents the 359command exit status for section 1, 6, and 8 utilities. 360Historically, this information was described in 361.Em DIAGNOSTICS , 362a practise that is now discouraged. 363.Pp 364See 365.Ic \&Ex . 366.It Em EXAMPLES 367Example usages. 368This often contains snippets of well-formed, well-tested invocations. 369Make sure that examples work properly! 370.It Em DIAGNOSTICS 371Documents error messages. 372In section 4 and 9 manuals, these are usually messages printed by the 373kernel to the console and to the kernel log. 374In section 1, 6, 7, and 8, these are usually messages printed by 375userland programs to the standard error output. 376.Pp 377Historically, this section was used in place of 378.Em EXIT STATUS 379for manuals in sections 1, 6, and 8; however, this practise is 380discouraged. 381.Pp 382See 383.Ic \&Bl 384.Fl diag . 385.It Em ERRORS 386Documents 387.Xr errno 2 388settings in sections 2, 3, 4, and 9. 389.Pp 390See 391.Ic \&Er . 392.It Em SEE ALSO 393References other manuals with related topics. 394This section should exist for most manuals. 395Cross-references should conventionally be ordered first by section, then 396alphabetically (ignoring case). 397.Pp 398References to other documentation concerning the topic of the manual page, 399for example authoritative books or journal articles, may also be 400provided in this section. 401.Pp 402See 403.Ic \&Rs 404and 405.Ic \&Xr . 406.It Em STANDARDS 407References any standards implemented or used. 408If not adhering to any standards, the 409.Em HISTORY 410section should be used instead. 411.Pp 412See 413.Ic \&St . 414.It Em HISTORY 415A brief history of the subject, including where it was first implemented, 416and when it was ported to or reimplemented for the operating system at hand. 417.It Em AUTHORS 418Credits to the person or persons who wrote the code and/or documentation. 419Authors should generally be noted by both name and email address. 420.Pp 421See 422.Ic \&An . 423.It Em CAVEATS 424Common misuses and misunderstandings should be explained 425in this section. 426.It Em BUGS 427Known bugs, limitations, and work-arounds should be described 428in this section. 429.It Em SECURITY CONSIDERATIONS 430Documents any security precautions that operators should consider. 431.El 432.Sh MACRO OVERVIEW 433This overview is sorted such that macros of similar purpose are listed 434together, to help find the best macro for any given purpose. 435Deprecated macros are not included in the overview, but can be found below 436in the alphabetical 437.Sx MACRO REFERENCE . 438.Ss Document preamble and NAME section macros 439.Bl -column "Brq, Bro, Brc" description 440.It Ic \&Dd Ta document date: Cm $\&Mdocdate$ | Ar month day , year 441.It Ic \&Dt Ta document title: Ar TITLE section Op Ar arch 442.It Ic \&Os Ta operating system footer: Op Ar footer text 443.It Ic \&Nm Ta document name (one argument) 444.It Ic \&Nd Ta document description (one line) 445.El 446.Ss Sections and cross references 447.Bl -column "Brq, Bro, Brc" description 448.It Ic \&Sh Ta section header (one line) 449.It Ic \&Ss Ta subsection header (one line) 450.It Ic \&Sx Ta internal cross reference to a section or subsection 451.It Ic \&Xr Ta cross reference to another manual page: Ar name section 452.It Ic \&Tg Ta tag the definition of a Ar term Pq <= 1 arguments 453.It Ic \&Pp Ta start a text paragraph (no arguments) 454.El 455.Ss Displays and lists 456.Bl -column "Brq, Bro, Brc" description 457.It Ic \&Bd , \&Ed Ta display block: 458.Fl Ar type 459.Op Fl offset Ar width 460.Op Fl compact 461.It Ic \&D1 Ta indented display (one line) 462.It Ic \&Dl Ta indented literal display (one line) 463.It Ic \&Ql Ta in-line literal display: Ql text 464.It Ic \&Bl , \&El Ta list block: 465.Fl Ar type 466.Op Fl width Ar val 467.Op Fl offset Ar val 468.Op Fl compact 469.It Ic \&It Ta list item (syntax depends on Fl Ar type ) 470.It Ic \&Ta Ta table cell separator in Ic \&Bl Fl column No lists 471.It Ic \&Rs , \&%* , \&Re Ta bibliographic block (references) 472.El 473.Ss Spacing control 474.Bl -column "Brq, Bro, Brc" description 475.It Ic \&Pf Ta prefix, no following horizontal space (one argument) 476.It Ic \&Ns Ta roman font, no preceding horizontal space (no arguments) 477.It Ic \&Ap Ta apostrophe without surrounding whitespace (no arguments) 478.It Ic \&Sm Ta switch horizontal spacing mode: Op Cm on | off 479.It Ic \&Bk , \&Ek Ta keep block: Fl words 480.El 481.Ss Semantic markup for command line utilities 482.Bl -column "Brq, Bro, Brc" description 483.It Ic \&Nm Ta start a SYNOPSIS block with the name of a utility 484.It Ic \&Fl Ta command line options (flags) (>=0 arguments) 485.It Ic \&Cm Ta command modifier (>0 arguments) 486.It Ic \&Ar Ta command arguments (>=0 arguments) 487.It Ic \&Op , \&Oo , \&Oc Ta optional syntax elements (enclosure) 488.It Ic \&Ic Ta internal or interactive command (>0 arguments) 489.It Ic \&Ev Ta environmental variable (>0 arguments) 490.It Ic \&Pa Ta file system path (>=0 arguments) 491.El 492.Ss Semantic markup for function libraries 493.Bl -column "Brq, Bro, Brc" description 494.It Ic \&Lb Ta function library (one argument) 495.It Ic \&In Ta include file (one argument) 496.It Ic \&Fd Ta other preprocessor directive (>0 arguments) 497.It Ic \&Ft Ta function type (>0 arguments) 498.It Ic \&Fo , \&Fc Ta function block: Ar funcname 499.It Ic \&Fn Ta function name: Ar funcname Op Ar argument ... 500.It Ic \&Fa Ta function argument (>0 arguments) 501.It Ic \&Vt Ta variable type (>0 arguments) 502.It Ic \&Va Ta variable name (>0 arguments) 503.It Ic \&Dv Ta defined variable or preprocessor constant (>0 arguments) 504.It Ic \&Er Ta error constant (>0 arguments) 505.It Ic \&Ev Ta environmental variable (>0 arguments) 506.El 507.Ss Various semantic markup 508.Bl -column "Brq, Bro, Brc" description 509.It Ic \&An Ta author name (>0 arguments) 510.It Ic \&Lk Ta hyperlink: Ar uri Op Ar display_name 511.It Ic \&Mt Ta Do mailto Dc hyperlink: Ar localpart Ns @ Ns Ar domain 512.It Ic \&Cd Ta kernel configuration declaration (>0 arguments) 513.It Ic \&Ad Ta memory address (>0 arguments) 514.It Ic \&Ms Ta mathematical symbol (>0 arguments) 515.El 516.Ss Physical markup 517.Bl -column "Brq, Bro, Brc" description 518.It Ic \&Em Ta italic font or underline (emphasis) (>0 arguments) 519.It Ic \&Sy Ta boldface font (symbolic) (>0 arguments) 520.It Ic \&No Ta return to roman font (normal) (>0 arguments) 521.It Ic \&Bf , \&Ef Ta font block: Fl Ar type | Cm \&Em | \&Li | \&Sy 522.El 523.Ss Physical enclosures 524.Bl -column "Brq, Bro, Brc" description 525.It Ic \&Dq , \&Do , \&Dc Ta enclose in typographic double quotes: Dq text 526.It Ic \&Qq , \&Qo , \&Qc Ta enclose in typewriter double quotes: Qq text 527.It Ic \&Sq , \&So , \&Sc Ta enclose in single quotes: Sq text 528.It Ic \&Pq , \&Po , \&Pc Ta enclose in parentheses: Pq text 529.It Ic \&Bq , \&Bo , \&Bc Ta enclose in square brackets: Bq text 530.It Ic \&Brq , \&Bro , \&Brc Ta enclose in curly braces: Brq text 531.It Ic \&Aq , \&Ao , \&Ac Ta enclose in angle brackets: Aq text 532.It Ic \&Eo , \&Ec Ta generic enclosure 533.El 534.Ss Text production 535.Bl -column "Brq, Bro, Brc" description 536.It Ic \&Ex Fl std Ta standard command exit values: Op Ar utility ... 537.It Ic \&Rv Fl std Ta standard function return values: Op Ar function ... 538.It Ic \&St Ta reference to a standards document (one argument) 539.It Ic \&At Ta At 540.It Ic \&Bx Ta Bx 541.It Ic \&Bsx Ta Bsx 542.It Ic \&Nx Ta Nx 543.It Ic \&Fx Ta Fx 544.It Ic \&Ox Ta Ox 545.It Ic \&Dx Ta Dx 546.El 547.Sh MACRO REFERENCE 548This section is a canonical reference of all macros, arranged 549alphabetically. 550For the scoping of individual macros, see 551.Sx MACRO SYNTAX . 552.Bl -tag -width 3n 553.It Ic \&%A Ar first_name ... last_name 554Author name of an 555.Ic \&Rs 556block. 557Multiple authors should each be accorded their own 558.Ic \%%A 559line. 560Author names should be ordered with full or abbreviated forename(s) 561first, then full surname. 562.It Ic \&%B Ar title 563Book title of an 564.Ic \&Rs 565block. 566This macro may also be used in a non-bibliographic context when 567referring to book titles. 568.It Ic \&%C Ar location 569Publication city or location of an 570.Ic \&Rs 571block. 572.It Ic \&%D Oo Ar month day , Oc Ar year 573Publication date of an 574.Ic \&Rs 575block. 576Provide the full English name of the 577.Ar month 578and all four digits of the 579.Ar year . 580.It Ic \&%I Ar name 581Publisher or issuer name of an 582.Ic \&Rs 583block. 584.It Ic \&%J Ar name 585Journal name of an 586.Ic \&Rs 587block. 588.It Ic \&%N Ar number 589Issue number (usually for journals) of an 590.Ic \&Rs 591block. 592.It Ic \&%O Ar line 593Optional information of an 594.Ic \&Rs 595block. 596.It Ic \&%P Ar number 597Book or journal page number of an 598.Ic \&Rs 599block. 600Conventionally, the argument starts with 601.Ql p.\& 602for a single page or 603.Ql pp.\& 604for a range of pages, for example: 605.Pp 606.Dl .%P pp. 42\e(en47 607.It Ic \&%Q Ar name 608Institutional author (school, government, etc.) of an 609.Ic \&Rs 610block. 611Multiple institutional authors should each be accorded their own 612.Ic \&%Q 613line. 614.It Ic \&%R Ar name 615Technical report name of an 616.Ic \&Rs 617block. 618.It Ic \&%T Ar title 619Article title of an 620.Ic \&Rs 621block. 622This macro may also be used in a non-bibliographical context when 623referring to article titles. 624.It Ic \&%U Ar protocol Ns :// Ns Ar path 625URI of reference document. 626.It Ic \&%V Ar number 627Volume number of an 628.Ic \&Rs 629block. 630.It Ic \&Ac 631Close an 632.Ic \&Ao 633block. 634Does not have any tail arguments. 635.Tg Ad 636.It Ic \&Ad Ar address 637Memory address. 638Do not use this for postal addresses. 639.Pp 640Examples: 641.Dl \&.Ad [0,$] 642.Dl \&.Ad 0x00000000 643.Tg An 644.It Ic \&An Fl split | nosplit | Ar first_name ... last_name 645Author name. 646Can be used both for the authors of the program, function, or driver 647documented in the manual, or for the authors of the manual itself. 648Requires either the name of an author or one of the following arguments: 649.Pp 650.Bl -tag -width "-nosplitX" -offset indent -compact 651.It Fl split 652Start a new output line before each subsequent invocation of 653.Ic \&An . 654.It Fl nosplit 655The opposite of 656.Fl split . 657.El 658.Pp 659The default is 660.Fl nosplit . 661The effect of selecting either of the 662.Fl split 663modes ends at the beginning of the 664.Em AUTHORS 665section. 666In the 667.Em AUTHORS 668section, the default is 669.Fl nosplit 670for the first author listing and 671.Fl split 672for all other author listings. 673.Pp 674Examples: 675.Dl \&.An -nosplit 676.Dl \&.An Kristaps Dzonsons \&Aq \&Mt kristaps@bsd.lv 677.It Ic \&Ao Ar block 678Begin a block enclosed by angle brackets. 679Does not have any head arguments. 680This macro is almost never useful. 681See 682.Ic \&Aq 683for more details. 684.Tg Ap 685.It Ic \&Ap 686Inserts an apostrophe without any surrounding whitespace. 687This is generally used as a grammatical device when referring to the verb 688form of a function. 689.Pp 690Examples: 691.Dl \&.Fn execve \&Ap d 692.Tg Aq 693.It Ic \&Aq Ar line 694Enclose the rest of the input line in angle brackets. 695The only important use case is for email addresses. 696See 697.Ic \&Mt 698for an example. 699.Pp 700Occasionally, it is used for names of characters and keys, for example: 701.Bd -literal -offset indent 702Press the 703\&.Aq escape 704key to ... 705.Ed 706.Pp 707For URIs, use 708.Ic \&Lk 709instead, and 710.Ic \&In 711for 712.Dq #include 713directives. 714Never wrap 715.Ic \&Ar 716in 717.Ic \&Aq . 718.Pp 719Since 720.Ic \&Aq 721usually renders with non-ASCII characters in non-ASCII output modes, 722do not use it where the ASCII characters 723.Sq < 724and 725.Sq > 726are required as syntax elements. 727Instead, use these characters directly in such cases, combining them 728with the macros 729.Ic \&Pf , 730.Ic \&Ns , 731or 732.Ic \&Eo 733as needed. 734.Pp 735See also 736.Ic \&Ao . 737.Tg Ar 738.It Ic \&Ar Op Ar placeholder ... 739Command arguments. 740If an argument is not provided, the string 741.Dq file ...\& 742is used as a default. 743.Pp 744Examples: 745.Dl ".Fl o Ar file" 746.Dl ".Ar" 747.Dl ".Ar arg1 , arg2 ." 748.Pp 749The arguments to the 750.Ic \&Ar 751macro are names and placeholders for command arguments; 752for fixed strings to be passed verbatim as arguments, use 753.Ic \&Fl 754or 755.Ic \&Cm . 756.Tg At 757.It Ic \&At Op Ar version 758Formats an 759.At 760version. 761Accepts one optional argument: 762.Pp 763.Bl -tag -width "v[1-7] | 32vX" -offset indent -compact 764.It Cm v[1-7] | 32v 765A version of 766.At . 767.It Cm III 768.At III . 769.It Cm V | V.[1-4] 770A version of 771.At V . 772.El 773.Pp 774Note that these arguments do not begin with a hyphen. 775.Pp 776Examples: 777.Dl \&.At 778.Dl \&.At III 779.Dl \&.At V.1 780.Pp 781See also 782.Ic \&Bsx , 783.Ic \&Bx , 784.Ic \&Dx , 785.Ic \&Fx , 786.Ic \&Nx , 787and 788.Ic \&Ox . 789.It Ic \&Bc 790Close a 791.Ic \&Bo 792block. 793Does not have any tail arguments. 794.Tg Bd 795.It Ic \&Bd Fl Ns Ar type Oo Fl offset Ar width Oc Op Fl compact 796Begin a display block. 797Display blocks are used to select a different indentation and 798justification than the one used by the surrounding text. 799They may contain both macro lines and text lines. 800By default, a display block is preceded by a vertical space. 801.Pp 802The 803.Ar type 804must be one of the following: 805.Bl -tag -width 13n -offset indent 806.It Fl centered 807Produce one output line from each input line, and center-justify each line. 808Using this display type is not recommended; many 809.Nm 810implementations render it poorly. 811.It Fl filled 812Change the positions of line breaks to fill each line, and left- and 813right-justify the resulting block. 814.It Fl literal 815Produce one output line from each input line, 816and do not justify the block at all. 817Preserve white space as it appears in the input. 818Always use a constant-width font. 819Use this for displaying source code. 820.It Fl ragged 821Change the positions of line breaks to fill each line, and left-justify 822the resulting block. 823.It Fl unfilled 824The same as 825.Fl literal , 826but using the same font as for normal text, which is a variable width font 827if supported by the output device. 828.El 829.Pp 830The 831.Ar type 832must be provided first. 833Additional arguments may follow: 834.Bl -tag -width 13n -offset indent 835.It Fl offset Ar width 836Indent the display by the 837.Ar width , 838which may be one of the following: 839.Bl -item 840.It 841One of the pre-defined strings 842.Cm indent , 843the width of a standard indentation (six constant width characters); 844.Cm indent-two , 845twice 846.Cm indent ; 847.Cm left , 848which has no effect; 849.Cm right , 850which justifies to the right margin; or 851.Cm center , 852which aligns around an imagined center axis. 853.It 854A macro invocation, which selects a predefined width 855associated with that macro. 856The most popular is the imaginary macro 857.Ar \&Ds , 858which resolves to 859.Sy 6n . 860.It 861A scaling width as described in 862.Xr roff 7 . 863.It 864An arbitrary string, which indents by the length of this string. 865.El 866.Pp 867When the argument is missing, 868.Fl offset 869is ignored. 870.It Fl compact 871Do not assert vertical space before the display. 872.El 873.Pp 874Examples: 875.Bd -literal -offset indent 876\&.Bd \-literal \-offset indent \-compact 877 Hello world. 878\&.Ed 879.Ed 880.Pp 881See also 882.Ic \&D1 883and 884.Ic \&Dl . 885.Tg Bf 886.It Ic \&Bf Fl emphasis | literal | symbolic | Cm \&Em | \&Li | \&Sy 887Change the font mode for a scoped block of text. 888The 889.Fl emphasis 890and 891.Cm \&Em 892argument are equivalent, as are 893.Fl symbolic 894and 895.Cm \&Sy , 896and 897.Fl literal 898and 899.Cm \&Li . 900Without an argument, this macro does nothing. 901The font mode continues until broken by a new font mode in a nested 902scope or 903.Ic \&Ef 904is encountered. 905.Pp 906See also 907.Ic \&Li , 908.Ic \&Ef , 909.Ic \&Em , 910and 911.Ic \&Sy . 912.Tg Bk 913.It Ic \&Bk Fl words 914For each macro, keep its output together on the same output line, 915until the end of the macro or the end of the input line is reached, 916whichever comes first. 917Line breaks in text lines are unaffected. 918.Pp 919The 920.Fl words 921argument is required; additional arguments are ignored. 922.Pp 923The following example will not break within each 924.Ic \&Op 925macro line: 926.Bd -literal -offset indent 927\&.Bk \-words 928\&.Op Fl f Ar flags 929\&.Op Fl o Ar output 930\&.Ek 931.Ed 932.Pp 933Be careful in using over-long lines within a keep block! 934Doing so will clobber the right margin. 935.Tg Bl 936.It Xo 937.Ic \&Bl 938.Fl Ns Ar type 939.Op Fl width Ar val 940.Op Fl offset Ar val 941.Op Fl compact 942.Op Ar col ... 943.Xc 944Begin a list. 945Lists consist of items specified using the 946.Ic \&It 947macro, containing a head or a body or both. 948.Pp 949The list 950.Ar type 951is mandatory and must be specified first. 952The 953.Fl width 954and 955.Fl offset 956arguments accept macro names as described for 957.Ic \&Bd 958.Fl offset , 959scaling widths as described in 960.Xr roff 7 , 961or use the length of the given string. 962The 963.Fl offset 964is a global indentation for the whole list, affecting both item heads 965and bodies. 966For those list types supporting it, the 967.Fl width 968argument requests an additional indentation of item bodies, 969to be added to the 970.Fl offset . 971Unless the 972.Fl compact 973argument is specified, list entries are separated by vertical space. 974.Pp 975A list must specify one of the following list types: 976.Bl -tag -width 12n -offset indent 977.It Fl bullet 978No item heads can be specified, but a bullet will be printed at the head 979of each item. 980Item bodies start on the same output line as the bullet 981and are indented according to the 982.Fl width 983argument. 984.It Fl column 985A columnated list. 986The 987.Fl width 988argument has no effect; instead, the string length of each argument 989specifies the width of one column. 990If the first line of the body of a 991.Fl column 992list is not an 993.Ic \&It 994macro line, 995.Ic \&It 996contexts spanning one input line each are implied until an 997.Ic \&It 998macro line is encountered, at which point items start being interpreted as 999described in the 1000.Ic \&It 1001documentation. 1002.It Fl dash 1003Like 1004.Fl bullet , 1005except that dashes are used in place of bullets. 1006.It Fl diag 1007Like 1008.Fl inset , 1009except that item heads are not parsed for macro invocations. 1010Most often used in the 1011.Em DIAGNOSTICS 1012section with error constants in the item heads. 1013.It Fl enum 1014A numbered list. 1015No item heads can be specified. 1016Formatted like 1017.Fl bullet , 1018except that ordinal numbers are used in place of bullets, 1019starting at 1. 1020.It Fl hang 1021Like 1022.Fl tag , 1023except that the first lines of item bodies are not indented, but follow 1024the item heads like in 1025.Fl inset 1026lists. 1027.It Fl hyphen 1028Synonym for 1029.Fl dash . 1030.It Fl inset 1031Item bodies follow items heads on the same line, using normal inter-word 1032spacing. 1033Bodies are not indented, and the 1034.Fl width 1035argument is ignored. 1036.It Fl item 1037No item heads can be specified, and none are printed. 1038Bodies are not indented, and the 1039.Fl width 1040argument is ignored. 1041.It Fl ohang 1042Item bodies start on the line following item heads and are not indented. 1043The 1044.Fl width 1045argument is ignored. 1046.It Fl tag 1047Item bodies are indented according to the 1048.Fl width 1049argument. 1050When an item head fits inside the indentation, the item body follows 1051this head on the same output line. 1052Otherwise, the body starts on the output line following the head. 1053.El 1054.Pp 1055Lists may be nested within lists and displays. 1056Nesting of 1057.Fl column 1058and 1059.Fl enum 1060lists may not be portable. 1061.Pp 1062See also 1063.Ic \&El 1064and 1065.Ic \&It . 1066.It Ic \&Bo Ar block 1067Begin a block enclosed by square brackets. 1068Does not have any head arguments. 1069.Pp 1070Examples: 1071.Bd -literal -offset indent -compact 1072\&.Bo 1 , 1073\&.Dv BUFSIZ \&Bc 1074.Ed 1075.Pp 1076See also 1077.Ic \&Bq . 1078.Tg Bq 1079.It Ic \&Bq Ar line 1080Encloses its arguments in square brackets. 1081.Pp 1082Examples: 1083.Dl \&.Bq 1 , \&Dv BUFSIZ 1084.Pp 1085.Em Remarks : 1086this macro is sometimes abused to emulate optional arguments for 1087commands; the correct macros to use for this purpose are 1088.Ic \&Op , 1089.Ic \&Oo , 1090and 1091.Ic \&Oc . 1092.Pp 1093See also 1094.Ic \&Bo . 1095.It Ic \&Brc 1096Close a 1097.Ic \&Bro 1098block. 1099Does not have any tail arguments. 1100.It Ic \&Bro Ar block 1101Begin a block enclosed by curly braces. 1102Does not have any head arguments. 1103.Pp 1104Examples: 1105.Bd -literal -offset indent -compact 1106\&.Bro 1 , ... , 1107\&.Va n \&Brc 1108.Ed 1109.Pp 1110See also 1111.Ic \&Brq . 1112.Tg Brq 1113.It Ic \&Brq Ar line 1114Encloses its arguments in curly braces. 1115.Pp 1116Examples: 1117.Dl \&.Brq 1 , ... , \&Va n 1118.Pp 1119See also 1120.Ic \&Bro . 1121.Tg Bsx 1122.It Ic \&Bsx Op Ar version 1123Format the 1124.Bsx 1125version provided as an argument, or a default value if 1126no argument is provided. 1127.Pp 1128Examples: 1129.Dl \&.Bsx 1.0 1130.Dl \&.Bsx 1131.Pp 1132See also 1133.Ic \&At , 1134.Ic \&Bx , 1135.Ic \&Dx , 1136.Ic \&Fx , 1137.Ic \&Nx , 1138and 1139.Ic \&Ox . 1140.It Ic \&Bt 1141Supported only for compatibility, do not use this in new manuals. 1142Prints 1143.Dq is currently in beta test. 1144.Tg Bx 1145.It Ic \&Bx Op Ar version Op Ar variant 1146Format the 1147.Bx 1148version provided as an argument, or a default value if no 1149argument is provided. 1150.Pp 1151Examples: 1152.Dl \&.Bx 4.3 Tahoe 1153.Dl \&.Bx 4.4 1154.Dl \&.Bx 1155.Pp 1156See also 1157.Ic \&At , 1158.Ic \&Bsx , 1159.Ic \&Dx , 1160.Ic \&Fx , 1161.Ic \&Nx , 1162and 1163.Ic \&Ox . 1164.Tg Cd 1165.It Ic \&Cd Ar line 1166Kernel configuration declaration. 1167This denotes strings accepted by 1168.Xr config 8 . 1169It is most often used in section 4 manual pages. 1170.Pp 1171Examples: 1172.Dl \&.Cd device le0 at scode? 1173.Pp 1174.Em Remarks : 1175this macro is commonly abused by using quoted literals to retain 1176whitespace and align consecutive 1177.Ic \&Cd 1178declarations. 1179This practise is discouraged. 1180.Tg Cm 1181.It Ic \&Cm Ar keyword ... 1182Command modifiers. 1183Typically used for fixed strings passed as arguments to interactive 1184commands, to commands in interpreted scripts, or to configuration 1185file directives, unless 1186.Ic \&Fl 1187is more appropriate. 1188.Pp 1189Examples: 1190.Dl ".Nm mt Fl f Ar device Cm rewind" 1191.Dl ".Nm ps Fl o Cm pid , Ns Cm command" 1192.Dl ".Nm dd Cm if= Ns Ar file1 Cm of= Ns Ar file2" 1193.Dl ".Ic set Fl o Cm vi" 1194.Dl ".Ic lookup Cm file bind" 1195.Dl ".Ic permit Ar identity Op Cm as Ar target" 1196.Tg D1 1197.It Ic \&D1 Ar line 1198One-line indented display. 1199This is formatted by the default rules and is useful for simple indented 1200statements. 1201It is followed by a newline. 1202.Pp 1203Examples: 1204.Dl \&.D1 \&Fl abcdefgh 1205.Pp 1206See also 1207.Ic \&Bd 1208and 1209.Ic \&Dl . 1210.It Ic \&Db 1211This macro is obsolete. 1212No replacement is needed. 1213It is ignored by 1214.Xr mandoc 1 1215and groff including its arguments. 1216It was formerly used to toggle a debugging mode. 1217.It Ic \&Dc 1218Close a 1219.Ic \&Do 1220block. 1221Does not have any tail arguments. 1222.Tg Dd 1223.It Ic \&Dd Cm $\&Mdocdate$ | Ar month day , year 1224Document date for display in the page footer, 1225by convention the date of the last change. 1226This is the mandatory first macro of any 1227.Nm 1228manual. 1229.Pp 1230The 1231.Ar month 1232is the full English month name, the 1233.Ar day 1234is an integer number, and the 1235.Ar year 1236is the full four-digit year. 1237.Pp 1238Other arguments are not portable; the 1239.Xr mandoc 1 1240utility handles them as follows: 1241.Bl -dash -offset 3n -compact 1242.It 1243To have the date automatically filled in by the 1244.Ox 1245version of 1246.Xr cvs 1 , 1247the special string 1248.Dq $\&Mdocdate$ 1249can be given as an argument. 1250.It 1251The traditional, purely numeric 1252.Xr man 7 1253format 1254.Ar year Ns \(en Ns Ar month Ns \(en Ns Ar day 1255is accepted, too. 1256.It 1257If a date string cannot be parsed, it is used verbatim. 1258.It 1259If no date string is given, the current date is used. 1260.El 1261.Pp 1262Examples: 1263.Dl \&.Dd $\&Mdocdate$ 1264.Dl \&.Dd $\&Mdocdate: July 2 2018$ 1265.Dl \&.Dd July 2, 2018 1266.Pp 1267See also 1268.Ic \&Dt 1269and 1270.Ic \&Os . 1271.Tg Dl 1272.It Ic \&Dl Ar line 1273One-line indented display. 1274This is formatted as literal text and is useful for commands and 1275invocations. 1276It is followed by a newline. 1277.Pp 1278Examples: 1279.Dl \&.Dl % mandoc mdoc.7 \e(ba less 1280.Pp 1281See also 1282.Ic \&Ql , 1283.Ic \&Bd Fl literal , 1284and 1285.Ic \&D1 . 1286.It Ic \&Do Ar block 1287Begin a block enclosed by double quotes. 1288Does not have any head arguments. 1289.Pp 1290Examples: 1291.Bd -literal -offset indent -compact 1292\&.Do 1293April is the cruellest month 1294\&.Dc 1295\e(em T.S. Eliot 1296.Ed 1297.Pp 1298See also 1299.Ic \&Dq . 1300.Tg Dq 1301.It Ic \&Dq Ar line 1302Encloses its arguments in 1303.Dq typographic 1304double-quotes. 1305.Pp 1306Examples: 1307.Bd -literal -offset indent -compact 1308\&.Dq April is the cruellest month 1309\e(em T.S. Eliot 1310.Ed 1311.Pp 1312See also 1313.Ic \&Qq , 1314.Ic \&Sq , 1315and 1316.Ic \&Do . 1317.Tg Dt 1318.It Ic \&Dt Ar TITLE section Op Ar arch 1319Document title for display in the page header. 1320This is the mandatory second macro of any 1321.Nm 1322file. 1323.Pp 1324Its arguments are as follows: 1325.Bl -tag -width section -offset 2n 1326.It Ar TITLE 1327The document's title (name), defaulting to 1328.Dq UNTITLED 1329if unspecified. 1330To achieve a uniform appearance of page header lines, 1331it should by convention be all caps. 1332.It Ar section 1333The manual section. 1334This may be one of 1335.Cm 1 1336.Pq General Commands , 1337.Cm 2 1338.Pq System Calls , 1339.Cm 3 1340.Pq Library Functions , 1341.Cm 3p 1342.Pq Perl Library , 1343.Cm 4 1344.Pq Device Drivers , 1345.Cm 5 1346.Pq File Formats , 1347.Cm 6 1348.Pq Games , 1349.Cm 7 1350.Pq Miscellaneous Information , 1351.Cm 8 1352.Pq System Manager's Manual , 1353or 1354.Cm 9 1355.Pq Kernel Developer's Manual . 1356It should correspond to the manual's filename suffix and defaults to 1357the empty string if unspecified. 1358.It Ar arch 1359This specifies the machine architecture a manual page applies to, 1360where relevant. 1361For 1362.Ox , 1363the following are valid architectures: 1364.Cm alpha , 1365.Cm amd64 , 1366.Cm armv7 , 1367.Cm arm64 , 1368.Cm hppa , 1369.Cm i386 , 1370.Cm landisk , 1371.Cm loongson , 1372.Cm luna88k , 1373.Cm macppc , 1374.Cm mips64 , 1375.Cm octeon , 1376.Cm powerpc64 , 1377.Cm riscv64 , 1378and 1379.Cm sparc64 . 1380.El 1381.Pp 1382Examples: 1383.Dl \&.Dt FOO 1 1384.Dl \&.Dt FOO 9 i386 1385.Pp 1386See also 1387.Ic \&Dd 1388and 1389.Ic \&Os . 1390.Tg Dv 1391.It Ic \&Dv Ar identifier ... 1392Defined variables such as preprocessor constants, constant symbols, 1393enumeration values, and so on. 1394.Pp 1395Examples: 1396.Dl \&.Dv NULL 1397.Dl \&.Dv BUFSIZ 1398.Dl \&.Dv STDOUT_FILENO 1399.Pp 1400See also 1401.Ic \&Er 1402and 1403.Ic \&Ev 1404for special-purpose constants, 1405.Ic \&Va 1406for variable symbols, and 1407.Ic \&Fd 1408for listing preprocessor variable definitions in the 1409.Em SYNOPSIS . 1410.Tg Dx 1411.It Ic \&Dx Op Ar version 1412Format the 1413.Dx 1414version provided as an argument, or a default 1415value if no argument is provided. 1416.Pp 1417Examples: 1418.Dl \&.Dx 2.4.1 1419.Dl \&.Dx 1420.Pp 1421See also 1422.Ic \&At , 1423.Ic \&Bsx , 1424.Ic \&Bx , 1425.Ic \&Fx , 1426.Ic \&Nx , 1427and 1428.Ic \&Ox . 1429.It Ic \&Ec Op Ar closing_delimiter 1430Close a scope started by 1431.Ic \&Eo . 1432.Pp 1433The 1434.Ar closing_delimiter 1435argument is used as the enclosure tail, for example, specifying \e(rq 1436will emulate 1437.Ic \&Dc . 1438.It Ic \&Ed 1439End a display context started by 1440.Ic \&Bd . 1441.It Ic \&Ef 1442End a font mode context started by 1443.Ic \&Bf . 1444.It Ic \&Ek 1445End a keep context started by 1446.Ic \&Bk . 1447.It Ic \&El 1448End a list context started by 1449.Ic \&Bl . 1450See also 1451.Ic \&It . 1452.Tg Em 1453.It Ic \&Em Ar word ... 1454Request an italic font. 1455If the output device does not provide that, underline. 1456.Pp 1457This is most often used for stress emphasis (not to be confused with 1458importance, see 1459.Ic \&Sy ) . 1460In the rare cases where none of the semantic markup macros fit, 1461it can also be used for technical terms and placeholders, except 1462that for syntax elements, 1463.Ic \&Sy 1464and 1465.Ic \&Ar 1466are preferred, respectively. 1467.Pp 1468Examples: 1469.Bd -literal -compact -offset indent 1470Selected lines are those 1471\&.Em not 1472matching any of the specified patterns. 1473Some of the functions use a 1474\&.Em hold space 1475to save the pattern space for subsequent retrieval. 1476.Ed 1477.Pp 1478See also 1479.Ic \&No , 1480.Ic \&Ql , 1481and 1482.Ic \&Sy . 1483.It Ic \&En Ar word ... 1484This macro is obsolete. 1485Use 1486.Ic \&Eo 1487or any of the other enclosure macros. 1488.Pp 1489It encloses its argument in the delimiters specified by the last 1490.Ic \&Es 1491macro. 1492.Tg Eo 1493.It Ic \&Eo Op Ar opening_delimiter 1494An arbitrary enclosure. 1495The 1496.Ar opening_delimiter 1497argument is used as the enclosure head, for example, specifying \e(lq 1498will emulate 1499.Ic \&Do . 1500.Tg Er 1501.It Ic \&Er Ar identifier ... 1502Error constants for definitions of the 1503.Va errno 1504libc global variable. 1505This is most often used in section 2 and 3 manual pages. 1506.Pp 1507Examples: 1508.Dl \&.Er EPERM 1509.Dl \&.Er ENOENT 1510.Pp 1511See also 1512.Ic \&Dv 1513for general constants. 1514.It Ic \&Es Ar opening_delimiter closing_delimiter 1515This macro is obsolete. 1516Use 1517.Ic \&Eo 1518or any of the other enclosure macros. 1519.Pp 1520It takes two arguments, defining the delimiters to be used by subsequent 1521.Ic \&En 1522macros. 1523.Tg Ev 1524.It Ic \&Ev Ar identifier ... 1525Environmental variables such as those specified in 1526.Xr environ 7 . 1527.Pp 1528Examples: 1529.Dl \&.Ev DISPLAY 1530.Dl \&.Ev PATH 1531.Pp 1532See also 1533.Ic \&Dv 1534for general constants. 1535.Tg Ex 1536.It Ic \&Ex Fl std Op Ar utility ... 1537Insert a standard sentence regarding command exit values of 0 on success 1538and >0 on failure. 1539This is most often used in section 1, 6, and 8 manual pages. 1540.Pp 1541If 1542.Ar utility 1543is not specified, the document's name set by 1544.Ic \&Nm 1545is used. 1546Multiple 1547.Ar utility 1548arguments are treated as separate utilities. 1549.Pp 1550See also 1551.Ic \&Rv . 1552.Tg Fa 1553.It Ic \&Fa Ar argument ... 1554Function argument or parameter. 1555Each argument may be a name and a type (recommended for the 1556.Em SYNOPSIS 1557section), a name alone (for function invocations), 1558or a type alone (for function prototypes). 1559If both a type and a name are given or if the type consists of multiple 1560words, all words belonging to the same function argument have to be 1561given in a single argument to the 1562.Ic \&Fa 1563macro. 1564.Pp 1565This macro is also used to specify the field name of a structure. 1566.Pp 1567Most often, the 1568.Ic \&Fa 1569macro is used in the 1570.Em SYNOPSIS 1571within 1572.Ic \&Fo 1573blocks when documenting multi-line function prototypes. 1574If invoked with multiple arguments, the arguments are separated by a 1575comma. 1576Furthermore, if the following macro is another 1577.Ic \&Fa , 1578the last argument will also have a trailing comma. 1579.Pp 1580Examples: 1581.Dl \&.Fa \(dqconst char *p\(dq 1582.Dl \&.Fa \(dqint a\(dq \(dqint b\(dq \(dqint c\(dq 1583.Dl \&.Fa \(dqchar *\(dq size_t 1584.Pp 1585See also 1586.Ic \&Fo . 1587.It Ic \&Fc 1588End a function context started by 1589.Ic \&Fo . 1590.Tg Fd 1591.It Ic \&Fd Pf # Ar directive Op Ar argument ... 1592Preprocessor directive, in particular for listing it in the 1593.Em SYNOPSIS . 1594Historically, it was also used to document include files. 1595The latter usage has been deprecated in favour of 1596.Ic \&In . 1597.Pp 1598Examples: 1599.Dl \&.Fd #define sa_handler __sigaction_u.__sa_handler 1600.Dl \&.Fd #define SIO_MAXNFDS 1601.Dl \&.Fd #ifdef FS_DEBUG 1602.Dl \&.Ft void 1603.Dl \&.Fn dbg_open \(dqconst char *\(dq 1604.Dl \&.Fd #endif 1605.Pp 1606See also 1607.Sx MANUAL STRUCTURE , 1608.Ic \&In , 1609and 1610.Ic \&Dv . 1611.Tg Fl 1612.It Ic \&Fl Op Ar word ... 1613Command-line flag or option. 1614Used when listing arguments to command-line utilities. 1615For each argument, prints an ASCII hyphen-minus character 1616.Sq \- , 1617immediately followed by the argument. 1618If no arguments are provided, a hyphen-minus is printed followed by a space. 1619If the argument is a macro, a hyphen-minus is prefixed 1620to the subsequent macro output. 1621.Pp 1622Examples: 1623.Dl ".Nm du Op Fl H | L | P" 1624.Dl ".Nm ls Op Fl 1AaCcdFfgHhikLlmnopqRrSsTtux" 1625.Dl ".Nm route Cm add Fl inet Ar destination gateway" 1626.Dl ".Nm locate.updatedb Op Fl \e-fcodes Ns = Ns Ar dbfile" 1627.Dl ".Nm aucat Fl o Fl" 1628.Dl ".Nm kill Fl Ar signal_number" 1629.Pp 1630For GNU-style long options, escaping the additional hyphen-minus is not 1631strictly required, but may be safer with future versions of GNU troff; see 1632.Xr mandoc_char 7 1633for details. 1634.Pp 1635See also 1636.Ic \&Cm . 1637.Tg Fn 1638.It Ic \&Fn Ar funcname Op Ar argument ... 1639A function name. 1640.Pp 1641Function arguments are surrounded in parenthesis and 1642are delimited by commas. 1643If no arguments are specified, blank parenthesis are output. 1644In the 1645.Em SYNOPSIS 1646section, this macro starts a new output line, 1647and a blank line is automatically inserted between function definitions. 1648.Pp 1649Examples: 1650.Dl \&.Fn \(dqint funcname\(dq \(dqint arg0\(dq \(dqint arg1\(dq 1651.Dl \&.Fn funcname \(dqint arg0\(dq 1652.Dl \&.Fn funcname arg0 1653.Bd -literal -offset indent 1654\&.Ft functype 1655\&.Fn funcname 1656.Ed 1657.Pp 1658When referring to a function documented in another manual page, use 1659.Ic \&Xr 1660instead. 1661See also 1662.Sx MANUAL STRUCTURE , 1663.Ic \&Fo , 1664and 1665.Ic \&Ft . 1666.Tg Fo 1667.It Ic \&Fo Ar funcname 1668Begin a function block. 1669This is a multi-line version of 1670.Ic \&Fn . 1671.Pp 1672Invocations usually occur in the following context: 1673.Bd -ragged -offset indent 1674.Pf \. Ic \&Ft Ar functype 1675.br 1676.Pf \. Ic \&Fo Ar funcname 1677.br 1678.Pf \. Ic \&Fa Qq Ar argtype Ar argname 1679.br 1680\&.\.\. 1681.br 1682.Pf \. Ic \&Fc 1683.Ed 1684.Pp 1685A 1686.Ic \&Fo 1687scope is closed by 1688.Ic \&Fc . 1689.Pp 1690See also 1691.Sx MANUAL STRUCTURE , 1692.Ic \&Fa , 1693.Ic \&Fc , 1694and 1695.Ic \&Ft . 1696.It Ic \&Fr Ar number 1697This macro is obsolete. 1698No replacement markup is needed. 1699.Pp 1700It was used to show numerical function return values in an italic font. 1701.Tg Ft 1702.It Ic \&Ft Ar functype 1703A function type. 1704.Pp 1705In the 1706.Em SYNOPSIS 1707section, a new output line is started after this macro. 1708.Pp 1709Examples: 1710.Dl \&.Ft int 1711.Bd -literal -offset indent -compact 1712\&.Ft functype 1713\&.Fn funcname 1714.Ed 1715.Pp 1716See also 1717.Sx MANUAL STRUCTURE , 1718.Ic \&Fn , 1719and 1720.Ic \&Fo . 1721.Tg Fx 1722.It Ic \&Fx Op Ar version 1723Format the 1724.Fx 1725version provided as an argument, or a default value 1726if no argument is provided. 1727.Pp 1728Examples: 1729.Dl \&.Fx 7.1 1730.Dl \&.Fx 1731.Pp 1732See also 1733.Ic \&At , 1734.Ic \&Bsx , 1735.Ic \&Bx , 1736.Ic \&Dx , 1737.Ic \&Nx , 1738and 1739.Ic \&Ox . 1740.It Ic \&Hf Ar filename 1741This macro is not implemented in 1742.Xr mandoc 1 . 1743It was used to include the contents of a (header) file literally. 1744.Tg Ic 1745.It Ic \&Ic Ar keyword ... 1746Internal or interactive command, or configuration instruction 1747in a configuration file. 1748See also 1749.Ic \&Cm . 1750.Pp 1751Examples: 1752.Dl \&.Ic :wq 1753.Dl \&.Ic hash 1754.Dl \&.Ic alias 1755.Pp 1756Note that using 1757.Ic \&Ql , 1758.Ic \&Dl , 1759or 1760.Ic \&Bd Fl literal 1761is preferred for displaying code samples; the 1762.Ic \&Ic 1763macro is used when referring to an individual command name. 1764.Tg In 1765.It Ic \&In Ar filename 1766The name of an include file. 1767This macro is most often used in section 2, 3, and 9 manual pages. 1768.Pp 1769When invoked as the first macro on an input line in the 1770.Em SYNOPSIS 1771section, the argument is displayed in angle brackets 1772and preceded by 1773.Qq #include , 1774and a blank line is inserted in front if there is a preceding 1775function declaration. 1776In other sections, it only encloses its argument in angle brackets 1777and causes no line break. 1778.Pp 1779Examples: 1780.Dl \&.In sys/types.h 1781.Pp 1782See also 1783.Sx MANUAL STRUCTURE . 1784.Tg It 1785.It Ic \&It Op Ar head 1786A list item. 1787The syntax of this macro depends on the list type. 1788.Pp 1789Lists 1790of type 1791.Fl hang , 1792.Fl ohang , 1793.Fl inset , 1794and 1795.Fl diag 1796have the following syntax: 1797.Pp 1798.D1 Pf \. Ic \&It Ar args 1799.Pp 1800Lists of type 1801.Fl bullet , 1802.Fl dash , 1803.Fl enum , 1804.Fl hyphen 1805and 1806.Fl item 1807have the following syntax: 1808.Pp 1809.D1 Pf \. Ic \&It 1810.Pp 1811with subsequent lines interpreted within the scope of the 1812.Ic \&It 1813until either a closing 1814.Ic \&El 1815or another 1816.Ic \&It . 1817.Pp 1818The 1819.Fl tag 1820list has the following syntax: 1821.Pp 1822.D1 Pf \. Ic \&It Op Cm args 1823.Pp 1824Subsequent lines are interpreted as with 1825.Fl bullet 1826and family. 1827The line arguments correspond to the list's left-hand side; body 1828arguments correspond to the list's contents. 1829.Pp 1830The 1831.Fl column 1832list is the most complicated. 1833Its syntax is as follows: 1834.Pp 1835.D1 Pf \. Ic \&It Ar cell Op Ic \&Ta Ar cell ... 1836.D1 Pf \. Ic \&It Ar cell Op <TAB> Ar cell ... 1837.Pp 1838The arguments consist of one or more lines of text and macros 1839representing a complete table line. 1840Cells within the line are delimited by the special 1841.Ic \&Ta 1842block macro or by literal tab characters. 1843.Pp 1844Using literal tabs is strongly discouraged because they are very 1845hard to use correctly and 1846.Nm 1847code using them is very hard to read. 1848In particular, a blank character is syntactically significant 1849before and after the literal tab character. 1850If a word precedes or follows the tab without an intervening blank, 1851that word is never interpreted as a macro call, but always output 1852literally. 1853.Pp 1854The tab cell delimiter may only be used within the 1855.Ic \&It 1856line itself; on following lines, only the 1857.Ic \&Ta 1858macro can be used to delimit cells, and portability requires that 1859.Ic \&Ta 1860is called by other macros: some parsers do not recognize it when 1861it appears as the first macro on a line. 1862.Pp 1863Note that quoted strings may span tab-delimited cells on an 1864.Ic \&It 1865line. 1866For example, 1867.Pp 1868.Dl .It \(dqcol1 ,\& <TAB> col2 ,\(dq \&; 1869.Pp 1870will preserve the whitespace before both commas, 1871but not the whitespace before the semicolon. 1872.Pp 1873See also 1874.Ic \&Bl . 1875.Tg Lb 1876.It Ic \&Lb Cm lib Ns Ar name 1877Specify a library. 1878.Pp 1879The 1880.Ar name 1881parameter may be a system library, such as 1882.Cm z 1883or 1884.Cm pam , 1885in which case a small library description is printed next to the linker 1886invocation; or a custom library, in which case the library name is 1887printed in quotes. 1888This is most commonly used in the 1889.Em SYNOPSIS 1890section as described in 1891.Sx MANUAL STRUCTURE . 1892.Pp 1893Examples: 1894.Dl \&.Lb libz 1895.Dl \&.Lb libmandoc 1896.Tg Li 1897.It Ic \&Li Ar word ... 1898Request a typewriter (literal) font. 1899Deprecated because on terminal output devices, this is usually 1900indistinguishable from normal text. 1901For literal displays, use 1902.Ic \&Ql Pq in-line , 1903.Ic \&Dl Pq single line , 1904or 1905.Ic \&Bd Fl literal Pq multi-line 1906instead. 1907.Tg Lk 1908.It Ic \&Lk Ar uri Op Ar display_name 1909Format a hyperlink. 1910.Pp 1911Examples: 1912.Dl \&.Lk https://bsd.lv \(dqThe BSD.lv Project\(dq 1913.Dl \&.Lk https://bsd.lv 1914.Pp 1915See also 1916.Ic \&Mt . 1917.It Ic \&Lp 1918Deprecated synonym for 1919.Ic \&Pp . 1920.Tg Ms 1921.It Ic \&Ms Ar name 1922Display a mathematical symbol. 1923.Pp 1924Examples: 1925.Dl \&.Ms sigma 1926.Dl \&.Ms aleph 1927.Tg Mt 1928.It Ic \&Mt Ar localpart Ns @ Ns Ar domain 1929Format a 1930.Dq mailto: 1931hyperlink. 1932.Pp 1933Examples: 1934.Dl \&.Mt discuss@manpages.bsd.lv 1935.Dl \&.An Kristaps Dzonsons \&Aq \&Mt kristaps@bsd.lv 1936.Tg Nd 1937.It Ic \&Nd Ar line 1938A one line description of the manual's content. 1939This is the mandatory last macro of the 1940.Em NAME 1941section and not appropriate for other sections. 1942.Pp 1943Examples: 1944.Dl Pf . Ic \&Nd mdoc language reference 1945.Dl Pf . Ic \&Nd format and display UNIX manuals 1946.Pp 1947The 1948.Ic \&Nd 1949macro technically accepts child macros and terminates with a subsequent 1950.Ic \&Sh 1951invocation. 1952Do not assume this behaviour: some 1953.Xr whatis 1 1954database generators are not smart enough to parse more than the line 1955arguments and will display macros verbatim. 1956.Pp 1957See also 1958.Ic \&Nm . 1959.Tg Nm 1960.It Ic \&Nm Op Ar name 1961The name of the manual page, or \(em in particular in section 1, 6, 1962and 8 pages \(em of an additional command or feature documented in 1963the manual page. 1964When first invoked, the 1965.Ic \&Nm 1966macro expects a single argument, the name of the manual page. 1967Usually, the first invocation happens in the 1968.Em NAME 1969section of the page. 1970The specified name will be remembered and used whenever the macro is 1971called again without arguments later in the page. 1972The 1973.Ic \&Nm 1974macro uses 1975.Sx Block full-implicit 1976semantics when invoked as the first macro on an input line in the 1977.Em SYNOPSIS 1978section; otherwise, it uses ordinary 1979.Sx In-line 1980semantics. 1981.Pp 1982Examples: 1983.Bd -literal -offset indent 1984\&.Sh SYNOPSIS 1985\&.Nm cat 1986\&.Op Fl benstuv 1987\&.Op Ar 1988.Ed 1989.Pp 1990In the 1991.Em SYNOPSIS 1992of section 2, 3 and 9 manual pages, use the 1993.Ic \&Fn 1994macro rather than 1995.Ic \&Nm 1996to mark up the name of the manual page. 1997.Tg No 1998.It Ic \&No Ar word ... 1999Normal text. 2000Closes the scope of any preceding in-line macro. 2001When used after physical formatting macros like 2002.Ic \&Em 2003or 2004.Ic \&Sy , 2005switches back to the standard font face and weight. 2006Can also be used to embed plain text strings in macro lines 2007using semantic annotation macros. 2008.Pp 2009Examples: 2010.Dl ".Em italic , Sy bold , No and roman" 2011.Bd -literal -offset indent 2012\&.Sm off 2013\&.Cm :C No / Ar pattern No / Ar replacement No / 2014\&.Sm on 2015.Ed 2016.Pp 2017See also 2018.Ic \&Em , 2019.Ic \&Ql , 2020and 2021.Ic \&Sy . 2022.Tg Ns 2023.It Ic \&Ns 2024Suppress a space between the output of the preceding macro 2025and the following text or macro. 2026Following invocation, input is interpreted as normal text 2027just like after an 2028.Ic \&No 2029macro. 2030.Pp 2031This has no effect when invoked at the start of a macro line. 2032.Pp 2033Examples: 2034.Dl ".Ar name Ns = Ns Ar value" 2035.Dl ".Cm :M Ns Ar pattern" 2036.Dl ".Fl o Ns Ar output" 2037.Pp 2038See also 2039.Ic \&No 2040and 2041.Ic \&Sm . 2042.Tg Nx 2043.It Ic \&Nx Op Ar version 2044Format the 2045.Nx 2046version provided as an argument, or a default value if 2047no argument is provided. 2048.Pp 2049Examples: 2050.Dl \&.Nx 5.01 2051.Dl \&.Nx 2052.Pp 2053See also 2054.Ic \&At , 2055.Ic \&Bsx , 2056.Ic \&Bx , 2057.Ic \&Dx , 2058.Ic \&Fx , 2059and 2060.Ic \&Ox . 2061.It Ic \&Oc 2062Close multi-line 2063.Ic \&Oo 2064context. 2065.It Ic \&Oo Ar block 2066Multi-line version of 2067.Ic \&Op . 2068.Pp 2069Examples: 2070.Bd -literal -offset indent -compact 2071\&.Oo 2072\&.Op Fl flag Ns Ar value 2073\&.Oc 2074.Ed 2075.Tg Op 2076.It Ic \&Op Ar line 2077Optional part of a command line. 2078Prints the argument(s) in brackets. 2079This is most often used in the 2080.Em SYNOPSIS 2081section of section 1 and 8 manual pages. 2082.Pp 2083Examples: 2084.Dl \&.Op \&Fl a \&Ar b 2085.Dl \&.Op \&Ar a | b 2086.Pp 2087See also 2088.Ic \&Oo . 2089.Tg Os 2090.It Ic \&Os Op Ar footer text 2091The mandatory third macro of every 2092.Nm 2093file. 2094Usually, do not specify any arguments, 2095in particular not the operating system name and/or version. 2096.Pp 2097If no argument is given, 2098.Xr mandoc 1 2099prints its 2100.Fl Ios 2101argument in the page footer, or 2102.Fa sysname 2103and 2104.Fa release 2105as returned by 2106.Xr uname 3 2107by default. 2108.Pp 2109Manual pages that are part of a portable software project can override 2110the default by giving the project name and version number as arguments, 2111but leaving it blank is never a bad choice. 2112.Pp 2113See also 2114.Ic \&Dd 2115and 2116.Ic \&Dt . 2117.It Ic \&Ot Ar functype 2118This macro is obsolete. 2119Use 2120.Ic \&Ft 2121instead; with 2122.Xr mandoc 1 , 2123both have the same effect. 2124.Pp 2125Historical 2126.Nm 2127packages described it as 2128.Dq "old function type (FORTRAN)" . 2129.Tg Ox 2130.It Ic \&Ox Op Ar version 2131Format the 2132.Ox 2133version provided as an argument, or a default value 2134if no argument is provided. 2135.Pp 2136Examples: 2137.Dl \&.Ox 4.5 2138.Dl \&.Ox 2139.Pp 2140See also 2141.Ic \&At , 2142.Ic \&Bsx , 2143.Ic \&Bx , 2144.Ic \&Dx , 2145.Ic \&Fx , 2146and 2147.Ic \&Nx . 2148.Tg Pa 2149.It Ic \&Pa Ar name ... 2150An absolute or relative file system path, or a file or directory name. 2151If an argument is not provided, the character 2152.Sq \(ti 2153is used as a default. 2154.Pp 2155Examples: 2156.Dl \&.Pa /usr/bin/mandoc 2157.Dl \&.Pa /usr/share/man/man7/mdoc.7 2158.Pp 2159See also 2160.Ic \&Lk . 2161.It Ic \&Pc 2162Close parenthesised context opened by 2163.Ic \&Po . 2164.Tg Pf 2165.It Ic \&Pf Ar prefix macro Op Ar argument ... 2166Removes the space between its argument and the following macro. 2167It is equivalent to: 2168.Pp 2169.D1 Ic \&No Pf \e& Ar prefix Ic \&Ns Ar macro Op Ar argument ... 2170.Pp 2171The 2172.Ar prefix 2173argument is not parsed for macro names or delimiters, 2174but used verbatim as if it were escaped. 2175.Pp 2176Examples: 2177.Dl ".Pf $ Ar variable_name" 2178.Dl ".Pf . Ar macro_name" 2179.Dl ".Pf 0x Ar hex_digits" 2180.Pp 2181See also 2182.Ic \&Ns 2183and 2184.Ic \&Sm . 2185.It Ic \&Po Ar block 2186Multi-line version of 2187.Ic \&Pq . 2188.Tg Pp 2189.It Ic \&Pp 2190Break a paragraph. 2191This will assert vertical space between prior and subsequent macros 2192and/or text. 2193.Pp 2194Paragraph breaks are not needed before or after 2195.Ic \&Sh 2196or 2197.Ic \&Ss 2198macros or before displays 2199.Pq Ic \&Bd Ar line 2200or lists 2201.Pq Ic \&Bl 2202unless the 2203.Fl compact 2204flag is given. 2205.Tg Pq 2206.It Ic \&Pq Ar line 2207Parenthesised enclosure. 2208.Pp 2209See also 2210.Ic \&Po . 2211.It Ic \&Qc 2212Close quoted context opened by 2213.Ic \&Qo . 2214.Tg Ql 2215.It Ic \&Ql Ar line 2216In-line literal display. 2217This can be used for complete command invocations and for multi-word 2218code examples when an indented display is not desired. 2219.Pp 2220See also 2221.Ic \&Dl 2222and 2223.Ic \&Bd 2224.Fl literal . 2225.It Ic \&Qo Ar block 2226Multi-line version of 2227.Ic \&Qq . 2228.Tg Qq 2229.It Ic \&Qq Ar line 2230Encloses its arguments in 2231.Qq typewriter 2232double-quotes. 2233Consider using 2234.Ic \&Dq . 2235.Pp 2236See also 2237.Ic \&Dq , 2238.Ic \&Sq , 2239and 2240.Ic \&Qo . 2241.It Ic \&Re 2242Close an 2243.Ic \&Rs 2244block. 2245Does not have any tail arguments. 2246.Tg Rs 2247.It Ic \&Rs 2248Begin a bibliographic 2249.Pq Dq reference 2250block. 2251Does not have any head arguments. 2252The block macro may only contain 2253.Ic \&%A , 2254.Ic \&%B , 2255.Ic \&%C , 2256.Ic \&%D , 2257.Ic \&%I , 2258.Ic \&%J , 2259.Ic \&%N , 2260.Ic \&%O , 2261.Ic \&%P , 2262.Ic \&%Q , 2263.Ic \&%R , 2264.Ic \&%T , 2265.Ic \&%U , 2266and 2267.Ic \&%V 2268child macros (at least one must be specified). 2269.Pp 2270Examples: 2271.Bd -literal -offset indent -compact 2272\&.Rs 2273\&.%A J. E. Hopcroft 2274\&.%A J. D. Ullman 2275\&.%B Introduction to Automata Theory, Languages, and Computation 2276\&.%I Addison-Wesley 2277\&.%C Reading, Massachusetts 2278\&.%D 1979 2279\&.Re 2280.Ed 2281.Pp 2282If an 2283.Ic \&Rs 2284block is used within a SEE ALSO section, a vertical space is asserted 2285before the rendered output, else the block continues on the current 2286line. 2287.Tg Rv 2288.It Ic \&Rv Fl std Op Ar function ... 2289Insert a standard sentence regarding a function call's return value of 0 2290on success and \-1 on error, with the 2291.Va errno 2292libc global variable set on error. 2293.Pp 2294If 2295.Ar function 2296is not specified, the document's name set by 2297.Ic \&Nm 2298is used. 2299Multiple 2300.Ar function 2301arguments are treated as separate functions. 2302.Pp 2303See also 2304.Ic \&Ex . 2305.It Ic \&Sc 2306Close single-quoted context opened by 2307.Ic \&So . 2308.Tg Sh 2309.It Ic \&Sh Ar TITLE LINE 2310Begin a new section. 2311For a list of conventional manual sections, see 2312.Sx MANUAL STRUCTURE . 2313These sections should be used unless it's absolutely necessary that 2314custom sections be used. 2315.Pp 2316Section names should be unique so that they may be keyed by 2317.Ic \&Sx . 2318Although this macro is parsed, it should not consist of child node or it 2319may not be linked with 2320.Ic \&Sx . 2321.Pp 2322See also 2323.Ic \&Pp , 2324.Ic \&Ss , 2325and 2326.Ic \&Sx . 2327.Tg Sm 2328.It Ic \&Sm Op Cm on | off 2329Switches the spacing mode for output generated from macros. 2330.Pp 2331By default, spacing is 2332.Cm on . 2333When switched 2334.Cm off , 2335no white space is inserted between macro arguments and between the 2336output generated from adjacent macros, but text lines 2337still get normal spacing between words and sentences. 2338.Pp 2339When called without an argument, the 2340.Ic \&Sm 2341macro toggles the spacing mode. 2342Using this is not recommended because it makes the code harder to read. 2343.It Ic \&So Ar block 2344Multi-line version of 2345.Ic \&Sq . 2346.Tg Sq 2347.It Ic \&Sq Ar line 2348Encloses its arguments in 2349.Sq typewriter 2350single-quotes. 2351.Pp 2352See also 2353.Ic \&Dq , 2354.Ic \&Qq , 2355and 2356.Ic \&So . 2357.Tg Ss 2358.It Ic \&Ss Ar Title line 2359Begin a new subsection. 2360Unlike with 2361.Ic \&Sh , 2362there is no convention for the naming of subsections. 2363Except 2364.Em DESCRIPTION , 2365the conventional sections described in 2366.Sx MANUAL STRUCTURE 2367rarely have subsections. 2368.Pp 2369Sub-section names should be unique so that they may be keyed by 2370.Ic \&Sx . 2371Although this macro is parsed, it should not consist of child node or it 2372may not be linked with 2373.Ic \&Sx . 2374.Pp 2375See also 2376.Ic \&Pp , 2377.Ic \&Sh , 2378and 2379.Ic \&Sx . 2380.Tg St 2381.It Ic \&St Fl Ns Ar abbreviation 2382Replace an abbreviation for a standard with the full form. 2383The following standards are recognised. 2384Where multiple lines are given without a blank line in between, 2385they all refer to the same standard, and using the first form 2386is recommended. 2387.Bl -tag -width 1n 2388.It C language standards 2389.Pp 2390.Bl -tag -width "-p1003.1g-2000" -compact 2391.It \-ansiC 2392.St -ansiC 2393.It \-ansiC-89 2394.St -ansiC-89 2395.It \-isoC 2396.St -isoC 2397.It \-isoC-90 2398.St -isoC-90 2399.br 2400The original C standard. 2401.Pp 2402.It \-isoC-amd1 2403.St -isoC-amd1 2404.Pp 2405.It \-isoC-tcor1 2406.St -isoC-tcor1 2407.Pp 2408.It \-isoC-tcor2 2409.St -isoC-tcor2 2410.Pp 2411.It \-isoC-99 2412.St -isoC-99 2413.br 2414The second major version of the C language standard. 2415.Pp 2416.It \-isoC-2011 2417.St -isoC-2011 2418.br 2419The third major version of the C language standard. 2420.El 2421.It POSIX.1 before the Single UNIX Specification 2422.Pp 2423.Bl -tag -width "-p1003.1g-2000" -compact 2424.It \-p1003.1-88 2425.St -p1003.1-88 2426.It \-p1003.1 2427.St -p1003.1 2428.br 2429The original POSIX standard, based on ANSI C. 2430.Pp 2431.It \-p1003.1-90 2432.St -p1003.1-90 2433.It \-iso9945-1-90 2434.St -iso9945-1-90 2435.br 2436The first update of POSIX.1. 2437.Pp 2438.It \-p1003.1b-93 2439.St -p1003.1b-93 2440.It \-p1003.1b 2441.St -p1003.1b 2442.br 2443Real-time extensions. 2444.Pp 2445.It \-p1003.1c-95 2446.St -p1003.1c-95 2447.br 2448POSIX thread interfaces. 2449.Pp 2450.It \-p1003.1i-95 2451.St -p1003.1i-95 2452.br 2453Technical Corrigendum. 2454.Pp 2455.It \-p1003.1-96 2456.St -p1003.1-96 2457.It \-iso9945-1-96 2458.St -iso9945-1-96 2459.br 2460Includes POSIX.1-1990, 1b, 1c, and 1i. 2461.El 2462.It X/Open Portability Guide version 4 and related standards 2463.Pp 2464.Bl -tag -width "-p1003.1g-2000" -compact 2465.It \-xpg3 2466.St -xpg3 2467.br 2468An XPG4 precursor, published in 1989. 2469.Pp 2470.It \-p1003.2 2471.St -p1003.2 2472.It \-p1003.2-92 2473.St -p1003.2-92 2474.It \-iso9945-2-93 2475.St -iso9945-2-93 2476.br 2477An XCU4 precursor. 2478.Pp 2479.It \-p1003.2a-92 2480.St -p1003.2a-92 2481.br 2482Updates to POSIX.2. 2483.Pp 2484.It \-xpg4 2485.St -xpg4 2486.br 2487Based on POSIX.1 and POSIX.2, published in 1992. 2488.El 2489.It Single UNIX Specification version 1 and related standards 2490.Pp 2491.Bl -tag -width "-p1003.1g-2000" -compact 2492.It \-susv1 2493.St -susv1 2494.It \-xpg4.2 2495.St -xpg4.2 2496.br 2497This standard was published in 1994. 2498It was used as the basis for UNIX 95 certification. 2499The following two refer to parts of it. 2500.Pp 2501.It \-xcurses4.2 2502.St -xcurses4.2 2503.Pp 2504.It \-p1003.1g-2000 2505.St -p1003.1g-2000 2506.br 2507Networking APIs, including sockets. 2508.Pp 2509.It \-svid4 2510.St -svid4 , 2511.br 2512Published in 1995. 2513.El 2514.It Single UNIX Specification version 2 and related standards 2515.Pp 2516.Bl -tag -width "-p1003.1g-2000" -compact 2517.It \-susv2 2518.St -susv2 2519This Standard was published in 1997 2520and is also called X/Open Portability Guide version 5. 2521It was used as the basis for UNIX 98 certification. 2522The following refer to parts of it. 2523.Pp 2524.It \-xbd5 2525.St -xbd5 2526.Pp 2527.It \-xsh5 2528.St -xsh5 2529.Pp 2530.It \-xcu5 2531.St -xcu5 2532.Pp 2533.It \-xns5 2534.St -xns5 2535.It \-xns5.2 2536.St -xns5.2 2537.El 2538.It Single UNIX Specification version 3 2539.Pp 2540.Bl -tag -width "-p1003.1-2001" -compact 2541.It \-p1003.1-2001 2542.St -p1003.1-2001 2543.It \-susv3 2544.St -susv3 2545.br 2546This standard is based on C99, SUSv2, POSIX.1-1996, 1d, and 1j. 2547It is also called X/Open Portability Guide version 6. 2548It is used as the basis for UNIX 03 certification. 2549.Pp 2550.It \-p1003.1-2004 2551.St -p1003.1-2004 2552.br 2553The second and last Technical Corrigendum. 2554.El 2555.It POSIX issues 7 and 8 2556.Pp 2557.Bl -tag -width "-p1003.1g-2000" -compact 2558.It \-p1003.1-2008 2559.St -p1003.1-2008 2560.It \-susv4 2561.St -susv4 2562.br 2563This standard is based on C99. 2564It is also called the 2565Open Group Standard Base Specifications, Issue 7. 2566.El 2567.Pp 2568.Bl -tag -width "-p1003.1g-2000" -compact 2569.It \-p1003.1-2024 2570.St -p1003.1-2024 2571.br 2572This standard is based on C17. 2573It is also called the 2574Open Group Standard Base Specifications, Issue 8. 2575.El 2576.It Other standards 2577.Pp 2578.Bl -tag -width "-p1003.1g-2000" -compact 2579.It \-ieee754 2580.St -ieee754 2581.br 2582Floating-point arithmetic. 2583.Pp 2584.It \-iso8601 2585.St -iso8601 2586.br 2587Representation of dates and times, published in 1988. 2588.Pp 2589.It \-iso8802-3 2590.St -iso8802-3 2591.br 2592Ethernet local area networks. 2593.Pp 2594.It \-ieee1275-94 2595.St -ieee1275-94 2596.El 2597.El 2598.Tg Sx 2599.It Ic \&Sx Ar Title line 2600Reference a section or subsection in the same manual page. 2601The referenced section or subsection name must be identical to the 2602enclosed argument, including whitespace. 2603.Pp 2604Examples: 2605.Dl \&.Sx MANUAL STRUCTURE 2606.Pp 2607See also 2608.Ic \&Sh 2609and 2610.Ic \&Ss . 2611.Tg Sy 2612.It Ic \&Sy Ar word ... 2613Request a boldface font. 2614.Pp 2615This is most often used to indicate importance or seriousness (not to be 2616confused with stress emphasis, see 2617.Ic \&Em ) . 2618When none of the semantic macros fit, it is also adequate for syntax 2619elements that have to be given or that appear verbatim. 2620.Pp 2621Examples: 2622.Bd -literal -compact -offset indent 2623\&.Sy Warning : 2624If 2625\&.Sy s 2626appears in the owner permissions, set-user-ID mode is set. 2627This utility replaces the former 2628\&.Sy dumpdir 2629program. 2630.Ed 2631.Pp 2632See also 2633.Ic \&Em , 2634.Ic \&No , 2635and 2636.Ic \&Ql . 2637.Tg Ta 2638.It Ic \&Ta 2639Table cell separator in 2640.Ic \&Bl Fl column 2641lists; can only be used below 2642.Ic \&It . 2643.Tg Tg 2644.It Ic \&Tg Op Ar term 2645Announce that the next input line starts a definition of the 2646.Ar term . 2647This macro must appear alone on its own input line. 2648The argument defaults to the first argument of the first macro 2649on the next line. 2650The argument may not contain whitespace characters, not even when it is quoted. 2651This macro is a 2652.Xr mandoc 1 2653extension and is typically ignored by other formatters. 2654.Pp 2655When viewing terminal output with 2656.Xr less 1 , 2657the interactive 2658.Ic :t 2659command can be used to go to the definition of the 2660.Ar term 2661as described for the 2662.Ev MANPAGER 2663variable in 2664.Xr man 1 ; 2665when producing HTML output, a fragment identifier 2666.Pq Ic id No attribute 2667is generated, to be used for deep linking to this place of the document. 2668.Pp 2669In most cases, adding a 2670.Ic \&Tg 2671macro would be redundant because 2672.Xr mandoc 1 2673is able to automatically tag most definitions. 2674This macro is intended for cases where automatic tagging of a 2675.Ar term 2676is unsatisfactory, for example if a definition is not tagged 2677automatically (false negative) or if places are tagged that do 2678not define the 2679.Ar term 2680(false positives). 2681When there is at least one 2682.Ic \&Tg 2683macro for a 2684.Ar term , 2685no other places are automatically marked as definitions of that 2686.Ar term . 2687.It Ic \&Tn Ar word ... 2688Supported only for compatibility, do not use this in new manuals. 2689Even though the macro name 2690.Pq Dq tradename 2691suggests a semantic function, historic usage is inconsistent, mostly 2692using it as a presentation-level macro to request a small caps font. 2693.It Ic \&Ud 2694Supported only for compatibility, do not use this in new manuals. 2695Prints out 2696.Dq currently under development. 2697.It Ic \&Ux 2698Supported only for compatibility, do not use this in new manuals. 2699Prints out 2700.Dq Ux . 2701.Tg Va 2702.It Ic \&Va Oo Ar type Oc Ar identifier ... 2703A variable name. 2704.Pp 2705Examples: 2706.Dl \&.Va foo 2707.Dl \&.Va const char *bar ; 2708.Pp 2709For function arguments and parameters, use 2710.Ic \&Fa 2711instead. 2712For declarations of global variables in the 2713.Em SYNOPSIS 2714section, use 2715.Ic \&Vt . 2716.Tg Vt 2717.It Ic \&Vt Ar type Op Ar identifier 2718A variable type. 2719.Pp 2720This is also used for indicating global variables in the 2721.Em SYNOPSIS 2722section, in which case a variable name is also specified. 2723Note that it accepts 2724.Sx Block partial-implicit 2725syntax when invoked as the first macro on an input line in the 2726.Em SYNOPSIS 2727section, else it accepts ordinary 2728.Sx In-line 2729syntax. 2730In the former case, this macro starts a new output line, 2731and a blank line is inserted in front if there is a preceding 2732function definition or include directive. 2733.Pp 2734Examples: 2735.Dl \&.Vt unsigned char 2736.Dl \&.Vt extern const char * const sys_signame[] \&; 2737.Pp 2738For parameters in function prototypes, use 2739.Ic \&Fa 2740instead, for function return types 2741.Ic \&Ft , 2742and for variable names outside the 2743.Em SYNOPSIS 2744section 2745.Ic \&Va , 2746even when including a type with the name. 2747See also 2748.Sx MANUAL STRUCTURE . 2749.It Ic \&Xc 2750Close a scope opened by 2751.Ic \&Xo . 2752.It Ic \&Xo Ar block 2753Extend the header of an 2754.Ic \&It 2755macro or the body of a partial-implicit block macro 2756beyond the end of the input line. 2757This macro originally existed to work around the 9-argument limit 2758of historic 2759.Xr roff 7 . 2760.Tg Xr 2761.It Ic \&Xr Ar name section 2762Link to another manual 2763.Pq Qq cross-reference . 2764.Pp 2765Cross reference the 2766.Ar name 2767and 2768.Ar section 2769number of another man page. 2770.Pp 2771Examples: 2772.Dl \&.Xr mandoc 1 2773.Dl \&.Xr mandoc 1 \&; 2774.Dl \&.Xr mandoc 1 \&Ns s behaviour 2775.El 2776.Sh MACRO SYNTAX 2777The syntax of a macro depends on its classification. 2778In this section, 2779.Sq \-arg 2780refers to macro arguments, which may be followed by zero or more 2781.Sq parm 2782parameters; 2783.Sq \&Yo 2784opens the scope of a macro; and if specified, 2785.Sq \&Yc 2786closes it out. 2787.Pp 2788The 2789.Em Callable 2790column indicates that the macro may also be called by passing its name 2791as an argument to another macro. 2792For example, 2793.Sq \&.Op \&Fl O \&Ar file 2794produces 2795.Sq Op Fl O Ar file . 2796To prevent a macro call and render the macro name literally, 2797escape it by prepending a zero-width space, 2798.Sq \e& . 2799For example, 2800.Sq \&Op \e&Fl O 2801produces 2802.Sq Op \&Fl O . 2803If a macro is not callable but its name appears as an argument 2804to another macro, it is interpreted as opaque text. 2805For example, 2806.Sq \&.Fl \&Sh 2807produces 2808.Sq Fl \&Sh . 2809.Pp 2810The 2811.Em Parsed 2812column indicates whether the macro may call other macros by receiving 2813their names as arguments. 2814If a macro is not parsed but the name of another macro appears 2815as an argument, it is interpreted as opaque text. 2816.Pp 2817The 2818.Em Scope 2819column, if applicable, describes closure rules. 2820.Ss Block full-explicit 2821Multi-line scope closed by an explicit closing macro. 2822All macros contains bodies; only 2823.Ic \&Bf 2824and 2825.Pq optionally 2826.Ic \&Bl 2827contain a head. 2828.Bd -literal -offset indent 2829\&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB 2830\(lBbody...\(rB 2831\&.Yc 2832.Ed 2833.Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXX" -offset indent 2834.It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope 2835.It Ic \&Bd Ta \&No Ta \&No Ta closed by Ic \&Ed 2836.It Ic \&Bf Ta \&No Ta \&No Ta closed by Ic \&Ef 2837.It Ic \&Bk Ta \&No Ta \&No Ta closed by Ic \&Ek 2838.It Ic \&Bl Ta \&No Ta \&No Ta closed by Ic \&El 2839.It Ic \&Ed Ta \&No Ta \&No Ta opened by Ic \&Bd 2840.It Ic \&Ef Ta \&No Ta \&No Ta opened by Ic \&Bf 2841.It Ic \&Ek Ta \&No Ta \&No Ta opened by Ic \&Bk 2842.It Ic \&El Ta \&No Ta \&No Ta opened by Ic \&Bl 2843.El 2844.Ss Block full-implicit 2845Multi-line scope closed by end-of-file or implicitly by another macro. 2846All macros have bodies; some 2847.Po 2848.Ic \&It Fl bullet , 2849.Fl hyphen , 2850.Fl dash , 2851.Fl enum , 2852.Fl item 2853.Pc 2854don't have heads; only one 2855.Po 2856.Ic \&It 2857in 2858.Ic \&Bl Fl column 2859.Pc 2860has multiple heads. 2861.Bd -literal -offset indent 2862\&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead... \(lBTa head...\(rB\(rB 2863\(lBbody...\(rB 2864.Ed 2865.Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXXXXXXXXXX" -offset indent 2866.It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope 2867.It Ic \&It Ta \&No Ta Yes Ta closed by Ic \&It , Ic \&El 2868.It Ic \&Nd Ta \&No Ta \&No Ta closed by Ic \&Sh 2869.It Ic \&Nm Ta \&No Ta Yes Ta closed by Ic \&Nm , Ic \&Sh , Ic \&Ss 2870.It Ic \&Sh Ta \&No Ta Yes Ta closed by Ic \&Sh 2871.It Ic \&Ss Ta \&No Ta Yes Ta closed by Ic \&Sh , Ic \&Ss 2872.El 2873.Pp 2874Note that the 2875.Ic \&Nm 2876macro is a 2877.Sx Block full-implicit 2878macro only when invoked as the first macro 2879in a 2880.Em SYNOPSIS 2881section line, else it is 2882.Sx In-line . 2883.Ss Block partial-explicit 2884Like block full-explicit, but also with single-line scope. 2885Each has at least a body and, in limited circumstances, a head 2886.Po 2887.Ic \&Fo , 2888.Ic \&Eo 2889.Pc 2890and/or tail 2891.Pq Ic \&Ec . 2892.Bd -literal -offset indent 2893\&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB 2894\(lBbody...\(rB 2895\&.Yc \(lBtail...\(rB 2896 2897\&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB \ 2898\(lBbody...\(rB \&Yc \(lBtail...\(rB 2899.Ed 2900.Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXXX" -offset indent 2901.It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope 2902.It Ic \&Ac Ta Yes Ta Yes Ta opened by Ic \&Ao 2903.It Ic \&Ao Ta Yes Ta Yes Ta closed by Ic \&Ac 2904.It Ic \&Bc Ta Yes Ta Yes Ta closed by Ic \&Bo 2905.It Ic \&Bo Ta Yes Ta Yes Ta opened by Ic \&Bc 2906.It Ic \&Brc Ta Yes Ta Yes Ta opened by Ic \&Bro 2907.It Ic \&Bro Ta Yes Ta Yes Ta closed by Ic \&Brc 2908.It Ic \&Dc Ta Yes Ta Yes Ta opened by Ic \&Do 2909.It Ic \&Do Ta Yes Ta Yes Ta closed by Ic \&Dc 2910.It Ic \&Ec Ta Yes Ta Yes Ta opened by Ic \&Eo 2911.It Ic \&Eo Ta Yes Ta Yes Ta closed by Ic \&Ec 2912.It Ic \&Fc Ta Yes Ta Yes Ta opened by Ic \&Fo 2913.It Ic \&Fo Ta \&No Ta \&No Ta closed by Ic \&Fc 2914.It Ic \&Oc Ta Yes Ta Yes Ta closed by Ic \&Oo 2915.It Ic \&Oo Ta Yes Ta Yes Ta opened by Ic \&Oc 2916.It Ic \&Pc Ta Yes Ta Yes Ta closed by Ic \&Po 2917.It Ic \&Po Ta Yes Ta Yes Ta opened by Ic \&Pc 2918.It Ic \&Qc Ta Yes Ta Yes Ta opened by Ic \&Oo 2919.It Ic \&Qo Ta Yes Ta Yes Ta closed by Ic \&Oc 2920.It Ic \&Re Ta \&No Ta \&No Ta opened by Ic \&Rs 2921.It Ic \&Rs Ta \&No Ta \&No Ta closed by Ic \&Re 2922.It Ic \&Sc Ta Yes Ta Yes Ta opened by Ic \&So 2923.It Ic \&So Ta Yes Ta Yes Ta closed by Ic \&Sc 2924.It Ic \&Xc Ta Yes Ta Yes Ta opened by Ic \&Xo 2925.It Ic \&Xo Ta Yes Ta Yes Ta closed by Ic \&Xc 2926.El 2927.Ss Block partial-implicit 2928Like block full-implicit, but with single-line scope closed by the 2929end of the line. 2930.Bd -literal -offset indent 2931\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBbody...\(rB \(lBres...\(rB 2932.Ed 2933.Bl -column "MacroX" "CallableX" "ParsedX" -offset indent 2934.It Em Macro Ta Em Callable Ta Em Parsed 2935.It Ic \&Aq Ta Yes Ta Yes 2936.It Ic \&Bq Ta Yes Ta Yes 2937.It Ic \&Brq Ta Yes Ta Yes 2938.It Ic \&D1 Ta \&No Ta \&Yes 2939.It Ic \&Dl Ta \&No Ta Yes 2940.It Ic \&Dq Ta Yes Ta Yes 2941.It Ic \&En Ta Yes Ta Yes 2942.It Ic \&Op Ta Yes Ta Yes 2943.It Ic \&Pq Ta Yes Ta Yes 2944.It Ic \&Ql Ta Yes Ta Yes 2945.It Ic \&Qq Ta Yes Ta Yes 2946.It Ic \&Sq Ta Yes Ta Yes 2947.It Ic \&Vt Ta Yes Ta Yes 2948.El 2949.Pp 2950Note that the 2951.Ic \&Vt 2952macro is a 2953.Sx Block partial-implicit 2954only when invoked as the first macro 2955in a 2956.Em SYNOPSIS 2957section line, else it is 2958.Sx In-line . 2959.Ss Special block macro 2960The 2961.Ic \&Ta 2962macro can only be used below 2963.Ic \&It 2964in 2965.Ic \&Bl Fl column 2966lists. 2967It delimits blocks representing table cells; 2968these blocks have bodies, but no heads. 2969.Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXXX" -offset indent 2970.It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope 2971.It Ic \&Ta Ta Yes Ta Yes Ta closed by Ic \&Ta , Ic \&It 2972.El 2973.Ss In-line 2974Closed by the end of the line, fixed argument lengths, 2975and/or subsequent macros. 2976In-line macros have only text children. 2977If a number (or inequality) of arguments is 2978.Pq n , 2979then the macro accepts an arbitrary number of arguments. 2980.Bd -literal -offset indent 2981\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB \(lBres...\(rB 2982 2983\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB Yc... 2984 2985\&.Yo \(lB\-arg \(lBval...\(rB\(rB arg0 arg1 argN 2986.Ed 2987.Bl -column "MacroX" "CallableX" "ParsedX" "Arguments" -offset indent 2988.It Em Macro Ta Em Callable Ta Em Parsed Ta Em Arguments 2989.It Ic \&%A Ta \&No Ta \&No Ta >0 2990.It Ic \&%B Ta \&No Ta \&No Ta >0 2991.It Ic \&%C Ta \&No Ta \&No Ta >0 2992.It Ic \&%D Ta \&No Ta \&No Ta >0 2993.It Ic \&%I Ta \&No Ta \&No Ta >0 2994.It Ic \&%J Ta \&No Ta \&No Ta >0 2995.It Ic \&%N Ta \&No Ta \&No Ta >0 2996.It Ic \&%O Ta \&No Ta \&No Ta >0 2997.It Ic \&%P Ta \&No Ta \&No Ta >0 2998.It Ic \&%Q Ta \&No Ta \&No Ta >0 2999.It Ic \&%R Ta \&No Ta \&No Ta >0 3000.It Ic \&%T Ta \&No Ta \&No Ta >0 3001.It Ic \&%U Ta \&No Ta \&No Ta >0 3002.It Ic \&%V Ta \&No Ta \&No Ta >0 3003.It Ic \&Ad Ta Yes Ta Yes Ta >0 3004.It Ic \&An Ta Yes Ta Yes Ta >0 3005.It Ic \&Ap Ta Yes Ta Yes Ta 0 3006.It Ic \&Ar Ta Yes Ta Yes Ta n 3007.It Ic \&At Ta Yes Ta Yes Ta 1 3008.It Ic \&Bsx Ta Yes Ta Yes Ta n 3009.It Ic \&Bt Ta \&No Ta \&No Ta 0 3010.It Ic \&Bx Ta Yes Ta Yes Ta n 3011.It Ic \&Cd Ta Yes Ta Yes Ta >0 3012.It Ic \&Cm Ta Yes Ta Yes Ta >0 3013.It Ic \&Db Ta \&No Ta \&No Ta 1 3014.It Ic \&Dd Ta \&No Ta \&No Ta n 3015.It Ic \&Dt Ta \&No Ta \&No Ta n 3016.It Ic \&Dv Ta Yes Ta Yes Ta >0 3017.It Ic \&Dx Ta Yes Ta Yes Ta n 3018.It Ic \&Em Ta Yes Ta Yes Ta >0 3019.It Ic \&Er Ta Yes Ta Yes Ta >0 3020.It Ic \&Es Ta Yes Ta Yes Ta 2 3021.It Ic \&Ev Ta Yes Ta Yes Ta >0 3022.It Ic \&Ex Ta \&No Ta \&No Ta n 3023.It Ic \&Fa Ta Yes Ta Yes Ta >0 3024.It Ic \&Fd Ta \&No Ta \&No Ta >0 3025.It Ic \&Fl Ta Yes Ta Yes Ta n 3026.It Ic \&Fn Ta Yes Ta Yes Ta >0 3027.It Ic \&Fr Ta Yes Ta Yes Ta >0 3028.It Ic \&Ft Ta Yes Ta Yes Ta >0 3029.It Ic \&Fx Ta Yes Ta Yes Ta n 3030.It Ic \&Hf Ta \&No Ta \&No Ta n 3031.It Ic \&Ic Ta Yes Ta Yes Ta >0 3032.It Ic \&In Ta \&No Ta \&No Ta 1 3033.It Ic \&Lb Ta \&No Ta \&No Ta 1 3034.It Ic \&Li Ta Yes Ta Yes Ta >0 3035.It Ic \&Lk Ta Yes Ta Yes Ta >0 3036.It Ic \&Lp Ta \&No Ta \&No Ta 0 3037.It Ic \&Ms Ta Yes Ta Yes Ta >0 3038.It Ic \&Mt Ta Yes Ta Yes Ta >0 3039.It Ic \&Nm Ta Yes Ta Yes Ta n 3040.It Ic \&No Ta Yes Ta Yes Ta >0 3041.It Ic \&Ns Ta Yes Ta Yes Ta 0 3042.It Ic \&Nx Ta Yes Ta Yes Ta n 3043.It Ic \&Os Ta \&No Ta \&No Ta n 3044.It Ic \&Ot Ta Yes Ta Yes Ta >0 3045.It Ic \&Ox Ta Yes Ta Yes Ta n 3046.It Ic \&Pa Ta Yes Ta Yes Ta n 3047.It Ic \&Pf Ta Yes Ta Yes Ta 1 3048.It Ic \&Pp Ta \&No Ta \&No Ta 0 3049.It Ic \&Rv Ta \&No Ta \&No Ta n 3050.It Ic \&Sm Ta \&No Ta \&No Ta <2 3051.It Ic \&St Ta \&No Ta Yes Ta 1 3052.It Ic \&Sx Ta Yes Ta Yes Ta >0 3053.It Ic \&Sy Ta Yes Ta Yes Ta >0 3054.It Ic \&Tg Ta \&No Ta \&No Ta <2 3055.It Ic \&Tn Ta Yes Ta Yes Ta >0 3056.It Ic \&Ud Ta \&No Ta \&No Ta 0 3057.It Ic \&Ux Ta Yes Ta Yes Ta n 3058.It Ic \&Va Ta Yes Ta Yes Ta n 3059.It Ic \&Vt Ta Yes Ta Yes Ta >0 3060.It Ic \&Xr Ta Yes Ta Yes Ta 2 3061.El 3062.Ss Delimiters 3063When a macro argument consists of one single input character 3064considered as a delimiter, the argument gets special handling. 3065This does not apply when delimiters appear in arguments containing 3066more than one character. 3067Consequently, to prevent special handling and just handle it 3068like any other argument, a delimiter can be escaped by prepending 3069a zero-width space 3070.Pq Sq \e& . 3071In text lines, delimiters never need escaping, but may be used 3072as normal punctuation. 3073.Pp 3074For many macros, when the leading arguments are opening delimiters, 3075these delimiters are put before the macro scope, 3076and when the trailing arguments are closing delimiters, 3077these delimiters are put after the macro scope. 3078Spacing is suppressed after opening delimiters 3079and before closing delimiters. 3080For example, 3081.Pp 3082.D1 Pf \. \&Aq "( [ word ] ) ." 3083.Pp 3084renders as: 3085.Pp 3086.D1 Aq ( [ word ] ) . 3087.Pp 3088Opening delimiters are: 3089.Pp 3090.Bl -tag -width Ds -offset indent -compact 3091.It \&( 3092left parenthesis 3093.It \&[ 3094left bracket 3095.El 3096.Pp 3097Closing delimiters are: 3098.Pp 3099.Bl -tag -width Ds -offset indent -compact 3100.It \&. 3101period 3102.It \&, 3103comma 3104.It \&: 3105colon 3106.It \&; 3107semicolon 3108.It \&) 3109right parenthesis 3110.It \&] 3111right bracket 3112.It \&? 3113question mark 3114.It \&! 3115exclamation mark 3116.El 3117.Pp 3118Note that even a period preceded by a backslash 3119.Pq Sq \e.\& 3120gets this special handling; use 3121.Sq \e&.\& 3122to prevent that. 3123.Pp 3124Many in-line macros interrupt their scope when they encounter 3125delimiters, and resume their scope when more arguments follow that 3126are not delimiters. 3127For example, 3128.Pp 3129.D1 Pf \. \&Fl "a ( b | c \e*(Ba d ) e" 3130.Pp 3131renders as: 3132.Pp 3133.D1 Fl a ( b | c \*(Ba d ) e 3134.Pp 3135This applies to both opening and closing delimiters, 3136and also to the middle delimiter, which does not suppress spacing: 3137.Pp 3138.Bl -tag -width Ds -offset indent -compact 3139.It \&| 3140vertical bar 3141.El 3142.Pp 3143As a special case, the predefined string \e*(Ba is handled and rendered 3144in the same way as a plain 3145.Sq \&| 3146character. 3147Using this predefined string is not recommended in new manuals. 3148.Pp 3149Appending a zero-width space 3150.Pq Sq \e& 3151to the end of an input line is also useful to prevent the interpretation 3152of a trailing period, exclamation or question mark as the end of a 3153sentence, for example when an abbreviation happens to occur 3154at the end of a text or macro input line. 3155.Ss Font handling 3156In 3157.Nm 3158documents, usage of semantic markup is recommended in order to have 3159proper fonts automatically selected; only when no fitting semantic markup 3160is available, consider falling back to 3161.Sx Physical markup 3162macros. 3163Whenever any 3164.Nm 3165macro switches the 3166.Xr roff 7 3167font mode, it will automatically restore the previous font when exiting 3168its scope. 3169Manually switching the font using the 3170.Xr roff 7 3171.Ql \ef 3172font escape sequences is never required. 3173.Sh COMPATIBILITY 3174This section provides an incomplete list of compatibility issues 3175between mandoc and GNU troff 3176.Pq Qq groff . 3177.Pp 3178The following problematic behaviour is found in groff: 3179.Pp 3180.Bl -dash -compact 3181.It 3182.Ic \&Pa 3183does not format its arguments when used in the FILES section under 3184certain list types. 3185.It 3186.Ic \&Ta 3187can only be called by other macros, but not at the beginning of a line. 3188.It 3189.Sq \ef 3190.Pq font face 3191and 3192.Sq \eF 3193.Pq font family face 3194.Sx Text Decoration 3195escapes behave irregularly when specified within line-macro scopes. 3196.It 3197Negative scaling units return to prior lines. 3198Instead, mandoc truncates them to zero. 3199.El 3200.Pp 3201The following features are unimplemented in mandoc: 3202.Pp 3203.Bl -dash -compact 3204.It 3205.Ic \&Bd Fl file Ar file 3206is unsupported for security reasons. 3207.It 3208.Ic \&Bd 3209.Fl filled 3210does not adjust the right margin, but is an alias for 3211.Ic \&Bd 3212.Fl ragged . 3213.It 3214.Ic \&Bd 3215.Fl literal 3216does not use a literal font, but is an alias for 3217.Ic \&Bd 3218.Fl unfilled . 3219.It 3220.Ic \&Bd 3221.Fl offset Cm center 3222and 3223.Fl offset Cm right 3224don't work. 3225Groff does not implement centered and flush-right rendering either, 3226but produces large indentations. 3227.El 3228.Sh SEE ALSO 3229.Xr man 1 , 3230.Xr mandoc 1 , 3231.Xr eqn 7 , 3232.Xr man 7 , 3233.Xr mandoc_char 7 , 3234.Xr roff 7 , 3235.Xr tbl 7 3236.Pp 3237The web page 3238.Lk https://mandoc.bsd.lv/mdoc/ "extended documentation for the mdoc language" 3239provides a few tutorial-style pages for beginners, an extensive style 3240guide for advanced authors, and an alphabetic index helping to choose 3241the best macros for various kinds of content. 3242.Pp 3243The manual page 3244.Lk https://man.voidlinux.org/groff_mdoc "groff_mdoc(7)" 3245contained in the 3246.Dq groff 3247package documents exactly the same language in a somewhat different style. 3248.Sh HISTORY 3249The 3250.Nm 3251language first appeared as a troff macro package in 3252.Bx 4.4 . 3253It was later significantly updated by Werner Lemberg and Ruslan Ermilov 3254in groff-1.17. 3255The standalone implementation that is part of the 3256.Xr mandoc 1 3257utility written by Kristaps Dzonsons appeared in 3258.Ox 4.6 . 3259.Sh AUTHORS 3260The 3261.Nm 3262reference was written by 3263.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv . 3264