1man-pages(7)           Miscellaneous Information 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-section
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 name and version of the project  that  provides  the  manual
85              page  (not necessarily the package that provides the functional‐
86              ity).
87
88       manual-section
89              Normally, this should be empty, since the default value will  be
90              good.
91
92   Sections within a manual page
93       The  list  below shows conventional or suggested sections.  Most manual
94       pages should include at least the highlighted sections.  Arrange a  new
95       manual page so that sections are placed in the order shown in the list.
96
97              NAME
98              LIBRARY          [Normally only in Sections 2, 3]
99              SYNOPSIS
100              CONFIGURATION    [Normally only in Section 4]
101              DESCRIPTION
102              OPTIONS          [Normally only in Sections 1, 8]
103              EXIT STATUS      [Normally only in Sections 1, 8]
104              RETURN VALUE     [Normally only in Sections 2, 3]
105              ERRORS           [Typically only in Sections 2, 3]
106              ENVIRONMENT
107              FILES
108              ATTRIBUTES       [Normally only in Sections 2, 3]
109              VERSIONS         [Normally only in Sections 2, 3]
110              STANDARDS
111              HISTORY
112              NOTES
113              CAVEATS
114              BUGS
115              EXAMPLES
116              AUTHORS          [Discouraged]
117              REPORTING BUGS   [Not used in man-pages]
118              COPYRIGHT        [Not used in man-pages]
119              SEE ALSO
120
121       Where  a  traditional  heading would apply, please use it; this kind of
122       consistency can make the information  easier  to  understand.   If  you
123       must,  you  can  create your own headings if they make things easier to
124       understand (this can be especially useful for pages in Sections  4  and
125       5).   However,  before  doing  this, consider whether you could use the
126       traditional headings, with some subsections  (.SS)  within  those  sec‐
127       tions.
128
129       The following list elaborates on the contents of each of the above sec‐
130       tions.
131
132       NAME   The name of this manual page.
133
134              See man(7) for important details of the line(s) that should fol‐
135              low the .SH NAME command.  All words in this line (including the
136              word immediately following the "\-") should be in lowercase, ex‐
137              cept  where  English or technical terminological convention dic‐
138              tates otherwise.
139
140       LIBRARY
141              The library providing a symbol.
142
143              It shows the common name of the library, and in parentheses, the
144              name  of the library file and, if needed, the linker flag needed
145              to link a program against it: (libfoo[, -lfoo]).
146
147       SYNOPSIS
148              A brief summary of the command or function's interface.
149
150              For commands, this shows the syntax of the command and its argu‐
151              ments  (including  options); boldface is used for as-is text and
152              italics are used to indicate  replaceable  arguments.   Brackets
153              ([])  surround  optional  arguments,  vertical bars (|) separate
154              choices, and ellipses (...) can be repeated.  For functions,  it
155              shows  any  required  data  declarations or #include directives,
156              followed by the function declaration.
157
158              Where a feature test macro must be defined in  order  to  obtain
159              the  declaration  of  a  function  (or a variable) from a header
160              file, then the SYNOPSIS should indicate this,  as  described  in
161              feature_test_macros(7).
162
163       CONFIGURATION
164              Configuration details for a device.
165
166              This section normally appears only in Section 4 pages.
167
168       DESCRIPTION
169              An explanation of what the program, function, or format does.
170
171              Discuss how it interacts with files and standard input, and what
172              it produces on standard output or standard error.   Omit  inter‐
173              nals  and implementation details unless they're critical for un‐
174              derstanding the interface.  Describe the usual case; for  infor‐
175              mation on command-line options of a program use the OPTIONS sec‐
176              tion.
177
178              When describing new behavior or new flags for a system  call  or
179              library  function,  be  careful  to note the kernel or C library
180              version that introduced the change.   The  preferred  method  of
181              noting  this  information for flags is as part of a .TP list, in
182              the following form (here, for a new system call flag):
183
184                       XYZ_FLAG (since Linux 3.7)
185                              Description of flag...
186
187              Including version information is especially useful to users  who
188              are  constrained  to  using  older  kernel or C library versions
189              (which is typical in embedded systems, for example).
190
191       OPTIONS
192              A description of the command-line options accepted by a  program
193              and how they change its behavior.
194
195              This  section  should  appear  only  for  Section 1 and 8 manual
196              pages.
197
198       EXIT STATUS
199              A list of the possible exit status values of a program  and  the
200              conditions that cause these values to be returned.
201
202              This  section  should  appear  only  for  Section 1 and 8 manual
203              pages.
204
205       RETURN VALUE
206              For Section 2 and 3 pages, this section gives a list of the val‐
207              ues the library routine will return to the caller and the condi‐
208              tions that cause these values to be returned.
209
210       ERRORS For Section 2 and 3 manual pages, this is a list of  the  values
211              that may be placed in errno in the event of an error, along with
212              information about the cause of the errors.
213
214              Where several different conditions produce the same  error,  the
215              preferred  approach is to create separate list entries (with du‐
216              plicate error names) for each of the conditions.  This makes the
217              separate conditions clear, may make the list easier to read, and
218              allows metainformation (e.g., kernel version  number  where  the
219              condition  first became applicable) to be more easily marked for
220              each condition.
221
222              The error list should be in alphabetical order.
223
224       ENVIRONMENT
225              A list of all environment variables that affect the  program  or
226              function and how they affect it.
227
228       FILES  A  list  of the files the program or function uses, such as con‐
229              figuration files, startup files, and files the program  directly
230              operates on.
231
232              Give  the full pathname of these files, and use the installation
233              process to modify the directory part to match user  preferences.
234              For  many  programs,  the  default  installation  location is in
235              /usr/local, so your base manual page should  use  /usr/local  as
236              the base.
237
238       ATTRIBUTES
239              A summary of various attributes of the function(s) documented on
240              this page.  See attributes(7) for further details.
241
242       VERSIONS
243              A summary of systems where  the  API  performs  differently,  or
244              where there's a similar API.
245
246       STANDARDS
247              A description of any standards or conventions that relate to the
248              function or command described by the manual page.
249
250              The preferred terms to use for the various standards are  listed
251              as headings in standards(7).
252
253              This  section should note the current standards to which the API
254              conforms to.
255
256              If the API is not governed by any standards but commonly  exists
257              on  other  systems, note them.  If the call is Linux-specific or
258              GNU-specific, note this.  If it's available in  the  BSDs,  note
259              that.
260
261              If  this  section consists of just a list of standards (which it
262              commonly does), terminate the list with a period ('.').
263
264       HISTORY
265              A brief summary of the Linux kernel or glibc  versions  where  a
266              system  call  or  library function appeared, or changed signifi‐
267              cantly in its operation.
268
269              As a general rule, every new interface should include a  HISTORY
270              section in its manual page.  Unfortunately, many existing manual
271              pages don't include this information (since there was no  policy
272              to  do  so  when they were written).  Patches to remedy this are
273              welcome, but, from the perspective of  programmers  writing  new
274              code, this information probably matters only in the case of ker‐
275              nel interfaces that have been added in Linux 2.4 or later (i.e.,
276              changes  since  Linux 2.2), and library functions that have been
277              added to glibc since glibc 2.1 (i.e., changes since glibc 2.0).
278
279              The syscalls(2) manual page also provides information about ker‐
280              nel versions in which various system calls first appeared.
281
282       Old  versions  of  standards  should  be mentioned here, rather than in
283       STANDARDS, for example, SUS, SUSv2, and XPG, or the SVr4 and 4.xBSD im‐
284       plementation standards.
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       CAVEATS
297              Warnings about typical user misuse of an API, that don't consti‐
298              tute an API bug or design defect.
299
300       BUGS   A list of limitations,  known  defects  or  inconveniences,  and
301              other questionable activities.
302
303       EXAMPLES
304              One  or  more examples demonstrating how this function, file, or
305              command is used.
306
307              For details on writing example programs,  see  Example  programs
308              below.
309
310       AUTHORS
311              A list of authors of the documentation or program.
312
313              Use  of  an AUTHORS section is strongly discouraged.  Generally,
314              it is better not to clutter every page with a list of (over time
315              potentially  numerous)  authors;  if  you write or significantly
316              amend a page, add a copyright notice as a comment in the  source
317              file.   If you are the author of a device driver and want to in‐
318              clude an address for reporting bugs, place this under  the  BUGS
319              section.
320
321       REPORTING BUGS
322              The  man-pages  project  doesn't use a REPORTING BUGS section in
323              manual pages.  Information on reporting bugs is instead supplied
324              in  the  script-generated  COLOPHON  section.   However, various
325              projects do use a REPORTING BUGS section.  It is recommended  to
326              place it near the foot of the page.
327
328       COPYRIGHT
329              The  man-pages project doesn't use a COPYRIGHT section in manual
330              pages.  Copyright information is instead maintained in the  page
331              source.   In  pages  where this section is present, it is recom‐
332              mended to place it near the foot of the  page,  just  above  SEE
333              ALSO.
334
335       SEE ALSO
336              A  comma-separated  list of related man pages, possibly followed
337              by other related pages or documents.
338
339              The list should be ordered by section number and then alphabeti‐
340              cally by name.  Do not terminate this list with a period.
341
342              Where the SEE ALSO list contains many long manual page names, to
343              improve the visual result of the output, it may be useful to em‐
344              ploy  the  .ad l (don't right justify) and .nh (don't hyphenate)
345              directives.  Hyphenation of individual page names  can  be  pre‐
346              vented by preceding words with the string "\%".
347
348              Given  the  distributed,  autonomous nature of FOSS projects and
349              their documentation, it is sometimes necessary—and in many cases
350              desirable—that  the SEE ALSO section includes references to man‐
351              ual pages provided by other projects.
352

