git.saurik.com Git - apple/libinfo.git/blame_incremental

... / ...

Commit	Line	Data
	1	.\" $KAME: if_indextoname.3,v 1.10 2000/11/24 08:13:51 itojun Exp $
	2	.\" BSDI Id: if_indextoname.3,v 2.2 2000/04/17 22:38:05 dab Exp
	3	.\"
	4	.\" Copyright (c) 1997, 2000
	5	.\" Berkeley Software Design, Inc. All rights reserved.
	6	.\"
	7	.\" Redistribution and use in source and binary forms, with or without
	8	.\" modification, are permitted provided that the following conditions
	9	.\" are met:
	10	.\" 1. Redistributions of source code must retain the above copyright
	11	.\" notice, this list of conditions and the following disclaimer.
	12	.\"
	13	.\" THIS SOFTWARE IS PROVIDED BY Berkeley Software Design, Inc. ``AS IS'' AND
	14	.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
	15	.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
	16	.\" ARE DISCLAIMED. IN NO EVENT SHALL Berkeley Software Design, Inc. BE LIABLE
	17	.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
	18	.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
	19	.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
	20	.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
	21	.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
	22	.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
	23	.\" SUCH DAMAGE.
	24	.\"
	25	.\" $FreeBSD: src/lib/libc/net/if_indextoname.3,v 1.11 2005/11/23 10:49:07 ru Exp $
	26	.\"
	27	.Dd November 23, 2005
	28	.Dt IF_NAMETOINDEX 3
	29	.Os
	30	.Sh NAME
	31	.Nm if_nametoindex ,
	32	.Nm if_indextoname ,
	33	.Nm if_nameindex ,
	34	.Nm if_freenameindex
	35	.Nd provide mappings between interface names and indexes
	36	.Sh SYNOPSIS
	37	.In sys/types.h
	38	.In sys/socket.h
	39	.In net/if.h
	40	.Ft "unsigned int"
	41	.Fn if_nametoindex "const char *ifname"
	42	.Ft "char *"
	43	.Fn if_indextoname "unsigned int ifindex" "char *ifname"
	44	.Ft "struct if_nameindex *"
	45	.Fn if_nameindex "void"
	46	.Ft void
	47	.Fn if_freenameindex "struct if_nameindex *ptr"
	48	.Sh DESCRIPTION
	49	The
	50	.Fn if_nametoindex
	51	function maps the interface name specified in
	52	.Fa ifname
	53	to its corresponding index.
	54	If the specified interface does not exist, it returns 0.
	55	.Pp
	56	The
	57	.Fn if_indextoname
	58	function maps the interface index specified in
	59	.Fa ifindex
	60	to it corresponding name, which is copied into the
	61	buffer pointed to by
	62	.Fa ifname ,
	63	which must be of at least
	64	.Dv IFNAMSIZ
	65	bytes.
	66	This pointer is also the return value of the function.
	67	If there is no interface corresponding to the specified
	68	index,
	69	.Dv NULL
	70	is returned.
	71	.Pp
	72	The
	73	.Fn if_nameindex
	74	function returns an array of
	75	.Vt if_nameindex
	76	structures, one structure per interface, as
	77	defined in the include file
	78	.In net/if.h .
	79	The
	80	.Vt if_nameindex
	81	structure contains at least the following entries:
	82	.Bd -literal
	83	unsigned int if_index; /* 1, 2, ... */
	84	char if_name; / null terminated name: "le0", ... */
	85	.Ed
	86	.Pp
	87	The end of the array of structures is indicated by a structure with an
	88	.Va if_index
	89	of 0 and an
	90	.Va if_name
	91	of
	92	.Dv NULL .
	93	A
	94	.Dv NULL
	95	pointer is returned upon an error.
	96	.Pp
	97	The
	98	.Fn if_freenameindex
	99	function frees the dynamic memory that was
	100	allocated by
	101	.Fn if_nameindex .
	102	.Sh RETURN VALUES
	103	Upon successful completion,
	104	.Fn if_nametoindex
	105	returns the index number of the interface.
	106	If the interface is not found, a value of 0 is returned and
	107	.Va errno
	108	is set to
	109	.Er ENXIO .
	110	A value of 0 is also returned if an error
	111	occurs while retrieving the list of interfaces via
	112	.Xr getifaddrs 3 .
	113	.Pp
	114	Upon successful completion,
	115	.Fn if_indextoname
	116	returns
	117	.Fa ifname .
	118	If the interface is not found, a
	119	.Dv NULL
	120	pointer is returned and
	121	.Va errno
	122	is set to
	123	.Er ENXIO .
	124	A
	125	.Dv NULL
	126	pointer is also returned if an error
	127	occurs while retrieving the list of interfaces via
	128	.Xr getifaddrs 3 .
	129	.Pp
	130	The
	131	.Fn if_nameindex
	132	returns a
	133	.Dv NULL
	134	pointer if an error
	135	occurs while retrieving the list of interfaces via
	136	.Xr getifaddrs 3 ,
	137	or if sufficient memory cannot be allocated.
	138	.Sh SEE ALSO
	139	.Xr getifaddrs 3 ,
	140	.Xr networking 4
	141	.Sh STANDARDS
	142	The
	143	.Fn if_nametoindex ,
	144	.Fn if_indextoname ,
	145	.Fn if_nameindex ,
	146	and
	147	.Fn if_freenameindex
	148	functions conform to
	149	.%T "RFC 2553" .
	150	.Sh HISTORY
	151	The implementation first appeared in BSDi
	152	.Bsx .