net: add server support.
[ccan] / ccan / net / net.h
1 /* Licensed under BSD-MIT - see LICENSE file for details */
2 #ifndef CCAN_NET_H
3 #define CCAN_NET_H
4 /**
5  * net_client_lookup - look up a network name to connect to.
6  * @hostname: the name to look up
7  * @service: the service to look up
8  * @family: Usually AF_UNSPEC, otherwise AF_INET or AF_INET6.
9  * @socktype: SOCK_DGRAM or SOCK_STREAM.
10  *
11  * This will do a synchronous lookup of a given name, returning a linked list
12  * of results, or NULL on error.  You should use freeaddrinfo() to free it.
13  *
14  * Example:
15  *      #include <sys/types.h>
16  *      #include <sys/socket.h>
17  *      #include <stdio.h>
18  *      #include <netdb.h>
19  *      #include <err.h>
20  *      ...
21  *      struct addrinfo *addr;
22  *
23  *      // Get a TCP connection to ccan.ozlabs.org daytime port.
24  *      addr = net_client_lookup("ccan.ozlabs.org", "daytime",
25  *                               AF_UNSPEC, SOCK_STREAM);
26  *      if (!addr)
27  *              errx(1, "Failed to look up daytime at ccan.ozlabs.org");
28  */
29 struct addrinfo *net_client_lookup(const char *hostname,
30                                    const char *service,
31                                    int family,
32                                    int socktype);
33
34 /**
35  * net_connect - connect to a server
36  * @addrinfo: linked list struct addrinfo (usually from net_client_lookup).
37  *
38  * This synchronously connects to a server described by @addrinfo, or returns
39  * -1 on error (and sets errno).
40  *
41  * Example:
42  *      int fd;
43  *      ...
44  *      fd = net_connect(addr);
45  *      if (fd < 0)
46  *              err(1, "Failed to connect to ccan.ozlabs.org");
47  *      freeaddrinfo(addr);
48  */
49 int net_connect(const struct addrinfo *addrinfo);
50
51 /**
52  * net_server_lookup - look up a service name to bind to.
53  * @service: the service to look up
54  * @family: Usually AF_UNSPEC, otherwise AF_INET or AF_INET6.
55  * @socktype: SOCK_DGRAM or SOCK_STREAM.
56  *
57  * This will do a synchronous lookup of a given name, returning a linked list
58  * of results, or NULL on error.  You should use freeaddrinfo() to free it.
59  *
60  * Example:
61  *      #include <sys/types.h>
62  *      #include <sys/socket.h>
63  *      #include <stdio.h>
64  *      #include <netdb.h>
65  *      #include <err.h>
66  *      ...
67  *      struct addrinfo *addr;
68  *
69  *      // Get address(es) to bind for our service.
70  *      addr = net_server_lookup("8888", AF_UNSPEC, SOCK_STREAM);
71  *      if (!addr)
72  *              errx(1, "Failed to look up 8888 to bind to");
73  */
74 struct addrinfo *net_server_lookup(const char *service,
75                                    int family,
76                                    int socktype);
77
78 /**
79  * net_bind - create listening socket(s)
80  * @addrinfo: the address(es) to bind to.
81  * @fds: array of two fds.
82  *
83  * This will create one (or if necessary) two sockets, mark them
84  * SO_REUSEADDR, bind them to the given address(es), and make them
85  * listen() (if the socket type is SOCK_STREAM or SOCK_SEQPACKET).
86  *
87  * Returns -1 (and sets errno) on error, or 1 or 2 depending on how many
88  * @fds are valid.
89  *
90  * Example:
91  *      int fds[2], i, num_fds;
92  *
93  *      num_fds = net_bind(addr, fds);
94  *      if (num_fds < 0)
95  *              err(1, "Failed to listen on port 8888");
96  *
97  *      for (i = 0; i < num_fds; i++)
98  *              printf(" Got fd %u/%u: %i\n", i, num_fds, fds[i]);
99  */
100 int net_bind(const struct addrinfo *addrinfo, int fds[2]);
101 #endif /* CCAN_NET_H */