[src/trunk]: src/lib/libutil Add a manual page.

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

details:   https://anonhg.NetBSD.org/src/rev/ec20f12abcbb
branches:  trunk
changeset: 571367:ec20f12abcbb
user:      christos <christos%NetBSD.org@localhost>
date:      Sat Nov 20 03:06:09 2004 +0000

description:
Add a manual page.

diffstat:

 lib/libutil/Makefile            |    5 +-
 lib/libutil/sockaddr_snprintf.3 |  199 ++++++++++++++++++++++++++++++++++++++++
 lib/libutil/util.3              |    3 +-
 3 files changed, 204 insertions(+), 3 deletions(-)

diffs (239 lines):

diff -r b8d157b7ac28 -r ec20f12abcbb lib/libutil/Makefile
--- a/lib/libutil/Makefile      Sat Nov 20 00:53:13 2004 +0000
+++ b/lib/libutil/Makefile      Sat Nov 20 03:06:09 2004 +0000
@@ -1,4 +1,4 @@
-#      $NetBSD: Makefile,v 1.45 2004/11/19 21:37:19 christos Exp $
+#      $NetBSD: Makefile,v 1.46 2004/11/20 03:06:09 christos Exp $
 #      @(#)Makefile    8.1 (Berkeley) 6/4/93
 
 USE_SHLIBDIR=  yes
@@ -22,7 +22,8 @@
        login.3 login_cap.3 loginx.3 \
        disklabel_dkcksum.3 disklabel_scan.3 \
        opendisk.3 openpty.3 pidfile.3 pidlock.3 \
-       pw_getconf.3 pw_init.3 pw_lock.3 secure_path.3 snprintb.3 ttyaction.3 \
+       pw_getconf.3 pw_init.3 pw_lock.3 secure_path.3 snprintb.3 \
+       sockaddr_snprintf.3 ttyaction.3 \
        ttymsg.3 util.3
 
 .PATH: ${NETBSDSRCDIR}/lib/libc/gen
