tacit/minix
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
3c0096fc84
minix/external/bsd/mdocml/dist/mdoc.7
David van Moolenbroek db63c22446 work-3.2.1 squash commit 
Squashed commit of the following:

commit 8fcdd34f87fe9daaac235315d3b6e1d4986ea0ed
Author: David van Moolenbroek <david@minix3.org>
Date:   Tue Nov 5 14:26:57 2013 +0100

    Fix for ramdisk generation (?)

    Change-Id: If7fd55d9a146d7d7b621da274ac0472a5b246c36

commit 5ffd24ad49bff556adceb050c7cbfddd774ed200
Author: David van Moolenbroek <david@minix3.org>
Date:   Tue Nov 5 13:16:56 2013 +0100

    Rebase fixes

    Too lazy to merge this into the appropriate patch.

    Change-Id: I66505d6a0d65330656e78ec9615a026f892b8609

commit 0240220770e6cc18fe16bd0c82e6e5e2c88a4301
Author: David van Moolenbroek <david@minix3.org>
Date:   Sun Oct 6 15:58:54 2013 +0200

    VFS: further cleanup of device code

    - all TTY-related exceptions have now been merged into the regular
      code paths, allowing non-TTY drivers to expose TTY-like devices;
    - as part of this, CTTY_MAJOR is now fully managed by VFS instead of
      being an ugly stepchild of the TTY driver;
    - device styles have become completely obsolete, support for them has
      been removed throughout the system; same for device flags, which had
      already become useless a while ago;
    - device map open/close and I/O function pointers have lost their use,
      thus finally making the VFS device code actually readable;
    - the device-unrelated pm_setsid has been moved to misc.c;
    - some other small cleanup-related changes.

    Change-Id: If90b10d1818e98a12139da3e94a15d250c9933da

commit 07d10dc91955475340005fa86adf71aa981712c8
Author: David van Moolenbroek <david@minix3.org>
Date:   Sat Oct 5 14:59:59 2013 +0200

    IS: dump number of in-use FDs for VFS

    Change-Id: If0e2092d5a8c384c31b1f44cc0591bb119c6d8de

commit ced39723e3e7c39a4a2ef516834702a36a6a26c8
Author: David van Moolenbroek <david@minix3.org>
Date:   Sat Oct 5 01:40:58 2013 +0200

    TTY: fix earlier PTY select "improvement"

    It was just plain wrong.

    Change-Id: Ieab4b4f01d9461e05e0d0ba6427a99d863d6b98d

commit a4a63c15cc5f9daf2e149b84ec930834fe24a983
Author: David van Moolenbroek <david@minix3.org>
Date:   Sat Oct 5 16:31:35 2013 +0200

    Extend dupfrom(2) into copyfd(2)

    This single function allows copying file descriptors from and to
    processes, and closing a previously copied remote file descriptor.
    This function replaces the five FD-related UDS backcalls. While it
    limits the total number of in-flight file descriptors to OPEN_MAX,
    this change greatly improves crash recovery support of UDS, since all
    in-flight file descriptors will be closed instead of keeping them
    open indefinitely (causing VFS to crash on system shutdown). With the
    new copyfd call, UDS becomes simpler, and the concept of filps is no
    longer exposed outside of VFS.

    This patch also moves the checkperms(2) stub into libminlib, thus
    fully abstracting away message details of VFS communication from UDS.

    Change-Id: Idd32ad390a566143c8ef66955e5ae2c221cff966

commit 663e0abb01990da768f1701df6366a4d3bbd67c1
Author: David van Moolenbroek <david@minix3.org>
Date:   Sat Oct 5 12:50:44 2013 +0200

    VFS: better dupfrom(2) deadlock detection

    Change-Id: I29f00075698888c7c8ca60b47ab82fba8c606f4e

commit 54c509663718cc109b0f11ab0adc196bfa82015b
Author: David van Moolenbroek <david@minix3.org>
Date:   Fri Oct 4 21:10:01 2013 +0200

    UDS: sendmsg/recvmsg fixes

    - sendmsg: the accumulation of multiple in-flight file descriptors was
      already described in the comments; now the code actually does what
      the comments say :) -- also, added robustness in case of a failure;
    - recvmsg: only create a socket rights message if there are file
      descriptors pending at all;
    - recvmsg: copy back the control message length;
    - recvmsg: use CMSG_SPACE instead of CMSG_LEN to compute sizes.

    Not sure if all of this is now working according to specification,
    but at least tmux seems to be happy with it.

    Change-Id: I8d076c14c3ff3220b7fea730e0f08f4b4254ede5

commit b0a891c329d721eb84e06ecac803789fe8197306
Author: David van Moolenbroek <david@minix3.org>
Date:   Fri Oct 4 18:41:21 2013 +0200

    UDS: add support for FIONREAD

    Change-Id: I50030012b408242a86f8c55017429acdadff49d1

commit e81d59c874d57d0d0010d3b1ace2351d01f66766
Author: David van Moolenbroek <david@minix3.org>
Date:   Fri Oct 4 18:00:42 2013 +0200

    UDS: align struct sockaddr_un with NetBSD

    Well, make a start, anyway. Our copy was missing a legacy field from
    the structure, that could very well cause applications to fail trying
    to set, clear, or check it. As a consequence, SUN_LEN now yields the
    same result as on NetBSD.

    Change-Id: I80f6aff7769be402b3bd3959f64d314509ed138c

commit 66f8ad9ac7f0e008cdf416877eeab63ed599477d
Author: David van Moolenbroek <david@minix3.org>
Date:   Fri Oct 4 17:57:42 2013 +0200

    UDS: support for nonblocking sockets

    This patch includes several other fixes, which are now tested in the
    test56 test set.

    Change-Id: I9535d5a6c072abf966252838522c5f65b353c6c2

commit 9b4a7ba7ced0b40bf650451ec7baf2935b2ccfe7
Author: David van Moolenbroek <david@minix3.org>
Date:   Fri Oct 4 16:46:18 2013 +0200

    UDS: clean up source code

    - move VFS calls to a separate source file;
    - solve a few subtle bugs, mostly in error handling;
    - simplify debug reporting code;
    - make a few definitions more independent;
    - restyle to something closer to KNF.

    Change-Id: I7b0537adfccac8b92b5cc3e78dac9f5ce3c79f03

commit 881641da1fa711d2d4bf8687cb5beb843801daf8
Author: David van Moolenbroek <david@minix3.org>
Date:   Fri Oct 4 16:29:40 2013 +0200

    UDS: split off from PFS

    Change-Id: I769cbd64aa6e5e85a797caf0f8bbb4c20e145263

commit 2baef79e569c4cebda1a3f831b8e329295e449e6
Author: David van Moolenbroek <david@minix3.org>
Date:   Wed Oct 2 19:37:00 2013 +0200

    at_wini: PCI-only now; one controller per instance

    - remove non-PCI support, since all supported platforms with at_wini
      devices also have PCI support by now;
    - correspondingly, stop using information from the BIOS altogether;
    - limit each driver instance to one controller, to be in line with
      the general MINIX3 one-instance-per-controller driver model; this
      limits the number of disks per at_wini instance to four;
    - go through the controllers by the order of their occurrence in the
      PCI table, thus removing the exception for compatibility devices;
    - let the second at_wini instance shut down silently if there is only
      one IDE controller;
    - clean up some extra code we don't need anymore, and resolve some
      WARNS=5 level warnings.

    Overall, these changes should simplify automatic loading of the right
    disk drivers at boot time in the future.

    Change-Id: Ia64d08cfbeb9916abd68c9c2941baeb87d02a806

commit f7aaabe7e0ae93b439b02d3c21c38f11bae7bbcf
Author: David van Moolenbroek <david@minix3.org>
Date:   Tue Oct 1 00:42:41 2013 +0200

    system.conf: subsystem VID/DID matching support

    - change "vid/did" to "vid:did", old form still supported for now;
    - allow "vid:did/subvid:subdid" specification in system.conf, in
      which case a device will be visible to a driver if the subsystem
      VID/DID also match.

    Change-Id: I7aef54da1b0bc81e24b5d98f1a28416f38f8b266

commit 178d896a32140285e7e9f00dba7bb4a871752f60
Author: Lionel Sambuc <lionel@minix3.org>
Date:   Tue Oct 8 19:00:16 2013 +0200

    usr.bin/man: Update

    Change-Id: I0c5d2115ba384687032f7b2af50d99dedc323b7a

commit 33e8e00217bbf38300f266dda5a494ad4e51bebd
Author: Lionel Sambuc <lionel@minix3.org>
Date:   Tue Oct 8 18:05:29 2013 +0200

    external/bsd/mdocml: Update

    Change-Id: I17b54e52e8322676d83ed4386f586f8ef3029f72

