Linux程序员手册 第7部分
更新日期： 2020-08-13

名称

man-pages - 约定编写Linux手册页

语法

man [section] title

说明

本页描述了为Linux手册页项目编写手册页时应采用的约定，该约定记录了Linux内核和GNU C库提供的用户空间API。因此，该项目提供了第2节中的大部分页面，在Linux手册页的第3、4和7节中显示了许多页面，并且在第1、5和8节中显示了一些页面。系统。本页上描述的约定对于编写其他项目的手册页的作者可能也很有用。

手册页的章节

传统上，手册各节的定义如下：

1 User commands (Programs)

用户可以在外壳程序内执行的命令。

2 System calls

功能，这环绕操作由内核来执行。

3 Library calls

除系统调用包装程序外的所有库函数(大多数libc函数)。

4 Special files (devices)

在/ dev中找到的文件，允许通过内核访问设备。

5 File formats and configuration files

描述各种人类可读的文件格式和配置文件。

6 Games

系统上提供了游戏和有趣的小程序。

7 Overview, conventions, and miscellaneous

各种主题，约定和协议，字符集标准，标准文件系统布局以及其他杂项的概述或描述。

8 System management commands

像mount(8)这样的命令，其中只有root才能执行。

Macro package

应该使用man(7)中描述的groff an.tmac软件包标记新的手册页。这种选择主要是为了保持一致性：使用这些宏对绝大多数现有的Linux手册页进行标记。

Conventions for source file layout

请尽可能将源代码行的长度限制为不超过约75个字符。当内联提交修补程序时，这有助于避免某些邮件客户端中的换行。

Title line

手册页中的第一个命令应该是TH命令：

.TH标题部分日期来源手册

该命令的参数如下：

title

手册页的标题，写在全部大写字母(例如，MAN-PAGES)。

section

手册页应放置的部分编号(例如7)。

date

对手册页进行的最后一次重要更改的日期。 (在手册页项目中，这些时间戳的必要更新由脚本自动处理，因此不需要作为修补程序的一部分进行手动更新。)日期应以YYYY-MM-DD的形式编写。

source

命令，函数或系统调用的源。

对于第1节和第8节中的那几本手册页，您可能只想编写GNU。

对于系统调用，只需编写Linux。 (一种较早的做法是写出要从中写入/检查手册页的内核的版本号。但是，这从来没有做到一致，因此可能比不包含版本号更糟糕。此后，请避免包含版本号)

对于库调用是的glibc或其他常见GNU库的一个组成部分，只需使用GNU C库，GNU，或一个空字符串。

对于第4节页面，使用Linux。

如有疑问，只需编写Linux或GNU。

manual

手册的标题(例如，对于手册页包中的第2和3页的页面，请使用Linux程序员手册)。

Sections within a manual page

下面的列表显示了常规或建议的部分。大多数手册页至少应包括突出显示的部分。安排一个新的手册页，以便将各个部分按列表中显示的顺序放置。

NAME
SYNOPSIS
CONFIGURATION      [Normally only in Section 4]
DESCRIPTION
OPTIONS            [Normally only in Sections 1, 8]
EXIT STATUS        [Normally only in Sections 1, 8]
RETURN VALUE       [Normally only in Sections 2, 3]
ERRORS             [Typically only in Sections 2, 3]
ENVIRONMENT
FILES
VERSIONS           [Normally only in Sections 2, 3]
ATTRIBUTES         [Normally only in Sections 2, 3]
CONFORMING TO
NOTES
BUGS
EXAMPLES
AUTHORS            [Discouraged]
REPORTING BUGS     [Not used in man-pages]
COPYRIGHT          [Not used in man-pages]
SEE ALSO

适用传统标题的地方，请使用；这种一致性可以使信息更易于理解。如果你一定要，你可以创建自己的标题，如果他们让事情更容易理解(这可能是在第4和第5页特别有用)。但是，在执行此操作之前，请考虑是否可以使用传统标题，这些标题中包含一些小节(.SS)。

以下列表详细说明了上述每个部分的内容。

NAME

本手册页的名称。

有关.SH NAME命令后的行的重要详细信息，请参见man(7)。该行中的所有单词(包括紧跟在" \-"之后的单词)均应小写，除非英语或技术术语惯例另有规定。

SYNOPSIS

