source3/lib/unix_msg/unix_msg.h

   1 /*
   2  * Unix SMB/CIFS implementation.
   3  * Copyright (C) Volker Lendecke 2013
   4  *
   5  * This program is free software; you can redistribute it and/or modify
   6  * it under the terms of the GNU General Public License as published by
   7  * the Free Software Foundation; either version 3 of the License, or
   8  * (at your option) any later version.
   9  *
  10  * This program is distributed in the hope that it will be useful,
  11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13  * GNU General Public License for more details.
  14  *
  15  * You should have received a copy of the GNU General Public License
  16  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  17  */
  18
  19 #ifndef __UNIX_MSG_H__
  20 #define __UNIX_MSG_H__
  21
  22 #include "replace.h"
  23 #include "poll_funcs/poll_funcs.h"
  24 #include "system/network.h"
  25
  26 /**
  27  * @file unix_msg.h
  28  *
  29  * @brief Send large messages over unix domain datagram sockets
  30  *
  31  * A unix_msg_ctx represents a unix domain datagram socket.
  32  *
  33  * Unix domain datagram sockets have some unique properties compared with UDP
  34  * sockets:
  35  *
  36  * - They are reliable, i.e. as long as both sender and receiver are processes
  37  *   that are alive, nothing is lost.
  38  *
  39  * - They preserve sequencing
  40  *
  41  * Based on these two properties, this code implements sending of large
  42  * messages. It aims at being maximally efficient for short, single-datagram
  43  * messages. Ideally, if the receiver queue is not full, sending a message
  44  * should be a single syscall without malloc. Receiving a message should also
  45  * not malloc anything before the data is shipped to the user.
  46  *
  47  * If unix_msg_send meets a full receive buffer, more effort is required: The
  48  * socket behind unix_msg_send is not pollable for POLLOUT, it will always be
  49  * writable: A datagram socket can send anywhere, the full queue is a property
  50  * of of the receiving socket. unix_msg_send creates a new unnamed socket that
  51  * it will connect(2) to the target socket. This unnamed socket is then
  52  * pollable for POLLOUT. The socket will be writable when the destination
  53  * socket's queue is drained sufficiently.
  54  *
  55  * If unix_msg_send is asked to send a message larger than fragment_size, it
  56  * will try sending the message in pieces with proper framing, the receiving
  57  * side will reassemble the messages.
  58  *
  59  * fd-passing is supported.
  60  * Note that by default the fds passed to recv_callback are closed by
  61  * the receive handler in order to avoid fd-leaks. If the provider of
  62  * the recv_callback wants to use a passed file descriptor after the
  63  * callback returns, it must copy the fd away and set the corresponding
  64  * entry in the "fds" array to -1.
  65  */
  66
  67 /**
  68  * @brief Abstract structure representing a unix domain datagram socket
  69  */
  70 struct unix_msg_ctx;
  71
  72 /**
  73  * @brief Initialize a struct unix_msg_ctx
  74  *
  75  * @param[in] path The socket path
  76  * @param[in] ev_funcs The event callback functions to use
  77  * @param[in] fragment_size Maximum datagram size to send/receive
  78  * @param[in] cookie Random number to identify this context
  79  * @param[in] recv_callback Function called when a message is received
  80  * @param[in] private_data Private pointer for recv_callback
  81  * @param[out] result The new struct unix_msg_ctx
  82  * @return 0 on success, errno on failure
  83  */
  84
  85
  86 int unix_msg_init(const struct sockaddr_un *addr,
  87                   const struct poll_funcs *ev_funcs,
  88                   size_t fragment_size, uint64_t cookie,
  89                   void (*recv_callback)(struct unix_msg_ctx *ctx,
  90                                         uint8_t *msg, size_t msg_len,
  91                                         int *fds, size_t num_fds,
  92                                         void *private_data),
  93                   void *private_data,
  94                   struct unix_msg_ctx **result);
  95
  96 /**
  97  * @brief Send a message
  98  *
  99  * @param[in] ctx The context to send across
 100  * @param[in] dst_sock The destination socket path
 101  * @param[in] iov The message
 102  * @param[in] iovlen The number of iov structs
 103  * @param[in] fds - optional fd array
 104  * @param[in] num_fds - fd array size
 105  * @return 0 on success, errno on failure
 106  */
 107
 108 int unix_msg_send(struct unix_msg_ctx *ctx, const struct sockaddr_un *dst,
 109                   const struct iovec *iov, int iovlen,
 110                   const int *fds, size_t num_fds);
 111
 112 /**
 113  * @brief Free a unix_msg_ctx
 114  *
 115  * @param[in] ctx The message context to free
 116  * @return 0 on success, errno on failure (EBUSY)
 117  */
 118 int unix_msg_free(struct unix_msg_ctx *ctx);
 119
 120 #endif