usr/src/man/man3socket/if_nametoindex.3socket

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