lib/libc/net/if_indextoname.3

   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 LIBRARY
  37 .Lb libc
  38 .Sh SYNOPSIS
  39 .In sys/types.h
  40 .In sys/socket.h
  41 .In net/if.h
  42 .Ft "unsigned int"
  43 .Fn if_nametoindex "const char *ifname"
  44 .Ft "char *"
  45 .Fn if_indextoname "unsigned int ifindex" "char *ifname"
  46 .Ft "struct if_nameindex *"
  47 .Fn if_nameindex "void"
  48 .Ft void
  49 .Fn if_freenameindex "struct if_nameindex *ptr"
  50 .Sh DESCRIPTION
  51 The
  52 .Fn if_nametoindex
  53 function maps the interface name specified in
  54 .Fa ifname
  55 to its corresponding index.
  56 If the specified interface does not exist, it returns 0.
  57 .Pp
  58 The
  59 .Fn if_indextoname
  60 function maps the interface index specified in
  61 .Fa ifindex
  62 to it corresponding name, which is copied into the
  63 buffer pointed to by
  64 .Fa ifname ,
  65 which must be of at least
  66 .Dv IFNAMSIZ
  67 bytes.
  68 This pointer is also the return value of the function.
  69 If there is no interface corresponding to the specified
  70 index,
  71 .Dv NULL
  72 is returned.
  73 .Pp
  74 The
  75 .Fn if_nameindex
  76 function returns an array of
  77 .Vt if_nameindex
  78 structures, one structure per interface, as
  79 defined in the include file
  80 .In net/if.h .
  81 The
  82 .Vt if_nameindex
  83 structure contains at least the following entries:
  84 .Bd -literal
  85     unsigned int   if_index;  /* 1, 2, ... */
  86     char          *if_name;   /* null terminated name: "lnc0", ... */
  87 .Ed
  88 .Pp
  89 The end of the array of structures is indicated by a structure with an
  90 .Va if_index
  91 of 0 and an
  92 .Va if_name
  93 of
  94 .Dv NULL .
  95 A
  96 .Dv NULL
  97 pointer is returned upon an error.
  98 .Pp
  99 The
 100 .Fn if_freenameindex
 101 function frees the dynamic memory that was
 102 allocated by
 103 .Fn if_nameindex .
 104 .Sh RETURN VALUES
 105 Upon successful completion,
 106 .Fn if_nametoindex
 107 returns the index number of the interface.
 108 If the interface is not found, a value of 0 is returned and
 109 .Va errno
 110 is set to
 111 .Er ENXIO .
 112 A value of 0 is also returned if an error
 113 occurs while retrieving the list of interfaces via
 114 .Xr getifaddrs 3 .
 115 .Pp
 116 Upon successful completion,
 117 .Fn if_indextoname
 118 returns
 119 .Fa ifname .
 120 If the interface is not found, a
 121 .Dv NULL
 122 pointer is returned and
 123 .Va errno
 124 is set to
 125 .Er ENXIO .
 126 A
 127 .Dv NULL
 128 pointer is also returned if an error
 129 occurs while retrieving the list of interfaces via
 130 .Xr getifaddrs 3 .
 131 .Pp
 132 The
 133 .Fn if_nameindex
 134 returns a
 135 .Dv NULL
 136 pointer if an error
 137 occurs while retrieving the list of interfaces via
 138 .Xr getifaddrs 3 ,
 139 or if sufficient memory cannot be allocated.
 140 .Sh SEE ALSO
 141 .Xr getifaddrs 3 ,
 142 .Xr networking 4
 143 .Sh STANDARDS
 144 The
 145 .Fn if_nametoindex ,
 146 .Fn if_indextoname ,
 147 .Fn if_nameindex ,
 148 and
 149 .Fn if_freenameindex
 150 functions conform to
 151 .%T "RFC 2553" .
 152 .Sh HISTORY
 153 The implementation first appeared in BSDi
 154 .Bsx .