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  documents  the
14       user-space API provided by the Linux kernel and the GNU C library.  The
15       project thus provides most of the pages in Section 2, many of the pages
16       that appear in Sections 3, 4, and 7, and a few of the pages that appear
17       in Sections 1, 5, and 8 of the man pages on a Linux system.   The  con‐
18       ventions  described on this page may also be useful for authors writing
19       man pages for other projects.
20
21   Sections of the manual pages
22       The manual Sections are traditionally defined as follows:
23
24       1 User commands (Programs)
25              Commands that can be executed by the user from within a shell.
26
27       2 System calls
28              Functions which wrap operations performed by the kernel.
29
30       3 Library calls
31              All library functions excluding the system call  wrappers  (Most
32              of the libc functions).
33
34       4 Special files (devices)
35              Files found in /dev which allow to access to devices through the
36              kernel.
37
38       5 File formats and configuration files
39              Describes various human-readable file formats and  configuration
40              files.
41
42       6 Games
43              Games and funny little programs available on the system.
44
45       7 Overview, conventions, and miscellaneous
46              Overviews  or  descriptions  of  various topics, conventions and
47              protocols, character set standards, the standard filesystem lay‐
48              out, and miscellaneous other things.
49
50       8 System management commands
51              Commands like mount(8), many of which only root can execute.
52
53   Macro package
54       New  manual  pages  should be marked up using the groff an.tmac package
55       described in man(7).  This choice is mainly for consistency:  the  vast
56       majority  of  existing  Linux  manual  pages  are marked up using these
57       macros.
58
59   Conventions for source file layout
60       Please limit source code line length to no more than about  75  charac‐
61       ters  wherever  possible.   This helps avoid line-wrapping in some mail
62       clients when patches are submitted inline.
63
64   Title line
65       The first command in a man page should be a TH command:
66
67              .TH title section date source manual
68
69       The arguments of the command are as follows:
70
71       title  The title of the man page,  written  in  all  caps  (e.g.,  MAN-
72              PAGES).
73
74       section
75              The section number in which the man page should be placed (e.g.,
76              7).
77
78       date   The date of the last nontrivial change that was made to the  man
79              page.   (Within  the man-pages project, the necessary updates to
80              these timestamps are handled automatically by scripts, so  there
81              is  no  need to manually update them as part of a patch.)  Dates
82              should be written in the form YYYY-MM-DD.
83
84       source The source of the command, function, or system call.
85
86              For those few man-pages pages in Sections 1 and 8, probably  you
87              just want to write GNU.
88
89              For system calls, just write Linux.  (An earlier practice was to
90              write the version number of the kernel  from  which  the  manual
91              page  was  being  written/checked.  However, this was never done
92              consistently, and so was probably worse than including  no  ver‐
93              sion number.  Henceforth, avoid including a version number.)
94
95              For  library  calls  that  are part of glibc or one of the other
96              common GNU libraries, just use GNU C Library, GNU, or  an  empty
97              string.
98
99              For Section 4 pages, use Linux.
100
101              In cases of doubt, just write Linux, or GNU.
102
103       manual The  title of the manual (e.g., for Section 2 and 3 pages in the
104              man-pages package, use Linux Programmer's Manual).
105
106   Sections within a manual page
107       The list below shows conventional or suggested sections.   Most  manual
108       pages  should include at least the highlighted sections.  Arrange a new
109       manual page so that sections are placed in the order shown in the list.
110
111              NAME
112              SYNOPSIS
113              CONFIGURATION    [Normally only in Section 4]
114              DESCRIPTION
115              OPTIONS          [Normally only in Sections 1, 8]
116              EXIT STATUS      [Normally only in Sections 1, 8]
117              RETURN VALUE     [Normally only in Sections 2, 3]
118              ERRORS           [Typically only in Sections 2, 3]
119              ENVIRONMENT
120              FILES
121              VERSIONS         [Normally only in Sections 2, 3]
122              ATTRIBUTES       [Normally only in Sections 2, 3]
123              CONFORMING TO
124              NOTES
125              BUGS
126              EXAMPLES
127              AUTHORS          [Discouraged]
128              REPORTING BUGS   [Not used in man-pages]
129              COPYRIGHT        [Not used in man-pages]
130              SEE ALSO
131
132       Where a traditional heading would apply, please use it;  this  kind  of
133       consistency  can  make  the  information  easier to understand.  If you
134       must, you can create your own headings if they make  things  easier  to
135       understand  (this  can be especially useful for pages in Sections 4 and
136       5).  However, before doing this, consider whether  you  could  use  the
137       traditional  headings,  with  some  subsections (.SS) within those sec‐
138       tions.
139
140       The following list elaborates on the contents of each of the above sec‐
141       tions.
142
143       NAME   The name of this manual page.
144
145              See man(7) for important details of the line(s) that should fol‐
146              low the .SH NAME command.  All words in this line (including the
147              word immediately following the "\-") should be in lowercase, ex‐
148              cept where English or technical terminological  convention  dic‐
149              tates otherwise.
150
151       SYNOPSIS
152              A brief summary of the command or function's interface.
153
154              For commands, this shows the syntax of the command and its argu‐
155              ments (including options); boldface is used for as-is  text  and
156              italics  are  used  to indicate replaceable arguments.  Brackets
157              ([]) surround optional arguments,  vertical  bars  (|)  separate
158              choices,  and ellipses (...) can be repeated.  For functions, it
159              shows any required data  declarations  or  #include  directives,
160              followed by the function declaration.
161
162              Where  a  feature  test macro must be defined in order to obtain
163              the declaration of a function (or  a  variable)  from  a  header
164              file,  then  the  SYNOPSIS should indicate this, as described in
165              feature_test_macros(7).
166
167       CONFIGURATION
168              Configuration details for a device.
169
170              This section normally appears only in Section 4 pages.
171
172       DESCRIPTION
173              An explanation of what the program, function, or format does.
174
175              Discuss how it interacts with files and standard input, and what
176              it  produces  on standard output or standard error.  Omit inter‐
177              nals and implementation details unless they're critical for  un‐
178              derstanding  the interface.  Describe the usual case; for infor‐
179              mation on command-line options of a program use the OPTIONS sec‐
180              tion.
181
182              When  describing  new behavior or new flags for a system call or
183              library function, be careful to note the  kernel  or  C  library
184              version  that  introduced  the  change.  The preferred method of
185              noting this information for flags is as part of a .TP  list,  in
186              the following form (here, for a new system call flag):
187
188                       XYZ_FLAG (since Linux 3.7)
189                              Description of flag...
190
191              Including  version information is especially useful to users who
192              are constrained to using older  kernel  or  C  library  versions
193              (which is typical in embedded systems, for example).
194
195       OPTIONS
196              A  description of the command-line options accepted by a program
197              and how they change its behavior.
198
199              This section should appear only  for  Section  1  and  8  manual
200              pages.
201
202       EXIT STATUS
203              A  list  of the possible exit status values of a program and the
204              conditions that cause these values to be returned.
205
206              This section should appear only  for  Section  1  and  8  manual
207              pages.
208
209       RETURN VALUE
210              For Section 2 and 3 pages, this section gives a list of the val‐
211              ues the library routine will return to the caller and the condi‐
212              tions that cause these values to be returned.
213
214       ERRORS For  Section  2 and 3 manual pages, this is a list of the values
215              that may be placed in errno in the event of an error, along with
216              information about the cause of the errors.
217
218              Where  several  different conditions produce the same error, the
219              preferred approach is to create separate list entries (with  du‐
220              plicate error names) for each of the conditions.  This makes the
221              separate conditions clear, may make the list easier to read, and
222              allows  metainformation  (e.g.,  kernel version number where the
223              condition first became applicable) to be more easily marked  for
224              each condition.
225
226              The error list should be in alphabetical order.
227
228       ENVIRONMENT
229              A  list  of all environment variables that affect the program or
230              function and how they affect it.
231
232       FILES  A list of the files the program or function uses, such  as  con‐
233              figuration  files, startup files, and files the program directly
234              operates on.
235
236              Give the full pathname of these files, and use the  installation
237              process  to modify the directory part to match user preferences.
238              For many programs,  the  default  installation  location  is  in
239              /usr/local,  so  your  base manual page should use /usr/local as
240              the base.
241
242       ATTRIBUTES
243              A summary of various attributes of the function(s) documented on
244              this page.  See attributes(7) for further details.
245
246       VERSIONS
247              A  brief  summary  of the Linux kernel or glibc versions where a
248              system call or library function appeared,  or  changed  signifi‐
249              cantly in its operation.
250
251              As a general rule, every new interface should include a VERSIONS
252              section in its manual page.  Unfortunately, many existing manual
253              pages  don't include this information (since there was no policy
254              to do so when they were written).  Patches to  remedy  this  are
255              welcome,  but,  from  the perspective of programmers writing new
256              code, this information probably matters only in the case of ker‐
257              nel interfaces that have been added in Linux 2.4 or later (i.e.,
258              changes since kernel 2.2), and library functions that have  been
259              added  to  glibc  since  version  2.1 (i.e., changes since glibc
260              2.0).
261
262              The syscalls(2) manual page also provides information about ker‐
263              nel versions in which various system calls first appeared.
264
265       CONFORMING TO
266              A description of any standards or conventions that relate to the
267              function or command described by the manual page.
268
269              The preferred terms to use for the various standards are  listed
270              as headings in standards(7).
271
272              For  a  page  in  Section  2  or 3, this section should note the
273              POSIX.1 version(s) that the call conforms to, and  also  whether
274              the call is specified in C99.  (Don't worry too much about other
275              standards like SUS, SUSv2, and XPG, or the SVr4 and  4.xBSD  im‐
276              plementation  standards,  unless the call was specified in those
277              standards, but isn't in the current version of POSIX.1.)
278
279              If the call is not governed by any standards but commonly exists
280              on  other  systems,  note  them.  If the call is Linux-specific,
281              note this.
282
283              If this section consists of just a list of standards  (which  it
284              commonly does), terminate the list with a period ('.').
285
286       NOTES  Miscellaneous notes.
287
288              For  Section 2 and 3 man pages you may find it useful to include
289              subsections (SS) named Linux Notes and Glibc Notes.
290
291              In Section 2, use the heading C  library/kernel  differences  to
292              mark  off  notes  that describe the differences (if any) between
293              the C library wrapper function for a system  call  and  the  raw
294              system call interface provided by the kernel.
295
296       BUGS   A  list  of  limitations,  known  defects or inconveniences, and
297              other questionable activities.
298
299       EXAMPLES
300              One or more examples demonstrating how this  function,  file  or
301              command is used.
302
303              For  details  on  writing example programs, see Example programs
304              below.
305
306       AUTHORS
307              A list of authors of the documentation or program.
308
309              Use of an AUTHORS section is strongly  discouraged.   Generally,
310              it is better not to clutter every page with a list of (over time
311              potentially numerous) authors; if  you  write  or  significantly
312              amend  a page, add a copyright notice as a comment in the source
313              file.  If you are the author of a device driver and want to  in‐
314              clude  an  address for reporting bugs, place this under the BUGS
315              section.
316
317       REPORTING BUGS
318              The man-pages project doesn't use a REPORTING  BUGS  section  in
319              manual pages.  Information on reporting bugs is instead supplied
320              in the  script-generated  COLOPHON  section.   However,  various
321              projects  do use a REPORTING BUGS section.  it is recommended to
322              place it near the foot of the page.
323
324       COPYRIGHT
325              The man-pages project doesn't use a COPYRIGHT section in  manual
326              pages.   Copyright information is instead maintained in the page
327              source.  In pages where this section is present,  it  is  recom‐
328              mended  to  place  it  near the foot of the page, just above SEE
329              ALSO.
330
331       SEE ALSO
332              A comma-separated list of related man pages,  possibly  followed
333              by other related pages or documents.
334
335              The list should be ordered by section number and then alphabeti‐
336              cally by name.  Do not terminate this list with a period.
337
338              Where the SEE ALSO list contains many long manual page names, to
339              improve the visual result of the output, it may be useful to em‐
340              ploy the .ad l (don't right justify) and .nh  (don't  hyphenate)
341              directives.   Hyphenation  of  individual page names can be pre‐
342              vented by preceding words with the string "\%".
343
344              Given the distributed, autonomous nature of  FOSS  projects  and
345              their documentation, it is sometimes necessary—and in many cases
346              desirable—that the SEE ALSO section includes references to  man‐
347              ual pages provided by other projects.
348

STYLE GUIDE

350       The  following  subsections  describe  the preferred style for the man-
351       pages project.  For details not covered below, the  Chicago  Manual  of
352       Style is usually a good source; try also grepping for preexisting usage
353       in the project source tree.
354
355   Use of gender-neutral language
356       As far as possible, use gender-neutral language  in  the  text  of  man
357       pages.  Use of "they" ("them", "themself", "their") as a gender-neutral
358       singular pronoun is acceptable.
359
360   Formatting conventions for manual pages describing commands
361       For manual pages that describe a command (typically in Sections  1  and
362       8),  the arguments are always specified using italics, even in the SYN‐
363       OPSIS section.
364
365       The name of the command, and its options, should always be formatted in
366       bold.
367
368   Formatting conventions for manual pages describing functions
369       For  manual  pages that describe functions (typically in Sections 2 and
370       3), the arguments are always specified using italics, even in the  SYN‐
371       OPSIS section, where the rest of the function is specified in bold:
372
373           int myfunction(int argc, char **argv);
374
375       Variable names should, like argument names, be specified in italics.
376
377       Any reference to the subject of the current manual page should be writ‐
378       ten with the name in bold followed by a pair of  parentheses  in  Roman
379       (normal)  font.   For  example, in the fcntl(2) man page, references to
380       the subject of the page would be written as:  fcntl().   The  preferred
381       way to write this in the source file is:
382
383           .BR fcntl ()
384
385       (Using  this format, rather than the use of "\fB...\fP()" makes it eas‐
386       ier to write tools that parse man page source files.)
387
388   Use semantic newlines
389       In the source of a manual page, new sentences should be started on  new
390       lines,  and  long  sentences  should  split into lines at clause breaks
391       (commas, semicolons, colons, and so on).   This  convention,  sometimes
392       known  as  "semantic  newlines",  makes  it easier to see the effect of
393       patches, which often operate at the level of  individual  sentences  or
394       sentence clauses.
395
396   Formatting conventions (general)
397       Paragraphs  should be separated by suitable markers (usually either .PP
398       or .IP).  Do not separate paragraphs using blank lines, as this results
399       in poor rendering in some output formats (such as PostScript and PDF).
400
401       Filenames (whether pathnames, or references to header files) are always
402       in italics (e.g., <stdio.h>), except in the SYNOPSIS section, where in‐
403       cluded files are in bold (e.g., #include <stdio.h>).  When referring to
404       a standard header file include, specify the header file  surrounded  by
405       angle brackets, in the usual C way (e.g., <stdio.h>).
406
407       Special macros, which are usually in uppercase, are in bold (e.g., MAX‐
408       INT).  Exception: don't boldface NULL.
409
410       When enumerating a list of error codes, the codes  are  in  bold  (this
411       list usually uses the .TP macro).
412
413       Complete  commands  should,  if long, be written as an indented line on
414       their own, with a blank line before and after the command, for example
415
416           man 7 man-pages
417
418       If the command is short, then it can be included inline in the text, in
419       italic  format,  for example, man 7 man-pages.  In this case, it may be
420       worth using nonbreaking spaces ("\ ") at suitable places  in  the  com‐
421       mand.  Command options should be written in italics (e.g., -l).
422
423       Expressions,  if  not  written  on  a separate indented line, should be
424       specified in italics.  Again, the use of nonbreaking spaces may be  ap‐
425       propriate if the expression is inlined with normal text.
426
427       When  showing example shell sessions, user input should be formatted in
428       bold, for example
429
430           $ date
431           Thu Jul  7 13:01:27 CEST 2016
432
433       Any reference to another man page should be written with  the  name  in
434       bold,  always  followed by the section number, formatted in Roman (nor‐
435       mal) font, without any separating spaces (e.g.,  intro(2)).   The  pre‐
436       ferred way to write this in the source file is:
437
438           .BR intro (2)
439
440       (Including  the  section  number  in  cross  references lets tools like
441       man2html(1) create properly hyperlinked pages.)
442
443       Control characters should be written in bold face, with no quotes;  for
444       example, ^X.
445
446   Spelling
447       Starting with release 2.59, man-pages follows American spelling conven‐
448       tions (previously, there was a  random  mix  of  British  and  American
449       spellings);  please  write all new pages and patches according to these
450       conventions.
451
452       Aside from the well-known spelling differences, there are a  few  other
453       subtleties to watch for:
454
455       *  American  English  tends to use the forms "backward", "upward", "to‐
456          ward", and so on rather than the  British  forms  "backwards",  "up‐
457          wards", "towards", and so on.
458
459   BSD version numbers
460       The  classical  scheme for writing BSD version numbers is x.yBSD, where
461       x.y is the version number (e.g., 4.2BSD).  Avoid forms such as BSD 4.3.
462
463   Capitalization
464       In subsection ("SS") headings, capitalize the first word in  the  head‐
465       ing,  but  otherwise  use  lowercase, except where English usage (e.g.,
466       proper nouns) or programming language  requirements  (e.g.,  identifier
467       names) dictate otherwise.  For example:
468
469           .SS Unicode under Linux
470
471   Indentation of structure definitions, shell session logs, and so on
472       When  structure definitions, shell session logs, and so on are included
473       in running text, indent them by 4 spaces (i.e.,  a  block  enclosed  by
474       .in +4n and .in), format them using the .EX and EE macros, and surround
475       them with suitable paragraph markers (either .PP or .IP).  For example:
476
477               .PP
478               .in +4n
479               .EX
480               int
481               main(int argc, char *argv[])
482               {
483                   return 0;
484               }
485               .EE
486               .in
487               .PP
488
489   Preferred terms
490       The following table lists some preferred terms to  use  in  man  pages,
491       mainly to ensure consistency across pages.
492
493       Term                 Avoid using              Notes
494       ──────────────────────────────────────────────────────────────────
495
496       bit mask             bitmask
497       built-in             builtin
498       Epoch                epoch                    For  the UNIX Epoch
499                                                     (00:00:00,  1   Jan
500                                                     1970 UTC)
501       filename             file name
502       filesystem           file system
503       hostname             host name
504       inode                i-node
505       lowercase            lower case, lower-case
506       nonzero              non-zero
507       pathname             path name
508       pseudoterminal       pseudo-terminal
509       privileged port      reserved  port, system
510                            port
511       real-time            realtime, real time
512       run time             runtime
513       saved set-group-ID   saved group ID,  saved
514                            set-GID
515       saved set-user-ID    saved  user  ID, saved
516                            set-UID
517       set-group-ID         set-GID, setgid
518       set-user-ID          set-UID, setuid
519       superuser            super user, super-user
520       superblock           super  block,   super-
521                            block
522       timestamp            time stamp
523       timezone             time zone
524       uppercase            upper case, upper-case
525       usable               useable
526       user space           userspace
527       username             user name
528       x86-64               x86_64                   Except if referring
529                                                     to result  of  "un‐
530                                                     ame -m" or similar
531       zeros                zeroes
532
533       See also the discussion Hyphenation of attributive compounds below.
534
535   Terms to avoid
536       The following table lists some terms to avoid using in man pages, along
537       with some suggested alternatives, mainly to ensure  consistency  across
538       pages.
539
540       Avoid             Use instead           Notes
541       ────────────────────────────────────────────────────────────
542
543       32bit             32-bit                same   for   8-bit,
544                                               16-bit, etc.
545       current process   calling process       A  common   mistake
546                                               made by kernel pro‐
547                                               grammers when writ‐
548                                               ing man pages
549       manpage           man   page,  manual
550                         page
551       minus infinity    negative infinity
552       non-root          unprivileged user
553       non-superuser     unprivileged user
554       nonprivileged     unprivileged
555       OS                operating system
556       plus infinity     positive infinity
557       pty               pseudoterminal
558       tty               terminal
559       Unices            UNIX systems
560       Unixes            UNIX systems
561
562   Trademarks
563       Use the correct spelling and case for trademarks.  The following  is  a
564       list  of  the correct spellings of various relevant trademarks that are
565       sometimes misspelled:
566
567            DG/UX
568            HP-UX
569            UNIX
570            UnixWare
571
572   NULL, NUL, null pointer, and null character
573       A null pointer is a pointer that points to nothing, and is normally in‐
574       dicated by the constant NULL.  On the other hand, NUL is the null byte,
575       a byte with the value 0, represented in C via  the  character  constant
576       '\0'.
577
578       The  preferred term for the pointer is "null pointer" or simply "NULL";
579       avoid writing "NULL pointer".
580
581       The preferred term for the byte is "null byte".  Avoid  writing  "NUL",
582       since  it  is  too  easily  confused with "NULL".  Avoid also the terms
583       "zero byte" and "null character".  The byte that terminates a C  string
584       should  be described as "the terminating null byte"; strings may be de‐
585       scribed as "null-terminated", but avoid the use of "NUL-terminated".
586
587   Hyperlinks
588       For hyperlinks, use the .UR/.UE macro pair  (see  groff_man(7)).   This
589       produces proper hyperlinks that can be used in a web browser, when ren‐
590       dering a page with, say:
591
592            BROWSER=firefox man -H pagename
593
594   Use of e.g., i.e., etc., a.k.a., and similar
595       In general, the use of abbreviations such as  "e.g.",  "i.e.",  "etc.",
596       "cf.",  and "a.k.a." should be avoided, in favor of suitable full word‐
597       ings ("for example", "that is", "and so on", "compare to", "also  known
598       as").
599
600       The  only  place where such abbreviations may be acceptable is in short
601       parenthetical asides (e.g., like this one).
602
603       Always include periods in such abbreviations, as shown here.  In  addi‐
604       tion, "e.g." and "i.e." should always be followed by a comma.
605
606   Em-dashes
607       The  way  to  write  an em-dash—the glyph that appears at either end of
608       this subphrase—in *roff is with the macro "\(em".  (On an ASCII  termi‐
609       nal,  an  em-dash  typically renders as two hyphens, but in other typo‐
610       graphical contexts it renders as a long  dash.)   Em-dashes  should  be
611       written without surrounding spaces.
612
613   Hyphenation of attributive compounds
614       Compound  terms  should be hyphenated when used attributively (i.e., to
615       qualify a following noun). Some examples:
616
617           32-bit value
618           command-line argument
619           floating-point number
620           run-time check
621           user-space function
622           wide-character string
623
624   Hyphenation with multi, non, pre, re, sub, and so on
625       The general tendency in modern English is not to hyphenate  after  pre‐
626       fixes  such  as  "multi", "non", "pre", "re", "sub", and so on.  Manual
627       pages should generally follow this rule when these prefixes are used in
628       natural English constructions with simple suffixes.  The following list
629       gives some examples of the preferred forms:
630
631           interprocess
632           multithreaded
633           multiprocess
634           nonblocking
635           nondefault
636           nonempty
637           noninteractive
638           nonnegative
639           nonportable
640           nonzero
641           preallocated
642           precreate
643           prerecorded
644           reestablished
645           reinitialize
646           rearm
647           reread
648           subcomponent
649           subdirectory
650           subsystem
651
652       Hyphens should be retained when the prefixes are  used  in  nonstandard
653       English  words,  with  trademarks,  proper nouns, acronyms, or compound
654       terms.  Some examples:
655
656           non-ASCII
657           non-English
658           non-NULL
659           non-real-time
660
661       Finally, note that "re-create" and "recreate" are two different  verbs,
662       and the former is probably what you want.
663
664   Generating optimal glyphs
665       Where a real minus character is required (e.g., for numbers such as -1,
666       for man page cross references such as utf-8(7), or when writing options
667       that  have a leading dash, such as in ls -l), use the following form in
668       the man page source:
669
670           \-
671
672       This guideline applies also to code examples.
673
674       To produce unslanted single quotes that render well  in  ASCII,  UTF-8,
675       and PDF, use "\(aq" ("apostrophe quote"); for example
676
677           \(aqC\(aq
678
679       where  C is the quoted character.  This guideline applies also to char‐
680       acter constants used in code examples.
681
682       Where a proper caret (^) that renders well in both a terminal  and  PDF
683       is required, use "\(ha".  This is especially necessary in code samples,
684       to get a nicely rendered caret when rendering to PDF.
685
686       Using a naked "~" character results in a poor rendering  in  PDF.   In‐
687       stead use "\(ti".  This is especially necessary in code samples, to get
688       a nicely rendered tilde when rendering to PDF.
689
690   Example programs and shell sessions
691       Manual pages may include example programs demonstrating how  to  use  a
692       system call or library function.  However, note the following:
693
694       *  Example programs should be written in C.
695
696       *  An  example  program is necessary and useful only if it demonstrates
697          something beyond what can easily be provided in a  textual  descrip‐
698          tion  of  the interface.  An example program that does nothing other
699          than call an interface usually serves little purpose.
700
701       *  Example programs should ideally be short (e.g., a good  example  can
702          often  be  provided  in less than 100 lines of code), though in some
703          cases longer programs may be necessary to  properly  illustrate  the
704          use of an API.
705
706       *  Expressive code and useful comments are appreciated.
707
708       *  Example programs should do error checking after system calls and li‐
709          brary function calls.
710
711       *  Example programs should be complete, and  compile  without  warnings
712          when compiled with cc -Wall.
713
714       *  Where possible and appropriate, example programs should allow exper‐
715          imentation, by varying their behavior based on inputs (ideally  from
716          command-line arguments, or alternatively, via input read by the pro‐
717          gram).
718
719       *  Example programs should be  laid  out  according  to  Kernighan  and
720          Ritchie  style, with 4-space indents.  (Avoid the use of TAB charac‐
721          ters in source code!)  The following command can be used  to  format
722          your source code to something close to the preferred style:
723
724              indent -npro -kr -i4 -ts4 -sob -l72 -ss -nut -psl prog.c
725
726       *  For  consistency, all example programs should terminate using either
727          of:
728
729               exit(EXIT_SUCCESS);
730               exit(EXIT_FAILURE);
731
732          Avoid using the following forms to terminate a program:
733
734              exit(0);
735              exit(1);
736              return n;
737
738       *  If there is extensive explanatory text  before  the  program  source
739          code,  mark  off  the  source code with a subsection heading Program
740          source, as in:
741
742              .SS Program source
743
744          Always do this if the explanatory text includes a shell session log.
745
746       If you include a shell session log demonstrating the use of  a  program
747       or other system feature:
748
749       *  Place the session log above the source code listing
750
751       *  Indent the session log by four spaces.
752
753       *  Boldface the user input text, to distinguish it from output produced
754          by the system.
755
756       For some examples of  what  example  programs  should  look  like,  see
757       wait(2) and pipe(2).
758

EXAMPLES

760       For canonical examples of how man pages in the man-pages package should
761       look, see pipe(2) and fcntl(2).
762

SEE ALSO

764       man(1), man2html(1),  attributes(7),  groff(7),  groff_man(7),  man(7),
765       mdoc(7)
766

COLOPHON

768       This  page  is  part of release 5.10 of the Linux man-pages project.  A
769       description of the project, information about reporting bugs,  and  the
770       latest     version     of     this    page,    can    be    found    at
771       https://www.kernel.org/doc/man-pages/.
772
773
774
775Linux                             2020-08-13                      MAN-PAGES(7)
Impressum