命令或函数界面的简要摘要。

对于命令，这显示了命令的语法及其参数(包括选项)；粗体字表示原样，斜体字表示可替换的参数。方括号([])围绕可选参数，竖线(|)分隔选项，并且省略号(...)可重复。对于函数，它显示所有必需的数据声明或#include指令，后跟函数声明。

如果必须定义功能测试宏才能从头文件中获取功能(或变量)的声明，则摘要应指出这一点，如feature_test_macros(7)中所述。

CONFIGURATION

设备的配置详细信息。

本节通常仅出现在第4节页面中。

DESCRIPTION

程序，功能或格式的说明。

讨论它如何与文件和标准输入进行交互，以及在标准输出或标准错误时产生的结果。省略内部及实施细则，除非他们是理解的界面至关重要。描述通常的情况;有关程序的命令行选项的信息，请使用OPTIONS部分。

When describing new behavior or new flags for a system call or library function, be careful to note the kernel or C library version that introduced the change. The preferred method of noting this information for flags is as part of a .TP

list, in the following form (here, for a new system call flag):

XYZ_FLAG(since Linux 3.7)

标志说明...

包含版本信息对于必须使用较旧的内核或C库版本(例如，在嵌入式系统中很常见)的用户特别有用。

OPTIONS

对程序接受的命令行选项及其如何更改其行为的描述。

本节仅应出现在第1节和第8节手册中。

EXIT STATUS

程序的可能退出状态值以及导致返回这些值的条件的列表。

这部分应仅适用于第1节和第8手册页。

RETURN VALUE

对于第2页和第3页，本节列出了库例程将返回给调用程序的值以及导致返回这些值的条件的列表。

ERRORS

对于第2和第3手册页，这是可以被放置在错误号在出现错误的情况下，与关于误差的原因的信息沿着所述值的列表。

当几个不同的条件产生相同的错误时，首选方法是为每个条件创建单独的列表条目(具有重复的错误名称)。这样可以使单独的条件清晰明了，可以使列表更易于阅读，并可以为每个条件更轻松地标记元信息(例如，条件首次适用的内核版本号)。

错误列表应按字母顺序排列。

ENVIRONMENT

影响程序或功能的所有环境变量及其影响方式的列表。

FILES

程序或功能使用的文件列表，例如配置文件，启动文件以及程序直接在其上运行的文件。

给出这些文件的完整路径，并使用安装程序来修改目录部分，以满足用户的偏好。对于许多程序，默认安装位置在/ usr / local中，因此您的基本手册页应使用/ usr / local作为基础。

ATTRIBUTES

本页记录的功能的各种属性的摘要。有关更多详细信息，请参见attributes(7)。

VERSIONS

Linux内核或glibc的版本，其中一个系统调用库函数出现，或在其操作显著改变了简要总结。

一般情况下，每一个新的界面应在其手册页一版本部分。不幸的是，许多现有的手册页不包含此信息(因为在编写时没有政策这样做)。欢迎使用修补程序来补救此问题，但是，从程序员编写新代码的角度来看，此信息仅在Linux 2.4或更高版本中已添加内核接口(即，自2.2版以来的更改)以及库函数的情况下才有意义已添加因为版本2.1到glibc(即，因为glibc的2.0变化)。

syscalls(2)手册页还提供有关内核版本的信息，在该内核中首次出现了各种系统调用。

CONFORMING TO

与手册页描述的功能或命令相关的任何标准或约定的描述。

用于各种标准的首选术语在标准(7)中列为标题。

对于第2或3节中的页面，本节应注意该调用符合的POSIX.1版本，以及是否在C99中指定了该调用。 (不必担心其他标准，例如SUS，SUSv2和XPG或SVr4和4.xBSD实现标准，除非在这些标准中指定了调用，但该调用不在POSIX.1的当前版本中。 )

如果呼叫不受任何标准约束，但通常存在于其他系统上，请注意它们。如果呼叫是特定于Linux的，请注意这一点。

如果此部分仅由标准列表组成(通常这样做)，请以句点(aq.aq)终止列表。

NOTES

杂项笔记。

对于第2和3节的手册页，您可能会发现包括名为Linux Notes和Glibc Notes的小节(SS)很有用。

