[src/trunk]: src/share/man/man9 confusing pooka.

[plunky <plunky%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/e435b7c4680e
branches:  trunk
changeset: 747148:e435b7c4680e
user:      plunky <plunky%NetBSD.org@localhost>
date:      Fri Sep 04 11:34:38 2009 +0000

description:
confusing pooka.
manpage improvements,
sunshine returns.

diffstat:

 share/man/man9/sockopt.9 |  16 ++++++++++++----
 1 files changed, 12 insertions(+), 4 deletions(-)

diffs (44 lines):

diff -r 589232e8e83e -r e435b7c4680e share/man/man9/sockopt.9
--- a/share/man/man9/sockopt.9  Fri Sep 04 11:26:54 2009 +0000
+++ b/share/man/man9/sockopt.9  Fri Sep 04 11:34:38 2009 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: sockopt.9,v 1.6 2009/08/03 19:57:40 rmind Exp $
+.\"    $NetBSD: sockopt.9,v 1.7 2009/09/04 11:34:38 plunky Exp $
 .\"
 .\" Copyright (c) 2008 Iain Hibbert
 .\" All rights reserved.
@@ -23,7 +23,7 @@
 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd October 28, 2008
+.Dd September 4, 2009
 .Dt SOCKOPT 9
 .Os
 .Sh NAME
@@ -49,8 +49,9 @@
 .Ft int
 .Fn sockopt_setint "struct sockopt *sopt" "int value"
 .Sh DESCRIPTION
-The sockopt structure is used to pass a socket option and associated
-value:
+The
+.Ft sockopt
+structure is used to pass a socket option and associated value:
 .Bd -literal -offset indent
 struct sockopt {
        int             sopt_level;             /* option level */
@@ -65,6 +66,13 @@
 size so that memory allocation is not required and sopt_data will point
 to this in that case.
 .Pp
+Rather than provide accessor functions, the
+.Ft sockopt
+structure is public and the contents are expected to be internally
+consistent, but the normal practice would be to use the appropriate methods
+for storage and retrieval of values where a known datatype is expected,
+as the size will be verified.
+.Pp
 Note: a sockopt structure may only be used for a single level/name/size
 combination.
 If the structure is to be re-used, it must be destroyed and re-initialized