FORMATTING AND WORDING CONVENTIONS

354       The following subsections note some details  for  preferred  formatting
355       and  wording  conventions  in various sections of the pages in the man-
356       pages project.
357
358   SYNOPSIS
359       Wrap the function prototype(s) in a .nf/.fi pair to prevent filling.
360
361       In general, where more than one function prototype is shown in the SYN‐
362       OPSIS, the prototypes should not be separated by blank lines.  However,
363       blank lines (achieved using .PP) may be added in the following cases:
364
365       •  to separate long lists of function prototypes  into  related  groups
366          (see for example list(3));
367
368       •  in other cases that may improve readability.
369
370       In  the  SYNOPSIS,  a  long function prototype may need to be continued
371       over to the next line.  The continuation line is indented according  to
372       the following rules:
373
374       (1)  If  there  is  a single such prototype that needs to be continued,
375            then align the continuation line so that when the page is rendered
376            on  a fixed-width font device (e.g., on an xterm) the continuation
377            line starts just below the start of the argument list in the  line
378            above.   (Exception:  the indentation may be adjusted if necessary
379            to prevent a very long continuation line or a further continuation
380            line where the function prototype is very long.)  As an example:
381
382                int tcsetattr(int fd, int optional_actions,
383                              const struct termios *termios_p);
384
385       (2)  But, where multiple functions in the SYNOPSIS require continuation
386            lines, and the function names have different lengths,  then  align
387            all continuation lines to start in the same column.  This provides
388            a nicer rendering in PDF output (because the SYNOPSIS uses a vari‐
389            able  width  font  where  spaces render narrower than most charac‐
390            ters).  As an example:
391
392                int getopt(int argc, char * const argv[],
393                           const char *optstring);
394                int getopt_long(int argc, char * const argv[],
395                           const char *optstring,
396                           const struct option *longopts, int *longindex);
397
398   RETURN VALUE
399       The preferred wording to describe how errno is set is "errno is set  to
400       indicate  the  error"  or similar.  This wording is consistent with the
401       wording used in both POSIX.1 and FreeBSD.
402
403   ATTRIBUTES
404       Note the following:
405
406       •  Wrap the table in this section in a .ad l/.ad pair to  disable  text
407          filling and a .nh/.hy pair to disable hyphenation.
408
409       •  Ensure  that  the table occupies the full page width through the use
410          of an lbx description for one of the columns (usually the first col‐
411          umn,  though  in  some cases the last column if it contains a lot of
412          text).
413
414       •  Make free use of T{/T} macro pairs to allow table cells to be broken
415          over  multiple  lines (also bearing in mind that pages may sometimes
416          be rendered to a width of less than 80 columns).
417
418       For examples of all of the above, see the source code of various pages.
419