在第2节中，使用标题C库/内核差异来标记注释，这些注释描述系统调用的C库包装函数与内核提供的原始系统调用接口之间的差异(如果有)。

BUGS

限制，已知缺陷或不便以及其他可疑活动的列表。

EXAMPLES

一个或多个示例说明如何使用此功能，文件或命令。

有关编写示例程序的详细信息，请参见下面的示例程序。

AUTHORS

文档或程序的作者列表。

强烈建议不要使用AUTHORS部分。通常，最好不要在每个页面上都堆满(随着时间的推移可能会有很多)作者列表。如果你写或修改显著页面，添加了版权声明在源文件中的注释。如果你是一个设备驱动程序的作者，并希望包括地址报告错误，把这个下BUGS部分。

REPORTING BUGS

手册页项目不在手册页中使用"报告错误"部分。有关报告错误的信息，而是在脚本生成的COLOPHON部分中提供。但是，各种项目的确使用"报告错误"部分。建议将其放置在页面底部附近。

COPYRIGHT

手册页项目在手册页中未使用"版权"部分。版权信息将保留在页面源中。在存在此部分的页面中，建议将其放置在页面底部附近，也要位于上方。

SEE ALSO

用逗号分隔的相关手册页列表，可能后面还有其他相关页或文档。

该列表应按部分编号排序，然后按名称字母顺序排序。不要以句号终止此列表。

如果" SEE ALSO"列表包含许多长的手动页面名称，则为了改善输出的视觉效果，使用.ad l(不正确对正)和.nh(不断字)指令可能很有用。可以通过在单词前面加上字符串" \％"来防止对各个页面名称进行连字。

鉴于FOSS项目及其文件的分布，自治性质，它有时是必要的---而且在许多情况下希望---即又见部分包括对其他项目提供的手册页引用。

STYLE GUIDE

以下小节描述了该男子的页面项目的首选样式。对于以下未涵盖的细节，通常可以使用《芝加哥风尚手册》。也尝试在项目源代码树中grepping预先存在的用法。

Use of gender-neutral language

尽可能在手册页文本中使用不分性别的语言。可以将"他们"("他们"，"他们自己"，"他们")用作中性的单数代词。

Formatting conventions for manual pages describing commands

对于描述命令的手册页(通常在第1节和第8节中)，即使在"摘要"部分中，也始终使用斜体来指定参数。

命令名称及其选项应始终以粗体格式设置。

Formatting conventions for manual pages describing functions

对于描述函数的手册页(通常在第2节和第3节中)，即使在"概要"部分中也始终以斜体指定参数，而在"概要"部分中，其余功能以粗体指定：

int myfunction(int argc，char ** argv);

变量名应该像参数名，被斜体指定。

对当前手册页主题的任何引用均应使用粗体名称，后跟一对用罗马(正常)字体显示的括号。例如，在fcntl(2)手册页中，对该页面主题的引用将写为：fcntl()。在源文件中写入此内容的首选方法是：

.BR fcntl ()

(使用这种格式，而不是使用" \ fB ... \ fP()"，使编写解析手册页源文件的工具更加容易。)

Use semantic newlines

在手册页的源代码中，新句子应从新行开始，长句子应在子句中断处(逗号，分号，冒号等)分成几行。该约定有时也称为"语义换行符"，使查看补丁的效果更加容易，补丁通常在单个句子或句子从句的层次上起作用。

Formatting conventions (general)

段落应使用适当的标记(通常是.PP或.IP)分隔。不要使用空行分隔段落，因为这会导致某些输出格式(例如PostScript和PDF)的渲染效果很差。

