← Back to branch summary

~raof/mir/prober-drm-device-probe

« back to all changes in this revision

Viewing changes to 3rd_party/libancillary/API

  • Committer: Alan Griffiths
  • Date: 2012-09-03 11:49:23 UTC
  • mto: This revision was merged to the branch mainline in revision 114.
  • Revision ID: alan@octopull.co.uk-20120903114923-na70zt8h5s6gnnkj
Add 3rd party including libancillary

Show diffs side-by-side

added added

removed removed

Lines of Context:
3rd_party/libancillary/API
 
1
  This library provide an easy interface to the black magic that can be done
 
2
  on Unix domain sockets, like passing file descriptors from one process to
 
3
  another.
 
4
 
 
5
  Programs that uses this library should include the ancillary.h header file.
 
6
  Nothing else is required.
 
7
 
 
8
  All functions of this library require the following header:
 
9
 
 
10
        #include <ancillary.h>
 
11
 
 
12
  At this time, the only ancillary data defined by the Single Unix
 
13
  Specification (v3) is file descriptors.
 
14
 
 
15
Passing file descriptors
 
16
 
 
17
        int ancil_send_fd(socket, file_descriptor)
 
18
          int socket: the Unix socket
 
19
          int file_descriptor: the file descriptor
 
20
          Return value: 0 for success, -1 for failure.
 
21
 
 
22
  Sends one file descriptor on a socket.
 
23
  In case of failure, errno is set; the possible values are the ones of the
 
24
  sendmsg(2) system call.
 
25
 
 
26
 
 
27
        int ancil_recv_fd(socket, file_descriptor)
 
28
          int socket: the Unix socket
 
29
          int *file_descriptor: pointer to the returned file descriptor
 
30
          Return value: 0 for success, -1 for failure
 
31
 
 
32
  Receives one file descriptor from a socket.
 
33
  In case of success, the file descriptor is stored in the integer pointed
 
34
  to by file_descriptor.
 
35
  In case of failure, errno is set; the possible values are the ones of the
 
36
  recvmsg(2) system call.
 
37
  The behavior is undefined if the recv_fd does not match a send_fd* on the
 
38
  other side.
 
39
 
 
40
 
 
41
        int ancil_send_fds(socket, file_descriptors, num_file_descriptors)
 
42
          int socket: the Unix socket
 
43
          const int *file_descriptors: array of file descriptors
 
44
          unsigned num_file_descriptors: number of file descriptors
 
45
          Return value: 0 for success, -1 for failure
 
46
 
 
47
  Sends several file descriptors on a socket.
 
48
  In case of failure, errno is set; the possible values are the ones of the
 
49
  sendmsg(2) system call.
 
50
  The maximum number of file descriptors that can be sent using this
 
51
  function is ANCIL_MAX_N_FDS; the behavior is undefined in case of
 
52
  overflow, probably a stack corruption.
 
53
 
 
54
 
 
55
        int ancil_recv_fds(socket, file_descriptors, num_file_descriptors)
 
56
          int socket: the Unix socket
 
57
          int *file_descriptors: return array of file descriptors
 
58
          unsigned num_file_descriptors: number of file descriptors
 
59
          Return value: number of received fd for success, -1 for failure
 
60
 
 
61
  Receives several file descriptors from a socket, no more than
 
62
  num_file_descriptors.
 
63
  In case of success, the received file descriptors are stored in the array
 
64
  pointed to by file_descriptors.
 
65
  In case of failure, errno is set; the possible values are the ones of the
 
66
  recvmsg(2) system call.
 
67
  The maximum number of file descriptors that can be received using this
 
68
  function is ANCIL_MAX_N_FDS; the behavior is undefined in case of
 
69
  overflow, probably a stack corruption.
 
70
  The behavior is undefined if the recv_fds does not match a send_fd* on
 
71
  the other side, or if the number of received file descriptors is more than
 
72
  num_file_descriptors.
 
73
 
 
74
 
 
75
        int ancil_send_fds_with_buffer(socket, fds, num, buffer)
 
76
          int socket: the Unix socket
 
77
          const int *fds: array of file descriptors
 
78
          unsigned num: number of file descriptors
 
79
          void *buffer: buffer to hold the system data structures
 
80
          Return value: 0 for success, -1 for failure
 
81
 
 
82
  Sends several file descriptors on a socket.
 
83
  In case of failure, errno is set; the possible values are the ones of the
 
84
  sendmsg(2) system call.
 
85
  The buffer argument must point to a memory area large enough to hold the
 
86
  system data structures, see ANCIL_FD_BUFFER.
 
87
 
 
88
 
 
89
        int ancil_send_fds_with_buffer(socket, fds, num, buffer)
 
90
          int socket: the Unix socket
 
91
          int *fds: return array of file descriptors
 
92
          unsigned num: number of file descriptors
 
93
          void *buffer: buffer to hold the system data structures
 
94
          Return value: number of received fd for success, -1 for failure
 
95
 
 
96
  Receives several file descriptors from a socket, no more than
 
97
  num_file_descriptors.
 
98
  In case of success, the received file descriptors are stored in the array
 
99
  pointed to by file_descriptors.
 
100
  In case of failure, errno is set; the possible values are the ones of the
 
101
  recvmsg(2) system call.
 
102
  The behavior is undefined if the recv_fds does not match a send_fd* on
 
103
  the other side, or if the number of received file descriptors is more than
 
104
  num_file_descriptors.
 
105
  The buffer argument must point to a memory area large enough to hold the
 
106
  system data structures, see ANCIL_FD_BUFFER.
 
107
 
 
108
 
 
109
        ANCIL_MAX_N_FDS
 
110
 
 
111
  Maximum number of file descriptors that can be sent with the sent_fds and
 
112
  recv_fds functions. If you have to send more at once, use the
 
113
  *_with_buffer versions. The value is enough to send "quite a few" file
 
114
  descriptors.
 
115
 
 
116
 
 
117
        ANCIL_FD_BUFFER(n)
 
118
          int n: number of file descriptors
 
119
 
 
120
  Expands to a structure data type large enough to hold the system data
 
121
  structures for n file descriptors. So the address of a variable declared
 
122
  of type ANCIL_FD_BUFFER(n) is suitable as the buffer argument for
 
123
  *_with_buffer on n file descriptors.
 
124
  To use this macro, you need <sys/types.h> and <sys/socket.h>. Bevare: with
 
125
  Solaris, the _XPG4_2 macro must be defined before sys/socket is included.
 
126
 
 
127
 
 
128
Tuning the compilation
 
129
 
 
130
  This library is designed to be included in projects, not installed in
 
131
  /usr/lib. If your project does not use some of the functions, the
 
132
  TUNE_OPTS variable in the Makefile allows not to build them. It is a list
 
133
  of proprocessor options:
 
134
 
 
135
  -DNDEBUG: turn assertions off (see assert(3))
 
136
  -DSPARE_SEND_FDS: do not build ancil_send_fds
 
137
  -DSPARE_SEND_FD:  do not build ancil_send_fd
 
138
  -DSPARE_RECV_FDS: do not build ancil_recv_fds
 
139
  -DSPARE_RECV_FD:  do not build ancil_recv_fd