ancillary.h

   1 /***************************************************************************
   2  * libancillary - black magic on Unix domain sockets
   3  * (C) Nicolas George
   4  * ancillary.h - public header
   5  ***************************************************************************/
   6
   7 /*
   8  * Redistribution and use in source and binary forms, with or without
   9  * modification, are permitted provided that the following conditions are met:
  10  *
  11  *  1. Redistributions of source code must retain the above copyright notice,
  12  *     this list of conditions and the following disclaimer.
  13  *  2. Redistributions in binary form must reproduce the above copyright
  14  *     notice, this list of conditions and the following disclaimer in the
  15  *     documentation and/or other materials provided with the distribution.
  16  *  3. The name of the author may not be used to endorse or promote products
  17  *     derived from this software without specific prior written permission.
  18  *
  19  * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR IMPLIED
  20  * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
  21  * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO
  22  * EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  23  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
  24  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
  25  * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
  26  * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
  27  * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
  28  * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  29  */
  30
  31 #ifndef ANCILLARY_H__
  32 #define ANCILLARY_H__
  33
  34 /***************************************************************************
  35  * Start of the readable part.
  36  ***************************************************************************/
  37
  38 #define ANCIL_MAX_N_FDS 960
  39 /*
  40  * Maximum number of fds that can be sent or received using the "esay"
  41  * functions; this is so that all can fit in one page.
  42  */
  43
  44 extern int
  45 ancil_send_fds_with_buffer(int, const int *, unsigned, void *);
  46 /*
  47  * ancil_send_fds_with_buffer(sock, n_fds, fds, buffer)
  48  *
  49  * Sends the file descriptors in the array pointed by fds, of length n_fds
  50  * on the socket sock.
  51  * buffer is a writeable memory area large enough to hold the required data
  52  * structures.
  53  * Returns: -1 and errno in case of error, 0 in case of success.
  54  */
  55
  56 extern int
  57 ancil_recv_fds_with_buffer(int, int *, unsigned, void *);
  58
  59 /*
  60  * ancil_recv_fds_with_buffer(sock, n_fds, fds, buffer)
  61  *
  62  * Receives *n_fds file descriptors into the array pointed by fds
  63  * from the socket sock.
  64  * buffer is a writeable memory area large enough to hold the required data
  65  * structures.
  66  * Returns: -1 and errno in case of error, the actual number of received fd
  67  * in case of success
  68  */
  69
  70
  71 extern int
  72 ancil_recv_fds_with_buffer_ext(int, int *, unsigned, void *, char *headers, int hsize);
  73 /*
  74  * ancil_send_fds_with_buffer_ext(sock, n_fds, fds, buffer, ext)
  75  *
  76  * Sends the file descriptors in the array pointed by fds, of length n_fds
  77  * on the socket sock.
  78  * buffer is a writeable memory area large enough to hold the required data
  79  * structures with also headers info.
  80  * Returns: -1 and errno in case of error, 0 in case of success.
  81  */
  82
  83 #define ANCIL_FD_BUFFER(n) \
  84     struct { \
  85         struct cmsghdr h; \
  86         int fd[n]; \
  87     }
  88 /* ANCIL_FD_BUFFER(n)
  89  *
  90  * A structure type suitable to be used as buffer for n file descriptors.
  91  * Requires <sys/socket.h>.
  92  * Example:
  93  * ANCIL_FD_BUFFER(42) buffer;
  94  * ancil_recv_fds_with_buffer(sock, 42, my_fds, &buffer);
  95  */
  96
  97 extern int
  98 ancil_send_fds(int, const int *, unsigned);
  99 /*
 100  * ancil_send_fds(sock, n_fds, fds)
 101  *
 102  * Sends the file descriptors in the array pointed by fds, of length n_fds
 103  * on the socket sock.
 104  * n_fds must not be greater than ANCIL_MAX_N_FDS.
 105  * Returns: -1 and errno in case of error, 0 in case of success.
 106  */
 107
 108 extern int
 109 ancil_recv_fds(int, int *, unsigned);
 110 /*
 111  * ancil_recv_fds(sock, n_fds, fds)
 112  *
 113  * Receives *n_fds file descriptors into the array pointed by fds
 114  * from the socket sock.
 115  * *n_fds must not be greater than ANCIL_MAX_N_FDS.
 116  * Returns: -1 and errno in case of error, the actual number of received fd
 117  * in case of success.
 118  */
 119
 120
 121 extern int
 122 ancil_send_fd(int, int);
 123 /* ancil_recv_fd(sock, fd);
 124  *
 125  * Sends the file descriptor fd on the socket sock.
 126  * Returns : -1 and errno in case of error, 0 in case of success.
 127  */
 128
 129 extern int
 130 ancil_recv_fd(int, int *);
 131 /* ancil_send_fd(sock, &fd);
 132  *
 133  * Receives the file descriptor fd from the socket sock.
 134  * Returns : -1 and errno in case of error, 0 in case of success.
 135  */
 136
 137 extern int
 138 ancil_recv_fd_ext(int, int *, char *headers, int hsize);
 139 /* ancil_send_fd(sock, &fd, char *headers);
 140  *
 141  * Receives the file descriptor fd and headers data from the socket sock.
 142  * Returns : -1 and errno in case of error, 0 in case of success.
 143  */
 144
 145 #endif /* ANCILLARY_H__ */