[Swan-dev] man pages for our library routines

[D. Hugh Redelmeier]

>From IRC:

<cagney>	DHR, unlike snprintf(), the *tot() return a length that 
includes the '\0'?

The way to answer this is to read the man pages.  Unfortunately, those 
have become unknown.

Henry created very comprehensive man pages for those library routines.

The FreeS/WAN and Openswan projects installed those pages so that, for 
example,
	man ipsec_addrtot
would display the page for addrtot.

The Libreswan project no longer builds or installs those pages.  But the 
source code for the pages still exists and can be consulted.  Albeit in 
XML rather than the original troff markup.

Since even some developers don't know of these pages' existence, there is 
a chance that the man pages are bitrotten.  But I have found few 
reasons to revise Henry's excellent code.  The major bitrot is probably 
that some routines have been deleted (perhaps without removing 
documentation) and some have been added (without providing documentation).

One consequence of a man page not being installed is that its aliases are 
not manifest.  For example, lib/libswan/ttoaddr.3.xml would be installed 
with additional links for ipsec_ttoaddr ipsec_tnatoaddr ipsec_addrtot ipsec_ttosubnet
ipsec_subnettot.

(I don't know how to view a manpage that is in XML.  The man command
would display one written in troff.  I'm old fashioned and don't
consider XML an improvement.  We're still fixing bug introduced by the
translation.)

Now for the answer to Andrew's original question.  Here's an extract
from lib/libswan/ttoaddr.3.xml

The binary-to-text functions return
<literal>0</literal>
for a failure, and otherwise
always return the size of buffer that would
be needed to
accommodate the full conversion result, including terminating NUL;
it is the caller's responsibility to check this against the size of
the provided buffer to determine whether truncation has occurred.</para>
</refsect1>