1MDOC(7) BSD Miscellaneous Information Manual MDOC(7)
2
4 mdoc — semantic markup language for formatting manual pages
5
7 The mdoc language supports authoring of manual pages for the man(1) util‐
8 ity by allowing semantic annotations of words, phrases, page sections and
9 complete manual pages. Such annotations are used by formatting tools to
10 achieve a uniform presentation across all manuals written in mdoc, and to
11 support hyperlinking if supported by the output medium.
12 This reference document describes the structure of manual pages and the
14 syntax and usage of the mdoc language. The reference implementation of a
15 parsing and formatting tool is mandoc(1); the COMPATIBILITY section
16 describes compatibility with other implementations.
17 In an mdoc document, lines beginning with the control character ‘.’ are
19 called “macro lines”. The first word is the macro name. It consists of
20 two or three letters. Most macro names begin with a capital letter. For
21 a list of available macros, see MACRO OVERVIEW. The words following the
22 macro name are arguments to the macro, optionally including the names of
23 other, callable macros; see MACRO SYNTAX for details.
24 Lines not beginning with the control character are called “text lines”.
26 They provide free-form text to be printed; the formatting of the text
27 depends on the respective processing context:
28 .Sh Macro lines change control state.
30 Text lines are interpreted within the current state.
31 Many aspects of the basic syntax of the mdoc language are based on the
33 roff(7) language; see the LANGUAGE SYNTAX and MACRO SYNTAX sections in
34 the roff(7) manual for details, in particular regarding comments, escape
35 sequences, whitespace, and quoting. However, using roff(7) requests in
36 mdoc documents is discouraged; mandoc(1) supports some of them merely for
37 backward compatibility.
38
40 A well-formed mdoc document consists of a document prologue followed by
41 one or more sections.
42 The prologue, which consists of the Dd, Dt, and Os macros in that order,
44 is required for every document.
45 The first section (sections are denoted by Sh) must be the NAME section,
47 consisting of at least one Nm followed by Nd.
48 Following that, convention dictates specifying at least the SYNOPSIS and
50 DESCRIPTION sections, although this varies between manual sections.
51 The following is a well-formed skeleton mdoc file for a utility
53 "progname":
54 .Dd $Mdocdate$
56 .Dt PROGNAME section
57 .Os
58 .Sh NAME
59 .Nm progname
60 .Nd one line about what it does
61 .\" .Sh LIBRARY
62 .\" For sections 2, 3, and 9 only.
63 .\" Not used in OpenBSD.
64 .Sh SYNOPSIS
65 .Nm progname
66 .Op Fl options
67 .Ar
68 .Sh DESCRIPTION
69 The
70 .Nm
71 utility processes files ...
72 .\" .Sh CONTEXT
73 .\" For section 9 functions only.
74 .\" .Sh IMPLEMENTATION NOTES
75 .\" Not used in OpenBSD.
76 .\" .Sh RETURN VALUES
77 .\" For sections 2, 3, and 9 function return values only.
78 .\" .Sh ENVIRONMENT
79 .\" For sections 1, 6, 7, and 8 only.
80 .\" .Sh FILES
81 .\" .Sh EXIT STATUS
82 .\" For sections 1, 6, and 8 only.
83 .\" .Sh EXAMPLES
84 .\" .Sh DIAGNOSTICS
85 .\" For sections 1, 4, 6, 7, 8, and 9 printf/stderr messages only.
86 .\" .Sh ERRORS
87 .\" For sections 2, 3, 4, and 9 errno settings only.
88 .\" .Sh SEE ALSO
89 .\" .Xr foobar 1
90 .\" .Sh STANDARDS
91 .\" .Sh HISTORY
92 .\" .Sh AUTHORS
93 .\" .Sh CAVEATS
94 .\" .Sh BUGS
95 .\" .Sh SECURITY CONSIDERATIONS
96 .\" Not used in OpenBSD.
97 The sections in an mdoc document are conventionally ordered as they
99 appear above. Sections should be composed as follows:
100 NAME
102 The name(s) and a one line description of the documented material.
103 The syntax for this as follows:
104 .Nm name0 ,
106 .Nm name1 ,
107 .Nm name2
108 .Nd a one line description
109 Multiple ‘Nm’ names should be separated by commas.
111 The Nm macro(s) must precede the Nd macro.
113 See Nm and Nd.
115 LIBRARY
117 The name of the library containing the documented material, which
118 is assumed to be a function in a section 2, 3, or 9 manual. The
119 syntax for this is as follows:
120 .Lb libarm
122 See Lb.
124 SYNOPSIS
126 Documents the utility invocation syntax, function call syntax, or
127 device configuration.
128 For the first, utilities (sections 1, 6, and 8), this is generally
130 structured as follows:
131 .Nm bar
133 .Op Fl v
134 .Op Fl o Ar file
135 .Op Ar
136 .Nm foo
137 .Op Fl v
138 .Op Fl o Ar file
139 .Op Ar
140 Commands should be ordered alphabetically.
142 For the second, function calls (sections 2, 3, 9):
144 .In header.h
146 .Vt extern const char *global;
147 .Ft "char *"
148 .Fn foo "const char *src"
149 .Ft "char *"
150 .Fn bar "const char *src"
151 Ordering of In, Vt, Fn, and Fo macros should follow C header-file
153 conventions.
154 And for the third, configurations (section 4):
156 .Cd "it* at isa? port 0x2e"
158 .Cd "it* at isa? port 0x4e"
159 Manuals not in these sections generally don't need a SYNOPSIS.
161 Some macros are displayed differently in the SYNOPSIS section, par‐
163 ticularly Nm, Cd, Fd, Fn, Fo, In, Vt, and Ft. All of these macros
164 are output on their own line. If two such dissimilar macros are
165 pairwise invoked (except for Ft before Fo or Fn), they are sepa‐
166 rated by a vertical space, unless in the case of Fo, Fn, and Ft,
167 which are always separated by vertical space.
168 When text and macros following an Nm macro starting an input line
170 span multiple output lines, all output lines but the first will be
171 indented to align with the text immediately following the Nm macro,
172 up to the next Nm, Sh, or Ss macro or the end of an enclosing
173 block, whichever comes first.
174 DESCRIPTION
176 This begins with an expansion of the brief, one line description in
177 NAME:
178 The
180 .Nm
181 utility does this, that, and the other.
182 It usually follows with a breakdown of the options (if documenting
184 a command), such as:
185 The arguments are as follows:
187 .Bl -tag -width Ds
188 .It Fl v
189 Print verbose information.
190 .El
191 List the options in alphabetical order, uppercase before lowercase
193 for each letter and with no regard to whether an option takes an
194 argument. Put digits in ascending order before all letter options.
195 Manuals not documenting a command won't include the above fragment.
197 Since the DESCRIPTION section usually contains most of the text of
199 a manual, longer manuals often use the Ss macro to form subsec‐
200 tions. In very long manuals, the DESCRIPTION may be split into
201 multiple sections, each started by an Sh macro followed by a non-
202 standard section name, and each having several subsections, like in
203 the present mdoc manual.
204 CONTEXT
206 This section lists the contexts in which functions can be called in
207 section 9. The contexts are autoconf, process, or interrupt.
208 IMPLEMENTATION NOTES
210 Implementation-specific notes should be kept here. This is useful
211 when implementing standard functions that may have side effects or
212 notable algorithmic implications.
213 RETURN VALUES
215 This section documents the return values of functions in sections
216 2, 3, and 9.
217 See Rv.
219 ENVIRONMENT
221 Lists the environment variables used by the utility, and explains
222 the syntax and semantics of their values. The environ(7) manual
223 provides examples of typical content and formatting.
224 See Ev.
226 FILES
228 Documents files used. It's helpful to document both the file name
229 and a short description of how the file is used (created, modified,
230 etc.).
231 See Pa.
233 EXIT STATUS
235 This section documents the command exit status for section 1, 6,
236 and 8 utilities. Historically, this information was described in
237 DIAGNOSTICS, a practise that is now discouraged.
238 See Ex.
240 EXAMPLES
242 Example usages. This often contains snippets of well-formed, well-
243 tested invocations. Make sure that examples work properly!
244 DIAGNOSTICS
246 Documents error messages. In section 4 and 9 manuals, these are
247 usually messages printed by the kernel to the console and to the
248 kernel log. In section 1, 6, 7, and 8, these are usually messages
249 printed by userland programs to the standard error output.
250 Historically, this section was used in place of EXIT STATUS for
252 manuals in sections 1, 6, and 8; however, this practise is discour‐
253 aged.
254 See Bl -diag.
256 ERRORS
258 Documents errno(2) settings in sections 2, 3, 4, and 9.
259 See Er.
261 SEE ALSO
263 References other manuals with related topics. This section should
264 exist for most manuals. Cross-references should conventionally be
265 ordered first by section, then alphabetically (ignoring case).
266 References to other documentation concerning the topic of the man‐
268 ual page, for example authoritative books or journal articles, may
269 also be provided in this section.
270 See Rs and Xr.
272 STANDARDS
274 References any standards implemented or used. If not adhering to
275 any standards, the HISTORY section should be used instead.
276 See St.
278 HISTORY
280 A brief history of the subject, including where it was first imple‐
281 mented, and when it was ported to or reimplemented for the operat‐
282 ing system at hand.
283 AUTHORS
285 Credits to the person or persons who wrote the code and/or documen‐
286 tation. Authors should generally be noted by both name and email
287 address.
288 See An.
290 CAVEATS
292 Common misuses and misunderstandings should be explained in this
293 section.
294 BUGS
296 Known bugs, limitations, and work-arounds should be described in
297 this section.
298 SECURITY CONSIDERATIONS
300 Documents any security precautions that operators should consider.
301
303 This overview is sorted such that macros of similar purpose are listed
304 together, to help find the best macro for any given purpose. Deprecated
305 macros are not included in the overview, but can be found below in the
306 alphabetical MACRO REFERENCE.
307 Document preamble and NAME section macros
309 Dd document date: $Mdocdate$ | month day, year
310 Dt document title: TITLE section [arch]
311 Os operating system version: [system [version]]
312 Nm document name (one argument)
313 Nd document description (one line)
314 Sections and cross references
316 Sh section header (one line)
317 Ss subsection header (one line)
318 Sx internal cross reference to a section or subsection
319 Xr cross reference to another manual page: name section
320 Pp, Lp start a text paragraph (no arguments)
321 Displays and lists
323 Bd, Ed display block: -type [-offset width] [-compact]
324 D1 indented display (one line)
325 Dl indented literal display (one line)
326 Ql in-line literal display: ‘text’
327 Bl, El list block: -type [-width val] [-offset val] [-compact]
328 It list item (syntax depends on -type)
329 Ta table cell separator in Bl -column lists
330 Rs, %*, Re bibliographic block (references)
331 Spacing control
333 Pf prefix, no following horizontal space (one argument)
334 Ns roman font, no preceding horizontal space (no arguments)
335 Ap apostrophe without surrounding whitespace (no arguments)
336 Sm switch horizontal spacing mode: [on | off]
337 Bk, Ek keep block: -words
338 Semantic markup for command line utilities
340 Nm start a SYNOPSIS block with the name of a utility
341 Fl command line options (flags) (>=0 arguments)
342 Cm command modifier (>0 arguments)
343 Ar command arguments (>=0 arguments)
344 Op, Oo, Oc optional syntax elements (enclosure)
345 Ic internal or interactive command (>0 arguments)
346 Ev environmental variable (>0 arguments)
347 Pa file system path (>=0 arguments)
348 Semantic markup for function libraries
350 Lb function library (one argument)
351 In include file (one argument)
352 Fd other preprocessor directive (>0 arguments)
353 Ft function type (>0 arguments)
354 Fo, Fc function block: funcname
355 Fn function name: [functype] funcname [[argtype] argname]
356 Fa function argument (>0 arguments)
357 Vt variable type (>0 arguments)
358 Va variable name (>0 arguments)
359 Dv defined variable or preprocessor constant (>0 arguments)
360 Er error constant (>0 arguments)
361 Ev environmental variable (>0 arguments)
362 Various semantic markup
364 An author name (>0 arguments)
365 Lk hyperlink: uri [name]
366 Mt “mailto” hyperlink: address
367 Cd kernel configuration declaration (>0 arguments)
368 Ad memory address (>0 arguments)
369 Ms mathematical symbol (>0 arguments)
370 Physical markup
372 Em italic font or underline (emphasis) (>0 arguments)
373 Sy boldface font (symbolic) (>0 arguments)
374 Li typewriter font (literal) (>0 arguments)
375 No return to roman font (normal) (no arguments)
376 Bf, Ef font block: [-type | Em | Li | Sy]
377 Physical enclosures
379 Dq, Do, Dc enclose in typographic double quotes: “text”
380 Qq, Qo, Qc enclose in typewriter double quotes: "text"
381 Sq, So, Sc enclose in single quotes: ‘text’
382 Pq, Po, Pc enclose in parentheses: (text)
383 Bq, Bo, Bc enclose in square brackets: [text]
384 Brq, Bro, Brc enclose in curly braces: {text}
385 Aq, Ao, Ac enclose in angle brackets: ⟨text⟩
386 Eo, Ec generic enclosure
387 Text production
389 Ex -std standard command exit values: [utility ...]
390 Rv -std standard function return values: [function ...]
391 St reference to a standards document (one argument)
392 At AT&T UNIX
393 Bx BSD
394 Bsx BSD/OS
395 Nx NetBSD
396 Fx FreeBSD
397 Ox OpenBSD
398 Dx DragonFly
399
401 This section is a canonical reference of all macros, arranged alphabeti‐
402 cally. For the scoping of individual macros, see MACRO SYNTAX.
403 %A
405 Author name of an Rs block. Multiple authors should each be accorded
406 their own %A line. Author names should be ordered with full or abbrevi‐
407 ated forename(s) first, then full surname.
408 %B
410 Book title of an Rs block. This macro may also be used in a non-biblio‐
411 graphic context when referring to book titles.
412 %C
414 Publication city or location of an Rs block.
415 %D
417 Publication date of an Rs block. Recommended formats of arguments are
418 month day, year or just year.
419 %I
421 Publisher or issuer name of an Rs block.
422 %J
424 Journal name of an Rs block.
425 %N
427 Issue number (usually for journals) of an Rs block.
428 %O
430 Optional information of an Rs block.
431 %P
433 Book or journal page number of an Rs block.
434 %Q
436 Institutional author (school, government, etc.) of an Rs block. Multiple
437 institutional authors should each be accorded their own %Q line.
438 %R
440 Technical report name of an Rs block.
441 %T
443 Article title of an Rs block. This macro may also be used in a non-bib‐
444 liographical context when referring to article titles.
445 %U
447 URI of reference document.
448 %V
450 Volume number of an Rs block.
451 Ac
453 Close an Ao block. Does not have any tail arguments.
454 Ad
456 Memory address. Do not use this for postal addresses.
457 Examples:
459 .Ad [0,$]
460 .Ad 0x00000000
461 An
463 Author name. Can be used both for the authors of the program, function,
464 or driver documented in the manual, or for the authors of the manual
465 itself. Requires either the name of an author or one of the following
466 arguments:
467 -split Start a new output line before each subsequent invoca‐
469 tion of An.
470 -nosplit The opposite of -split.
471 The default is -nosplit. The effect of selecting either of the -split
473 modes ends at the beginning of the AUTHORS section. In the AUTHORS sec‐
474 tion, the default is -nosplit for the first author listing and -split for
475 all other author listings.
476 Examples:
478 .An -nosplit
479 .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
480 Ao
482 Begin a block enclosed by angle brackets. Does not have any head argu‐
483 ments. This macro is almost never useful. See Aq for more details.
484 Ap
486 Inserts an apostrophe without any surrounding whitespace. This is gener‐
487 ally used as a grammatical device when referring to the verb form of a
488 function.
489 Examples:
491 .Fn execve Ap d
492 Aq
494 Encloses its arguments in angle brackets. The only important use case is
495 for email addresses. See Mt for an example.
496 Occasionally, it is used for names of characters and keys, for example:
498 Press the
500 .Aq escape
501 key to ...
502 For URIs, use Lk instead, and In for “#include” directives. Never wrap
504 Ar in Aq.
505 Since Aq usually renders with non-ASCII characters in non-ASCII output
507 modes, do not use it where the ASCII characters ‘<’ and ‘>’ are required
508 as syntax elements. Instead, use these characters directly in such
509 cases, combining them with the macros Pf, Ns, or Eo as needed.
510 See also Ao.
512 Ar
514 Command arguments. If an argument is not provided, the string “file ...”
515 is used as a default.
516 Examples:
518 .Fl o Ar file
519 .Ar
520 .Ar arg1 , arg2 .
521 The arguments to the Ar macro are names and placeholders for command
523 arguments; for fixed strings to be passed verbatim as arguments, use Fl
524 or Cm.
525 At
527 Formats an AT&T UNIX version. Accepts one optional argument:
528 v[1-7] | 32v A version of AT&T UNIX.
530 III AT&T UNIX III.
531 V | V.[1-4] A version of AT&T System V UNIX.
532 Note that these arguments do not begin with a hyphen.
534 Examples:
536 .At
537 .At III
538 .At V.1
539 See also Bsx, Bx, Dx, Fx, Nx, and Ox.
541 Bc
543 Close a Bo block. Does not have any tail arguments.
544 Bd
546 Begin a display block. Its syntax is as follows:
547 .Bd -type [-offset width] [-compact]
549 Display blocks are used to select a different indentation and justifica‐
551 tion than the one used by the surrounding text. They may contain both
552 macro lines and text lines. By default, a display block is preceded by a
553 vertical space.
554 The type must be one of the following:
556 -centered Produce one output line from each input line, and
558 center-justify each line. Using this display type
559 is not recommended; many mdoc implementations render
560 it poorly.
561 -filled Change the positions of line breaks to fill each
563 line, and left- and right-justify the resulting
564 block.
565 -literal Produce one output line from each input line, and do
567 not justify the block at all. Preserve white space
568 as it appears in the input. Always use a constant-
569 width font. Use this for displaying source code.
570 -ragged Change the positions of line breaks to fill each
572 line, and left-justify the resulting block.
573 -unfilled The same as -literal, but using the same font as for
575 normal text, which is a variable width font if sup‐
576 ported by the output device.
577 The type must be provided first. Additional arguments may follow:
579 -offset width Indent the display by the width, which may be one of
581 the following:
582 One of the pre-defined strings indent, the width of
584 a standard indentation (six constant width charac‐
585 ters); indent-two, twice indent; left, which has no
586 effect; right, which justifies to the right margin;
587 or center, which aligns around an imagined center
588 axis.
589 A macro invocation, which selects a predefined width
591 associated with that macro. The most popular is the
592 imaginary macro Ds, which resolves to 6n.
593 A scaling width as described in roff(7).
595 An arbitrary string, which indents by the length of
597 this string.
598 When the argument is missing, -offset is ignored.
600 -compact Do not assert vertical space before the display.
602 Examples:
604 .Bd -literal -offset indent -compact
606 Hello world.
607 .Ed
608 See also D1 and Dl.
610 Bf
612 Change the font mode for a scoped block of text. Its syntax is as fol‐
613 lows:
614 .Bf [-emphasis | -literal | -symbolic | Em | Li | Sy]
616 The -emphasis and Em argument are equivalent, as are -symbolic and Sy,
618 and -literal and Li. Without an argument, this macro does nothing. The
619 font mode continues until broken by a new font mode in a nested scope or
620 Ef is encountered.
621 See also Li, Ef, Em, and Sy.
623 Bk
625 For each macro, keep its output together on the same output line, until
626 the end of the macro or the end of the input line is reached, whichever
627 comes first. Line breaks in text lines are unaffected. The syntax is as
628 follows:
629 .Bk -words
631 The -words argument is required; additional arguments are ignored.
633 The following example will not break within each Op macro line:
635 .Bk -words
637 .Op Fl f Ar flags
638 .Op Fl o Ar output
639 .Ek
640 Be careful in using over-long lines within a keep block! Doing so will
642 clobber the right margin.
643 Bl
645 Begin a list. Lists consist of items specified using the It macro, con‐
646 taining a head or a body or both. The list syntax is as follows:
647 .Bl -type [-width val] [-offset val] [-compact] [HEAD ...]
649 The list type is mandatory and must be specified first. The -width and
651 -offset arguments accept macro names as described for Bd -offset, scaling
652 widths as described in roff(7), or use the length of the given string.
653 The -offset is a global indentation for the whole list, affecting both
654 item heads and bodies. For those list types supporting it, the -width
655 argument requests an additional indentation of item bodies, to be added
656 to the -offset. Unless the -compact argument is specified, list entries
657 are separated by vertical space.
658 A list must specify one of the following list types:
660 -bullet No item heads can be specified, but a bullet will be
662 printed at the head of each item. Item bodies start
663 on the same output line as the bullet and are
664 indented according to the -width argument.
665 -column A columnated list. The -width argument has no
667 effect; instead, the string length of each argument
668 specifies the width of one column. If the first line
669 of the body of a -column list is not an It macro
670 line, It contexts spanning one input line each are
671 implied until an It macro line is encountered, at
672 which point items start being interpreted as
673 described in the It documentation.
674 -dash Like -bullet, except that dashes are used in place of
676 bullets.
677 -diag Like -inset, except that item heads are not parsed
679 for macro invocations. Most often used in the
680 DIAGNOSTICS section with error constants in the item
681 heads.
682 -enum A numbered list. No item heads can be specified.
684 Formatted like -bullet, except that cardinal numbers
685 are used in place of bullets, starting at 1.
686 -hang Like -tag, except that the first lines of item bodies
688 are not indented, but follow the item heads like in
689 -inset lists.
690 -hyphen Synonym for -dash.
692 -inset Item bodies follow items heads on the same line,
694 using normal inter-word spacing. Bodies are not
695 indented, and the -width argument is ignored.
696 -item No item heads can be specified, and none are printed.
698 Bodies are not indented, and the -width argument is
699 ignored.
700 -ohang Item bodies start on the line following item heads
702 and are not indented. The -width argument is
703 ignored.
704 -tag Item bodies are indented according to the -width
706 argument. When an item head fits inside the indenta‐
707 tion, the item body follows this head on the same
708 output line. Otherwise, the body starts on the out‐
709 put line following the head.
710 Lists may be nested within lists and displays. Nesting of -column and
712 -enum lists may not be portable.
713 See also El and It.
715 Bo
717 Begin a block enclosed by square brackets. Does not have any head argu‐
718 ments.
719 Examples:
721 .Bo 1 ,
722 .Dv BUFSIZ Bc
723 See also Bq.
725 Bq
727 Encloses its arguments in square brackets.
728 Examples:
730 .Bq 1, Dv BUFSIZ
731 Remarks: this macro is sometimes abused to emulate optional arguments for
733 commands; the correct macros to use for this purpose are Op, Oo, and Oc.
734 See also Bo.
736 Brc
738 Close a Bro block. Does not have any tail arguments.
739 Bro
741 Begin a block enclosed by curly braces. Does not have any head argu‐
742 ments.
743 Examples:
745 .Bro 1 , ... ,
746 .Va n Brc
747 See also Brq.
749 Brq
751 Encloses its arguments in curly braces.
752 Examples:
754 .Brq 1, ..., Va n
755 See also Bro.
757 Bsx
759 Format the BSD/OS version provided as an argument, or a default value if
760 no argument is provided.
761 Examples:
763 .Bsx 1.0
764 .Bsx
765 See also At, Bx, Dx, Fx, Nx, and Ox.
767 Bt
769 Supported only for compatibility, do not use this in new manuals. Prints
770 “is currently in beta test.”
771 Bx
773 Format the BSD version provided as an argument, or a default value if no
774 argument is provided.
775 Examples:
777 .Bx 4.3 Tahoe
778 .Bx 4.4
779 .Bx
780 See also At, Bsx, Dx, Fx, Nx, and Ox.
782 Cd
784 Kernel configuration declaration. This denotes strings accepted by
785 config(8). It is most often used in section 4 manual pages.
786 Examples:
788 .Cd device le0 at scode?
789 Remarks: this macro is commonly abused by using quoted literals to retain
791 whitespace and align consecutive Cd declarations. This practise is dis‐
792 couraged.
793 Cm
795 Command modifiers. Typically used for fixed strings passed as arguments,
796 unless Fl is more appropriate. Also useful when specifying configuration
797 options or keys.
798 Examples:
800 .Nm mt Fl f Ar device Cm rewind
801 .Nm ps Fl o Cm pid , Ns Cm command
802 .Nm dd Cm if= Ns Ar file1 Cm of= Ns Ar file2
803 .Cm IdentityFile Pa ~/.ssh/id_rsa
804 .Cm LogLevel Dv DEBUG
805 D1
807 One-line indented display. This is formatted by the default rules and is
808 useful for simple indented statements. It is followed by a newline.
809 Examples:
811 .D1 Fl abcdefgh
812 See also Bd and Dl.
814 Db
816 This macro is obsolete. No replacement is needed. It is ignored by
817 mandoc(1) and groff including its arguments. It was formerly used to
818 toggle a debugging mode.
819 Dc
821 Close a Do block. Does not have any tail arguments.
822 Dd
824 Document date for display in the page footer. This is the mandatory
825 first macro of any mdoc manual. Its syntax is as follows:
826 .Dd month day, year
828 The month is the full English month name, the day is an integer number,
830 and the year is the full four-digit year.
831 Other arguments are not portable; the mandoc(1) utility handles them as
833 follows:
834 - To have the date automatically filled in by the OpenBSD version of
835 cvs(1), the special string “$Mdocdate$” can be given as an argu‐
836 ment.
837 - The traditional, purely numeric man(7) format year–month–day is
838 accepted, too.
839 - If a date string cannot be parsed, it is used verbatim.
840 - If no date string is given, the current date is used.
841 Examples:
843 .Dd $Mdocdate$
844 .Dd $Mdocdate: July 2 2018$
845 .Dd July 2, 2018
846 See also Dt and Os.
848 Dl
850 One-line indented display. This is formatted as literal text and is use‐
851 ful for commands and invocations. It is followed by a newline.
852 Examples:
854 .Dl % mandoc mdoc.7 \(ba less
855 See also Ql, Bd -literal, and D1.
857 Do
859 Begin a block enclosed by double quotes. Does not have any head argu‐
860 ments.
861 Examples:
863 .Do
864 April is the cruellest month
865 .Dc
866 \(em T.S. Eliot
867 See also Dq.
869 Dq
871 Encloses its arguments in “typographic” double-quotes.
872 Examples:
874 .Dq April is the cruellest month
875 \(em T.S. Eliot
876 See also Qq, Sq, and Do.
878 Dt
880 Document title for display in the page header. This is the mandatory
881 second macro of any mdoc file. Its syntax is as follows:
882 .Dt TITLE section [arch]
884 Its arguments are as follows:
886 TITLE The document's title (name), defaulting to “UNTITLED” if
888 unspecified. To achieve a uniform appearance of page header
889 lines, it should by convention be all caps.
890 section The manual section. This may be one of 1 (General Commands),
892 2 (System Calls), 3 (Library Functions), 3p (Perl Library), 4
893 (Device Drivers), 5 (File Formats), 6 (Games), 7
894 (Miscellaneous Information), 8 (System Manager's Manual), or 9
895 (Kernel Developer's Manual). It should correspond to the man‐
896 ual's filename suffix and defaults to the empty string if
897 unspecified.
898 arch This specifies the machine architecture a manual page applies
900 to, where relevant, for example alpha, amd64, i386, or
901 sparc64. The list of valid architectures varies by operating
902 system.
903 Examples:
905 .Dt FOO 1
906 .Dt FOO 9 i386
907 See also Dd and Os.
909 Dv
911 Defined variables such as preprocessor constants, constant symbols, enu‐
912 meration values, and so on.
913 Examples:
915 .Dv NULL
916 .Dv BUFSIZ
917 .Dv STDOUT_FILENO
918 See also Er and Ev for special-purpose constants, Va for variable sym‐
920 bols, and Fd for listing preprocessor variable definitions in the
921 SYNOPSIS.
922 Dx
924 Format the DragonFly version provided as an argument, or a default value
925 if no argument is provided.
926 Examples:
928 .Dx 2.4.1
929 .Dx
930 See also At, Bsx, Bx, Fx, Nx, and Ox.
932 Ec
934 Close a scope started by Eo. Its syntax is as follows:
935 .Ec [TERM]
937 The TERM argument is used as the enclosure tail, for example, specifying
939 \(rq will emulate Dc.
940 Ed
942 End a display context started by Bd.
943 Ef
945 End a font mode context started by Bf.
946 Ek
948 End a keep context started by Bk.
949 El
951 End a list context started by Bl.
952 See also Bl and It.
954 Em
956 Request an italic font. If the output device does not provide that,
957 underline.
958 This is most often used for stress emphasis (not to be confused with
960 importance, see Sy). In the rare cases where none of the semantic markup
961 macros fit, it can also be used for technical terms and placeholders,
962 except that for syntax elements, Sy and Ar are preferred, respectively.
963 Examples:
965 Selected lines are those
966 .Em not
967 matching any of the specified patterns.
968 Some of the functions use a
969 .Em hold space
970 to save the pattern space for subsequent retrieval.
971 See also Bf, Li, No, and Sy.
973 En
975 This macro is obsolete. Use Eo or any of the other enclosure macros.
976 It encloses its argument in the delimiters specified by the last Es
978 macro.
979 Eo
981 An arbitrary enclosure. Its syntax is as follows:
982 .Eo [TERM]
984 The TERM argument is used as the enclosure head, for example, specifying
986 \(lq will emulate Do.
987 Er
989 Error constants for definitions of the errno libc global variable. This
990 is most often used in section 2 and 3 manual pages.
991 Examples:
993 .Er EPERM
994 .Er ENOENT
995 See also Dv for general constants.
997 Es
999 This macro is obsolete. Use Eo or any of the other enclosure macros.
1000 It takes two arguments, defining the delimiters to be used by subsequent
1002 En macros.
1003 Ev
1005 Environmental variables such as those specified in environ(7).
1006 Examples:
1008 .Ev DISPLAY
1009 .Ev PATH
1010 See also Dv for general constants.
1012 Ex
1014 Insert a standard sentence regarding command exit values of 0 on success
1015 and >0 on failure. This is most often used in section 1, 6, and 8 manual
1016 pages. Its syntax is as follows:
1017 .Ex -std [utility ...]
1019 If utility is not specified, the document's name set by Nm is used. Mul‐
1021 tiple utility arguments are treated as separate utilities.
1022 See also Rv.
1024 Fa
1026 Function argument or parameter. Its syntax is as follows:
1027 .Fa "[argtype] [argname]" ...
1029 Each argument may be a name and a type (recommended for the SYNOPSIS sec‐
1031 tion), a name alone (for function invocations), or a type alone (for
1032 function prototypes). If both a type and a name are given or if the type
1033 consists of multiple words, all words belonging to the same function
1034 argument have to be given in a single argument to the Fa macro.
1035 This macro is also used to specify the field name of a structure.
1037 Most often, the Fa macro is used in the SYNOPSIS within Fo blocks when
1039 documenting multi-line function prototypes. If invoked with multiple
1040 arguments, the arguments are separated by a comma. Furthermore, if the
1041 following macro is another Fa, the last argument will also have a trail‐
1042 ing comma.
1043 Examples:
1045 .Fa "const char *p"
1046 .Fa "int a" "int b" "int c"
1047 .Fa "char *" size_t
1048 See also Fo.
1050 Fc
1052 End a function context started by Fo.
1053 Fd
1055 Preprocessor directive, in particular for listing it in the SYNOPSIS.
1056 Historically, it was also used to document include files. The latter
1057 usage has been deprecated in favour of In.
1058 Its syntax is as follows:
1060 .Fd #directive [argument ...]
1062 Examples:
1064 .Fd #define sa_handler __sigaction_u.__sa_handler
1065 .Fd #define SIO_MAXNFDS
1066 .Fd #ifdef FS_DEBUG
1067 .Ft void
1068 .Fn dbg_open "const char *"
1069 .Fd #endif
1070 See also MANUAL STRUCTURE, In, and Dv.
1072 Fl
1074 Command-line flag or option. Used when listing arguments to command-line
1075 utilities. Prints a fixed-width hyphen ‘-’ directly followed by each
1076 argument. If no arguments are provided, a hyphen is printed followed by
1077 a space. If the argument is a macro, a hyphen is prefixed to the subse‐
1078 quent macro output.
1079 Examples:
1081 .Fl R Op Fl H | L | P
1082 .Op Fl 1AaCcdFfgHhikLlmnopqRrSsTtux
1083 .Fl type Cm d Fl name Pa CVS
1084 .Fl Ar signal_number
1085 .Fl o Fl
1086 See also Cm.
1088 Fn
1090 A function name. Its syntax is as follows:
1091 .Fn [functype] funcname [[argtype] argname]
1093 Function arguments are surrounded in parenthesis and are delimited by
1095 commas. If no arguments are specified, blank parenthesis are output. In
1096 the SYNOPSIS section, this macro starts a new output line, and a blank
1097 line is automatically inserted between function definitions.
1098 Examples:
1100 .Fn "int funcname" "int arg0" "int arg1"
1101 .Fn funcname "int arg0"
1102 .Fn funcname arg0
1103 .Ft functype
1105 .Fn funcname
1106 When referring to a function documented in another manual page, use Xr
1108 instead. See also MANUAL STRUCTURE, Fo, and Ft.
1109 Fo
1111 Begin a function block. This is a multi-line version of Fn. Its syntax
1112 is as follows:
1113 .Fo funcname
1115 Invocations usually occur in the following context:
1117 .Ft functype
1119 .Fo funcname
1120 .Fa "argtype argname"
1121 ...
1122 .Fc
1123 A Fo scope is closed by Fc.
1125 See also MANUAL STRUCTURE, Fa, Fc, and Ft.
1127 Fr
1129 This macro is obsolete. No replacement markup is needed.
1130 It was used to show numerical function return values in an italic font.
1132 Ft
1134 A function type. Its syntax is as follows:
1135 .Ft functype
1137 In the SYNOPSIS section, a new output line is started after this macro.
1139 Examples:
1141 .Ft int
1142 .Ft functype
1143 .Fn funcname
1144 See also MANUAL STRUCTURE, Fn, and Fo.
1146 Fx
1148 Format the FreeBSD version provided as an argument, or a default value if
1149 no argument is provided.
1150 Examples:
1152 .Fx 7.1
1153 .Fx
1154 See also At, Bsx, Bx, Dx, Nx, and Ox.
1156 Hf
1158 This macro is not implemented in mandoc(1).
1159 It was used to include the contents of a (header) file literally. The
1161 syntax was:
1162 .Hf filename
1164 Ic
1166 Designate an internal or interactive command. This is similar to Cm but
1167 used for instructions rather than values.
1168 Examples:
1170 .Ic :wq
1171 .Ic hash
1172 .Ic alias
1173 Note that using Bd -literal or D1 is preferred for displaying code; the
1175 Ic macro is used when referring to specific instructions.
1176 In
1178 The name of an include file. This macro is most often used in section 2,
1179 3, and 9 manual pages.
1180 When invoked as the first macro on an input line in the SYNOPSIS section,
1182 the argument is displayed in angle brackets and preceded by "#include",
1183 and a blank line is inserted in front if there is a preceding function
1184 declaration. In other sections, it only encloses its argument in angle
1185 brackets and causes no line break.
1186 Examples:
1188 .In sys/types.h
1189 See also MANUAL STRUCTURE.
1191 It
1193 A list item. The syntax of this macro depends on the list type.
1194 Lists of type -hang, -ohang, -inset, and -diag have the following syntax:
1196 .It args
1198 Lists of type -bullet, -dash, -enum, -hyphen and -item have the following
1200 syntax:
1201 .It
1203 with subsequent lines interpreted within the scope of the It until either
1205 a closing El or another It.
1206 The -tag list has the following syntax:
1208 .It [args]
1210 Subsequent lines are interpreted as with -bullet and family. The line
1212 arguments correspond to the list's left-hand side; body arguments corre‐
1213 spond to the list's contents.
1214 The -column list is the most complicated. Its syntax is as follows:
1216 .It cell [Ta cell ...]
1218 .It cell [<TAB> cell ...]
1219 The arguments consist of one or more lines of text and macros represent‐
1221 ing a complete table line. Cells within the line are delimited by the
1222 special Ta block macro or by literal tab characters.
1223 Using literal tabs is strongly discouraged because they are very hard to
1225 use correctly and mdoc code using them is very hard to read. In particu‐
1226 lar, a blank character is syntactically significant before and after the
1227 literal tab character. If a word precedes or follows the tab without an
1228 intervening blank, that word is never interpreted as a macro call, but
1229 always output literally.
1230 The tab cell delimiter may only be used within the It line itself; on
1232 following lines, only the Ta macro can be used to delimit cells, and
1233 portability requires that Ta is called by other macros: some parsers do
1234 not recognize it when it appears as the first macro on a line.
1235 Note that quoted strings may span tab-delimited cells on an It line. For
1237 example,
1238 .It "col1 , <TAB> col2 ," ;
1240 will preserve the whitespace before both commas, but not the whitespace
1242 before the semicolon.
1243 See also Bl.
1245 Lb
1247 Specify a library. The syntax is as follows:
1248 .Lb library
1250 The library parameter may be a system library, such as libz or libpam, in
1252 which case a small library description is printed next to the linker
1253 invocation; or a custom library, in which case the library name is
1254 printed in quotes. This is most commonly used in the SYNOPSIS section as
1255 described in MANUAL STRUCTURE.
1256 Examples:
1258 .Lb libz
1259 .Lb libmandoc
1260 Li
1262 Denotes text that should be in a literal font mode. Note that this is a
1263 presentation term and should not be used for stylistically decorating
1264 technical terms.
1265 On terminal output devices, this is often indistinguishable from normal
1267 text.
1268 See also Bf, Em, No, and Sy.
1270 Lk
1272 Format a hyperlink. Its syntax is as follows:
1273 .Lk uri [name]
1275 Examples:
1277 .Lk http://bsd.lv "The BSD.lv Project"
1278 .Lk http://bsd.lv
1279 See also Mt.
1281 Lp
1283 Synonym for Pp.
1284 Ms
1286 Display a mathematical symbol. Its syntax is as follows:
1287 .Ms symbol
1289 Examples:
1291 .Ms sigma
1292 .Ms aleph
1293 Mt
1295 Format a “mailto:” hyperlink. Its syntax is as follows:
1296 .Mt address
1298 Examples:
1300 .Mt discuss@manpages.bsd.lv
1301 .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
1302 Nd
1304 A one line description of the manual's content. This is the mandatory
1305 last macro of the NAME section and not appropriate for other sections.
1306 Examples:
1308 .Nd mdoc language reference
1309 .Nd format and display UNIX manuals
1310 The Nd macro technically accepts child macros and terminates with a sub‐
1312 sequent Sh invocation. Do not assume this behaviour: some whatis(1)
1313 database generators are not smart enough to parse more than the line
1314 arguments and will display macros verbatim.
1315 See also Nm.
1317 Nm
1319 The name of the manual page, or — in particular in section 1, 6, and 8
1320 pages — of an additional command or feature documented in the manual
1321 page. When first invoked, the Nm macro expects a single argument, the
1322 name of the manual page. Usually, the first invocation happens in the
1323 NAME section of the page. The specified name will be remembered and used
1324 whenever the macro is called again without arguments later in the page.
1325 The Nm macro uses Block full-implicit semantics when invoked as the first
1326 macro on an input line in the SYNOPSIS section; otherwise, it uses ordi‐
1327 nary In-line semantics.
1328 Examples:
1330 .Sh SYNOPSIS
1332 .Nm cat
1333 .Op Fl benstuv
1334 .Op Ar
1335 In the SYNOPSIS of section 2, 3 and 9 manual pages, use the Fn macro
1337 rather than Nm to mark up the name of the manual page.
1338 No
1340 Normal text. Closes the scope of any preceding in-line macro. When used
1341 after physical formatting macros like Em or Sy, switches back to the
1342 standard font face and weight. Can also be used to embed plain text
1343 strings in macro lines using semantic annotation macros.
1344 Examples:
1346 .Em italic , Sy bold , No and roman
1347 .Sm off
1349 .Cm :C No / Ar pattern No / Ar replacement No /
1350 .Sm on
1351 See also Em, Li, and Sy.
1353 Ns
1355 Suppress a space between the output of the preceding macro and the fol‐
1356 lowing text or macro. Following invocation, input is interpreted as nor‐
1357 mal text just like after an No macro.
1358 This has no effect when invoked at the start of a macro line.
1360 Examples:
1362 .Ar name Ns = Ns Ar value
1363 .Cm :M Ns Ar pattern
1364 .Fl o Ns Ar output
1365 See also No and Sm.
1367 Nx
1369 Format the NetBSD version provided as an argument, or a default value if
1370 no argument is provided.
1371 Examples:
1373 .Nx 5.01
1374 .Nx
1375 See also At, Bsx, Bx, Dx, Fx, and Ox.
1377 Oc
1379 Close multi-line Oo context.
1380 Oo
1382 Multi-line version of Op.
1383 Examples:
1385 .Oo
1386 .Op Fl flag Ns Ar value
1387 .Oc
1388 Op
1390 Optional part of a command line. Prints the argument(s) in brackets.
1391 This is most often used in the SYNOPSIS section of section 1 and 8 manual
1392 pages.
1393 Examples:
1395 .Op Fl a Ar b
1396 .Op Ar a | b
1397 See also Oo.
1399 Os
1401 Operating system version for display in the page footer. This is the
1402 mandatory third macro of any mdoc file. Its syntax is as follows:
1403 .Os [system [version]]
1405 The optional system parameter specifies the relevant operating system or
1407 environment. It is suggested to leave it unspecified, in which case
1408 mandoc(1) uses its -Ios argument or, if that isn't specified either,
1409 sysname and release as returned by uname(3).
1410 Examples:
1412 .Os
1413 .Os KTH/CSC/TCS
1414 .Os BSD 4.3
1415 See also Dd and Dt.
1417 Ot
1419 This macro is obsolete. Use Ft instead; with mandoc(1), both have the
1420 same effect.
1421 Historical mdoc packages described it as “old function type (FORTRAN)”.
1423 Ox
1425 Format the OpenBSD version provided as an argument, or a default value if
1426 no argument is provided.
1427 Examples:
1429 .Ox 4.5
1430 .Ox
1431 See also At, Bsx, Bx, Dx, Fx, and Nx.
1433 Pa
1435 An absolute or relative file system path, or a file or directory name.
1436 If an argument is not provided, the character ‘~’ is used as a default.
1437 Examples:
1439 .Pa /usr/bin/mandoc
1440 .Pa /usr/share/man/man7/mdoc.7
1441 See also Lk.
1443 Pc
1445 Close parenthesised context opened by Po.
1446 Pf
1448 Removes the space between its argument and the following macro. Its syn‐
1449 tax is as follows:
1450 .Pf prefix macro arguments ...
1452 This is equivalent to:
1454 .No \&prefix Ns macro arguments ...
1456 The prefix argument is not parsed for macro names or delimiters, but used
1458 verbatim as if it were escaped.
1459 Examples:
1461 .Pf $ Ar variable_name
1462 .Pf . Ar macro_name
1463 .Pf 0x Ar hex_digits
1464 See also Ns and Sm.
1466 Po
1468 Multi-line version of Pq.
1469 Pp
1471 Break a paragraph. This will assert vertical space between prior and
1472 subsequent macros and/or text.
1473 Paragraph breaks are not needed before or after Sh or Ss macros or before
1475 displays (Bd) or lists (Bl) unless the -compact flag is given.
1476 Pq
1478 Parenthesised enclosure.
1479 See also Po.
1481 Qc
1483 Close quoted context opened by Qo.
1484 Ql
1486 In-line literal display. This can for example be used for complete com‐
1487 mand invocations and for multi-word code fragments when more specific
1488 markup is not appropriate and an indented display is not desired. While
1489 mandoc(1) always encloses the arguments in single quotes, other format‐
1490 ters usually omit the quotes on non-terminal output devices when the
1491 arguments have three or more characters.
1492 See also Dl and Bd -literal.
1494 Qo
1496 Multi-line version of Qq.
1497 Qq
1499 Encloses its arguments in "typewriter" double-quotes. Consider using Dq.
1500 See also Dq, Sq, and Qo.
1502 Re
1504 Close an Rs block. Does not have any tail arguments.
1505 Rs
1507 Begin a bibliographic (“reference”) block. Does not have any head argu‐
1508 ments. The block macro may only contain %A, %B, %C, %D, %I, %J, %N, %O,
1509 %P, %Q, %R, %T, %U, and %V child macros (at least one must be specified).
1510 Examples:
1512 .Rs
1513 .%A J. E. Hopcroft
1514 .%A J. D. Ullman
1515 .%B Introduction to Automata Theory, Languages, and Computation
1516 .%I Addison-Wesley
1517 .%C Reading, Massachusetts
1518 .%D 1979
1519 .Re
1520 If an Rs block is used within a SEE ALSO section, a vertical space is
1522 asserted before the rendered output, else the block continues on the cur‐
1523 rent line.
1524 Rv
1526 Insert a standard sentence regarding a function call's return value of 0
1527 on success and -1 on error, with the errno libc global variable set on
1528 error. Its syntax is as follows:
1529 .Rv -std [function ...]
1531 If function is not specified, the document's name set by Nm is used.
1533 Multiple function arguments are treated as separate functions.
1534 See also Ex.
1536 Sc
1538 Close single-quoted context opened by So.
1539 Sh
1541 Begin a new section. For a list of conventional manual sections, see
1542 MANUAL STRUCTURE. These sections should be used unless it's absolutely
1543 necessary that custom sections be used.
1544 Section names should be unique so that they may be keyed by Sx. Although
1546 this macro is parsed, it should not consist of child node or it may not
1547 be linked with Sx.
1548 See also Pp, Ss, and Sx.
1550 Sm
1552 Switches the spacing mode for output generated from macros. Its syntax
1553 is as follows:
1554 .Sm [on | off]
1556 By default, spacing is on. When switched off, no white space is inserted
1558 between macro arguments and between the output generated from adjacent
1559 macros, but text lines still get normal spacing between words and sen‐
1560 tences.
1561 When called without an argument, the Sm macro toggles the spacing mode.
1563 Using this is not recommended because it makes the code harder to read.
1564 So
1566 Multi-line version of Sq.
1567 Sq
1569 Encloses its arguments in ‘typewriter’ single-quotes.
1570 See also Dq, Qq, and So.
1572 Ss
1574 Begin a new subsection. Unlike with Sh, there is no convention for the
1575 naming of subsections. Except DESCRIPTION, the conventional sections
1576 described in MANUAL STRUCTURE rarely have subsections.
1577 Sub-section names should be unique so that they may be keyed by Sx.
1579 Although this macro is parsed, it should not consist of child node or it
1580 may not be linked with Sx.
1581 See also Pp, Sh, and Sx.
1583 St
1585 Replace an abbreviation for a standard with the full form. The following
1586 standards are recognised. Where multiple lines are given without a blank
1587 line in between, they all refer to the same standard, and using the first
1588 form is recommended.
1589 C language standards
1591 -ansiC ANSI X3.159-1989 (“ANSI C89”)
1593 -ansiC-89 ANSI X3.159-1989 (“ANSI C89”)
1594 -isoC ISO/IEC 9899:1990 (“ISO C90”)
1595 -isoC-90 ISO/IEC 9899:1990 (“ISO C90”)
1596 The original C standard.
1597 -isoC-amd1 ISO/IEC 9899/AMD1:1995 (“ISO C90, Amendment 1”)
1599 -isoC-tcor1 ISO/IEC 9899/TCOR1:1994 (“ISO C90, Technical
1601 Corrigendum 1”)
1602 -isoC-tcor2 ISO/IEC 9899/TCOR2:1995 (“ISO C90, Technical
1604 Corrigendum 2”)
1605 -isoC-99 ISO/IEC 9899:1999 (“ISO C99”)
1607 The second major version of the C language standard.
1608 -isoC-2011 ISO/IEC 9899:2011 (“ISO C11”)
1610 The third major version of the C language standard.
1611 POSIX.1 before the Single UNIX Specification
1613 -p1003.1-88 IEEE Std 1003.1-1988 (“POSIX.1”)
1615 -p1003.1 IEEE Std 1003.1 (“POSIX.1”)
1616 The original POSIX standard, based on ANSI C.
1617 -p1003.1-90 ISO/IEC 9945-1:1990 (“POSIX.1”)
1619 -iso9945-1-90 ISO/IEC 9945-1:1990 (“POSIX.1”)
1620 The first update of POSIX.1.
1621 -p1003.1b-93 IEEE Std 1003.1b-1993 (“POSIX.1”)
1623 -p1003.1b IEEE Std 1003.1b (“POSIX.1”)
1624 Real-time extensions.
1625 -p1003.1c-95 IEEE Std 1003.1c-1995 (“POSIX.1”)
1627 POSIX thread interfaces.
1628 -p1003.1i-95 IEEE Std 1003.1i-1995 (“POSIX.1”)
1630 Technical Corrigendum.
1631 -p1003.1-96 ISO/IEC 9945-1:1996 (“POSIX.1”)
1633 -iso9945-1-96 ISO/IEC 9945-1:1996 (“POSIX.1”)
1634 Includes POSIX.1-1990, 1b, 1c, and 1i.
1635 X/Open Portability Guide version 4 and related standards
1637 -xpg3 X/Open Portability Guide Issue 3 (“XPG3”)
1639 An XPG4 precursor, published in 1989.
1640 -p1003.2 IEEE Std 1003.2 (“POSIX.2”)
1642 -p1003.2-92 IEEE Std 1003.2-1992 (“POSIX.2”)
1643 -iso9945-2-93 ISO/IEC 9945-2:1993 (“POSIX.2”)
1644 An XCU4 precursor.
1645 -p1003.2a-92 IEEE Std 1003.2a-1992 (“POSIX.2”)
1647 Updates to POSIX.2.
1648 -xpg4 X/Open Portability Guide Issue 4 (“XPG4”)
1650 Based on POSIX.1 and POSIX.2, published in 1992.
1651 Single UNIX Specification version 1 and related standards
1653 -susv1
1655 -xpg4.2 X/Open Portability Guide Issue 4, Version 2 (“XPG4.2”)
1656 This standard was published in 1994. It was used as
1657 the basis for UNIX 95 certification. The following
1658 three refer to parts of it.
1659 -xsh4.2
1661 -xcurses4.2 X/Open Curses Issue 4, Version 2 (“XCURSES4.2”)
1663 -p1003.1g-2000 IEEE Std 1003.1g-2000 (“POSIX.1”)
1665 Networking APIs, including sockets.
1666 -svid4 System V Interface Definition, Fourth Edition
1668 (“SVID4”),
1669 Published in 1995.
1670 Single UNIX Specification version 2 and related standards
1672 -susv2 Version 2 of the Single UNIX Specification (“SUSv2”)
1674 This Standard was published in 1997 and is also called
1675 X/Open Portability Guide version 5. It was used as
1676 the basis for UNIX 98 certification. The following
1677 refer to parts of it.
1678 -xbd5 X/Open Base Definitions Issue 5 (“XBD5”)
1680 -xsh5 X/Open System Interfaces and Headers Issue 5 (“XSH5”)
1682 -xcu5 X/Open Commands and Utilities Issue 5 (“XCU5”)
1684 -xns5 X/Open Networking Services Issue 5 (“XNS5”)
1686 -xns5.2 X/Open Networking Services Issue 5.2 (“XNS5.2”)
1687 Single UNIX Specification version 3
1689 -p1003.1-2001 IEEE Std 1003.1-2001 (“POSIX.1”)
1691 -susv3 Version 3 of the Single UNIX Specification (“SUSv3”)
1692 This standard is based on C99, SUSv2, POSIX.1-1996, 1d,
1693 and 1j. It is also called X/Open Portability Guide
1694 version 6. It is used as the basis for UNIX 03 certi‐
1695 fication.
1696 -p1003.1-2004 IEEE Std 1003.1-2004 (“POSIX.1”)
1698 The second and last Technical Corrigendum.
1699 Single UNIX Specification version 4
1701 -p1003.1-2008 IEEE Std 1003.1-2008 (“POSIX.1”)
1703 -susv4
1704 This standard is also called X/Open Portability Guide
1705 version 7.
1706 Other standards
1708 -ieee754 IEEE Std 754-1985
1710 Floating-point arithmetic.
1711 -iso8601
1713 Representation of dates and times, published in 1988.
1714 -iso8802-3 ISO/IEC 8802-3:1989
1716 Ethernet local area networks.
1717 -ieee1275-94 IEEE Std 1275-1994 (“Open Firmware”)
1719 Sx
1721 Reference a section or subsection in the same manual page. The refer‐
1722 enced section or subsection name must be identical to the enclosed argu‐
1723 ment, including whitespace.
1724 Examples:
1726 .Sx MANUAL STRUCTURE
1727 See also Sh and Ss.
1729 Sy
1731 Request a boldface font.
1732 This is most often used to indicate importance or seriousness (not to be
1734 confused with stress emphasis, see Em). When none of the semantic macros
1735 fit, it is also adequate for syntax elements that have to be given or
1736 that appear verbatim.
1737 Examples:
1739 .Sy Warning :
1740 If
1741 .Sy s
1742 appears in the owner permissions, set-user-ID mode is set.
1743 This utility replaces the former
1744 .Sy dumpdir
1745 program.
1746 See also Bf, Em, Li, and No.
1748 Ta
1750 Table cell separator in Bl -column lists; can only be used below It.
1751 Tn
1753 Supported only for compatibility, do not use this in new manuals. Even
1754 though the macro name (“tradename”) suggests a semantic function, his‐
1755 toric usage is inconsistent, mostly using it as a presentation-level
1756 macro to request a small caps font.
1757 Ud
1759 Supported only for compatibility, do not use this in new manuals. Prints
1760 out “currently under development.”
1761 Ux
1763 Supported only for compatibility, do not use this in new manuals. Prints
1764 out “UNIX”.
1765 Va
1767 A variable name.
1768 Examples:
1770 .Va foo
1771 .Va const char *bar;
1772 For function arguments and parameters, use Fa instead. For declarations
1774 of global variables in the SYNOPSIS section, use Vt.
1775 Vt
1777 A variable type.
1778 This is also used for indicating global variables in the SYNOPSIS sec‐
1780 tion, in which case a variable name is also specified. Note that it
1781 accepts Block partial-implicit syntax when invoked as the first macro on
1782 an input line in the SYNOPSIS section, else it accepts ordinary In-line
1783 syntax. In the former case, this macro starts a new output line, and a
1784 blank line is inserted in front if there is a preceding function defini‐
1785 tion or include directive.
1786 Examples:
1788 .Vt unsigned char
1789 .Vt extern const char * const sys_signame[] ;
1790 For parameters in function prototypes, use Fa instead, for function
1792 return types Ft, and for variable names outside the SYNOPSIS section Va,
1793 even when including a type with the name. See also MANUAL STRUCTURE.
1794 Xc
1796 Close a scope opened by Xo.
1797 Xo
1799 Extend the header of an It macro or the body of a partial-implicit block
1800 macro beyond the end of the input line. This macro originally existed to
1801 work around the 9-argument limit of historic roff(7).
1802 Xr
1804 Link to another manual ("cross-reference"). Its syntax is as follows:
1805 .Xr name section
1807 Cross reference the name and section number of another man page.
1809 Examples:
1811 .Xr mandoc 1
1812 .Xr mandoc 1 ;
1813 .Xr mandoc 1 Ns s behaviour
1814
1816 The syntax of a macro depends on its classification. In this section,
1817 ‘-arg’ refers to macro arguments, which may be followed by zero or more
1818 ‘parm’ parameters; ‘Yo’ opens the scope of a macro; and if specified,
1819 ‘Yc’ closes it out.
1820 The Callable column indicates that the macro may also be called by pass‐
1822 ing its name as an argument to another macro. For example, ‘.Op Fl O Ar
1823 file’ produces ‘[-O file]’. To prevent a macro call and render the macro
1824 name literally, escape it by prepending a zero-width space, ‘\&’. For
1825 example, ‘Op \&Fl O’ produces ‘[Fl O]’. If a macro is not callable but
1826 its name appears as an argument to another macro, it is interpreted as
1827 opaque text. For example, ‘.Fl Sh’ produces ‘-Sh’.
1828 The Parsed column indicates whether the macro may call other macros by
1830 receiving their names as arguments. If a macro is not parsed but the
1831 name of another macro appears as an argument, it is interpreted as opaque
1832 text.
1833 The Scope column, if applicable, describes closure rules.
1835 Block full-explicit
1837 Multi-line scope closed by an explicit closing macro. All macros con‐
1838 tains bodies; only Bf and (optionally) Bl contain a head.
1839 .Yo [-arg [parm...]] [head...]
1841 [body...]
1842 .Yc
1843 Macro Callable Parsed Scope
1845 Bd No No closed by Ed
1846 Bf No No closed by Ef
1847 Bk No No closed by Ek
1848 Bl No No closed by El
1849 Ed No No opened by Bd
1850 Ef No No opened by Bf
1851 Ek No No opened by Bk
1852 El No No opened by Bl
1853 Block full-implicit
1855 Multi-line scope closed by end-of-file or implicitly by another macro.
1856 All macros have bodies; some (It -bullet, -hyphen, -dash, -enum, -item)
1857 don't have heads; only one (It in Bl -column) has multiple heads.
1858 .Yo [-arg [parm...]] [head... [Ta head...]]
1860 [body...]
1861 Macro Callable Parsed Scope
1863 It No Yes closed by It, El
1864 Nd No No closed by Sh
1865 Nm No Yes closed by Nm, Sh, Ss
1866 Sh No Yes closed by Sh
1867 Ss No Yes closed by Sh, Ss
1868 Note that the Nm macro is a Block full-implicit macro only when invoked
1870 as the first macro in a SYNOPSIS section line, else it is In-line.
1871 Block partial-explicit
1873 Like block full-explicit, but also with single-line scope. Each has at
1874 least a body and, in limited circumstances, a head (Fo, Eo) and/or tail
1875 (Ec).
1876 .Yo [-arg [parm...]] [head...]
1878 [body...]
1879 .Yc [tail...]
1880 .Yo [-arg [parm...]] [head...] [body...] Yc [tail...]
1882 Macro Callable Parsed Scope
1884 Ac Yes Yes opened by Ao
1885 Ao Yes Yes closed by Ac
1886 Bc Yes Yes closed by Bo
1887 Bo Yes Yes opened by Bc
1888 Brc Yes Yes opened by Bro
1889 Bro Yes Yes closed by Brc
1890 Dc Yes Yes opened by Do
1891 Do Yes Yes closed by Dc
1892 Ec Yes Yes opened by Eo
1893 Eo Yes Yes closed by Ec
1894 Fc Yes Yes opened by Fo
1895 Fo No No closed by Fc
1896 Oc Yes Yes closed by Oo
1897 Oo Yes Yes opened by Oc
1898 Pc Yes Yes closed by Po
1899 Po Yes Yes opened by Pc
1900 Qc Yes Yes opened by Oo
1901 Qo Yes Yes closed by Oc
1902 Re No No opened by Rs
1903 Rs No No closed by Re
1904 Sc Yes Yes opened by So
1905 So Yes Yes closed by Sc
1906 Xc Yes Yes opened by Xo
1907 Xo Yes Yes closed by Xc
1908 Block partial-implicit
1910 Like block full-implicit, but with single-line scope closed by the end of
1911 the line.
1912 .Yo [-arg [val...]] [body...] [res...]
1914 Macro Callable Parsed
1916 Aq Yes Yes
1917 Bq Yes Yes
1918 Brq Yes Yes
1919 D1 No Yes
1920 Dl No Yes
1921 Dq Yes Yes
1922 En Yes Yes
1923 Op Yes Yes
1924 Pq Yes Yes
1925 Ql Yes Yes
1926 Qq Yes Yes
1927 Sq Yes Yes
1928 Vt Yes Yes
1929 Note that the Vt macro is a Block partial-implicit only when invoked as
1931 the first macro in a SYNOPSIS section line, else it is In-line.
1932 Special block macro
1934 The Ta macro can only be used below It in Bl -column lists. It delimits
1935 blocks representing table cells; these blocks have bodies, but no heads.
1936 Macro Callable Parsed Scope
1938 Ta Yes Yes closed by Ta, It
1939 In-line
1941 Closed by the end of the line, fixed argument lengths, and/or subsequent
1942 macros. In-line macros have only text children. If a number (or
1943 inequality) of arguments is (n), then the macro accepts an arbitrary num‐
1944 ber of arguments.
1945 .Yo [-arg [val...]] [args...] [res...]
1947 .Yo [-arg [val...]] [args...] Yc...
1949 .Yo [-arg [val...]] arg0 arg1 argN
1951 Macro Callable Parsed Arguments
1953 %A No No >0
1954 %B No No >0
1955 %C No No >0
1956 %D No No >0
1957 %I No No >0
1958 %J No No >0
1959 %N No No >0
1960 %O No No >0
1961 %P No No >0
1962 %Q No No >0
1963 %R No No >0
1964 %T No No >0
1965 %U No No >0
1966 %V No No >0
1967 Ad Yes Yes >0
1968 An Yes Yes >0
1969 Ap Yes Yes 0
1970 Ar Yes Yes n
1971 At Yes Yes 1
1972 Bsx Yes Yes n
1973 Bt No No 0
1974 Bx Yes Yes n
1975 Cd Yes Yes >0
1976 Cm Yes Yes >0
1977 Db No No 1
1978 Dd No No n
1979 Dt No No n
1980 Dv Yes Yes >0
1981 Dx Yes Yes n
1982 Em Yes Yes >0
1983 Er Yes Yes >0
1984 Es Yes Yes 2
1985 Ev Yes Yes >0
1986 Ex No No n
1987 Fa Yes Yes >0
1988 Fd No No >0
1989 Fl Yes Yes n
1990 Fn Yes Yes >0
1991 Fr Yes Yes >0
1992 Ft Yes Yes >0
1993 Fx Yes Yes n
1994 Hf No No n
1995 Ic Yes Yes >0
1996 In No No 1
1997 Lb No No 1
1998 Li Yes Yes >0
1999 Lk Yes Yes >0
2000 Lp No No 0
2001 Ms Yes Yes >0
2002 Mt Yes Yes >0
2003 Nm Yes Yes n
2004 No Yes Yes 0
2005 Ns Yes Yes 0
2006 Nx Yes Yes n
2007 Os No No n
2008 Ot Yes Yes >0
2009 Ox Yes Yes n
2010 Pa Yes Yes n
2011 Pf Yes Yes 1
2012 Pp No No 0
2013 Rv No No n
2014 Sm No No <2
2015 St No Yes 1
2016 Sx Yes Yes >0
2017 Sy Yes Yes >0
2018 Tn Yes Yes >0
2019 Ud No No 0
2020 Ux Yes Yes n
2021 Va Yes Yes n
2022 Vt Yes Yes >0
2023 Xr Yes Yes 2
2024 Delimiters
2026 When a macro argument consists of one single input character considered
2027 as a delimiter, the argument gets special handling. This does not apply
2028 when delimiters appear in arguments containing more than one character.
2029 Consequently, to prevent special handling and just handle it like any
2030 other argument, a delimiter can be escaped by prepending a zero-width
2031 space (‘\&’). In text lines, delimiters never need escaping, but may be
2032 used as normal punctuation.
2033 For many macros, when the leading arguments are opening delimiters, these
2035 delimiters are put before the macro scope, and when the trailing argu‐
2036 ments are closing delimiters, these delimiters are put after the macro
2037 scope. Spacing is suppressed after opening delimiters and before closing
2038 delimiters. For example,
2039 .Aq ( [ word ] ) .
2041 renders as:
2043 ([⟨word⟩]).
2045 Opening delimiters are:
2047 ( left parenthesis
2049 [ left bracket
2050 Closing delimiters are:
2052 . period
2054 , comma
2055 : colon
2056 ; semicolon
2057 ) right parenthesis
2058 ] right bracket
2059 ? question mark
2060 ! exclamation mark
2061 Note that even a period preceded by a backslash (‘\.’) gets this special
2063 handling; use ‘\&.’ to prevent that.
2064 Many in-line macros interrupt their scope when they encounter delimiters,
2066 and resume their scope when more arguments follow that are not delim‐
2067 iters. For example,
2068 .Fl a ( b | c \*(Ba d ) e
2070 renders as:
2072 -a (-b | -c | -d) -e
2074 This applies to both opening and closing delimiters, and also to the mid‐
2076 dle delimiter, which does not suppress spacing:
2077 | vertical bar
2079 As a special case, the predefined string \*(Ba is handled and rendered in
2081 the same way as a plain ‘|’ character. Using this predefined string is
2082 not recommended in new manuals.
2083 Font handling
2085 In mdoc documents, usage of semantic markup is recommended in order to
2086 have proper fonts automatically selected; only when no fitting semantic
2087 markup is available, consider falling back to Physical markup macros.
2088 Whenever any mdoc macro switches the roff(7) font mode, it will automati‐
2089 cally restore the previous font when exiting its scope. Manually switch‐
2090 ing the font using the roff(7) ‘\f’ font escape sequences is never
2091 required.
2092
2094 This section provides an incomplete list of compatibility issues between
2095 mandoc and GNU troff ("groff").
2096 The following problematic behaviour is found in groff:
2098 - Dd with non-standard arguments behaves very strangely. When there
2100 are three arguments, they are printed verbatim. Any other number of
2101 arguments is replaced by the current date, but without any arguments
2102 the string “Epoch” is printed.
2103 - Lk only accepts a single link-name argument; the remainder is misfor‐
2104 matted.
2105 - Pa does not format its arguments when used in the FILES section under
2106 certain list types.
2107 - Ta can only be called by other macros, but not at the beginning of a
2108 line.
2109 - %C is not implemented (up to and including groff-1.22.2).
2110 - ‘\f’ (font face) and ‘\F’ (font family face) Text Decoration escapes
2111 behave irregularly when specified within line-macro scopes.
2112 - Negative scaling units return to prior lines. Instead, mandoc trun‐
2113 cates them to zero.
2114 The following features are unimplemented in mandoc:
2116 - Bd -file file is unsupported for security reasons.
2118 - Bd -filled does not adjust the right margin, but is an alias for Bd
2119 -ragged.
2120 - Bd -literal does not use a literal font, but is an alias for Bd
2121 -unfilled.
2122 - Bd -offset center and -offset right don't work. Groff does not
2123 implement centered and flush-right rendering either, but produces
2124 large indentations.
2125
2127 man(1), mandoc(1), eqn(7), man(7), mandoc_char(7), roff(7), tbl(7)
2128 The web page extended documentation for the mdoc language:
2130 http://mandoc.bsd.lv/mdoc/
2131 provides a few tutorial-style pages for beginners, an extensive style
2132 guide for advanced authors, and an alphabetic index helping to choose the
2133 best macros for various kinds of content.
2134
2136 The mdoc language first appeared as a troff macro package in 4.4BSD. It
2137 was later significantly updated by Werner Lemberg and Ruslan Ermilov in
2138 groff-1.17. The standalone implementation that is part of the mandoc(1)
2139 utility written by Kristaps Dzonsons appeared in OpenBSD 4.6.
2140
2142 The mdoc reference was written by Kristaps Dzonsons <kristaps@bsd.lv>.
2143BSD June 20, 2019 BSD