1door_call(3C) Standard C Library Functions door_call(3C)
2
6 door_call - invoke the function associated with a door descriptor
7
9 cc -mt [ flag... ] file... [ library... ]
10 #include <door.h>
11 int door_call(int d, door_arg_t *params);
13
16 The door_call() function invokes the function associated with the door
17 descriptor d, and passes the arguments (if any) specified in params.
18 All of the params members are treated as in/out parameters during a
19 door invocation and may be updated upon returning from a door call.
20 Passing NULL for params indicates there are no arguments to be passed
21 and no results expected.
22 Arguments are specified using the data_ptr and desc_ptr members of
25 params. The size of the argument data in bytes is passed in data_size
26 and the number of argument descriptors is passed in desc_num.
27 Results from the door invocation are placed in the buffer, rbuf. See
30 door_return(3C). The data_ptr and desc_ptr members of params are
31 updated to reflect the location of the results within the rbuf buffer.
32 The size of the data results and number of descriptors returned are
33 updated in the data_size and desc_num members. It is acceptable to use
34 the same buffer for input argument data and results, so door_call()
35 may be called with data_ptr and desc_ptr pointing to the buffer rbuf.
36 If the results of a door invocation exceed the size of the buffer spec‐
39 ified by rsize, the system automatically allocates a new buffer in the
40 caller's address space and updates the rbuf and rsize members to
41 reflect this location. In this case, the caller is responsible for
42 reclaiming this area using munmap(rbuf, rsize) when the buffer is no
43 longer required. See munmap(2).
44 Descriptors passed in a door_desc_t structure are identified by the
47 d_attributes member. The client marks the d_attributes member with the
48 type of object being passed by logically OR-ing the value of object
49 type. Currently, the only object type that can be passed or returned is
50 a file descriptor, denoted by the DOOR_DESCRIPTOR attribute. Addition‐
51 ally, the DOOR_RELEASE attribute can be set, causing the descriptor to
52 be closed in the caller's address space after it is passed to the tar‐
53 get. The descriptor will be closed even if door_call() returns an
54 error, unless that error is EFAULT or EBADF.
55 The door_desc_t structure includes the following members:
58 typedef struct {
60 door_attr_t d_attributes; /* Describes the parameter */
61 union {
62 struct {
63 int d_descriptor; /* Descriptor */
64 door_id_t d_id; /* Unique door id */
65 } d_desc;
66 } d_data;
67 } door_desc_t;
68 When file descriptors are passed or returned, a new descriptor is cre‐
72 ated in the target address space and the d_descriptor member in the
73 target argument is updated to reflect the new descriptor. In addition,
74 the system passes a system-wide unique number associated with each door
75 in the door_id member and marks the d_attributes member with other
76 attributes associated with a door including the following:
77 DOOR_LOCAL The door received was created by this process
79 using door_create(). See door_create(3C).
80 DOOR_PRIVATE The door received has a private pool of server
83 threads associated with the door.
84 DOOR_UNREF The door received is expecting an unreferenced
87 notification.
88 DOOR_UNREF_MULTI Similar to DOOR_UNREF, except multiple unrefer‐
91 enced notifications may be delivered for the same
92 door.
93 DOOR_REFUSE_DESC This door does not accept argument descriptors.
96 DOOR_NO_CANCEL This door does not cancel the server thread upon
99 client abort.
100 DOOR_REVOKED The door received has been revoked by the server.
103 The door_call() function is not a restartable system call. It returns
107 EINTR if a signal was caught and handled by this thread. If the door
108 invocation is not idempotent the caller should mask any signals that
109 may be generated during a door_call() operation. If the client aborts
110 in the middle of a door_call() and the door was not created with the
111 DOOR_NO_CANCEL flag, the server thread is notified using the POSIX (see
112 standards(5)) thread cancellation mechanism. See cancellation(5).
113 The descriptor returned from door_create() is marked as close on
116 exec(FD_CLOEXEC). Information about a door is available for all clients
117 of a door using door_info(). Applications concerned with security
118 should not place secure information in door data that is accessible by
119 door_info(). In particular, secure data should not be stored in the
120 data item cookie. See door_info(3C).
121
123 Upon successful completion, 0 is returned. Otherwise, −1 is returned
124 and errno is set to indicate the error.
125
127 The door_call() function will fail if:
128 E2BIG Arguments were too big for server thread stack.
130 EAGAIN Server was out of available resources.
133 EBADF Invalid door descriptor was passed.
136 EFAULT Argument pointers pointed outside the allocated address
139 space.
140 EINTR A signal was caught in the client, the client called
143 fork(2), or the server exited during invocation.
144 EINVAL Bad arguments were passed.
147 EMFILE The client or server has too many open descriptors.
150 ENFILE The desc_num argument is larger than the door's
153 DOOR_PARAM_DESC_MAX parameter (see door_getparam(3C)), and
154 the door does not have the DOOR_REFUSE_DESC set.
155 ENOBUFS The data_size argument is larger than the door's
158 DOOR_PARAM_DATA_MAX parameter, or smaller than the door's
159 DOOR_PARAM_DATA_MIN parameter (see door_getparam(3C)).
160 ENOTSUP The desc_num argument is non-zero and the door has the
163 DOOR_REFUSE_DESC flag set.
164 EOVERFLOW System could not create overflow area in caller for
167 results.
168
171 See attributes(5) for descriptions of the following attributes:
172 ┌─────────────────────────────┬─────────────────────────────┐
177 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
178 ├─────────────────────────────┼─────────────────────────────┤
179 │Architecture │all │
180 ├─────────────────────────────┼─────────────────────────────┤
181 │Availability │SUNWcsu │
182 ├─────────────────────────────┼─────────────────────────────┤
183 │Interface Stability │Stable │
184 ├─────────────────────────────┼─────────────────────────────┤
185 │MT-Level │Safe │
186 └─────────────────────────────┴─────────────────────────────┘
187
189 munmap(2), door_create(3C), door_getparam(3C), door_info(3C),
190 door_return(3C), libdoor(3LIB), attributes(5), cancellation(5), stan‐
191 dards(5)
192SunOS 5.11 22 Mar 2005 door_call(3C)