Linux man-pages 中缺失的手冊頁

以下是可能應該新增到 man-pages 集合中的頁面列表。如果您正在考慮編寫其中一個或多個頁面，那麼

• 明智的做法是提前告知維護者，以防其他人已經開始編寫該頁面或相關頁面。維護者也可能會為您指出手冊頁的有用資訊來源。
  
  
• 您需要對該主題有相當程度的理解，或者準備投入時間（例如，閱讀原始碼、編寫測試程式）來獲得這種理解。編寫測試程式很重要：在準備手冊頁期間，在編寫測試程式時，已經發現了很多核心和 glibc 的錯誤。
  
  
• 請遵循手冊頁的現有格式約定。有關格式的一些資訊在 man(7) 和 man-pages(7) 手冊頁中提供。作為如何使用這些約定的示例，請檢視 fcntl(2) 手冊頁並閱讀其原始檔 (man2/fcntl.2)。
  
  
• 該頁面必須以某種允許自由重新分發和修改的許可證提交。請在手冊頁的原始碼中包含該許可證或對其的引用。有關首選的自由許可證列表，請點選此處。
  
  
• 說明您是如何獲得頁面中的資訊的：是透過閱讀（或編寫）相關的核心或 (g)libc 原始碼；透過編寫測試程式（如果需要，並且如果它清晰且易於使用，則將其與補丁一起傳送）；來自標準文件；來自其他文件；來自郵件列表或 Usenet 執行緒（如果可能，請提供 URL）？
  
  
• 請按照提交補丁的專案指南提交頁面。請務必抄送給任何其他相關方，包括您知道的可能適合審查該頁面的任何人員。
  
  
• GNU C 庫使用 info(1) 記錄它提供的許多函式。由於許多程式設計師更喜歡 man 格式的文件，因此這並不妨礙為已經使用 info(1) 記錄的函式編寫手冊頁。理想情況下，手冊頁至少應包含與 info(1) 頁面中包含的資訊一樣多的資訊，並且還應包含 info(1) 頁面通常不涵蓋的詳細資訊，例如，有關該函式在各個 glibc 版本中如何更改的歷史資訊，或者 C 庫中操作的差異；此類資訊通常不存在於 info(1) 頁面中）。（另一種需要考慮的替代方案是，如果更合適，則向 glibc 文件的維護者提交補丁。）

系統呼叫

/sys 檔案系統

沒有針對 /sys 檔案系統的手冊頁：可能應該有一個類似於 proc(5) 的 sys(5) 頁面。核心原始檔 Documentation/filesystems/sysfs.txt 為此頁面提供了一個起點；另請參閱 Documentation/ 目錄下的許多其他 *sysfs*.txt 檔案。

GNU C 庫命令

GNU C 庫提供了一些命令（可執行檔案、指令碼），例如 ldd(1) 和 time(1)。這些命令在 man-pages 的第 1 節和第 8 節中進行了記錄。至少缺少以下頁面

庫函式

下面列出了未記錄的 (GNU) C 庫函式。像以下這樣的搜尋可能會建議其他需要記錄的函式

MPDIR=~/man-pages       # Directory containing uncompressed man-pages
GLIBCDIR=/SOME_DIR      # Directory containing glibc tree

for f in  $(cat $(find $GLIBCDIR -name Versions |
                egrep -v '/(hurd|mach)/') |
        egrep -v '({|}|^%)' |
        sed -e 's/#.*//' |
        tr ';' '\012' |
        sed 's/^  *//' |
        grep -v '^[_.]' |
        sort -u); do
    if ! test -f "$MPDIR/man3/$f.3" > /dev/null 2>&1 &&
                ! test -f "$MPDIR/man2/$f.2" > /dev/null 2>&1 ; then
        echo $f;
    fi
done

或者，可以檢視特定庫匯出的文字符號（除非庫符號已被剝離），以檢視是否有相應的手冊頁。這裡，使用 libm 的示例

nm -D /lib/libm.so.6 | sed -re '/^[0-9a-f]* T /!d; s///; /^_/d' |
	xargs whatis | sed -ne 's/: nothing appropriate\.$//p' | sort -u

在許多情況下，下面列出的介面是使用此類指令碼找到的，並且尚未檢查這些介面是否是可能最好不記錄的過時介面。

POSIX 執行緒 API

最後但同樣重要的是 POSIX 執行緒 API。請注意，glibc 提供了一組現有的、過時的頁面，這些頁面記錄了舊的 LinuxThreads 實現。（這些頁面是在允許重用的許可下編寫的，因此它們包含的一些材料可以在新頁面中使用。）

需要的是一組文件完整 API 的頁面，描述 LinuxThreads 和 NPTL 與標準不同的細節。現有的 pthreads(7) 手冊頁提供了 Linux 上 Pthreads 實現的概述，旨在作為這些手冊頁的背景文件。

所需的手冊頁列表很長（相關函式可以分組在單個頁面上）；標有更多星號的頁面可能最希望首先完成。