文件名(无论是路径名还是对头文件的引用)始终以斜体显示(例如)，但在"摘要"部分中除外，其中包含的文件以粗体显示(例如#include)。当引用标准头文件include时，请以通常的C方式(例如)指定用尖括号括起来的头文件。

特殊宏通常以大写形式显示，以粗体显示(例如MAXINT)。例外：不要将NULL设为黑体。

枚举错误代码列表时，错误代码以粗体显示(该列表通常使用.TP宏)。

完整的命令(如果很长)应该自己写成缩进行，例如，在命令之前和之后都应留空行。

man 7 man-pages

如果该命令很短，则可以以斜体格式将其内联包含在文本中，例如man 7手册页。在这种情况下，值得在命令的适当位置使用不间断空格(``'')。命令选项应使用斜体(例如-l)编写。

如果表达式未写在单独的缩进行上，则应以斜体指定。同样，如果表达式用普通文本内联，则不间断空格的使用可能是合适的。

在显示示例Shell会话时，用户输入应使用粗体格式，例如

$ date
Thu Jul  7 13:01:27 CEST 2016

任何对另一个手册页的引用均应以粗体显示，并始终以节号开头，并以罗马(常规)字体设置格式，并且不留任何空格(例如intro(2))。在源文件中写入此内容的首选方法是：

.BR intro (2)

(在交叉引用中包括节号，使诸如man2html(1)之类的工具可以创建正确的超链接页面。)

控制字符应以黑体字写成，不带引号；例如haX。

Spelling

从2.59版开始，手册页遵循美国的拼写约定(以前，英国和美国的拼写是随机组合的)；请按照这些约定编写所有新页面和补丁。

除了众所周知的拼写差异外，还需要注意其他一些细微之处：

*

美国英语趋向于使用"向后"，"向上"，"朝上"等形式，而不是英国的"向后"，"向上"，"朝上"等形式。

BSD version numbers

编写BSD版本号的经典方案是x.yBSD，其中x.y是版本号(例如4.2BSD)。避免使用诸如BSD 4.3之类的格式。

Capitalization

在小节(" SS")标题中，将标题中的第一个单词大写，但使用小写字母，除非英语用法(例如专有名词)或编程语言要求(例如标识符名称)另有规定。例如：

.SS Unicode under Linux

Indentation of structure definitions, shell session logs, and so on

当运行的文本中包含结构定义，shell会话日志等内容时，将它们缩进4个空格(即，用.in + 4n和.in包围的块)，使用.EX和EE宏格式化它们并环绕它们带有合适的段落标记(.PP或.IP)。例如：

.PP
    .in +4n
    .EX
    int
    main(int argc, char *argv[])
    {
        return 0;
    }
    .EE
    .in
    .PP

Preferred terms

下表列出了手册页中使用的一些首选术语，主要是为了确保跨页面的一致性。

单元格不一致

另请参见下面的"属性化合物的连字"讨论。

Terms to avoid

下表列出了一些避免在手册页中使用的术语以及一些建议的替代方法，主要是为了确保跨页面的一致性。

单元格不一致

Trademarks

对商标使用正确的拼写和大小写。以下是有时会拼写错误的各种相关商标的正确拼写列表：

DG / UX
HP-UX
UNIX系统
UnixWare

NULL, NUL, null pointer, and null character

空指针是不指向任何内容的指针，通常由常量NULL表示。另一方面，NUL是空字节，即值为0的字节，通过字符常量aq \ 0aq在C中表示。

指针的首选术语是"空指针"或简称为" NULL"。避免编写"空指针"。

字节的首选术语是"空字节"。避免编写" NUL"，因为它很容易与" NULL"混淆。也请避免使用术语"零字节"和"空字符"。终止C字符串的字节应被描述为"终止空字节"。字符串可以描述为"以Null终止"，但请避免使用"以NUL终止"。

Hyperlinks

对于超链接，请使用.UR / .UE宏对(请参阅groff_man(7))。这样会生成适当的超链接，当呈现页面时，可以在Web浏览器中使用该超链接，例如：

BROWSER = firefoxman -H页面名称

Use of e.g., i.e., etc., a.k.a., and similar

通常，使用诸如"例如"，"即"，"等"，" cf。"和" aka"的缩写。应避免使用适当的完整措词(例如"，"，"等等"，"比较"，"也称为")。

此类缩写唯一可以接受的地方是短括号内的小括号(例如，与此类似)。

如此处所示，请始终在缩写中包含句点。另外，"例如"和"即"应该始终后面跟一个逗号。

Em-dashes

在* roff中写em-破折号的方法(出现在此子短语两端的字形)是使用宏" (em"。(在ASCII终端上，em-破折号通常呈现为两个连字符，但在其他印刷上下文中，它表示为长破折号。)应将破折号写成没有周围空格的形式。

Hyphenation of attributive compounds

复合术语在定语使用时(即限定以下名词)应加连字符。一些例子：

32位值
命令行参数
浮点数
运行时检查
用户空间功能
宽字符字符串

Hyphenation with multi, non, pre, re, sub, and so on

现代英语的普遍趋势是不要在诸如" multi"，" non"，" pre"，" re"，" sub"等前缀之前连字符。当这些前缀用于带有简单后缀的自然英语结构时，手册页通常应遵循此规则。以下列表提供了一些首选形式的示例：

interprocess 进程间
    multithreaded 多线程
    multiprocess 多进程
    nonblocking 不阻塞
    nondefault 非默认
    nonempty 非空
    noninteractive 非互动
    nonnegative 非负的
    nonportable 不可携带
    nonzero 非零
    preallocated 预分配
    precreate 预创建
    prerecorded 预录
    reestablished 重新建立
    reinitialize 重新初始化
    rearm 重装
    reread 重读
    subcomponent 子组件
    subdirectory 子目录
    subsystem子系统

当前缀用于非标准英语单词，商标，专有名词，首字母缩写词或复合词时，应保留连字符。一些例子：

non-ASCII 非ASCII
    non-English 非英语
    non-NULL 非空
    non-real-time非实时

最后，请注意，" re-create"和" recreate"是两个不同的动词，前者可能是您想要的。

Generating optimal glyphs

如果需要一个真正的减号(例如，对于-1这样的数字，对于诸如utf-8(7)这样的手册页交叉引用，或者当编写带有前划线的选项时，例如ls -l)，请使用手册页源中的以下形式：

-

本指南也适用于代码示例。

要生成可以很好地呈现ASCII，UTF-8和PDF格式的非倾斜单引号，请使用" (aq"("撇号"))；例如