commit e28c0794f18eae77faf3055dadbe76a963242c4e
Author: Lionel Sambuc <lionel@minix3.org>
Date:   Thu Oct 3 18:26:21 2013 +0200

    Adapting build system to call MAKEDEV for /dev

     * Remove static proto.dev
     * Update releasetools/*image.sh not to use proto.dev, as well as
       minor comments cleanup
     * Add TOOL_TOPROTO

    Change-Id: If7dc16d4ebb3b0c4e859786fad25d4af000c999f

commit d26b8149f47461aac67078b8a63ddae21ecdf4f8
Author: Lionel Sambuc <lionel@minix3.org>
Date:   Thu Oct 3 13:54:24 2013 +0200

    MAKEDEV: Add mtree output, and ramdisk set.

    Change-Id: I36cb7e9451960189a33a04a5c2e3ddb19c7be75e

commit 8dc3249c2ec209689922abb306b0e3d15e6a0347
Author: David van Moolenbroek <david@minix3.org>
Date:   Sat Oct 5 20:24:25 2013 +0200

    3.3.0 sync fixes

    Keeping this version at 3.2.1 though, mainly for pkgsrc.

    Change-Id: Ic91e326623f6dbad58754152c4a632e4406f1117

commit f61a525630a33734481bfd8f0994ae33fef6c3fb
Author: David van Moolenbroek <david@minix3.org>
Date:   Wed Oct 2 13:37:49 2013 +0200

    keymaps: improve keypad slash support

    Now that the keymaps can distinguish between the regular slash key
    and the slash key on the numeric keypad, we can avoid localization
    of the latter.

    Change-Id: I20ead7d26a9baa82f5a522562524fd75d44efb42

commit 81e1e0e8e10c08459af9b7d24f51eff41225b62d
Author: Mikal Villa <mikal.villa@gmail.com>
Date:   Wed Oct 2 12:30:03 2013 +0200

    Norwegian keymap

    Change-Id: I181234afc8f1a058e92af6c1fe88979463aaff45

commit c9fc72ef1769f677ad6c932e84959f8756b32264
Author: Thomas Cort <tcort@minix3.org>
Date:   Fri Sep 6 21:40:42 2013 -0400

    Importing usr.bin/uname

    Change-Id: I4c316221e288edd839e26a2af4cb59f28bf722c1

commit 320e18fd3269219d4b68ba0df3ff8f8434a24a09
Author: Thomas Cort <tcort@minix3.org>
Date:   Fri Sep 6 21:40:31 2013 -0400

    uname: normalize release and version

    Most systems provide the full version number in the
    'release' field and the kernel version in 'version'.
    Minix used to split the full version number between
    release and version which caused problems for pkgsrc
    and other applications. This patch brings Minix's
    uname in line with other systems such as NetBSD.
    It also brings the getty banner in line with NetBSD.

    Old Minix uname:
    	sysname->Minix
    	nodename->10.0.2.15
    	release->3
    	version->2.1
    	machine->i686

    New Minix uname:
    	sysname->Minix
    	nodename->10.0.2.15
    	release->3.2.1
    	version->Minix 3.2.1 (GENERIC)
    	machine->i686

    Change-Id: I966633dfdcf2f9485966bb0d0d042afc45bbeb7d

commit 3840323699856b0ab67b3c6c3b79695acc25ffcb
Author: Lionel Sambuc <lionel@minix3.org>
Date:   Thu Sep 19 10:57:10 2013 +0200

    Replacing timer_t by netbsd's timer_t

     * Renamed struct timer to struct minix_timer
     * Renamed timer_t to minix_timer_t
     * Ensured all the code uses the minix_timer_t typedef
     * Removed ifdef around _BSD_TIMER_T
     * Removed include/timers.h and merged it into include/minix/timers.h
     * Resolved prototype conflict by renaming kernel's (re)set_timer
       to (re)set_kernel_timer.

    Change-Id: I56f0f30dfed96e1a0575d92492294cf9a06468a5

commit 23906ce75094c89071c04c6a2a2da780d5d1d9d1
Author: Lionel Sambuc <lionel@minix3.org>
Date:   Wed Oct 2 10:56:24 2013 +0200

    ARM serial driver: Comment termios_baud_rate.

    The B0-B115200 defines are flags, and not the actual speed they
    represent.

    This fixes an incoherency for B0 handling, and documents why it is
    required to call the function again after changing the speed flag.

    DFL_BAUD is set to one of the flag, so to translate it to an actual
    speed, the function calls itself again, which will always be able to
    finish without inducing another recursive call.

    Change-Id: I04ebfaefee31a88d05f0b726352d1581a966147b

commit 92db382b054926bc494cf369731e67af91033cc8
Author: David van Moolenbroek <david@minix3.org>
Date:   Tue Oct 1 23:25:01 2013 +0200

    TTY: skip /dev/log checks if console is serial

    It is unclear why /dev/log has its own open/close rules, but those
    rules conflict with serial console redirection.  This does not solve
    the root of the problem, but it puts back in place more or less the
    same workaround that was already in place before the TTY overhaul.

    Change-Id: Ib53abbc28a76c1f2b0befc8448aeed0173bc96a5

commit f1b6f94f744e82b0a4f0fbe8967a4986e079c7cd
Author: David van Moolenbroek <david@minix3.org>
Date:   Sat Oct 5 19:45:42 2013 +0200

    Corrections to keep VFS ABI-compatible

    Change-Id: Id8a53a687577c1b6f83c11c2e5fb0b8ed1cd2a08

commit 1d9f12eec8edb0ed8b9bc3cb05eb342d6e4ffb03
Author: David van Moolenbroek <david@minix3.org>
Date:   Sat Oct 5 19:35:11 2013 +0200

    Remove support for obsolete 3.2.1 ABI

    Change-Id: I76b4960bda41f55d9c42f8c99c5beae3424ca851

commit 93267010fcf5a6de5bc4ea511e1edab09c2362aa
Author: David van Moolenbroek <david@minix3.org>
Date:   Sat Aug 31 22:59:44 2013 +0200

    Fix various file system warnings

    Change-Id: Ied10498c3ae14f9f2fd06914f23239df330fa296

commit 42a4fca69efd41f11d28e5b4a4df45c3a14ea91f
Author: David van Moolenbroek <david@minix3.org>
Date:   Sat Oct 5 19:22:13 2013 +0200

    VFS/FS: replace protocol version with flag field

    The main motivation for this change is that only Loris supports
    multithreading, and Loris supports dynamic thread allocation, so the
    number of supported threads can be implemented as a bit flag (i.e.,
    either 1 or "at least as many as VFS has"). The ABI break obviates the
    need to support file system versioning at this time, and several
    other aspects are better implemented as flags as well. Other changes:

    - replace peek/bpeek test upon mount with FS flag as well;
    - mark libsffs as 64-bit file size capable;
    - remove old (3.2.1) getdents support.

    Change-Id: I313eace9c50ed816656c31cd47d969033d952a03

commit 6237d4580b2e7f4ca37222581c44f3898a9f2985
Author: Lionel Sambuc <lionel@minix3.org>
Date:   Fri Apr 19 13:16:51 2013 +0200

    usr.bin/stat Update

    Change-Id: I029160c73baab1b3465bc5397a36c55886db225b

commit 9e7f974e9fa61e0e1d9cb519a69155eb71826f9d
Author: Lionel Sambuc <lionel@minix3.org>
Date:   Fri Apr 19 09:54:51 2013 +0200

    almost aligned ioctl prototype

    Change-Id: I7f3eaa99d2a9767f71e8387cea5c7f56dcb28f99

commit b1a9440566584280bd07c6e646bb18d5b8133786
Author: Lionel Sambuc <lionel@minix3.org>
Date:   Thu Apr 18 14:42:15 2013 +0200

    32 to 64 bits fsblkcnt_t and fsfilcnt_t.

    Change-Id: I432229143c85cd178262b802a76ac606801ac59a

commit 8dea53df7843cf4a96601e019f941e7d13a878c0
Author: Lionel Sambuc <lionel@minix3.org>
Date:   Thu Apr 18 11:08:16 2013 +0200

    moving prototypes to lib.h

    Change-Id: If53d3f5ee761b10e0f3d4346a0c5b39ba7901c65

commit 0d00df150181bcc7ee20726801bbc34ebe978a29
Author: Lionel Sambuc <lionel@minix3.org>
Date:   Thu Apr 18 11:07:44 2013 +0200

    struct uucred

    Change-Id: Ia97cb6c38bb566be30d568a252ae7b76142a21dd

commit 1e355e9d217877943e01c5b8859d66258e54b3e5
Author: Lionel Sambuc <lionel@minix3.org>
Date:   Tue Apr 16 11:48:54 2013 +0200

    Alignement on netbsd types, part 1

    The following types are modified (old -> new):
     * _BSD_USECONDS_T_ int       -> unsigned int
     * __socklen_t      __int32_t -> __uint32_t
     * blksize_t        uint32_t  -> int32_t
     * rlim_t           uint32_t  -> uint64_t
    On ARM:
     * _BSD_CLOCK_T_    int       -> unsigned int
    On Intel:
     * _BSD_CLOCK_T_    int       -> unsigned long

    bin/cat is also updated in order to fix warnings.

    _BSD_TIMER_T_ has still to be aligned.

    Change-Id: I2b4fda024125a19901120546c4e22e443ba5e9d7

commit e7b39757eac1ab7aac5a59d7aa124fc316a6e01f
Author: Lionel Sambuc <lionel@minix3.org>
Date:   Fri Aug 23 20:27:27 2013 +0200

    Adapt the type used for adjtime_delta

    clock_t is currently a signed type, but in NetBSD this is not the
    case. As we plan on aligning our types we have to change this as this
    prevents negative delta from being correctly used.

    Change-Id: I9bccdee2b41626b0262471dc1900de505a1991a7

commit 5a551dbe663b22760632c5232326e4101360b330
Author: David van Moolenbroek <david@minix3.org>
Date:   Sat Oct 5 19:01:19 2013 +0200

    Butchered version of "Bumping version.."

    Change-Id: Ieb5f31fe037bcf45cc86a906f983a0ab3f636468

commit 6d601ae1d7072a8fb6cd908ff1d24ea4ca9bf1b0
Author: David van Moolenbroek <david@minix3.org>
Date:   Sat Oct 5 18:57:04 2013 +0200

    Trimmed version of "VFS: use 64-bit file..."

    Change-Id: I1b53ef05e939f6afed97f507d443a1d60ed81a21

commit 7adaa6556051b3800670399ee26d246fa9f32486
Author: David van Moolenbroek <david@minix3.org>
Date:   Sat Oct 5 18:37:39 2013 +0200

    Trimmed version of "stat.h: remove some big_ types"

    Change-Id: I6c17d6e5e9d2ab4c1bbf33e461cec4c37b870266

commit 3da9bd17116b66416e8e10ce148599b8ea723680
Author: Thomas Veerman <thomas@minix3.org>
Date:   Thu Mar 7 14:46:21 2013 +0000

    Define protocol version of {mode,ino,uid,gid}_t

    Change-Id: Ia2027749f2ce55a561d19eb895a5618505e9a2ac

commit 6ca17cd644c3b3e4f318faf7d1242855af473b6f
Author: Thomas Veerman <thomas@minix3.org>
Date:   Mon Mar 25 21:09:10 2013 +0000

    VFS-FS protocol: add versioning

    Change-Id: Ice6fbfd4b535b7435653fa08b27a3378d1cfdbf8

commit a7ff601df7d61c0925241ce10aee3a7e99343b3a
Author: David van Moolenbroek <david@minix3.org>
Date:   Sat Sep 28 14:46:21 2013 +0200

    Input infrastructure, INPUT server, PCKBD driver

    This commit separates the low-level keyboard driver from TTY, putting
    it in a separate driver (PCKBD). The commit also separates management
    of raw input devices from TTY, and puts it in a separate server
    (INPUT). All keyboard and mouse input from hardware is sent by drivers
    to the INPUT server, which either sends it to a process that has
    opened a raw input device, or otherwise forwards it to TTY for
    standard processing.

    Design by Dirk Vogt. Prototype by Uli Kastlunger.

    Additional changes made to the prototype:

    - the event communication is now based on USB HID codes; all input
      drivers have to use USB codes to describe events;
    - all TTY keymaps have been converted to USB format, with the effect
      that a single keymap covers all keys; there is no (static) escaped
      keymap anymore;
    - further keymap tweaks now allow remapping of literally all keys;
    - input device renumbering and protocol rewrite;
    - INPUT server rewrite, with added support for cancel and select;
    - PCKBD reimplementation, including PC/AT-to-USB translation;
    - support for manipulating keyboard LEDs has been added;
    - keyboard and mouse multiplexer devices have been added to INPUT,
      primarily so that an X server need only open two devices;
    - a new "libinputdriver" library abstracts away protocol details from
      input drivers, and should be used by all future input drivers;
    - both INPUT and PCKBD can be restarted;
    - TTY is now scheduled by KERNEL, so that it won't be punished for
      running a lot; without this, simply running "yes" on the console
      kills the system;
    - the KIOCBELL IOCTL has been moved to /dev/console;
    - support for the SCANCODES termios setting has been removed;
    - obsolete keymap compression has been removed;
    - the obsolete Olivetti M24 keymap has been removed.

    Change-Id: I3a672fb8c4fd566734e4b46d3994b4b7fc96d578

commit 0a3e629c0d4101a33c8b2e79c2e52d312978d34b
Author: David van Moolenbroek <david@minix3.org>
Date:   Fri Sep 27 11:56:29 2013 +0000

    TTY: allow selecting on translated minors

    Due to the existence of /dev/console and /dev/log, and the new
    "console=" setting, it is now possible that a single non-PTY object
    (e.g. serial) is accessible through two different minor numbers.  This
    poses a problem when sending late select replies (CDEV_SEL2_REPLY),
    because the object's minor number can not be used to identify the
    device.  Since selecting on such objects through translated minor
    numbers is actually required, we now save the minor number used to
    initiate the select query in order to send a late reply.

    The solution is suboptimal, as it is not possible to use two different
    minors to select on the same object at once.  In the future, there
    should be at least one select record for each minor that can be used
    with each object.

    Change-Id: I4d39681d2ffd68b4047daf933d45b7bafe3c885e

commit fe2167a148dd17e15502d98e64057239fa122dd5
Author: David van Moolenbroek <david@minix3.org>
Date:   Sat Sep 21 17:35:15 2013 +0200

    Take LOG out of the boot image

    Change-Id: Id2629776b53aae46629b04a42c15cbbacac9b949

commit 81e138bb5ba168322eb780978ed4a90fc1ab7945
Author: David van Moolenbroek <david@minix3.org>
Date:   Sat Sep 21 15:03:20 2013 +0200

    Kernel: make SIGKMESS target process list dynamic

    The set of processes to which a SIGKMESS signal is sent whenever new
    diagnostics messages are added to the kernel's message buffer, is now
    no longer hardcoded. Instead, processes can (un)register themselves
    to receive such notifications, by means of sys_diagctl().

    Change-Id: I9d6ac006a5d9bbfad2757587a068fc1ec3cc083e

commit 9afa18ec208646a9244048a1d444c474ceb47c73
Author: David van Moolenbroek <david@minix3.org>
Date:   Sat Sep 21 00:58:46 2013 +0200

    Rename SYSCTL kernel call to DIAGCTL

    Change-Id: I1b17373f01808d887dcbeab493838946fbef4ef6

commit f82f1ec4b06240e96ed8e64e4bfdf5b06d688f89
Author: David van Moolenbroek <david@minix3.org>
Date:   Wed Sep 18 20:13:59 2013 +0200

    Prevent Jenkins from breaking on old df(1)

    Change-Id: Ie8e1758bd9de4d5c95c597302f80d568058fbb68

commit 8a430b673dc97767306ddc9cb1a5367f333b7602
Author: David van Moolenbroek <david@minix3.org>
Date:   Wed Sep 18 14:09:47 2013 +0200

    Add testvnd.sh test script

    As part of this, change the "run" script to allow certain scripts to
    be run as root only.

    Change-Id: I846e41037f9d4f6c7fc0b5ea8250303a7bd72f5d

commit fd57902664f398edd9274c2ab1d87daa0b4f4584
Author: David van Moolenbroek <david@minix3.org>
Date:   Wed Sep 18 14:06:46 2013 +0200

    Import NetBSD vndconfig(8)

    The tool has been changed heavily to match our VND driver model.

    NetBSD is in the process of renaming it from vnconfig(8) to
    vndconfig(8). To keep things in sync, we have to play along.

    Change-Id: Ie86df184f03ab00573ea76b43c9caa0412e8321d

commit 6809baec22122124a04d8bf8f4f8b5fc7778cb3d
Author: David van Moolenbroek <david@minix3.org>
Date:   Wed Sep 18 14:02:17 2013 +0200

    Add VND driver, providing loopback devices

    Change-Id: I40fa695e28c67477a75383e6f1550e451afcab41

commit 4cb7efbfd17b934f914f633c8bebf5bec7934e5d
Author: David van Moolenbroek <david@minix3.org>
Date:   Wed Sep 18 13:55:15 2013 +0200

    VFS: add dupfrom(2) call

    This call copies a file descriptor from a remote process into the
    calling process. The call is for the VND driver only, and in the
    future, ACLs will prevent any other process from using this call.

    Change-Id: Ib16fdd1f1a12cb38a70d7e441dad91bc86898f6d

commit 378f893b1e710563e2ef2eee457255a6f3037885
Author: David van Moolenbroek <david@minix3.org>
Date:   Wed Sep 18 11:46:08 2013 +0200

    tests: do not skip installed shell tests

    When installed, the test scripts lose their ".sh" suffix, causing them
    to be skipped by the "run" script. With this patch, the tests are no
    longer specified with ".sh" suffix in the run script, and the suffix
    is added automatically as necessary.

    Change-Id: I0b72312e79992b9818559c6546a0e52cd95184c2

commit ecdd53c03077c3cceb29485aa56021d99485d6a5
Author: David van Moolenbroek <david@minix3.org>
Date:   Wed Sep 18 13:41:56 2013 +0200

    blocktest: prepare to be run as part of tests

    - fail SEF initialization if any of the subtests failed, so that the
      party invoking the "service up" can tell whether the test succeeded;
    - add "nocontig" option, because VM isn't particularly good at
      allocating contiguous memory;
    - add "silent" option, because it floods the console otherwise;
    - allow the device size to be smaller than the maximum transfer size;
    - install files to installed test directory.

    Change-Id: I45c818f817c11d90c5f94ae26a2fc49e36e6761e

commit 848ef711847b7adcf20dce333435802c4e1018ea
Author: David van Moolenbroek <david@minix3.org>
Date:   Wed Sep 18 13:38:36 2013 +0200

    Enable devname(3)

    There is no support for a device name database yet, so this call is
    expected to be fairly slow.

    Change-Id: I73aa5f267e2b6921b7d3bbdcc4beac463931132c

commit b84199849ad72030993bcf3f943da1509be15ded
Author: David van Moolenbroek <david@minix3.org>
Date:   Sun Sep 15 13:09:00 2013 +0200

    libbdev: be less noisy about clean driver restarts

    Change-Id: Ie02a459c9b544d361ab00bac431ef99de53b0c5f

commit 4f01352a2a6c82fc11465bc555c25e0344c5b970
Author: David van Moolenbroek <david@minix3.org>
Date:   Sat Sep 14 14:43:53 2013 +0200

    Straighten ioctl.h

    - include all ioctl subheaders, properly listing all letters;
    - change FBD's ioctl calls to use 'B' instead of 'F', in
      preparation of the VND driver.
    Change-Id: Ia718979568cc057f47cf505a89238d5b3b6695d4

commit 0ee3f3aeb3d634133a9cd8c3b81589772235c617
Author: David van Moolenbroek <david@minix3.org>
Date:   Sun Sep 15 18:55:42 2013 +0200

    VM: readd support for forgetting cached FS blocks

    Not all services involved in block I/O go through VM to access the
    blocks they need.  As a result, the blocks in VM may become stale,
    possibly causing corruption when the stale copy is restored by a
    service that does go through VM later on.  This patch restores support
    for forgetting cached blocks that belong to a particular device, and
    makes the relevant file systems use this functionality 1) when
    requested by VFS through REQ_FLUSH, and 2) upon unmount.

    Change-Id: I0758c5ed8fe4b5ba81d432595d2113175776aff8

commit c1652705b625a978ea2af169a21349352bd6575f
Author: David van Moolenbroek <david@minix3.org>
Date:   Wed Sep 11 14:50:18 2013 +0200

    filter: use libblockdriver

    Change-Id: Ifbca2482e996ddca58036d45f557165e636fb3fa

commit ad99ccdb45b897afa7573f75b1a29c4a19767870
Author: David van Moolenbroek <david@minix3.org>
Date:   Tue Sep 10 20:25:01 2013 +0200

    Rewrite character driver protocol

    As a side effect, remove the clone style, as the normal device style
    supports device cloning now.

    Change-Id: Ie82d1ef0385514a04a8faa139129a617895780b5

commit 4f91091ea26022877fd8c29094008d8072cf5e2b
Author: David van Moolenbroek <david@minix3.org>
Date:   Tue Sep 10 16:06:37 2013 +0200

    Remove support for reopening character devices

    Previously, VFS would reopen a character device after a driver crash
    if the associated file descriptor was opened with the O_REOPEN flag.
    This patch removes support for this feature. The code was complex,
    full of uncovered corner cases, and hard to test. Moreover, it did not
    actually hide the crash from user applications: they would get an
    error code to indicate that something went wrong, and have to decide
    based on the nature of the underlying device how to continue.

    - remove support for O_REOPEN, and make playwave(1) reopen its device;
    - remove support for the DEV_REOPEN protocol message;
    - remove all code in VFS related to reopening character devices;
    - no longer change VFS filp reference count and FD bitmap upon filp
      invalidation; instead, make get_filp* fail all calls on invalidated
      FDs except when obtained with the locktype VNODE_OPCL which is used
      by close_fd only;
    - remove the VFS fproc file descriptor bitmap entirely, returning to
      the situation that a FD is in use if its slot points to a filp; use
      FILP_CLOSED as single means of marking a filp as invalidated.

    Change-Id: I34f6bc69a036b3a8fc667c1f80435ff3af56558f

commit 8dfbb8fbe4f37642ac9700cc46ad0588687aa3a4
Author: David van Moolenbroek <david@minix3.org>
Date:   Tue Sep 10 12:19:08 2013 +0200

    VFS: rework device code

    - block the calling thread on character device close;
    - fully separate block and character open/close routines;
    - reuse generic open/close code for the cloning case;
    - zero all messages to drivers before filling them;
    - use appropriate types for major/minor device numbers.

    Change-Id: Ia90e6fe5688f212f835c5ee1bfca831cb249cf51

commit 9fabdb8b4edf637b47f1530bea145d68a028c319
Author: David van Moolenbroek <david@minix3.org>
Date:   Mon Sep 9 00:04:12 2013 +0200

    Make PFS backcalls regular VFS calls

    - prefix them with VFS_ as they are going to VFS;
    - give these calls normal call numbers;
    - give them their own set of message field aliases;
    - also make do_mapdriver a regular call.

    Change-Id: I2140439f288b06d699a1f65438bd8306509b259e

commit 8fbd5d36fa175e2c31ed4a239be3f785e2995aef
Author: David van Moolenbroek <david@minix3.org>
Date:   Wed Sep 11 12:48:10 2013 +0200

    TTY: use libchardriver; clean up

    - writing to a PTY master side blocks if there is not already a
      blocked reader on the slave side, and select now reflects this;
    - internally, TTY now uses a test based on "caller != NONE" rather
      than "grant != GRANT_INVALID" to identify whether a call is
      currently ongoing;
    - "offset" fields have been removed as they equal the corresponding
      "cum" fields;
    - improved variable typing and function naming here and there;
    - various other small fixes.

    Change-Id: I6b51452888942e864b4e034e8c8490576184a23e

commit 53df30e2b876c03b26f8f52abeafcf8f601e6fd2
Author: David van Moolenbroek <david@minix3.org>
Date:   Wed Sep 11 01:13:59 2013 +0200

    VFS: select(2) fixes

    - check each file descriptor's open access mode (filp_mode);
    - treat an error returned by a character driver as a select error;
    - check all filps in each set before finishing select;
    - do not copy back file descriptor sets if an error occurred;
    - remove the hardcoded list of supported character major devices,
      since all drivers should now be capable of responding properly;
    - add tests to test40 and fix its error count aggregation.

    Change-Id: I57ef58d3afb82640fc50b59c859ee4b25f02db17

commit f08c75810f26adf75a757b5b65fdfa2589cf701d
Author: David van Moolenbroek <david@minix3.org>
Date:   Wed Sep 11 01:07:28 2013 +0200

    Retire EBADIOCTL in favor of ENOTTY

    Change-Id: I6bd0e301d21ab7f2336e350e7e6e15d238c2c93d

commit 91b7de8257c92283648c796d882a9095a1f64707
Author: David van Moolenbroek <david@minix3.org>
Date:   Wed Sep 4 15:42:36 2013 +0000

    libnetsock: use libchardriver

    Change-Id: Ia5b780cad0b0c636db9bd866c7223da0d38ef6ea

commit 6a3a64d9669c5b1d6ca9acc12f02cd2f21f22d0f
Author: David van Moolenbroek <david@minix3.org>
Date:   Wed Sep 11 00:50:36 2013 +0200

    LWIP: move chardev message parsing into libnetsock

    Change-Id: Ie23fd003c9fa35811548f388c8e9b55e8d9de8d7

commit 39aa2794e04ad34aecc6dcf607c0987dad13c1ef
Author: David van Moolenbroek <david@minix3.org>
Date:   Mon Sep 9 14:53:28 2013 +0000

    INET: use libchardriver

    Change-Id: Icf8a1a5769ce0aede1cc28da99b9daf7d328182c

commit 7c0d3f508d8e840a2d30da4d3e3af696b9ad2abc
Author: David van Moolenbroek <david@minix3.org>
Date:   Tue Sep 3 02:00:20 2013 +0200

    PFS: use libchardriver; clean up

    - simplify and repair UDS request handling state machine;
    - simplify interface used between internal modules;
    - implement missing support for nonblocking I/O;
    - fix select implementation;
    - clean up global variables.

    Change-Id: Ia82c5c6f05cc3f0a498efc9a26de14b1cde6eace

commit 5598aedb79b34fd02b3b81427d683014a3303e0c
Author: David van Moolenbroek <david@minix3.org>
Date:   Tue Sep 3 01:59:20 2013 +0200

    libaudiodriver: use libchardriver

    Change-Id: I299d58d110ad14b69076276ba46c4325875c34ca

commit 2aadc0aa253427d18c1e3db597c33dd06d9c380e
Author: David van Moolenbroek <david@minix3.org>
Date:   Tue Sep 3 01:57:41 2013 +0200

    printer: use libchardriver

    Change-Id: Ifa3cabeada74c32df2613b8279c00f86e831c775

commit aeaa28b7c68aced329d9cf5b4a01af07b2f3638e
Author: David van Moolenbroek <david@minix3.org>
Date:   Tue Sep 3 01:49:38 2013 +0200

    libchardriver: full API rewrite

    The new API now covers the entire character driver protocol, while
    hiding all the message details. It should therefore be used by all
    new character drivers. All existing drivers that already made use of
    libchardriver have been changed to use the new API.

    As one of the most important API changes, support for scatter and
    gather transfers has been removed, as several key drivers already
    did not support this, and it could be supported at the safecopy
    level instead (for a future readv/writev).

    Additional changes include:

    - respond to block device open requests to avoid hanging VFS threads;
    - add support for sef_cancel.

    Change-Id: I1bab6c1cb66916c71b87aeb1db54a9bdf171fe6b

commit 6fbd39f8a65178d8fafa260dc42fde5341eb9097
Author: David van Moolenbroek <david@minix3.org>
Date:   Thu Aug 1 18:20:33 2013 +0200

    blocktest: add support for no alignment

    Some block drivers do not impose any alignment requirements, and this
    patch allows such block drivers to pass the test set. As a side effect,
    minimal support for min_write is added, but this part of blocktest is
    in need of further improvement.

commit d70dc11950991506fa08d144067de3fe86b17136
Author: David van Moolenbroek <david@minix3.org>
Date:   Wed Apr 18 00:04:28 2012 +0200

    libutil: let opendisk(3) try /dev

    If a device node is given without path, and opening the node fails
    initially, prepend "/dev/" to the node name and try opening again.
    This is more in line with NetBSD behavior.

commit 4b6bf57bc77973874b041239c5a7809448e4d857
Author: David van Moolenbroek <david@minix3.org>
Date:   Tue Sep 10 23:57:32 2013 +0200

    Block drivers: make IOCTL request unsigned long

    The block driver protocol and libblockdriver's bdr_ioctl hook are
    changed, as well as the users of this hook. Other parts of the system
    are expected to change accordingly eventually, since the ioctl(2)
    prototype has been aligned with NetBSD's.

    Change-Id: Ide46245b22cfa89ed267a38088fb0ab7696eba92

commit d74ea98bdfd90605dd5b0c57e12390dc4dba56e6
Author: David van Moolenbroek <david@minix3.org>
Date:   Sat Jul 27 00:49:49 2013 +0200

    Block protocol: add user endpoint to IOCTL request

    I/O control requests now come with the endpoint of the user process
    that initiated the ioctl(2) call. It is stored in a new BDEV_USER
    field, which is an alias for BDEV_FLAGS. The contents of this field
    are to be used only in highly specific situations. It should be
    preserved (not replaced!) by services that forward IOCTL requests,
    and may be set to NONE for service-initiated IOCTL requests.

    Change-Id: I68a01b9ce43eca00e61b985a9cf87f55ba683de4

commit 15afe7ddf85235f00e5a5d0e825d2894ac58549d
Author: David van Moolenbroek <david@minix3.org>
Date:   Sat Jul 27 00:49:49 2013 +0200

    Block protocol: use own [RW]_BIT definitions

    The original R_BIT and W_BIT definitions have nothing to do with the
    way these bits are used. Their distinct usage is more apparent when
    they have different names.

    Change-Id: Ia984457f900078b2e3502ceed565fead4e5bb965

commit c4c9435b0df31b36c11f27370475694043c5b8e0
Author: David van Moolenbroek <david@minix3.org>
Date:   Tue Sep 10 23:35:15 2013 +0200

    libblockdriver: expose BLOCKDRIVER_MAX_DEVICES

    This constant determines the range of valid device_id_t values that
    a block driver can return from the bdr_device hook: a value between
    0 and (BLOCKDRIVER_MAX_DEVICES - 1) inclusive.

    Change-Id: I80fac469e88ac13d4b869007e6f2c2f7569da433

commit 2c5bd1565b5d9b487899dee7a023a641343e65a9
Author: David van Moolenbroek <david@minix3.org>
Date:   Wed Sep 11 13:33:00 2013 +0200

    libblockdriver: various updates

    - internal structure rearrangement;
    - respond to char device open requests to avoid hanging VFS threads;
    - make drivers use designated initializers;
    - use devminor_t for all minor device numbers;
    - change bdr_other hook to take ipc_status and return nothing;
    - fix default geometry computation;
    - add support for sef_cancel.

    Change-Id: Ia063a136a3ddb2b78de36180feda870605753d70

commit b1cfc3123b03d5a8c9452ae251892593dc328357
Author: David van Moolenbroek <david@minix3.org>
Date:   Sun Sep 1 14:34:17 2013 +0200

    Block drivers: reply ENOTTY to unknown IOCTLs

    Change-Id: Ie2e82d2491d546f4dd73b009100646e249a147b5

commit b5eab0554511ace3d7fae40883be0da139b0e2ab
Author: David van Moolenbroek <david@minix3.org>
Date:   Sun Jul 28 14:03:07 2013 +0200

    Move SUB_PER_DRIVE definition into minix/drvlib.h

commit 20c8aedc6737fc935ccea0b394616851ff4fdece
Author: David van Moolenbroek <david@minix3.org>
Date:   Mon Sep 2 17:34:44 2013 +0200

    VFS: update filp_pos on chardev I/O (workaround)

    Previously, reading from or writing to a character device would not
    update the file position on the corresponding filp object.  Performing
    this update correctly is not trivial: during and after the I/O
    operation, the filp object must not be locked.  Ideally, read/write
    requests on a filp that is already involved in a read/write operation,
    should be queued.  For now, we optimistically update the file position
    at the start of the I/O; this works under the assumptions listed in
    the corresponding comment.

    Change-Id: I172a61781850423709924390ae3df1f2d1f94707

commit dbef7bae2308a2e4449b8f274898ed3b60b2add2
Author: David van Moolenbroek <david@minix3.org>
Date:   Mon Sep 2 13:45:02 2013 +0200

    I2C: change BUSC_I2C_xxx to use own protocol

    Previously it would use bits of the character driver protocol, which
    will change heavily.  In the new situation, the BUSC_I2C_xxx requests
    use a protocol more in line with the PCI protocol, with the reply code
    in m_type.

    Change-Id: I51597b3f191078c8178ce17372de123031f7a4c4

commit 7cdb9683ec718247b03cbae3c827d9834c484e91
Author: David van Moolenbroek <david@minix3.org>
Date:   Sat Aug 31 16:13:37 2013 +0200

    tests: add test77 for opening/closing PTYs

    Change-Id: I30e3418f75137aa08037fa6581ff3d4cce32a114

commit ed9ee8b9cd5a647130a81bd70af48cee4f6dca15
Author: David van Moolenbroek <david@minix3.org>
Date:   Sat Aug 31 16:08:25 2013 +0200

    TTY: fix for PTY open/close logic

    Opening and closing the master side of a pseudo terminal without
    opening the slave side would result in the pseudo terminal becoming
    permanently unavailable.  In addition, reopening the slave side
    would be possible but not allow for I/O.  Finally, attempting to
    open an in-use master would wipe its I/O state.  These issues have
    been resolved.

    Change-Id: I9235e3d9aba321803f9280b86b6b5e3646ad5ef3

commit cd14d52a99df7fb6dd7c6c48a034e4bf7c170789
Author: David van Moolenbroek <david@minix3.org>
Date:   Fri Aug 30 18:48:56 2013 +0200

    tests: remove select subdirectory

    This test set has been obsoleted by test40.

    Change-Id: I55439152824906778ad07d409dfb327ac10bea70

commit 5ab6f6e7c2f4618648f163af6bd705e5ef2fafb8
Author: David van Moolenbroek <david@minix3.org>
Date:   Fri Aug 30 18:43:23 2013 +0200

    tests: add test76 for interrupting VFS operations

    Change-Id: Ic436cac61de8c42e0c7ee2d442c647528654cde9

commit ad548d2c9f78e2f2dc2108c50b6c7ed6755a53f1
Author: David van Moolenbroek <david@minix3.org>
Date:   Wed Aug 28 13:08:16 2013 +0200

    VFS: fix interruption of blocking pipe operations

    POSIX states that when interrupted, partially successful pipe
    operations should return the partial result rather than EINTR. VFS
    previously wouldn't look at the partial result, and not clear it
    either, which would result in a panic upon the next pipe operation.

    Change-Id: Ia1eb72b4b77394051444e63a1390d49bb315eb04

commit 813198ce7b0ce171f79529e8f6c5a94ab26ce1cb
Author: David van Moolenbroek <david@minix3.org>
Date:   Fri Aug 30 00:57:16 2013 +0200

    libmthread: do not dump stack for free threads

    Change-Id: Ic438a252f5bddaf1513f554c71173e6fffb0c674

commit 53b6001312428a1ac7379718616cb640614f53e6
Author: David van Moolenbroek <david@minix3.org>
Date:   Fri Aug 30 14:00:50 2013 +0200

    VFS: worker thread model overhaul

    The main purpose of this patch is to fix handling of unpause calls
    from PM while another call is ongoing. The solution to this problem
    sparked a full revision of the threading model, consisting of a large
    number of related changes:

    - all active worker threads are now always associated with a process,
      and every process has at most one active thread working for it;
    - the process lock is always held by a process's worker thread;
    - a process can now have both normal work and postponed PM work
      associated to it;
    - timer expiry and non-postponed PM work is done from the main thread;
    - filp garbage collection is done from a thread associated with VFS;
    - reboot calls from PM are now done from a thread associated with PM;
    - the DS events handler is protected from starting multiple threads;
    - support for a system worker thread has been removed;
    - the deadlock recovery thread has been replaced by a parameter to the
      worker_start() function; the number of worker threads has
      consequently been increased by one;
    - saving and restoring of global but per-thread variables is now
      centralized in worker_suspend() and worker_resume(); err_code is now
      saved and restored in all cases;
    - the concept of jobs has been removed, and job_m_in now points to a
      message stored in the worker thread structure instead;
    - the PM lock has been removed;
    - the separate exec lock has been replaced by a lock on the VM
      process, which was already being locked for exec calls anyway;
    - PM_UNPAUSE is now processed as a postponed PM request, from a thread
      associated with the target process;
    - the FP_DROP_WORK flag has been removed, since it is no longer more
      than just an optimization and only applied to processes operating on
      a pipe when getting killed;
    - assignment to "fp" now takes place only when obtaining new work in
      the main thread or a worker thread, when resuming execution of a
      thread, and in the special case of exiting processes during reboot;
    - there are no longer special cases where the yield() call is used to
      force a thread to run.

    Change-Id: I7a97b9b95c2450454a9b5318dfa0e6150d4e6858

commit 6fbb7f4167510fb1a71fdad2b965dc2f7417aef4
Author: David van Moolenbroek <david@minix3.org>
Date:   Wed Aug 28 15:58:30 2013 +0200

    Retire ptrace(T_DUMPCORE), dumpcore(1), gcore(1)

    The T_DUMPCORE implementation was not only broken - it would currently
    produce a coredump of the tracer process rather than the traced
    process - but also deeply flawed, and fixing it would require serious
    alteration of PM's internal state machine. It should be possible to
    implement the same functionality in userland, and that is now the
    suggested way forward. For now, also remove the (identical) utilities
    using T_DUMPCORE: dumpcore(1) and gcore(1).

    Change-Id: I1d51be19c739362b8a5833de949b76382a1edbcc

commit fde44a0523a26b5bad5a0e3fc2921b1b5821d5d4
Author: David van Moolenbroek <david@minix3.org>
Date:   Fri Aug 30 13:42:51 2013 +0200

    VFS: process char driver replies from main thread

    Previously, processing of some replies coming from character drivers
    could block on locks, and therefore, such processing was done from
    threads that were associated to the character driver process. The
    hidden consequence of this was that if all threads were in use, VFS
    could drop replies coming from the driver. This patch returns VFS to
    a situation where the replies from character drivers are processed
    instantly from the main thread, by removing the situations that may
    cause VFS to block while handling those replies.

    - change the locking model for select, so that it will never block
      on any processing that happens after the select call has been set
      up, in particular processing of character driver select replies;
    - clearly mark all select routines that may never block;
    - protect against race conditions in do_select as result of the
      locking that still does happen there (as is required for pipes);
    - also handle select timers from the main thread;
    - move processing of character driver replies into device.c.

    Change-Id: I4dc8e69f265cbd178de0fbf321d35f58f067cc57

commit d5d67d293d4a7a2669eb179621a1c6d3e2796d97
Author: David van Moolenbroek <david@minix3.org>
Date:   Sun Aug 25 00:26:38 2013 +0200

    VFS: properly cancel select queries on unpause

    Change-Id: I16e71db3f5c1bcc7ba6045bc9f02b13d71dc31eb

commit d0371a4fbdaddbf7bc543a8046bb91454e09283d
Author: David van Moolenbroek <david@minix3.org>
Date:   Fri Aug 30 13:33:56 2013 +0200

    VFS: remove support for sync char driver protocol

    Change-Id: I57cc870a053b813b3a3fc45da46606ea84fe4cb1

commit 2b12ad511fabd5a1019f736221f2940bfe7e2781
Author: David van Moolenbroek <david@minix3.org>
Date:   Fri Aug 30 13:00:44 2013 +0200

    VFS: remove FP_BLOCKED_ON_DOPEN

    These days, DEV_OPEN calls to character drivers block the calling
    thread until completion or failure, and thus never return SUSPEND to
    the caller. The same already applied to BDEV_OPEN calls to block
    drivers. It has thus become impossible for a process to enter a state
    of being blocked on a device open call.

    There is currently no support for restarting device open calls to
    restarted character drivers. This support was present in the _DOPEN
    logic, but was already no longer triggering. In the future, this case
    should be handled by the thread performing the open request.

    Change-Id: I6cc1e7b4c9ed116c6ce160b315e6e060124dce00

commit 0eee377a337f5800760d2f5611d203c158ac6099
Author: David van Moolenbroek <david@minix3.org>
Date:   Fri Aug 30 12:18:27 2013 +0200

    PFS: remember request information for IOCTLs

    Not doing so caused PFS to commit protocol violations by relying on
    stale information when sending replies. This stale information always
    happened to be correct, which is why the problem went unnoticed.
    Change-Id: Ia42ca670718d6e731193cd2c34a3ff455f8a94d3

commit 3272c645aca015b6778a8fe945e014a0a5acc023
Author: David van Moolenbroek <david@minix3.org>
Date:   Fri Aug 30 11:14:03 2013 +0200

    Retire the synchronous character driver protocol

    - change all sync char drivers into async drivers;
    - retire support for the sync protocol in libchardev;
    - remove async dev style, as this is now the default;
    - remove dev_status from VFS;
    - clean up now-unused protocol messages.

    Change-Id: I6aacff712292f6b29f2ccd51bc1e7d7003723e87

commit 831d825d5a6891b79e97002e1a2d396dcb47bea6
Author: David van Moolenbroek <david@minix3.org>
Date:   Fri Aug 30 10:48:34 2013 +0200

    Sync char protocol: add nonblocking transfer flag

    The async char protocol already has this, so this patch closes the
    gap between the two protocols a bit. Support for this flag has been
    added to all sync char drivers that support CANCEL at all.

    The LOG driver was already using the asynchronous protocol, but it
    did not support the nonblocking transfer flag. This has been fixed
    as well.

    Change-Id: Ia55432c9f102765b59ad3feb45a8bd47a782c93f

commit 4f5aec7328128b9d035ff1158f0e6a0f7bd393e4
Author: David van Moolenbroek <david@minix3.org>
Date:   Sat Aug 24 12:29:39 2013 +0200

    VFS: set w_drv_sendrec only when needed

    As with w_task, this ensures that the field remains cleared if it is
    not used. Without this, worker_stop could mistakenly identify a thread
    as talking to a device driver rather than a (crashed) file server.

    Change-Id: I7d3ebed3efc3cd4f5c891f61c67a6463109b6376

commit 9bbf923154733f1b9ba52a063872ccdbaa7ff0f0
Author: Thomas Veerman <thomas@minix3.org>
Date:   Sat Aug 24 12:23:41 2013 +0200

    VFS: set w_task only when needed

    It was always set, but not always cleared, when talking to asynchronous
    drivers. This could cause erratic behavior upon a driver crash.

    Normally, a worker thread's w_task field is set when it's about to
    communicate with a driver or FS. Then upon receiving a reply we can
    do sanity checks (that the thread we want to wake up was actually
    waiting for a reply). Also, when a driver/FS crashes, we can identify
    which worker threads were talking to the crashed endpoint and handle
    the error gracefully.

    Asynchronous drivers are a bit special, though. In most cases, the
    sender of the request is not interested in the reply (the sender was
    suspended and only wants to know whether the request was successfully
    caried out or not). However, the open request is special, as the reply
    carries information needed by the sender. This is the only request
    where a worker thread actually yields and waits for the result. This is
    also the only case where we're interested in setting w_task for
    asynchronous drivers.

    Change-Id: Ia1ce2747937df376122b5e13b6a069de27fcc379

commit 2a293ca6703354cd7be8eb18147f7c4d18894132
Author: David van Moolenbroek <david@minix3.org>
Date:   Mon Aug 19 20:34:15 2013 +0200

    Import NetBSD df(1)

    Change-Id: Ia60f8b23b961e4132efece1e7e38f0d63597c13b

commit c35fc992ccc052e1f3741be0db9b676682f68bf8
Author: David van Moolenbroek <david@minix3.org>
Date:   Tue Aug 20 01:33:43 2013 +0200

    Enable getmntinfo(3)

    Change-Id: Id9d11a67cdcad331a52030127f7c7ead3c847919

commit 907b40860983a73fe22f45aa8b175b27cb7dc1d7
Author: David van Moolenbroek <david@minix3.org>
Date:   Tue Aug 20 00:49:07 2013 +0200

    test55: add tests for getvfsstat(2)

    Change-Id: Iad4567068a82bb0e780891a478ba5a06b63f1d48

commit 3297eb8d103545690e9f2cb6c63fdd1ce3452c6d
Author: David van Moolenbroek <david@minix3.org>
Date:   Tue Aug 20 01:28:23 2013 +0200

    Implement support for [f]statvfs1(2)

    The [f]statvfs(3) calls now use [f]statvfs1(2).

    Change-Id: I56c92fe1c70670f476631c4a50e47351562712c6

commit 4f576aff9f046276974c4a769427a1cb8c2470a0
Author: David van Moolenbroek <david@minix3.org>
Date:   Tue Aug 20 01:39:47 2013 +0200

    Implement support for getvfsstat(2)

    Change-Id: I4680c071b94fa855edfb6220b03cff6b20f3c1c9

commit 53485a9b35ec2e27ec0df232d8c80db1a829246b
Author: David van Moolenbroek <david@minix3.org>
Date:   Tue Aug 20 01:37:18 2013 +0200

    Redo mount(2)/umount(2) ABI

    - pass in file system type through mount(2), and return this type in
      statvfs structures as generated by [f]statvfs(2);
    - align mount flags field with NetBSD's, splitting out service flags
      which are not to be passed to VFS;
    - remove limitation of mount ABI to 16-byte labels, so that labels
      can be made larger in the future;
    - introduce new m11 message union type for mount(2) as side effect.

    Change-Id: Ia9ed4566d88af5239749c57274312be26bb61448

commit 6ebff29307cd1bacba965d1e8dfb465b6684ccb7
Author: David van Moolenbroek <david@minix3.org>
Date:   Tue Aug 20 01:35:35 2013 +0200

    Align "struct statvfs" with NetBSD

    This is a requirement for implementing calls such as getmntinfo(3).
    VFS is now responsible for filling in some of the structure's fields.

    Change-Id: I457b463c70ea2f326b9c50de954a91cfefba0065

commit 9b5871fd21d37b0533b6546c408ff4ad4ae02952
Author: David van Moolenbroek <david@minix3.org>
Date:   Tue Aug 20 00:55:49 2013 +0200

    VFS/FS: remove fstatfs(2) and REQ_FSTATFS

    The fstatfs(3) call now uses fstatvfs(2).

    Change-Id: Ic6bbb040e1a8f01aaffe1a6a809dd4c7a2eae2f6

Change-Id: I44109a83fd9155f15a8b580e9471ed1aff952673
2013-11-05 18:25:04 +01:00

3173 lines
70 KiB
Groff
Raw Blame History

.\" $Vendor-Id: mdoc.7,v 1.214 2012/01/03 10:18:05 kristaps Exp $
.\"
.\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
.\" Copyright (c) 2010, 2011 Ingo Schwarze <schwarze@openbsd.org>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd January 3, 2012
.Dt MDOC 7
.Os
.Sh NAME
.Nm mdoc
.Nd semantic markup language for formatting manual pages
.Sh DESCRIPTION
The
.Nm mdoc
language supports authoring of manual pages for the
.Xr man 1
utility by allowing semantic annotations of words, phrases,
page sections and complete manual pages.
Such annotations are used by formatting tools to achieve a uniform
presentation across all manuals written in
.Nm ,
and to support hyperlinking if supported by the output medium.
.Pp
This reference document describes the structure of manual pages
and the syntax and usage of the
.Nm
language.
The reference implementation of a parsing and formatting tool is
.Xr mandoc 1 ;
the
.Sx COMPATIBILITY
section describes compatibility with other implementations.
.Pp
In an
.Nm
document, lines beginning with the control character
.Sq \&.
are called
.Dq macro lines .
The first word is the macro name.
It consists of two or three letters.
Most macro names begin with a capital letter.
For a list of available macros, see
.Sx MACRO OVERVIEW .
The words following the macro name are arguments to the macro, optionally
including the names of other, callable macros; see
.Sx MACRO SYNTAX
for details.
.Pp
Lines not beginning with the control character are called
.Dq text lines .
They provide free-form text to be printed; the formatting of the text
depends on the respective processing context:
.Bd -literal -offset indent
\&.Sh Macro lines change control state.
Text lines are interpreted within the current state.
.Ed
.Pp
Many aspects of the basic syntax of the
.Nm
language are based on the
.Xr roff 7
language; see the
.Em LANGUAGE SYNTAX
and
.Em MACRO SYNTAX
sections in the
.Xr roff 7
manual for details, in particular regarding
comments, escape sequences, whitespace, and quoting.
However, using
.Xr roff 7
requests in
.Nm
documents is discouraged;
.Xr mandoc 1
supports some of them merely for backward compatibility.
.Sh MANUAL STRUCTURE
A well-formed
.Nm
document consists of a document prologue followed by one or more
sections.
.Pp
The prologue, which consists of the
.Sx \&Dd ,
.Sx \&Dt ,
and
.Sx \&Os
macros in that order, is required for every document.
.Pp
The first section (sections are denoted by
.Sx \&Sh )
must be the NAME section, consisting of at least one
.Sx \&Nm
followed by
.Sx \&Nd .
.Pp
Following that, convention dictates specifying at least the
.Em SYNOPSIS
and
.Em DESCRIPTION
sections, although this varies between manual sections.
.Pp
The following is a well-formed skeleton
.Nm
file for a utility
.Qq progname :
.Bd -literal -offset indent
\&.Dd $\&Mdocdate$
\&.Dt PROGNAME section
\&.Os
\&.Sh NAME
\&.Nm progname
\&.Nd one line about what it does
\&.\e\(dq .Sh LIBRARY
\&.\e\(dq For sections 2, 3, & 9 only.
\&.\e\(dq Not used in OpenBSD.
\&.Sh SYNOPSIS
\&.Nm progname
\&.Op Fl options
\&.Ar
\&.Sh DESCRIPTION
The
\&.Nm
utility processes files ...
\&.\e\(dq .Sh IMPLEMENTATION NOTES
\&.\e\(dq Not used in OpenBSD.
\&.\e\(dq .Sh RETURN VALUES
\&.\e\(dq For sections 2, 3, & 9 only.
\&.\e\(dq .Sh ENVIRONMENT
\&.\e\(dq For sections 1, 6, 7, & 8 only.
\&.\e\(dq .Sh FILES
\&.\e\(dq .Sh EXIT STATUS
\&.\e\(dq For sections 1, 6, & 8 only.
\&.\e\(dq .Sh EXAMPLES
\&.\e\(dq .Sh DIAGNOSTICS
\&.\e\(dq For sections 1, 4, 6, 7, & 8 only.
\&.\e\(dq .Sh ERRORS
\&.\e\(dq For sections 2, 3, & 9 only.
\&.\e\(dq .Sh SEE ALSO
\&.\e\(dq .Xr foobar 1
\&.\e\(dq .Sh STANDARDS
\&.\e\(dq .Sh HISTORY
\&.\e\(dq .Sh AUTHORS
\&.\e\(dq .Sh CAVEATS
\&.\e\(dq .Sh BUGS
\&.\e\(dq .Sh SECURITY CONSIDERATIONS
\&.\e\(dq Not used in OpenBSD.
.Ed
.Pp
The sections in an
.Nm
document are conventionally ordered as they appear above.
Sections should be composed as follows:
.Bl -ohang -offset Ds
.It Em NAME
The name(s) and a one line description of the documented material.
The syntax for this as follows:
.Bd -literal -offset indent
\&.Nm name0 ,
\&.Nm name1 ,
\&.Nm name2
\&.Nd a one line description
.Ed
.Pp
Multiple
.Sq \&Nm
names should be separated by commas.
.Pp
The
.Sx \&Nm
macro(s) must precede the
.Sx \&Nd
macro.
.Pp
See
.Sx \&Nm
and
.Sx \&Nd .
.It Em LIBRARY
The name of the library containing the documented material, which is
assumed to be a function in a section 2, 3, or 9 manual.
The syntax for this is as follows:
.Bd -literal -offset indent
\&.Lb libarm
.Ed
.Pp
See
.Sx \&Lb .
.It Em SYNOPSIS
Documents the utility invocation syntax, function call syntax, or device
configuration.
.Pp
For the first, utilities (sections 1, 6, and 8), this is
generally structured as follows:
.Bd -literal -offset indent
\&.Nm bar
\&.Op Fl v
\&.Op Fl o Ar file
\&.Op Ar
\&.Nm foo
\&.Op Fl v
\&.Op Fl o Ar file
\&.Op Ar
.Ed
.Pp
Commands should be ordered alphabetically.
.Pp
For the second, function calls (sections 2, 3, 9):
.Bd -literal -offset indent
\&.In header.h
\&.Vt extern const char *global;
\&.Ft "char *"
\&.Fn foo "const char *src"
\&.Ft "char *"
\&.Fn bar "const char *src"
.Ed
.Pp
Ordering of
.Sx \&In ,
.Sx \&Vt ,
.Sx \&Fn ,
and
.Sx \&Fo
macros should follow C header-file conventions.
.Pp
And for the third, configurations (section 4):
.Bd -literal -offset indent
\&.Cd \(dqit* at isa? port 0x2e\(dq
\&.Cd \(dqit* at isa? port 0x4e\(dq
.Ed
.Pp
Manuals not in these sections generally don't need a
.Em SYNOPSIS .
.Pp
Some macros are displayed differently in the
.Em SYNOPSIS
section, particularly
.Sx \&Nm ,
.Sx \&Cd ,
.Sx \&Fd ,
.Sx \&Fn ,
.Sx \&Fo ,
.Sx \&In ,
.Sx \&Vt ,
and
.Sx \&Ft .
All of these macros are output on their own line.
If two such dissimilar macros are pairwise invoked (except for
.Sx \&Ft
before
.Sx \&Fo
or
.Sx \&Fn ) ,
they are separated by a vertical space, unless in the case of
.Sx \&Fo ,
.Sx \&Fn ,
and
.Sx \&Ft ,
which are always separated by vertical space.
.Pp
When text and macros following an
.Sx \&Nm
macro starting an input line span multiple output lines,
all output lines but the first will be indented to align
with the text immediately following the
.Sx \&Nm
macro, up to the next
.Sx \&Nm ,
.Sx \&Sh ,
or
.Sx \&Ss
macro or the end of an enclosing block, whichever comes first.
.It Em DESCRIPTION
This begins with an expansion of the brief, one line description in
.Em NAME :
.Bd -literal -offset indent
The
\&.Nm
utility does this, that, and the other.
.Ed
.Pp
It usually follows with a breakdown of the options (if documenting a
command), such as:
.Bd -literal -offset indent
The arguments are as follows:
\&.Bl \-tag \-width Ds
\&.It Fl v
Print verbose information.
\&.El
.Ed
.Pp
Manuals not documenting a command won't include the above fragment.
.Pp
Since the
.Em DESCRIPTION
section usually contains most of the text of a manual, longer manuals
often use the
.Sx \&Ss
macro to form subsections.
In very long manuals, the
.Em DESCRIPTION
may be split into multiple sections, each started by an
.Sx \&Sh
macro followed by a non-standard section name, and each having
several subsections, like in the present
.Nm
manual.
.It Em IMPLEMENTATION NOTES
Implementation-specific notes should be kept here.
This is useful when implementing standard functions that may have side
effects or notable algorithmic implications.
.It Em RETURN VALUES
This section documents the
return values of functions in sections 2, 3, and 9.
.Pp
See
.Sx \&Rv .
.It Em ENVIRONMENT
Lists the environment variables used by the utility,
and explains the syntax and semantics of their values.
The
.Xr environ 7
manual provides examples of typical content and formatting.
.Pp
See
.Sx \&Ev .
.It Em FILES
Documents files used.
It's helpful to document both the file name and a short description of how
the file is used (created, modified, etc.).
.Pp
See
.Sx \&Pa .
.It Em EXIT STATUS
This section documents the
command exit status for section 1, 6, and 8 utilities.
Historically, this information was described in
.Em DIAGNOSTICS ,
a practise that is now discouraged.
.Pp
See
.Sx \&Ex .
.It Em EXAMPLES
Example usages.
This often contains snippets of well-formed, well-tested invocations.
Make sure that examples work properly!
.It Em DIAGNOSTICS
Documents error conditions.
This is most useful in section 4 manuals.
Historically, this section was used in place of
.Em EXIT STATUS
for manuals in sections 1, 6, and 8; however, this practise is
discouraged.
.Pp
See
.Sx \&Bl
.Fl diag .
.It Em ERRORS
Documents error handling in sections 2, 3, and 9.
.Pp
See
.Sx \&Er .
.It Em SEE ALSO
References other manuals with related topics.
This section should exist for most manuals.
Cross-references should conventionally be ordered first by section, then
alphabetically.
.Pp
References to other documentation concerning the topic of the manual page,
for example authoritative books or journal articles, may also be
provided in this section.
.Pp
See
.Sx \&Rs
and
.Sx \&Xr .
.It Em STANDARDS
References any standards implemented or used.
If not adhering to any standards, the
.Em HISTORY
section should be used instead.
.Pp
See
.Sx \&St .
.It Em HISTORY
A brief history of the subject, including where it was first implemented,
and when it was ported to or reimplemented for the operating system at hand.
.It Em AUTHORS
Credits to the person or persons who wrote the code and/or documentation.
Authors should generally be noted by both name and email address.
.Pp
See
.Sx \&An .
.It Em CAVEATS
Common misuses and misunderstandings should be explained
in this section.
.It Em BUGS
Known bugs, limitations, and work-arounds should be described
in this section.
.It Em SECURITY CONSIDERATIONS
Documents any security precautions that operators should consider.
.El
.Sh MACRO OVERVIEW
This overview is sorted such that macros of similar purpose are listed
together, to help find the best macro for any given purpose.
Deprecated macros are not included in the overview, but can be found below
in the alphabetical
.Sx MACRO REFERENCE .
.Ss Document preamble and NAME section macros
.Bl -column "Brq, Bro, Brc" description
.It Sx \&Dd Ta document date: Cm $\&Mdocdate$ | Ar month day , year
.It Sx \&Dt Ta document title: Ar TITLE section Op Ar volume | arch
.It Sx \&Os Ta operating system version: Op Ar system Op Ar version
.It Sx \&Nm Ta document name (one argument)
.It Sx \&Nd Ta document description (one line)
.El
.Ss Sections and cross references
.Bl -column "Brq, Bro, Brc" description
.It Sx \&Sh Ta section header (one line)
.It Sx \&Ss Ta subsection header (one line)
.It Sx \&Sx Ta internal cross reference to a section or subsection
.It Sx \&Xr Ta cross reference to another manual page: Ar name section
.It Sx \&Pp , \&Lp Ta start a text paragraph (no arguments)
.El
.Ss Displays and lists
.Bl -column "Brq, Bro, Brc" description
.It Sx \&Bd , \&Ed Ta display block:
.Fl Ar type
.Op Fl offset Ar width
.Op Fl compact
.It Sx \&D1 Ta indented display (one line)
.It Sx \&Dl Ta indented literal display (one line)
.It Sx \&Bl , \&El Ta list block:
.Fl Ar type
.Op Fl width Ar val
.Op Fl offset Ar val
.Op Fl compact
.It Sx \&It Ta list item (syntax depends on Fl Ar type )
.It Sx \&Ta Ta table cell separator in Sx \&Bl Fl column No lists
.It Sx \&Rs , \&%* , \&Re Ta bibliographic block (references)
.El
.Ss Spacing control
.Bl -column "Brq, Bro, Brc" description
.It Sx \&Pf Ta prefix, no following horizontal space (one argument)
.It Sx \&Ns Ta roman font, no preceding horizontal space (no arguments)
.It Sx \&Ap Ta apostrophe without surrounding whitespace (no arguments)
.It Sx \&Sm Ta switch horizontal spacing mode: Cm on | off
.It Sx \&Bk , \&Ek Ta keep block: Fl words
.It Sx \&br Ta force output line break in text mode (no arguments)
.It Sx \&sp Ta force vertical space: Op Ar height
.El
.Ss Semantic markup for command line utilities:
.Bl -column "Brq, Bro, Brc" description
.It Sx \&Nm Ta start a SYNOPSIS block with the name of a utility
.It Sx \&Fl Ta command line options (flags) (>=0 arguments)
.It Sx \&Cm Ta command modifier (>0 arguments)
.It Sx \&Ar Ta command arguments (>=0 arguments)
.It Sx \&Op , \&Oo , \&Oc Ta optional syntax elements (enclosure)
.It Sx \&Ic Ta internal or interactive command (>0 arguments)
.It Sx \&Ev Ta environmental variable (>0 arguments)
.It Sx \&Pa Ta file system path (>=0 arguments)
.El
.Ss Semantic markup for function libraries:
.Bl -column "Brq, Bro, Brc" description
.It Sx \&Lb Ta function library (one argument)
.It Sx \&In Ta include file (one argument)
.It Sx \&Ft Ta function type (>0 arguments)
.It Sx \&Fo , \&Fc Ta function block: Ar funcname
.It Sx \&Fn Ta function name:
.Op Ar functype
.Ar funcname
.Oo
.Op Ar argtype
.Ar argname
.Oc
.It Sx \&Fa Ta function argument (>0 arguments)
.It Sx \&Vt Ta variable type (>0 arguments)
.It Sx \&Va Ta variable name (>0 arguments)
.It Sx \&Dv Ta defined variable or preprocessor constant (>0 arguments)
.It Sx \&Er Ta error constant (>0 arguments)
.It Sx \&Ev Ta environmental variable (>0 arguments)
.El
.Ss Various semantic markup:
.Bl -column "Brq, Bro, Brc" description
.It Sx \&An Ta author name (>0 arguments)
.It Sx \&Lk Ta hyperlink: Ar uri Op Ar name
.It Sx \&Mt Ta Do mailto Dc hyperlink: Ar address
.It Sx \&Cd Ta kernel configuration declaration (>0 arguments)
.It Sx \&Ad Ta memory address (>0 arguments)
.It Sx \&Ms Ta mathematical symbol (>0 arguments)
.It Sx \&Tn Ta tradename (>0 arguments)
.El
.Ss Physical markup
.Bl -column "Brq, Bro, Brc" description
.It Sx \&Em Ta italic font or underline (emphasis) (>0 arguments)
.It Sx \&Sy Ta boldface font (symbolic) (>0 arguments)
.It Sx \&Li Ta typewriter font (literal) (>0 arguments)
.It Sx \&No Ta return to roman font (normal) (no arguments)
.It Sx \&Bf , \&Ef Ta font block:
.Op Fl Ar type | Cm \&Em | \&Li | \&Sy
.El
.Ss Physical enclosures
.Bl -column "Brq, Bro, Brc" description
.It Sx \&Dq , \&Do , \&Dc Ta enclose in typographic double quotes: Dq text
.It Sx \&Qq , \&Qo , \&Qc Ta enclose in typewriter double quotes: Qq text
.It Sx \&Sq , \&So , \&Sc Ta enclose in single quotes: Sq text
.It Sx \&Ql Ta single-quoted literal text: Ql text
.It Sx \&Pq , \&Po , \&Pc Ta enclose in parentheses: Pq text
.It Sx \&Bq , \&Bo , \&Bc Ta enclose in square brackets: Bq text
.It Sx \&Brq , \&Bro , \&Brc Ta enclose in curly braces: Brq text
.It Sx \&Aq , \&Ao , \&Ac Ta enclose in angle brackets: Aq text
.It Sx \&Eo , \&Ec Ta generic enclosure
.El
.Ss Text production
.Bl -column "Brq, Bro, Brc" description
.It Sx \&Ex Fl std Ta standard command exit values: Op Ar utility ...
.It Sx \&Rv Fl std Ta standard function return values: Op Ar function ...
.It Sx \&St Ta reference to a standards document (one argument)
.It Sx \&Ux Ta Ux
.It Sx \&At Ta At
.It Sx \&Bx Ta Bx
.It Sx \&Bsx Ta Bsx
.It Sx \&Nx Ta Nx
.It Sx \&Fx Ta Fx
.It Sx \&Ox Ta Ox
.It Sx \&Dx Ta Dx
.El
.Sh MACRO REFERENCE
This section is a canonical reference of all macros, arranged
alphabetically.
For the scoping of individual macros, see
.Sx MACRO SYNTAX .
.Ss \&%A
Author name of an
.Sx \&Rs
block.
Multiple authors should each be accorded their own
.Sx \%%A
line.
Author names should be ordered with full or abbreviated forename(s)
first, then full surname.
.Ss \&%B
Book title of an
.Sx \&Rs
block.
This macro may also be used in a non-bibliographic context when
referring to book titles.
.Ss \&%C
Publication city or location of an
.Sx \&Rs
block.
.Ss \&%D
Publication date of an
.Sx \&Rs
block.
Recommended formats of arguments are
.Ar month day , year
or just
.Ar year .
.Ss \&%I
Publisher or issuer name of an
.Sx \&Rs
block.
.Ss \&%J
Journal name of an
.Sx \&Rs
block.
.Ss \&%N
Issue number (usually for journals) of an
.Sx \&Rs
block.
.Ss \&%O
Optional information of an
.Sx \&Rs
block.
.Ss \&%P
Book or journal page number of an
.Sx \&Rs
block.
.Ss \&%Q
Institutional author (school, government, etc.) of an
.Sx \&Rs
block.
Multiple institutional authors should each be accorded their own
.Sx \&%Q
line.
.Ss \&%R
Technical report name of an
.Sx \&Rs
block.
.Ss \&%T
Article title of an
.Sx \&Rs
block.
This macro may also be used in a non-bibliographical context when
referring to article titles.
.Ss \&%U
URI of reference document.
.Ss \&%V
Volume number of an
.Sx \&Rs
block.
.Ss \&Ac
Close an
.Sx \&Ao
block.
Does not have any tail arguments.
.Ss \&Ad
Memory address.
Do not use this for postal addresses.
.Pp
Examples:
.Dl \&.Ad [0,$]
.Dl \&.Ad 0x00000000
.Ss \&An
Author name.
Can be used both for the authors of the program, function, or driver
documented in the manual, or for the authors of the manual itself.
Requires either the name of an author or one of the following arguments:
.Pp
.Bl -tag -width "-nosplitX" -offset indent -compact
.It Fl split
Start a new output line before each subsequent invocation of
.Sx \&An .
.It Fl nosplit
The opposite of
.Fl split .
.El
.Pp
The default is
.Fl nosplit .
The effect of selecting either of the
.Fl split
modes ends at the beginning of the
.Em AUTHORS
section.
In the
.Em AUTHORS
section, the default is
.Fl nosplit
for the first author listing and
.Fl split
for all other author listings.
.Pp
Examples:
.Dl \&.An -nosplit
.Dl \&.An Kristaps Dzonsons \&Aq kristaps@bsd.lv
.Ss \&Ao
Begin a block enclosed by angle brackets.
Does not have any head arguments.
.Pp
Examples:
.Dl \&.Fl -key= \&Ns \&Ao \&Ar val \&Ac
.Pp
See also
.Sx \&Aq .
.Ss \&Ap
Inserts an apostrophe without any surrounding whitespace.
This is generally used as a grammatical device when referring to the verb
form of a function.
.Pp
Examples:
.Dl \&.Fn execve \&Ap d
.Ss \&Aq
Encloses its arguments in angle brackets.
.Pp
Examples:
.Dl \&.Fl -key= \&Ns \&Aq \&Ar val
.Pp
.Em Remarks :
this macro is often abused for rendering URIs, which should instead use
.Sx \&Lk
or
.Sx \&Mt ,
or to note pre-processor
.Dq Li #include
statements, which should use
.Sx \&In .
.Pp
See also
.Sx \&Ao .
.Ss \&Ar
Command arguments.
If an argument is not provided, the string
.Dq file ...\&
is used as a default.
.Pp
Examples:
.Dl ".Fl o Ar file"
.Dl ".Ar"
.Dl ".Ar arg1 , arg2 ."
.Pp
The arguments to the
.Sx \&Ar
macro are names and placeholders for command arguments;
for fixed strings to be passed verbatim as arguments, use
.Sx \&Fl
or
.Sx \&Cm .
.Ss \&At
Formats an AT&T version.
Accepts one optional argument:
.Pp
.Bl -tag -width "v[1-7] | 32vX" -offset indent -compact
.It Cm v[1-7] | 32v
A version of
.At .
.It Cm III
.At III .
.It Cm V[.[1-4]]?
A version of
.At V .
.El
.Pp
Note that these arguments do not begin with a hyphen.
.Pp
Examples:
.Dl \&.At
.Dl \&.At III
.Dl \&.At V.1
.Pp
See also
.Sx \&Bsx ,
.Sx \&Bx ,
.Sx \&Dx ,
.Sx \&Fx ,
.Sx \&Nx ,
.Sx \&Ox ,
and
.Sx \&Ux .
.Ss \&Bc
Close a
.Sx \&Bo
block.
Does not have any tail arguments.
.Ss \&Bd
Begin a display block.
Its syntax is as follows:
.Bd -ragged -offset indent
.Pf \. Sx \&Bd
.Fl Ns Ar type
.Op Fl offset Ar width
.Op Fl compact
.Ed
.Pp
Display blocks are used to select a different indentation and
justification than the one used by the surrounding text.
They may contain both macro lines and text lines.
By default, a display block is preceded by a vertical space.
.Pp
The
.Ar type
must be one of the following:
.Bl -tag -width 13n -offset indent
.It Fl centered
Produce one output line from each input line, and centre-justify each line.
Using this display type is not recommended; many
.Nm
implementations render it poorly.
.It Fl filled
Change the positions of line breaks to fill each line, and left- and
right-justify the resulting block.
.It Fl literal
Produce one output line from each input line,
and do not justify the block at all.
Preserve white space as it appears in the input.
Always use a constant-width font.
Use this for displaying source code.
.It Fl ragged
Change the positions of line breaks to fill each line, and left-justify
the resulting block.
.It Fl unfilled
The same as
.Fl literal ,
but using the same font as for normal text, which is a variable width font
if supported by the output device.
.El
.Pp
The
.Ar type
must be provided first.
Additional arguments may follow:
.Bl -tag -width 13n -offset indent
.It Fl offset Ar width
Indent the display by the
.Ar width ,
which may be one of the following:
.Bl -item
.It
One of the pre-defined strings
.Cm indent ,
the width of a standard indentation (six constant width characters);
.Cm indent-two ,
twice
.Cm indent ;
.Cm left ,
which has no effect;
.Cm right ,
which justifies to the right margin; or
.Cm center ,
which aligns around an imagined centre axis.
.It
A macro invocation, which selects a predefined width
associated with that macro.
The most popular is the imaginary macro
.Ar \&Ds ,
which resolves to
.Sy 6n .
.It
A width using the syntax described in
.Sx Scaling Widths .
.It
An arbitrary string, which indents by the length of this string.
.El
.Pp
When the argument is missing,
.Fl offset
is ignored.
.It Fl compact
Do not assert vertical space before the display.
.El
.Pp
Examples:
.Bd -literal -offset indent
\&.Bd \-literal \-offset indent \-compact
Hello world.
\&.Ed
.Ed
.Pp
See also
.Sx \&D1
and
.Sx \&Dl .
.Ss \&Bf
Change the font mode for a scoped block of text.
Its syntax is as follows:
.Bd -ragged -offset indent
.Pf \. Sx \&Bf
.Oo
.Fl emphasis | literal | symbolic |
.Cm \&Em | \&Li | \&Sy
.Oc
.Ed
.Pp
The
.Fl emphasis
and
.Cm \&Em
argument are equivalent, as are
.Fl symbolic
and
.Cm \&Sy ,
and
.Fl literal
and
.Cm \&Li .
Without an argument, this macro does nothing.
The font mode continues until broken by a new font mode in a nested
scope or
.Sx \&Ef
is encountered.
.Pp
See also
.Sx \&Li ,
.Sx \&Ef ,
.Sx \&Em ,
and
.Sx \&Sy .
.Ss \&Bk
For each macro, keep its output together on the same output line,
until the end of the macro or the end of the input line is reached,
whichever comes first.
Line breaks in text lines are unaffected.
The syntax is as follows:
.Pp
.D1 Pf \. Sx \&Bk Fl words
.Pp
The
.Fl words
argument is required; additional arguments are ignored.
.Pp
The following example will not break within each
.Sx \&Op
macro line:
.Bd -literal -offset indent
\&.Bk \-words
\&.Op Fl f Ar flags
\&.Op Fl o Ar output
\&.Ek
.Ed
.Pp
Be careful in using over-long lines within a keep block!
Doing so will clobber the right margin.
.Ss \&Bl
Begin a list.
Lists consist of items specified using the
.Sx \&It
macro, containing a head or a body or both.
The list syntax is as follows:
.Bd -ragged -offset indent
.Pf \. Sx \&Bl
.Fl Ns Ar type
.Op Fl width Ar val
.Op Fl offset Ar val
.Op Fl compact
.Op HEAD ...
.Ed
.Pp
The list
.Ar type
is mandatory and must be specified first.
The
.Fl width
and
.Fl offset
arguments accept
.Sx Scaling Widths
or use the length of the given string.
The
.Fl offset
is a global indentation for the whole list, affecting both item heads
and bodies.
For those list types supporting it, the
.Fl width
argument requests an additional indentation of item bodies,
to be added to the
.Fl offset .
Unless the
.Fl compact
argument is specified, list entries are separated by vertical space.
.Pp
A list must specify one of the following list types:
.Bl -tag -width 12n -offset indent
.It Fl bullet
No item heads can be specified, but a bullet will be printed at the head
of each item.
Item bodies start on the same output line as the bullet
and are indented according to the
.Fl width
argument.
.It Fl column
A columnated list.
The
.Fl width
argument has no effect; instead, each argument specifies the width
of one column, using either the
.Sx Scaling Widths
syntax or the string length of the argument.
If the first line of the body of a
.Fl column
list is not an
.Sx \&It
macro line,
.Sx \&It
contexts spanning one input line each are implied until an
.Sx \&It
macro line is encountered, at which point items start being interpreted as
described in the
.Sx \&It
documentation.
.It Fl dash
Like
.Fl bullet ,
except that dashes are used in place of bullets.
.It Fl diag
Like
.Fl inset ,
except that item heads are not parsed for macro invocations.
Most often used in the
.Em DIAGNOSTICS
section with error constants in the item heads.
.It Fl enum
A numbered list.
No item heads can be specified.
Formatted like
.Fl bullet ,
except that cardinal numbers are used in place of bullets,
starting at 1.
.It Fl hang
Like
.Fl tag ,
except that the first lines of item bodies are not indented, but follow
the item heads like in
.Fl inset
lists.
.It Fl hyphen
Synonym for
.Fl dash .
.It Fl inset
Item bodies follow items heads on the same line, using normal inter-word
spacing.
Bodies are not indented, and the
.Fl width
argument is ignored.
.It Fl item
No item heads can be specified, and none are printed.
Bodies are not indented, and the
.Fl width
argument is ignored.
.It Fl ohang
Item bodies start on the line following item heads and are not indented.
The
.Fl width
argument is ignored.
.It Fl tag
Item bodies are indented according to the
.Fl width
argument.
When an item head fits inside the indentation, the item body follows
this head on the same output line.
Otherwise, the body starts on the output line following the head.
.El
.Pp
Lists may be nested within lists and displays.
Nesting of
.Fl column
and
.Fl enum
lists may not be portable.
.Pp
See also
.Sx \&El
and
.Sx \&It .
.Ss \&Bo
Begin a block enclosed by square brackets.
Does not have any head arguments.
.Pp
Examples:
.Bd -literal -offset indent -compact
\&.Bo 1 ,
\&.Dv BUFSIZ \&Bc
.Ed
.Pp
See also
.Sx \&Bq .
.Ss \&Bq
Encloses its arguments in square brackets.
.Pp
Examples:
.Dl \&.Bq 1 , \&Dv BUFSIZ
.Pp
.Em Remarks :
this macro is sometimes abused to emulate optional arguments for
commands; the correct macros to use for this purpose are
.Sx \&Op ,
.Sx \&Oo ,
and
.Sx \&Oc .
.Pp
See also
.Sx \&Bo .
.Ss \&Brc
Close a
.Sx \&Bro
block.
Does not have any tail arguments.
.Ss \&Bro
Begin a block enclosed by curly braces.
Does not have any head arguments.
.Pp
Examples:
.Bd -literal -offset indent -compact
\&.Bro 1 , ... ,
\&.Va n \&Brc
.Ed
.Pp
See also
.Sx \&Brq .
.Ss \&Brq
Encloses its arguments in curly braces.
.Pp
Examples:
.Dl \&.Brq 1 , ... , \&Va n
.Pp
See also
.Sx \&Bro .
.Ss \&Bsx
Format the BSD/OS version provided as an argument, or a default value if
no argument is provided.
.Pp
Examples:
.Dl \&.Bsx 1.0
.Dl \&.Bsx
.Pp
See also
.Sx \&At ,
.Sx \&Bx ,
.Sx \&Dx ,
.Sx \&Fx ,
.Sx \&Nx ,
.Sx \&Ox ,
and
.Sx \&Ux .
.Ss \&Bt
Prints
.Dq is currently in beta test.
.Ss \&Bx
Format the BSD version provided as an argument, or a default value if no
argument is provided.
.Pp
Examples:
.Dl \&.Bx 4.3 Tahoe
.Dl \&.Bx 4.4
.Dl \&.Bx
.Pp
See also
.Sx \&At ,
.Sx \&Bsx ,
.Sx \&Dx ,
.Sx \&Fx ,
.Sx \&Nx ,
.Sx \&Ox ,
and
.Sx \&Ux .
.Ss \&Cd
Kernel configuration declaration.
This denotes strings accepted by
.Xr config 8 .
It is most often used in section 4 manual pages.
.Pp
Examples:
.Dl \&.Cd device le0 at scode?
.Pp
.Em Remarks :
this macro is commonly abused by using quoted literals to retain
whitespace and align consecutive
.Sx \&Cd
declarations.
This practise is discouraged.
.Ss \&Cm
Command modifiers.
Typically used for fixed strings passed as arguments, unless
.Sx \&Fl
is more appropriate.
Also useful when specifying configuration options or keys.
.Pp
Examples:
.Dl ".Nm mt Fl f Ar device Cm rewind"
.Dl ".Nm ps Fl o Cm pid , Ns Cm command"
.Dl ".Nm dd Cm if= Ns Ar file1 Cm of= Ns Ar file2"
.Dl ".Cm IdentityFile Pa ~/.ssh/id_rsa"
.Dl ".Cm LogLevel Dv DEBUG"
.Ss \&D1
One-line indented display.
This is formatted by the default rules and is useful for simple indented
statements.
It is followed by a newline.
.Pp
Examples:
.Dl \&.D1 \&Fl abcdefgh
.Pp
See also
.Sx \&Bd
and
.Sx \&Dl .
.Ss \&Db
Switch debugging mode.
Its syntax is as follows:
.Pp
.D1 Pf \. Sx \&Db Cm on | off
.Pp
This macro is ignored by
.Xr mandoc 1 .
.Ss \&Dc
Close a
.Sx \&Do
block.
Does not have any tail arguments.
.Ss \&Dd
Document date.
This is the mandatory first macro of any
.Nm
manual.
Its syntax is as follows:
.Pp
.D1 Pf \. Sx \&Dd Ar month day , year
.Pp
The
.Ar month
is the full English month name, the
.Ar day
is an optionally zero-padded numeral, and the
.Ar year
is the full four-digit year.
.Pp
Other arguments are not portable; the
.Xr mandoc 1
utility handles them as follows:
.Bl -dash -offset 3n -compact
.It
To have the date automatically filled in by the
.Ox
version of
.Xr cvs 1 ,
the special string
.Dq $\&Mdocdate$
can be given as an argument.
.It
A few alternative date formats are accepted as well
and converted to the standard form.
.It
If a date string cannot be parsed, it is used verbatim.
.It
If no date string is given, the current date is used.
.El
.Pp
Examples:
.Dl \&.Dd $\&Mdocdate$
.Dl \&.Dd $\&Mdocdate: July 21 2007$
.Dl \&.Dd July 21, 2007
.Pp
See also
.Sx \&Dt
and
.Sx \&Os .
.Ss \&Dl
One-line intended display.
This is formatted as literal text and is useful for commands and
invocations.
It is followed by a newline.
.Pp
Examples:
.Dl \&.Dl % mandoc mdoc.7 \e(ba less
.Pp
See also
.Sx \&Bd
and
.Sx \&D1 .
.Ss \&Do
Begin a block enclosed by double quotes.
Does not have any head arguments.
.Pp
Examples:
.Bd -literal -offset indent -compact
\&.Do
April is the cruellest month
\&.Dc
\e(em T.S. Eliot
.Ed
.Pp
See also
.Sx \&Dq .
.Ss \&Dq
Encloses its arguments in
.Dq typographic
double-quotes.
.Pp
Examples:
.Bd -literal -offset indent -compact
\&.Dq April is the cruellest month
\e(em T.S. Eliot
.Ed
.Pp
See also
.Sx \&Qq ,
.Sx \&Sq ,
and
.Sx \&Do .
.Ss \&Dt
Document title.
This is the mandatory second macro of any
.Nm
file.
Its syntax is as follows:
.Bd -ragged -offset indent
.Pf \. Sx \&Dt
.Oo
.Ar title
.Oo
.Ar section
.Op Ar volume
.Op Ar arch
.Oc
.Oc
.Ed
.Pp
Its arguments are as follows:
.Bl -tag -width Ds -offset Ds
.It Ar title
The document's title (name), defaulting to
.Dq UNKNOWN
if unspecified.
It should be capitalised.
.It Ar section
The manual section.
This may be one of
.Ar 1
.Pq utilities ,
.Ar 2
.Pq system calls ,
.Ar 3
.Pq libraries ,
.Ar 3p
.Pq Perl libraries ,
.Ar 4
.Pq devices ,
.Ar 5
.Pq file formats ,
.Ar 6
.Pq games ,
.Ar 7
.Pq miscellaneous ,
.Ar 8
.Pq system utilities ,
.Ar 9
.Pq kernel functions ,
.Ar X11
.Pq X Window System ,
.Ar X11R6
.Pq X Window System ,
.Ar unass
.Pq unassociated ,
.Ar local
.Pq local system ,
.Ar draft
.Pq draft manual ,
or
.Ar paper
.Pq paper .
It should correspond to the manual's filename suffix and defaults to
.Dq 1
if unspecified.
.It Ar volume
This overrides the volume inferred from
.Ar section .
This field is optional, and if specified, must be one of
.Ar USD
.Pq users' supplementary documents ,
.Ar PS1
.Pq programmers' supplementary documents ,
.Ar AMD
.Pq administrators' supplementary documents ,
.Ar SMM
.Pq system managers' manuals ,
.Ar URM
.Pq users' reference manuals ,
.Ar PRM
.Pq programmers' reference manuals ,
.Ar KM
.Pq kernel manuals ,
.Ar IND
.Pq master index ,
.Ar MMI
.Pq master index ,
.Ar LOCAL
.Pq local manuals ,
.Ar LOC
.Pq local manuals ,
or
.Ar CON
.Pq contributed manuals .
.It Ar arch
This specifies the machine architecture a manual page applies to,
where relevant, for example
.Cm alpha ,
.Cm amd64 ,
.Cm i386 ,
or
.Cm sparc64 .
The list of supported architectures varies by operating system.
For the full list of all architectures recognized by
.Xr mandoc 1 ,
see the file
.Pa arch.in
in the source distribution.
.El
.Pp
Examples:
.Dl \&.Dt FOO 1
.Dl \&.Dt FOO 4 KM
.Dl \&.Dt FOO 9 i386
.Pp
See also
.Sx \&Dd
and
.Sx \&Os .
.Ss \&Dv
Defined variables such as preprocessor constants, constant symbols,
enumeration values, and so on.
.Pp
Examples:
.Dl \&.Dv NULL
.Dl \&.Dv BUFSIZ
.Dl \&.Dv STDOUT_FILENO
.Pp
See also
.Sx \&Er
and
.Sx \&Ev
for special-purpose constants and
.Sx \&Va
for variable symbols.
.Ss \&Dx
Format the DragonFly BSD version provided as an argument, or a default
value if no argument is provided.
.Pp
Examples:
.Dl \&.Dx 2.4.1
.Dl \&.Dx
.Pp
See also
.Sx \&At ,
.Sx \&Bsx ,
.Sx \&Bx ,
.Sx \&Fx ,
.Sx \&Nx ,
.Sx \&Ox ,
and
.Sx \&Ux .
.Ss \&Ec
Close a scope started by
.Sx \&Eo .
Its syntax is as follows:
.Pp
.D1 Pf \. Sx \&Ec Op Ar TERM
.Pp
The
.Ar TERM
argument is used as the enclosure tail, for example, specifying \e(rq
will emulate
.Sx \&Dc .
.Ss \&Ed
End a display context started by
.Sx \&Bd .
.Ss \&Ef
End a font mode context started by
.Sx \&Bf .
.Ss \&Ek
End a keep context started by
.Sx \&Bk .
.Ss \&El
End a list context started by
.Sx \&Bl .
.Pp
See also
.Sx \&Bl
and
.Sx \&It .
.Ss \&Em
Denotes text that should be
.Em emphasised .
Note that this is a presentation term and should not be used for
stylistically decorating technical terms.
Depending on the output device, this is usually represented
using an italic font or underlined characters.
.Pp
Examples:
.Dl \&.Em Warnings!
.Dl \&.Em Remarks :
.Pp
See also
.Sx \&Bf ,
.Sx \&Li ,
.Sx \&No ,
and
.Sx \&Sy .
.Ss \&En
This macro is obsolete and not implemented in
.Xr mandoc 1 .
.Ss \&Eo
An arbitrary enclosure.
Its syntax is as follows:
.Pp
.D1 Pf \. Sx \&Eo Op Ar TERM
.Pp
The
.Ar TERM
argument is used as the enclosure head, for example, specifying \e(lq
will emulate
.Sx \&Do .
.Ss \&Er
Error constants for definitions of the
.Va errno
libc global variable.
This is most often used in section 2 and 3 manual pages.
.Pp
Examples:
.Dl \&.Er EPERM
.Dl \&.Er ENOENT
.Pp
See also
.Sx \&Dv
for general constants.
.Ss \&Es
This macro is obsolete and not implemented.
.Ss \&Ev
Environmental variables such as those specified in
.Xr environ 7 .
.Pp
Examples:
.Dl \&.Ev DISPLAY
.Dl \&.Ev PATH
.Pp
See also
.Sx \&Dv
for general constants.
.Ss \&Ex
Insert a standard sentence regarding command exit values of 0 on success
and >0 on failure.
This is most often used in section 1, 6, and 8 manual pages.
Its syntax is as follows:
.Pp
.D1 Pf \. Sx \&Ex Fl std Op Ar utility ...
.Pp
If
.Ar utility
is not specified, the document's name set by
.Sx \&Nm
is used.
Multiple
.Ar utility
arguments are treated as separate utilities.
.Pp
See also
.Sx \&Rv .
.Ss \&Fa
Function argument.
Its syntax is as follows:
.Bd -ragged -offset indent
.Pf \. Sx \&Fa
.Op Cm argtype
.Cm argname
.Ed
.Pp
This may be invoked for names with or without the corresponding type.
It is also used to specify the field name of a structure.
Most often, the
.Sx \&Fa
macro is used in the
.Em SYNOPSIS
within
.Sx \&Fo
section when documenting multi-line function prototypes.
If invoked with multiple arguments, the arguments are separated by a
comma.
Furthermore, if the following macro is another
.Sx \&Fa ,
the last argument will also have a trailing comma.
.Pp
Examples:
.Dl \&.Fa \(dqconst char *p\(dq
.Dl \&.Fa \(dqint a\(dq \(dqint b\(dq \(dqint c\(dq
.Dl \&.Fa foo
.Pp
See also
.Sx \&Fo .
.Ss \&Fc
End a function context started by
.Sx \&Fo .
.Ss \&Fd
Historically used to document include files.
This usage has been deprecated in favour of
.Sx \&In .
Do not use this macro.
.Pp
See also
.Sx MANUAL STRUCTURE
and
.Sx \&In .
.Ss \&Fl
Command-line flag or option.
Used when listing arguments to command-line utilities.
Prints a fixed-width hyphen
.Sq \-
directly followed by each argument.
If no arguments are provided, a hyphen is printed followed by a space.
If the argument is a macro, a hyphen is prefixed to the subsequent macro
output.
.Pp
Examples:
.Dl ".Fl R Op Fl H | L | P"
.Dl ".Op Fl 1AaCcdFfgHhikLlmnopqRrSsTtux"
.Dl ".Fl type Cm d Fl name Pa CVS"
.Dl ".Fl Ar signal_number"
.Dl ".Fl o Fl"
.Pp
See also
.Sx \&Cm .
.Ss \&Fn
A function name.
Its syntax is as follows:
.Bd -ragged -offset indent
.Pf \. Ns Sx \&Fn
.Op Ar functype
.Ar funcname
.Op Oo Ar argtype Oc Ar argname
.Ed
.Pp
Function arguments are surrounded in parenthesis and
are delimited by commas.
If no arguments are specified, blank parenthesis are output.
In the
.Em SYNOPSIS
section, this macro starts a new output line,
and a blank line is automatically inserted between function definitions.
.Pp
Examples:
.Dl \&.Fn \(dqint funcname\(dq \(dqint arg0\(dq \(dqint arg1\(dq
.Dl \&.Fn funcname \(dqint arg0\(dq
.Dl \&.Fn funcname arg0
.Pp
.Bd -literal -offset indent -compact
\&.Ft functype
\&.Fn funcname
.Ed
.Pp
When referring to a function documented in another manual page, use
.Sx \&Xr
instead.
See also
.Sx MANUAL STRUCTURE ,
.Sx \&Fo ,
and
.Sx \&Ft .
.Ss \&Fo
Begin a function block.
This is a multi-line version of
.Sx \&Fn .
Its syntax is as follows:
.Pp
.D1 Pf \. Sx \&Fo Ar funcname
.Pp
Invocations usually occur in the following context:
.Bd -ragged -offset indent
.Pf \. Sx \&Ft Ar functype
.br
.Pf \. Sx \&Fo Ar funcname
.br
.Pf \. Sx \&Fa Oo Ar argtype Oc Ar argname
.br
\&.\.\.
.br
.Pf \. Sx \&Fc
.Ed
.Pp
A
.Sx \&Fo
scope is closed by
.Sx \&Fc .
.Pp
See also
.Sx MANUAL STRUCTURE ,
.Sx \&Fa ,
.Sx \&Fc ,
and
.Sx \&Ft .
.Ss \&Fr
This macro is obsolete and not implemented in
.Xr mandoc 1 .
.Pp
It was used to show function return values.
The syntax was:
.Pp
.Dl Pf . Sx \&Fr Ar value
.Ss \&Ft
A function type.
Its syntax is as follows:
.Pp
.D1 Pf \. Sx \&Ft Ar functype
.Pp
In the
.Em SYNOPSIS
section, a new output line is started after this macro.
.Pp
Examples:
.Dl \&.Ft int
.Bd -literal -offset indent -compact
\&.Ft functype
\&.Fn funcname
.Ed
.Pp
See also
.Sx MANUAL STRUCTURE ,
.Sx \&Fn ,
and
.Sx \&Fo .
.Ss \&Fx
Format the
.Fx
version provided as an argument, or a default value
if no argument is provided.
.Pp
Examples:
.Dl \&.Fx 7.1
.Dl \&.Fx
.Pp
See also
.Sx \&At ,
.Sx \&Bsx ,
.Sx \&Bx ,
.Sx \&Dx ,
.Sx \&Nx ,
.Sx \&Ox ,
and
.Sx \&Ux .
.Ss \&Hf
This macro is not implemented in
.Xr mandoc 1 .
.Pp
It was used to include the contents of a (header) file literally.
The syntax was:
.Pp
.Dl Pf . Sx \&Hf Ar filename
.Ss \&Ic
Designate an internal or interactive command.
This is similar to
.Sx \&Cm
but used for instructions rather than values.
.Pp
Examples:
.Dl \&.Ic :wq
.Dl \&.Ic hash
.Dl \&.Ic alias
.Pp
Note that using
.Sx \&Bd Fl literal
or
.Sx \&D1
is preferred for displaying code; the
.Sx \&Ic
macro is used when referring to specific instructions.
.Ss \&In
An
.Dq include
file.
When invoked as the first macro on an input line in the
.Em SYNOPSIS
section, the argument is displayed in angle brackets
and preceded by
.Dq #include ,
and a blank line is inserted in front if there is a preceding
function declaration.
This is most often used in section 2, 3, and 9 manual pages.
.Pp
Examples:
.Dl \&.In sys/types.h
.Pp
See also
.Sx MANUAL STRUCTURE .
.Ss \&It
A list item.
The syntax of this macro depends on the list type.
.Pp
Lists
of type
.Fl hang ,
.Fl ohang ,
.Fl inset ,
and
.Fl diag
have the following syntax:
.Pp
.D1 Pf \. Sx \&It Ar args
.Pp
Lists of type
.Fl bullet ,
.Fl dash ,
.Fl enum ,
.Fl hyphen
and
.Fl item
have the following syntax:
.Pp
.D1 Pf \. Sx \&It
.Pp
with subsequent lines interpreted within the scope of the
.Sx \&It
until either a closing
.Sx \&El
or another
.Sx \&It .
.Pp
The
.Fl tag
list has the following syntax:
.Pp
.D1 Pf \. Sx \&It Op Cm args
.Pp
Subsequent lines are interpreted as with
.Fl bullet
and family.
The line arguments correspond to the list's left-hand side; body
arguments correspond to the list's contents.
.Pp
The
.Fl column
list is the most complicated.
Its syntax is as follows:
.Pp
.D1 Pf \. Sx \&It Ar cell Op <TAB> Ar cell ...
.D1 Pf \. Sx \&It Ar cell Op Sx \&Ta Ar cell ...
.Pp
The arguments consist of one or more lines of text and macros
representing a complete table line.
Cells within the line are delimited by tabs or by the special
.Sx \&Ta
block macro.
The tab cell delimiter may only be used within the
.Sx \&It
line itself; on following lines, only the
.Sx \&Ta
macro can be used to delimit cells, and
.Sx \&Ta
is only recognised as a macro when called by other macros,
not as the first macro on a line.
.Pp
Note that quoted strings may span tab-delimited cells on an
.Sx \&It
line.
For example,
.Pp
.Dl .It \(dqcol1 ; <TAB> col2 ;\(dq \&;
.Pp
will preserve the semicolon whitespace except for the last.
.Pp
See also
.Sx \&Bl .
.Ss \&Lb
Specify a library.
The syntax is as follows:
.Pp
.D1 Pf \. Sx \&Lb Ar library
.Pp
The
.Ar library
parameter may be a system library, such as
.Cm libz
or
.Cm libpam ,
in which case a small library description is printed next to the linker
invocation; or a custom library, in which case the library name is
printed in quotes.
This is most commonly used in the
.Em SYNOPSIS
section as described in
.Sx MANUAL STRUCTURE .
.Pp
Examples:
.Dl \&.Lb libz
.Dl \&.Lb mdoc
.Ss \&Li
Denotes text that should be in a
.Li literal
font mode.
Note that this is a presentation term and should not be used for
stylistically decorating technical terms.
.Pp
On terminal output devices, this is often indistinguishable from
normal text.
.Pp
See also
.Sx \&Bf ,
.Sx \&Em ,
.Sx \&No ,
and
.Sx \&Sy .
.Ss \&Lk
Format a hyperlink.
Its syntax is as follows:
.Pp
.D1 Pf \. Sx \&Lk Ar uri Op Ar name
.Pp
Examples:
.Dl \&.Lk http://bsd.lv \(dqThe BSD.lv Project\(dq
.Dl \&.Lk http://bsd.lv
.Pp
See also
.Sx \&Mt .
.Ss \&Lp
Synonym for
.Sx \&Pp .
.Ss \&Ms
Display a mathematical symbol.
Its syntax is as follows:
.Pp
.D1 Pf \. Sx \&Ms Ar symbol
.Pp
Examples:
.Dl \&.Ms sigma
.Dl \&.Ms aleph
.Ss \&Mt
Format a
.Dq mailto:
hyperlink.
Its syntax is as follows:
.Pp
.D1 Pf \. Sx \&Mt Ar address
.Pp
Examples:
.Dl \&.Mt discuss@manpages.bsd.lv
.Ss \&Nd
A one line description of the manual's content.
This may only be invoked in the
.Em SYNOPSIS
section subsequent the
.Sx \&Nm
macro.
.Pp
Examples:
.Dl Pf . Sx \&Nd mdoc language reference
.Dl Pf . Sx \&Nd format and display UNIX manuals
.Pp
The
.Sx \&Nd
macro technically accepts child macros and terminates with a subsequent
.Sx \&Sh
invocation.
Do not assume this behaviour: some
.Xr whatis 1
database generators are not smart enough to parse more than the line
arguments and will display macros verbatim.
.Pp
See also
.Sx \&Nm .
.Ss \&Nm
The name of the manual page, or \(em in particular in section 1, 6,
and 8 pages \(em of an additional command or feature documented in
the manual page.
When first invoked, the
.Sx \&Nm
macro expects a single argument, the name of the manual page.
Usually, the first invocation happens in the
.Em NAME
section of the page.
The specified name will be remembered and used whenever the macro is
called again without arguments later in the page.
The
.Sx \&Nm
macro uses
.Sx Block full-implicit
semantics when invoked as the first macro on an input line in the
.Em SYNOPSIS
section; otherwise, it uses ordinary
.Sx In-line
semantics.
.Pp
Examples:
.Bd -literal -offset indent
\&.Sh SYNOPSIS
\&.Nm cat
\&.Op Fl benstuv
\&.Op Ar
.Ed
.Pp
In the
.Em SYNOPSIS
of section 2, 3 and 9 manual pages, use the
.Sx \&Fn
macro rather than
.Sx \&Nm
to mark up the name of the manual page.
.Ss \&No
Normal text.
Closes the scope of any preceding in-line macro.
When used after physical formatting macros like
.Sx \&Em
or
.Sx \&Sy ,
switches back to the standard font face and weight.
Can also be used to embed plain text strings in macro lines
using semantic annotation macros.
.Pp
Examples:
.Dl ".Em italic , Sy bold , No and roman"
.Pp
.Bd -literal -offset indent -compact
\&.Sm off
\&.Cm :C No / Ar pattern No / Ar replacement No /
\&.Sm on
.Ed
.Pp
See also
.Sx \&Em ,
.Sx \&Li ,
and
.Sx \&Sy .
.Ss \&Ns
Suppress a space between the output of the preceding macro
and the following text or macro.
Following invocation, input is interpreted as normal text
just like after an
.Sx \&No
macro.
.Pp
This has no effect when invoked at the start of a macro line.
.Pp
Examples:
.Dl ".Ar name Ns = Ns Ar value"
.Dl ".Cm :M Ns Ar pattern"
.Dl ".Fl o Ns Ar output"
.Pp
See also
.Sx \&No
and
.Sx \&Sm .
.Ss \&Nx
Format the
.Nx
version provided as an argument, or a default value if
no argument is provided.
.Pp
Examples:
.Dl \&.Nx 5.01
.Dl \&.Nx
.Pp
See also
.Sx \&At ,
.Sx \&Bsx ,
.Sx \&Bx ,
.Sx \&Dx ,
.Sx \&Fx ,
.Sx \&Ox ,
and
.Sx \&Ux .
.Ss \&Oc
Close multi-line
.Sx \&Oo
context.
.Ss \&Oo
Multi-line version of
.Sx \&Op .
.Pp
Examples:
.Bd -literal -offset indent -compact
\&.Oo
\&.Op Fl flag Ns Ar value
\&.Oc
.Ed
.Ss \&Op
Optional part of a command line.
Prints the argument(s) in brackets.
This is most often used in the
.Em SYNOPSIS
section of section 1 and 8 manual pages.
.Pp
Examples:
.Dl \&.Op \&Fl a \&Ar b
.Dl \&.Op \&Ar a | b
.Pp
See also
.Sx \&Oo .
.Ss \&Os
Document operating system version.
This is the mandatory third macro of
any
.Nm
file.
Its syntax is as follows:
.Pp
.D1 Pf \. Sx \&Os Op Ar system Op Ar version
.Pp
The optional
.Ar system
parameter specifies the relevant operating system or environment.
Left unspecified, it defaults to the local operating system version.
This is the suggested form.
.Pp
Examples:
.Dl \&.Os
.Dl \&.Os KTH/CSC/TCS
.Dl \&.Os BSD 4.3
.Pp
See also
.Sx \&Dd
and
.Sx \&Dt .
.Ss \&Ot
This macro is obsolete and not implemented in
.Xr mandoc 1 .
.Pp
Historical
.Xr mdoc 7
packages described it as
.Dq "old function type (FORTRAN)" .
.Ss \&Ox
Format the
.Ox
version provided as an argument, or a default value
if no argument is provided.
.Pp
Examples:
.Dl \&.Ox 4.5
.Dl \&.Ox
.Pp
See also
.Sx \&At ,
.Sx \&Bsx ,
.Sx \&Bx ,
.Sx \&Dx ,
.Sx \&Fx ,
.Sx \&Nx ,
and
.Sx \&Ux .
.Ss \&Pa
An absolute or relative file system path, or a file or directory name.
If an argument is not provided, the character
.Sq \(ti
is used as a default.
.Pp
Examples:
.Dl \&.Pa /usr/bin/mandoc
.Dl \&.Pa /usr/share/man/man7/mdoc.7
.Pp
See also
.Sx \&Lk .
.Ss \&Pc
Close parenthesised context opened by
.Sx \&Po .
.Ss \&Pf
Removes the space between its argument
.Pq Dq prefix
and the following macro.
Its syntax is as follows:
.Pp
.D1 .Pf Ar prefix macro arguments ...
.Pp
This is equivalent to:
.Pp
.D1 .No Ar prefix No \&Ns Ar macro arguments ...
.Pp
Examples:
.Dl ".Pf $ Ar variable_name"
.Dl ".Pf 0x Ar hex_digits"
.Pp
See also
.Sx \&Ns
and
.Sx \&Sm .
.Ss \&Po
Multi-line version of
.Sx \&Pq .
.Ss \&Pp
Break a paragraph.
This will assert vertical space between prior and subsequent macros
and/or text.
.Pp
Paragraph breaks are not needed before or after
.Sx \&Sh
or
.Sx \&Ss
macros or before displays
.Pq Sx \&Bd
or lists
.Pq Sx \&Bl
unless the
.Fl compact
flag is given.
.Ss \&Pq
Parenthesised enclosure.
.Pp
See also
.Sx \&Po .
.Ss \&Qc
Close quoted context opened by
.Sx \&Qo .
.Ss \&Ql
Format a single-quoted literal.
See also
.Sx \&Qq
and
.Sx \&Sq .
.Ss \&Qo
Multi-line version of
.Sx \&Qq .
.Ss \&Qq
Encloses its arguments in
.Qq typewriter
double-quotes.
Consider using
.Sx \&Dq .
.Pp
See also
.Sx \&Dq ,
.Sx \&Sq ,
and
.Sx \&Qo .
.Ss \&Re
Close an
.Sx \&Rs
block.
Does not have any tail arguments.
.Ss \&Rs
Begin a bibliographic
.Pq Dq reference
block.
Does not have any head arguments.
The block macro may only contain
.Sx \&%A ,
.Sx \&%B ,
.Sx \&%C ,
.Sx \&%D ,
.Sx \&%I ,
.Sx \&%J ,
.Sx \&%N ,
.Sx \&%O ,
.Sx \&%P ,
.Sx \&%Q ,
.Sx \&%R ,
.Sx \&%T ,
.Sx \&%U ,
and
.Sx \&%V
child macros (at least one must be specified).
.Pp
Examples:
.Bd -literal -offset indent -compact
\&.Rs
\&.%A J. E. Hopcroft
\&.%A J. D. Ullman
\&.%B Introduction to Automata Theory, Languages, and Computation
\&.%I Addison-Wesley
\&.%C Reading, Massachusettes
\&.%D 1979
\&.Re
.Ed
.Pp
If an
.Sx \&Rs
block is used within a SEE ALSO section, a vertical space is asserted
before the rendered output, else the block continues on the current
line.
.Ss \&Rv
Insert a standard sentence regarding a function call's return value of 0
on success and \-1 on error, with the
.Va errno
libc global variable set on error.
Its syntax is as follows:
.Pp
.D1 Pf \. Sx \&Rv Fl std Op Ar function ...
.Pp
If
.Ar function
is not specified, the document's name set by
.Sx \&Nm
is used.
Multiple
.Ar function
arguments are treated as separate functions.
.Pp
See also
.Sx \&Ex .
.Ss \&Sc
Close single-quoted context opened by
.Sx \&So .
.Ss \&Sh
Begin a new section.
For a list of conventional manual sections, see
.Sx MANUAL STRUCTURE .
These sections should be used unless it's absolutely necessary that
custom sections be used.
.Pp
Section names should be unique so that they may be keyed by
.Sx \&Sx .
Although this macro is parsed, it should not consist of child node or it
may not be linked with
.Sx \&Sx .
.Pp
See also
.Sx \&Pp ,
.Sx \&Ss ,
and
.Sx \&Sx .
.Ss \&Sm
Switches the spacing mode for output generated from macros.
Its syntax is as follows:
.Pp
.D1 Pf \. Sx \&Sm Cm on | off
.Pp
By default, spacing is
.Cm on .
When switched
.Cm off ,
no white space is inserted between macro arguments and between the
output generated from adjacent macros, but text lines
still get normal spacing between words and sentences.
.Ss \&So
Multi-line version of
.Sx \&Sq .
.Ss \&Sq
Encloses its arguments in
.Sq typewriter
single-quotes.
.Pp
See also
.Sx \&Dq ,
.Sx \&Qq ,
and
.Sx \&So .
.Ss \&Ss
Begin a new subsection.
Unlike with
.Sx \&Sh ,
there is no convention for the naming of subsections.
Except
.Em DESCRIPTION ,
the conventional sections described in
.Sx MANUAL STRUCTURE
rarely have subsections.
.Pp
Sub-section names should be unique so that they may be keyed by
.Sx \&Sx .
Although this macro is parsed, it should not consist of child node or it
may not be linked with
.Sx \&Sx .
.Pp
See also
.Sx \&Pp ,
.Sx \&Sh ,
and
.Sx \&Sx .
.Ss \&St
Replace an abbreviation for a standard with the full form.
The following standards are recognised:
.Pp
.Bl -tag -width "-p1003.1g-2000X" -compact
.It \-p1003.1-88
.St -p1003.1-88
.It \-p1003.1-90
.St -p1003.1-90
.It \-p1003.1-96
.St -p1003.1-96
.It \-p1003.1-2001
.St -p1003.1-2001
.It \-p1003.1-2004
.St -p1003.1-2004
.It \-p1003.1-2008
.St -p1003.1-2008
.It \-p1003.1
.St -p1003.1
.It \-p1003.1b
.St -p1003.1b
.It \-p1003.1b-93
.St -p1003.1b-93
.It \-p1003.1c-95
.St -p1003.1c-95
.It \-p1003.1g-2000
.St -p1003.1g-2000
.It \-p1003.1i-95
.St -p1003.1i-95
.It \-p1003.2-92
.St -p1003.2-92
.It \-p1003.2a-92
.St -p1003.2a-92
.It \-p1387.2-95
.St -p1387.2-95
.It \-p1003.2
.St -p1003.2
.It \-p1387.2
.St -p1387.2
.It \-isoC
.St -isoC
.It \-isoC-90
.St -isoC-90
.It \-isoC-amd1
.St -isoC-amd1
.It \-isoC-tcor1
.St -isoC-tcor1
.It \-isoC-tcor2
.St -isoC-tcor2
.It \-isoC-99
.St -isoC-99
.It \-isoC-2011
.St -isoC-2011
.It \-iso9945-1-90
.St -iso9945-1-90
.It \-iso9945-1-96
.St -iso9945-1-96
.It \-iso9945-2-93
.St -iso9945-2-93
.It \-ansiC
.St -ansiC
.It \-ansiC-89
.St -ansiC-89
.It \-ansiC-99
.St -ansiC-99
.It \-ieee754
.St -ieee754
.It \-iso8802-3
.St -iso8802-3
.It \-iso8601
.St -iso8601
.It \-ieee1275-94
.St -ieee1275-94
.It \-xpg3
.St -xpg3
.It \-xpg4
.St -xpg4
.It \-xpg4.2
.St -xpg4.2
.It \-xpg4.3
.St -xpg4.3
.It \-xbd5
.St -xbd5
.It \-xcu5
.St -xcu5
.It \-xsh5
.St -xsh5
.It \-xns5
.St -xns5
.It \-xns5.2
.St -xns5.2
.It \-xns5.2d2.0
.St -xns5.2d2.0
.It \-xcurses4.2
.St -xcurses4.2
.It \-susv2
.St -susv2
.It \-susv3
.St -susv3
.It \-svid4
.St -svid4
.El
.Ss \&Sx
Reference a section or subsection in the same manual page.
The referenced section or subsection name must be identical to the
enclosed argument, including whitespace.
.Pp
Examples:
.Dl \&.Sx MANUAL STRUCTURE
.Pp
See also
.Sx \&Sh
and
.Sx \&Ss .
.Ss \&Sy
Format enclosed arguments in symbolic
.Pq Dq boldface .
Note that this is a presentation term and should not be used for
stylistically decorating technical terms.
.Pp
See also
.Sx \&Bf ,
.Sx \&Em ,
.Sx \&Li ,
and
.Sx \&No .
.Ss \&Ta
Table cell separator in
.Sx \&Bl Fl column
lists; can only be used below
.Sx \&It .
.Ss \&Tn
Format a tradename.
.Pp
Since this macro is often implemented to use a small caps font,
it has historically been used for acronyms (like ASCII) as well.
Such usage is not recommended because it would use the same macro
sometimes for semantical annotation, sometimes for physical formatting.
.Pp
Examples:
.Dl \&.Tn IBM
.Ss \&Ud
Prints out
.Dq currently under development.
.Ss \&Ux
Format the UNIX name.
Accepts no argument.
.Pp
Examples:
.Dl \&.Ux
.Pp
See also
.Sx \&At ,
.Sx \&Bsx ,
.Sx \&Bx ,
.Sx \&Dx ,
.Sx \&Fx ,
.Sx \&Nx ,
and
.Sx \&Ox .
.Ss \&Va
A variable name.
.Pp
Examples:
.Dl \&.Va foo
.Dl \&.Va const char *bar ;
.Ss \&Vt
A variable type.
This is also used for indicating global variables in the
.Em SYNOPSIS
section, in which case a variable name is also specified.
Note that it accepts
.Sx Block partial-implicit
syntax when invoked as the first macro on an input line in the
.Em SYNOPSIS
section, else it accepts ordinary
.Sx In-line
syntax.
In the former case, this macro starts a new output line,
and a blank line is inserted in front if there is a preceding
function definition or include directive.
.Pp
Note that this should not be confused with
.Sx \&Ft ,
which is used for function return types.
.Pp
Examples:
.Dl \&.Vt unsigned char
.Dl \&.Vt extern const char * const sys_signame[] \&;
.Pp
See also
.Sx MANUAL STRUCTURE
and
.Sx \&Va .
.Ss \&Xc
Close a scope opened by
.Sx \&Xo .
.Ss \&Xo
Extend the header of an
.Sx \&It
macro or the body of a partial-implicit block macro
beyond the end of the input line.
This macro originally existed to work around the 9-argument limit
of historic
.Xr roff 7 .
.Ss \&Xr
Link to another manual
.Pq Qq cross-reference .
Its syntax is as follows:
.Pp
.D1 Pf \. Sx \&Xr Ar name section
.Pp
The
.Ar name
and
.Ar section
are the name and section of the linked manual.
If
.Ar section
is followed by non-punctuation, an
.Sx \&Ns
is inserted into the token stream.
This behaviour is for compatibility with
GNU troff.
.Pp
Examples:
.Dl \&.Xr mandoc 1
.Dl \&.Xr mandoc 1 \&;
.Dl \&.Xr mandoc 1 \&Ns s behaviour
.Ss \&br
Emits a line-break.
This macro should not be used; it is implemented for compatibility with
historical manuals.
.Pp
Consider using
.Sx \&Pp
in the event of natural paragraph breaks.
.Ss \&sp
Emits vertical space.
This macro should not be used; it is implemented for compatibility with
historical manuals.
Its syntax is as follows:
.Pp
.D1 Pf \. Sx \&sp Op Ar height
.Pp
The
.Ar height
argument must be formatted as described in
.Sx Scaling Widths .
If unspecified,
.Sx \&sp
asserts a single vertical space.
.Sh MACRO SYNTAX
The syntax of a macro depends on its classification.
In this section,
.Sq \-arg
refers to macro arguments, which may be followed by zero or more
.Sq parm
parameters;
.Sq \&Yo
opens the scope of a macro; and if specified,
.Sq \&Yc
closes it out.
.Pp
The
.Em Callable
column indicates that the macro may also be called by passing its name
as an argument to another macro.
For example,
.Sq \&.Op \&Fl O \&Ar file
produces
.Sq Op Fl O Ar file .
To prevent a macro call and render the macro name literally,
escape it by prepending a zero-width space,
.Sq \e& .
For example,
.Sq \&Op \e&Fl O
produces
.Sq Op \&Fl O .
If a macro is not callable but its name appears as an argument
to another macro, it is interpreted as opaque text.
For example,
.Sq \&.Fl \&Sh
produces
.Sq Fl \&Sh .
.Pp
The
.Em Parsed
column indicates whether the macro may call other macros by receiving
their names as arguments.
If a macro is not parsed but the name of another macro appears
as an argument, it is interpreted as opaque text.
.Pp
The
.Em Scope
column, if applicable, describes closure rules.
.Ss Block full-explicit
Multi-line scope closed by an explicit closing macro.
All macros contains bodies; only
.Sx \&Bf
and
.Pq optionally
.Sx \&Bl
contain a head.
.Bd -literal -offset indent
\&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB
\(lBbody...\(rB
\&.Yc
.Ed
.Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXX" -offset indent
.It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope
.It Sx \&Bd Ta \&No Ta \&No Ta closed by Sx \&Ed
.It Sx \&Bf Ta \&No Ta \&No Ta closed by Sx \&Ef
.It Sx \&Bk Ta \&No Ta \&No Ta closed by Sx \&Ek
.It Sx \&Bl Ta \&No Ta \&No Ta closed by Sx \&El
.It Sx \&Ed Ta \&No Ta \&No Ta opened by Sx \&Bd
.It Sx \&Ef Ta \&No Ta \&No Ta opened by Sx \&Bf
.It Sx \&Ek Ta \&No Ta \&No Ta opened by Sx \&Bk
.It Sx \&El Ta \&No Ta \&No Ta opened by Sx \&Bl
.El
.Ss Block full-implicit
Multi-line scope closed by end-of-file or implicitly by another macro.
All macros have bodies; some
.Po
.Sx \&It Fl bullet ,
.Fl hyphen ,
.Fl dash ,
.Fl enum ,
.Fl item
.Pc
don't have heads; only one
.Po
.Sx \&It
in
.Sx \&Bl Fl column
.Pc
has multiple heads.
.Bd -literal -offset indent
\&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead... \(lBTa head...\(rB\(rB
\(lBbody...\(rB
.Ed
.Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXXXXXXXXXX" -offset indent
.It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope
.It Sx \&It Ta \&No Ta Yes Ta closed by Sx \&It , Sx \&El
.It Sx \&Nd Ta \&No Ta \&No Ta closed by Sx \&Sh
.It Sx \&Nm Ta \&No Ta Yes Ta closed by Sx \&Nm , Sx \&Sh , Sx \&Ss
.It Sx \&Sh Ta \&No Ta Yes Ta closed by Sx \&Sh
.It Sx \&Ss Ta \&No Ta Yes Ta closed by Sx \&Sh , Sx \&Ss
.El
.Pp
Note that the
.Sx \&Nm
macro is a
.Sx Block full-implicit
macro only when invoked as the first macro
in a
.Em SYNOPSIS
section line, else it is
.Sx In-line .
.Ss Block partial-explicit
Like block full-explicit, but also with single-line scope.
Each has at least a body and, in limited circumstances, a head
.Po
.Sx \&Fo ,
.Sx \&Eo
.Pc
and/or tail
.Pq Sx \&Ec .
.Bd -literal -offset indent
\&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB
\(lBbody...\(rB
\&.Yc \(lBtail...\(rB
\&.Yo \(lB\-arg \(lBparm...\(rB\(rB \(lBhead...\(rB \
\(lBbody...\(rB \&Yc \(lBtail...\(rB
.Ed
.Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXXX" -offset indent
.It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope
.It Sx \&Ac Ta Yes Ta Yes Ta opened by Sx \&Ao
.It Sx \&Ao Ta Yes Ta Yes Ta closed by Sx \&Ac
.It Sx \&Bc Ta Yes Ta Yes Ta closed by Sx \&Bo
.It Sx \&Bo Ta Yes Ta Yes Ta opened by Sx \&Bc
.It Sx \&Brc Ta Yes Ta Yes Ta opened by Sx \&Bro
.It Sx \&Bro Ta Yes Ta Yes Ta closed by Sx \&Brc
.It Sx \&Dc Ta Yes Ta Yes Ta opened by Sx \&Do
.It Sx \&Do Ta Yes Ta Yes Ta closed by Sx \&Dc
.It Sx \&Ec Ta Yes Ta Yes Ta opened by Sx \&Eo
.It Sx \&Eo Ta Yes Ta Yes Ta closed by Sx \&Ec
.It Sx \&Fc Ta Yes Ta Yes Ta opened by Sx \&Fo
.It Sx \&Fo Ta \&No Ta \&No Ta closed by Sx \&Fc
.It Sx \&Oc Ta Yes Ta Yes Ta closed by Sx \&Oo
.It Sx \&Oo Ta Yes Ta Yes Ta opened by Sx \&Oc
.It Sx \&Pc Ta Yes Ta Yes Ta closed by Sx \&Po
.It Sx \&Po Ta Yes Ta Yes Ta opened by Sx \&Pc
.It Sx \&Qc Ta Yes Ta Yes Ta opened by Sx \&Oo
.It Sx \&Qo Ta Yes Ta Yes Ta closed by Sx \&Oc
.It Sx \&Re Ta \&No Ta \&No Ta opened by Sx \&Rs
.It Sx \&Rs Ta \&No Ta \&No Ta closed by Sx \&Re
.It Sx \&Sc Ta Yes Ta Yes Ta opened by Sx \&So
.It Sx \&So Ta Yes Ta Yes Ta closed by Sx \&Sc
.It Sx \&Xc Ta Yes Ta Yes Ta opened by Sx \&Xo
.It Sx \&Xo Ta Yes Ta Yes Ta closed by Sx \&Xc
.El
.Ss Block partial-implicit
Like block full-implicit, but with single-line scope closed by the
end of the line.
.Bd -literal -offset indent
\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBbody...\(rB \(lBres...\(rB
.Ed
.Bl -column "MacroX" "CallableX" "ParsedX" -offset indent
.It Em Macro Ta Em Callable Ta Em Parsed
.It Sx \&Aq Ta Yes Ta Yes
.It Sx \&Bq Ta Yes Ta Yes
.It Sx \&Brq Ta Yes Ta Yes
.It Sx \&D1 Ta \&No Ta \&Yes
.It Sx \&Dl Ta \&No Ta Yes
.It Sx \&Dq Ta Yes Ta Yes
.It Sx \&Op Ta Yes Ta Yes
.It Sx \&Pq Ta Yes Ta Yes
.It Sx \&Ql Ta Yes Ta Yes
.It Sx \&Qq Ta Yes Ta Yes
.It Sx \&Sq Ta Yes Ta Yes
.It Sx \&Vt Ta Yes Ta Yes
.El
.Pp
Note that the
.Sx \&Vt
macro is a
.Sx Block partial-implicit
only when invoked as the first macro
in a
.Em SYNOPSIS
section line, else it is
.Sx In-line .
.Ss Special block macro
The
.Sx \&Ta
macro can only be used below
.Sx \&It
in
.Sx \&Bl Fl column
lists.
It delimits blocks representing table cells;
these blocks have bodies, but no heads.
.Bl -column "MacroX" "CallableX" "ParsedX" "closed by XXXX" -offset indent
.It Em Macro Ta Em Callable Ta Em Parsed Ta Em Scope
.It Sx \&Ta Ta Yes Ta Yes Ta closed by Sx \&Ta , Sx \&It
.El
.Ss In-line
Closed by the end of the line, fixed argument lengths,
and/or subsequent macros.
In-line macros have only text children.
If a number (or inequality) of arguments is
.Pq n ,
then the macro accepts an arbitrary number of arguments.
.Bd -literal -offset indent
\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB \(lBres...\(rB
\&.Yo \(lB\-arg \(lBval...\(rB\(rB \(lBargs...\(rB Yc...
\&.Yo \(lB\-arg \(lBval...\(rB\(rB arg0 arg1 argN
.Ed
.Bl -column "MacroX" "CallableX" "ParsedX" "Arguments" -offset indent
.It Em Macro Ta Em Callable Ta Em Parsed Ta Em Arguments
.It Sx \&%A Ta \&No Ta \&No Ta >0
.It Sx \&%B Ta \&No Ta \&No Ta >0
.It Sx \&%C Ta \&No Ta \&No Ta >0
.It Sx \&%D Ta \&No Ta \&No Ta >0
.It Sx \&%I Ta \&No Ta \&No Ta >0
.It Sx \&%J Ta \&No Ta \&No Ta >0
.It Sx \&%N Ta \&No Ta \&No Ta >0
.It Sx \&%O Ta \&No Ta \&No Ta >0
.It Sx \&%P Ta \&No Ta \&No Ta >0
.It Sx \&%Q Ta \&No Ta \&No Ta >0
.It Sx \&%R Ta \&No Ta \&No Ta >0
.It Sx \&%T Ta \&No Ta \&No Ta >0
.It Sx \&%U Ta \&No Ta \&No Ta >0
.It Sx \&%V Ta \&No Ta \&No Ta >0
.It Sx \&Ad Ta Yes Ta Yes Ta >0
.It Sx \&An Ta Yes Ta Yes Ta >0
.It Sx \&Ap Ta Yes Ta Yes Ta 0
.It Sx \&Ar Ta Yes Ta Yes Ta n
.It Sx \&At Ta Yes Ta Yes Ta 1
.It Sx \&Bsx Ta Yes Ta Yes Ta n
.It Sx \&Bt Ta \&No Ta \&No Ta 0
.It Sx \&Bx Ta Yes Ta Yes Ta n
.It Sx \&Cd Ta Yes Ta Yes Ta >0
.It Sx \&Cm Ta Yes Ta Yes Ta >0
.It Sx \&Db Ta \&No Ta \&No Ta 1
.It Sx \&Dd Ta \&No Ta \&No Ta n
.It Sx \&Dt Ta \&No Ta \&No Ta n
.It Sx \&Dv Ta Yes Ta Yes Ta >0
.It Sx \&Dx Ta Yes Ta Yes Ta n
.It Sx \&Em Ta Yes Ta Yes Ta >0
.It Sx \&En Ta \&No Ta \&No Ta 0
.It Sx \&Er Ta Yes Ta Yes Ta >0
.It Sx \&Es Ta \&No Ta \&No Ta 0
.It Sx \&Ev Ta Yes Ta Yes Ta >0
.It Sx \&Ex Ta \&No Ta \&No Ta n
.It Sx \&Fa Ta Yes Ta Yes Ta >0
.It Sx \&Fd Ta \&No Ta \&No Ta >0
.It Sx \&Fl Ta Yes Ta Yes Ta n
.It Sx \&Fn Ta Yes Ta Yes Ta >0
.It Sx \&Fr Ta \&No Ta \&No Ta n
.It Sx \&Ft Ta Yes Ta Yes Ta >0
.It Sx \&Fx Ta Yes Ta Yes Ta n
.It Sx \&Hf Ta \&No Ta \&No Ta n
.It Sx \&Ic Ta Yes Ta Yes Ta >0
.It Sx \&In Ta \&No Ta \&No Ta 1
.It Sx \&Lb Ta \&No Ta \&No Ta 1
.It Sx \&Li Ta Yes Ta Yes Ta >0
.It Sx \&Lk Ta Yes Ta Yes Ta >0
.It Sx \&Lp Ta \&No Ta \&No Ta 0
.It Sx \&Ms Ta Yes Ta Yes Ta >0
.It Sx \&Mt Ta Yes Ta Yes Ta >0
.It Sx \&Nm Ta Yes Ta Yes Ta n
.It Sx \&No Ta Yes Ta Yes Ta 0
.It Sx \&Ns Ta Yes Ta Yes Ta 0
.It Sx \&Nx Ta Yes Ta Yes Ta n
.It Sx \&Os Ta \&No Ta \&No Ta n
.It Sx \&Ot Ta \&No Ta \&No Ta n
.It Sx \&Ox Ta Yes Ta Yes Ta n
.It Sx \&Pa Ta Yes Ta Yes Ta n
.It Sx \&Pf Ta Yes Ta Yes Ta 1
.It Sx \&Pp Ta \&No Ta \&No Ta 0
.It Sx \&Rv Ta \&No Ta \&No Ta n
.It Sx \&Sm Ta \&No Ta \&No Ta 1
.It Sx \&St Ta \&No Ta Yes Ta 1
.It Sx \&Sx Ta Yes Ta Yes Ta >0
.It Sx \&Sy Ta Yes Ta Yes Ta >0
.It Sx \&Tn Ta Yes Ta Yes Ta >0
.It Sx \&Ud Ta \&No Ta \&No Ta 0
.It Sx \&Ux Ta Yes Ta Yes Ta n
.It Sx \&Va Ta Yes Ta Yes Ta n
.It Sx \&Vt Ta Yes Ta Yes Ta >0
.It Sx \&Xr Ta Yes Ta Yes Ta >0
.It Sx \&br Ta \&No Ta \&No Ta 0
.It Sx \&sp Ta \&No Ta \&No Ta 1
.El
.Ss Delimiters
When a macro argument consists of one single input character
considered as a delimiter, the argument gets special handling.
This does not apply when delimiters appear in arguments containing
more than one character.
Consequently, to prevent special handling and just handle it
like any other argument, a delimiter can be escaped by prepending
a zero-width space
.Pq Sq \e& .
In text lines, delimiters never need escaping, but may be used
as normal punctuation.
.Pp
For many macros, when the leading arguments are opening delimiters,
these delimiters are put before the macro scope,
and when the trailing arguments are closing delimiters,
these delimiters are put after the macro scope.
For example,
.Pp
.D1 Pf \. \&Aq "( [ word ] ) ."
.Pp
renders as:
.Pp
.D1 Aq ( [ word ] ) .
.Pp
Opening delimiters are:
.Pp
.Bl -tag -width Ds -offset indent -compact
.It \&(
left parenthesis
.It \&[
left bracket
.El
.Pp
Closing delimiters are:
.Pp
.Bl -tag -width Ds -offset indent -compact
.It \&.
period
.It \&,
comma
.It \&:
colon
.It \&;
semicolon
.It \&)
right parenthesis
.It \&]
right bracket
.It \&?
question mark
.It \&!
exclamation mark
.El
.Pp
Note that even a period preceded by a backslash
.Pq Sq \e.\&
gets this special handling; use
.Sq \e&.
to prevent that.
.Pp
Many in-line macros interrupt their scope when they encounter
delimiters, and resume their scope when more arguments follow that
are not delimiters.
For example,
.Pp
.D1 Pf \. \&Fl "a ( b | c \e*(Ba d ) e"
.Pp
renders as:
.Pp
.D1 Fl a ( b | c \*(Ba d ) e
.Pp
This applies to both opening and closing delimiters,
and also to the middle delimiter:
.Pp
.Bl -tag -width Ds -offset indent -compact
.It \&|
vertical bar
.El
.Pp
As a special case, the predefined string \e*(Ba is handled and rendered
in the same way as a plain
.Sq \&|
character.
Using this predefined string is not recommended in new manuals.
.Ss Font handling
In
.Nm
documents, usage of semantic markup is recommended in order to have
proper fonts automatically selected; only when no fitting semantic markup
is available, consider falling back to
.Sx Physical markup
macros.
Whenever any
.Nm
macro switches the
.Xr roff 7
font mode, it will automatically restore the previous font when exiting
its scope.
Manually switching the font using the
.Xr roff 7
.Ql \ef
font escape sequences is never required.
.Sh COMPATIBILITY
This section documents compatibility between mandoc and other other
troff implementations, at this time limited to GNU troff
.Pq Qq groff .
The term
.Qq historic groff
refers to groff versions before 1.17,
which featured a significant update of the
.Pa doc.tmac
file.
.Pp
Heirloom troff, the other significant troff implementation accepting
\-mdoc, is similar to historic groff.
.Pp
The following problematic behaviour is found in groff:
.ds hist (Historic groff only.)
.Pp
.Bl -dash -compact
.It
Display macros
.Po
.Sx \&Bd ,
.Sx \&Dl ,
and
.Sx \&D1
.Pc
may not be nested.
\*[hist]
.It
.Sx \&At
with unknown arguments produces no output at all.
\*[hist]
Newer groff and mandoc print
.Qq AT&T UNIX
and the arguments.
.It
.Sx \&Bl Fl column
does not recognise trailing punctuation characters when they immediately
precede tabulator characters, but treats them as normal text and
outputs a space before them.
.It
.Sx \&Bd Fl ragged compact
does not start a new line.
\*[hist]
.It
.Sx \&Dd
with non-standard arguments behaves very strangely.
When there are three arguments, they are printed verbatim.
Any other number of arguments is replaced by the current date,
but without any arguments the string
.Dq Epoch
is printed.
.It
.Sx \&Fl
does not print a dash for an empty argument.
\*[hist]
.It
.Sx \&Fn
does not start a new line unless invoked as the line macro in the
.Em SYNOPSIS
section.
\*[hist]
.It
.Sx \&Fo
with
.Pf non- Sx \&Fa
children causes inconsistent spacing between arguments.
In mandoc, a single space is always inserted between arguments.
.It
.Sx \&Ft
in the
.Em SYNOPSIS
causes inconsistent vertical spacing, depending on whether a prior
.Sx \&Fn
has been invoked.
See
.Sx \&Ft
and
.Sx \&Fn
for the normalised behaviour in mandoc.
.It
.Sx \&In
ignores additional arguments and is not treated specially in the
.Em SYNOPSIS .
\*[hist]
.It
.Sx \&It
sometimes requires a
.Fl nested
flag.
\*[hist]
In new groff and mandoc, any list may be nested by default and
.Fl enum
lists will restart the sequence only for the sub-list.
.It
.Sx \&Li
followed by a delimiter is incorrectly used in some manuals
instead of properly quoting that character, which sometimes works with
historic groff.
.It
.Sx \&Lk
only accepts a single link-name argument; the remainder is misformatted.
.It
.Sx \&Pa
does not format its arguments when used in the FILES section under
certain list types.
.It
.Sx \&Ta
can only be called by other macros, but not at the beginning of a line.
.It
.Sx \&%C
is not implemented.
.It
Historic groff only allows up to eight or nine arguments per macro input
line, depending on the exact situation.
Providing more arguments causes garbled output.
The number of arguments on one input line is not limited with mandoc.
.It
Historic groff has many un-callable macros.
Most of these (excluding some block-level macros) are callable
in new groff and mandoc.
.It
.Sq \(ba
(vertical bar) is not fully supported as a delimiter.
\*[hist]
.It
.Sq \ef
.Pq font face
and
.Sq \ef
.Pq font family face
.Sx Text Decoration
escapes behave irregularly when specified within line-macro scopes.
.It
Negative scaling units return to prior lines.
Instead, mandoc truncates them to zero.
.El
.Pp
The following features are unimplemented in mandoc:
.Pp
.Bl -dash -compact
.It
.Sx \&Bd
.Fl file Ar file .
.It
.Sx \&Bd
.Fl offset Ar center
and
.Fl offset Ar right .
Groff does not implement centred and flush-right rendering either,
but produces large indentations.
.It
The
.Sq \eh
.Pq horizontal position ,
.Sq \ev
.Pq vertical position ,
.Sq \em
.Pq text colour ,
.Sq \eM
.Pq text filling colour ,
.Sq \ez
.Pq zero-length character ,
.Sq \ew
.Pq string length ,
.Sq \ek
.Pq horizontal position marker ,
.Sq \eo
.Pq text overstrike ,
and
.Sq \es
.Pq text size
escape sequences are all discarded in mandoc.
.It
The
.Sq \ef
scaling unit is accepted by mandoc, but rendered as the default unit.
.It
In quoted literals, groff allows pairwise double-quotes to produce a
standalone double-quote in formatted output.
This is not supported by mandoc.
.El
.Sh SEE ALSO
.Xr man 1 ,
.Xr mandoc 1 ,
.Xr eqn 7 ,
.Xr man 7 ,
.Xr mandoc_char 7 ,
.Xr roff 7 ,
.Xr tbl 7
.Sh HISTORY
The
.Nm
language first appeared as a troff macro package in
.Bx 4.4 .
It was later significantly updated by Werner Lemberg and Ruslan Ermilov
in groff-1.17.
The standalone implementation that is part of the
.Xr mandoc 1
utility written by Kristaps Dzonsons appeared in
.Ox 4.6 .
.Sh AUTHORS
The
.Nm
reference was written by
.An Kristaps Dzonsons ,
.Mt kristaps@bsd.lv .
Reference in New Issue View Git Blame Copy Permalink