Aren
/
NetBSD
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Add a manual page.

This commit is contained in:
christos 2004-11-20 03:06:09 +00:00
parent 95f9af9926
commit 1fe49f768f
3 changed files with 204 additions and 3 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
lib/libutil/Makefile
View File

@ -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

199
lib/libutil/sockaddr_snprintf.3 Normal file
View File

@ -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.

3
lib/libutil/util.3
View File

@ -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