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 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: funcname [argument ...]
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 [display_name]
366 Mt “mailto” hyperlink: localpart@domain
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 No return to roman font (normal) (>0 arguments)
375 Bf, Ef font block: -type | Em | Li | Sy
376 Physical enclosures
378 Dq, Do, Dc enclose in typographic double quotes: “text”
379 Qq, Qo, Qc enclose in typewriter double quotes: "text"
380 Sq, So, Sc enclose in single quotes: ‘text’
381 Pq, Po, Pc enclose in parentheses: (text)
382 Bq, Bo, Bc enclose in square brackets: [text]
383 Brq, Bro, Brc enclose in curly braces: {text}
384 Aq, Ao, Ac enclose in angle brackets: ⟨text⟩
385 Eo, Ec generic enclosure
386 Text production
388 Ex -std standard command exit values: [utility ...]
389 Rv -std standard function return values: [function ...]
390 St reference to a standards document (one argument)
391 At AT&T UNIX
392 Bx BSD
393 Bsx BSD/OS
394 Nx NetBSD
395 Fx FreeBSD
396 Ox OpenBSD
397 Dx DragonFly
398
400 This section is a canonical reference of all macros, arranged alphabeti‐
401 cally. For the scoping of individual macros, see MACRO SYNTAX.
402 %A first_name ... last_name
404 Author name of an Rs block. Multiple authors should each be
405 accorded their own %A line. Author names should be ordered with
406 full or abbreviated forename(s) first, then full surname.
407 %B title
409 Book title of an Rs block. This macro may also be used in a non-
410 bibliographic context when referring to book titles.
411 %C location
413 Publication city or location of an Rs block.
414 %D [month day,] year
416 Publication date of an Rs block. Provide the full English name of
417 the month and all four digits of the year.
418 %I name
420 Publisher or issuer name of an Rs block.
421 %J name
423 Journal name of an Rs block.
424 %N number
426 Issue number (usually for journals) of an Rs block.
427 %O line
429 Optional information of an Rs block.
430 %P number
432 Book or journal page number of an Rs block.
433 %Q name
435 Institutional author (school, government, etc.) of an Rs block.
436 Multiple institutional authors should each be accorded their own %Q
437 line.
438 %R name
440 Technical report name of an Rs block.
441 %T title
443 Article title of an Rs block. This macro may also be used in a non-
444 bibliographical context when referring to article titles.
445 %U protocol://path
447 URI of reference document.
448 %V number
450 Volume number of an Rs block.
451 Ac Close an Ao block. Does not have any tail arguments.
453 Ad address
455 Memory address. Do not use this for postal addresses.
456 Examples:
458 .Ad [0,$]
459 .Ad 0x00000000
460 An -split | -nosplit | first_name ... last_name
462 Author name. Can be used both for the authors of the program, func‐
463 tion, or driver documented in the manual, or for the authors of the
464 manual itself. Requires either the name of an author or one of the
465 following arguments:
466 -split Start a new output line before each subsequent
468 invocation of An.
469 -nosplit The opposite of -split.
470 The default is -nosplit. The effect of selecting either of the
472 -split modes ends at the beginning of the AUTHORS section. In the
473 AUTHORS section, the default is -nosplit for the first author list‐
474 ing and -split for all other author listings.
475 Examples:
477 .An -nosplit
478 .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
479 Ao block
481 Begin a block enclosed by angle brackets. Does not have any head
482 arguments. This macro is almost never useful. See Aq for more
483 details.
484 Ap Inserts an apostrophe without any surrounding whitespace. This is
486 generally used as a grammatical device when referring to the verb
487 form of a function.
488 Examples:
490 .Fn execve Ap d
491 Aq line
493 Enclose the rest of the input line in angle brackets. The only
494 important use case is for email addresses. See Mt for an example.
495 Occasionally, it is used for names of characters and keys, for exam‐
497 ple:
498 Press the
500 .Aq escape
501 key to ...
502 For URIs, use Lk instead, and In for “#include” directives. Never
504 wrap Ar in Aq.
505 Since Aq usually renders with non-ASCII characters in non-ASCII out‐
507 put modes, do not use it where the ASCII characters ‘<’ and ‘>’ are
508 required as syntax elements. Instead, use these characters directly
509 in such cases, combining them with the macros Pf, Ns, or Eo as
510 needed.
511 See also Ao.
513 Ar [placeholder ...]
515 Command arguments. If an argument is not provided, the string “file
516 ...” is used as a default.
517 Examples:
519 .Fl o Ar file
520 .Ar
521 .Ar arg1 , arg2 .
522 The arguments to the Ar macro are names and placeholders for command
524 arguments; for fixed strings to be passed verbatim as arguments, use
525 Fl or Cm.
526 At [version]
528 Formats an AT&T UNIX version. Accepts one optional argument:
529 v[1-7] | 32v A version of AT&T UNIX.
531 III AT&T UNIX III.
532 V | V.[1-4] A version of AT&T System V UNIX.
533 Note that these arguments do not begin with a hyphen.
535 Examples:
537 .At
538 .At III
539 .At V.1
540 See also Bsx, Bx, Dx, Fx, Nx, and Ox.
542 Bc Close a Bo block. Does not have any tail arguments.
544 Bd -type [-offset width] [-compact]
546 Begin a display block. Display blocks are used to select a differ‐
547 ent indentation and justification than the one used by the surround‐
548 ing text. They may contain both macro lines and text lines. By
549 default, a display block is preceded by a vertical space.
550 The type must be one of the following:
552 -centered Produce one output line from each input line,
554 and center-justify each line. Using this dis‐
555 play type is not recommended; many mdoc imple‐
556 mentations render it poorly.
557 -filled Change the positions of line breaks to fill
559 each line, and left- and right-justify the
560 resulting block.
561 -literal Produce one output line from each input line,
563 and do not justify the block at all. Preserve
564 white space as it appears in the input. Always
565 use a constant-width font. Use this for dis‐
566 playing source code.
567 -ragged Change the positions of line breaks to fill
569 each line, and left-justify the resulting
570 block.
571 -unfilled The same as -literal, but using the same font
573 as for normal text, which is a variable width
574 font if supported by the output device.
575 The type must be provided first. Additional arguments may follow:
577 -offset width Indent the display by the width, which may be
579 one of the following:
580 One of the pre-defined strings indent, the
582 width of a standard indentation (six constant
583 width characters); indent-two, twice indent;
584 left, which has no effect; right, which justi‐
585 fies to the right margin; or center, which
586 aligns around an imagined center axis.
587 A macro invocation, which selects a predefined
589 width associated with that macro. The most
590 popular is the imaginary macro Ds, which
591 resolves to 6n.
592 A scaling width as described in roff(7).
594 An arbitrary string, which indents by the
596 length of this string.
597 When the argument is missing, -offset is
599 ignored.
600 -compact Do not assert vertical space before the dis‐
602 play.
603 Examples:
605 .Bd -literal -offset indent -compact
607 Hello world.
608 .Ed
609 See also D1 and Dl.
611 Bf -emphasis | -literal | -symbolic | Em | Li | Sy
613 Change the font mode for a scoped block of text. The -emphasis and
614 Em argument are equivalent, as are -symbolic and Sy, and -literal
615 and Li. Without an argument, this macro does nothing. The font
616 mode continues until broken by a new font mode in a nested scope or
617 Ef is encountered.
618 See also Li, Ef, Em, and Sy.
620 Bk -words
622 For each macro, keep its output together on the same output line,
623 until the end of the macro or the end of the input line is reached,
624 whichever comes first. Line breaks in text lines are unaffected.
625 The -words argument is required; additional arguments are ignored.
627 The following example will not break within each Op macro line:
629 .Bk -words
631 .Op Fl f Ar flags
632 .Op Fl o Ar output
633 .Ek
634 Be careful in using over-long lines within a keep block! Doing so
636 will clobber the right margin.
637 Bl -type [-width val] [-offset val] [-compact] [col ...]
639 Begin a list. Lists consist of items specified using the It macro,
640 containing a head or a body or both.
641 The list type is mandatory and must be specified first. The -width
643 and -offset arguments accept macro names as described for Bd
644 -offset, scaling widths as described in roff(7), or use the length
645 of the given string. The -offset is a global indentation for the
646 whole list, affecting both item heads and bodies. For those list
647 types supporting it, the -width argument requests an additional
648 indentation of item bodies, to be added to the -offset. Unless the
649 -compact argument is specified, list entries are separated by verti‐
650 cal space.
651 A list must specify one of the following list types:
653 -bullet No item heads can be specified, but a bullet
655 will be printed at the head of each item. Item
656 bodies start on the same output line as the bul‐
657 let and are indented according to the -width
658 argument.
659 -column A columnated list. The -width argument has no
661 effect; instead, the string length of each argu‐
662 ment specifies the width of one column. If the
663 first line of the body of a -column list is not
664 an It macro line, It contexts spanning one input
665 line each are implied until an It macro line is
666 encountered, at which point items start being
667 interpreted as described in the It documenta‐
668 tion.
669 -dash Like -bullet, except that dashes are used in
671 place of bullets.
672 -diag Like -inset, except that item heads are not
674 parsed for macro invocations. Most often used
675 in the DIAGNOSTICS section with error constants
676 in the item heads.
677 -enum A numbered list. No item heads can be speci‐
679 fied. Formatted like -bullet, except that car‐
680 dinal numbers are used in place of bullets,
681 starting at 1.
682 -hang Like -tag, except that the first lines of item
684 bodies are not indented, but follow the item
685 heads like in -inset lists.
686 -hyphen Synonym for -dash.
688 -inset Item bodies follow items heads on the same line,
690 using normal inter-word spacing. Bodies are not
691 indented, and the -width argument is ignored.
692 -item No item heads can be specified, and none are
694 printed. Bodies are not indented, and the
695 -width argument is ignored.
696 -ohang Item bodies start on the line following item
698 heads and are not indented. The -width argument
699 is ignored.
700 -tag Item bodies are indented according to the -width
702 argument. When an item head fits inside the
703 indentation, the item body follows this head on
704 the same output line. Otherwise, the body
705 starts on the output line following the head.
706 Lists may be nested within lists and displays. Nesting of -column
708 and -enum lists may not be portable.
709 See also El and It.
711 Bo block
713 Begin a block enclosed by square brackets. Does not have any head
714 arguments.
715 Examples:
717 .Bo 1 ,
718 .Dv BUFSIZ Bc
719 See also Bq.
721 Bq line
723 Encloses its arguments in square brackets.
724 Examples:
726 .Bq 1, Dv BUFSIZ
727 Remarks: this macro is sometimes abused to emulate optional argu‐
729 ments for commands; the correct macros to use for this purpose are
730 Op, Oo, and Oc.
731 See also Bo.
733 Brc Close a Bro block. Does not have any tail arguments.
735 Bro block
737 Begin a block enclosed by curly braces. Does not have any head
738 arguments.
739 Examples:
741 .Bro 1 , ... ,
742 .Va n Brc
743 See also Brq.
745 Brq line
747 Encloses its arguments in curly braces.
748 Examples:
750 .Brq 1, ..., Va n
751 See also Bro.
753 Bsx [version]
755 Format the BSD/OS version provided as an argument, or a default
756 value if no argument is provided.
757 Examples:
759 .Bsx 1.0
760 .Bsx
761 See also At, Bx, Dx, Fx, Nx, and Ox.
763 Bt Supported only for compatibility, do not use this in new manuals.
765 Prints “is currently in beta test.”
766 Bx [version [variant]]
768 Format the BSD version provided as an argument, or a default value
769 if no argument is provided.
770 Examples:
772 .Bx 4.3 Tahoe
773 .Bx 4.4
774 .Bx
775 See also At, Bsx, Dx, Fx, Nx, and Ox.
777 Cd line
779 Kernel configuration declaration. This denotes strings accepted by
780 config(8). It is most often used in section 4 manual pages.
781 Examples:
783 .Cd device le0 at scode?
784 Remarks: this macro is commonly abused by using quoted literals to
786 retain whitespace and align consecutive Cd declarations. This prac‐
787 tise is discouraged.
788 Cm keyword ...
790 Command modifiers. Typically used for fixed strings passed as argu‐
791 ments, unless Fl is more appropriate. Also useful when specifying
792 configuration options or keys.
793 Examples:
795 .Nm mt Fl f Ar device Cm rewind
796 .Nm ps Fl o Cm pid , Ns Cm command
797 .Nm dd Cm if= Ns Ar file1 Cm of= Ns Ar file2
798 .Cm IdentityFile Pa ~/.ssh/id_rsa
799 .Cm LogLevel Dv DEBUG
800 D1 line
802 One-line indented display. This is formatted by the default rules
803 and is useful for simple indented statements. It is followed by a
804 newline.
805 Examples:
807 .D1 Fl abcdefgh
808 See also Bd and Dl.
810 Db This macro is obsolete. No replacement is needed. It is ignored by
812 mandoc(1) and groff including its arguments. It was formerly used
813 to toggle a debugging mode.
814 Dc Close a Do block. Does not have any tail arguments.
816 Dd $Mdocdate$ | month day, year
818 Document date for display in the page footer. This is the mandatory
819 first macro of any mdoc manual.
820 The month is the full English month name, the day is an integer num‐
822 ber, and the year is the full four-digit year.
823 Other arguments are not portable; the mandoc(1) utility handles them
825 as follows:
826 - To have the date automatically filled in by the OpenBSD ver‐
827 sion of cvs(1), the special string “$Mdocdate$” can be given
828 as an argument.
829 - The traditional, purely numeric man(7) format year–month–day
830 is accepted, too.
831 - If a date string cannot be parsed, it is used verbatim.
832 - If no date string is given, the current date is used.
833 Examples:
835 .Dd $Mdocdate$
836 .Dd $Mdocdate: July 2 2018$
837 .Dd July 2, 2018
838 See also Dt and Os.
840 Dl line
842 One-line indented display. This is formatted as literal text and is
843 useful for commands and invocations. It is followed by a newline.
844 Examples:
846 .Dl % mandoc mdoc.7 \(ba less
847 See also Ql, Bd -literal, and D1.
849 Do block
851 Begin a block enclosed by double quotes. Does not have any head
852 arguments.
853 Examples:
855 .Do
856 April is the cruellest month
857 .Dc
858 \(em T.S. Eliot
859 See also Dq.
861 Dq line
863 Encloses its arguments in “typographic” double-quotes.
864 Examples:
866 .Dq April is the cruellest month
867 \(em T.S. Eliot
868 See also Qq, Sq, and Do.
870 Dt TITLE section [arch]
872 Document title for display in the page header. This is the manda‐
873 tory second macro of any mdoc file.
874 Its arguments are as follows:
876 TITLE The document's title (name), defaulting to “UNTITLED” if
878 unspecified. To achieve a uniform appearance of page
879 header lines, it should by convention be all caps.
880 section The manual section. This may be one of 1 (General
882 Commands), 2 (System Calls), 3 (Library Functions), 3p
883 (Perl Library), 4 (Device Drivers), 5 (File Formats), 6
884 (Games), 7 (Miscellaneous Information), 8 (System
885 Manager's Manual), or 9 (Kernel Developer's Manual). It
886 should correspond to the manual's filename suffix and
887 defaults to the empty string if unspecified.
888 arch This specifies the machine architecture a manual page
890 applies to, where relevant, for example alpha, amd64,
891 i386, or sparc64. The list of valid architectures varies
892 by operating system.
893 Examples:
895 .Dt FOO 1
896 .Dt FOO 9 i386
897 See also Dd and Os.
899 Dv identifier ...
901 Defined variables such as preprocessor constants, constant symbols,
902 enumeration values, and so on.
903 Examples:
905 .Dv NULL
906 .Dv BUFSIZ
907 .Dv STDOUT_FILENO
908 See also Er and Ev for special-purpose constants, Va for variable
910 symbols, and Fd for listing preprocessor variable definitions in the
911 SYNOPSIS.
912 Dx [version]
914 Format the DragonFly version provided as an argument, or a default
915 value if no argument is provided.
916 Examples:
918 .Dx 2.4.1
919 .Dx
920 See also At, Bsx, Bx, Fx, Nx, and Ox.
922 Ec [closing_delimiter]
924 Close a scope started by Eo.
925 The closing_delimiter argument is used as the enclosure tail, for
927 example, specifying \(rq will emulate Dc.
928 Ed End a display context started by Bd.
930 Ef End a font mode context started by Bf.
932 Ek End a keep context started by Bk.
934 El End a list context started by Bl. See also It.
936 Em word ...
938 Request an italic font. If the output device does not provide that,
939 underline.
940 This is most often used for stress emphasis (not to be confused with
942 importance, see Sy). In the rare cases where none of the semantic
943 markup macros fit, it can also be used for technical terms and
944 placeholders, except that for syntax elements, Sy and Ar are pre‐
945 ferred, respectively.
946 Examples:
948 Selected lines are those
949 .Em not
950 matching any of the specified patterns.
951 Some of the functions use a
952 .Em hold space
953 to save the pattern space for subsequent retrieval.
954 See also No, Ql, and Sy.
956 En word ...
958 This macro is obsolete. Use Eo or any of the other enclosure
959 macros.
960 It encloses its argument in the delimiters specified by the last Es
962 macro.
963 Eo [opening_delimiter]
965 An arbitrary enclosure. The opening_delimiter argument is used as
966 the enclosure head, for example, specifying \(lq will emulate Do.
967 Er identifier ...
969 Error constants for definitions of the errno libc global variable.
970 This is most often used in section 2 and 3 manual pages.
971 Examples:
973 .Er EPERM
974 .Er ENOENT
975 See also Dv for general constants.
977 Es opening_delimiter closing_delimiter
979 This macro is obsolete. Use Eo or any of the other enclosure
980 macros.
981 It takes two arguments, defining the delimiters to be used by subse‐
983 quent En macros.
984 Ev identifier ...
986 Environmental variables such as those specified in environ(7).
987 Examples:
989 .Ev DISPLAY
990 .Ev PATH
991 See also Dv for general constants.
993 Ex -std [utility ...]
995 Insert a standard sentence regarding command exit values of 0 on
996 success and >0 on failure. This is most often used in section 1, 6,
997 and 8 manual pages.
998 If utility is not specified, the document's name set by Nm is used.
1000 Multiple utility arguments are treated as separate utilities.
1001 See also Rv.
1003 Fa argument ...
1005 Function argument or parameter. Each argument may be a name and a
1006 type (recommended for the SYNOPSIS section), a name alone (for func‐
1007 tion invocations), or a type alone (for function prototypes). If
1008 both a type and a name are given or if the type consists of multiple
1009 words, all words belonging to the same function argument have to be
1010 given in a single argument to the Fa macro.
1011 This macro is also used to specify the field name of a structure.
1013 Most often, the Fa macro is used in the SYNOPSIS within Fo blocks
1015 when documenting multi-line function prototypes. If invoked with
1016 multiple arguments, the arguments are separated by a comma. Fur‐
1017 thermore, if the following macro is another Fa, the last argument
1018 will also have a trailing comma.
1019 Examples:
1021 .Fa "const char *p"
1022 .Fa "int a" "int b" "int c"
1023 .Fa "char *" size_t
1024 See also Fo.
1026 Fc End a function context started by Fo.
1028 Fd #directive [argument ...]
1030 Preprocessor directive, in particular for listing it in the
1031 SYNOPSIS. Historically, it was also used to document include files.
1032 The latter usage has been deprecated in favour of In.
1033 Examples:
1035 .Fd #define sa_handler __sigaction_u.__sa_handler
1036 .Fd #define SIO_MAXNFDS
1037 .Fd #ifdef FS_DEBUG
1038 .Ft void
1039 .Fn dbg_open "const char *"
1040 .Fd #endif
1041 See also MANUAL STRUCTURE, In, and Dv.
1043 Fl [word ...]
1045 Command-line flag or option. Used when listing arguments to com‐
1046 mand-line utilities. Prints a fixed-width hyphen ‘-’ directly fol‐
1047 lowed by each argument. If no arguments are provided, a hyphen is
1048 printed followed by a space. If the argument is a macro, a hyphen
1049 is prefixed to the subsequent macro output.
1050 Examples:
1052 .Fl R Op Fl H | L | P
1053 .Op Fl 1AaCcdFfgHhikLlmnopqRrSsTtux
1054 .Fl type Cm d Fl name Pa CVS
1055 .Fl Ar signal_number
1056 .Fl o Fl
1057 See also Cm.
1059 Fn funcname [argument ...]
1061 A function name.
1062 Function arguments are surrounded in parenthesis and are delimited
1064 by commas. If no arguments are specified, blank parenthesis are
1065 output. In the SYNOPSIS section, this macro starts a new output
1066 line, and a blank line is automatically inserted between function
1067 definitions.
1068 Examples:
1070 .Fn "int funcname" "int arg0" "int arg1"
1071 .Fn funcname "int arg0"
1072 .Fn funcname arg0
1073 .Ft functype
1075 .Fn funcname
1076 When referring to a function documented in another manual page, use
1078 Xr instead. See also MANUAL STRUCTURE, Fo, and Ft.
1079 Fo funcname
1081 Begin a function block. This is a multi-line version of Fn.
1082 Invocations usually occur in the following context:
1084 .Ft functype
1086 .Fo funcname
1087 .Fa "argtype argname"
1088 ...
1089 .Fc
1090 A Fo scope is closed by Fc.
1092 See also MANUAL STRUCTURE, Fa, Fc, and Ft.
1094 Fr number
1096 This macro is obsolete. No replacement markup is needed.
1097 It was used to show numerical function return values in an italic
1099 font.
1100 Ft functype
1102 A function type.
1103 In the SYNOPSIS section, a new output line is started after this
1105 macro.
1106 Examples:
1108 .Ft int
1109 .Ft functype
1110 .Fn funcname
1111 See also MANUAL STRUCTURE, Fn, and Fo.
1113 Fx [version]
1115 Format the FreeBSD version provided as an argument, or a default
1116 value if no argument is provided.
1117 Examples:
1119 .Fx 7.1
1120 .Fx
1121 See also At, Bsx, Bx, Dx, Nx, and Ox.
1123 Hf filename
1125 This macro is not implemented in mandoc(1). It was used to include
1126 the contents of a (header) file literally.
1127 Ic keyword ...
1129 Designate an internal or interactive command. This is similar to Cm
1130 but used for instructions rather than values.
1131 Examples:
1133 .Ic :wq
1134 .Ic hash
1135 .Ic alias
1136 Note that using Ql, Dl, or Bd -literal is preferred for displaying
1138 code samples; the Ic macro is used when referring to an individual
1139 command name.
1140 In filename
1142 The name of an include file. This macro is most often used in sec‐
1143 tion 2, 3, and 9 manual pages.
1144 When invoked as the first macro on an input line in the SYNOPSIS
1146 section, the argument is displayed in angle brackets and preceded by
1147 "#include", and a blank line is inserted in front if there is a pre‐
1148 ceding function declaration. In other sections, it only encloses
1149 its argument in angle brackets and causes no line break.
1150 Examples:
1152 .In sys/types.h
1153 See also MANUAL STRUCTURE.
1155 It [head]
1157 A list item. The syntax of this macro depends on the list type.
1158 Lists of type -hang, -ohang, -inset, and -diag have the following
1160 syntax:
1161 .It args
1163 Lists of type -bullet, -dash, -enum, -hyphen and -item have the fol‐
1165 lowing syntax:
1166 .It
1168 with subsequent lines interpreted within the scope of the It until
1170 either a closing El or another It.
1171 The -tag list has the following syntax:
1173 .It [args]
1175 Subsequent lines are interpreted as with -bullet and family. The
1177 line arguments correspond to the list's left-hand side; body argu‐
1178 ments correspond to the list's contents.
1179 The -column list is the most complicated. Its syntax is as follows:
1181 .It cell [Ta cell ...]
1183 .It cell [<TAB> cell ...]
1184 The arguments consist of one or more lines of text and macros repre‐
1186 senting a complete table line. Cells within the line are delimited
1187 by the special Ta block macro or by literal tab characters.
1188 Using literal tabs is strongly discouraged because they are very
1190 hard to use correctly and mdoc code using them is very hard to read.
1191 In particular, a blank character is syntactically significant before
1192 and after the literal tab character. If a word precedes or follows
1193 the tab without an intervening blank, that word is never interpreted
1194 as a macro call, but always output literally.
1195 The tab cell delimiter may only be used within the It line itself;
1197 on following lines, only the Ta macro can be used to delimit cells,
1198 and portability requires that Ta is called by other macros: some
1199 parsers do not recognize it when it appears as the first macro on a
1200 line.
1201 Note that quoted strings may span tab-delimited cells on an It line.
1203 For example,
1204 .It "col1 , <TAB> col2 ," ;
1206 will preserve the whitespace before both commas, but not the white‐
1208 space before the semicolon.
1209 See also Bl.
1211 Lb libname
1213 Specify a library.
1214 The name parameter may be a system library, such as z or pam, in
1216 which case a small library description is printed next to the linker
1217 invocation; or a custom library, in which case the library name is
1218 printed in quotes. This is most commonly used in the SYNOPSIS sec‐
1219 tion as described in MANUAL STRUCTURE.
1220 Examples:
1222 .Lb libz
1223 .Lb libmandoc
1224 Li word ...
1226 Request a typewriter (literal) font. Deprecated because on terminal
1227 output devices, this is usually indistinguishable from normal text.
1228 For literal displays, use Ql (in-line), Dl (single line), or Bd
1229 -literal (multi-line) instead.
1230 Lk uri [display_name]
1232 Format a hyperlink.
1233 Examples:
1235 .Lk http://bsd.lv "The BSD.lv Project"
1236 .Lk http://bsd.lv
1237 See also Mt.
1239 Lp Deprecated synonym for Pp.
1241 Ms name
1243 Display a mathematical symbol.
1244 Examples:
1246 .Ms sigma
1247 .Ms aleph
1248 Mt localpart@domain
1250 Format a “mailto:” hyperlink.
1251 Examples:
1253 .Mt discuss@manpages.bsd.lv
1254 .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv
1255 Nd line
1257 A one line description of the manual's content. This is the manda‐
1258 tory last macro of the NAME section and not appropriate for other
1259 sections.
1260 Examples:
1262 .Nd mdoc language reference
1263 .Nd format and display UNIX manuals
1264 The Nd macro technically accepts child macros and terminates with a
1266 subsequent Sh invocation. Do not assume this behaviour: some
1267 whatis(1) database generators are not smart enough to parse more
1268 than the line arguments and will display macros verbatim.
1269 See also Nm.
1271 Nm [name]
1273 The name of the manual page, or — in particular in section 1, 6, and
1274 8 pages — of an additional command or feature documented in the man‐
1275 ual page. When first invoked, the Nm macro expects a single argu‐
1276 ment, the name of the manual page. Usually, the first invocation
1277 happens in the NAME section of the page. The specified name will be
1278 remembered and used whenever the macro is called again without argu‐
1279 ments later in the page. The Nm macro uses Block full-implicit
1280 semantics when invoked as the first macro on an input line in the
1281 SYNOPSIS section; otherwise, it uses ordinary In-line semantics.
1282 Examples:
1284 .Sh SYNOPSIS
1286 .Nm cat
1287 .Op Fl benstuv
1288 .Op Ar
1289 In the SYNOPSIS of section 2, 3 and 9 manual pages, use the Fn macro
1291 rather than Nm to mark up the name of the manual page.
1292 No word ...
1294 Normal text. Closes the scope of any preceding in-line macro. When
1295 used after physical formatting macros like Em or Sy, switches back
1296 to the standard font face and weight. Can also be used to embed
1297 plain text strings in macro lines using semantic annotation macros.
1298 Examples:
1300 .Em italic , Sy bold , No and roman
1301 .Sm off
1303 .Cm :C No / Ar pattern No / Ar replacement No /
1304 .Sm on
1305 See also Em, Ql, and Sy.
1307 Ns Suppress a space between the output of the preceding macro and the
1309 following text or macro. Following invocation, input is interpreted
1310 as normal text just like after an No macro.
1311 This has no effect when invoked at the start of a macro line.
1313 Examples:
1315 .Ar name Ns = Ns Ar value
1316 .Cm :M Ns Ar pattern
1317 .Fl o Ns Ar output
1318 See also No and Sm.
1320 Nx [version]
1322 Format the NetBSD version provided as an argument, or a default
1323 value if no argument is provided.
1324 Examples:
1326 .Nx 5.01
1327 .Nx
1328 See also At, Bsx, Bx, Dx, Fx, and Ox.
1330 Oc Close multi-line Oo context.
1332 Oo block
1334 Multi-line version of Op.
1335 Examples:
1337 .Oo
1338 .Op Fl flag Ns Ar value
1339 .Oc
1340 Op line
1342 Optional part of a command line. Prints the argument(s) in brack‐
1343 ets. This is most often used in the SYNOPSIS section of section 1
1344 and 8 manual pages.
1345 Examples:
1347 .Op Fl a Ar b
1348 .Op Ar a | b
1349 See also Oo.
1351 Os [system [version]]
1353 Operating system version for display in the page footer. This is
1354 the mandatory third macro of any mdoc file.
1355 The optional system parameter specifies the relevant operating sys‐
1357 tem or environment. It is suggested to leave it unspecified, in
1358 which case mandoc(1) uses its -Ios argument or, if that isn't speci‐
1359 fied either, sysname and release as returned by uname(3).
1360 Examples:
1362 .Os
1363 .Os KTH/CSC/TCS
1364 .Os BSD 4.3
1365 See also Dd and Dt.
1367 Ot functype
1369 This macro is obsolete. Use Ft instead; with mandoc(1), both have
1370 the same effect.
1371 Historical mdoc packages described it as “old function type
1373 (FORTRAN)”.
1374 Ox [version]
1376 Format the OpenBSD version provided as an argument, or a default
1377 value if no argument is provided.
1378 Examples:
1380 .Ox 4.5
1381 .Ox
1382 See also At, Bsx, Bx, Dx, Fx, and Nx.
1384 Pa name ...
1386 An absolute or relative file system path, or a file or directory
1387 name. If an argument is not provided, the character ‘~’ is used as
1388 a default.
1389 Examples:
1391 .Pa /usr/bin/mandoc
1392 .Pa /usr/share/man/man7/mdoc.7
1393 See also Lk.
1395 Pc Close parenthesised context opened by Po.
1397 Pf prefix macro [argument ...]
1399 Removes the space between its argument and the following macro. It
1400 is equivalent to:
1401 No \&prefix Ns macro [argument ...]
1403 The prefix argument is not parsed for macro names or delimiters, but
1405 used verbatim as if it were escaped.
1406 Examples:
1408 .Pf $ Ar variable_name
1409 .Pf . Ar macro_name
1410 .Pf 0x Ar hex_digits
1411 See also Ns and Sm.
1413 Po block
1415 Multi-line version of Pq.
1416 Pp Break a paragraph. This will assert vertical space between prior
1418 and subsequent macros and/or text.
1419 Paragraph breaks are not needed before or after Sh or Ss macros or
1421 before displays (Bd line) or lists (Bl) unless the -compact flag is
1422 given.
1423 Pq line
1425 Parenthesised enclosure.
1426 See also Po.
1428 Qc Close quoted context opened by Qo.
1430 Ql line
1432 In-line literal display. This can be used for complete command
1433 invocations and for multi-word code examples when an indented dis‐
1434 play is not desired.
1435 See also Dl and Bd -literal.
1437 Qo block
1439 Multi-line version of Qq.
1440 Qq line
1442 Encloses its arguments in "typewriter" double-quotes. Consider
1443 using Dq.
1444 See also Dq, Sq, and Qo.
1446 Re Close an Rs block. Does not have any tail arguments.
1448 Rs Begin a bibliographic (“reference”) block. Does not have any head
1450 arguments. The block macro may only contain %A, %B, %C, %D, %I, %J,
1451 %N, %O, %P, %Q, %R, %T, %U, and %V child macros (at least one must
1452 be specified).
1453 Examples:
1455 .Rs
1456 .%A J. E. Hopcroft
1457 .%A J. D. Ullman
1458 .%B Introduction to Automata Theory, Languages, and Computation
1459 .%I Addison-Wesley
1460 .%C Reading, Massachusetts
1461 .%D 1979
1462 .Re
1463 If an Rs block is used within a SEE ALSO section, a vertical space
1465 is asserted before the rendered output, else the block continues on
1466 the current line.
1467 Rv -std [function ...]
1469 Insert a standard sentence regarding a function call's return value
1470 of 0 on success and -1 on error, with the errno libc global variable
1471 set on error.
1472 If function is not specified, the document's name set by Nm is used.
1474 Multiple function arguments are treated as separate functions.
1475 See also Ex.
1477 Sc Close single-quoted context opened by So.
1479 Sh TITLE LINE
1481 Begin a new section. For a list of conventional manual sections,
1482 see MANUAL STRUCTURE. These sections should be used unless it's
1483 absolutely necessary that custom sections be used.
1484 Section names should be unique so that they may be keyed by Sx.
1486 Although this macro is parsed, it should not consist of child node
1487 or it may not be linked with Sx.
1488 See also Pp, Ss, and Sx.
1490 Sm [on | off]
1492 Switches the spacing mode for output generated from macros.
1493 By default, spacing is on. When switched off, no white space is
1495 inserted between macro arguments and between the output generated
1496 from adjacent macros, but text lines still get normal spacing
1497 between words and sentences.
1498 When called without an argument, the Sm macro toggles the spacing
1500 mode. Using this is not recommended because it makes the code
1501 harder to read.
1502 So block
1504 Multi-line version of Sq.
1505 Sq line
1507 Encloses its arguments in ‘typewriter’ single-quotes.
1508 See also Dq, Qq, and So.
1510 Ss Title line
1512 Begin a new subsection. Unlike with Sh, there is no convention for
1513 the naming of subsections. Except DESCRIPTION, the conventional
1514 sections described in MANUAL STRUCTURE rarely have subsections.
1515 Sub-section names should be unique so that they may be keyed by Sx.
1517 Although this macro is parsed, it should not consist of child node
1518 or it may not be linked with Sx.
1519 See also Pp, Sh, and Sx.
1521 St -abbreviation
1523 Replace an abbreviation for a standard with the full form. The fol‐
1524 lowing standards are recognised. Where multiple lines are given
1525 without a blank line in between, they all refer to the same stan‐
1526 dard, and using the first form is recommended.
1527 C language standards
1529 -ansiC ANSI X3.159-1989 (“ANSI C89”)
1531 -ansiC-89 ANSI X3.159-1989 (“ANSI C89”)
1532 -isoC ISO/IEC 9899:1990 (“ISO C90”)
1533 -isoC-90 ISO/IEC 9899:1990 (“ISO C90”)
1534 The original C standard.
1535 -isoC-amd1 ISO/IEC 9899/AMD1:1995 (“ISO C90, Amendment 1”)
1537 -isoC-tcor1 ISO/IEC 9899/TCOR1:1994 (“ISO C90, Technical
1539 Corrigendum 1”)
1540 -isoC-tcor2 ISO/IEC 9899/TCOR2:1995 (“ISO C90, Technical
1542 Corrigendum 2”)
1543 -isoC-99 ISO/IEC 9899:1999 (“ISO C99”)
1545 The second major version of the C language stan‐
1546 dard.
1547 -isoC-2011 ISO/IEC 9899:2011 (“ISO C11”)
1549 The third major version of the C language stan‐
1550 dard.
1551 POSIX.1 before the Single UNIX Specification
1553 -p1003.1-88 IEEE Std 1003.1-1988 (“POSIX.1”)
1555 -p1003.1 IEEE Std 1003.1 (“POSIX.1”)
1556 The original POSIX standard, based on ANSI C.
1557 -p1003.1-90 ISO/IEC 9945-1:1990 (“POSIX.1”)
1559 -iso9945-1-90 ISO/IEC 9945-1:1990 (“POSIX.1”)
1560 The first update of POSIX.1.
1561 -p1003.1b-93 IEEE Std 1003.1b-1993 (“POSIX.1”)
1563 -p1003.1b IEEE Std 1003.1b (“POSIX.1”)
1564 Real-time extensions.
1565 -p1003.1c-95 IEEE Std 1003.1c-1995 (“POSIX.1”)
1567 POSIX thread interfaces.
1568 -p1003.1i-95 IEEE Std 1003.1i-1995 (“POSIX.1”)
1570 Technical Corrigendum.
1571 -p1003.1-96 ISO/IEC 9945-1:1996 (“POSIX.1”)
1573 -iso9945-1-96 ISO/IEC 9945-1:1996 (“POSIX.1”)
1574 Includes POSIX.1-1990, 1b, 1c, and 1i.
1575 X/Open Portability Guide version 4 and related standards
1577 -xpg3 X/Open Portability Guide Issue 3 (“XPG3”)
1579 An XPG4 precursor, published in 1989.
1580 -p1003.2 IEEE Std 1003.2 (“POSIX.2”)
1582 -p1003.2-92 IEEE Std 1003.2-1992 (“POSIX.2”)
1583 -iso9945-2-93 ISO/IEC 9945-2:1993 (“POSIX.2”)
1584 An XCU4 precursor.
1585 -p1003.2a-92 IEEE Std 1003.2a-1992 (“POSIX.2”)
1587 Updates to POSIX.2.
1588 -xpg4 X/Open Portability Guide Issue 4 (“XPG4”)
1590 Based on POSIX.1 and POSIX.2, published in 1992.
1591 Single UNIX Specification version 1 and related standards
1593 -susv1
1595 -xpg4.2 X/Open Portability Guide Issue 4, Version 2
1596 (“XPG4.2”)
1597 This standard was published in 1994. It was used
1598 as the basis for UNIX 95 certification. The fol‐
1599 lowing three refer to parts of it.
1600 -xsh4.2
1602 -xcurses4.2 X/Open Curses Issue 4, Version 2 (“XCURSES4.2”)
1604 -p1003.1g-2000 IEEE Std 1003.1g-2000 (“POSIX.1”)
1606 Networking APIs, including sockets.
1607 -svid4 System V Interface Definition, Fourth Edition
1609 (“SVID4”),
1610 Published in 1995.
1611 Single UNIX Specification version 2 and related standards
1613 -susv2 Version 2 of the Single UNIX Specification
1615 (“SUSv2”) This Standard was published in 1997 and
1616 is also called X/Open Portability Guide version
1617 5. It was used as the basis for UNIX 98 certifi‐
1618 cation. The following refer to parts of it.
1619 -xbd5 X/Open Base Definitions Issue 5 (“XBD5”)
1621 -xsh5 X/Open System Interfaces and Headers Issue 5
1623 (“XSH5”)
1624 -xcu5 X/Open Commands and Utilities Issue 5 (“XCU5”)
1626 -xns5 X/Open Networking Services Issue 5 (“XNS5”)
1628 -xns5.2 X/Open Networking Services Issue 5.2 (“XNS5.2”)
1629 Single UNIX Specification version 3
1631 -p1003.1-2001 IEEE Std 1003.1-2001 (“POSIX.1”)
1633 -susv3 Version 3 of the Single UNIX Specification
1634 (“SUSv3”)
1635 This standard is based on C99, SUSv2,
1636 POSIX.1-1996, 1d, and 1j. It is also called
1637 X/Open Portability Guide version 6. It is used as
1638 the basis for UNIX 03 certification.
1639 -p1003.1-2004 IEEE Std 1003.1-2004 (“POSIX.1”)
1641 The second and last Technical Corrigendum.
1642 Single UNIX Specification version 4
1644 -p1003.1-2008 IEEE Std 1003.1-2008 (“POSIX.1”)
1646 -susv4
1647 This standard is also called X/Open Portability
1648 Guide version 7.
1649 Other standards
1651 -ieee754 IEEE Std 754-1985
1653 Floating-point arithmetic.
1654 -iso8601
1656 Representation of dates and times, published in
1657 1988.
1658 -iso8802-3 ISO/IEC 8802-3:1989
1660 Ethernet local area networks.
1661 -ieee1275-94 IEEE Std 1275-1994 (“Open Firmware”)
1663 Sx Title line
1665 Reference a section or subsection in the same manual page. The ref‐
1666 erenced section or subsection name must be identical to the enclosed
1667 argument, including whitespace.
1668 Examples:
1670 .Sx MANUAL STRUCTURE
1671 See also Sh and Ss.
1673 Sy word ...
1675 Request a boldface font.
1676 This is most often used to indicate importance or seriousness (not
1678 to be confused with stress emphasis, see Em). When none of the
1679 semantic macros fit, it is also adequate for syntax elements that
1680 have to be given or that appear verbatim.
1681 Examples:
1683 .Sy Warning :
1684 If
1685 .Sy s
1686 appears in the owner permissions, set-user-ID mode is set.
1687 This utility replaces the former
1688 .Sy dumpdir
1689 program.
1690 See also Em, No, and Ql.
1692 Ta Table cell separator in Bl -column lists; can only be used below It.
1694 Tn word ...
1696 Supported only for compatibility, do not use this in new manuals.
1697 Even though the macro name (“tradename”) suggests a semantic func‐
1698 tion, historic usage is inconsistent, mostly using it as a presenta‐
1699 tion-level macro to request a small caps font.
1700 Ud Supported only for compatibility, do not use this in new manuals.
1702 Prints out “currently under development.”
1703 Ux Supported only for compatibility, do not use this in new manuals.
1705 Prints out “UNIX”.
1706 Va [type] identifier ...
1708 A variable name.
1709 Examples:
1711 .Va foo
1712 .Va const char *bar;
1713 For function arguments and parameters, use Fa instead. For declara‐
1715 tions of global variables in the SYNOPSIS section, use Vt.
1716 Vt type [identifier]
1718 A variable type.
1719 This is also used for indicating global variables in the SYNOPSIS
1721 section, in which case a variable name is also specified. Note that
1722 it accepts Block partial-implicit syntax when invoked as the first
1723 macro on an input line in the SYNOPSIS section, else it accepts
1724 ordinary In-line syntax. In the former case, this macro starts a
1725 new output line, and a blank line is inserted in front if there is a
1726 preceding function definition or include directive.
1727 Examples:
1729 .Vt unsigned char
1730 .Vt extern const char * const sys_signame[] ;
1731 For parameters in function prototypes, use Fa instead, for function
1733 return types Ft, and for variable names outside the SYNOPSIS section
1734 Va, even when including a type with the name. See also MANUAL
1735 STRUCTURE.
1736 Xc Close a scope opened by Xo.
1738 Xo block
1740 Extend the header of an It macro or the body of a partial-implicit
1741 block macro beyond the end of the input line. This macro originally
1742 existed to work around the 9-argument limit of historic roff(7).
1743 Xr name section
1745 Link to another manual ("cross-reference").
1746 Cross reference the name and section number of another man page.
1748 Examples:
1750 .Xr mandoc 1
1751 .Xr mandoc 1 ;
1752 .Xr mandoc 1 Ns s behaviour
1753
1755 The syntax of a macro depends on its classification. In this section,
1756 ‘-arg’ refers to macro arguments, which may be followed by zero or more
1757 ‘parm’ parameters; ‘Yo’ opens the scope of a macro; and if specified,
1758 ‘Yc’ closes it out.
1759 The Callable column indicates that the macro may also be called by pass‐
1761 ing its name as an argument to another macro. For example, ‘.Op Fl O Ar
1762 file’ produces ‘[-O file]’. To prevent a macro call and render the macro
1763 name literally, escape it by prepending a zero-width space, ‘\&’. For
1764 example, ‘Op \&Fl O’ produces ‘[Fl O]’. If a macro is not callable but
1765 its name appears as an argument to another macro, it is interpreted as
1766 opaque text. For example, ‘.Fl Sh’ produces ‘-Sh’.
1767 The Parsed column indicates whether the macro may call other macros by
1769 receiving their names as arguments. If a macro is not parsed but the
1770 name of another macro appears as an argument, it is interpreted as opaque
1771 text.
1772 The Scope column, if applicable, describes closure rules.
1774 Block full-explicit
1776 Multi-line scope closed by an explicit closing macro. All macros con‐
1777 tains bodies; only Bf and (optionally) Bl contain a head.
1778 .Yo [-arg [parm...]] [head...]
1780 [body...]
1781 .Yc
1782 Macro Callable Parsed Scope
1784 Bd No No closed by Ed
1785 Bf No No closed by Ef
1786 Bk No No closed by Ek
1787 Bl No No closed by El
1788 Ed No No opened by Bd
1789 Ef No No opened by Bf
1790 Ek No No opened by Bk
1791 El No No opened by Bl
1792 Block full-implicit
1794 Multi-line scope closed by end-of-file or implicitly by another macro.
1795 All macros have bodies; some (It -bullet, -hyphen, -dash, -enum, -item)
1796 don't have heads; only one (It in Bl -column) has multiple heads.
1797 .Yo [-arg [parm...]] [head... [Ta head...]]
1799 [body...]
1800 Macro Callable Parsed Scope
1802 It No Yes closed by It, El
1803 Nd No No closed by Sh
1804 Nm No Yes closed by Nm, Sh, Ss
1805 Sh No Yes closed by Sh
1806 Ss No Yes closed by Sh, Ss
1807 Note that the Nm macro is a Block full-implicit macro only when invoked
1809 as the first macro in a SYNOPSIS section line, else it is In-line.
1810 Block partial-explicit
1812 Like block full-explicit, but also with single-line scope. Each has at
1813 least a body and, in limited circumstances, a head (Fo, Eo) and/or tail
1814 (Ec).
1815 .Yo [-arg [parm...]] [head...]
1817 [body...]
1818 .Yc [tail...]
1819 .Yo [-arg [parm...]] [head...] [body...] Yc [tail...]
1821 Macro Callable Parsed Scope
1823 Ac Yes Yes opened by Ao
1824 Ao Yes Yes closed by Ac
1825 Bc Yes Yes closed by Bo
1826 Bo Yes Yes opened by Bc
1827 Brc Yes Yes opened by Bro
1828 Bro Yes Yes closed by Brc
1829 Dc Yes Yes opened by Do
1830 Do Yes Yes closed by Dc
1831 Ec Yes Yes opened by Eo
1832 Eo Yes Yes closed by Ec
1833 Fc Yes Yes opened by Fo
1834 Fo No No closed by Fc
1835 Oc Yes Yes closed by Oo
1836 Oo Yes Yes opened by Oc
1837 Pc Yes Yes closed by Po
1838 Po Yes Yes opened by Pc
1839 Qc Yes Yes opened by Oo
1840 Qo Yes Yes closed by Oc
1841 Re No No opened by Rs
1842 Rs No No closed by Re
1843 Sc Yes Yes opened by So
1844 So Yes Yes closed by Sc
1845 Xc Yes Yes opened by Xo
1846 Xo Yes Yes closed by Xc
1847 Block partial-implicit
1849 Like block full-implicit, but with single-line scope closed by the end of
1850 the line.
1851 .Yo [-arg [val...]] [body...] [res...]
1853 Macro Callable Parsed
1855 Aq Yes Yes
1856 Bq Yes Yes
1857 Brq Yes Yes
1858 D1 No Yes
1859 Dl No Yes
1860 Dq Yes Yes
1861 En Yes Yes
1862 Op Yes Yes
1863 Pq Yes Yes
1864 Ql Yes Yes
1865 Qq Yes Yes
1866 Sq Yes Yes
1867 Vt Yes Yes
1868 Note that the Vt macro is a Block partial-implicit only when invoked as
1870 the first macro in a SYNOPSIS section line, else it is In-line.
1871 Special block macro
1873 The Ta macro can only be used below It in Bl -column lists. It delimits
1874 blocks representing table cells; these blocks have bodies, but no heads.
1875 Macro Callable Parsed Scope
1877 Ta Yes Yes closed by Ta, It
1878 In-line
1880 Closed by the end of the line, fixed argument lengths, and/or subsequent
1881 macros. In-line macros have only text children. If a number (or
1882 inequality) of arguments is (n), then the macro accepts an arbitrary num‐
1883 ber of arguments.
1884 .Yo [-arg [val...]] [args...] [res...]
1886 .Yo [-arg [val...]] [args...] Yc...
1888 .Yo [-arg [val...]] arg0 arg1 argN
1890 Macro Callable Parsed Arguments
1892 %A No No >0
1893 %B No No >0
1894 %C No No >0
1895 %D No No >0
1896 %I No No >0
1897 %J No No >0
1898 %N No No >0
1899 %O No No >0
1900 %P No No >0
1901 %Q No No >0
1902 %R No No >0
1903 %T No No >0
1904 %U No No >0
1905 %V No No >0
1906 Ad Yes Yes >0
1907 An Yes Yes >0
1908 Ap Yes Yes 0
1909 Ar Yes Yes n
1910 At Yes Yes 1
1911 Bsx Yes Yes n
1912 Bt No No 0
1913 Bx Yes Yes n
1914 Cd Yes Yes >0
1915 Cm Yes Yes >0
1916 Db No No 1
1917 Dd No No n
1918 Dt No No n
1919 Dv Yes Yes >0
1920 Dx Yes Yes n
1921 Em Yes Yes >0
1922 Er Yes Yes >0
1923 Es Yes Yes 2
1924 Ev Yes Yes >0
1925 Ex No No n
1926 Fa Yes Yes >0
1927 Fd No No >0
1928 Fl Yes Yes n
1929 Fn Yes Yes >0
1930 Fr Yes Yes >0
1931 Ft Yes Yes >0
1932 Fx Yes Yes n
1933 Hf No No n
1934 Ic Yes Yes >0
1935 In No No 1
1936 Lb No No 1
1937 Li Yes Yes >0
1938 Lk Yes Yes >0
1939 Lp No No 0
1940 Ms Yes Yes >0
1941 Mt Yes Yes >0
1942 Nm Yes Yes n
1943 No Yes Yes >0
1944 Ns Yes Yes 0
1945 Nx Yes Yes n
1946 Os No No n
1947 Ot Yes Yes >0
1948 Ox Yes Yes n
1949 Pa Yes Yes n
1950 Pf Yes Yes 1
1951 Pp No No 0
1952 Rv No No n
1953 Sm No No <2
1954 St No Yes 1
1955 Sx Yes Yes >0
1956 Sy Yes Yes >0
1957 Tn Yes Yes >0
1958 Ud No No 0
1959 Ux Yes Yes n
1960 Va Yes Yes n
1961 Vt Yes Yes >0
1962 Xr Yes Yes 2
1963 Delimiters
1965 When a macro argument consists of one single input character considered
1966 as a delimiter, the argument gets special handling. This does not apply
1967 when delimiters appear in arguments containing more than one character.
1968 Consequently, to prevent special handling and just handle it like any
1969 other argument, a delimiter can be escaped by prepending a zero-width
1970 space (‘\&’). In text lines, delimiters never need escaping, but may be
1971 used as normal punctuation.
1972 For many macros, when the leading arguments are opening delimiters, these
1974 delimiters are put before the macro scope, and when the trailing argu‐
1975 ments are closing delimiters, these delimiters are put after the macro
1976 scope. Spacing is suppressed after opening delimiters and before closing
1977 delimiters. For example,
1978 .Aq ( [ word ] ) .
1980 renders as:
1982 ([⟨word⟩]).
1984 Opening delimiters are:
1986 ( left parenthesis
1988 [ left bracket
1989 Closing delimiters are:
1991 . period
1993 , comma
1994 : colon
1995 ; semicolon
1996 ) right parenthesis
1997 ] right bracket
1998 ? question mark
1999 ! exclamation mark
2000 Note that even a period preceded by a backslash (‘\.’) gets this special
2002 handling; use ‘\&.’ to prevent that.
2003 Many in-line macros interrupt their scope when they encounter delimiters,
2005 and resume their scope when more arguments follow that are not delim‐
2006 iters. For example,
2007 .Fl a ( b | c \*(Ba d ) e
2009 renders as:
2011 -a (-b | -c | -d) -e
2013 This applies to both opening and closing delimiters, and also to the mid‐
2015 dle delimiter, which does not suppress spacing:
2016 | vertical bar
2018 As a special case, the predefined string \*(Ba is handled and rendered in
2020 the same way as a plain ‘|’ character. Using this predefined string is
2021 not recommended in new manuals.
2022 Font handling
2024 In mdoc documents, usage of semantic markup is recommended in order to
2025 have proper fonts automatically selected; only when no fitting semantic
2026 markup is available, consider falling back to Physical markup macros.
2027 Whenever any mdoc macro switches the roff(7) font mode, it will automati‐
2028 cally restore the previous font when exiting its scope. Manually switch‐
2029 ing the font using the roff(7) ‘\f’ font escape sequences is never
2030 required.
2031
2033 This section provides an incomplete list of compatibility issues between
2034 mandoc and GNU troff ("groff").
2035 The following problematic behaviour is found in groff:
2037 - Dd with non-standard arguments behaves very strangely. When there
2039 are three arguments, they are printed verbatim. Any other number of
2040 arguments is replaced by the current date, but without any arguments
2041 the string “Epoch” is printed.
2042 - Lk only accepts a single link-name argument; the remainder is misfor‐
2043 matted.
2044 - Pa does not format its arguments when used in the FILES section under
2045 certain list types.
2046 - Ta can only be called by other macros, but not at the beginning of a
2047 line.
2048 - %C is not implemented (up to and including groff-1.22.2).
2049 - ‘\f’ (font face) and ‘\F’ (font family face) Text Decoration escapes
2050 behave irregularly when specified within line-macro scopes.
2051 - Negative scaling units return to prior lines. Instead, mandoc trun‐
2052 cates them to zero.
2053 The following features are unimplemented in mandoc:
2055 - Bd -file file is unsupported for security reasons.
2057 - Bd -filled does not adjust the right margin, but is an alias for Bd
2058 -ragged.
2059 - Bd -literal does not use a literal font, but is an alias for Bd
2060 -unfilled.
2061 - Bd -offset center and -offset right don't work. Groff does not
2062 implement centered and flush-right rendering either, but produces
2063 large indentations.
2064
2066 man(1), mandoc(1), eqn(7), man(7), mandoc_char(7), roff(7), tbl(7)
2067 The web page extended documentation for the mdoc language:
2069 http://mandoc.bsd.lv/mdoc/
2070 provides a few tutorial-style pages for beginners, an extensive style
2071 guide for advanced authors, and an alphabetic index helping to choose the
2072 best macros for various kinds of content.
2073
2075 The mdoc language first appeared as a troff macro package in 4.4BSD. It
2076 was later significantly updated by Werner Lemberg and Ruslan Ermilov in
2077 groff-1.17. The standalone implementation that is part of the mandoc(1)
2078 utility written by Kristaps Dzonsons appeared in OpenBSD 4.6.
2079
2081 The mdoc reference was written by Kristaps Dzonsons <kristaps@bsd.lv>.
2082BSD May 10, 2020 BSD