git.ozlabs.org Git - ccan/blob - 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 */