STYLE GUIDE

421       The following subsections describe the preferred  style  for  the  man-
422       pages  project.   For  details not covered below, the Chicago Manual of
423       Style is usually a good source; try also grepping for preexisting usage
424       in the project source tree.
425
426   Use of gender-neutral language
427       As  far  as  possible,  use  gender-neutral language in the text of man
428       pages.  Use of "they" ("them", "themself", "their") as a gender-neutral
429       singular pronoun is acceptable.
430
431   Formatting conventions for manual pages describing commands
432       For  manual  pages that describe a command (typically in Sections 1 and
433       8), the arguments are always specified using italics, even in the  SYN‐
434       OPSIS section.
435
436       The name of the command, and its options, should always be formatted in
437       bold.
438
439   Formatting conventions for manual pages describing functions
440       For manual pages that describe functions (typically in Sections  2  and
441       3),  the arguments are always specified using italics, even in the SYN‐
442       OPSIS section, where the rest of the function is specified in bold:
443
444           int myfunction(int argc, char **argv);
445
446       Variable names should, like argument names, be specified in italics.
447
448       Any reference to the subject of the current manual page should be writ‐
449       ten  with  the  name in bold followed by a pair of parentheses in Roman
450       (normal) font.  For example, in the fcntl(2) man  page,  references  to
451       the  subject  of  the page would be written as: fcntl().  The preferred
452       way to write this in the source file is:
453
454           .BR fcntl ()
455
456       (Using this format, rather than the use of "\fB...\fP()" makes it  eas‐
457       ier to write tools that parse man page source files.)
458
459   Use semantic newlines
460       In  the source of a manual page, new sentences should be started on new
461       lines, long sentences should be split into lines at clause breaks (com‐
462       mas,  semicolons,  colons, and so on), and long clauses should be split
463       at phrase boundaries.  This convention, sometimes  known  as  "semantic
464       newlines",  makes  it  easier to see the effect of patches, which often
465       operate at the level of individual sentences, clauses, or phrases.
466
467   Lists
468       There are different kinds of lists:
469
470       Tagged paragraphs
471              These are used for a list of tags and their descriptions.   When
472              the  tags  are  constants (either macros or numbers) they are in
473              bold.  Use the .TP macro.
474
475              An example is this "Tagged paragraphs" subsection is itself.
476
477       Ordered lists
478              Elements are preceded by  a  number  in  parentheses  (1),  (2).
479              These represent a set of steps that have an order.
480
481              When there are substeps, they will be numbered like (4.2).
482
483       Positional lists
484              Elements  are  preceded  by  a number (index) in square brackets
485              [4], [5].  These represent fields in a  set.   The  first  index
486              will be:
487
488              0      When  it  represents  fields of a C data structure, to be
489                     consistent with arrays.
490              1      When it represents fields of a  file,  to  be  consistent
491                     with tools like cut(1).
492
493       Alternatives list
494              Elements  are  preceded  by  a  letter  in parentheses (a), (b).
495              These represent a set of (normally) exclusive alternatives.
496
497       Bullet lists
498              Elements are preceded by bullet symbols (\[bu]).  Anything  that
499              doesn't fit elsewhere is usually covered by this type of list.
500
501       Numbered notes
502              Not  really  a  list, but the syntax is identical to "positional
503              lists".
504
505       There should always be exactly 2 spaces between the list symbol and the
506       elements.  This doesn't apply to "tagged paragraphs", which use the de‐
507       fault indentation rules.
508
509   Formatting conventions (general)
510       Paragraphs should be separated by suitable markers (usually either  .PP
511       or .IP).  Do not separate paragraphs using blank lines, as this results
512       in poor rendering in some output formats (such as PostScript and PDF).
513
514       Filenames (whether pathnames, or references to header files) are always
515       in italics (e.g., <stdio.h>), except in the SYNOPSIS section, where in‐
516       cluded files are in bold (e.g., #include <stdio.h>).  When referring to
517       a  standard  header file include, specify the header file surrounded by
518       angle brackets, in the usual C way (e.g., <stdio.h>).
519
520       Special macros, which are usually in uppercase, are in bold (e.g., MAX‐
521       INT).  Exception: don't boldface NULL.
522
523       When  enumerating  a  list  of error codes, the codes are in bold (this
524       list usually uses the .TP macro).
525
526       Complete commands should, if long, be written as an  indented  line  on
527       their own, with a blank line before and after the command, for example
528
529           man 7 man-pages
530
531       If the command is short, then it can be included inline in the text, in
532       italic format, for example, man 7 man-pages.  In this case, it  may  be
533       worth  using  nonbreaking spaces (\[ti]) at suitable places in the com‐
534       mand.  Command options should be written in italics (e.g., -l).
535
536       Expressions, if not written on a  separate  indented  line,  should  be
537       specified  in italics.  Again, the use of nonbreaking spaces may be ap‐
538       propriate if the expression is inlined with normal text.
539
540       When showing example shell sessions, user input should be formatted  in
541       bold, for example
542
543           $ date
544           Thu Jul  7 13:01:27 CEST 2016
545
546       Any  reference  to  another man page should be written with the name in
547       bold, always followed by the section number, formatted in  Roman  (nor‐
548       mal)  font,  without  any separating spaces (e.g., intro(2)).  The pre‐
549       ferred way to write this in the source file is:
550
551           .BR intro (2)
552
553       (Including the section number  in  cross  references  lets  tools  like
554       man2html(1) create properly hyperlinked pages.)
555
556       Control  characters should be written in bold face, with no quotes; for
557       example, ^X.
558
559   Spelling
560       Starting with release 2.59, man-pages follows American spelling conven‐
561       tions  (previously,  there  was  a  random  mix of British and American
562       spellings); please write all new pages and patches according  to  these
563       conventions.
564
565       Aside  from  the well-known spelling differences, there are a few other
566       subtleties to watch for:
567
568       •  American English tends to use the forms "backward",  "upward",  "to‐
569          ward",  and  so  on  rather than the British forms "backwards", "up‐
570          wards", "towards", and so on.
571
572       •  Opinions are divided on "acknowledgement" vs "acknowledgment".   The
573          latter  is predominant, but not universal usage in American English.
574          POSIX and the BSD license use the former  spelling.   In  the  Linux
575          man-pages project, we use "acknowledgement".
576
577   BSD version numbers
578       The  classical  scheme for writing BSD version numbers is x.yBSD, where
579       x.y is the version number (e.g., 4.2BSD).  Avoid forms such as BSD 4.3.
580
581   Capitalization
582       In subsection ("SS") headings, capitalize the first word in  the  head‐
583       ing,  but  otherwise  use  lowercase, except where English usage (e.g.,
584       proper nouns) or programming language  requirements  (e.g.,  identifier
585       names) dictate otherwise.  For example:
586
587           .SS Unicode under Linux
588
589   Indentation of structure definitions, shell session logs, and so on
590       When  structure definitions, shell session logs, and so on are included
591       in running text, indent them by 4 spaces (i.e.,  a  block  enclosed  by
592       .in +4n  and  .in),  format them using the .EX and .EE macros, and sur‐
593       round them with suitable paragraph markers (either .PP  or  .IP).   For
594       example:
595
596           .PP
597           .in +4n
598           .EX
599           int
600           main(int argc, char *argv[])
601           {
602               return 0;
603           }
604           .EE
605           .in
606           .PP
607
608   Preferred terms
609       The  following  table  lists  some preferred terms to use in man pages,
610       mainly to ensure consistency across pages.
611
612       Term                 Avoid using              Notes
613       ────────────────────────────────────────────────────────────────
614       bit mask             bitmask
615       built-in             builtin
616       Epoch                epoch                    For the UNIX
617                                                     Epoch (00:00:00,
618                                                     1 Jan 1970 UTC)
619       filename             file name
620       filesystem           file system
621       hostname             host name
622       inode                i-node
623       lowercase            lower case, lower-case
624       nonzero              non-zero
625       pathname             path name
626       pseudoterminal       pseudo-terminal
627       privileged port      reserved port, system
628                            port
629       real-time            realtime, real time
630       run time             runtime
631       saved set-group-ID   saved group ID, saved
632                            set-GID
633       saved set-user-ID    saved user ID, saved
634                            set-UID
635       set-group-ID         set-GID, setgid
636       set-user-ID          set-UID, setuid
637       superuser            super user, super-user
638       superblock           super block, super-
639                            block
640       symbolic link        symlink
641       timestamp            time stamp
642       timezone             time zone
643       uppercase            upper case, upper-case
644       usable               useable
645       user space           userspace
646       username             user name
647       x86-64               x86_64                   Except if refer‐
648                                                     ring to result
649                                                     of "uname -m" or
650                                                     similar
651       zeros                zeroes
652
653       See also the discussion Hyphenation of attributive compounds below.
654
655   Terms to avoid
656       The following table lists some terms to avoid using in man pages, along
657       with some suggested alternatives, mainly to ensure consistency across
658       pages.
659
660       Avoid             Use instead         Notes
661       ──────────────────────────────────────────────────────────
662
663       32bit             32-bit              same for 8-bit,
664                                             16-bit, etc.
665       current process   calling process     A common mistake
666                                             made by kernel pro‐
667                                             grammers when writ‐
668                                             ing man pages
669       manpage           man page, manual
670                         page
671       minus infinity    negative infinity
672       non-root          unprivileged user
673
674       non-superuser     unprivileged user
675       nonprivileged     unprivileged
676       OS                operating system
677       plus infinity     positive infinity
678       pty               pseudoterminal
679       tty               terminal
680       Unices            UNIX systems
681       Unixes            UNIX systems
682
683   Trademarks
684       Use the correct spelling and case for trademarks.  The following  is  a
685       list  of  the correct spellings of various relevant trademarks that are
686       sometimes misspelled:
687
688              DG/UX
689              HP-UX
690              UNIX
691              UnixWare
692
693   NULL, NUL, null pointer, and null byte
694       A null pointer is a pointer that points to nothing, and is normally in‐
695       dicated by the constant NULL.  On the other hand, NUL is the null byte,
696       a byte with the value 0, represented in C via  the  character  constant
697       '\0'.
698
699       The  preferred term for the pointer is "null pointer" or simply "NULL";
700       avoid writing "NULL pointer".
701
702       The preferred term for the byte is "null byte".  Avoid  writing  "NUL",
703       since  it  is  too  easily  confused with "NULL".  Avoid also the terms
704       "zero byte" and "null character".  The byte that terminates a C  string
705       should  be described as "the terminating null byte"; strings may be de‐
706       scribed as "null-terminated", but avoid the use of "NUL-terminated".
707
708   Hyperlinks
709       For hyperlinks, use the .UR/.UE macro pair  (see  groff_man(7)).   This
710       produces proper hyperlinks that can be used in a web browser, when ren‐
711       dering a page with, say:
712
713           BROWSER=firefox man -H pagename
714
715   Use of e.g., i.e., etc., a.k.a., and similar
716       In general, the use of abbreviations such as  "e.g.",  "i.e.",  "etc.",
717       "cf.",  and "a.k.a." should be avoided, in favor of suitable full word‐
718       ings ("for example", "that is", "and so on", "compare to", "also  known
719       as").
720
721       The  only  place where such abbreviations may be acceptable is in short
722       parenthetical asides (e.g., like this one).
723
724       Always include periods in such abbreviations, as shown here.  In  addi‐
725       tion, "e.g." and "i.e." should always be followed by a comma.
726
727   Em-dashes
728       The  way  to  write  an em-dash—the glyph that appears at either end of
729       this subphrase—in *roff is with the macro "\[em]".  (On an ASCII termi‐
730       nal,  an  em-dash  typically renders as two hyphens, but in other typo‐
731       graphical contexts it renders as a long  dash.)   Em-dashes  should  be
732       written without surrounding spaces.
733
734   Hyphenation of attributive compounds
735       Compound  terms  should be hyphenated when used attributively (i.e., to
736       qualify a following noun). Some examples:
737
738              32-bit value
739              command-line argument
740              floating-point number
741
742              run-time check
743              user-space function
744              wide-character string
745
746   Hyphenation with multi, non, pre, re, sub, and so on
747       The general tendency in modern English is not to hyphenate  after  pre‐
748       fixes  such  as  "multi", "non", "pre", "re", "sub", and so on.  Manual
749       pages should generally follow this rule when these prefixes are used in
750       natural English constructions with simple suffixes.  The following list
751       gives some examples of the preferred forms:
752
753              interprocess
754              multithreaded
755              multiprocess
756              nonblocking
757              nondefault
758              nonempty
759              noninteractive
760              nonnegative
761              nonportable
762              nonzero
763              preallocated
764              precreate
765              prerecorded
766              reestablished
767              reinitialize
768              rearm
769              reread
770              subcomponent
771              subdirectory
772              subsystem
773
774       Hyphens should be retained when the prefixes are  used  in  nonstandard
775       English  words,  with  trademarks,  proper nouns, acronyms, or compound
776       terms.  Some examples:
777
778              non-ASCII
779              non-English
780              non-NULL
781              non-real-time
782
783       Finally, note that "re-create" and "recreate" are two different  verbs,
784       and the former is probably what you want.
785
786   Generating optimal glyphs
787       Where a real minus character is required (e.g., for numbers such as -1,
788       for man page cross references such as utf-8(7), or when writing options
789       that  have a leading dash, such as in ls -l), use the following form in
790       the man page source:
791
792           \-
793
794       This guideline applies also to code examples.
795
796       The use of real minus signs serves the following purposes:
797
798       •  To provide better renderings on various  targets  other  than  ASCII
799          terminals, notably in PDF and on Unicode/UTF-8-capable terminals.
800
801       •  To generate glyphs that when copied from rendered pages will produce
802          real minus signs when pasted into a terminal.
803
804       To produce unslanted single quotes that render well  in  ASCII,  UTF-8,
805       and PDF, use "\[aq]" ("apostrophe quote"); for example
806
807           \[aq]C\[aq]
808
809       where  C is the quoted character.  This guideline applies also to char‐
810       acter constants used in code examples.
811
812       Where a proper caret (^) that renders well in both a terminal  and  PDF
813       is  required,  use  "\[ha]".  This is especially necessary in code sam‐
814       ples, to get a nicely rendered caret when rendering to PDF.
815
816       Using a naked "~" character results in a poor rendering  in  PDF.   In‐
817       stead  use  "\[ti]".   This is especially necessary in code samples, to
818       get a nicely rendered tilde when rendering to PDF.
819
820   Example programs and shell sessions
821       Manual pages may include example programs demonstrating how  to  use  a
822       system call or library function.  However, note the following:
823
824       •  Example programs should be written in C.
825
826       •  An  example  program is necessary and useful only if it demonstrates
827          something beyond what can easily be provided in a  textual  descrip‐
828          tion  of  the interface.  An example program that does nothing other
829          than call an interface usually serves little purpose.
830
831       •  Example programs should ideally be short (e.g., a good  example  can
832          often  be  provided  in less than 100 lines of code), though in some
833          cases longer programs may be necessary to  properly  illustrate  the
834          use of an API.
835
836       •  Expressive code is appreciated.
837
838       •  Comments should included where helpful.  Complete sentences in free-
839          standing comments should be terminated by a period.  Periods  should
840          generally  be  omitted  in  "tag"  comments (i.e., comments that are
841          placed on the same line of code); such comments are in any case typ‐
842          ically brief phrases rather than complete sentences.
843
844       •  Example programs should do error checking after system calls and li‐
845          brary function calls.
846
847       •  Example programs should be complete, and  compile  without  warnings
848          when compiled with cc -Wall.
849
850       •  Where possible and appropriate, example programs should allow exper‐
851          imentation, by varying their behavior based on inputs (ideally  from
852          command-line arguments, or alternatively, via input read by the pro‐
853          gram).
854
855       •  Example programs should be  laid  out  according  to  Kernighan  and
856          Ritchie  style, with 4-space indents.  (Avoid the use of TAB charac‐
857          ters in source code!)  The following command can be used  to  format
858          your source code to something close to the preferred style:
859
860              indent -npro -kr -i4 -ts4 -sob -l72 -ss -nut -psl prog.c
861
862       •  For  consistency, all example programs should terminate using either
863          of:
864
865              exit(EXIT_SUCCESS);
866              exit(EXIT_FAILURE);
867
868          Avoid using the following forms to terminate a program:
869
870              exit(0);
871              exit(1);
872              return n;
873
874       •  If there is extensive explanatory text  before  the  program  source
875          code,  mark  off  the  source code with a subsection heading Program
876          source, as in:
877
878              .SS Program source
879
880          Always do this if the explanatory text includes a shell session log.
881
882       If you include a shell session log demonstrating the use of  a  program
883       or other system feature:
884
885       •  Place the session log above the source code listing.
886
887       •  Indent the session log by four spaces.
888
889       •  Boldface the user input text, to distinguish it from output produced
890          by the system.
891
892       For some examples of  what  example  programs  should  look  like,  see
893       wait(2) and pipe(2).
894

EXAMPLES

896       For canonical examples of how man pages in the man-pages package should
897       look, see pipe(2) and fcntl(2).
898

SEE ALSO

900       man(1), man2html(1),  attributes(7),  groff(7),  groff_man(7),  man(7),
901       mdoc(7)
902
903
904
905Linux man-pages 6.04              2023-03-30                      man-pages(7)
Impressum