1 /* 2 * Description: This file contains the implementation for RFC 2553/3493 section Section 4: Interface Identification 3 */ 4 /* 5 * This file contains the implementation for RFC 2553/3493 section Section 4: Interface Identification 6 * The following functions are implemented 7 * lwip_if_indextoname 8 * lwip_if_nametoindex 9 * lwip_if_nameindex 10 * lwip_if_freenameindex 11 * @note: when passing the ifname pointer to the function lwip_if_indextoname: 12 * The ifname argument must point to a buffer of at least IF_NAMESIZE bytes into which the interface 13 * name corresponding to the specified 14 * index is returned. 15 * IF_NAMESIZE is same as IFNAMSIZ and is of 16 bytes including null 16 * 17 */ 18 19 #ifndef LWIP_HDR_IF_H 20 #define LWIP_HDR_IF_H 21 22 #include "lwip/opt.h" 23 24 #if LWIP_SOCKET /* don't build if not configured for use in lwipopts.h */ 25 26 #include "lwip/netif.h" 27 28 #if defined (__cplusplus) && __cplusplus 29 extern "C" { 30 #endif 31 32 #if !LWIP_LITEOS_COMPAT 33 34 /* Keep the size same as general interface length */ 35 #define IF_NAMESIZE IFNAMSIZ 36 37 /** 38 * Structure to store the if_index and if_name for each interface. 39 */ 40 struct if_nameindex { 41 unsigned int if_index; /* 1, 2, ... */ 42 char *if_name; /* null terminated name: "eth0", ... */ 43 }; 44 45 #endif /* !LWIP_LITEOS_COMPAT */ 46 47 #ifdef LWIP_COMPAT_SOCKETS 48 #if LWIP_COMPAT_SOCKETS != 2 49 /* 50 * Func Name: lwip_if_indextoname 51 */ 52 /** 53 * @ingroup Socket_Interfaces 54 * @brief 55 * This function maps an interface index into its corresponding name. 56 * The ifname argument must point to a buffer of at least IF_NAMESIZE/IFNAMSIZ bytes into which the interface 57 * name corresponding to the specified index is returned. 58 * (IF_NAMESIZE is also defined in <if.h> and its value includes a terminating null byte at the end of the 59 * interface name.) This pointer is also the return value of the function. 60 * @param[in] unsigned int ifindex Specifies an interface index for which the name is to be retrieved. 61 * @param[out] char* ifname Specifies the output interface name which is retrieved based on ifindex 62 * 63 * @return 64 * char * ifname: On success \n 65 * NULL : On failure. The errno is set to indicate the error. \n 66 * @par Errors 67 * @li The if_indextoname() function fails in the following conditions: 68 * - <b> [ENXIO] </b>: \n The ifindex is more than the max range /There is no name as per the index specified 69 * - <b> [EFAULT] </b>: \n The ifname is a null pointer 70 * @par POSIX Conformance: 71 * Implementation deviates from RFC 3493, POSIX.1-2001.The following are the exceptions to conformance: 72 * Posix expects errno for scenario If there was a system error (such as running out of memory), if_indextoname 73 * returns NULL and errno would be set to the proper value (e.g., ENOMEM). 74 * Stack do not allocate memory in this function, so ENOMEM is not returned 75 * @note 76 * The caller of this function should ensure that the ifname point to a buffer of at least IF_NAMESIZE/IFNAMSIZ bytes. 77 * If there is no interface corresponding to the specified index, NULL is returned, and errno is set to ENXIO. 78 * Stack only supports ifindex to be max 255 and the index should start from 1 to get a valid name. 79 * @par Related Topics 80 * if_nametoindex() 81 * if_freenameindex() 82 * if_nameindex() 83 */ 84 char *lwip_if_indextoname(unsigned int ifindex, char *ifname); 85 86 /* 87 * Func Name: lwip_if_nametoindex 88 */ 89 /** 90 * @ingroup Socket_Interfaces 91 * @brief 92 * This function maps an interface name into its corresponding index. 93 * The ifname argument must point to a buffer of at least IF_NAMESIZE/IFNAMSIZ bytes which will contain the 94 * interface name. 95 * @param[in] const char *ifname Specifies the interface name for which corresponding interface 96 * index is required. 97 * @return 98 * unsigned int ifindex: On success.The interface index for the interface name mentioned in ifname \n 99 * 0 : On failure. The errno is set to indicate the error. \n 100 * @par Errors 101 * @li The lwip_if_nametoindex() function fails in the following conditions: 102 * - <b> [ENODEV] </b>: \n Could not find the index corresponding to the interface name 103 * - <b> [EFAULT] </b>: \n The ifname is a null pointer. 104 * @par POSIX Conformance: 105 * Implementation deviates from RFC 3493, POSIX.1-2001.The following are the exceptions to conformance: 106 * POSIX expects errno for scenario If there was a system error (such as running out of memory), 107 * if_nametoindex returns 0 and errno would be set to the proper value (e.g., ENOMEM). 108 * Stack does not allocate memory in this function, so ENOMEM is not returned. 109 * @note 110 * The caller of this function should ensure that the ifname point to a buffer of at least 111 * IF_NAMESIZE/IFNAMSIZ bytes. If there is no interface index corresponding to the specified name, 112 * 0 is returned, and errno is set to ENODEV. 113 * 0 is an invalid index. 114 * @par Related Topics 115 * if_indextoname() 116 * if_freenameindex() 117 * if_nameindex() 118 */ 119 unsigned int lwip_if_nametoindex(const char *ifname); 120 121 /* 122 * Func Name: lwip_if_nameindex 123 */ 124 /** 125 * @ingroup Socket_Interfaces 126 * @brief 127 * This function returns an array of if_nameindex structures, one structure per interface. 128 * The if_nameindex structure holds the information about a single interface and is defined as a result of 129 * including the <if.h> header. 130 * The end of the array of structures is indicated by a structure with an if_index of 0 and an if_name of NULL. 131 * The function returns a NULL pointer upon an error, and would set errno to the appropriate value. 132 * The memory used for this array of structures along with the interface names pointed to by the if_name members 133 * is obtained dynamically. 134 * @param[in] void The function does not take any input instead returns all the interfaces in format 135 * if_nameindex structures. 136 * 137 * @return 138 * struct if_nameindex * : On success. The function returns an array of if_nameindex structures, one structure 139 * per interface. \n 140 * NULL : On failure. The errno is set to indicate the error. \n 141 * @par Errors 142 * @li The if_nameindex() function fails in the following conditions: 143 * - <b> [ENOBUFS] </b>: \n Insufficient resources available. For this, the function returns NULL. 144 * @par POSIX Conformance: 145 * Implementation conforms to POSIX.1-2001, POSIX.1-2008, RFC 3493. 146 * @note 147 * The end of the array of structures is indicated by a structure with an if_index of 0 and an if_name of NULL. 148 * The function returns a NULL pointer upon an error, and would set errno to the appropriate value. 149 * @par Related Topics 150 * if_indextoname() 151 * if_nametoindex() 152 * if_freenameindex() 153 */ 154 struct if_nameindex *lwip_if_nameindex(void); 155 156 /* 157 * Func Name: lwip_if_freenameindex 158 */ 159 /** 160 * @ingroup Socket_Interfaces 161 * @brief 162 * This function frees the dynamic memory that was allocated by if_nameindex(). 163 * The argument to this function must be a pointer that was returned by if_nameindex(). 164 * @param[in] struct if_nameindex *ptr The argument to this function must be a pointer that was returned by 165 * lwip_if_nameindex() 166 * 167 * @return 168 * void : On success.\n 169 * void : On failure. The errno is not set \n 170 * @par POSIX Conformance: 171 * Implementation conforms to POSIX.1-2001, POSIX.1-2008, RFC 3493. 172 * @par Related Topics 173 * if_indextoname() 174 * if_nametoindex() 175 * if_nameindex() 176 */ 177 void lwip_if_freenameindex(struct if_nameindex *ptr); 178 179 /* @ingroup socket */ 180 #define if_indextoname(ifindex, ifname) lwip_if_indextoname(ifindex, ifname) 181 /* @ingroup socket */ 182 #define if_nametoindex(ifname) lwip_if_nametoindex(ifname) 183 #define if_nameindex(void) lwip_if_nameindex(void) 184 #define if_freenameindex(ptr) lwip_if_freenameindex(ptr) 185 #else 186 /* @ingroup socket */ 187 #define lwip_if_indextoname(ifindex, ifname) if_indextoname(ifindex, ifname) 188 /* @ingroup socket */ 189 #define lwip_if_nametoindex(ifname) if_nametoindex(ifname) 190 #define lwip_if_nameindex(void) if_nameindex(void) 191 #define lwip_if_freenameindex(ptr) if_freenameindex(ptr) 192 #endif /* LWIP_COMPAT_SOCKETS == 2 */ 193 #endif /* LWIP_COMPAT_SOCKETS */ 194 195 #if defined (__cplusplus) && __cplusplus 196 } 197 #endif 198 199 #endif /* LWIP_SOCKET */ 200 201 #endif /* !LWIP_HDR_IF_H */ 202 203