ip46.html (6923B)
1 <html> 2 <head> 3 <meta name="viewport" content="width=device-width, initial-scale=1.0" /> 4 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> 5 <meta http-equiv="Content-Language" content="en" /> 6 <title>skalibs: the ip46 library interface</title> 7 <meta name="Description" content="skalibs: the ip46 library interface" /> 8 <meta name="Keywords" content="skalibs c unix ip46 library libstddjb" /> 9 <!-- <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" /> --> 10 </head> 11 <body> 12 13 <p> 14 <a href="index.html">libstddjb</a><br /> 15 <a href="../libskarnet.html">libskarnet</a><br /> 16 <a href="../index.html">skalibs</a><br /> 17 <a href="//skarnet.org/software/">Software</a><br /> 18 <a href="//skarnet.org/">skarnet.org</a> 19 </p> 20 21 <h1> The <tt>ip46</tt> library interface </h1> 22 23 <p> 24 The following functions and structures are declared in the <tt>skalibs/ip46.h</tt> header, 25 and implemented in the <tt>libskarnet.a</tt> or <tt>libskarnet.so</tt> library. 26 </p> 27 28 <h2> General information </h2> 29 30 <p> 31 <tt>ip46</tt> is a set of macros and functions to support both IPv4 32 and IPv6 network operations in an abstracted way. 33 </p> 34 35 <p> 36 If skalibs has been built with the <a href="../flags.html#noipv6">--disable-ipv6</a> 37 configure option, or it detects at build time than the target does not support IPv6, then 38 <tt>ip46</tt> structures and functions will be directly aliased to their 39 IPv4 implementations with no overhead at all. 40 </p> 41 42 <h2> Data structures </h2> 43 44 <p> 45 An <tt>ip46full_t</tt> is a structure that contains either an IPv4 or an IPv6 46 address. 47 If <em>a</em> is an <tt>ip46full_t</tt>, then: 48 </p> 49 50 <ul> 51 <li> ip46_is6(&<em>a</em>) is 1 if <em>a</em> is 52 IPv6 and 0 otherwise. </li> 53 <li> <em>a</em>.ip points to 16 (if IPv6) or 4 (if IPv4) bytes containing 54 the address, in network byte order. </li> 55 </ul> 56 57 <p> 58 If skalibs has been build with IPv6 support, an <tt>ip46_t</tt> is 59 the same type as an <tt>ip46full_t</tt>. Otherwise, an <tt>ip46_t</tt> 60 is a structure that just contains an IPv4 address. 61 </p> 62 63 <h2> Functions </h2> 64 65 <p> 66 <code> int ip46_from_ip4 (ip46_t *a, char const *ip) </code> <br /> 67 Stores the IPv4 pointed to by <em>ip</em> into *<em>a</em>. Returns 1. 68 </p> 69 70 <p> 71 <code> int ip46_from_ip6 (ip46_t *a, char const *ip) </code> <br /> 72 Stores the IPv6 pointed to by <em>ip</em> into *<em>a</em>. Returns 1, 73 except if IPv6 is unavailable, in which case it returns 0 ENOSYS. 74 </p> 75 76 <p> 77 <code> size_t ip46_fmt (char *s, ip46_t const *a) </code> <br /> 78 Formats the address in *<em>a</em> into the string <em>s</em>, which 79 must be preallocated. Returns the number of bytes written. The address 80 will be accordingly formatted as IPv4 or IPv6. 81 </p> 82 83 <p> 84 <code> size_t ip46_scan (char const *s, ip46_t *a) </code> <br /> 85 Scans the string <em>s</em> for an IPv4 or IPv6 address. If it finds 86 one, writes it into *<em>a</em> and returns the number of bytes read. 87 If it cannot, returns 0. 88 </p> 89 90 <p> 91 <code> size_t ip46_scanlist (ip46_t *list, size_t max, char const *s, size_t *n) </code> <br /> 92 Scans the string <em>s</em> for a list of comma-, semicolon-, space-, tab- or 93 newline-separated IPv4 or IPv6 addresses, up to a maximum of <em>max</em>. It 94 stores them into the (preallocated) ip46_t array pointed to by <em>list</em>. 95 It returns the number of bytes read (0 if <em>s</em> does not contain a valid 96 IP list at all), and stores the number of found and scanned addresses into *<em>n</em>. 97 </p> 98 99 <p> 100 <code> int socket_connect46 (int fd, ip46_t *a, uint16_t port) </code> <br /> 101 Connects the socket <em>fd</em> to address *<em>a</em> and port <em>port</em>. 102 Returns 0 in case of success, and -1 (and sets errno) in case of failure. 103 </p> 104 105 <p> 106 <code> int socket_bind46 (int fd, ip46_t *a, uint16_t port) </code> <br /> 107 Binds the socket <em>fd</em> to address *<em>a</em> and port <em>port</em>. 108 Returns 0 in case of success, and -1 (and sets errno) in case of failure. 109 </p> 110 111 <p> 112 <code> int socket_bind46_reuse (int fd, ip46_t *a, uint16_t port) </code> <br /> 113 Same as the previous function, with the SO_REUSEADDR option. 114 </p> 115 116 <p> 117 <code> int socket_deadlineconnstamp46 (int fd, ip46_t const *a, uint16_t port, tain const *deadline, tain *stamp) </code> <br /> 118 Attempts to synchronously connect the socket <em>fd</em> to address a<em>a</em> 119 and port <em>port</em>. Returns 1 if it succeeds and 0 (and sets errno) 120 if it fails. <em>stamp</em> must contain an accurate enough 121 timestamp, and is updated when the function returns. If the connection is 122 still pending by <em>deadline</em>, then the attempt stops and the function 123 returns 0 ETIMEDOUT. 124 </p> 125 126 <p> 127 <code> ssize_t socket_recv46 (int fd, char *s, size_t len, ip46_t *a, uint16_t *port) </code> <br /> 128 Reads a datagram from socket <em>fd</em>. The message is stored into buffer <em>s</em> 129 of max length <em>len</em>, and stores the sender information into address *<em>a</em> 130 and port *<em>port</em>. Returns the length of the read datagram, or -1 if it fails. 131 </p> 132 133 <p> 134 <code> ssize_t socket_send46 (int fd, char const *s, size_t len, ip46_t const *a, uint16_t port) </code> <br /> 135 Writes a datagram to socket <em>fd</em>. The message is read from buffer <em>s</em> 136 of length <em>len</em>, and the recipient information is address *<em>a</em> 137 and port <em>port</em>. Returns the number of written bytes, or -1 if it fails. 138 </p> 139 140 <p> 141 <code> int socket_local46 (int fd, ip46_t *a, uint16_t *port) </code> <br /> 142 Gets the local information about bound socket <em>fd</em>: the local IP 143 address is stored into *<em>a</em> and the local port into *<em>port</em>. 144 Returns 0 in case of success, and -1 (and sets errno) in case of failure. 145 </p> 146 147 <p> 148 <code> int socket_remote46 (int fd, ip46_t *a, uint16_t *port) </code> <br /> 149 Gets the peer information about connected socket <em>fd</em>: the remote IP 150 address is stored into *<em>a</em> and the remote port into *<em>port</em>. 151 Returns 0 in case of success, and -1 (and sets errno) in case of failure. 152 </p> 153 154 <p> 155 <code> ssize_t socket_recvnb46 (int fd, char *s, size_t len, ip46_t *a, uint16_t *port, 156 tain const *deadline, tain *stamp) </code> <br /> 157 Like <tt>socket_recv46</tt>, except that the function blocks until a datagram 158 is received. *<em>stamp</em> must be an accurate enough approximation of the 159 current time, and is updated when the function returns. If no datagram has 160 arrived by absolute date *<em>deadline</em>, the function returns -1 ETIMEOUT. 161 </p> 162 163 <p> 164 <code> ssize_t socket_sendnb46 (int fd, char const *s, size_t len, ip46_t const *a, uint16_t port, 165 tain const *deadline, tain *stamp) </code> <br /> 166 Like <tt>socket_send46</tt>, except that the function blocks until a datagram 167 has been effectively sent. *<em>stamp</em> must be an accurate enough approximation of the 168 current time, and is updated when the function returns. If the message still has 169 not been sent by absolute date *<em>deadline</em>, the function returns -1 ETIMEOUT. 170 </p> 171 172 </body> 173 </html>