Hacker News Reader

Comment by rosser | Hacker News Reader

Small, somewhat nit-picky critique: the man pages for system calls are in section 2. If you want to see the docs for the "read()" syscall, and not the bash builtin "read", saying "man read" w̶o̶n̶'̶t̶ may not (see follow-up) do what you expect. Instead, you should say

  man 2 read

This should probably be mentioned somewhere.

Otherwise, great writeup. Thanks for sharing!

(edited)

View on HN

Different Unix systems take different syntax for specifying the section. Long ago I learned to say "man -a read" and just get _all_ the "read" pages, scanning for the ones I want (and sometimes learning about things I didn't know were there).

I'm going to hijack this comment to ask a question that I haven't been able to google:

What is the number after the command called? For example, when I look up 'man sed', I find a manpage for 'sed(1)'[0]. When I look up 'man kill', I find manpages for 'kill(1)' and 'kill(2)'[2].

Can somebody tell me what that number is called so I can look it up? Thanks..

0: https://developer.apple.com/library/mac/documentation/Darwin... 1: https://developer.apple.com/library/mac/documentation/Darwin... 2: http://man7.org/linux/man-pages/man2/kill.2.html

That number refers to the section of the man pages that the command is in. See http://en.wikipedia.org/wiki/Man_page#Manual_sections for an example list; however, it seems the list is not the same between systems.

That's the "section" I'm talking about. "sed(1)" means that the man page for that sed is in section 1. "kill(1)" versus "kill(2)" likewise: the former is the command; the latter is the syscall. To distinguish between them, you need to tell man(1) which section to look in for the desired context.

There's a manpage bash-builtins in section 7, but I've never seen a system that had manpages for the individual builtins, let alone having them in section 1. "man read" on every system I've used opens the read manpage in section 2.

Some syscalls share names with commands in section 1 though.

My local CentOS 6.2 VM has bash-builtins in section 1, which is where "man read" takes me. Same with a RHEL 6.4 machine in the colo.

This might be a distro-specific thing.

Same with OSX: "man read" opens the builtin(1) manpage. However on Debian 7.3, it opens read(2).

You can configure the priority of the sections in /etc/man.conf or similar.

read is also documented by POSIX, and those man pages are often installed in section 1p.

At least on my Mac, it opens the page for BUILTIN(1).

I can't remember a unix system for at least the last decade that hasn't given me the section 1 bash "read" instead of the section 2 system "read" on a "man read".

I've been on Ubuntu for several years, and I see the same as JoshTriplett. Must be platform dependent.

This is why the documentation for COHERENT was changed from "man" pages to what we called a Lexicon, removing the concept of sections. Each entry would have the description of the type of the entry, such as system call, shell command, and so on. Steve Ness has made this available online at http://www.nesssoftware.com/home/mwc/manual.php

You can change the section search order with the SECTION directive in /etc/man_db.conf, or you can override that global setting with the MANSECT environment variable. I just learned this from "man man". :) I'm personally tempted to put "2 3" ahead of the rest, because most of the time I'm just trying to refresh my memory on function parameters.

Reply on news.ycombinator.com