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_DGRAM_H__
  20 #define __UNIX_DGRAM_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
  60 /**
  61  * @brief Abstract structure representing a unix domain datagram socket
  62  */
  63 struct unix_msg_ctx;
  64
  65 /**
  66  * @brief Initialize a struct unix_msg_ctx
  67  *
  68  * @param[in] path The socket path
  69  * @param[in] ev_funcs The event callback functions to use
  70  * @param[in] fragment_size Maximum datagram size to send/receive
  71  * @param[in] cookie Random number to identify this context
  72  * @param[in] recv_callback Function called when a message is received
  73  * @param[in] private_data Private pointer for recv_callback
  74  * @param[out] result The new struct unix_msg_ctx
  75  * @return 0 on success, errno on failure
  76  */
  77
  78 int unix_msg_init(const char *path, const struct poll_funcs *ev_funcs,
  79                   size_t fragment_size, uint64_t cookie,
  80                   void (*recv_callback)(struct unix_msg_ctx *ctx,
  81                                         uint8_t *msg, size_t msg_len,
  82                                         void *private_data),
  83                   void *private_data,
  84                   struct unix_msg_ctx **result);
  85
  86 /**
  87  * @brief Send a message
  88  *
  89  * @param[in] ctx The context to send across
  90  * @param[in] dst_sock The destination socket path
  91  * @param[in] iov The message
  92  * @param[in] iovlen The number of iov structs
  93  * @return 0 on success, errno on failure
  94  */
  95
  96 int unix_msg_send(struct unix_msg_ctx *ctx, const char *dst_sock,
  97                   const struct iovec *iov, int iovlen);
  98
  99 /**
 100  * @brief Free a unix_msg_ctx
 101  *
 102  * @param[in] ctx The message context to free
 103  * @return 0 on success, errno on failure (EBUSY)
 104  */
 105 int unix_msg_free(struct unix_msg_ctx *ctx);
 106
 107 #endif