share/man/man3xnet/if_nametoindex.3xnet

   1 '\" te
   2 .\" Copyright (C) 2003, Sun Microsystems, Inc.
   3 .\" All Rights Reserved
   4 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   5 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   6 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   7 .TH IF_NAMETOINDEX 3XNET "Dec 14, 2003"
   8 .SH NAME
   9 if_nametoindex, if_indextoname, if_nameindex, if_freenameindex \- functions to
  10 map Internet Protocol network interface names and interface indexes
  11 .SH SYNOPSIS
  12 .LP
  13 .nf
  14 \fBcc\fR [ \fIflag\fR... ] \fIfile\fR... [ \fIlibrary\fR... ]
  15 #include <net/if.h>
  16
  17 \fBunsigned int\fR \fBif_nametoindex\fR(\fBconst char *\fR\fIifname\fR);
  18 .fi
  19
  20 .LP
  21 .nf
  22 \fBchar *\fR\fBif_indextoname\fR(\fBunsigned int\fR \fIifindex\fR, \fBchar *\fR\fIifname\fR);
  23 .fi
  24
  25 .LP
  26 .nf
  27 \fBstruct if_nameindex *\fR\fBif_nameindex\fR(void)
  28 .fi
  29
  30 .LP
  31 .nf
  32 \fBvoid\fR \fBif_freenameindex\fR(\fBstruct if_nameindex *\fR\fIptr\fR);
  33 .fi
  34
  35 .SH PARAMETERS
  36 .sp
  37 .LP
  38 These functions support the following parameters:
  39 .sp
  40 .ne 2
  41 .na
  42 \fB\fIifname\fR\fR
  43 .ad
  44 .RS 11n
  45 interface name
  46 .RE
  47
  48 .sp
  49 .ne 2
  50 .na
  51 \fB\fIifindex\fR\fR
  52 .ad
  53 .RS 11n
  54 interface index
  55 .RE
  56
  57 .sp
  58 .ne 2
  59 .na
  60 \fB\fIptr\fR\fR
  61 .ad
  62 .RS 11n
  63 pointer returned by \fBif_nameindex()\fR
  64 .RE
  65
  66 .SH DESCRIPTION
  67 .sp
  68 .LP
  69 This \fBAPI\fR defines two functions that map between an Internet Protocol
  70 network interface name and index, a third function that returns all the
  71 interface names and indexes, and a fourth function to return the dynamic memory
  72 allocated by the previous function.
  73 .sp
  74 .LP
  75 Network interfaces are normally known by names such as \fBeri0\fR, \fBsl1\fR,
  76 \fBppp2\fR, and the like. The \fIifname\fR argument must point to a buffer of
  77 at least \fBIF_NAMESIZE\fR bytes into which the interface name corresponding to
  78 the specified index is returned. \fBIF_NAMESIZE\fR is defined in
  79 <\fBnet/if.h\fR> and its value includes a terminating null byte at the end of
  80 the interface name.
  81 .sp
  82 .ne 2
  83 .na
  84 \fB\fBif_nametoindex()\fR\fR
  85 .ad
  86 .RS 22n
  87 The \fBif_nametoindex()\fR function returns the interface index corresponding
  88 to the interface name pointed to by the \fIifname\fR pointer. If the specified
  89 interface name does not exist, the return value is \fB0\fR, and \fIerrno\fR is
  90 set to \fBENXIO\fR. If there was a system error, such as running out of memory,
  91 the return value is \fB0\fR and \fIerrno\fR is set to the proper value, for
  92 example, \fBENOMEM\fR.
  93 .RE
  94
  95 .sp
  96 .ne 2
  97 .na
  98 \fB\fBif_indextoname()\fR\fR
  99 .ad
 100 .RS 22n
 101 The \fBif_indextoname()\fR function maps an interface index into its
 102 corresponding name. This pointer is also the return value of the function. If
 103 there is no interface corresponding to the specified index, \fBNULL\fR is
 104 returned, and \fIerrno\fR is set to \fBENXIO\fR, if there was a system error,
 105 such as running out of memory, \fBif_indextoname()\fR returns \fBNULL\fR and
 106 \fIerrno\fR would be set to the proper value, for example, \fBENOMEM\fR.
 107 .RE
 108
 109 .sp
 110 .ne 2
 111 .na
 112 \fB\fB*if_nameindex()\fR\fR
 113 .ad
 114 .RS 22n
 115 The \fBif_nameindex()\fR function returns an array of \fBif_nameindex\fR
 116 structures, one structure per interface. The \fBif_nameindex\fR structure holds
 117 the information about a single interface and is defined when the
 118 <\fBnet/if.h\fR> header is included:
 119 .sp
 120 .in +2
 121 .nf
 122 struct if_nameindex {
 123     unsigned int   if_index;  /* 1, 2, ... */
 124     char           *if_name;   /* null terminated name: "eri0", ... */
 125 };
 126 .fi
 127 .in -2
 128
 129 The end of the array of structures is indicated by a structure with an
 130 \fBif_index\fR of 0 and an \fBif_name\fR of \fBNULL\fR. The function returns a
 131 null pointer upon an error and sets \fIerrno\fR to the appropriate value. The
 132 memory used for this array of structures along with the interface names pointed
 133 to by the \fBif_name\fR members is obtained dynamically. This memory is freed
 134 by the \fBif_freenameindex()\fR function.
 135 .RE
 136
 137 .sp
 138 .ne 2
 139 .na
 140 \fB\fBif_freenameindex()\fR\fR
 141 .ad
 142 .RS 22n
 143 The \fBif_freenameindex()\fR function frees the dynamic memory that was
 144 allocated by \fBif_nameindex()\fR. The argument to this function must be a
 145 pointer that was returned by \fBif_nameindex()\fR.
 146 .RE
 147
 148 .SH ATTRIBUTES
 149 .sp
 150 .LP
 151 See \fBattributes\fR(5) for descriptions of the following attributes:
 152 .sp
 153
 154 .sp
 155 .TS
 156 box;
 157 c | c
 158 l | l .
 159 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 160 _
 161 Interface Stability     Standard
 162 _
 163 MT-Level        MT-Safe
 164 .TE
 165
 166 .SH SEE ALSO
 167 .sp
 168 .LP
 169 \fBifconfig\fR(8), \fBif_nametoindex\fR(3SOCKET), \fBattributes\fR(5),
 170 \fBstandards\fR(5), \fBif\fR(7P)