(aqC(aq

其中C是带引号的字符。该准则也适用于代码示例中使用的字符常量。

如果需要在终端和PDF中都能很好地呈现的插入符号(ha)，请使用" (ha"。在代码示例中，这尤其必要，以便在呈现为PDF时获得呈现良好的插入符号。

使用裸露的" ti"字符会导致PDF呈现效果较差。而是使用" (ti"。这在代码示例中尤其必要，以便在呈现为PDF时获得良好的波浪线。

Example programs and shell sessions

手册页可能包括示例程序，这些程序演示了如何使用系统调用或库函数。但是，请注意以下几点：

*

示例程序应使用C编写。

*

仅当示例程序演示了界面文本描述中不容易提供的内容时，示例程序才是必要且有用的。除了调用接口外什么也不做的示例程序通常没有什么用处。

*

示例程序应相当短(最好少于100行；理想情况下少于50行)。

*

示例程序应在系统调用和库函数调用之后进行错误检查。

*

示例程序应该是完整的，并且在使用cc-Wall进行编译时无需警告就可以编译。

*

在可能且适当的情况下，示例程序应允许通过基于输入(理想情况下是从命令行自变量，或者通过程序读取的输入)改变其行为来进行实验。

*

示例程序应根据Kernighan和Ritchie样式进行布局，并带有4个空格的缩进。 (避免在源代码中使用TAB字符！)以下命令可用于将源代码设置为与首选样式相似的格式：

缩进-npro-kr-i4-ts4-sob-l72-ss-nut-psl prog.c

*

为了保持一致，所有示例程序都应使用以下任一方法终止：

     exit(EXIT_SUCCESS);      exit(EXIT_FAILURE);

避免使用以下形式终止程序：

    exit(0);     exit(1);     return n;

*

如果程序源代码之前有大量说明文字，请在标题为"程序源"的小节中标记源代码，如下所示：

    .SS Program source

如果解释性文本包含外壳会话日志，请始终执行此操作。

如果您包含表明使用程序或其他系统功能的shell会话日志，请执行以下操作：

*

将会话日志放在源代码清单上方

*

将会话日志缩进四个空格。

*

用粗体显示用户输入的文本，以区别于系统产生的输出。

有关示例程序外观的一些示例，请参见wait(2)和pipe(2)。

示例

有关手册页包中手册页外观的规范示例，请参见pipe(2)和fcntl(2)。

另外参见

man(1)，man2html(1)，attributes(7)，groff(7)，groff_man(7)，man(7)，mdoc(7)

出版信息

这个页面是Linux手册页项目5.08版的一部分。有关项目的说明、有关报告错误的信息以及此页面的最新版本，请访问https://www.kernel.org/doc/man-pages/。