1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/os/ossrv/genericopenlibs/openenvcore/include/net/if.dosc Fri Jun 15 03:10:57 2012 +0200
1.3 @@ -0,0 +1,601 @@
1.4 +/** @file ../include/net/if.h
1.5 +@internalComponent
1.6 +*/
1.7 +
1.8 +
1.9 +/** @def IF_NAMESIZE
1.10 +
1.11 +Length of interface external name, including terminating '\\0'.
1.12 +Limitation: IAP names in P.I.P.S. are restricted to 49 bytes in ASCII. For names in languages with a multi-byte character set,
1.13 +you can go upto 24 characters for 2-byte and 16 characters for 3-byte representations.
1.14 +All lengths are excluding the terminal NULL character.
1.15 +
1.16 +@publishedAll
1.17 +@externallyDefinedApi
1.18 +*/
1.19 +
1.20 +/** @fn if_freenameindex(struct if_nameindex *ptr)
1.21 +@param ptr
1.22 +
1.23 +Refer to if_nametoindex() for the documentation
1.24 +
1.25 +
1.26 +
1.27 +
1.28 +@publishedAll
1.29 +@externallyDefinedApi
1.30 +*/
1.31 +
1.32 +
1.33 +
1.34 +/** @fn if_nameindex(void)
1.35 +
1.36 +Refer to if_nametoindex() for the documentation
1.37 +
1.38 +
1.39 +
1.40 +
1.41 +@publishedAll
1.42 +@externallyDefinedApi
1.43 +*/
1.44 +
1.45 +
1.46 +
1.47 +/** @fn if_indextoname(unsigned int ifindex, char *ifname)
1.48 +@param ifindex
1.49 +@param ifname
1.50 +
1.51 +Refer to if_nametoindex() for the documentation
1.52 +
1.53 +
1.54 +
1.55 +
1.56 +@publishedAll
1.57 +@externallyDefinedApi
1.58 +*/
1.59 +
1.60 +
1.61 +/** @fn if_nametoindex(const char *ifname)
1.62 +@param ifname
1.63 +
1.64 +Note: This description also covers the following functions -
1.65 + if_indextoname() if_nameindex() if_freenameindex()
1.66 +
1.67 +@return Upon successful completion, if_nametoindex returns the index number of the interface.
1.68 +If the interface is not found, a value of 0 is returned and errno is set to ENXIO. Upon successful completion, if_indextoname returns ifname. If the interface is not found, a NULL pointer is returned and errno is set to ENXIO. The if_nameindex returns a NULL pointer if sufficient memory cannot be allocated.
1.69 +
1.70 + The if_nametoindex function maps the interface name specified in ifname to its corresponding index.
1.71 +If the specified interface does not exist, it returns 0.
1.72 +
1.73 + The if_indextoname function maps the interface index specified in ifindex to it corresponding name, which is copied into the
1.74 +buffer pointed to by ifname, which must be of at least IFNAMSIZ bytes.
1.75 +This pointer is also the return value of the function.
1.76 +If there is no interface corresponding to the specified
1.77 +index, NULL is returned.
1.78 +
1.79 +@code
1.80 + The if_nameindex function returns an array of if_nameindex structures, one structure per interface, as defined in the include
1.81 + file #include <net/if.h>;
1.82 + The if_nameindex structure contains at least the following entries:
1.83 + unsigned int if_index; /* 1, 2, ... */
1.84 + char *if_name; /* null terminated name: "le0", ... */
1.85 +@endcode
1.86 +
1.87 + The end of the array of structures is indicated by a structure with an if_index of 0 and an if_name of NULL. A NULL pointer is returned upon an error.
1.88 +
1.89 + The if_freenameindex function frees the dynamic memory that was
1.90 +allocated by if_nameindex.
1.91 +
1.92 +
1.93 +
1.94 +
1.95 +
1.96 +
1.97 +
1.98 +@publishedAll
1.99 +@externallyDefinedApi
1.100 +*/
1.101 +
1.102 +
1.103 +
1.104 +/** @struct if_nameindex
1.105 +
1.106 +Includes the following members,
1.107 +
1.108 +@publishedAll
1.109 +@externallyDefinedApi
1.110 +*/
1.111 +
1.112 +/** @var if_nameindex::if_index
1.113 +
1.114 +Numeric index of the interface.
1.115 +
1.116 +*/
1.117 +
1.118 +/** @var if_nameindex::if_name
1.119 +
1.120 +Null-terminated name of the interface.
1.121 +
1.122 +*/
1.123 +
1.124 +/** @struct if_clonereq
1.125 +
1.126 +Structure used to query names of interface cloners.
1.127 +
1.128 +@publishedAll
1.129 +@released
1.130 +*/
1.131 +
1.132 +/** @var if_clonereq::ifcr_total
1.133 +
1.134 +total cloners (out)
1.135 +
1.136 +*/
1.137 +
1.138 +/** @var if_clonereq::ifcr_count
1.139 +
1.140 +room for this many in user buffer
1.141 +
1.142 +*/
1.143 +
1.144 +/** @var if_clonereq::ifcr_buffer
1.145 +
1.146 +buffer for cloner names
1.147 +
1.148 +*/
1.149 +
1.150 +/** @struct if_data
1.151 +
1.152 +Structure describing information about an interface which may be of interest to management entities.
1.153 +
1.154 +@publishedAll
1.155 +@released
1.156 +*/
1.157 +
1.158 +/** @var if_data::ifi_type
1.159 +
1.160 +generic interface information.
1.161 +ethernet, tokenring, etc
1.162 +
1.163 +*/
1.164 +
1.165 +/** @var if_data::ifi_physical
1.166 +
1.167 +generic interface information
1.168 +e.g., AUI, Thinnet, 10base-T, etc
1.169 +
1.170 +*/
1.171 +
1.172 +/** @var if_data::ifi_addrlen
1.173 +
1.174 +generic interface information
1.175 +media address length
1.176 +
1.177 +*/
1.178 +
1.179 +/** @var if_data::ifi_hdrlen
1.180 +
1.181 +generic interface information
1.182 +media header length
1.183 +
1.184 +*/
1.185 +
1.186 +/** @var if_data::ifi_link_state
1.187 +
1.188 +generic interface information
1.189 +current link state
1.190 +
1.191 +*/
1.192 +
1.193 +/** @var if_data::ifi_recvquota
1.194 +
1.195 +generic interface information
1.196 +polling quota for receive intrs
1.197 +
1.198 +*/
1.199 +
1.200 +/** @var if_data::ifi_xmitquota
1.201 +
1.202 +generic interface information
1.203 +polling quota for xmit intrs
1.204 +
1.205 +*/
1.206 +
1.207 +/** @var if_data::ifi_datalen
1.208 +
1.209 +generic interface information
1.210 +length of this data struct
1.211 +
1.212 +*/
1.213 +
1.214 +/** @var if_data::ifi_mtu
1.215 +
1.216 +generic interface information
1.217 +maximum transmission unit
1.218 +
1.219 +*/
1.220 +
1.221 +/** @var if_data::ifi_metric
1.222 +
1.223 +generic interface information
1.224 +routing metric (external only)
1.225 +
1.226 +*/
1.227 +
1.228 +/** @var if_data::ifi_baudrate
1.229 +
1.230 +generic interface information
1.231 +linespeed
1.232 +
1.233 +*/
1.234 +
1.235 +/** @var if_data::ifi_ipackets
1.236 +
1.237 +volatile statistics.
1.238 +packets received on interface
1.239 +
1.240 +*/
1.241 +/** @var if_data::ifi_ierrors
1.242 +
1.243 +volatile statistics.
1.244 +input errors on interface
1.245 +
1.246 +*/
1.247 +
1.248 +/** @var if_data::ifi_opackets
1.249 +
1.250 +volatile statistics.
1.251 +packets sent on interface.
1.252 +
1.253 +*/
1.254 +
1.255 +/** @var if_data::ifi_oerrors
1.256 +
1.257 +volatile statistics.
1.258 +output errors on interface.
1.259 +
1.260 +*/
1.261 +
1.262 +/** @var if_data::ifi_collisions
1.263 +
1.264 +volatile statistics.
1.265 +collisions on csma interfaces.
1.266 +
1.267 +*/
1.268 +
1.269 +/** @var if_data::ifi_ibytes
1.270 +
1.271 +volatile statistics.
1.272 +total number of octets received.
1.273 +
1.274 +*/
1.275 +
1.276 +/** @var if_data::ifi_obytes
1.277 +
1.278 +volatile statistics.
1.279 +total number of octets sent.
1.280 +
1.281 +*/
1.282 +
1.283 +/** @var if_data::ifi_imcasts
1.284 +
1.285 +volatile statistics.
1.286 +packets received via multicast.
1.287 +
1.288 +*/
1.289 +
1.290 +/** @var if_data::ifi_omcasts
1.291 +
1.292 +volatile statistics.
1.293 +packets sent via multicast
1.294 +
1.295 +*/
1.296 +
1.297 +/** @var if_data::ifi_iqdrops
1.298 +
1.299 +volatile statistics.
1.300 +dropped on input, this interface.
1.301 +
1.302 +*/
1.303 +
1.304 +/** @var if_data::ifi_noproto
1.305 +
1.306 +volatile statistics.
1.307 +destined for unsupported protocol.
1.308 +
1.309 +*/
1.310 +
1.311 +/** @var if_data::ifi_hwassist
1.312 +
1.313 +volatile statistics.
1.314 +HW offload capabilities
1.315 +
1.316 +*/
1.317 +
1.318 +/** @var if_data::ifi_epoch
1.319 +
1.320 +volatile statistics.
1.321 +uptime at attach or stat reset.
1.322 +
1.323 +*/
1.324 +
1.325 +/** @var if_data::ifi_timepad
1.326 +
1.327 +volatile statistics.
1.328 +time_t is int, not long on alpha.
1.329 +
1.330 +*/
1.331 +
1.332 +/** @var if_data::ifi_lastchange
1.333 +
1.334 +volatile statistics.
1.335 +time of last administrative change
1.336 +
1.337 +*/
1.338 +
1.339 +/** @struct if_msghdr
1.340 +
1.341 +Message format for use in obtaining information about interfaces from getkerninfo and the routing socket
1.342 +
1.343 +@publishedAll
1.344 +@released
1.345 +*/
1.346 +
1.347 +/** @struct ifa_msghdr
1.348 +
1.349 +Message format for use in obtaining information about interface addresses from getkerninfo and the routing socket
1.350 +
1.351 +@publishedAll
1.352 +@released
1.353 +*/
1.354 +
1.355 +/** @var ifa_msghdr::ifam_msglen
1.356 +
1.357 +to skip over non-understood messages
1.358 +
1.359 +*/
1.360 +
1.361 +/** @var ifa_msghdr::ifam_version
1.362 +
1.363 +future binary compatibility
1.364 +
1.365 +*/
1.366 +
1.367 +/** @var ifa_msghdr::ifam_type
1.368 +
1.369 +message type
1.370 +
1.371 +*/
1.372 +
1.373 +/** @var ifa_msghdr::ifam_addrs
1.374 +
1.375 +like rtm_addrs
1.376 +
1.377 +*/
1.378 +
1.379 +/** @var ifa_msghdr::ifam_flags
1.380 +
1.381 +value of ifa_flags
1.382 +
1.383 +*/
1.384 +
1.385 +/** @var ifa_msghdr::ifam_index
1.386 +
1.387 +index for associated ifp
1.388 +
1.389 +*/
1.390 +
1.391 +/** @var ifa_msghdr::ifam_metric
1.392 +
1.393 +index for associated ifp
1.394 +
1.395 +*/
1.396 +
1.397 +/** @struct ifma_msghdr
1.398 +
1.399 +Message format for use in obtaining information about multicast addresses from the routing socket
1.400 +
1.401 +@publishedAll
1.402 +@released
1.403 +*/
1.404 +
1.405 +/** @var ifma_msghdr::ifmam_msglen
1.406 +
1.407 +to skip over non-understood messages
1.408 +
1.409 +*/
1.410 +
1.411 +/** @var ifma_msghdr::ifmam_version
1.412 +
1.413 +future binary compatibility
1.414 +
1.415 +*/
1.416 +
1.417 +/** @var ifma_msghdr::ifmam_type
1.418 +
1.419 +message type
1.420 +
1.421 +*/
1.422 +
1.423 +/** @var ifma_msghdr::ifmam_addrs
1.424 +
1.425 +like rtm_addrs
1.426 +
1.427 +*/
1.428 +
1.429 +/** @var ifma_msghdr::ifmam_flags
1.430 +
1.431 +value of ifa_flags
1.432 +
1.433 +*/
1.434 +
1.435 +/** @var ifma_msghdr::ifmam_index
1.436 +
1.437 +index for associated ifp
1.438 +
1.439 +*/
1.440 +
1.441 +
1.442 +/** @struct if_announcemsghdr
1.443 +
1.444 +Message format announcing the arrival or departure of a network interface.
1.445 +
1.446 +@publishedAll
1.447 +@released
1.448 +*/
1.449 +
1.450 +/** @var if_announcemsghdr::ifan_msglen
1.451 +
1.452 +to skip over non-understood messages
1.453 +
1.454 +*/
1.455 +
1.456 +/** @var if_announcemsghdr::ifan_version
1.457 +
1.458 +future binary compatibility
1.459 +
1.460 +*/
1.461 +
1.462 +/** @var if_announcemsghdr::ifan_type
1.463 +
1.464 +message type
1.465 +
1.466 +*/
1.467 +
1.468 +/** @var if_announcemsghdr::ifan_index
1.469 +
1.470 +index for associated ifp
1.471 +
1.472 +*/
1.473 +
1.474 +/** @var if_announcemsghdr::ifan_name
1.475 +
1.476 +if name, e.g. "en0"
1.477 +
1.478 +*/
1.479 +
1.480 +/** @var if_announcemsghdr::ifan_what
1.481 +
1.482 +what type of announcement
1.483 +
1.484 +*/
1.485 +
1.486 +
1.487 +/** @struct ifreq
1.488 +
1.489 +Interface request structure used for socket ioctl's.
1.490 +All interface ioctl's must have parameter definitions which begin with ifr_name. The remainder may be interface specific.
1.491 +
1.492 +@publishedAll
1.493 +@released
1.494 +*/
1.495 +
1.496 +/** @struct ifconf
1.497 +
1.498 +Structure used in SIOCGIFCONF request.
1.499 +Used to retrieve interface configuration for machine (useful for programs which must know all networks accessible).
1.500 +
1.501 +@publishedAll
1.502 +@released
1.503 +*/
1.504 +
1.505 +
1.506 +/** @struct if_laddrreq
1.507 +
1.508 +Structure for SIOC[AGD]LIFADDR
1.509 +
1.510 +@publishedAll
1.511 +@released
1.512 +*/
1.513 +
1.514 +
1.515 +/** @fn int setdefaultif( const struct ifreq* ifrequest )
1.516 +@param ifrequest
1.517 +
1.518 +@return The setdefaultif returns 0 on success and -1 on failure.
1.519 +Specifically, if the interface is not found, -1 is returned and errno is set to ENOENT.
1.520 +
1.521 +The setdefaultif function can be used to set (or remove) a default network interface (either IAP or SNAP) for the application.
1.522 +This default interface, if set, will be used by all the further socket related function calls (connect, send, write etc)
1.523 +and all the host resolver function calls (getaddrinfo, getnameinfo, gethostbyname, getaddrbyname etc).
1.524 +
1.525 +If there is a default interface set using setdefaultif and if there is a separate interface set on a socket
1.526 +using the ioctl system call, network operations on that socket will not use the default one,
1.527 +but the socket specific interface.
1.528 +
1.529 +To remove the default interace, pass NULL as the argument.
1.530 +
1.531 +To set an IAP name as the default interface, the 'ifr_name' member of the 'ifreq' structure must be filled with
1.532 +the IAP name to be set. Unicode IAP names can also be set by converting them to UTF8 format before passing them to
1.533 +this API. See the example below:
1.534 +
1.535 +@code
1.536 +#include <stdio.h>
1.537 +#include <string.h>
1.538 +#include <net/if.h>
1.539 +
1.540 +int main()
1.541 + {
1.542 + struct ifreq ifReq;
1.543 + int ret;
1.544 +
1.545 + /* Set the default interface using IAP name */
1.546 + strcpy( ifReq.ifr_name, "Example Interface Name" );
1.547 + ret = setdefaultif( &ifReq );
1.548 + if( ret == -1 )
1.549 + printf( "Setting default interface failed with errno = %d", errno );
1.550 +
1.551 + /* Perform network operations */
1.552 + /* ... */
1.553 +
1.554 + /* Remove the default interface */
1.555 + ret = setdefaultif( NULL );
1.556 + if( ret == -1 )
1.557 + printf( "Removing default interface failed with errno = %d", errno );
1.558 +
1.559 + return 0;
1.560 + }
1.561 +@endcode
1.562 +
1.563 +To set a SNAP id as the default interface, the 'ifr_name' member of the 'ifreq' structure must be an empty string.
1.564 +In this case, the 'snap_id' member of the 'ifr_ifru' union in the parameter should contain the SNAP id to be set.
1.565 +It is recommended to zero initialize the 'ifreq' structure in this case. See the example below.
1.566 +
1.567 +@code
1.568 +#include <stdio.h>
1.569 +#include <string.h>
1.570 +#include <net/if.h>
1.571 +
1.572 +int main()
1.573 + {
1.574 + struct ifreq ifReq;
1.575 + int ret;
1.576 + unsigned int snapId = /* Get the SNAP id to be set from the application settings */
1.577 +
1.578 + /* Set the default interface using SNAP id */
1.579 +
1.580 + /* memset the ifreq to make sure that the interface name is an empty string */
1.581 + memset(&ifReq, 0, sizeof(struct ifreq));
1.582 + ifReq.ifr_ifru.snap_id = snapId;
1.583 +
1.584 + ret = setdefaultif( &ifReq );
1.585 + if( ret == -1 )
1.586 + printf( "Setting default interface failed with errno = %d", errno );
1.587 +
1.588 + /* Perform network operations */
1.589 + /* ... */
1.590 +
1.591 + /* Remove the default interface */
1.592 + ret = setdefaultif( NULL );
1.593 + if( ret == -1 )
1.594 + printf( "Removing default interface failed with errno = %d", errno );
1.595 +
1.596 + return 0;
1.597 + }
1.598 +@endcode
1.599 +
1.600 +The setdefaultif is not guaranteed to be thread safe.
1.601 +
1.602 +@publishedAll
1.603 +@released
1.604 +*/