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

STYLE GUIDE

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

EXAMPLE

733       For canonical examples of how man pages in the man-pages package should
734       look, see pipe(2) and fcntl(2).
735

SEE ALSO

737       man(1), man2html(1),  attributes(7),  groff(7),  groff_man(7),  man(7),
738       mdoc(7)
739

COLOPHON

741       This  page  is  part of release 5.02 of the Linux man-pages project.  A
742       description of the project, information about reporting bugs,  and  the
743       latest     version     of     this    page,    can    be    found    at
744       https://www.kernel.org/doc/man-pages/.
745
746
747
748Linux                             2019-03-06                      MAN-PAGES(7)
Impressum