== Reading Unix manpages

One of the important skills for Unix programming is the ability to parse
manpages carefully. This is not as easy as it looks, because manpages
are traditionally written in a style where everything is important and
you have to think carefully about the implications of the exact wording
used.

(This can be useful for other things than Unix manpages, since a lot of
specifications are written in the same style.)

For example, today I was emailed a comment on my [[Python
socket module irritation entry ../python/SocketModuleIrritations]]
pointing out the existence of the _.makefile()_ method function,
which:

> Return a *file object* associated with the socket. [...]
> The file object references a _dup()_ped version of the socket file
> descriptor, so the file object and socket object may be closed or
> garbage-collected independently.

Thinking about how I would use this, one of the things I found myself
wondering about was what would happen if you _dup()_ped a socket
file descriptor and called _shutdown()_ on only one of the file
descriptors. (Bearing in mind that you have to _close()_ *all* of the
file descriptors for a socket before the socket goes away.)

So I consulted the manpage. The Linux _shutdown(2)_ manpage contains the
following description (emphasis mine):

> The shutdown call causes all or part of a full-duplex connection on
> *the socket associated with fd* to be shut down.

(Similar wording appears in the Solaris and FreeBSD manual pages.)

Once I put on my spec reading hat, it was clear that saying 'the socket
associated with fd' instead of something like 'the file descriptor
fd' was important. Thus _shutdown(2)_ is not like _close()_ and has
an immediate effect when called, no matter how many times the file
descriptor has been _dup()_ped.

(And some [[quick Python ../python/TestingSystemBehavior]] later,
I had confirmed this.)