2 Unix SMB/CIFS implementation.
4 Copyright (C) Stefan Metzmacher 2009
6 ** NOTE! The following LGPL license applies to the tsocket
7 ** library. This does NOT imply that all of Samba is released
10 This library is free software; you can redistribute it and/or
11 modify it under the terms of the GNU Lesser General Public
12 License as published by the Free Software Foundation; either
13 version 3 of the License, or (at your option) any later version.
15 This library is distributed in the hope that it will be useful,
16 but WITHOUT ANY WARRANTY; without even the implied warranty of
17 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
18 Lesser General Public License for more details.
20 You should have received a copy of the GNU Lesser General Public
21 License along with this library; if not, see <http://www.gnu.org/licenses/>.
29 struct samba_sockaddr
;
30 struct tsocket_address
;
31 struct tdgram_context
;
32 struct tstream_context
;
38 * The tsocket abstraction is an API ...
42 * @defgroup tsocket The tsocket API
44 * The tsocket abstraction is split into two different kinds of
45 * communication interfaces.
47 * There's the "tstream_context" interface with abstracts the communication
48 * through a bidirectional byte stream between two endpoints.
50 * And there's the "tdgram_context" interface with abstracts datagram based
51 * communication between any number of endpoints.
53 * Both interfaces share the "tsocket_address" abstraction for endpoint
56 * The whole library is based on the talloc(3) and 'tevent' libraries and
57 * provides "tevent_req" based "foo_send()"/"foo_recv()" functions pairs for
58 * all abstracted methods that need to be async.
60 * @section vsock Virtual Sockets
62 * The abstracted layout of tdgram_context and tstream_context allow
63 * implementations around virtual sockets for encrypted tunnels (like TLS,
64 * SASL or GSSAPI) or named pipes over smb.
66 * @section npa Named Pipe Auth (NPA) Sockets
68 * Samba has an implementation to abstract named pipes over smb (within the
69 * server side). See libcli/named_pipe_auth/npa_tstream.[ch] for the core code.
70 * The current callers are located in source4/ntvfs/ipc/vfs_ipc.c and
71 * source4/rpc_server/service_rpc.c for the users.
75 * @defgroup tsocket_address The tsocket_address abstraction
78 * The tsocket_address represents an socket endpoint genericly.
79 * As it's like an abstract class it has no specific constructor.
80 * The specific constructors are descripted in later sections.
86 * @brief Get a string representation of the endpoint.
88 * This function creates a string representation of the endpoint for debugging.
89 * The output will look as followed:
93 * ipv4:192.168.1.1:143
95 * Callers should not try to parse the string! The should use additional methods
96 * of the specific tsocket_address implemention to get more details.
98 * @param[in] addr The address to convert.
100 * @param[in] mem_ctx The talloc memory context to allocate the memory.
102 * @return The address as a string representation, NULL on error.
104 * @see tsocket_address_is_inet()
105 * @see tsocket_address_inet_addr_string()
106 * @see tsocket_address_inet_port()
108 char *tsocket_address_string(const struct tsocket_address
*addr
,
109 TALLOC_CTX
*mem_ctx
);
113 * @brief This creates a copy of a tsocket_address.
115 * This is useful when before doing modifications to a socket via additional
116 * methods of the specific tsocket_address implementation.
118 * @param[in] addr The address to create the copy from.
120 * @param[in] mem_ctx The talloc memory context to use.
122 * @return A newly allocated copy of addr (tsocket_address *), NULL
125 struct tsocket_address
*tsocket_address_copy(const struct tsocket_address
*addr
,
126 TALLOC_CTX
*mem_ctx
);
128 struct tsocket_address
*_tsocket_address_copy(const struct tsocket_address
*addr
,
130 const char *location
);
132 #define tsocket_address_copy(addr, mem_ctx) \
133 _tsocket_address_copy(addr, mem_ctx, __location__)
141 * @defgroup tdgram_context The tdgram_context abstraction
144 * The tdgram_context is like an abstract class for datagram based sockets. The
145 * interface provides async 'tevent_req' based functions on top functionality
146 * is similar to the recvfrom(2)/sendto(2)/close(2) syscalls.
148 * @note You can always use talloc_free(tdgram) to cleanup the resources
149 * of the tdgram_context on a fatal error.
154 * @brief Ask for next available datagram on the abstracted tdgram_context.
156 * It returns a 'tevent_req' handle, where the caller can register
157 * a callback with tevent_req_set_callback(). The callback is triggered
158 * when a datagram is available or an error happened.
160 * @param[in] mem_ctx The talloc memory context to use.
162 * @param[in] ev The tevent_context to run on.
164 * @param[in] dgram The dgram context to work on.
166 * @return Returns a 'tevent_req' handle, where the caller can
167 * register a callback with tevent_req_set_callback().
168 * NULL on fatal error.
170 * @see tdgram_inet_udp_socket()
171 * @see tdgram_unix_socket()
173 struct tevent_req
*tdgram_recvfrom_send(TALLOC_CTX
*mem_ctx
,
174 struct tevent_context
*ev
,
175 struct tdgram_context
*dgram
);
178 * @brief Receive the next available datagram on the abstracted tdgram_context.
180 * This function should be called by the callback when a datagram is available
181 * or an error happened.
183 * The caller can only have one outstanding tdgram_recvfrom_send() at a time
184 * otherwise the caller will get '*perrno = EBUSY'.
186 * @param[in] req The tevent request from tdgram_recvfrom_send().
188 * @param[out] perrno The error number, set if an error occurred.
190 * @param[in] mem_ctx The memory context to use.
192 * @param[out] buf This will hold the buffer of the datagram.
194 * @param[out] src The abstracted tsocket_address of the sender of the
197 * @return The length of the datagram (0 is never returned!),
198 * -1 on error with perrno set to the actual errno.
200 * @see tdgram_recvfrom_send()
202 ssize_t
tdgram_recvfrom_recv(struct tevent_req
*req
,
206 struct tsocket_address
**src
);
209 * @brief Send a datagram to a destination endpoint.
211 * The function can be called to send a datagram (specified by a buf/len) to a
212 * destination endpoint (specified by dst). It's not allowed for len to be 0.
214 * It returns a 'tevent_req' handle, where the caller can register a callback
215 * with tevent_req_set_callback(). The callback is triggered when the specific
216 * implementation (assumes it) has delivered the datagram to the "wire".
218 * The callback is then supposed to get the result by calling
219 * tdgram_sendto_recv() on the 'tevent_req'.
221 * @param[in] mem_ctx The talloc memory context to use.
223 * @param[in] ev The tevent_context to run on.
225 * @param[in] dgram The dgram context to work on.
227 * @param[in] buf The buffer to send.
229 * @param[in] len The length of the buffer to send. It has to be bigger
232 * @param[in] dst The destination to send the datagram to in form of a
235 * @return Returns a 'tevent_req' handle, where the caller can
236 * register a callback with tevent_req_set_callback().
237 * NULL on fatal error.
239 * @see tdgram_inet_udp_socket()
240 * @see tdgram_unix_socket()
241 * @see tdgram_sendto_recv()
243 struct tevent_req
*tdgram_sendto_send(TALLOC_CTX
*mem_ctx
,
244 struct tevent_context
*ev
,
245 struct tdgram_context
*dgram
,
246 const uint8_t *buf
, size_t len
,
247 const struct tsocket_address
*dst
);
250 * @brief Receive the result of the sent datagram.
252 * The caller can only have one outstanding tdgram_sendto_send() at a time
253 * otherwise the caller will get '*perrno = EBUSY'.
255 * @param[in] req The tevent request from tdgram_sendto_send().
257 * @param[out] perrno The error number, set if an error occurred.
259 * @return The length of the datagram (0 is never returned!), -1 on
260 * error with perrno set to the actual errno.
262 * @see tdgram_sendto_send()
264 ssize_t
tdgram_sendto_recv(struct tevent_req
*req
,
268 * @brief Shutdown/close an abstracted socket.
270 * It returns a 'tevent_req' handle, where the caller can register a callback
271 * with tevent_req_set_callback(). The callback is triggered when the specific
272 * implementation (assumes it) has delivered the datagram to the "wire".
274 * The callback is then supposed to get the result by calling
275 * tdgram_sendto_recv() on the 'tevent_req'.
277 * @param[in] mem_ctx The talloc memory context to use.
279 * @param[in] ev The tevent_context to run on.
281 * @param[in] dgram The dgram context diconnect from.
283 * @return Returns a 'tevent_req' handle, where the caller can
284 * register a callback with tevent_req_set_callback().
285 * NULL on fatal error.
287 * @see tdgram_disconnect_recv()
289 struct tevent_req
*tdgram_disconnect_send(TALLOC_CTX
*mem_ctx
,
290 struct tevent_context
*ev
,
291 struct tdgram_context
*dgram
);
294 * @brief Receive the result from a tdgram_disconnect_send() request.
296 * The caller should make sure there're no outstanding tdgram_recvfrom_send()
297 * and tdgram_sendto_send() calls otherwise the caller will get
300 * @param[in] req The tevent request from tdgram_disconnect_send().
302 * @param[out] perrno The error number, set if an error occurred.
304 * @return The length of the datagram (0 is never returned!), -1 on
305 * error with perrno set to the actual errno.
307 * @see tdgram_disconnect_send()
309 int tdgram_disconnect_recv(struct tevent_req
*req
,
317 * @defgroup tstream_context The tstream_context abstraction
320 * The tstream_context is like an abstract class for stream based sockets. The
321 * interface provides async 'tevent_req' based functions on top functionality
322 * is similar to the readv(2)/writev(2)/close(2) syscalls.
324 * @note You can always use talloc_free(tstream) to cleanup the resources
325 * of the tstream_context on a fatal error.
331 * @brief Report the number of bytes received but not consumed yet.
333 * The tstream_pending_bytes() function reports how much bytes of the incoming
334 * stream have been received but not consumed yet.
336 * @param[in] stream The tstream_context to check for pending bytes.
338 * @return The number of bytes received, -1 on error with errno
341 ssize_t
tstream_pending_bytes(struct tstream_context
*stream
);
344 * @brief Read a specific amount of bytes from a stream socket.
346 * The function can be called to read for a specific amount of bytes from the
347 * stream into given buffers. The caller has to preallocate the buffers.
349 * The caller might need to use tstream_pending_bytes() if the protocol doesn't
350 * have a fixed pdu header containing the pdu size.
352 * @param[in] mem_ctx The talloc memory context to use.
354 * @param[in] ev The tevent_context to run on.
356 * @param[in] stream The tstream context to work on.
358 * @param[out] vector A preallocated iovec to store the data to read.
360 * @param[in] count The number of buffers in the vector allocated.
362 * @return A 'tevent_req' handle, where the caller can register
363 * a callback with tevent_req_set_callback(). NULL on
366 * @see tstream_unix_connect_send()
367 * @see tstream_inet_tcp_connect_send()
369 struct tevent_req
*tstream_readv_send(TALLOC_CTX
*mem_ctx
,
370 struct tevent_context
*ev
,
371 struct tstream_context
*stream
,
372 struct iovec
*vector
,
376 * @brief Get the result of a tstream_readv_send().
378 * The caller can only have one outstanding tstream_readv_send()
379 * at a time otherwise the caller will get *perrno = EBUSY.
381 * @param[in] req The tevent request from tstream_readv_send().
383 * @param[out] perrno The error number, set if an error occurred.
385 * @return The length of the stream (0 is never returned!), -1 on
386 * error with perrno set to the actual errno.
388 int tstream_readv_recv(struct tevent_req
*req
,
392 * @brief Write buffers from a vector into a stream socket.
394 * The function can be called to write buffers from a given vector
395 * to a stream socket.
397 * You have to ensure that the vector is not empty.
399 * @param[in] mem_ctx The talloc memory context to use.
401 * @param[in] ev The tevent_context to run on.
403 * @param[in] stream The tstream context to work on.
405 * @param[in] vector The iovec vector with data to write on a stream socket.
407 * @param[in] count The number of buffers in the vector to write.
409 * @return A 'tevent_req' handle, where the caller can register
410 * a callback with tevent_req_set_callback(). NULL on
413 struct tevent_req
*tstream_writev_send(TALLOC_CTX
*mem_ctx
,
414 struct tevent_context
*ev
,
415 struct tstream_context
*stream
,
416 const struct iovec
*vector
,
420 * @brief Get the result of a tstream_writev_send().
422 * The caller can only have one outstanding tstream_writev_send()
423 * at a time otherwise the caller will get *perrno = EBUSY.
425 * @param[in] req The tevent request from tstream_writev_send().
427 * @param[out] perrno The error number, set if an error occurred.
429 * @return The length of the stream (0 is never returned!), -1 on
430 * error with perrno set to the actual errno.
432 int tstream_writev_recv(struct tevent_req
*req
,
436 * @brief Shutdown/close an abstracted socket.
438 * It returns a 'tevent_req' handle, where the caller can register a callback
439 * with tevent_req_set_callback(). The callback is triggered when the specific
440 * implementation (assumes it) has delivered the stream to the "wire".
442 * The callback is then supposed to get the result by calling
443 * tdgram_sendto_recv() on the 'tevent_req'.
445 * @param[in] mem_ctx The talloc memory context to use.
447 * @param[in] ev The tevent_context to run on.
449 * @param[in] stream The tstream context to work on.
451 * @return A 'tevent_req' handle, where the caller can register
452 * a callback with tevent_req_set_callback(). NULL on
455 struct tevent_req
*tstream_disconnect_send(TALLOC_CTX
*mem_ctx
,
456 struct tevent_context
*ev
,
457 struct tstream_context
*stream
);
460 * @brief Get the result of a tstream_disconnect_send().
462 * The caller can only have one outstanding tstream_writev_send()
463 * at a time otherwise the caller will get *perrno = EBUSY.
465 * @param[in] req The tevent request from tstream_disconnect_send().
467 * @param[out] perrno The error number, set if an error occurred.
469 * @return The length of the stream (0 is never returned!), -1 on
470 * error with perrno set to the actual errno.
472 int tstream_disconnect_recv(struct tevent_req
*req
,
481 * @defgroup tsocket_bsd tsocket_bsd - inet, inet6 and unix
484 * The main tsocket library comes with implementations for BSD style ipv4, ipv6
491 * @brief Find out if the tsocket_address represents an ipv4 or ipv6 endpoint.
493 * @param[in] addr The tsocket_address pointer
495 * @param[in] fam The family can be can be "ipv4", "ipv6" or "ip". With
496 * "ip" is autodetects "ipv4" or "ipv6" based on the
499 * @return true if addr represents an address of the given family,
502 bool tsocket_address_is_inet(const struct tsocket_address
*addr
, const char *fam
);
506 * @brief Create a tsocket_address for ipv4 and ipv6 endpoint addresses.
508 * @param[in] mem_ctx The talloc memory context to use.
510 * @param[in] fam The family can be can be "ipv4", "ipv6" or "ip". With
511 * "ip" is autodetects "ipv4" or "ipv6" based on the
514 * @param[in] addr A valid ip address string based on the selected family
515 * (dns names are not allowed!). It's valid to pass NULL,
516 * which gets mapped to "0.0.0.0" or "::".
518 * @param[in] port A valid port number.
520 * @param[out] _addr A tsocket_address pointer to store the information.
522 * @return 0 on success, -1 on error with errno set.
524 int tsocket_address_inet_from_strings(TALLOC_CTX
*mem_ctx
,
528 struct tsocket_address
**_addr
);
530 int _tsocket_address_inet_from_strings(TALLOC_CTX
*mem_ctx
,
534 struct tsocket_address
**_addr
,
535 const char *location
);
537 #define tsocket_address_inet_from_strings(mem_ctx, fam, addr, port, _addr) \
538 _tsocket_address_inet_from_strings(mem_ctx, fam, addr, port, _addr, \
544 * @brief Create a tsocket_address for ipv4 and ipv6 endpoint addresses.
546 * @param[in] mem_ctx The talloc memory context to use.
548 * @param[in] fam The family can be can be "ipv4", "ipv6" or "ip". With
549 * "ip" it autodetects "ipv4" or "ipv6" based on the
552 * @param[in] host_port_addr A valid ip address string based on the
553 * selected family (dns names are not allowed!). A port
554 * number may follow sepatated by a colon. IPv6 may be
555 * surrounded in square brackets, and these are required
556 * if appending a port number. It's valid to pass NULL,
557 * which gets mapped to "0.0.0.0" or "::".
559 * @param[in] default_port A valid port number for the default port if none
562 * @param[out] _addr A tsocket_address pointer to store the information.
564 * @return 0 on success, -1 on error with errno set.
566 int tsocket_address_inet_from_hostport_strings(TALLOC_CTX
*mem_ctx
,
568 const char *host_port_addr
,
569 uint16_t default_port
,
570 struct tsocket_address
**_addr
);
572 int _tsocket_address_inet_from_hostport_strings(TALLOC_CTX
*mem_ctx
,
574 const char *host_port_addr
,
575 uint16_t default_port
,
576 struct tsocket_address
**_addr
,
577 const char *location
);
579 #define tsocket_address_inet_from_hostport_strings( \
580 mem_ctx, fam, host_port_addr, default_port, _addr) \
581 _tsocket_address_inet_from_hostport_strings( \
582 mem_ctx, fam, host_port_addr, default_port, _addr, __location__)
586 * @brief Get the address of an 'inet' tsocket_address as a string.
588 * @param[in] addr The address to convert to a string.
590 * @param[in] mem_ctx The talloc memory context to use.
592 * @return A newly allocated string of the address, NULL on error
595 * @see tsocket_address_is_inet()
597 char *tsocket_address_inet_addr_string(const struct tsocket_address
*addr
,
598 TALLOC_CTX
*mem_ctx
);
601 * @brief Get the port number as an integer from an 'inet' tsocket_address.
603 * @param[in] addr The tsocket address to use.
605 * @return The port number, 0 on error with errno set.
607 uint16_t tsocket_address_inet_port(const struct tsocket_address
*addr
);
610 * @brief Set the port number of an existing 'inet' tsocket_address.
612 * @param[in] addr The existing tsocket_address to use.
614 * @param[in] port The valid port number to set.
616 * @return 0 on success, -1 on error with errno set.
618 int tsocket_address_inet_set_port(struct tsocket_address
*addr
,
622 * @brief Find out if the tsocket_address represents an unix domain endpoint.
624 * @param[in] addr The tsocket_address pointer
626 * @return true if addr represents an unix domain endpoint,
629 bool tsocket_address_is_unix(const struct tsocket_address
*addr
);
633 * @brief Create a tsocket_address for a unix domain endpoint addresses.
635 * @param[in] mem_ctx The talloc memory context to use.
637 * @param[in] path The filesystem path, NULL will map "".
639 * @param[in] _addr The tsocket_address pointer to store the information.
641 * @return 0 on success, -1 on error with errno set.
643 * @see tsocket_address_is_unix()
645 int tsocket_address_unix_from_path(TALLOC_CTX
*mem_ctx
,
647 struct tsocket_address
**_addr
);
649 int _tsocket_address_unix_from_path(TALLOC_CTX
*mem_ctx
,
651 struct tsocket_address
**_addr
,
652 const char *location
);
654 #define tsocket_address_unix_from_path(mem_ctx, path, _addr) \
655 _tsocket_address_unix_from_path(mem_ctx, path, _addr, \
660 * @brief Get the address of an 'unix' tsocket_address.
662 * @param[in] addr A valid 'unix' tsocket_address.
664 * @param[in] mem_ctx The talloc memory context to use.
666 * @return The path of the unix domain socket, NULL on error or if
667 * the tsocket_address doesn't represent an unix domain
670 char *tsocket_address_unix_path(const struct tsocket_address
*addr
,
671 TALLOC_CTX
*mem_ctx
);
675 * @brief Wrap an existing file descriptors into the tdgram abstraction.
677 * You can use this function to wrap an existing file descriptors into the
678 * tdgram abstraction. After that you're not able to use this file descriptor
679 * for anything else. The file descriptor will be closed when the stream gets
680 * freed. If you still want to use the fd you have have to create a duplicate.
682 * @param[in] mem_ctx The talloc memory context to use.
684 * @param[in] fd The non blocking fd to use!
686 * @param[out] dgram A pointer to store an allocated tdgram_context.
688 * @return 0 on success, -1 on error.
693 * rc = tdgram_bsd_existing_socket(mem_ctx, fd2, &tdgram);
699 * @warning This is an internal function. You should read the code to fully
700 * understand it if you plan to use it.
702 int tdgram_bsd_existing_socket(TALLOC_CTX
*mem_ctx
,
704 struct tdgram_context
**dgram
);
706 int _tdgram_bsd_existing_socket(TALLOC_CTX
*mem_ctx
,
708 struct tdgram_context
**_dgram
,
709 const char *location
);
710 #define tdgram_bsd_existing_socket(mem_ctx, fd, dgram) \
711 _tdgram_bsd_existing_socket(mem_ctx, fd, dgram, \
716 * @brief Request a syscall optimization for tdgram_recvfrom_send()
718 * This function is only used to reduce the amount of syscalls and
719 * optimize performance. You should only use this if you know
722 * The optimization is off by default.
724 * @param[in] dgram The tdgram_context of a bsd socket, if this
725 * not a bsd socket the function does nothing.
727 * @param[in] on The boolean value to turn the optimization on and off.
729 * @return The old boolean value.
731 * @see tdgram_recvfrom_send()
733 bool tdgram_bsd_optimize_recvfrom(struct tdgram_context
*dgram
,
738 * @brief Create a tdgram_context for a ipv4 or ipv6 UDP communication.
740 * @param[in] local An 'inet' tsocket_address for the local endpoint.
742 * @param[in] remote An 'inet' tsocket_address for the remote endpoint or
743 * NULL (??? to create a listener?).
745 * @param[in] mem_ctx The talloc memory context to use.
747 * @param[in] dgram The tdgram_context pointer to setup the udp
748 * communication. The function will allocate the memory.
750 * @return 0 on success, -1 on error with errno set.
752 * @see tdgram_inet_udp_broadcast_socket()
754 int tdgram_inet_udp_socket(const struct tsocket_address
*local
,
755 const struct tsocket_address
*remote
,
757 struct tdgram_context
**dgram
);
759 int _tdgram_inet_udp_socket(const struct tsocket_address
*local
,
760 const struct tsocket_address
*remote
,
762 struct tdgram_context
**dgram
,
763 const char *location
);
764 #define tdgram_inet_udp_socket(local, remote, mem_ctx, dgram) \
765 _tdgram_inet_udp_socket(local, remote, mem_ctx, dgram, __location__)
770 * @brief Create a tdgram_context for a ipv4 UDP broadcast (and unicast) communication.
772 * @param[in] local An 'inet' (ipv4 only) tsocket_address for the local endpoint.
774 * @param[in] mem_ctx The talloc memory context to use.
776 * @param[in] dgram The tdgram_context pointer to setup the udp
777 * communication. The function will allocate the memory.
779 * @return 0 on success, -1 on error with errno set.
781 * @see tdgram_inet_udp_socket()
783 int tdgram_inet_udp_broadcast_socket(const struct tsocket_address
*local
,
785 struct tdgram_context
**dgram
);
787 int _tdgram_inet_udp_broadcast_socket(const struct tsocket_address
*local
,
789 struct tdgram_context
**dgram
,
790 const char *location
);
791 #define tdgram_inet_udp_broadcast_socket(local, mem_ctx, dgram) \
792 _tdgram_inet_udp_broadcast_socket(local, mem_ctx, dgram, __location__)
797 * @brief Create a tdgram_context for unix domain datagram communication.
799 * @param[in] local An 'unix' tsocket_address for the local endpoint.
801 * @param[in] remote An 'unix' tsocket_address for the remote endpoint or
802 * NULL (??? to create a listener?).
804 * @param[in] mem_ctx The talloc memory context to use.
806 * @param[in] dgram The tdgram_context pointer to setup the udp
807 * communication. The function will allocate the memory.
809 * @return 0 on success, -1 on error with errno set.
811 int tdgram_unix_socket(const struct tsocket_address
*local
,
812 const struct tsocket_address
*remote
,
814 struct tdgram_context
**dgram
);
816 int _tdgram_unix_socket(const struct tsocket_address
*local
,
817 const struct tsocket_address
*remote
,
819 struct tdgram_context
**dgram
,
820 const char *location
);
822 #define tdgram_unix_socket(local, remote, mem_ctx, dgram) \
823 _tdgram_unix_socket(local, remote, mem_ctx, dgram, __location__)
827 * @brief Request a syscall optimization for tstream_readv_send()
829 * This function is only used to reduce the amount of syscalls and
830 * optimize performance. You should only use this if you know
833 * The optimization is off by default.
835 * @param[in] stream The tstream_context of a bsd socket, if this
836 * not a bsd socket the function does nothing.
838 * @param[in] on The boolean value to turn the optimization on and off.
840 * @return The old boolean value.
842 * @see tstream_readv_send()
844 bool tstream_bsd_optimize_readv(struct tstream_context
*stream
,
848 * @brief Connect async to a TCP endpoint and create a tstream_context for the
849 * stream based communication.
851 * Use this function to connect asynchronously to a remote ipv4 or ipv6 TCP
852 * endpoint and create a tstream_context for the stream based communication.
854 * @param[in] mem_ctx The talloc memory context to use.
856 * @param[in] ev The tevent_context to run on.
858 * @param[in] local An 'inet' tsocket_address for the local endpoint.
860 * @param[in] remote An 'inet' tsocket_address for the remote endpoint.
862 * @return A 'tevent_req' handle, where the caller can register a
863 * callback with tevent_req_set_callback(). NULL on a fatal
866 * @see tstream_inet_tcp_connect_recv()
868 struct tevent_req
*tstream_inet_tcp_connect_send(TALLOC_CTX
*mem_ctx
,
869 struct tevent_context
*ev
,
870 const struct tsocket_address
*local
,
871 const struct tsocket_address
*remote
);
875 * @brief Receive the result from a tstream_inet_tcp_connect_send().
877 * @param[in] req The tevent request from tstream_inet_tcp_connect_send().
879 * @param[out] perrno The error number, set if an error occurred.
881 * @param[in] mem_ctx The talloc memory context to use.
883 * @param[out] stream A tstream_context pointer to setup the tcp communication
884 * on. This function will allocate the memory.
886 * @param[out] local The real 'inet' tsocket_address of the local endpoint.
887 * This parameter is optional and can be NULL.
889 * @return 0 on success, -1 on error with perrno set.
891 int tstream_inet_tcp_connect_recv(struct tevent_req
*req
,
894 struct tstream_context
**stream
,
895 struct tsocket_address
**local
)
897 int _tstream_inet_tcp_connect_recv(struct tevent_req
*req
,
900 struct tstream_context
**stream
,
901 struct tsocket_address
**local
,
902 const char *location
);
903 #define tstream_inet_tcp_connect_recv(req, perrno, mem_ctx, stream, local) \
904 _tstream_inet_tcp_connect_recv(req, perrno, mem_ctx, stream, local, \
909 * @brief Connect async to a unix domain endpoint and create a tstream_context
910 * for the stream based communication.
912 * Use this function to connenct asynchronously to a unix domainendpoint and
913 * create a tstream_context for the stream based communication.
915 * The callback is triggered when a socket is connected and ready for IO or an
918 * @param[in] mem_ctx The talloc memory context to use.
920 * @param[in] ev The tevent_context to run on.
922 * @param[in] local An 'unix' tsocket_address for the local endpoint.
924 * @param[in] remote An 'unix' tsocket_address for the remote endpoint.
926 * @return A 'tevent_req' handle, where the caller can register a
927 * callback with tevent_req_set_callback(). NULL on a falal
930 * @see tstream_unix_connect_recv()
932 struct tevent_req
* tstream_unix_connect_send(TALLOC_CTX
*mem_ctx
,
933 struct tevent_context
*ev
,
934 const struct tsocket_address
*local
,
935 const struct tsocket_address
*remote
);
939 * @brief Receive the result from a tstream_unix_connect_send().
941 * @param[in] req The tevent request from tstream_inet_tcp_connect_send().
943 * @param[out] perrno The error number, set if an error occurred.
945 * @param[in] mem_ctx The talloc memory context to use.
947 * @param[in] stream The tstream context to work on.
949 * @return 0 on success, -1 on error with perrno set.
951 int tstream_unix_connect_recv(struct tevent_req
*req
,
954 struct tstream_context
**stream
);
956 int _tstream_unix_connect_recv(struct tevent_req
*req
,
959 struct tstream_context
**stream
,
960 const char *location
);
961 #define tstream_unix_connect_recv(req, perrno, mem_ctx, stream) \
962 _tstream_unix_connect_recv(req, perrno, mem_ctx, stream, \
968 * @brief Create two connected 'unix' tsocket_contexts for stream based
971 * @param[in] mem_ctx1 The talloc memory context to use for stream1.
973 * @param[in] stream1 The first stream to connect.
975 * @param[in] mem_ctx2 The talloc memory context to use for stream2.
977 * @param[in] stream2 The second stream to connect.
979 * @return 0 on success, -1 on error with errno set.
981 int tstream_unix_socketpair(TALLOC_CTX
*mem_ctx1
,
982 struct tstream_context
**stream1
,
983 TALLOC_CTX
*mem_ctx2
,
984 struct tstream_context
**stream2
);
986 int _tstream_unix_socketpair(TALLOC_CTX
*mem_ctx1
,
987 struct tstream_context
**_stream1
,
988 TALLOC_CTX
*mem_ctx2
,
989 struct tstream_context
**_stream2
,
990 const char *location
);
992 #define tstream_unix_socketpair(mem_ctx1, stream1, mem_ctx2, stream2) \
993 _tstream_unix_socketpair(mem_ctx1, stream1, mem_ctx2, stream2, \
1001 * @brief Convert a tsocket address to a bsd socket address.
1003 * @param[in] mem_ctx The talloc memory context to use.
1005 * @param[in] sa The sockaddr structure to convert.
1007 * @param[in] sa_socklen The length of the sockaddr structure.
1009 * @param[out] addr The tsocket pointer to allocate and fill.
1011 * @return 0 on success, -1 on error with errno set.
1013 int tsocket_address_bsd_from_sockaddr(TALLOC_CTX
*mem_ctx
,
1014 const struct sockaddr
*sa
,
1016 struct tsocket_address
**addr
);
1018 int _tsocket_address_bsd_from_sockaddr(TALLOC_CTX
*mem_ctx
,
1019 const struct sockaddr
*sa
,
1021 struct tsocket_address
**_addr
,
1022 const char *location
);
1024 #define tsocket_address_bsd_from_sockaddr(mem_ctx, sa, sa_socklen, _addr) \
1025 _tsocket_address_bsd_from_sockaddr(mem_ctx, sa, sa_socklen, _addr, \
1031 * @brief Convert a samba address to a tsocket address.
1033 * @param[in] mem_ctx The talloc memory context to use.
1035 * @param[in] s_addr The samba address structure to convert.
1037 * @param[out] t_addr The tsocket pointer to allocate and fill.
1039 * @return 0 on success, -1 on error with errno set.
1041 int tsocket_address_bsd_from_samba_sockaddr(TALLOC_CTX
*mem_ctx
,
1042 const struct samba_sockaddr
*xs_addr
,
1043 struct tsocket_address
**t_addr
);
1045 int _tsocket_address_bsd_from_samba_sockaddr(TALLOC_CTX
*mem_ctx
,
1046 const struct samba_sockaddr
*xs_addr
,
1047 struct tsocket_address
**t_addr
,
1048 const char *location
);
1050 #define tsocket_address_bsd_from_samba_sockaddr(mem_ctx, xs_addr, t_addr) \
1051 _tsocket_address_bsd_from_samba_sockaddr(mem_ctx, xs_addr, t_addr, \
1056 * @brief Fill a bsd sockaddr structure.
1058 * @param[in] addr The tsocket address structure to use.
1060 * @param[in] sa The bsd sockaddr structure to fill out.
1062 * @param[in] sa_socklen The length of the bsd sockaddr structure to fill out.
1064 * @return The actual size of the sockaddr structure, -1 on error
1065 * with errno set. The size could differ from sa_socklen.
1069 * struct sockaddr_storage ss;
1071 * socklen = tsocket_address_bsd_sockaddr(taddr,
1072 * (struct sockaddr *) &ss,
1073 * sizeof(struct sockaddr_storage));
1074 * if (socklen < 0) {
1079 ssize_t
tsocket_address_bsd_sockaddr(const struct tsocket_address
*addr
,
1080 struct sockaddr
*sa
,
1085 * @brief Wrap an existing file descriptors into the tstream abstraction.
1087 * You can use this function to wrap an existing file descriptors into the
1088 * tstream abstraction. After that you're not able to use this file descriptor
1089 * for anything else. The file descriptor will be closed when the stream gets
1090 * freed. If you still want to use the fd you have have to create a duplicate.
1092 * @param[in] mem_ctx The talloc memory context to use.
1094 * @param[in] fd The non blocking fd to use!
1096 * @param[out] stream A pointer to store an allocated tstream_context.
1098 * @return 0 on success, -1 on error.
1103 * rc = tstream_bsd_existing_socket(mem_ctx, fd2, &tstream);
1105 * stream_terminate_connection(conn, "named_pipe_accept: out of memory");
1110 * @warning This is an internal function. You should read the code to fully
1111 * understand it if you plan to use it.
1113 int tstream_bsd_existing_socket(TALLOC_CTX
*mem_ctx
,
1115 struct tstream_context
**stream
);
1117 int _tstream_bsd_existing_socket(TALLOC_CTX
*mem_ctx
,
1119 struct tstream_context
**_stream
,
1120 const char *location
);
1121 #define tstream_bsd_existing_socket(mem_ctx, fd, stream) \
1122 _tstream_bsd_existing_socket(mem_ctx, fd, stream, \
1131 * @defgroup tsocket_helper Queue and PDU helpers
1134 * In order to make the live easier for callers which want to implement a
1135 * function to receive a full PDU with a single async function pair, there're
1136 * some helper functions.
1138 * There're some cases where the caller wants doesn't care about the order of
1139 * doing IO on the abstracted sockets.
1145 * @brief Queue a dgram blob for sending through the socket.
1147 * This function queues a blob for sending to destination through an existing
1148 * dgram socket. The async callback is triggered when the whole blob is
1149 * delivered to the underlying system socket.
1151 * The caller needs to make sure that all non-scalar input parameters hang
1152 * around for the whole lifetime of the request.
1154 * @param[in] mem_ctx The memory context for the result.
1156 * @param[in] ev The event context the operation should work on.
1158 * @param[in] dgram The tdgram_context to send the message buffer.
1160 * @param[in] queue The existing dgram queue.
1162 * @param[in] buf The message buffer to send.
1164 * @param[in] len The message length.
1166 * @param[in] dst The destination socket address.
1168 * @return The async request handle. NULL on fatal error.
1170 * @see tdgram_sendto_queue_recv()
1172 struct tevent_req
*tdgram_sendto_queue_send(TALLOC_CTX
*mem_ctx
,
1173 struct tevent_context
*ev
,
1174 struct tdgram_context
*dgram
,
1175 struct tevent_queue
*queue
,
1178 struct tsocket_address
*dst
);
1181 * @brief Receive the result of the sent dgram blob.
1183 * @param[in] req The tevent request from tdgram_sendto_queue_send().
1185 * @param[out] perrno The error set to the actual errno.
1187 * @return The length of the datagram (0 is never returned!), -1 on
1188 * error with perrno set to the actual errno.
1190 ssize_t
tdgram_sendto_queue_recv(struct tevent_req
*req
, int *perrno
);
1192 typedef int (*tstream_readv_pdu_next_vector_t
)(struct tstream_context
*stream
,
1194 TALLOC_CTX
*mem_ctx
,
1195 struct iovec
**vector
,
1198 struct tevent_req
*tstream_readv_pdu_send(TALLOC_CTX
*mem_ctx
,
1199 struct tevent_context
*ev
,
1200 struct tstream_context
*stream
,
1201 tstream_readv_pdu_next_vector_t next_vector_fn
,
1202 void *next_vector_private
);
1203 int tstream_readv_pdu_recv(struct tevent_req
*req
, int *perrno
);
1206 * @brief Queue a read request for a PDU on the socket.
1208 * This function queues a read request for a PDU on a stream socket. The async
1209 * callback is triggered when a full PDU has been read from the socket.
1211 * The caller needs to make sure that all non-scalar input parameters hang
1212 * around for the whole lifetime of the request.
1214 * @param[in] mem_ctx The memory context for the result
1216 * @param[in] ev The tevent_context to run on
1218 * @param[in] stream The stream to send data through
1220 * @param[in] queue The existing send queue
1222 * @param[in] next_vector_fn The next vector function
1224 * @param[in] next_vector_private The private_data of the next vector function
1226 * @return The async request handle. NULL on fatal error.
1228 * @see tstream_readv_pdu_queue_recv()
1230 struct tevent_req
*tstream_readv_pdu_queue_send(TALLOC_CTX
*mem_ctx
,
1231 struct tevent_context
*ev
,
1232 struct tstream_context
*stream
,
1233 struct tevent_queue
*queue
,
1234 tstream_readv_pdu_next_vector_t next_vector_fn
,
1235 void *next_vector_private
);
1238 * @brief Receive the PDU blob read from the stream.
1240 * @param[in] req The tevent request from tstream_readv_pdu_queue_send().
1242 * @param[out] perrno The error set to the actual errno.
1244 * @return The number of bytes read on success, -1 on error with
1245 * perrno set to the actual errno.
1247 int tstream_readv_pdu_queue_recv(struct tevent_req
*req
, int *perrno
);
1250 * @brief Queue an iovector for sending through the socket
1252 * This function queues an iovector for sending to destination through an
1253 * existing stream socket. The async callback is triggered when the whole
1254 * vectror has been delivered to the underlying system socket.
1256 * The caller needs to make sure that all non-scalar input parameters hang
1257 * around for the whole lifetime of the request.
1259 * @param[in] mem_ctx The memory context for the result.
1261 * @param[in] ev The tevent_context to run on.
1263 * @param[in] stream The stream to send data through.
1265 * @param[in] queue The existing send queue.
1267 * @param[in] vector The iovec vector so write.
1269 * @param[in] count The size of the vector.
1271 * @return The async request handle. NULL on fatal error.
1273 struct tevent_req
*tstream_writev_queue_send(TALLOC_CTX
*mem_ctx
,
1274 struct tevent_context
*ev
,
1275 struct tstream_context
*stream
,
1276 struct tevent_queue
*queue
,
1277 const struct iovec
*vector
,
1281 * @brief Receive the result of the sent iovector.
1283 * @param[in] req The tevent request from tstream_writev_queue_send().
1285 * @param[out] perrno The error set to the actual errno.
1287 * @return The length of the iovector (0 is never returned!), -1 on
1288 * error with perrno set to the actual errno.
1290 int tstream_writev_queue_recv(struct tevent_req
*req
, int *perrno
);
1296 #endif /* _TSOCKET_H */