tor-android/jni/libancillary/API

  This library provide an easy interface to the black magic that can be done
  on Unix domain sockets, like passing file descriptors from one process to
  another.

  Programs that uses this library should include the ancillary.h header file.
  Nothing else is required.

  All functions of this library require the following header:

	#include <ancillary.h>

  At this time, the only ancillary data defined by the Single Unix
  Specification (v3) is file descriptors.

Passing file descriptors

	int ancil_send_fd(socket, file_descriptor)
	  int socket: the Unix socket
	  int file_descriptor: the file descriptor
	  Return value: 0 for success, -1 for failure.

  Sends one file descriptor on a socket.
  In case of failure, errno is set; the possible values are the ones of the
  sendmsg(2) system call.


	int ancil_recv_fd(socket, file_descriptor)
	  int socket: the Unix socket
	  int *file_descriptor: pointer to the returned file descriptor
	  Return value: 0 for success, -1 for failure

  Receives one file descriptor from a socket.
  In case of success, the file descriptor is stored in the integer pointed
  to by file_descriptor.
  In case of failure, errno is set; the possible values are the ones of the
  recvmsg(2) system call.
  The behavior is undefined if the recv_fd does not match a send_fd* on the
  other side.


	int ancil_send_fds(socket, file_descriptors, num_file_descriptors)
	  int socket: the Unix socket
	  const int *file_descriptors: array of file descriptors
	  unsigned num_file_descriptors: number of file descriptors
	  Return value: 0 for success, -1 for failure

  Sends several file descriptors on a socket.
  In case of failure, errno is set; the possible values are the ones of the
  sendmsg(2) system call.
  The maximum number of file descriptors that can be sent using this
  function is ANCIL_MAX_N_FDS; the behavior is undefined in case of
  overflow, probably a stack corruption.


	int ancil_recv_fds(socket, file_descriptors, num_file_descriptors)
	  int socket: the Unix socket
	  int *file_descriptors: return array of file descriptors
	  unsigned num_file_descriptors: number of file descriptors
	  Return value: number of received fd for success, -1 for failure

  Receives several file descriptors from a socket, no more than
  num_file_descriptors.
  In case of success, the received file descriptors are stored in the array
  pointed to by file_descriptors.
  In case of failure, errno is set; the possible values are the ones of the
  recvmsg(2) system call.
  The maximum number of file descriptors that can be received using this
  function is ANCIL_MAX_N_FDS; the behavior is undefined in case of
  overflow, probably a stack corruption.
  The behavior is undefined if the recv_fds does not match a send_fd* on
  the other side, or if the number of received file descriptors is more than
  num_file_descriptors.


	int ancil_send_fds_with_buffer(socket, fds, num, buffer)
	  int socket: the Unix socket
	  const int *fds: array of file descriptors
	  unsigned num: number of file descriptors
	  void *buffer: buffer to hold the system data structures
	  Return value: 0 for success, -1 for failure

  Sends several file descriptors on a socket.
  In case of failure, errno is set; the possible values are the ones of the
  sendmsg(2) system call.
  The buffer argument must point to a memory area large enough to hold the
  system data structures, see ANCIL_FD_BUFFER.


	int ancil_send_fds_with_buffer(socket, fds, num, buffer)
	  int socket: the Unix socket
	  int *fds: return array of file descriptors
	  unsigned num: number of file descriptors
	  void *buffer: buffer to hold the system data structures
	  Return value: number of received fd for success, -1 for failure

  Receives several file descriptors from a socket, no more than
  num_file_descriptors.
  In case of success, the received file descriptors are stored in the array
  pointed to by file_descriptors.
  In case of failure, errno is set; the possible values are the ones of the
  recvmsg(2) system call.
  The behavior is undefined if the recv_fds does not match a send_fd* on
  the other side, or if the number of received file descriptors is more than
  num_file_descriptors.
  The buffer argument must point to a memory area large enough to hold the
  system data structures, see ANCIL_FD_BUFFER.


	ANCIL_MAX_N_FDS

  Maximum number of file descriptors that can be sent with the sent_fds and
  recv_fds functions. If you have to send more at once, use the
  *_with_buffer versions. The value is enough to send "quite a few" file
  descriptors.


	ANCIL_FD_BUFFER(n)
	  int n: number of file descriptors

  Expands to a structure data type large enough to hold the system data
  structures for n file descriptors. So the address of a variable declared
  of type ANCIL_FD_BUFFER(n) is suitable as the buffer argument for
  *_with_buffer on n file descriptors.
  To use this macro, you need <sys/types.h> and <sys/socket.h>. Bevare: with
  Solaris, the _XPG4_2 macro must be defined before sys/socket is included.


Tuning the compilation

  This library is designed to be included in projects, not installed in
  /usr/lib. If your project does not use some of the functions, the
  TUNE_OPTS variable in the Makefile allows not to build them. It is a list
  of proprocessor options:

  -DNDEBUG: turn assertions off (see assert(3))
  -DSPARE_SEND_FDS: do not build ancil_send_fds
  -DSPARE_SEND_FD:  do not build ancil_send_fd
  -DSPARE_RECV_FDS: do not build ancil_recv_fds
  -DSPARE_RECV_FD:  do not build ancil_recv_fd