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 de‐
16 scribes 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 de‐
27 pends 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 ap‐
99 pear 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 options 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 Tg tag the definition of a term (<= 1 arguments)
321 Pp start a text paragraph (no arguments)
322 Displays and lists
324 Bd, Ed display block: -type [-offset width] [-compact]
325 D1 indented display (one line)
326 Dl indented literal display (one line)
327 Ql in-line literal display: ‘text’
328 Bl, El list block: -type [-width val] [-offset val] [-compact]
329 It list item (syntax depends on -type)
330 Ta table cell separator in Bl -column lists
331 Rs, %*, Re bibliographic block (references)
332 Spacing control
334 Pf prefix, no following horizontal space (one argument)
335 Ns roman font, no preceding horizontal space (no arguments)
336 Ap apostrophe without surrounding whitespace (no arguments)
337 Sm switch horizontal spacing mode: [on | off]
338 Bk, Ek keep block: -words
339 Semantic markup for command line utilities
341 Nm start a SYNOPSIS block with the name of a utility
342 Fl command line options (flags) (>=0 arguments)
343 Cm command modifier (>0 arguments)
344 Ar command arguments (>=0 arguments)
345 Op, Oo, Oc optional syntax elements (enclosure)
346 Ic internal or interactive command (>0 arguments)
347 Ev environmental variable (>0 arguments)
348 Pa file system path (>=0 arguments)
349 Semantic markup for function libraries
351 Lb function library (one argument)
352 In include file (one argument)
353 Fd other preprocessor directive (>0 arguments)
354 Ft function type (>0 arguments)
355 Fo, Fc function block: funcname
356 Fn function name: funcname [argument ...]
357 Fa function argument (>0 arguments)
358 Vt variable type (>0 arguments)
359 Va variable name (>0 arguments)
360 Dv defined variable or preprocessor constant (>0 arguments)
361 Er error constant (>0 arguments)
362 Ev environmental variable (>0 arguments)
363 Various semantic markup
365 An author name (>0 arguments)
366 Lk hyperlink: uri [display_name]
367 Mt “mailto” hyperlink: localpart@domain
368 Cd kernel configuration declaration (>0 arguments)
369 Ad memory address (>0 arguments)
370 Ms mathematical symbol (>0 arguments)
371 Physical markup
373 Em italic font or underline (emphasis) (>0 arguments)
374 Sy boldface font (symbolic) (>0 arguments)
375 No return to roman font (normal) (>0 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 first_name ... last_name
405 Author name of an Rs block. Multiple authors should each be ac‐
406 corded their own %A line. Author names should be ordered with full
407 or abbreviated forename(s) first, then full surname.
408 %B title
410 Book title of an Rs block. This macro may also be used in a non-
411 bibliographic context when referring to book titles.
412 %C location
414 Publication city or location of an Rs block.
415 %D [month day,] year
417 Publication date of an Rs block. Provide the full English name of
418 the month and all four digits of the year.
419 %I name
421 Publisher or issuer name of an Rs block.
422 %J name
424 Journal name of an Rs block.
425 %N number
427 Issue number (usually for journals) of an Rs block.
428 %O line
430 Optional information of an Rs block.
431 %P number
433 Book or journal page number of an Rs block. Conventionally, the ar‐
434 gument starts with ‘p.’ for a single page or ‘pp.’ for a range of
435 pages, for example:
436 .%P pp. 42\(en47
438 %Q name
440 Institutional author (school, government, etc.) of an Rs block.
441 Multiple institutional authors should each be accorded their own %Q
442 line.
443 %R name
445 Technical report name of an Rs block.
446 %T title
448 Article title of an Rs block. This macro may also be used in a non-
449 bibliographical context when referring to article titles.
450 %U protocol://path
452 URI of reference document.
453 %V number
455 Volume number of an Rs block.
456 Ac Close an Ao block. Does not have any tail arguments.
458 Ad address
460 Memory address. Do not use this for postal addresses.
461 Examples:
463 .Ad [0,$]
464 .Ad 0x00000000
465 An -split | -nosplit | first_name ... last_name
467 Author name. Can be used both for the authors of the program, func‐
468 tion, or driver documented in the manual, or for the authors of the
469 manual itself. Requires either the name of an author or one of the
470 following arguments:
471 -split Start a new output line before each subsequent in‐
473 vocation of An.
474 -nosplit The opposite of -split.
475 The default is -nosplit. The effect of selecting either of the
477 -split modes ends at the beginning of the AUTHORS section. In the
478 AUTHORS section, the default is -nosplit for the first author list‐
479 ing and -split for all other author listings.
480 Examples:
482 .An -nosplit
483 .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
484 Ao block
486 Begin a block enclosed by angle brackets. Does not have any head
487 arguments. This macro is almost never useful. See Aq for more de‐
488 tails.
489 Ap Inserts an apostrophe without any surrounding whitespace. This is
491 generally used as a grammatical device when referring to the verb
492 form of a function.
493 Examples:
495 .Fn execve Ap d
496 Aq line
498 Enclose the rest of the input line in angle brackets. The only im‐
499 portant use case is for email addresses. See Mt for an example.
500 Occasionally, it is used for names of characters and keys, for exam‐
502 ple:
503 Press the
505 .Aq escape
506 key to ...
507 For URIs, use Lk instead, and In for “#include” directives. Never
509 wrap Ar in Aq.
510 Since Aq usually renders with non-ASCII characters in non-ASCII out‐
512 put modes, do not use it where the ASCII characters ‘<’ and ‘>’ are
513 required as syntax elements. Instead, use these characters directly
514 in such cases, combining them with the macros Pf, Ns, or Eo as
515 needed.
516 See also Ao.
518 Ar [placeholder ...]
520 Command arguments. If an argument is not provided, the string “file
521 ...” is used as a default.
522 Examples:
524 .Fl o Ar file
525 .Ar
526 .Ar arg1 , arg2 .
527 The arguments to the Ar macro are names and placeholders for command
529 arguments; for fixed strings to be passed verbatim as arguments, use
530 Fl or Cm.
531 At [version]
533 Formats an AT&T UNIX version. Accepts one optional argument:
534 v[1-7] | 32v A version of AT&T UNIX.
536 III AT&T System III UNIX.
537 V | V.[1-4] A version of AT&T System V UNIX.
538 Note that these arguments do not begin with a hyphen.
540 Examples:
542 .At
543 .At III
544 .At V.1
545 See also Bsx, Bx, Dx, Fx, Nx, and Ox.
547 Bc Close a Bo block. Does not have any tail arguments.
549 Bd -type [-offset width] [-compact]
551 Begin a display block. Display blocks are used to select a differ‐
552 ent indentation and justification than the one used by the surround‐
553 ing text. They may contain both macro lines and text lines. By de‐
554 fault, a display block is preceded by a vertical space.
555 The type must be one of the following:
557 -centered Produce one output line from each input line,
559 and center-justify each line. Using this dis‐
560 play type is not recommended; many mdoc imple‐
561 mentations render it poorly.
562 -filled Change the positions of line breaks to fill
564 each line, and left- and right-justify the re‐
565 sulting block.
566 -literal Produce one output line from each input line,
568 and do not justify the block at all. Preserve
569 white space as it appears in the input. Always
570 use a constant-width font. Use this for dis‐
571 playing source code.
572 -ragged Change the positions of line breaks to fill
574 each line, and left-justify the resulting
575 block.
576 -unfilled The same as -literal, but using the same font
578 as for normal text, which is a variable width
579 font if supported by the output device.
580 The type must be provided first. Additional arguments may follow:
582 -offset width Indent the display by the width, which may be
584 one of the following:
585 One of the pre-defined strings indent, the
587 width of a standard indentation (six constant
588 width characters); indent-two, twice indent;
589 left, which has no effect; right, which justi‐
590 fies to the right margin; or center, which
591 aligns around an imagined center axis.
592 A macro invocation, which selects a predefined
594 width associated with that macro. The most
595 popular is the imaginary macro Ds, which re‐
596 solves to 6n.
597 A scaling width as described in roff(7).
599 An arbitrary string, which indents by the
601 length of this string.
602 When the argument is missing, -offset is ig‐
604 nored.
605 -compact Do not assert vertical space before the dis‐
607 play.
608 Examples:
610 .Bd -literal -offset indent -compact
612 Hello world.
613 .Ed
614 See also D1 and Dl.
616 Bf -emphasis | -literal | -symbolic | Em | Li | Sy
618 Change the font mode for a scoped block of text. The -emphasis and
619 Em argument are equivalent, as are -symbolic and Sy, and -literal
620 and Li. Without an argument, this macro does nothing. The font
621 mode continues until broken by a new font mode in a nested scope or
622 Ef is encountered.
623 See also Li, Ef, Em, and Sy.
625 Bk -words
627 For each macro, keep its output together on the same output line,
628 until the end of the macro or the end of the input line is reached,
629 whichever comes first. Line breaks in text lines are unaffected.
630 The -words argument is required; additional arguments are ignored.
632 The following example will not break within each Op macro line:
634 .Bk -words
636 .Op Fl f Ar flags
637 .Op Fl o Ar output
638 .Ek
639 Be careful in using over-long lines within a keep block! Doing so
641 will clobber the right margin.
642 Bl -type [-width val] [-offset val] [-compact] [col ...]
644 Begin a list. Lists consist of items specified using the It macro,
645 containing a head or a body or both.
646 The list type is mandatory and must be specified first. The -width
648 and -offset arguments accept macro names as described for Bd
649 -offset, scaling widths as described in roff(7), or use the length
650 of the given string. The -offset is a global indentation for the
651 whole list, affecting both item heads and bodies. For those list
652 types supporting it, the -width argument requests an additional in‐
653 dentation of item bodies, to be added to the -offset. Unless the
654 -compact argument is specified, list entries are separated by verti‐
655 cal space.
656 A list must specify one of the following list types:
658 -bullet No item heads can be specified, but a bullet
660 will be printed at the head of each item. Item
661 bodies start on the same output line as the bul‐
662 let and are indented according to the -width ar‐
663 gument.
664 -column A columnated list. The -width argument has no
666 effect; instead, the string length of each argu‐
667 ment specifies the width of one column. If the
668 first line of the body of a -column list is not
669 an It macro line, It contexts spanning one input
670 line each are implied until an It macro line is
671 encountered, at which point items start being
672 interpreted as described in the It documenta‐
673 tion.
674 -dash Like -bullet, except that dashes are used in
676 place of bullets.
677 -diag Like -inset, except that item heads are not
679 parsed for macro invocations. Most often used
680 in the DIAGNOSTICS section with error constants
681 in the item heads.
682 -enum A numbered list. No item heads can be speci‐
684 fied. Formatted like -bullet, except that car‐
685 dinal numbers are used in place of bullets,
686 starting at 1.
687 -hang Like -tag, except that the first lines of item
689 bodies are not indented, but follow the item
690 heads like in -inset lists.
691 -hyphen Synonym for -dash.
693 -inset Item bodies follow items heads on the same line,
695 using normal inter-word spacing. Bodies are not
696 indented, and the -width argument is ignored.
697 -item No item heads can be specified, and none are
699 printed. Bodies are not indented, and the
700 -width argument is ignored.
701 -ohang Item bodies start on the line following item
703 heads and are not indented. The -width argument
704 is ignored.
705 -tag Item bodies are indented according to the -width
707 argument. When an item head fits inside the in‐
708 dentation, the item body follows this head on
709 the same output line. Otherwise, the body
710 starts on the output line following the head.
711 Lists may be nested within lists and displays. Nesting of -column
713 and -enum lists may not be portable.
714 See also El and It.
716 Bo block
718 Begin a block enclosed by square brackets. Does not have any head
719 arguments.
720 Examples:
722 .Bo 1 ,
723 .Dv BUFSIZ Bc
724 See also Bq.
726 Bq line
728 Encloses its arguments in square brackets.
729 Examples:
731 .Bq 1, Dv BUFSIZ
732 Remarks: this macro is sometimes abused to emulate optional argu‐
734 ments for commands; the correct macros to use for this purpose are
735 Op, Oo, and Oc.
736 See also Bo.
738 Brc Close a Bro block. Does not have any tail arguments.
740 Bro block
742 Begin a block enclosed by curly braces. Does not have any head ar‐
743 guments.
744 Examples:
746 .Bro 1 , ... ,
747 .Va n Brc
748 See also Brq.
750 Brq line
752 Encloses its arguments in curly braces.
753 Examples:
755 .Brq 1, ..., Va n
756 See also Bro.
758 Bsx [version]
760 Format the BSD/OS version provided as an argument, or a default
761 value if no argument is provided.
762 Examples:
764 .Bsx 1.0
765 .Bsx
766 See also At, Bx, Dx, Fx, Nx, and Ox.
768 Bt Supported only for compatibility, do not use this in new manuals.
770 Prints “is currently in beta test.”
771 Bx [version [variant]]
773 Format the BSD version provided as an argument, or a default value
774 if no 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 line
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
791 retain whitespace and align consecutive Cd declarations. This prac‐
792 tise is discouraged.
793 Cm keyword ...
795 Command modifiers. Typically used for fixed strings passed as argu‐
796 ments to interactive commands, to commands in interpreted scripts,
797 or to configuration file directives, unless Fl is more appropriate.
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 .Ic set Fl o Cm vi
804 .Ic lookup Cm file bind
805 .Ic permit Ar identity Op Cm as Ar target
806 D1 line
808 One-line indented display. This is formatted by the default rules
809 and is useful for simple indented statements. It is followed by a
810 newline.
811 Examples:
813 .D1 Fl abcdefgh
814 See also Bd and Dl.
816 Db This macro is obsolete. No replacement is needed. It is ignored by
818 mandoc(1) and groff including its arguments. It was formerly used
819 to toggle a debugging mode.
820 Dc Close a Do block. Does not have any tail arguments.
822 Dd $Mdocdate$ | month day, year
824 Document date for display in the page footer, by convention the date
825 of the last change. This is the mandatory first macro of any mdoc
826 manual.
827 The month is the full English month name, the day is an integer num‐
829 ber, and the year is the full four-digit year.
830 Other arguments are not portable; the mandoc(1) utility handles them
832 as follows:
833 - To have the date automatically filled in by the OpenBSD ver‐
834 sion of cvs(1), the special string “$Mdocdate$” can be given
835 as an argument.
836 - The traditional, purely numeric man(7) format year–month–day
837 is accepted, too.
838 - If a date string cannot be parsed, it is used verbatim.
839 - If no date string is given, the current date is used.
840 Examples:
842 .Dd $Mdocdate$
843 .Dd $Mdocdate: July 2 2018$
844 .Dd July 2, 2018
845 See also Dt and Os.
847 Dl line
849 One-line indented display. This is formatted as literal text and is
850 useful for commands and invocations. It is followed by a newline.
851 Examples:
853 .Dl % mandoc mdoc.7 \(ba less
854 See also Ql, Bd -literal, and D1.
856 Do block
858 Begin a block enclosed by double quotes. Does not have any head ar‐
859 guments.
860 Examples:
862 .Do
863 April is the cruellest month
864 .Dc
865 \(em T.S. Eliot
866 See also Dq.
868 Dq line
870 Encloses its arguments in “typographic” double-quotes.
871 Examples:
873 .Dq April is the cruellest month
874 \(em T.S. Eliot
875 See also Qq, Sq, and Do.
877 Dt TITLE section [arch]
879 Document title for display in the page header. This is the manda‐
880 tory second macro of any mdoc file.
881 Its arguments are as follows:
883 TITLE The document's title (name), defaulting to “UNTITLED” if
885 unspecified. To achieve a uniform appearance of page
886 header lines, it should by convention be all caps.
887 section The manual section. This may be one of 1 (General
889 Commands), 2 (System Calls), 3 (Library Functions), 3p
890 (Perl Library), 4 (Device Drivers), 5 (File Formats), 6
891 (Games), 7 (Miscellaneous Information), 8 (System
892 Manager's Manual), or 9 (Kernel Developer's Manual). It
893 should correspond to the manual's filename suffix and de‐
894 faults to the empty string if unspecified.
895 arch This specifies the machine architecture a manual page ap‐
897 plies to, where relevant, for example alpha, amd64, i386,
898 or sparc64. The list of valid architectures varies by
899 operating system.
900 Examples:
902 .Dt FOO 1
903 .Dt FOO 9 i386
904 See also Dd and Os.
906 Dv identifier ...
908 Defined variables such as preprocessor constants, constant symbols,
909 enumeration values, and so on.
910 Examples:
912 .Dv NULL
913 .Dv BUFSIZ
914 .Dv STDOUT_FILENO
915 See also Er and Ev for special-purpose constants, Va for variable
917 symbols, and Fd for listing preprocessor variable definitions in the
918 SYNOPSIS.
919 Dx [version]
921 Format the DragonFly version provided as an argument, or a default
922 value if no argument is provided.
923 Examples:
925 .Dx 2.4.1
926 .Dx
927 See also At, Bsx, Bx, Fx, Nx, and Ox.
929 Ec [closing_delimiter]
931 Close a scope started by Eo.
932 The closing_delimiter argument is used as the enclosure tail, for
934 example, specifying \(rq will emulate Dc.
935 Ed End a display context started by Bd.
937 Ef End a font mode context started by Bf.
939 Ek End a keep context started by Bk.
941 El End a list context started by Bl. See also It.
943 Em word ...
945 Request an italic font. If the output device does not provide that,
946 underline.
947 This is most often used for stress emphasis (not to be confused with
949 importance, see Sy). In the rare cases where none of the semantic
950 markup macros fit, it can also be used for technical terms and
951 placeholders, except that for syntax elements, Sy and Ar are pre‐
952 ferred, respectively.
953 Examples:
955 Selected lines are those
956 .Em not
957 matching any of the specified patterns.
958 Some of the functions use a
959 .Em hold space
960 to save the pattern space for subsequent retrieval.
961 See also No, Ql, and Sy.
963 En word ...
965 This macro is obsolete. Use Eo or any of the other enclosure
966 macros.
967 It encloses its argument in the delimiters specified by the last Es
969 macro.
970 Eo [opening_delimiter]
972 An arbitrary enclosure. The opening_delimiter argument is used as
973 the enclosure head, for example, specifying \(lq will emulate Do.
974 Er identifier ...
976 Error constants for definitions of the errno libc global variable.
977 This is most often used in section 2 and 3 manual pages.
978 Examples:
980 .Er EPERM
981 .Er ENOENT
982 See also Dv for general constants.
984 Es opening_delimiter closing_delimiter
986 This macro is obsolete. Use Eo or any of the other enclosure
987 macros.
988 It takes two arguments, defining the delimiters to be used by subse‐
990 quent En macros.
991 Ev identifier ...
993 Environmental variables such as those specified in environ(7).
994 Examples:
996 .Ev DISPLAY
997 .Ev PATH
998 See also Dv for general constants.
1000 Ex -std [utility ...]
1002 Insert a standard sentence regarding command exit values of 0 on
1003 success and >0 on failure. This is most often used in section 1, 6,
1004 and 8 manual pages.
1005 If utility is not specified, the document's name set by Nm is used.
1007 Multiple utility arguments are treated as separate utilities.
1008 See also Rv.
1010 Fa argument ...
1012 Function argument or parameter. Each argument may be a name and a
1013 type (recommended for the SYNOPSIS section), a name alone (for func‐
1014 tion invocations), or a type alone (for function prototypes). If
1015 both a type and a name are given or if the type consists of multiple
1016 words, all words belonging to the same function argument have to be
1017 given in a single argument to the Fa macro.
1018 This macro is also used to specify the field name of a structure.
1020 Most often, the Fa macro is used in the SYNOPSIS within Fo blocks
1022 when documenting multi-line function prototypes. If invoked with
1023 multiple arguments, the arguments are separated by a comma. Fur‐
1024 thermore, if the following macro is another Fa, the last argument
1025 will also have a trailing comma.
1026 Examples:
1028 .Fa "const char *p"
1029 .Fa "int a" "int b" "int c"
1030 .Fa "char *" size_t
1031 See also Fo.
1033 Fc End a function context started by Fo.
1035 Fd #directive [argument ...]
1037 Preprocessor directive, in particular for listing it in the
1038 SYNOPSIS. Historically, it was also used to document include files.
1039 The latter usage has been deprecated in favour of In.
1040 Examples:
1042 .Fd #define sa_handler __sigaction_u.__sa_handler
1043 .Fd #define SIO_MAXNFDS
1044 .Fd #ifdef FS_DEBUG
1045 .Ft void
1046 .Fn dbg_open "const char *"
1047 .Fd #endif
1048 See also MANUAL STRUCTURE, In, and Dv.
1050 Fl [word ...]
1052 Command-line flag or option. Used when listing arguments to com‐
1053 mand-line utilities. For each argument, prints an ASCII hyphen-mi‐
1054 nus character ‘-’, immediately followed by the argument. If no ar‐
1055 guments are provided, a hyphen-minus is printed followed by a space.
1056 If the argument is a macro, a hyphen-minus is prefixed to the subse‐
1057 quent macro output.
1058 Examples:
1060 .Nm du Op Fl H | L | P
1061 .Nm ls Op Fl 1AaCcdFfgHhikLlmnopqRrSsTtux
1062 .Nm route Cm add Fl inet Ar destination gateway
1063 .Nm locate.updatedb Op Fl \-fcodes Ns = Ns Ar dbfile
1064 .Nm aucat Fl o Fl
1065 .Nm kill Fl Ar signal_number
1066 For GNU-sytle long options, escaping the additional hyphen-minus is
1068 not strictly required, but may be safer with future versions of GNU
1069 troff; see mandoc_char(7) for details.
1070 See also Cm.
1072 Fn funcname [argument ...]
1074 A function name.
1075 Function arguments are surrounded in parenthesis and are delimited
1077 by commas. If no arguments are specified, blank parenthesis are
1078 output. In the SYNOPSIS section, this macro starts a new output
1079 line, and a blank line is automatically inserted between function
1080 definitions.
1081 Examples:
1083 .Fn "int funcname" "int arg0" "int arg1"
1084 .Fn funcname "int arg0"
1085 .Fn funcname arg0
1086 .Ft functype
1088 .Fn funcname
1089 When referring to a function documented in another manual page, use
1091 Xr instead. See also MANUAL STRUCTURE, Fo, and Ft.
1092 Fo funcname
1094 Begin a function block. This is a multi-line version of Fn.
1095 Invocations usually occur in the following context:
1097 .Ft functype
1099 .Fo funcname
1100 .Fa "argtype argname"
1101 ...
1102 .Fc
1103 A Fo scope is closed by Fc.
1105 See also MANUAL STRUCTURE, Fa, Fc, and Ft.
1107 Fr number
1109 This macro is obsolete. No replacement markup is needed.
1110 It was used to show numerical function return values in an italic
1112 font.
1113 Ft functype
1115 A function type.
1116 In the SYNOPSIS section, a new output line is started after this
1118 macro.
1119 Examples:
1121 .Ft int
1122 .Ft functype
1123 .Fn funcname
1124 See also MANUAL STRUCTURE, Fn, and Fo.
1126 Fx [version]
1128 Format the FreeBSD version provided as an argument, or a default
1129 value if no argument is provided.
1130 Examples:
1132 .Fx 7.1
1133 .Fx
1134 See also At, Bsx, Bx, Dx, Nx, and Ox.
1136 Hf filename
1138 This macro is not implemented in mandoc(1). It was used to include
1139 the contents of a (header) file literally.
1140 Ic keyword ...
1142 Internal or interactive command, or configuration instruction in a
1143 configuration file. See also Cm.
1144 Examples:
1146 .Ic :wq
1147 .Ic hash
1148 .Ic alias
1149 Note that using Ql, Dl, or Bd -literal is preferred for displaying
1151 code samples; the Ic macro is used when referring to an individual
1152 command name.
1153 In filename
1155 The name of an include file. This macro is most often used in sec‐
1156 tion 2, 3, and 9 manual pages.
1157 When invoked as the first macro on an input line in the SYNOPSIS
1159 section, the argument is displayed in angle brackets and preceded by
1160 "#include", and a blank line is inserted in front if there is a pre‐
1161 ceding function declaration. In other sections, it only encloses
1162 its argument in angle brackets and causes no line break.
1163 Examples:
1165 .In sys/types.h
1166 See also MANUAL STRUCTURE.
1168 It [head]
1170 A list item. The syntax of this macro depends on the list type.
1171 Lists of type -hang, -ohang, -inset, and -diag have the following
1173 syntax:
1174 .It args
1176 Lists of type -bullet, -dash, -enum, -hyphen and -item have the fol‐
1178 lowing syntax:
1179 .It
1181 with subsequent lines interpreted within the scope of the It until
1183 either a closing El or another It.
1184 The -tag list has the following syntax:
1186 .It [args]
1188 Subsequent lines are interpreted as with -bullet and family. The
1190 line arguments correspond to the list's left-hand side; body argu‐
1191 ments correspond to the list's contents.
1192 The -column list is the most complicated. Its syntax is as follows:
1194 .It cell [Ta cell ...]
1196 .It cell [<TAB> cell ...]
1197 The arguments consist of one or more lines of text and macros repre‐
1199 senting a complete table line. Cells within the line are delimited
1200 by the special Ta block macro or by literal tab characters.
1201 Using literal tabs is strongly discouraged because they are very
1203 hard to use correctly and mdoc code using them is very hard to read.
1204 In particular, a blank character is syntactically significant before
1205 and after the literal tab character. If a word precedes or follows
1206 the tab without an intervening blank, that word is never interpreted
1207 as a macro call, but always output literally.
1208 The tab cell delimiter may only be used within the It line itself;
1210 on following lines, only the Ta macro can be used to delimit cells,
1211 and portability requires that Ta is called by other macros: some
1212 parsers do not recognize it when it appears as the first macro on a
1213 line.
1214 Note that quoted strings may span tab-delimited cells on an It line.
1216 For example,
1217 .It "col1 , <TAB> col2 ," ;
1219 will preserve the whitespace before both commas, but not the white‐
1221 space before the semicolon.
1222 See also Bl.
1224 Lb libname
1226 Specify a library.
1227 The name parameter may be a system library, such as z or pam, in
1229 which case a small library description is printed next to the linker
1230 invocation; or a custom library, in which case the library name is
1231 printed in quotes. This is most commonly used in the SYNOPSIS sec‐
1232 tion as described in MANUAL STRUCTURE.
1233 Examples:
1235 .Lb libz
1236 .Lb libmandoc
1237 Li word ...
1239 Request a typewriter (literal) font. Deprecated because on terminal
1240 output devices, this is usually indistinguishable from normal text.
1241 For literal displays, use Ql (in-line), Dl (single line), or Bd
1242 -literal (multi-line) instead.
1243 Lk uri [display_name]
1245 Format a hyperlink.
1246 Examples:
1248 .Lk https://bsd.lv "The BSD.lv Project"
1249 .Lk https://bsd.lv
1250 See also Mt.
1252 Lp Deprecated synonym for Pp.
1254 Ms name
1256 Display a mathematical symbol.
1257 Examples:
1259 .Ms sigma
1260 .Ms aleph
1261 Mt localpart@domain
1263 Format a “mailto:” hyperlink.
1264 Examples:
1266 .Mt discuss@manpages.bsd.lv
1267 .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
1268 Nd line
1270 A one line description of the manual's content. This is the manda‐
1271 tory last macro of the NAME section and not appropriate for other
1272 sections.
1273 Examples:
1275 .Nd mdoc language reference
1276 .Nd format and display UNIX manuals
1277 The Nd macro technically accepts child macros and terminates with a
1279 subsequent Sh invocation. Do not assume this behaviour: some
1280 whatis(1) database generators are not smart enough to parse more
1281 than the line arguments and will display macros verbatim.
1282 See also Nm.
1284 Nm [name]
1286 The name of the manual page, or — in particular in section 1, 6, and
1287 8 pages — of an additional command or feature documented in the man‐
1288 ual page. When first invoked, the Nm macro expects a single argu‐
1289 ment, the name of the manual page. Usually, the first invocation
1290 happens in the NAME section of the page. The specified name will be
1291 remembered and used whenever the macro is called again without argu‐
1292 ments later in the page. The Nm macro uses Block full-implicit se‐
1293 mantics when invoked as the first macro on an input line in the
1294 SYNOPSIS section; otherwise, it uses ordinary In-line semantics.
1295 Examples:
1297 .Sh SYNOPSIS
1299 .Nm cat
1300 .Op Fl benstuv
1301 .Op Ar
1302 In the SYNOPSIS of section 2, 3 and 9 manual pages, use the Fn macro
1304 rather than Nm to mark up the name of the manual page.
1305 No word ...
1307 Normal text. Closes the scope of any preceding in-line macro. When
1308 used after physical formatting macros like Em or Sy, switches back
1309 to the standard font face and weight. Can also be used to embed
1310 plain text strings in macro lines using semantic annotation macros.
1311 Examples:
1313 .Em italic , Sy bold , No and roman
1314 .Sm off
1316 .Cm :C No / Ar pattern No / Ar replacement No /
1317 .Sm on
1318 See also Em, Ql, and Sy.
1320 Ns Suppress a space between the output of the preceding macro and the
1322 following text or macro. Following invocation, input is interpreted
1323 as normal text just like after an No macro.
1324 This has no effect when invoked at the start of a macro line.
1326 Examples:
1328 .Ar name Ns = Ns Ar value
1329 .Cm :M Ns Ar pattern
1330 .Fl o Ns Ar output
1331 See also No and Sm.
1333 Nx [version]
1335 Format the NetBSD version provided as an argument, or a default
1336 value if no argument is provided.
1337 Examples:
1339 .Nx 5.01
1340 .Nx
1341 See also At, Bsx, Bx, Dx, Fx, and Ox.
1343 Oc Close multi-line Oo context.
1345 Oo block
1347 Multi-line version of Op.
1348 Examples:
1350 .Oo
1351 .Op Fl flag Ns Ar value
1352 .Oc
1353 Op line
1355 Optional part of a command line. Prints the argument(s) in brack‐
1356 ets. This is most often used in the SYNOPSIS section of section 1
1357 and 8 manual pages.
1358 Examples:
1360 .Op Fl a Ar b
1361 .Op Ar a | b
1362 See also Oo.
1364 Os [system [version]]
1366 Operating system version for display in the page footer. This is
1367 the mandatory third macro of any mdoc file.
1368 The optional system parameter specifies the relevant operating sys‐
1370 tem or environment. It is suggested to leave it unspecified, in
1371 which case mandoc(1) uses its -Ios argument or, if that isn't speci‐
1372 fied either, sysname and release as returned by uname(3).
1373 Examples:
1375 .Os
1376 .Os KTH/CSC/TCS
1377 .Os BSD 4.3
1378 See also Dd and Dt.
1380 Ot functype
1382 This macro is obsolete. Use Ft instead; with mandoc(1), both have
1383 the same effect.
1384 Historical mdoc packages described it as “old function type
1386 (FORTRAN)”.
1387 Ox [version]
1389 Format the OpenBSD version provided as an argument, or a default
1390 value if no argument is provided.
1391 Examples:
1393 .Ox 4.5
1394 .Ox
1395 See also At, Bsx, Bx, Dx, Fx, and Nx.
1397 Pa name ...
1399 An absolute or relative file system path, or a file or directory
1400 name. If an argument is not provided, the character ‘~’ is used as
1401 a default.
1402 Examples:
1404 .Pa /usr/bin/mandoc
1405 .Pa /usr/share/man/man7/mdoc.7
1406 See also Lk.
1408 Pc Close parenthesised context opened by Po.
1410 Pf prefix macro [argument ...]
1412 Removes the space between its argument and the following macro. It
1413 is equivalent to:
1414 No \&prefix Ns macro [argument ...]
1416 The prefix argument is not parsed for macro names or delimiters, but
1418 used verbatim as if it were escaped.
1419 Examples:
1421 .Pf $ Ar variable_name
1422 .Pf . Ar macro_name
1423 .Pf 0x Ar hex_digits
1424 See also Ns and Sm.
1426 Po block
1428 Multi-line version of Pq.
1429 Pp Break a paragraph. This will assert vertical space between prior
1431 and subsequent macros and/or text.
1432 Paragraph breaks are not needed before or after Sh or Ss macros or
1434 before displays (Bd line) or lists (Bl) unless the -compact flag is
1435 given.
1436 Pq line
1438 Parenthesised enclosure.
1439 See also Po.
1441 Qc Close quoted context opened by Qo.
1443 Ql line
1445 In-line literal display. This can be used for complete command in‐
1446 vocations and for multi-word code examples when an indented display
1447 is not desired.
1448 See also Dl and Bd -literal.
1450 Qo block
1452 Multi-line version of Qq.
1453 Qq line
1455 Encloses its arguments in "typewriter" double-quotes. Consider us‐
1456 ing Dq.
1457 See also Dq, Sq, and Qo.
1459 Re Close an Rs block. Does not have any tail arguments.
1461 Rs Begin a bibliographic (“reference”) block. Does not have any head
1463 arguments. The block macro may only contain %A, %B, %C, %D, %I, %J,
1464 %N, %O, %P, %Q, %R, %T, %U, and %V child macros (at least one must
1465 be specified).
1466 Examples:
1468 .Rs
1469 .%A J. E. Hopcroft
1470 .%A J. D. Ullman
1471 .%B Introduction to Automata Theory, Languages, and Computation
1472 .%I Addison-Wesley
1473 .%C Reading, Massachusetts
1474 .%D 1979
1475 .Re
1476 If an Rs block is used within a SEE ALSO section, a vertical space
1478 is asserted before the rendered output, else the block continues on
1479 the current line.
1480 Rv -std [function ...]
1482 Insert a standard sentence regarding a function call's return value
1483 of 0 on success and -1 on error, with the errno libc global variable
1484 set on error.
1485 If function is not specified, the document's name set by Nm is used.
1487 Multiple function arguments are treated as separate functions.
1488 See also Ex.
1490 Sc Close single-quoted context opened by So.
1492 Sh TITLE LINE
1494 Begin a new section. For a list of conventional manual sections,
1495 see MANUAL STRUCTURE. These sections should be used unless it's ab‐
1496 solutely necessary that custom sections be used.
1497 Section names should be unique so that they may be keyed by Sx. Al‐
1499 though this macro is parsed, it should not consist of child node or
1500 it may not be linked with Sx.
1501 See also Pp, Ss, and Sx.
1503 Sm [on | off]
1505 Switches the spacing mode for output generated from macros.
1506 By default, spacing is on. When switched off, no white space is in‐
1508 serted between macro arguments and between the output generated from
1509 adjacent macros, but text lines still get normal spacing between
1510 words and sentences.
1511 When called without an argument, the Sm macro toggles the spacing
1513 mode. Using this is not recommended because it makes the code
1514 harder to read.
1515 So block
1517 Multi-line version of Sq.
1518 Sq line
1520 Encloses its arguments in ‘typewriter’ single-quotes.
1521 See also Dq, Qq, and So.
1523 Ss Title line
1525 Begin a new subsection. Unlike with Sh, there is no convention for
1526 the naming of subsections. Except DESCRIPTION, the conventional
1527 sections described in MANUAL STRUCTURE rarely have subsections.
1528 Sub-section names should be unique so that they may be keyed by Sx.
1530 Although this macro is parsed, it should not consist of child node
1531 or it may not be linked with Sx.
1532 See also Pp, Sh, and Sx.
1534 St -abbreviation
1536 Replace an abbreviation for a standard with the full form. The fol‐
1537 lowing standards are recognised. Where multiple lines are given
1538 without a blank line in between, they all refer to the same stan‐
1539 dard, and using the first form is recommended.
1540 C language standards
1542 -ansiC ANSI X3.159-1989 (“ANSI C89”)
1544 -ansiC-89 ANSI X3.159-1989 (“ANSI C89”)
1545 -isoC ISO/IEC 9899:1990 (“ISO C90”)
1546 -isoC-90 ISO/IEC 9899:1990 (“ISO C90”)
1547 The original C standard.
1548 -isoC-amd1 ISO/IEC 9899/AMD1:1995 (“ISO C90, Amendment 1”)
1550 -isoC-tcor1 ISO/IEC 9899/TCOR1:1994 (“ISO C90, Technical
1552 Corrigendum 1”)
1553 -isoC-tcor2 ISO/IEC 9899/TCOR2:1995 (“ISO C90, Technical
1555 Corrigendum 2”)
1556 -isoC-99 ISO/IEC 9899:1999 (“ISO C99”)
1558 The second major version of the C language stan‐
1559 dard.
1560 -isoC-2011 ISO/IEC 9899:2011 (“ISO C11”)
1562 The third major version of the C language stan‐
1563 dard.
1564 POSIX.1 before the Single UNIX Specification
1566 -p1003.1-88 IEEE Std 1003.1-1988 (“POSIX.1”)
1568 -p1003.1 IEEE Std 1003.1 (“POSIX.1”)
1569 The original POSIX standard, based on ANSI C.
1570 -p1003.1-90 ISO/IEC 9945-1:1990 (“POSIX.1”)
1572 -iso9945-1-90 ISO/IEC 9945-1:1990 (“POSIX.1”)
1573 The first update of POSIX.1.
1574 -p1003.1b-93 IEEE Std 1003.1b-1993 (“POSIX.1”)
1576 -p1003.1b IEEE Std 1003.1b (“POSIX.1”)
1577 Real-time extensions.
1578 -p1003.1c-95 IEEE Std 1003.1c-1995 (“POSIX.1”)
1580 POSIX thread interfaces.
1581 -p1003.1i-95 IEEE Std 1003.1i-1995 (“POSIX.1”)
1583 Technical Corrigendum.
1584 -p1003.1-96 ISO/IEC 9945-1:1996 (“POSIX.1”)
1586 -iso9945-1-96 ISO/IEC 9945-1:1996 (“POSIX.1”)
1587 Includes POSIX.1-1990, 1b, 1c, and 1i.
1588 X/Open Portability Guide version 4 and related standards
1590 -xpg3 X/Open Portability Guide Issue 3 (“XPG3”)
1592 An XPG4 precursor, published in 1989.
1593 -p1003.2 IEEE Std 1003.2 (“POSIX.2”)
1595 -p1003.2-92 IEEE Std 1003.2-1992 (“POSIX.2”)
1596 -iso9945-2-93 ISO/IEC 9945-2:1993 (“POSIX.2”)
1597 An XCU4 precursor.
1598 -p1003.2a-92 IEEE Std 1003.2a-1992 (“POSIX.2”)
1600 Updates to POSIX.2.
1601 -xpg4 X/Open Portability Guide Issue 4 (“XPG4”)
1603 Based on POSIX.1 and POSIX.2, published in 1992.
1604 Single UNIX Specification version 1 and related standards
1606 -susv1
1608 -xpg4.2 X/Open Portability Guide Issue 4, Version 2
1609 (“XPG4.2”)
1610 This standard was published in 1994. It was used
1611 as the basis for UNIX 95 certification. The fol‐
1612 lowing three refer to parts of it.
1613 -xsh4.2
1615 -xcurses4.2 X/Open Curses Issue 4, Version 2 (“XCURSES4.2”)
1617 -p1003.1g-2000 IEEE Std 1003.1g-2000 (“POSIX.1”)
1619 Networking APIs, including sockets.
1620 -svid4 System V Interface Definition, Fourth Edition
1622 (“SVID4”),
1623 Published in 1995.
1624 Single UNIX Specification version 2 and related standards
1626 -susv2 Version 2 of the Single UNIX Specification
1628 (“SUSv2”) This Standard was published in 1997 and
1629 is also called X/Open Portability Guide version
1630 5. It was used as the basis for UNIX 98 certifi‐
1631 cation. The following refer to parts of it.
1632 -xbd5 X/Open Base Definitions Issue 5 (“XBD5”)
1634 -xsh5 X/Open System Interfaces and Headers Issue 5
1636 (“XSH5”)
1637 -xcu5 X/Open Commands and Utilities Issue 5 (“XCU5”)
1639 -xns5 X/Open Networking Services Issue 5 (“XNS5”)
1641 -xns5.2 X/Open Networking Services Issue 5.2 (“XNS5.2”)
1642 Single UNIX Specification version 3
1644 -p1003.1-2001 IEEE Std 1003.1-2001 (“POSIX.1”)
1646 -susv3 Version 3 of the Single UNIX Specification
1647 (“SUSv3”)
1648 This standard is based on C99, SUSv2,
1649 POSIX.1-1996, 1d, and 1j. It is also called
1650 X/Open Portability Guide version 6. It is used as
1651 the basis for UNIX 03 certification.
1652 -p1003.1-2004 IEEE Std 1003.1-2004 (“POSIX.1”)
1654 The second and last Technical Corrigendum.
1655 Single UNIX Specification version 4
1657 -p1003.1-2008 IEEE Std 1003.1-2008 (“POSIX.1”)
1659 -susv4
1660 This standard is also called X/Open Portability
1661 Guide version 7.
1662 Other standards
1664 -ieee754 IEEE Std 754-1985
1666 Floating-point arithmetic.
1667 -iso8601 ISO 8601
1669 Representation of dates and times, published in
1670 1988.
1671 -iso8802-3 ISO/IEC 8802-3:1989
1673 Ethernet local area networks.
1674 -ieee1275-94 IEEE Std 1275-1994 (“Open Firmware”)
1676 Sx Title line
1678 Reference a section or subsection in the same manual page. The ref‐
1679 erenced section or subsection name must be identical to the enclosed
1680 argument, including whitespace.
1681 Examples:
1683 .Sx MANUAL STRUCTURE
1684 See also Sh and Ss.
1686 Sy word ...
1688 Request a boldface font.
1689 This is most often used to indicate importance or seriousness (not
1691 to be confused with stress emphasis, see Em). When none of the se‐
1692 mantic macros fit, it is also adequate for syntax elements that have
1693 to be given or that appear verbatim.
1694 Examples:
1696 .Sy Warning :
1697 If
1698 .Sy s
1699 appears in the owner permissions, set-user-ID mode is set.
1700 This utility replaces the former
1701 .Sy dumpdir
1702 program.
1703 See also Em, No, and Ql.
1705 Ta Table cell separator in Bl -column lists; can only be used below It.
1707 Tg [term]
1709 Announce that the next input line starts a definition of the term.
1710 This macro must appear alone on its own input line. The argument
1711 defaults to the first argument of the first macro on the next line.
1712 The argument may not contain whitespace characters, not even when it
1713 is quoted. This macro is a mandoc(1) extension and is typically ig‐
1714 nored by other formatters.
1715 When viewing terminal output with less(1), the interactive :t com‐
1717 mand can be used to go to the definition of the term as described
1718 for the MANPAGER variable in man(1); when producing HTML output, a
1719 fragment identifier (id attribute) is generated, to be used for deep
1720 linking to this place of the document.
1721 In most cases, adding a Tg macro would be redundant because
1723 mandoc(1) is able to automatically tag most definitions. This macro
1724 is intended for cases where automatic tagging of a term is unsatis‐
1725 factory, for example if a definition is not tagged automatically
1726 (false negative) or if places are tagged that do not define the term
1727 (false positives). When there is at least one Tg macro for a term,
1728 no other places are automatically marked as definitions of that
1729 term.
1730 Tn word ...
1732 Supported only for compatibility, do not use this in new manuals.
1733 Even though the macro name (“tradename”) suggests a semantic func‐
1734 tion, historic usage is inconsistent, mostly using it as a presenta‐
1735 tion-level macro to request a small caps font.
1736 Ud Supported only for compatibility, do not use this in new manuals.
1738 Prints out “currently under development.”
1739 Ux Supported only for compatibility, do not use this in new manuals.
1741 Prints out “UNIX”.
1742 Va [type] identifier ...
1744 A variable name.
1745 Examples:
1747 .Va foo
1748 .Va const char *bar;
1749 For function arguments and parameters, use Fa instead. For declara‐
1751 tions of global variables in the SYNOPSIS section, use Vt.
1752 Vt type [identifier]
1754 A variable type.
1755 This is also used for indicating global variables in the SYNOPSIS
1757 section, in which case a variable name is also specified. Note that
1758 it accepts Block partial-implicit syntax when invoked as the first
1759 macro on an input line in the SYNOPSIS section, else it accepts or‐
1760 dinary In-line syntax. In the former case, this macro starts a new
1761 output line, and a blank line is inserted in front if there is a
1762 preceding function definition or include directive.
1763 Examples:
1765 .Vt unsigned char
1766 .Vt extern const char * const sys_signame[] ;
1767 For parameters in function prototypes, use Fa instead, for function
1769 return types Ft, and for variable names outside the SYNOPSIS section
1770 Va, even when including a type with the name. See also MANUAL
1771 STRUCTURE.
1772 Xc Close a scope opened by Xo.
1774 Xo block
1776 Extend the header of an It macro or the body of a partial-implicit
1777 block macro beyond the end of the input line. This macro originally
1778 existed to work around the 9-argument limit of historic roff(7).
1779 Xr name section
1781 Link to another manual ("cross-reference").
1782 Cross reference the name and section number of another man page.
1784 Examples:
1786 .Xr mandoc 1
1787 .Xr mandoc 1 ;
1788 .Xr mandoc 1 Ns s behaviour
1789
1791 The syntax of a macro depends on its classification. In this section,
1792 ‘-arg’ refers to macro arguments, which may be followed by zero or more
1793 ‘parm’ parameters; ‘Yo’ opens the scope of a macro; and if specified,
1794 ‘Yc’ closes it out.
1795 The Callable column indicates that the macro may also be called by pass‐
1797 ing its name as an argument to another macro. For example, ‘.Op Fl O Ar
1798 file’ produces ‘[-O file]’. To prevent a macro call and render the macro
1799 name literally, escape it by prepending a zero-width space, ‘\&’. For
1800 example, ‘Op \&Fl O’ produces ‘[Fl O]’. If a macro is not callable but
1801 its name appears as an argument to another macro, it is interpreted as
1802 opaque text. For example, ‘.Fl Sh’ produces ‘-Sh’.
1803 The Parsed column indicates whether the macro may call other macros by
1805 receiving their names as arguments. If a macro is not parsed but the
1806 name of another macro appears as an argument, it is interpreted as opaque
1807 text.
1808 The Scope column, if applicable, describes closure rules.
1810 Block full-explicit
1812 Multi-line scope closed by an explicit closing macro. All macros con‐
1813 tains bodies; only Bf and (optionally) Bl contain a head.
1814 .Yo [-arg [parm...]] [head...]
1816 [body...]
1817 .Yc
1818 Macro Callable Parsed Scope
1820 Bd No No closed by Ed
1821 Bf No No closed by Ef
1822 Bk No No closed by Ek
1823 Bl No No closed by El
1824 Ed No No opened by Bd
1825 Ef No No opened by Bf
1826 Ek No No opened by Bk
1827 El No No opened by Bl
1828 Block full-implicit
1830 Multi-line scope closed by end-of-file or implicitly by another macro.
1831 All macros have bodies; some (It -bullet, -hyphen, -dash, -enum, -item)
1832 don't have heads; only one (It in Bl -column) has multiple heads.
1833 .Yo [-arg [parm...]] [head... [Ta head...]]
1835 [body...]
1836 Macro Callable Parsed Scope
1838 It No Yes closed by It, El
1839 Nd No No closed by Sh
1840 Nm No Yes closed by Nm, Sh, Ss
1841 Sh No Yes closed by Sh
1842 Ss No Yes closed by Sh, Ss
1843 Note that the Nm macro is a Block full-implicit macro only when invoked
1845 as the first macro in a SYNOPSIS section line, else it is In-line.
1846 Block partial-explicit
1848 Like block full-explicit, but also with single-line scope. Each has at
1849 least a body and, in limited circumstances, a head (Fo, Eo) and/or tail
1850 (Ec).
1851 .Yo [-arg [parm...]] [head...]
1853 [body...]
1854 .Yc [tail...]
1855 .Yo [-arg [parm...]] [head...] [body...] Yc [tail...]
1857 Macro Callable Parsed Scope
1859 Ac Yes Yes opened by Ao
1860 Ao Yes Yes closed by Ac
1861 Bc Yes Yes closed by Bo
1862 Bo Yes Yes opened by Bc
1863 Brc Yes Yes opened by Bro
1864 Bro Yes Yes closed by Brc
1865 Dc Yes Yes opened by Do
1866 Do Yes Yes closed by Dc
1867 Ec Yes Yes opened by Eo
1868 Eo Yes Yes closed by Ec
1869 Fc Yes Yes opened by Fo
1870 Fo No No closed by Fc
1871 Oc Yes Yes closed by Oo
1872 Oo Yes Yes opened by Oc
1873 Pc Yes Yes closed by Po
1874 Po Yes Yes opened by Pc
1875 Qc Yes Yes opened by Oo
1876 Qo Yes Yes closed by Oc
1877 Re No No opened by Rs
1878 Rs No No closed by Re
1879 Sc Yes Yes opened by So
1880 So Yes Yes closed by Sc
1881 Xc Yes Yes opened by Xo
1882 Xo Yes Yes closed by Xc
1883 Block partial-implicit
1885 Like block full-implicit, but with single-line scope closed by the end of
1886 the line.
1887 .Yo [-arg [val...]] [body...] [res...]
1889 Macro Callable Parsed
1891 Aq Yes Yes
1892 Bq Yes Yes
1893 Brq Yes Yes
1894 D1 No Yes
1895 Dl No Yes
1896 Dq Yes Yes
1897 En Yes Yes
1898 Op Yes Yes
1899 Pq Yes Yes
1900 Ql Yes Yes
1901 Qq Yes Yes
1902 Sq Yes Yes
1903 Vt Yes Yes
1904 Note that the Vt macro is a Block partial-implicit only when invoked as
1906 the first macro in a SYNOPSIS section line, else it is In-line.
1907 Special block macro
1909 The Ta macro can only be used below It in Bl -column lists. It delimits
1910 blocks representing table cells; these blocks have bodies, but no heads.
1911 Macro Callable Parsed Scope
1913 Ta Yes Yes closed by Ta, It
1914 In-line
1916 Closed by the end of the line, fixed argument lengths, and/or subsequent
1917 macros. In-line macros have only text children. If a number (or in‐
1918 equality) of arguments is (n), then the macro accepts an arbitrary number
1919 of arguments.
1920 .Yo [-arg [val...]] [args...] [res...]
1922 .Yo [-arg [val...]] [args...] Yc...
1924 .Yo [-arg [val...]] arg0 arg1 argN
1926 Macro Callable Parsed Arguments
1928 %A No No >0
1929 %B No No >0
1930 %C No No >0
1931 %D No No >0
1932 %I No No >0
1933 %J No No >0
1934 %N No No >0
1935 %O No No >0
1936 %P No No >0
1937 %Q No No >0
1938 %R No No >0
1939 %T No No >0
1940 %U No No >0
1941 %V No No >0
1942 Ad Yes Yes >0
1943 An Yes Yes >0
1944 Ap Yes Yes 0
1945 Ar Yes Yes n
1946 At Yes Yes 1
1947 Bsx Yes Yes n
1948 Bt No No 0
1949 Bx Yes Yes n
1950 Cd Yes Yes >0
1951 Cm Yes Yes >0
1952 Db No No 1
1953 Dd No No n
1954 Dt No No n
1955 Dv Yes Yes >0
1956 Dx Yes Yes n
1957 Em Yes Yes >0
1958 Er Yes Yes >0
1959 Es Yes Yes 2
1960 Ev Yes Yes >0
1961 Ex No No n
1962 Fa Yes Yes >0
1963 Fd No No >0
1964 Fl Yes Yes n
1965 Fn Yes Yes >0
1966 Fr Yes Yes >0
1967 Ft Yes Yes >0
1968 Fx Yes Yes n
1969 Hf No No n
1970 Ic Yes Yes >0
1971 In No No 1
1972 Lb No No 1
1973 Li Yes Yes >0
1974 Lk Yes Yes >0
1975 Lp No No 0
1976 Ms Yes Yes >0
1977 Mt Yes Yes >0
1978 Nm Yes Yes n
1979 No Yes Yes >0
1980 Ns Yes Yes 0
1981 Nx Yes Yes n
1982 Os No No n
1983 Ot Yes Yes >0
1984 Ox Yes Yes n
1985 Pa Yes Yes n
1986 Pf Yes Yes 1
1987 Pp No No 0
1988 Rv No No n
1989 Sm No No <2
1990 St No Yes 1
1991 Sx Yes Yes >0
1992 Sy Yes Yes >0
1993 Tg No No <2
1994 Tn Yes Yes >0
1995 Ud No No 0
1996 Ux Yes Yes n
1997 Va Yes Yes n
1998 Vt Yes Yes >0
1999 Xr Yes Yes 2
2000 Delimiters
2002 When a macro argument consists of one single input character considered
2003 as a delimiter, the argument gets special handling. This does not apply
2004 when delimiters appear in arguments containing more than one character.
2005 Consequently, to prevent special handling and just handle it like any
2006 other argument, a delimiter can be escaped by prepending a zero-width
2007 space (‘\&’). In text lines, delimiters never need escaping, but may be
2008 used as normal punctuation.
2009 For many macros, when the leading arguments are opening delimiters, these
2011 delimiters are put before the macro scope, and when the trailing argu‐
2012 ments are closing delimiters, these delimiters are put after the macro
2013 scope. Spacing is suppressed after opening delimiters and before closing
2014 delimiters. For example,
2015 .Aq ( [ word ] ) .
2017 renders as:
2019 ([⟨word⟩]).
2021 Opening delimiters are:
2023 ( left parenthesis
2025 [ left bracket
2026 Closing delimiters are:
2028 . period
2030 , comma
2031 : colon
2032 ; semicolon
2033 ) right parenthesis
2034 ] right bracket
2035 ? question mark
2036 ! exclamation mark
2037 Note that even a period preceded by a backslash (‘\.’) gets this special
2039 handling; use ‘\&.’ to prevent that.
2040 Many in-line macros interrupt their scope when they encounter delimiters,
2042 and resume their scope when more arguments follow that are not delim‐
2043 iters. For example,
2044 .Fl a ( b | c \*(Ba d ) e
2046 renders as:
2048 -a (-b | -c | -d) -e
2050 This applies to both opening and closing delimiters, and also to the mid‐
2052 dle delimiter, which does not suppress spacing:
2053 | vertical bar
2055 As a special case, the predefined string \*(Ba is handled and rendered in
2057 the same way as a plain ‘|’ character. Using this predefined string is
2058 not recommended in new manuals.
2059 Appending a zero-width space (‘\&’) to the end of an input line is also
2061 useful to prevent the interpretation of a trailing period, exclamation or
2062 question mark as the end of a sentence, for example when an abbreviation
2063 happens to occur at the end of a text or macro input line.
2064 Font handling
2066 In mdoc documents, usage of semantic markup is recommended in order to
2067 have proper fonts automatically selected; only when no fitting semantic
2068 markup is available, consider falling back to Physical markup macros.
2069 Whenever any mdoc macro switches the roff(7) font mode, it will automati‐
2070 cally restore the previous font when exiting its scope. Manually switch‐
2071 ing the font using the roff(7) ‘\f’ font escape sequences is never re‐
2072 quired.
2073
2075 This section provides an incomplete list of compatibility issues between
2076 mandoc and GNU troff ("groff").
2077 The following problematic behaviour is found in groff:
2079 - Pa does not format its arguments when used in the FILES section under
2081 certain list types.
2082 - Ta can only be called by other macros, but not at the beginning of a
2083 line.
2084 - ‘\f’ (font face) and ‘\F’ (font family face) Text Decoration escapes
2085 behave irregularly when specified within line-macro scopes.
2086 - Negative scaling units return to prior lines. Instead, mandoc trun‐
2087 cates them to zero.
2088 The following features are unimplemented in mandoc:
2090 - Bd -file file is unsupported for security reasons.
2092 - Bd -filled does not adjust the right margin, but is an alias for Bd
2093 -ragged.
2094 - Bd -literal does not use a literal font, but is an alias for Bd
2095 -unfilled.
2096 - Bd -offset center and -offset right don't work. Groff does not im‐
2097 plement centered and flush-right rendering either, but produces large
2098 indentations.
2099
2101 man(1), mandoc(1), eqn(7), man(7), mandoc_char(7), roff(7), tbl(7)
2102 The web page extended documentation for the mdoc language:
2104 https://mandoc.bsd.lv/mdoc/ provides a few tutorial-style pages for be‐
2105 ginners, an extensive style guide for advanced authors, and an alphabetic
2106 index helping to choose the best macros for various kinds of content.
2107 The manual page groff_mdoc(7): https://man.voidlinux.org/groff_mdoc con‐
2109 tained in the “groff” package documents exactly the same language in a
2110 somewhat different style.
2111
2113 The mdoc language first appeared as a troff macro package in 4.4BSD. It
2114 was later significantly updated by Werner Lemberg and Ruslan Ermilov in
2115 groff-1.17. The standalone implementation that is part of the mandoc(1)
2116 utility written by Kristaps Dzonsons appeared in OpenBSD 4.6.
2117
2119 The mdoc reference was written by Kristaps Dzonsons <kristaps@bsd.lv>.
2120BSD July 29, 2021 BSD