第十五篇，man手册

一、man手册。
1、什么是man手册？
man手册就是linux下提供给用户查看linux语法的一本书，当用户遇到一些不懂的命令/函数的时候，不用刻意地去记住命令/函数是什么，只需要记住怎么在man手册中查询即可。

遇到不懂的命令   --->  立即查询man手册    -->  得知： 命令功能、命令参数、命令使用方法。
遇到不懂的函数   --->  立即查询man手册    -->  得知： 函数功能、函数头文件、函数原型、函数参数、函数返回值。

2、man手册是如何管理内容？
gec@ubuntu:~$ man man  (按'q'退出到终端)    --> 查看man手册如何使用的。
第一个man就是使用man命令
第二个man就是查询的内容。
    
  The table below shows the section numbers of the manual followed by the types of pages they contain. 
 //man手册根据不同类型的内容是通过数组区分。

 手册数      手册上存放的内容
   1        Executable programs or shell commands
       //可执行程序或者shell命令               ---> 也就是说，当你有不懂的命令，就去第1个手册查询。

   2        System calls (functions provided by the kernel)
       //系统调用函数(这些函数都是由内核来提供)  -->  也就是说，当你有不懂的系统调用函数，只需要去第二个手册中查询。

   3        Library calls (functions within program libraries)
       //库调用函数(这些函数是由库提供)          -->  也就是说，当你有不懂的库调用函数时，只需要去第三个手册中查询。

问题1： 我怎么知道某一个函数是库调用，还是系统调用？
1）通过调用函数次数经验去记住。
2）通过man手册的-k选项来查询得到。

gec@ubuntu:~$ man -k printf
printf (1)           - format and print data         ---> 由于第1手册是存放命令的，所以printf函数肯定不是第1手册。
printf (1posix)      - write formatted output
printf (3)           - formatted output conversion   ---> printf函数是第3个手册。
printf (3posix)      - print formatted output

3）你先man一下第2手册，如果行，那么就是系统调用，那么不行，就是库调用。

问题2： 系统调用与库调用都不需要写实现过程，只需要直接调用即可，那么它们有什么区别？
系统调用这些函数都是由内核提供，也就是说这些函数本身就是存在于linux系统中。
库调用这些函数都是第三方移植进行，也就是说这些函数本身不属于linux系统中，而是移植进来才可以使用。

  

3、举例子  ---  命令
1）假设遇到一个命令叫mkdir，但是不会使用，那怎么办？
命令100%是在第1个手册，直接在第1个手册进行查询就可以。

gec@ubuntu:~$ man 1 mkdir

2）分析内容。
NAME   --> 对命令的功能进行简单的描述
       mkdir - make directories
    //mkdir命令可以创建多个目录

SYNOPSIS   --> 使用格式
       mkdir [OPTION]... DIRECTORY...

mkdir    --> 命令
[]       --> 代表这个选项可以省略，也就是说选项你可以写，也可以不写。
[OPTION]...   --> 代表选项参数可以不写，也可以写多个。
DIRECTORY...  --> 代表这个参数一定要写，而且可以写多个。

DESCRIPTION   --> 对命令的功能进行详细的描述
       Create the DIRECTORY(ies), if they do not already exist.
    //如果一堆目录不存在，那么可以创建这堆目录。

-p, --parents
// -p 等价于 --parents
              no error if existing, make parent directories as needed
        //如果存在不会报错，还可以根据你的需要创建不存在多级父目录。

-m, --mode=MODE
//-m MODE 等价于 --mode=MODE
              set file mode (as in chmod), not a=rwx - umask
        //设置文件起始权限(好像chmod命令一样)，起始权限不会受到umask的干扰。
 

4、举例子   --  函数。
1）假设遇到一个函数叫open，但是不会使用，那么怎么办？
由于函数是分为系统调用与库调用，首先第一步就是先查询这个函数究竟是哪一个？

open (1)             - start a program on a new virtual terminal (VT).   --> 第1手册是存放命令的，所以可以排除。
open (2)             - open and possibly create a file                   --> 第2手册是有的，所以内核有提供open函数。
open (3posix)        - open file relative to directory file descriptor   --> 第3手册也有，代表有人重写了该函数。

2）直接在第2手册中查询即可。
gec@ubuntu:~$ man 2 open

3）分析内容。
NAME   --> 对函数进行简单的描述
       open - open and possibly create a file
    //创建并打开文件

SYNOPSIS   --> 使用格式（包含了头文件和函数原型）

       //只要程序中使用open函数，就要包含以下的三个头文件。
       #include <sys/types.h>
       #include <sys/stat.h>
       #include <fcntl.h>

       //函数原型
       int open(const char *pathname, int flags);

