]>
Commit | Line | Data |
---|---|---|
ba83bc0d MK |
1 | .\" (C) Copyright 1992-1999 Rickard E. Faith and David A. Wheeler |
2 | .\" (faith@cs.unc.edu and dwheeler@ida.org) | |
3 | .\" and (C) Copyright 2007 Michael Kerrisk <mtk-manpages@gmx.net> | |
4 | .\" | |
5 | .\" Permission is granted to make and distribute verbatim copies of this | |
6 | .\" manual provided the copyright notice and this permission notice are | |
7 | .\" preserved on all copies. | |
8 | .\" | |
9 | .\" Permission is granted to copy and distribute modified versions of this | |
10 | .\" manual under the conditions for verbatim copying, provided that the | |
11 | .\" entire resulting derived work is distributed under the terms of a | |
12 | .\" permission notice identical to this one. | |
13 | .\" | |
14 | .\" Since the Linux kernel and libraries are constantly changing, this | |
15 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
16 | .\" responsibility for errors or omissions, or for damages resulting from | |
17 | .\" the use of the information contained herein. The author(s) may not | |
18 | .\" have taken the same level of care in the production of this manual, | |
19 | .\" which is licensed free of charge, as they might when working | |
20 | .\" professionally. | |
21 | .\" | |
22 | .\" Formatted or processed versions of this manual, if unaccompanied by | |
23 | .\" the source, must acknowledge the copyright and authors of this work. | |
24 | .\" | |
25 | .\" FIXME Add some SEE ALSO references to this page from: | |
26 | .\" man.1, man.7, mdoc.7, and perhaps intro.* | |
27 | .\" Also write up in HOWTOHELP | |
28 | .\" | |
29 | .TH MAN-PAGES 7 2007-05-30 "Linux" "Linux Programmer's Manual" | |
30 | .SH NAME | |
31 | man-pages \- conventions for writing Linux man pages | |
32 | .SH SYNOPSIS | |
33 | .B man | |
34 | .RI [ section ] | |
35 | .I title | |
36 | .SH DESCRIPTION | |
37 | This page describes the conventions that should be employed | |
38 | when writing man pages for the Linux \fIman-pages\fP project, | |
39 | which comprises Sections 2, 3, 4, 5, and 7 of the Linux manual pages. | |
40 | The conventions described on this page may also be useful | |
41 | for authors writing man pages for other projects. | |
42 | .SS Sections of the Manual Pages | |
43 | .PP | |
44 | The manual Sections are traditionally defined as follows: | |
45 | .RS | |
46 | .TP 10 | |
47 | .B 1 Commands (Programs) | |
48 | Those commands that can be executed by the user from within | |
49 | a shell. | |
50 | .TP | |
51 | .B 2 System calls | |
52 | Those functions which must be performed by the kernel. | |
53 | .TP | |
54 | .B 3 Library calls | |
55 | Most of the | |
56 | .I libc | |
57 | functions. | |
58 | .TP | |
59 | .B 4 Special files (devices) | |
60 | Files found in | |
61 | .IR /dev . | |
62 | .TP | |
63 | .B 5 File formats and conventions | |
64 | The format for | |
65 | .I /etc/passwd | |
66 | and other human-readable files. | |
67 | .TP | |
68 | .B 6 Games | |
69 | .TP | |
70 | .B 7 Conventions and miscellaneous | |
71 | Overviews of various topics, conventions and protocols, | |
72 | character set standards, and miscellaneous other things. | |
73 | .TP | |
74 | .B 8 System management commands | |
75 | Commands like | |
76 | .BR mount (8), | |
77 | many of which only root can execute. | |
78 | .\" .TP | |
79 | .\" .B 9 Kernel routines | |
80 | .\" This is an obsolete manual section. | |
81 | .\" Once it was thought a good idea to document the Linux kernel here, | |
82 | .\" but in fact very little has been documented, and the documentation | |
83 | .\" that exists is outdated already. | |
84 | .\" There are better sources of | |
85 | .\" information for kernel developers. | |
86 | .RE | |
87 | .SS Macro package | |
88 | New manual pages should be marked up using the | |
89 | .B groff tmac.an | |
90 | package described in | |
91 | .BR man (7). | |
92 | This choice is mainly for consistency: the vast majority of | |
93 | existing Linux manual pages are marked up using these macros. | |
94 | .SS Conventions for source file layout | |
95 | Please limit source code line length to no more than 75 characters | |
96 | wherever possible. | |
97 | This helps avoid line-wrapping in some mail clients when patches are | |
98 | submitted inline. | |
99 | ||
100 | New sentences should be started on new lines. | |
101 | This makes it easier to see the effect of patches, | |
102 | which often operate at the level of individual sentences. | |
103 | .SS Title line | |
104 | The first command in a man page should be a \fBTH\fP command: | |
105 | .RS | |
106 | .sp | |
107 | .B \&.TH | |
108 | .IR "title section date source manual" | |
109 | .sp | |
110 | .RE | |
111 | where: | |
112 | .RS | |
113 | .TP 10 | |
114 | .I title | |
115 | The title of the man page, written in all caps (e.g., | |
116 | .IR MAN-PAGES ). | |
117 | .TP | |
118 | .I section | |
119 | The section number in which the man page should be placed (e.g., | |
120 | .IR 7 ). | |
121 | .TP | |
122 | .I date | |
123 | The date of the last revision\(emremember to change this every time a | |
124 | change is made to the man page, since this is the most general way of doing | |
125 | version control. | |
126 | Dates should be written in the form YYYY-MM-DD. | |
127 | .TP | |
128 | .I source | |
129 | The source of the command, function, or system call. | |
130 | .sp | |
131 | For those few \fIman-pages\fP pages in Sections 1 and 8, | |
132 | probably you just want to write | |
133 | .IR GNU . | |
134 | .sp | |
135 | For system calls, just write | |
136 | .IR "Linux" . | |
137 | (An earlier practice was to write the version number | |
138 | of the kernel from which the manual page was being written/checked. | |
139 | However, this was never done consistently, and so was | |
140 | probably worse than including no version number. | |
141 | Henceforth, avoid including a version number.) | |
142 | .sp | |
143 | For library calls that are part of glibc or one of the | |
144 | other common GNU libraries, just use | |
145 | .IR "GNU C Library" ", " GNU , | |
146 | or an empty string. | |
147 | .sp | |
148 | For Section 4 pages, use | |
149 | .IR "Linux" . | |
150 | .sp | |
151 | In cases of doubt, just write | |
152 | .IR Linux ", or " GNU . | |
153 | .TP | |
154 | .I manual | |
155 | The title of the manual (e.g., for Section 2 and 3 pages in | |
156 | the \fIman-pages\fP package, use | |
157 | .IR "Linux Programmer's Manual" ). | |
158 | .RE | |
159 | .SS Sections within a manual page | |
160 | The list below shows conventional or suggested sections. | |
161 | Most manual pages should include at least the | |
162 | .B highlighted | |
163 | sections. | |
164 | Srrange a new manual page so that sections | |
165 | are placed in the order shown in the list. | |
166 | .in +0.5i | |
167 | .nf | |
168 | ||
169 | \fBNAME\fP | |
170 | \fBSYNOPSIS\fP | |
171 | \fBDESCRIPTION\fP | |
172 | OPTIONS [Normally only in Sections 1, 8] | |
173 | EXIT STATUS [Normally only in Sections 1, 8] | |
174 | RETURN VALUE [Normally only in Sections 2, 3] | |
175 | .\" May 07: Few current man pages have an ERROR HANDLING section,,, | |
176 | .\" ERROR HANDLING, | |
177 | ERRORS [Typically only in Sections 2, 3] | |
178 | .\" May 07: Almost no current man pages have a USAGE section,,, | |
179 | .\" USAGE, | |
180 | ..\" DIAGNOSTICS, | |
181 | .\" May 07: Almost no current man pages have a SECURITY section,,, | |
182 | .\" SECURITY, | |
183 | ENVIRONMENT | |
184 | FILES | |
185 | VERSIONS [Normally only in Sections 2, 3] | |
186 | CONFORMING TO | |
187 | NOTES | |
188 | BUGS | |
189 | EXAMPLE | |
190 | .\" AUTHOR sections are discouraged | |
191 | AUTHOR [Discouraged] | |
192 | \fBSEE ALSO\fP | |
193 | ||
194 | .fi | |
195 | .in | |
196 | .IR "Where a traditional heading would apply" ", " "please use it" ; | |
197 | this kind of consistency can make the information easier to understand. | |
198 | If you must, you can create your own | |
199 | headings if they make things easier to understand (this can | |
200 | be especially useful for pages in Sections 4 and 5). | |
201 | However, before doing this, consider whether you could use the | |
202 | traditional headings, with some subsections (\fI.SS\fP) within | |
203 | those sections. | |
204 | ||
205 | The following list elaborates on the contents of each of | |
206 | the above sections. | |
207 | .TP 14 | |
208 | .B NAME | |
209 | The name of this manual page. | |
210 | See | |
211 | .BR man (7) | |
212 | for important details of the line(s) that should follow the | |
213 | \fB.SH NAME\fI command. | |
214 | .TP | |
215 | .B SYNOPSIS | |
216 | briefly describes the command or function's interface. | |
217 | For commands, this shows the syntax of the command and its arguments | |
218 | (including options); | |
219 | boldface is used for as-is text and italics are used to indicate replaceable | |
220 | arguments. | |
221 | Brackets ([]) surround optional arguments, vertical bars (|) | |
222 | separate choices, and ellipses (\&...) can be repeated. | |
223 | For functions, it shows any required data declarations or | |
224 | .B #include | |
225 | directives, followed by the function declaration. | |
226 | .TP | |
227 | .B DESCRIPTION | |
228 | gives an explanation of what the program, function, or format does. | |
229 | Discuss how it interacts with files and standard input, and what it | |
230 | produces on standard output or standard error. | |
231 | Omit internals and implementation details unless they're critical for | |
232 | understanding the interface. | |
233 | Describe the usual case; | |
234 | for information on command-line options of a program use the | |
235 | .B OPTIONS | |
236 | section. | |
237 | .\" If there is some kind of input grammar or complex set of subcommands, | |
238 | .\" consider describing them in a separate | |
239 | .\" .B USAGE | |
240 | .\" section (and just place an overview in the | |
241 | .\" .B DESCRIPTION | |
242 | .\" section). | |
243 | .TP | |
244 | .B OPTIONS | |
245 | describes the command-line options accepted by a | |
246 | program and how they change its behavior. | |
247 | This section should only appear for Section 1 and 8 manual pages. | |
248 | .\" .TP | |
249 | .\" .B USAGE | |
250 | .\" describes the grammar of any sublanguage this implements. | |
251 | .\" FIXME document VERSIONS | |
252 | .\" FIXME document other common Section Heading types | |
253 | .\" FIXME make a clear statement about the order of Sections | |
254 | .TP | |
255 | .B EXIT STATUS | |
256 | lists the possible exit status values of a program and | |
257 | the conditions that cause these values to be returned. | |
258 | This section should only appear for Section 1 and 8 manual pages. | |
259 | .TP | |
260 | .B RETURN VALUE | |
261 | For Section 2 and 3 pages, this section gives a | |
262 | list of the values the library routine will return to the caller | |
263 | and the conditions that cause these values to be returned. | |
264 | .TP | |
265 | .B ERRORS | |
266 | For Section 2 and 3 manual pages, this is a list of the | |
267 | values that may be placed in | |
268 | .I errno | |
269 | in the event of an error, along with information about the cause | |
270 | of the errors. | |
271 | .TP | |
272 | .B ENVIRONMENT | |
273 | lists all environment variables that affect the program or function | |
274 | and how they affect it. | |
275 | .TP | |
276 | .B FILES | |
277 | lists the files the program or function uses, such as | |
278 | configuration files, startup files, | |
279 | and files the program directly operates on. | |
280 | Give the full pathname of these files, and use the installation | |
281 | process to modify the directory part to match user preferences. | |
282 | For many programs, the default installation location is in | |
283 | .IR /usr/local , | |
284 | so your base manual page should use | |
285 | .I /usr/local | |
286 | as the base. | |
287 | .\" May 07: Almost no current man pages have a DIAGNOSTICS section; | |
288 | .\" "RETURN VALUE" or "EXIT STATUS" is preferred. | |
289 | .\" .TP | |
290 | .\" .B DIAGNOSTICS | |
291 | .\" gives an overview of the most common error messages and how to | |
292 | .\" cope with them. | |
293 | .\" You don't need to explain system error messages | |
294 | .\" or fatal signals that can appear during execution of any program | |
295 | .\" unless they're special in some way to the program. | |
296 | .\" | |
297 | .\" May 07: Almost no current man pages have a SECURITY section. | |
298 | .\".TP | |
299 | .\".B SECURITY | |
300 | .\"discusses security issues and implications. | |
301 | .\"Warn about configurations or environments that should be avoided, | |
302 | .\"commands that may have security implications, and so on, especially | |
303 | .\"if they aren't obvious. | |
304 | .\"Discussing security in a separate section isn't necessary; | |
305 | .\"if it's easier to understand, place security information in the | |
306 | .\"other sections (such as the | |
307 | .\" .B DESCRIPTION | |
308 | .\" or | |
309 | .\" .B USAGE | |
310 | .\" section). | |
311 | .\" However, please include security information somewhere! | |
312 | .TP | |
313 | .B VERSIONS | |
314 | A brief summary of the Linux kernel or glibc versions where a | |
315 | system call or library function appeared, | |
316 | or changed significantly in its operation. | |
317 | .TP | |
318 | .B CONFORMING TO | |
319 | describes any standards or conventions that relate to the function or command described by the manula page. | |
320 | For a page in Section 2 or 3, this section should note the POSIX.1 | |
321 | version(s) that the call conforms to. | |
322 | If the call is not governed by any standards but exists on other | |
323 | systems, note them. | |
324 | If the call is Linux specific, note this. | |
325 | When talking about standards and systems | |
326 | here is probably no need to talk about anything more than | |
327 | C89, C99, POSIX.1-2001 (or later), xBSD, and SVr4, and perhaps Solaris | |
328 | (see | |
329 | .BR standards (7)). | |
330 | .TP | |
331 | .B NOTES | |
332 | provides miscellaneous notes. | |
333 | For Section 2 and 3 man pages you may find it usful to include | |
334 | subsections (\fBSS\fP) named \fILinux Notes\fP and \fIGlibc Notes\fP. | |
335 | .TP | |
336 | .B BUGS | |
337 | lists limitations, known defects or inconveniences, | |
338 | and other questionable activities. | |
339 | .TP | |
340 | .B EXAMPLE | |
341 | provides one or more examples describing how this function, file or | |
342 | command is used. | |
343 | For details on writing example programs, see \fIExample Programs\fP below. | |
344 | .TP | |
345 | .B AUTHOR | |
346 | lists authors of the documentation or program so you can mail in bug | |
347 | reports. | |
348 | .BR "Use of an AUTHOR section is discouraged for pages in | |
349 | the \fIman-pages\fP package". | |
350 | (One exception is Section 4 pages that list the authors of | |
351 | device drivers, to whom software bugs should be sent.) | |
352 | Generally, it is better not to clutter every page with a list | |
353 | of (over time potentially numerous) authors; | |
354 | if you write or significantly amend a page, | |
355 | add a copyright notice as a comment in the source file. | |
356 | .TP | |
357 | .B SEE ALSO | |
358 | lists related man pages, ordered by section number and | |
359 | alphabetically by name, possibly followed by | |
360 | other related pages or documents. | |
361 | .SS Font conventions | |
362 | .PP | |
363 | For functions, the arguments are always specified using italics, | |
364 | .IR "even in the SYNOPSIS section" , | |
365 | where the rest of the function is specified in bold: | |
366 | .PP | |
367 | .RS | |
368 | .BI " int myfunction(int " argc ", char **" argv ); | |
369 | .RE | |
370 | .PP | |
371 | Filenames are always in italics (e.g., | |
372 | .IR "/usr/include/stdio.h" ), | |
373 | except in the SYNOPSIS section, where included files are in bold (e.g., | |
374 | .BR "#include <stdio.h>" ). | |
375 | .PP | |
376 | Special macros, which are usually in upper case, are in bold (e.g., | |
377 | .BR MAXINT ). | |
378 | Exception: don't boldface NULL. | |
379 | .PP | |
380 | When enumerating a list of error codes, the codes are in bold (this list | |
381 | usually uses the | |
382 | .B \&.TP | |
383 | macro). | |
384 | .PP | |
385 | Any reference to the subject of the current manual page | |
386 | should be written with the name in bold, | |
387 | followed by a pair of parentheses in Roman (normal) font, | |
388 | e.g., | |
389 | .BR man (). | |
390 | The preferred way to write this in the source file is: | |
391 | .nf | |
392 | ||
393 | .BR man () | |
394 | ||
395 | .fi | |
396 | (Using this format, rather than the use of "\\fB...\\fP()" | |
397 | makes it easier to write tools that parse man page source files.) | |
398 | .PP | |
399 | Any reference to another man page | |
400 | should be written with the name in bold, | |
401 | \fIalways\fP followed by the section number, | |
402 | formatted in Roman (normal) font, without any | |
403 | separating spaces (e.g., | |
404 | .BR intro (2)). | |
405 | The preferred way to write this in the source file is: | |
406 | .nf | |
407 | ||
408 | .BR intro (2) | |
409 | ||
410 | .fi | |
411 | (Including the section number in cross references lets tools like | |
412 | .BR man2html (1) | |
413 | create properly hyperlinked pages.) | |
414 | .SS Example Programs | |
415 | Manual pages can include example programs demonstrating how to | |
416 | use a system call or library function. | |
417 | However, note the following: | |
418 | .TP 3 | |
419 | * | |
420 | Example programs should be written in C. | |
421 | .TP | |
422 | * | |
423 | An example program is only necessary and useful if it demonstrates | |
424 | something beyond what can easily be provided in a textual | |
425 | description of the interface. | |
426 | An example program that does nothing | |
427 | other than call an interface usually serves little purpose. | |
428 | .TP | |
429 | * | |
430 | Example programs should be fairly short (preferably < 100 lines; | |
431 | ideally < 50 lines). | |
432 | .TP | |
433 | * | |
434 | Example programs should do error checking after system calls and | |
435 | library function calls. | |
436 | .TP | |
437 | * | |
438 | Example programs should be complete, and compile without | |
439 | warnings when compiled with \fIcc -Wall\fP. | |
440 | .TP | |
441 | * | |
442 | Where possible and appropriate, example programs should allow | |
443 | experimentation, by varying their behaviour based on inputs | |
444 | (ideally from command-line arguments, or alternatively, via | |
445 | input read by the program). | |
446 | .TP | |
447 | * | |
448 | Example programs should be laid out according to Kernighan and | |
449 | Ritchie style, with a few concessions: | |
450 | .RS | |
451 | .TP 3 | |
452 | \(bu | |
453 | 4-space indents are preferred. | |
454 | (Avoid the use of TAB characters in source code!) | |
455 | .TP | |
456 | \(bu | |
457 | In the interests of keeping a program short, compressing | |
458 | error-handling code such as in the following is acceptable: | |
459 | .nf | |
460 | ||
461 | if (func(...) == -1) | |
462 | { perror("func"); exit(EXIT_FAILURE); } | |
463 | .fi | |
464 | .RE | |
465 | .PP | |
466 | For some examples of what example programs should look like, see | |
467 | .BR wait (2) | |
468 | and | |
469 | .BR pipe (2). | |
470 | .SH EXAMPLE | |
471 | For canonical examples of how man pages in the | |
472 | .BR man-pages | |
473 | package should look, see | |
474 | .BR pipe (2) | |
475 | and | |
476 | .BR fcntl (2). | |
477 | .SH SEE ALSO | |
478 | .BR man (1), | |
479 | .BR man2html (1), | |
480 | .BR man (7), | |
481 | .BR mdoc (7) |