diff -r b8d157b7ac28 -r ec20f12abcbb lib/libutil/sockaddr_snprintf.3
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/lib/libutil/sockaddr_snprintf.3   Sat Nov 20 03:06:09 2004 +0000
@@ -0,0 +1,199 @@
+.\"     $NetBSD: sockaddr_snprintf.3,v 1.1 2004/11/20 03:06:09 christos Exp $
+.\"
+.\" Copyright (c) 2004 The NetBSD Foundation, Inc.
+.\" All rights reserved.
+.\"
+.\" This code is derived from software contributed to The NetBSD Foundation
+.\" by Christos Zoulas.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\" 3. All advertising materials mentioning features or use of this software
+.\"    must display the following acknowledgement:
+.\"        This product includes software developed by the NetBSD
+.\"        Foundation, Inc. and its contributors.
+.\" 4. Neither the name of The NetBSD Foundation nor the names of its
+.\"    contributors may be used to endorse or promote products derived
+.\"    from this software without specific prior written permission.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
+.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
+.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
+.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+.\" CONTRACT, STRICT LIABILITY, OR TORT (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 November 19, 2004
+.Dt SOCKADDR_SNPRINTF 8
+.Os
+.Sh NAME
+.Nm sockaddr_snprintf
+.Nd formatting function for socket address structures
+.Sh SYNOPSIS
+.In util.h
+.Ft int
+.Fn "sockaddr_snprintf" "char *buf" "size_t buflen" "const char *fmt" "const struct sockaddr *sa"
+.Sh DESCRIPTION
+The
+.Fn sockaddr_snprintf
+function formats a socket address into a form suitable for printing.
+.Pp
+This function is convenient because it is protocol independent, i.e. one does
+not need to know the address family of the sockaddr in order to print it.
+The
+.Xr printf 3
+like format string specifies how the address is going to be printed.
+Some formatting characters are only supported by some address families.
+If a certain formatting character is not supported, then the string
+.Dt N/A
+is printed.
+.Pp
+The resulting formatted string is placed into
+.Fa buf .
+Up to
+.Fa buflen
+characters are placed in
+.Fa buf .
+.Pp
+The following formatting characters are supported:
+.Bl -tag -width %a
+.It a
+The node address portion of the socket address is printed numerically.
+For
+.Dv AF_INET
+the address is printed as:
+.Dv A.B.C.D 
+and
+for AF_INET6
+the address is printed as:
+.Dv A:B...[%if] 
+using
+.Xr getnameinfo
+internally with
+.Dv NI_NUMERICHOST .
+For 
+.Dv AF_APPLETALK
+the address is printed as:
+.Dv A.B
+For
+.Dv AF_LOCAL
+.Dv ( AF_UNIX )
+the address is printed as:
+.Dv socket-path
+For
+.Dv AF_LINK
+the address is printed as:
+.Dv a.b.c.d.e.f
+using
+.Xr link_ntoa 3 ,
+but the interface portion is skipped (see below).
+For
+.Dv AF_UNSPEC
+nothing is printed.
+.It f
+The numeric value of the family of the address is printed.
+.It l
+The length of the socket address is printed.
+.It p
+For
+.Dv AF_INET ,
+.Dv AF_INET6 ,
+and
+.Dv AF_APPLETALK
+the numeric value of the port portion of the address is printed.
+.It I
+For
+.Dv AF_LINK
+addresses, the interface name portion is printed.
+.It F
+For
+.Dv AF_INET6
+addresses, the flowinfo portion of the address is printed numerically.
+.It R
+For
+.Dv AF_APPLETALK
+addresses, the netrange portion of the address is printed as:
+.Dv phase:[firstnet,lastnet]
+.It S
+For
+.Dv AF_INET6
+addresses, the scope portion of the address is printed numerically.
+.El
+.Sh RETURN VALUES
+The
+.Fn sockaddr_snprintf 
+function returns the number of characters that are required to format the
+value
+.Fa val
+given the format string
+.Fa fmt
+excluding the terminating NUL.
+The returned string in
+.Fa buf
+is always NUL-terminated.
+If the address family is not supported,
+.Fn sockaddr_snprintf
+returns -1 and sets
+.Fa errno
+to 
+.Dv EAFNOSUPPORT .
+For
+.Dv AF_INET
+and
+.DV AF_INET6
+addresses
+.Fn sockaddr_snprintf
+returns -1 if the
+.Xr getnameinfo 3
+conversion failed, and
+.Fa errno
+is set to the error value from
+.Xr getnameinfo 3 .
+.Sh ERRORS
+If the buffer
+.Fa buf
+is too small to hold the formatted output,
+.Fn sockaddr_snprintf
+will still return the buffer, containing a truncated string.
+.Sh SEE ALSO
+.Xr getnameinfo 3
+.Xr link_ntoa 3
+.Xr snprintf 3
+.Sh HISTORY
+The
+.Fn sockaddr_snprintf
+first appeared in
+.Nx 3.0
+.Sh BUGS
+The
+.Fn sockaddr_snprintf
+interface is experimental and might change in the future.
+.Pp
+There is no way to specify different formatting styles for particular
+addresses.
+For example it would be useful to print
+.Dv AF_LINK
+addresses as
+.Dv %.2x:%.2x...
+instead of
+.Dv %x.%x...
+.Pp
+This function is supposed to be quick, but
+.Xr getnameinfo 3
+might use system calls to convert the scope number to an interface name.
+.Pp
+Not all formatting characters are supported by all address families and
+printing
+.Dv N/A
+is not very conventient.
diff -r b8d157b7ac28 -r ec20f12abcbb lib/libutil/util.3
--- a/lib/libutil/util.3        Sat Nov 20 00:53:13 2004 +0000
+++ b/lib/libutil/util.3        Sat Nov 20 03:06:09 2004 +0000
@@ -1,4 +1,4 @@
-.\"     $NetBSD: util.3,v 1.13 2002/12/22 02:19:15 wiz Exp $
+.\"     $NetBSD: util.3,v 1.14 2004/11/20 03:06:09 christos Exp $
 .\"
 .\" Copyright (c) 2001 The NetBSD Foundation, Inc.
 .\" All rights reserved.
@@ -105,6 +105,7 @@
 setclasscontext.3      query login.conf database about a user class
 setusercontext.3       query login.conf database about a user class
 snprintb.3     bitmask output conversion
+sockaddr_snprintf.3    socket address formatting function
 ttyaction.3    ttyaction utility function
 ttylock.3      locks based on files containing PIDs
 ttymsg.3       ttymsg utility function