看到函数原型，你要马上得到以下几个结论：
参数个数：   看逗号   如果有n个逗号，那么就有n+1个参数。   2
参数名字：   看下划线                                     pathname      flags
参数类型：   看除了名字之外的部分                         const char*   int
返回值类型： 看函数名字前面的部分                         int 

4）分析参数填什么。
在DESCRIPTION下，根据参数的名字(下划线划住的那个名字)寻找到相应的位置，只需要阅读该位置的上下文即可。

pathname  --> 需要打开的那个文件的路径
Given a pathname for a file
//提供一个文件的路径

flags     --> 操作文件的权限
The argument flags must include one of the following access modes: O_RDONLY, O_WRONLY, or O_RDWR. 
//flags参数必须包含以下的几个模式其中的一个： O_RDONLY, O_WRONLY, or O_RDWR.
                         //只读      只写      可读可写

5）分析函数的返回值是什么。
只需要去RETURN VALUE中寻找即可。

open() return the new file descriptor, or -1 if an error occurred 

  成功： 新的文件描述符  (int)
  失败： -1  

例子： open("/home/gec/xxx.txt",O_RDONLY);
      //以只读的方式来打开家目录下xxx.txt这个文件

    练习1： 查询  pwd  cp
    练习2： 查询  bzero  read  close
 
二、安装中文man手册。
1、中文man手册资源文件： manpages-zh-1.5.1.tar.gz
2、先把资源文件放置到共享目录中：
   windows:  D:\GZ2180\02 linux基础\03
   linux:    /mnt/hgfs/GZ2180/02 linux基础/03

3、切换到资源文件所在的路径下
gec@ubuntu:~$ cd /mnt/hgfs/GZ2180/02\ linux基础/03

4、在linux下解压资源文件，最好解压在linux独有的目录下（家目录）
gec@ubuntu:/mnt/hgfs/GZ2180/02 linux基础/03$ tar zxvf manpages-zh-1.5.1.tar.gz -C /home/gec

5、切换到家目录下，看看有没有新的东西。
gec@ubuntu:/mnt/hgfs/GZ2180/02 linux基础/03$ cd
gec@ubuntu:~$ ls
manpages-zh-1.5.1/ 

6、为中文手册创建一个新的安装目录。
gec@ubuntu:~$ sudo mkdir /usr/local/cman
gec@ubuntu:~$ sudo chmod 777 /usr/local/cman

7、切换到解压之后的目录下，看看有什么内容？
gec@ubuntu:~/manpages-zh-1.5.1$ ls
aclocal.m4  ChangeLog  configure.in  DOCS/    install-sh   Makefile.in  NEWS    src/
AUTHORS     configure    --> 每一个安装包中肯定有一个configure文件
COPYING       INSTALL  Makefile.am  missing      README  utils/

8、了解configure文件安装参数。
gec@ubuntu:~/manpages-zh-1.5.1$ ./configure -h

Usage:       ./configure [OPTION]... [VAR=VALUE]...
 //使用格式：./configure [选项]... [变量=值]...

--prefix=PREFIX         install architecture-independent files in PREFIX    //指定想安装的路径
            [/usr/local]

例如： 我想安装到/usr/local/cman
--prefix=/usr/local/cman

--disable-zhtw          do not generate manpages for zh_TW   --> 禁用繁体字，最终得到的结果是简体字。
--disable-zhcn          do not generate manpage for zh_CN    --> 禁用简体字，最终得到的结果是繁体字。

9、配置
gec@ubuntu:~/manpages-zh-1.5.1$ ./configure --prefix=/usr/local/cman --disable-zhtw

10、编译
gec@ubuntu:~/manpages-zh-1.5.1$ make

11、安装
gec@ubuntu:~/manpages-zh-1.5.1$ make install

12、查看安装的结果。
gec@ubuntu:/usr/local/cman/share/man/zh_CN$ ls
man1/  man2/  man3/  man4/  man5/  man6/  man7/  man8/    --> 如果看到这八个目录，说明已经成功了。

例子： 查看ls用法。
gec@ubuntu:~$ man ls

[-M path]
gec@ubuntu:~$ man -M /usr/local/cman/share/man/zh_CN/ ls

   练习1： 安装中文man手册到你的ubuntu中。
   练习2： 永久设置cman为查看中文手册的命令。

man ls  -> 查英文
cman ls -> 查中文

 思路：   man -M /usr/local/cman/share/man/zh_CN/  取一个新的别名叫  cman

1>. 打开脚本文件。
    gedit ~/.bashrc

2>. 将以下这句话写入到脚本中。
    alias cman='man -M /usr/local/cman/share/man/zh_CN/'

3>. 重启终端生效脚本。
4>. 就可以在任意路径下使用cman ls