diff --git a/lib/libutil/Makefile b/lib/libutil/Makefile index bb111dc3368a..3656cea2926c 100644 --- a/lib/libutil/Makefile +++ b/lib/libutil/Makefile @@ -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 @@ MAN= getbootfile.3 getlabelsector.3 getmaxpartitions.3 \ 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 --git a/lib/libutil/sockaddr_snprintf.3 b/lib/libutil/sockaddr_snprintf.3 new file mode 100644 index 000000000000..9de495780c41 --- /dev/null +++ b/lib/libutil/sockaddr_snprintf.3 @@ -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 --git a/lib/libutil/util.3 b/lib/libutil/util.3 index 5c7fe133a9b3..bf1ff3210d9d 100644 --- a/lib/libutil/util.3 +++ b/lib/libutil/util.3 @@ -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 @@ secure_path.3 determine if a file appears to be ``secure'' 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