2 * Unix SMB/CIFS implementation.
3 * Copyright (C) Volker Lendecke 2013
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.
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.
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/>.
19 #ifndef __UNIX_DGRAM_H__
20 #define __UNIX_DGRAM_H__
23 #include "poll_funcs/poll_funcs.h"
24 #include "system/network.h"
29 * @brief Send large messages over unix domain datagram sockets
31 * A unix_msg_ctx represents a unix domain datagram socket.
33 * Unix domain datagram sockets have some unique properties compared with UDP
36 * - They are reliable, i.e. as long as both sender and receiver are processes
37 * that are alive, nothing is lost.
39 * - They preserve sequencing
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.
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.
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.
61 * @brief Abstract structure representing a unix domain datagram socket
66 * @brief Initialize a struct unix_msg_ctx
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
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
,
84 struct unix_msg_ctx
**result
);
87 * @brief Send a message
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
96 int unix_msg_send(struct unix_msg_ctx
*ctx
, const char *dst_sock
,
97 const struct iovec
*iov
, int iovlen
);
100 * @brief Free a unix_msg_ctx
102 * @param[in] ctx The message context to free
103 * @return 0 on success, errno on failure (EBUSY)
105 int unix_msg_free(struct unix_msg_ctx
*ctx
);