1MAN-PAGES(7)               Linux Programmer's Manual              MAN-PAGES(7)
2
3
4

NAME

6       man-pages - conventions for writing Linux man pages
7

SYNOPSIS

9       man [section] title
10

DESCRIPTION

12       This  page describes the conventions that should be employed when writ‐
13       ing man pages for the Linux man-pages project, which comprises Sections
14       2, 3, 4, 5, and 7 of the Linux manual pages.  The conventions described
15       on this page may also be useful for authors writing man pages for other
16       projects.
17
18   Sections of the Manual Pages
19       The manual Sections are traditionally defined as follows:
20
21       1 Commands (Programs)
22                 Those commands that can be executed by the user from within a
23                 shell.
24
25       2 System calls
26                 Those functions which must be performed by the kernel.
27
28       3 Library calls
29                 Most of the libc functions.
30
31       4 Special files (devices)
32                 Files found in /dev.
33
34       5 File formats and conventions
35                 The format for /etc/passwd and other human-readable files.
36
37       6 Games
38
39       7 Conventions and miscellaneous
40                 Overviews of various topics, conventions and protocols, char‐
41                 acter set standards, and miscellaneous other things.
42
43       8 System management commands
44                 Commands like mount(8), many of which only root can execute.
45
46   Macro package
47       New  manual  pages  should be marked up using the groff an.tmac package
48       described in man(7).  This choice is mainly for consistency:  the  vast
49       majority  of  existing  Linux  manual  pages  are marked up using these
50       macros.
51
52   Conventions for source file layout
53       Please limit source code line length to no more than about  75  charac‐
54       ters  wherever  possible.   This helps avoid line-wrapping in some mail
55       clients when patches are submitted inline.
56
57       New sentences should be started on new lines.  This makes it easier  to
58       see the effect of patches, which often operate at the level of individ‐
59       ual sentences.
60
61   Title line
62       The first command in a man page should be a TH command:
63
64              .TH title section date source manual
65
66       where:
67
68              title     The title of the man page, written in all caps  (e.g.,
69                        MAN-PAGES).
70
71              section   The  section  number  in  which the man page should be
72                        placed (e.g., 7).
73
74              date      The date of the last revision  —  remember  to  change
75                        this  every  time  a  change  is made to the man page,
76                        since this is the most general way  of  doing  version
77                        control.  Dates should be written in the form YYYY-MM-
78                        DD.
79
80              source    The source of the command, function, or system call.
81
82                        For those few man-pages pages in  Sections  1  and  8,
83                        probably you just want to write GNU.
84
85                        For system calls, just write Linux.  (An earlier prac‐
86                        tice was to write the version  number  of  the  kernel
87                        from  which the manual page was being written/checked.
88                        However, this was never done consistently, and so  was
89                        probably  worse  than  including  no  version  number.
90                        Henceforth, avoid including a version number.)
91
92                        For library calls that are part of glibc or one of the
93                        other  common  GNU  libraries, just use GNU C Library,
94                        GNU, or an empty string.
95
96                        For Section 4 pages, use Linux.
97
98                        In cases of doubt, just write Linux, or GNU.
99
100              manual    The title of the manual (e.g., for  Section  2  and  3
101                        pages in the man-pages package, use Linux Programmer's
102                        Manual).
103
104   Sections within a manual page
105       The list below shows conventional or suggested sections.   Most  manual
106       pages  should include at least the highlighted sections.  Arrange a new
107       manual page so that sections are placed in the order shown in the list.
108
109            NAME
110            SYNOPSIS
111            CONFIGURATION      [Normally only in Section 4]
112            DESCRIPTION
113            OPTIONS            [Normally only in Sections 1, 8]
114            EXIT STATUS        [Normally only in Sections 1, 8]
115            RETURN VALUE       [Normally only in Sections 2, 3]
116            ERRORS             [Typically only in Sections 2, 3]
117            ENVIRONMENT
118            FILES
119            VERSIONS           [Normally only in Sections 2, 3]
120            CONFORMING TO
121            NOTES
122            BUGS
123            EXAMPLE
124            SEE ALSO
125
126       Where a traditional heading would apply, please use it;  this  kind  of
127       consistency  can  make  the  information  easier to understand.  If you
128       must, you can create your own headings if they make  things  easier  to
129       understand  (this  can be especially useful for pages in Sections 4 and
130       5).  However, before doing this, consider whether  you  could  use  the
131       traditional  headings,  with  some  subsections (.SS) within those sec‐
132       tions.
133
134       The following list elaborates on the contents of each of the above sec‐
135       tions.
136
137       NAME          The  name  of this manual page.  See man(7) for important
138                     details of the line(s) that should follow  the  .SH  NAME
139                     command.
140
141       SYNOPSIS      briefly  describes  the  command or function's interface.
142                     For commands, this shows the syntax of  the  command  and
143                     its  arguments  (including options); boldface is used for
144                     as-is text and italics are used to  indicate  replaceable
145                     arguments.   Brackets  ([])  surround optional arguments,
146                     vertical bars (|) separate choices,  and  ellipses  (...)
147                     can  be  repeated.   For functions, it shows any required
148                     data declarations or #include directives, followed by the
149                     function declaration.
150
151                     Where  a  feature  test macro must be defined in order to
152                     obtain the declaration of a function (or a variable) from
153                     a header file, then the SYNOPSIS should indicate this, as
154                     described in feature_test_macros(7).
155
156       CONFIGURATION Configuration details for a device.   This  section  nor‐
157                     mally only appears in Section 4 pages.
158
159       DESCRIPTION   gives  an  explanation  of what the program, function, or
160                     format does.  Discuss how it  interacts  with  files  and
161                     standard  input,  and what it produces on standard output
162                     or standard error.   Omit  internals  and  implementation
163                     details  unless  they're  critical  for understanding the
164                     interface.  Describe the usual case; for  information  on
165                     command-line  options  of  a program use the OPTIONS sec‐
166                     tion.
167
168       OPTIONS       describes the command-line options accepted by a  program
169                     and  how  they  change its behavior.  This section should
170                     only appear for Section 1 and 8 manual pages.
171
172       EXIT STATUS   lists the possible exit status values of  a  program  and
173                     the  conditions  that  cause these values to be returned.
174                     This section should only appear for Section 1 and 8  man‐
175                     ual pages.
176
177       RETURN VALUE  For  Section  2 and 3 pages, this section gives a list of
178                     the values the library routine will return to the  caller
179                     and   the  conditions  that  cause  these  values  to  be
180                     returned.
181
182       ERRORS        For Section 2 and 3 manual pages, this is a list  of  the
183                     values  that  may  be  placed in errno in the event of an
184                     error, along with information  about  the  cause  of  the
185                     errors.  The error list should be in alphabetical order.
186
187       ENVIRONMENT   lists  all  environment variables that affect the program
188                     or function and how they affect it.
189
190       FILES         lists the files the program or  function  uses,  such  as
191                     configuration files, startup files, and files the program
192                     directly operates on.  Give the full  pathname  of  these
193                     files,  and  use  the  installation process to modify the
194                     directory part to match user preferences.  For many  pro‐
195                     grams,   the   default   installation   location   is  in
196                     /usr/local,  so  your  base  manual   page   should   use
197                     /usr/local as the base.
198
199       VERSIONS      A  brief  summary  of  the Linux kernel or glibc versions
200                     where a system call  or  library  function  appeared,  or
201                     changed  significantly  in  its  operation.  As a general
202                     rule, every new interface should include a VERSIONS  sec‐
203                     tion  in  its  manual page.  Unfortunately, many existing
204                     manual pages don't include this information (since  there
205                     was  no policy to do so when they were written).  Patches
206                     to remedy this are welcome, but, from the perspective  of
207                     programmers  writing  new code, this information probably
208                     only matters in the case of kernel interfaces  that  have
209                     been  added  in  Linux  2.4 or later (i.e., changes since
210                     kernel 2.2), and library functions that have  been  added
211                     to  glibc  since  version  2.1 (i.e., changes since glibc
212                     2.0).
213
214                     The syscalls(2) manual  page  also  provides  information
215                     about kernel versions in which various system calls first
216                     appeared.
217
218       CONFORMING TO describes any standards or conventions that relate to the
219                     function  or command described by the manual page.  For a
220                     page in Section 2 or 3,  this  section  should  note  the
221                     POSIX.1  version(s)  that  the call conforms to, and also
222                     whether the call is specified in C99.  (Don't  worry  too
223                     much  about  other standards like SUS, SUSv2, and XPG, or
224                     the SVr4 and 4.xBSD implementation standards, unless  the
225                     call  was  specified in those standards, but isn't in the
226                     current version of POSIX.1.)  (See standards(7).)
227
228                     If the call is not governed by any standards but commonly
229                     exists  on  other  systems,  note  them.   If the call is
230                     Linux-specific, note this.
231
232                     If this section consists of  just  a  list  of  standards
233                     (which  it  commonly  does),  terminate  the  list with a
234                     period ('.').
235
236       NOTES         provides miscellaneous notes.  For Section 2  and  3  man
237                     pages  you may find it useful to include subsections (SS)
238                     named Linux Notes and Glibc Notes.
239
240       BUGS          lists limitations, known defects or  inconveniences,  and
241                     other questionable activities.
242
243       EXAMPLE       provides  one  or more examples describing how this func‐
244                     tion, file or command is used.  For  details  on  writing
245                     example programs, see Example Programs below.
246
247       AUTHORS       lists authors of the documentation or program.  Use of an
248                     AUTHORS section is strongly discouraged.   Generally,  it
249                     is  better not to clutter every page with a list of (over
250                     time potentially numerous) authors; if you write or  sig‐
251                     nificantly amend a page, add a copyright notice as a com‐
252                     ment in the source file.  If you  are  the  author  of  a
253                     device  driver and want to include an address for report‐
254                     ing bugs, place this under the BUGS section.
255
256       SEE ALSO      provides a comma-separated list  of  related  man  pages,
257                     ordered  by  section  number  and  then alphabetically by
258                     name, possibly followed by other related pages  or  docu‐
259                     ments.  Do not terminate this with a period.
260
261   Font conventions
262       For  functions,  the arguments are always specified using italics, even
263       in the SYNOPSIS section, where the rest of the function is specified in
264       bold:
265
266           int myfunction(int argc, char **argv);
267
268       Variable names should, like argument names, be specified in italics.
269
270       Filenames   (whether   pathnames,   or   references  to  files  in  the
271       /usr/include directory) are always in italics (e.g., <stdio.h>), except
272       in  the  SYNOPSIS  section,  where  included  files  are in bold (e.g.,
273       #include <stdio.h>).  When referring to a standard include  file  under
274       /usr/include,  specify the header file surrounded by angle brackets, in
275       the usual C way (e.g., <stdio.h>).
276
277       Special macros, which are usually in upper case,  are  in  bold  (e.g.,
278       MAXINT).  Exception: don't boldface NULL.
279
280       When  enumerating  a  list  of error codes, the codes are in bold (this
281       list usually uses the .TP macro).
282
283       Complete commands should, if long, be written as in an indented line on
284       their own, for example
285
286           man 7 man-pages
287
288       If the command is short, then it can be included inline in the text, in
289       italic format, for example, man 7 man-pages.  In this case, it  may  be
290       worth  using  non-breaking spaces ("\ ") at suitable places in the com‐
291       mand.  Command options should be written in italics, e.g., -l.
292
293       Expressions, if not written on a  separate  indented  line,  should  be
294       specified  in  italics.   Again,  the use of non-breaking spaces may be
295       appropriate if the expression is inlined with normal text.
296
297       Any reference to the subject of the current manual page should be writ‐
298       ten with the name in bold.  If the subject is a function (i.e., this is
299       a Section 2 or 3 page), then the name should be followed by a  pair  of
300       parentheses  in  Roman (normal) font.  For example, in the fcntl(2) man
301       page, references to the subject  of  the  page  would  be  written  as:
302       fcntl().  The preferred way to write this in the source file is:
303
304           .BR fcntl ()
305
306       (Using  this format, rather than the use of "\fB...\fP()" makes it eas‐
307       ier to write tools that parse man page source files.)
308
309       Any reference to another man page should be written with  the  name  in
310       bold,  always  followed by the section number, formatted in Roman (nor‐
311       mal) font, without any separating spaces (e.g.,  intro(2)).   The  pre‐
312       ferred way to write this in the source file is:
313
314           .BR intro (2)
315
316       (Including  the  section  number  in  cross  references lets tools like
317       man2html(1) create properly hyperlinked pages.)
318
319   Spelling
320       Starting with release 2.59, man-pages follows American spelling conven‐
321       tions;  please  write all new pages and patches according to these con‐
322       ventions.
323
324   Example Programs and Shell Sessions
325       Manual pages can include example programs demonstrating how  to  use  a
326       system call or library function.  However, note the following:
327
328       *  Example programs should be written in C.
329
330       *  An  example  program is only necessary and useful if it demonstrates
331          something beyond what can easily be provided in a  textual  descrip‐
332          tion  of  the interface.  An example program that does nothing other
333          than call an interface usually serves little purpose.
334
335       *  Example programs should be fairly short (preferably  less  than  100
336          lines; ideally less than 50 lines).
337
338       *  Example  programs  should  do  error checking after system calls and
339          library function calls.
340
341       *  Example programs should be complete, and  compile  without  warnings
342          when compiled with cc -Wall.
343
344       *  Where possible and appropriate, example programs should allow exper‐
345          imentation, by varying their behavior based on inputs (ideally  from
346          command-line arguments, or alternatively, via input read by the pro‐
347          gram).
348
349       *  Example programs should be  laid  out  according  to  Kernighan  and
350          Ritchie  style, with 4-space indents.  (Avoid the use of TAB charac‐
351          ters in source code!)
352
353       For some examples of  what  example  programs  should  look  like,  see
354       wait(2) and pipe(2).
355
356       If  you  include  a shell session demonstrating the use of a program or
357       other system feature, boldface the user input text, to  distinguish  it
358       from output produced by the system.
359
360   Indentation of structure definitions, shell session logs, etc.
361       When  structure  definitions,  shell session logs, etc. are included in
362       running text, indent them by  4  spaces  (i.e.,  a  block  enclosed  by
363       .in +4n and .in).
364

EXAMPLE

366       For canonical examples of how man pages in the man-pages package should
367       look, see pipe(2) and fcntl(2).
368

SEE ALSO

370       man(1), man2html(1), groff(7), groff_man(7), man(7), mdoc(7)
371

COLOPHON

373       This page is part of release 3.22 of the Linux  man-pages  project.   A
374       description  of  the project, and information about reporting bugs, can
375       be found at http://www.kernel.org/doc/man-pages/.
376
377
378
379Linux                             2008-10-28                      MAN-PAGES(7)
Impressum