第 173 / 187 篇

17.2. man 与 Unix 手册

说明

本文是个人学习用的非官方中英对照译文,原文:https://diveintosystems.org/book/Appendix2/man.html。
原书采用 CC BY-NC-ND 4.0 许可(禁止演绎),请勿公开传播本译文。
标为「译注」「现代更新」的内容是译者补充,不代表原书作者观点;代码与原文逐字一致,未作改动。

17.2. man and the Unix Manual

Unix 手册页提供了 ls 或 rm 等 Unix 命令、系统调用以及库函数的文档。可以用 Unix 的 man 命令阅读手册页。apropos 命令可以用来搜索与某个主题相关的 Unix 命令和库函数,主题由作为其命令行参数给出的搜索模式提供。许多 Unix 和 C 库的手册页也可以在网上找到,例如 kernel.org 上。

Unix manual pages provide documentation for Unix commands like ls, or rm, of system calls, and of library functions. You can read manual pages using the Unix man command. The apropos command can be used to search for Unix commands and library functions related to a topic supplied by a search pattern given as its command line argument. Many Unix and C library man pages are also available online, such as at kernel.org.

Unix 手册分为几个部分(section)。前三部分最常用。

The Unix manual is divided into several sections. The first three are the most commonly used.

  1. 第 1 部分是可以在命令行上输入的命令(例如 ls)。
  1. Section 1 is for commands that you can enter on the command line (e.g., ls).
  1. 第 2 部分是可以在程序代码中调用的 Unix 系统调用(例如 fork)。
  1. Section 2 is for Unix system calls that you can call from program code (e.g., fork).
  1. 第 3 部分是可以在程序代码中调用的库函数(例如 printf 这样的 C 库函数)。
  1. Section 3 is for library functions that you can call from your program code (e.g., C library functions such as printf).

运行 man 命令可以查看关于某个命令或函数的文档的手册页。手册页在一个名为 less 的程序中打开。在 less 中,输入 q 退出,按空格键向下翻一整页,用方向键一次上下移动一行。还可以用类似 Vim 搜索的 / 语法搜索内容。

Run the man command to view the manual page with documentation about a command or function. The man page is opened in a program named less. You can quit less by typing q, move down a full a page by typing the space bar, or move up and down one line at a time using the arrow keys. You can also search for content using / syntax similar to Vim search.

要查看 ls 命令的手册页,运行:

To view the man page for the ls command, run:

1
$ man ls

有时同一个名字既用作命令,又用作函数。在这种情况下,可以通过指定它所在的手册部分来得到正确的手册页。例如,要得到出现在手册第 2 部分中的系统调用 write 的手册页,输入:

Sometimes the same name is used for a command and a function. In this case you can get the correct man page by specifying the part of the manual in which it is contained. For example, to get the man page for the system call write, which appears in section 2 of the manual, type:

1
$ man 2 write

你也可以阅读 man 自己的手册页来进一步了解它:

You can also read the manual page for man to learn more about it:

1
$ man man

17.2.1. 阅读手册页

17.2.1. Reading man pages

如何阅读手册页可能不是一目了然的,所以我们来看一个例子,即 toupper 的手册页:

It may not be completely obvious how to read a man page, so lets look at an example of the toupper man page:

1
$ man toupper

toupper 库函数的手册页大致如下:

The man page for the toupper library function look something like this:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
TOUPPER(3)          Linux Programmer's Manual          TOUPPER(3)



NAME
toupper, tolower - convert letter to upper or lower case

SYNOPSIS
#include <ctype.h>

int toupper (int c);
int tolower (int c);

DESCRIPTION
toupper() converts the letter c to upper case, if possible.

tolower() converts the letter c to lower case, if possible.

If c is not an unsigned char value, or EOF, the behavior
of these functions is undefined.

RETURN VALUE
The value returned is that of the converted letter, or c
if the conversion was not possible.

CONFORMING TO
ANSI C, BSD 4.3

BUGS
The details of what constitutes an uppercase or lowercase
letter depend on the current locale. For example,
the default C locale does not know about umlauts, so
no conversion is done for them.
In some non-English locales, there are lowercase letters
with no corresponding uppercase equivalent; the German
sharp s is one example.

SEE ALSO
isalpha(3), setlocale(3), locale(7)

GNU 1993-04-04 TOUPPER(3)

第一行 TOUPPER(3) 表明 toupper 的手册页在手册的第 3 部分。

The first line, TOUPPER(3), says that the man page for toupper is in section 3 of the manual.

NAME、DESCRIPTION 和 RETURN VALUE 这几部分给出了函数功能的简短和详细描述,说明了它的参数是什么,以及它返回什么:

The NAME, DESCRIPTION, and RETURN VALUE, parts give short and long descriptions of what the function does, what its parameters are, and what it returns:

1
2
3
4
5
6
7
8
9
NAME
toupper, tolower - convert letter to upper or lower case

DESCRIPTION
toupper() converts the letter c to upper case, if possible.

RETURN VALUE
The value returned is that of the converted letter,
or c if the conversion was not possible.

SYNOPSIS 部分指出使用这个函数是否需要包含某些头文件,以及编译可执行文件时是否需要显式链接某些库。它还列出了完整的函数原型:

The SYNOPSIS part indicates if any header files need to be included to use this function, and if it is necessary to explicitly link in any libraries to compile an executable. It also lists the full function prototype:

1
2
3
4
SYNOPSIS
#include < ctype.h >

int toupper (int c);

这个概要表明,要调用 toupper,.c 文件必须 #include <ctype.h>,而调用这个函数的程序不需要显式链接任何库。

The synopsis indicates that to call toupper a .c file must #include <ctype.h>, and that no library needs to be explicitly linked into a program that calls this function.

SEE ALSO 部分列出了其他相关的函数。然后可以对它们运行 man 来进一步了解(例如 man isalpha)。

The SEE ALSO part lists other related functions. You can then run man on these to learn more about them (e.g., man isalpha).

1
2
SEE ALSO
isalpha(3), setlocale(3), locale(7)

手册页有时还包含如何调用函数的示例。

Man pages sometimes include examples of how to call the function.

17.2.2. apropos

17.2.2. apropos

有时你并不知道想用的函数或命令叫什么名字。apropos 命令在 Unix 手册页的描述中搜索与你作为命令行选项给出的搜索模式匹配的关键词,并列出它认为合适的命令/函数。例如,如果你想找到一个获取当前工作目录的函数的名字,但记不起这个函数叫什么,可以问 apropos:

Sometimes you do not know the name of a function or command that you want to use. The apropos command searches Unix manual page descriptions for key words that match the search pattern you list as a command line option and lists commands/functions that it thinks are appropriate matches. For example, if you want to find the name of a function for getting the current working directory, but you can’t remember the function’s name, you can ask apropos:

1
2
3
4
$ apropos "current working directory"
get_current_dir_name (3) - Get current working directory
getcwd (3) - Get current working directory
getwd (3) - Get current working directory

然后你可以阅读结果中的一些手册页,看看其中哪一个是你想要的:

Then you can read some of the man pages for the results to see which one of these is the one you want:

1
$ man 3 getcwd

17.2.3. 参考资料

17.2.3. References

更多信息参见:

For more information see:

  • 手册页:man man、man apropos
  • The man pages: man man, man apropos
  • kernel.org 上的 Linux 手册页在线版本。
  • kernel.org on-line version of Linux manual pages.