diff options
Diffstat (limited to 'man7/man-pages.7')
| -rw-r--r-- | man7/man-pages.7 | 1227 |
1 files changed, 1227 insertions, 0 deletions
diff --git a/man7/man-pages.7 b/man7/man-pages.7 new file mode 100644 index 0000000..6d8b0ea --- /dev/null +++ b/man7/man-pages.7 @@ -0,0 +1,1227 @@ +'\" t +.\" (C) Copyright 1992-1999 Rickard E. Faith and David A. Wheeler +.\" (faith@cs.unc.edu and dwheeler@ida.org) +.\" and (C) Copyright 2007 Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" 2007-05-30 created by mtk, using text from old man.7 plus +.\" rewrites and additional text. +.\" +.TH man-pages 7 2023-03-30 "Linux man-pages 6.05.01" +.SH NAME +man-pages \- conventions for writing Linux man pages +.SH SYNOPSIS +.B man +.RI [ section ] +.I title +.SH DESCRIPTION +This page describes the conventions that should be employed +when writing man pages for the Linux \fIman-pages\fP project, +which documents the user-space API provided by the Linux kernel +and the GNU C library. +The project thus provides most of the pages in Section 2, +many of the pages that appear in Sections 3, 4, and 7, +and a few of the pages that appear in Sections 1, 5, and 8 +of the man pages on a Linux system. +The conventions described on this page may also be useful +for authors writing man pages for other projects. +.SS Sections of the manual pages +The manual Sections are traditionally defined as follows: +.TP +.B 1 User commands (Programs) +Commands that can be executed by the user from within +a shell. +.TP +.B 2 System calls +Functions which wrap operations performed by the kernel. +.TP +.B 3 Library calls +All library functions excluding the system call wrappers +(Most of the +.I libc +functions). +.TP +.B 4 Special files (devices) +Files found in +.I /dev +which allow to access to devices through the kernel. +.TP +.B 5 File formats and configuration files +Describes various human-readable file formats and configuration files. +.TP +.B 6 Games +Games and funny little programs available on the system. +.TP +.B 7 Overview, conventions, and miscellaneous +Overviews or descriptions of various topics, conventions, and protocols, +character set standards, the standard filesystem layout, and miscellaneous +other things. +.TP +.B 8 System management commands +Commands like +.BR mount (8), +many of which only root can execute. +.\" .TP +.\" .B 9 Kernel routines +.\" This is an obsolete manual section. +.\" Once it was thought a good idea to document the Linux kernel here, +.\" but in fact very little has been documented, and the documentation +.\" that exists is outdated already. +.\" There are better sources of +.\" information for kernel developers. +.SS Macro package +New manual pages should be marked up using the +.B groff an.tmac +package described in +.BR man (7). +This choice is mainly for consistency: the vast majority of +existing Linux manual pages are marked up using these macros. +.SS Conventions for source file layout +Please limit source code line length to no more than about 75 characters +wherever possible. +This helps avoid line-wrapping in some mail clients when patches are +submitted inline. +.SS Title line +The first command in a man page should be a +.B TH +command: +.PP +.RS +.B \&.TH +.I "title section date source manual-section" +.RE +.PP +The arguments of the command are as follows: +.TP +.I title +The title of the man page, written in all caps (e.g., +.IR MAN-PAGES ). +.TP +.I section +The section number in which the man page should be placed (e.g., +.IR 7 ). +.TP +.I date +The date of the last nontrivial change that was made to the man page. +(Within the +.I man-pages +project, the necessary updates to these timestamps are handled +automatically by scripts, so there is no need to manually update +them as part of a patch.) +Dates should be written in the form YYYY-MM-DD. +.TP +.I source +The name and version of the project that provides the manual page +(not necessarily the package that provides the functionality). +.TP +.I manual-section +Normally, this should be empty, +since the default value will be good. +.\" +.SS Sections within a manual page +The list below shows conventional or suggested sections. +Most manual pages should include at least the +.B highlighted +sections. +Arrange a new manual page so that sections +are placed in the order shown in the list. +.PP +.RS +.TS +l l. +\fBNAME\fP +LIBRARY [Normally only in Sections 2, 3] +\fBSYNOPSIS\fP +CONFIGURATION [Normally only in Section 4] +\fBDESCRIPTION\fP +OPTIONS [Normally only in Sections 1, 8] +EXIT STATUS [Normally only in Sections 1, 8] +RETURN VALUE [Normally only in Sections 2, 3] +.\" May 07: Few current man pages have an ERROR HANDLING section,,, +.\" ERROR HANDLING, +ERRORS [Typically only in Sections 2, 3] +.\" May 07: Almost no current man pages have a USAGE section,,, +.\" USAGE, +.\" DIAGNOSTICS, +.\" May 07: Almost no current man pages have a SECURITY section,,, +.\" SECURITY, +ENVIRONMENT +FILES +ATTRIBUTES [Normally only in Sections 2, 3] +VERSIONS [Normally only in Sections 2, 3] +STANDARDS +HISTORY +NOTES +CAVEATS +BUGS +EXAMPLES +.\" AUTHORS sections are discouraged +AUTHORS [Discouraged] +REPORTING BUGS [Not used in man-pages] +COPYRIGHT [Not used in man-pages] +\fBSEE ALSO\fP +.TE +.RE +.PP +.IR "Where a traditional heading would apply" ", " "please use it" ; +this kind of consistency can make the information easier to understand. +If you must, you can create your own +headings if they make things easier to understand (this can +be especially useful for pages in Sections 4 and 5). +However, before doing this, consider whether you could use the +traditional headings, with some subsections (\fI.SS\fP) within +those sections. +.PP +The following list elaborates on the contents of each of +the above sections. +.TP +.B NAME +The name of this manual page. +.IP +See +.BR man (7) +for important details of the line(s) that should follow the +\fB.SH NAME\fP command. +All words in this line (including the word immediately +following the "\e\-") should be in lowercase, +except where English or technical terminological convention +dictates otherwise. +.TP +.B LIBRARY +The library providing a symbol. +.IP +It shows the common name of the library, +and in parentheses, +the name of the library file +and, if needed, the linker flag needed to link a program against it: +.RI ( libfoo "[, " \-lfoo ]). +.TP +.B SYNOPSIS +A brief summary of the command or function's interface. +.IP +For commands, this shows the syntax of the command and its arguments +(including options); +boldface is used for as-is text and italics are used to +indicate replaceable arguments. +Brackets ([]) surround optional arguments, vertical bars (|) +separate choices, and ellipses (\&...) can be repeated. +For functions, it shows any required data declarations or +.B #include +directives, followed by the function declaration. +.IP +Where a feature test macro must be defined in order to obtain +the declaration of a function (or a variable) from a header file, +then the SYNOPSIS should indicate this, as described in +.BR feature_test_macros (7). +.\" FIXME . Say something here about compiler options +.TP +.B CONFIGURATION +Configuration details for a device. +.IP +This section normally appears only in Section 4 pages. +.TP +.B DESCRIPTION +An explanation of what the program, function, or format does. +.IP +Discuss how it interacts with files and standard input, and what it +produces on standard output or standard error. +Omit internals and implementation details unless they're critical for +understanding the interface. +Describe the usual case; +for information on command-line options of a program use the +.B OPTIONS +section. +.\" If there is some kind of input grammar or complex set of subcommands, +.\" consider describing them in a separate +.\" .B USAGE +.\" section (and just place an overview in the +.\" .B DESCRIPTION +.\" section). +.IP +When describing new behavior or new flags for +a system call or library function, +be careful to note the kernel or C library version +that introduced the change. +The preferred method of noting this information for flags is as part of a +.B .TP +list, in the following form (here, for a new system call flag): +.RS 16 +.TP +.BR XYZ_FLAG " (since Linux 3.7)" +Description of flag... +.RE +.IP +Including version information is especially useful to users +who are constrained to using older kernel or C library versions +(which is typical in embedded systems, for example). +.TP +.B OPTIONS +A description of the command-line options accepted by a +program and how they change its behavior. +.IP +This section should appear only for Section 1 and 8 manual pages. +.\" .TP +.\" .B USAGE +.\" describes the grammar of any sublanguage this implements. +.TP +.B EXIT STATUS +A list of the possible exit status values of a program and +the conditions that cause these values to be returned. +.IP +This section should appear only for Section 1 and 8 manual pages. +.TP +.B RETURN VALUE +For Section 2 and 3 pages, this section gives a +list of the values the library routine will return to the caller +and the conditions that cause these values to be returned. +.TP +.B ERRORS +For Section 2 and 3 manual pages, this is a list of the +values that may be placed in +.I errno +in the event of an error, along with information about the cause +of the errors. +.IP +Where several different conditions produce the same error, +the preferred approach is to create separate list entries +(with duplicate error names) for each of the conditions. +This makes the separate conditions clear, may make the list easier to read, +and allows metainformation +(e.g., kernel version number where the condition first became applicable) +to be more easily marked for each condition. +.IP +.IR "The error list should be in alphabetical order" . +.TP +.B ENVIRONMENT +A list of all environment variables that affect the program or function +and how they affect it. +.TP +.B FILES +A list of the files the program or function uses, such as +configuration files, startup files, +and files the program directly operates on. +.IP +Give the full pathname of these files, and use the installation +process to modify the directory part to match user preferences. +For many programs, the default installation location is in +.IR /usr/local , +so your base manual page should use +.I /usr/local +as the base. +.\" May 07: Almost no current man pages have a DIAGNOSTICS section; +.\" "RETURN VALUE" or "EXIT STATUS" is preferred. +.\" .TP +.\" .B DIAGNOSTICS +.\" gives an overview of the most common error messages and how to +.\" cope with them. +.\" You don't need to explain system error messages +.\" or fatal signals that can appear during execution of any program +.\" unless they're special in some way to the program. +.\" +.\" May 07: Almost no current man pages have a SECURITY section. +.\".TP +.\".B SECURITY +.\"discusses security issues and implications. +.\"Warn about configurations or environments that should be avoided, +.\"commands that may have security implications, and so on, especially +.\"if they aren't obvious. +.\"Discussing security in a separate section isn't necessary; +.\"if it's easier to understand, place security information in the +.\"other sections (such as the +.\" .B DESCRIPTION +.\" or +.\" .B USAGE +.\" section). +.\" However, please include security information somewhere! +.TP +.B ATTRIBUTES +A summary of various attributes of the function(s) documented on this page. +See +.BR attributes (7) +for further details. +.TP +.B VERSIONS +A summary of systems where the API performs differently, +or where there's a similar API. +.TP +.B STANDARDS +A description of any standards or conventions that relate to the function +or command described by the manual page. +.IP +The preferred terms to use for the various standards are listed as +headings in +.BR standards (7). +.IP +This section should note the current standards to which the API conforms to. +.IP +If the API is not governed by any standards but commonly +exists on other systems, note them. +If the call is Linux-specific or GNU-specific, note this. +If it's available in the BSDs, note that. +.IP +If this section consists of just a list of standards +(which it commonly does), +terminate the list with a period (\[aq].\[aq]). +.TP +.B HISTORY +A brief summary of the Linux kernel or glibc versions where a +system call or library function appeared, +or changed significantly in its operation. +.IP +As a general rule, every new interface should +include a HISTORY section in its manual page. +Unfortunately, +many existing manual pages don't include this information +(since there was no policy to do so when they were written). +Patches to remedy this are welcome, +but, from the perspective of programmers writing new code, +this information probably matters only in the case of kernel +interfaces that have been added in Linux 2.4 or later +(i.e., changes since Linux 2.2), +and library functions that have been added to glibc since glibc 2.1 +(i.e., changes since glibc 2.0). +.IP +The +.BR syscalls (2) +manual page also provides information about kernel versions +in which various system calls first appeared. +.PP +Old versions of standards should be mentioned here, +rather than in STANDARDS, +for example, +SUS, SUSv2, and XPG, or the SVr4 and 4.xBSD implementation standards. +.TP +.B NOTES +Miscellaneous notes. +.IP +For Section 2 and 3 man pages you may find it useful to include +subsections (\fBSS\fP) named \fILinux Notes\fP and \fIglibc Notes\fP. +.IP +In Section 2, use the heading +.I "C library/kernel differences" +to mark off notes that describe the differences (if any) between +the C library wrapper function for a system call and +the raw system call interface provided by the kernel. +.TP +.B CAVEATS +Warnings about typical user misuse of an API, +that don't constitute an API bug or design defect. +.TP +.B BUGS +A list of limitations, known defects or inconveniences, +and other questionable activities. +.TP +.B EXAMPLES +One or more examples demonstrating how this function, file, or +command is used. +.IP +For details on writing example programs, +see \fIExample programs\fP below. +.TP +.B AUTHORS +A list of authors of the documentation or program. +.IP +\fBUse of an AUTHORS section is strongly discouraged\fP. +Generally, it is better not to clutter every page with a list +of (over time potentially numerous) authors; +if you write or significantly amend a page, +add a copyright notice as a comment in the source file. +If you are the author of a device driver and want to include +an address for reporting bugs, place this under the BUGS section. +.TP +.B REPORTING BUGS +The +.I man-pages +project doesn't use a REPORTING BUGS section in manual pages. +Information on reporting bugs is instead supplied in the +script-generated COLOPHON section. +However, various projects do use a REPORTING BUGS section. +It is recommended to place it near the foot of the page. +.TP +.B COPYRIGHT +The +.I man-pages +project doesn't use a COPYRIGHT section in manual pages. +Copyright information is instead maintained in the page source. +In pages where this section is present, +it is recommended to place it near the foot of the page, just above SEE ALSO. +.TP +.B SEE ALSO +A comma-separated list of related man pages, possibly followed by +other related pages or documents. +.IP +The list should be ordered by section number and +then alphabetically by name. +Do not terminate this list with a period. +.IP +Where the SEE ALSO list contains many long manual page names, +to improve the visual result of the output, it may be useful to employ the +.I .ad l +(don't right justify) +and +.I .nh +(don't hyphenate) +directives. +Hyphenation of individual page names can be prevented +by preceding words with the string "\e%". +.IP +Given the distributed, autonomous nature of FOSS projects +and their documentation, it is sometimes necessary\[em]and in many cases +desirable\[em]that the SEE ALSO section includes references to +manual pages provided by other projects. +.SH FORMATTING AND WORDING CONVENTIONS +The following subsections note some details for preferred formatting and +wording conventions in various sections of the pages in the +.I man-pages +project. +.SS SYNOPSIS +Wrap the function prototype(s) in a +.IR .nf / .fi +pair to prevent filling. +.PP +In general, where more than one function prototype is shown in the SYNOPSIS, +the prototypes should +.I not +be separated by blank lines. +However, blank lines (achieved using +.IR .PP ) +may be added in the following cases: +.IP \[bu] 3 +to separate long lists of function prototypes into related groups +(see for example +.BR list (3)); +.IP \[bu] +in other cases that may improve readability. +.PP +In the SYNOPSIS, a long function prototype may need to be +continued over to the next line. +The continuation line is indented according to the following rules: +.IP (1) 5 +If there is a single such prototype that needs to be continued, +then align the continuation line so that when the page is +rendered on a fixed-width font device (e.g., on an xterm) the +continuation line starts just below the start of the argument +list in the line above. +(Exception: the indentation may be +adjusted if necessary to prevent a very long continuation line +or a further continuation line where the function prototype is +very long.) +As an example: +.IP +.in +4n +.nf +.BI "int tcsetattr(int " fd ", int " optional_actions , +.BI " const struct termios *" termios_p ); +.fi +.in +.IP (2) +But, where multiple functions in the SYNOPSIS require +continuation lines, and the function names have different +lengths, then align all continuation lines to start in the +same column. +This provides a nicer rendering in PDF output +(because the SYNOPSIS uses a variable width font where +spaces render narrower than most characters). +As an example: +.IP +.in +4n +.nf +.BI "int getopt(int " argc ", char * const " argv[] , +.BI " const char *" optstring ); +.BI "int getopt_long(int " argc ", char * const " argv[] , +.BI " const char *" optstring , +.BI " const struct option *" longopts ", int *" longindex ); +.fi +.in +.SS RETURN VALUE +The preferred wording to describe how +.I errno +is set is +.RI \[dq] errno +is set to indicate the error" +or similar. +.\" Before man-pages 5.11, many different wordings were used, which +.\" was confusing, and potentially made scripted edits more difficult. +This wording is consistent with the wording used in both POSIX.1 and FreeBSD. +.SS ATTRIBUTES +.\" See man-pages commit c466875ecd64ed3d3cd3e578406851b7dfb397bf +Note the following: +.IP \[bu] 3 +Wrap the table in this section in a +.IR ".ad\ l" / .ad +pair to disable text filling and a +.IR .nh / .hy +pair to disable hyphenation. +.IP \[bu] +Ensure that the table occupies the full page width through the use of an +.I lbx +description for one of the columns +(usually the first column, +though in some cases the last column if it contains a lot of text). +.IP \[bu] +Make free use of +.IR T{ / T} +macro pairs to allow table cells to be broken over multiple lines +(also bearing in mind that pages may sometimes be rendered to a +width of less than 80 columns). +.PP +For examples of all of the above, see the source code of various pages. +.SH STYLE GUIDE +The following subsections describe the preferred style for the +.I man-pages +project. +For details not covered below, the Chicago Manual of Style +is usually a good source; +try also grepping for preexisting usage in the project source tree. +.SS Use of gender-neutral language +As far as possible, use gender-neutral language in the text of man +pages. +Use of "they" ("them", "themself", "their") as a gender-neutral singular +pronoun is acceptable. +.\" +.SS Formatting conventions for manual pages describing commands +For manual pages that describe a command (typically in Sections 1 and 8), +the arguments are always specified using italics, +.IR "even in the SYNOPSIS section" . +.PP +The name of the command, and its options, should +always be formatted in bold. +.\" +.SS Formatting conventions for manual pages describing functions +For manual pages that describe functions (typically in Sections 2 and 3), +the arguments are always specified using italics, +.IR "even in the SYNOPSIS section" , +where the rest of the function is specified in bold: +.PP +.BI " int myfunction(int " argc ", char **" argv ); +.PP +Variable names should, like argument names, be specified in italics. +.PP +Any reference to the subject of the current manual page +should be written with the name in bold followed by +a pair of parentheses in Roman (normal) font. +For example, in the +.BR fcntl (2) +man page, references to the subject of the page would be written as: +.BR fcntl (). +The preferred way to write this in the source file is: +.PP +.EX + .BR fcntl () +.EE +.PP +(Using this format, rather than the use of "\efB...\efP()" +makes it easier to write tools that parse man page source files.) +.\" +.SS Use semantic newlines +In the source of a manual page, +new sentences should be started on new lines, +long sentences should be split into lines at clause breaks +(commas, semicolons, colons, and so on), +and long clauses should be split at phrase boundaries. +This convention, sometimes known as "semantic newlines", +makes it easier to see the effect of patches, +which often operate at the level of +individual sentences, clauses, or phrases. +.\" +.SS Lists +There are different kinds of lists: +.TP +Tagged paragraphs +These are used for a list of tags and their descriptions. +When the tags are constants (either macros or numbers) +they are in bold. +Use the +.B .TP +macro. +.IP +An example is this "Tagged paragraphs" subsection is itself. +.TP +Ordered lists +Elements are preceded by a number in parentheses (1), (2). +These represent a set of steps that have an order. +.IP +When there are substeps, +they will be numbered like (4.2). +.TP +Positional lists +Elements are preceded by a number (index) in square brackets [4], [5]. +These represent fields in a set. +The first index will be: +.RS +.TP +.B 0 +When it represents fields of a C data structure, +to be consistent with arrays. +.PD 0 +.TP +.B 1 +When it represents fields of a file, +to be consistent with tools like +.BR cut (1). +.PD +.RE +.TP +Alternatives list +Elements are preceded by a letter in parentheses (a), (b). +These represent a set of (normally) exclusive alternatives. +.TP +Bullet lists +Elements are preceded by bullet symbols +.RB ( \e[bu] ). +Anything that doesn't fit elsewhere is +usually covered by this type of list. +.TP +Numbered notes +Not really a list, +but the syntax is identical to "positional lists". +.PP +There should always be exactly +2 spaces between the list symbol and the elements. +This doesn't apply to "tagged paragraphs", +which use the default indentation rules. +.\" +.SS Formatting conventions (general) +Paragraphs should be separated by suitable markers (usually either +.I .PP +or +.IR .IP ). +Do +.I not +separate paragraphs using blank lines, as this results in poor rendering +in some output formats (such as PostScript and PDF). +.PP +Filenames (whether pathnames, or references to header files) +are always in italics (e.g., +.IR <stdio.h> ), +except in the SYNOPSIS section, where included files are in bold (e.g., +.BR "#include <stdio.h>" ). +When referring to a standard header file include, +specify the header file surrounded by angle brackets, +in the usual C way (e.g., +.IR <stdio.h> ). +.PP +Special macros, which are usually in uppercase, are in bold (e.g., +.BR MAXINT ). +Exception: don't boldface NULL. +.PP +When enumerating a list of error codes, the codes are in bold (this list +usually uses the +.B \&.TP +macro). +.PP +Complete commands should, if long, +be written as an indented line on their own, +with a blank line before and after the command, for example +.PP +.in +4n +.EX +man 7 man\-pages +.EE +.in +.PP +If the command is short, then it can be included inline in the text, +in italic format, for example, +.IR "man 7 man-pages" . +In this case, it may be worth using nonbreaking spaces +(\e[ti]) at suitable places in the command. +Command options should be written in italics (e.g., +.IR \-l ). +.PP +Expressions, if not written on a separate indented line, should +be specified in italics. +Again, the use of nonbreaking spaces may be appropriate +if the expression is inlined with normal text. +.PP +When showing example shell sessions, +user input should be formatted in bold, +for example +.PP +.in +4n +.EX +$ \fBdate\fP +Thu Jul 7 13:01:27 CEST 2016 +.EE +.in +.PP +Any reference to another man page +should be written with the name in bold, +.I always +followed by the section number, +formatted in Roman (normal) font, without any +separating spaces (e.g., +.BR intro (2)). +The preferred way to write this in the source file is: +.PP +.EX + .BR intro (2) +.EE +.PP +(Including the section number in cross references lets tools like +.BR man2html (1) +create properly hyperlinked pages.) +.PP +Control characters should be written in bold face, +with no quotes; for example, +.BR \[ha]X . +.SS Spelling +Starting with release 2.59, +.I man-pages +follows American spelling conventions +(previously, there was a random mix of British and American spellings); +please write all new pages and patches according to these conventions. +.PP +Aside from the well-known spelling differences, +there are a few other subtleties to watch for: +.IP \[bu] 3 +American English tends to use the forms "backward", "upward", "toward", +and so on +rather than the British forms "backwards", "upwards", "towards", and so on. +.IP \[bu] +Opinions are divided on "acknowledgement" vs "acknowledgment". +The latter is predominant, but not universal usage in American English. +POSIX and the BSD license use the former spelling. +In the Linux man-pages project, we use "acknowledgement". +.SS BSD version numbers +The classical scheme for writing BSD version numbers is +.IR x.yBSD , +where +.I x.y +is the version number (e.g., 4.2BSD). +Avoid forms such as +.IR "BSD 4.3" . +.SS Capitalization +In subsection ("SS") headings, +capitalize the first word in the heading, but otherwise use lowercase, +except where English usage (e.g., proper nouns) or programming +language requirements (e.g., identifier names) dictate otherwise. +For example: +.PP +.in +4n +.EX +\&.SS Unicode under Linux +.EE +.in +.\" +.SS Indentation of structure definitions, shell session logs, and so on +When structure definitions, shell session logs, and so on are included +in running text, indent them by 4 spaces (i.e., a block enclosed by +.I ".in\ +4n" +and +.IR ".in" ), +format them using the +.I .EX +and +.I .EE +macros, and surround them with suitable paragraph markers (either +.I .PP +or +.IR .IP ). +For example: +.PP +.in +4n +.EX +\&.PP +\&.in +4n +\&.EX +int +main(int argc, char *argv[]) +{ + return 0; +} +\&.EE +\&.in +\&.PP +.EE +.in +.SS Preferred terms +The following table lists some preferred terms to use in man pages, +mainly to ensure consistency across pages. +.ad l +.TS +l l l +--- +l l ll. +Term Avoid using Notes + +bit mask bitmask +built-in builtin +Epoch epoch T{ +For the UNIX Epoch (00:00:00, 1 Jan 1970 UTC) +T} +filename file name +filesystem file system +hostname host name +inode i-node +lowercase lower case, lower-case +nonzero non-zero +pathname path name +pseudoterminal pseudo-terminal +privileged port T{ +reserved port, +system port +T} +real-time T{ +realtime, +real time +T} +run time runtime +saved set-group-ID T{ +saved group ID, +saved set-GID +T} +saved set-user-ID T{ +saved user ID, +saved set-UID +T} +set-group-ID set-GID, setgid +set-user-ID set-UID, setuid +superuser T{ +super user, +super-user +T} +superblock T{ +super block, +super-block +T} +symbolic link symlink +timestamp time stamp +timezone time zone +uppercase upper case, upper-case +usable useable +user space userspace +username user name +x86-64 x86_64 T{ +Except if referring to result of "uname\ \-m" or similar +T} +zeros zeroes +.TE +.PP +See also the discussion +.I Hyphenation of attributive compounds +below. +.SS Terms to avoid +The following table lists some terms to avoid using in man pages, +along with some suggested alternatives, +mainly to ensure consistency across pages. +.ad l +.TS +l l l +--- +l l l. +Avoid Use instead Notes + +32bit 32-bit T{ +same for 8-bit, 16-bit, etc. +T} +current process calling process T{ +A common mistake made by kernel programmers when writing man pages +T} +manpage T{ +man page, manual page +T} +minus infinity negative infinity +non-root unprivileged user +non-superuser unprivileged user +nonprivileged unprivileged +OS operating system +plus infinity positive infinity +pty pseudoterminal +tty terminal +Unices UNIX systems +Unixes UNIX systems +.TE +.ad +.\" +.SS Trademarks +Use the correct spelling and case for trademarks. +The following is a list of the correct spellings of various +relevant trademarks that are sometimes misspelled: +.IP +.TS +l. +DG/UX +HP-UX +UNIX +UnixWare +.TE +.SS NULL, NUL, null pointer, and null byte +A +.I null pointer +is a pointer that points to nothing, +and is normally indicated by the constant +.IR NULL . +On the other hand, +.I NUL +is the +.IR "null byte" , +a byte with the value 0, represented in C via the character constant +.IR \[aq]\e0\[aq] . +.PP +The preferred term for the pointer is "null pointer" or simply "NULL"; +avoid writing "NULL pointer". +.PP +The preferred term for the byte is "null byte". +Avoid writing "NUL", since it is too easily confused with "NULL". +Avoid also the terms "zero byte" and "null character". +The byte that terminates a C string should be described +as "the terminating null byte"; +strings may be described as "null-terminated", +but avoid the use of "NUL-terminated". +.SS Hyperlinks +For hyperlinks, use the +.IR .UR / .UE +macro pair +(see +.BR groff_man (7)). +This produces proper hyperlinks that can be used in a web browser, +when rendering a page with, say: +.PP +.in +4n +.EX +BROWSER=firefox man -H pagename +.EE +.in +.SS Use of e.g., i.e., etc., a.k.a., and similar +In general, the use of abbreviations such as "e.g.", "i.e.", "etc.", +"cf.", and "a.k.a." should be avoided, +in favor of suitable full wordings +("for example", "that is", "and so on", "compare to", "also known as"). +.PP +The only place where such abbreviations may be acceptable is in +.I short +parenthetical asides (e.g., like this one). +.PP +Always include periods in such abbreviations, as shown here. +In addition, "e.g." and "i.e." should always be followed by a comma. +.SS Em-dashes +The way to write an em-dash\[em]the glyph that appears +at either end of this subphrase\[em]in *roff is with the macro "\e[em]". +(On an ASCII terminal, an em-dash typically renders as two hyphens, +but in other typographical contexts it renders as a long dash.) +Em-dashes should be written +.I without +surrounding spaces. +.SS Hyphenation of attributive compounds +Compound terms should be hyphenated when used attributively +(i.e., to qualify a following noun). Some examples: +.IP +.TS +l. +32-bit value +command-line argument +floating-point number +run-time check +user-space function +wide-character string +.TE +.SS Hyphenation with multi, non, pre, re, sub, and so on +The general tendency in modern English is not to hyphenate +after prefixes such as "multi", "non", "pre", "re", "sub", and so on. +Manual pages should generally follow this rule when these prefixes are +used in natural English constructions with simple suffixes. +The following list gives some examples of the preferred forms: +.IP +.TS +l. +interprocess +multithreaded +multiprocess +nonblocking +nondefault +nonempty +noninteractive +nonnegative +nonportable +nonzero +preallocated +precreate +prerecorded +reestablished +reinitialize +rearm +reread +subcomponent +subdirectory +subsystem +.TE +.PP +Hyphens should be retained when the prefixes are used in nonstandard +English words, with trademarks, proper nouns, acronyms, or compound terms. +Some examples: +.IP +.TS +l. +non-ASCII +non-English +non-NULL +non-real-time +.TE +.PP +Finally, note that "re-create" and "recreate" are two different verbs, +and the former is probably what you want. +.\" +.SS Generating optimal glyphs +Where a real minus character is required (e.g., for numbers such as \-1, +for man page cross references such as +.BR utf\-8 (7), +or when writing options that have a leading dash, such as in +.IR "ls\ \-l"), +use the following form in the man page source: +.PP +.in +4n +.EX +\e\- +.EE +.in +.PP +This guideline applies also to code examples. +.PP +The use of real minus signs serves the following purposes: +.\" https://lore.kernel.org/linux-man/20210121061158.5ul7226fgbrmodbt@localhost.localdomain/ +.IP \[bu] 3 +To provide better renderings on various targets other than +ASCII terminals, +notably in PDF and on Unicode/UTF\-8-capable terminals. +.IP \[bu] +To generate glyphs that when copied from rendered pages will +produce real minus signs when pasted into a terminal. +.PP +To produce unslanted single quotes that render well in ASCII, UTF-8, and PDF, +use "\e[aq]" ("apostrophe quote"); for example +.PP +.in +4n +.EX +\e[aq]C\e[aq] +.EE +.in +.PP +where +.I C +is the quoted character. +This guideline applies also to character constants used in code examples. +.PP +Where a proper caret (\[ha]) that renders well in both a terminal and PDF +is required, use "\\[ha]". +This is especially necessary in code samples, +to get a nicely rendered caret when rendering to PDF. +.PP +Using a naked "\[ti]" character results in a poor rendering in PDF. +Instead use "\\[ti]". +This is especially necessary in code samples, +to get a nicely rendered tilde when rendering to PDF. +.\" +.SS Example programs and shell sessions +Manual pages may include example programs demonstrating how to +use a system call or library function. +However, note the following: +.IP \[bu] 3 +Example programs should be written in C. +.IP \[bu] +An example program is necessary and useful only if it demonstrates +something beyond what can easily be provided in a textual +description of the interface. +An example program that does nothing +other than call an interface usually serves little purpose. +.IP \[bu] +Example programs should ideally be short +(e.g., a good example can often be provided in less than 100 lines of code), +though in some cases longer programs may be necessary +to properly illustrate the use of an API. +.IP \[bu] +Expressive code is appreciated. +.IP \[bu] +Comments should included where helpful. +Complete sentences in free-standing comments should be +terminated by a period. +Periods should generally be omitted in "tag" comments +(i.e., comments that are placed on the same line of code); +such comments are in any case typically brief phrases +rather than complete sentences. +.IP \[bu] +Example programs should do error checking after system calls and +library function calls. +.IP \[bu] +Example programs should be complete, and compile without +warnings when compiled with \fIcc\ \-Wall\fP. +.IP \[bu] +Where possible and appropriate, example programs should allow +experimentation, by varying their behavior based on inputs +(ideally from command-line arguments, or alternatively, via +input read by the program). +.IP \[bu] +Example programs should be laid out according to Kernighan and +Ritchie style, with 4-space indents. +(Avoid the use of TAB characters in source code!) +The following command can be used to format your source code to +something close to the preferred style: +.IP +.in +4n +.EX +indent \-npro \-kr \-i4 \-ts4 \-sob \-l72 \-ss \-nut \-psl prog.c +.EE +.in +.IP \[bu] +For consistency, all example programs should terminate using either of: +.IP +.in +4n +.EX +exit(EXIT_SUCCESS); +exit(EXIT_FAILURE); +.EE +.in +.IP +Avoid using the following forms to terminate a program: +.IP +.in +4n +.EX +exit(0); +exit(1); +return n; +.EE +.in +.IP \[bu] +If there is extensive explanatory text before the +program source code, mark off the source code +with a subsection heading +.IR "Program source" , +as in: +.IP +.in +4n +.EX +\&.SS Program source +.EE +.in +.IP +Always do this if the explanatory text includes a shell session log. +.PP +If you include a shell session log demonstrating the use of a program +or other system feature: +.IP \[bu] 3 +Place the session log above the source code listing. +.IP \[bu] +Indent the session log by four spaces. +.IP \[bu] +Boldface the user input text, +to distinguish it from output produced by the system. +.PP +For some examples of what example programs should look like, see +.BR wait (2) +and +.BR pipe (2). +.SH EXAMPLES +For canonical examples of how man pages in the +.I man-pages +package should look, see +.BR pipe (2) +and +.BR fcntl (2). +.SH SEE ALSO +.BR man (1), +.BR man2html (1), +.BR attributes (7), +.BR groff (7), +.BR groff_man (7), +.BR man (7), +.BR mdoc (7) |