Question

An often overlooked function that requires no external library, but basically has no documentation whatsoever.

Answer 1

UPDATE (2010-10-11): The linux man-pages now have documentation of the getaddrinfo_a, you can find it here: http://www.kernel.org/doc/man-pages/online/pages/man3/getaddrinfo_a.3.html

As a disclaimer I should add that I’m quite new to C but not exactly a newbie, so there might be bugs, or bad coding practices, please do correct me (and my grammar sucks too).

I personally didn’t know about it until I came upon this post by Adam Langley, I shall give a few code snippets to illustrate the usage of it and clarify some things that might not be that clear on first use. The benefits of using this is that you get back data readily usable in socket(), listen() and other functions, and if done right you won’t have to worry about ipv4/v6 either.
So to start off with the basics, as taken from the link above (you will need to link against libanl (-lanl)) :
Here is the function prototype:

int getaddrinfo_a(int mode, struct gaicb *list[], int ent,                    struct sigevent *); 

1. The mode is either GAI_WAIT (which is probably not what you want) and GAI_NOWAIT for async lookups
2. The gaicb argument accepts an array of hosts to lookup with the ent argument specifying how many elements the array has
3. The sigevent will be responsible for telling the function how we are to be notified, more on this in a moment

A gaicb struct looks like this:

struct gaicb {     const char *ar_name;     const char *ar_service;     const struct addrinfo *ar_request;     struct addrinfo *ar_result; }; 

If you’re familiar with getaddrinfo, then these fields correspond to them like so:

int getaddrinfo(const char *node, const char *service,                 const struct addrinfo *hints,                 struct addrinfo **res); 

The node is the ar_name field, service is the port, the hints argument corresponds to the ar_request member and the result is stored in the rest.
Now you specify how you want to be notified through the sigevent structure:

struct sigevent {     sigval_t sigev_value;     int sigev_signo;     int sigev_notify;     void (*sigev_notify_function) (sigval_t);     pthread_addr_t *sigev_notify_attributes; }; 

1. You can ignore the notification via setting _sigev_notify_ to SIGEV_NONE
2. You can trigger a signal via setting sigev_notify to SIGEV_SIGNAL and sigev_signo to the desired signal. Note that when using a real-time signal (SIGRTMIN–SIGRTMAX, always use it via the macros and addition SIGRTMIN+2 etc.) you can pass along a pointer or value in the sigev_value.sival_ptr or sigev_value.sival_int member respectivley
3. You can request a callback in a new thread via setting sigev_notify to SIGEV_NONE

So basically if you want to look up a hostname you set ar_name to the host and set everything else to NULL, if you want to connect to a host you set ar_name and ar_service , and if you want to create a server you specify ar_service and the ar_result field. You can of course customize the ar_request member to your hearts content, look at man getaddrinfo for more info.

If you have an event loop with select/poll/epoll/kqueue you might want to use signalfd for convenience. Signalfd creates a file descriptor on which you can use the usuall event polling mechanisms like so:

#define _GNU_SOURCE //yes this will not be so standardish #include <netdb.h> #include <signal.h> #include <sys/signalfd.h>  void signalfd_setup(void) {     int sfd;     sigset_t mask;      sigemptyset(&mask);     sigaddset(&mask, SIGRTMIN);     sigprocmask(SIG_BLOCK, &mask, NULL); //we block the signal     sfd = signalfd(-1, &mask, 0);     //add it to the event queue } void signalfd_read(int fd) {     ssize_t s;     struct signalfd_siginfo fdsi;     struct gaicb *host;      while((s = read(fd, &fdsi, sizeof(struct signalfd_siginfo))) > 0){     if (s != sizeof(struct signalfd_siginfo)) return; //thats bad     host = fdsi.ssi_ptr; //the pointer passed to the sigevent structure             //the result is in the host->ar_result member             create_server(host);     } } void create_server(struct gaicb *host) {     struct addrinfo *rp, *result;     int fd;      result = host->ar_result;     for(rp = result; rp != NULL; rp = rp->ai_next) {         fd = socket(rp->ai_family, rp->ai_socktype, rp->ai_protocol);         bind(fd, rp->ai_addr, rp->ai_addrlen);         listen(fd, SOMAXCONN);         //error checks are missing!          freeaddrinfo(host->ar_request);         freeaddrinfo(result);         //you should free everything you put into the gaicb     } } int main(int argc, char *argv[]) {     struct gaicb *host;     struct addrinfo *hints;     struct sigevent sig;      host = calloc(1, sizeof(struct gaicb));     hints = calloc(1, sizeof(struct addrinfo));      hints->ai_family = AF_UNSPEC; //we dont care if its v4 or v6     hints->ai_socktype = SOCK_STREAM;     hints->ai_flags = AI_PASSIVE;     //every other field is NULL-d by calloc      host->ar_service = '8888'; //the port we will listen on     host->ar_request = hints;      sig.sigev_notify = SIGEV_SIGNAL;     sig.sigev_value.sival_ptr = host;     sig.sigev_signo = SIGRTMIN;      getaddrinfo_a(GAI_NOWAIT, &host, 1, &sig);      signalfd_setup();      //start your event loop     return 0; } 

You can of course use a simple signal handler for this job too, look at man sigaction for more info.