1 /* Licensed under BSD-MIT - see LICENSE file for details */
5 #include <sys/socket.h>
12 * net_client_lookup - look up a network name to connect to.
13 * @hostname: the name to look up
14 * @service: the service to look up
15 * @family: Usually AF_UNSPEC, otherwise AF_INET or AF_INET6.
16 * @socktype: SOCK_DGRAM or SOCK_STREAM.
18 * This will do a synchronous lookup of a given name, returning a linked list
19 * of results, or NULL on error. You should use freeaddrinfo() to free it.
26 * struct addrinfo *addr;
28 * // Get a TCP connection to ccan.ozlabs.org daytime port.
29 * addr = net_client_lookup("ccan.ozlabs.org", "daytime",
30 * AF_UNSPEC, SOCK_STREAM);
32 * errx(1, "Failed to look up daytime at ccan.ozlabs.org");
34 struct addrinfo *net_client_lookup(const char *hostname,
40 * net_connect - connect to a server
41 * @addrinfo: linked list struct addrinfo (usually from net_client_lookup).
43 * This synchronously connects to a server described by @addrinfo, or returns
44 * -1 on error (and sets errno).
49 * fd = net_connect(addr);
51 * err(1, "Failed to connect to ccan.ozlabs.org");
54 int net_connect(const struct addrinfo *addrinfo);
57 * net_connect_async - initiate connect to a server
58 * @addrinfo: linked list struct addrinfo (usually from net_client_lookup).
59 * @pfds: array of two struct pollfd.
61 * This begins connecting to a server described by @addrinfo,
62 * and places the one or two file descriptors into pfds[0] and pfds[1].
63 * It returns a valid file descriptor if connect() returned immediately.
65 * Otherwise it returns -1 and sets errno, most likely EINPROGRESS.
66 * In this case, poll() on pfds and call net_connect_complete().
69 * struct pollfd pfds[2];
71 * fd = net_connect_async(addr, pfds);
72 * if (fd < 0 && errno != EINPROGRESS)
73 * err(1, "Failed to connect to ccan.ozlabs.org");
75 int net_connect_async(const struct addrinfo *addrinfo, struct pollfd *pfds);
78 * net_connect_complete - complete net_connect_async call.
79 * @pfds: array of two struct pollfd handed to net_connect_async.
81 * When poll() reports some activity, this determines whether a connection
82 * has completed. If so, it cleans up and returns the connected fd.
83 * Otherwise, it returns -1, and sets errno (usually EINPROGRESS).
86 * // After net_connect_async.
87 * while (fd < 0 && errno == EINPROGRESS) {
88 * // Wait for activity...
90 * fd = net_connect_complete(pfds);
93 * err(1, "connecting");
94 * printf("Connected on fd %i!\n", fd);
96 int net_connect_complete(struct pollfd *pfds);
99 * net_connect_abort - abort a net_connect_async call.
100 * @pfds: array of two struct pollfd handed to net_connect_async.
102 * Closes the file descriptors.
105 * // After net_connect_async.
106 * if (poll(pfds, 2, 1000) == 0) { // Timeout.
107 * net_connect_abort(pfds);
110 * fd = net_connect_complete(pfds);
112 * err(1, "connecting");
115 void net_connect_abort(struct pollfd *pfds);
118 * net_server_lookup - look up a service name to bind to.
119 * @service: the service to look up
120 * @family: Usually AF_UNSPEC, otherwise AF_INET or AF_INET6.
121 * @socktype: SOCK_DGRAM or SOCK_STREAM.
123 * This will do a synchronous lookup of a given name, returning a linked list
124 * of results, or NULL on error. You should use freeaddrinfo() to free it.
130 * struct addrinfo *addr;
132 * // Get address(es) to bind for our service.
133 * addr = net_server_lookup("8888", AF_UNSPEC, SOCK_STREAM);
135 * errx(1, "Failed to look up 8888 to bind to");
137 struct addrinfo *net_server_lookup(const char *service,
142 * net_bind - create listening socket(s)
143 * @addrinfo: the address(es) to bind to.
144 * @fds: array of two fds.
146 * This will create one (or if necessary) two sockets, mark them
147 * SO_REUSEADDR, bind them to the given address(es), and make them
148 * listen() (if the socket type is SOCK_STREAM or SOCK_SEQPACKET).
150 * Returns -1 (and sets errno) on error, or 1 or 2 depending on how many
154 * int fds[2], i, num_fds;
156 * num_fds = net_bind(addr, fds);
158 * err(1, "Failed to listen on port 8888");
160 * for (i = 0; i < num_fds; i++)
161 * printf(" Got fd %u/%u: %i\n", i, num_fds, fds[i]);
163 int net_bind(const struct addrinfo *addrinfo, int fds[2]);
164 #endif /* CCAN_NET_H */