DOOR_CALL(3C) Standard C Library Functions DOOR_CALL(3C)
NAME
door_call - invoke the function associated with a door descriptor
SYNOPSIS
cc -mt [
flag... ]
file... [
library... ]
#include <door.h>
int door_call(
int d,
door_arg_t *params);
DESCRIPTION
The
door_call() function invokes the function associated with the door
descriptor
d, and passes the arguments (if any) specified in
params. All
of the
params members are treated as in/out parameters during a door
invocation and may be updated upon returning from a door call. Passing
NULL for
params indicates there are no arguments to be passed and no
results expected.
The
door_arg_t structure includes the following members:
typedef struct {
char *data_ptr; /* Argument/result data */
size_t data_size; /* Argument/result data size */
door_desc_t *desc_ptr; /* Argument/result descriptors */
uint_t desc_num; /* Argument/result num descriptors */
char *rbuf; /* Result area */
size_t rsize; /* Result size */
} door_arg_t;
The
door_desc_t structure includes the following members:
typedef struct {
door_attr_t d_attributes; /* Describes the parameter */
union {
struct {
int d_descriptor; /* Descriptor */
door_id_t d_id; /* Unique door id */
} d_desc;
} d_data;
} door_desc_t;
Arguments are specified using the
data_ptr and
desc_ptr members of
params. The size of the argument data in bytes is passed in
data_size and
the number of argument descriptors is passed in
desc_num.
Results from the door invocation are placed in the buffer,
rbuf. See
door_return(3C). The
data_ptr and
desc_ptr members of
params are updated
to reflect the location of the results within the
rbuf buffer. The size
of the data results and number of descriptors returned are updated in the
data_size and
desc_num members. It is acceptable to use the same buffer
for input argument data and results, so
door_call() may be called with
data_ptr and
desc_ptr pointing to the buffer
rbuf.
If the results of a door invocation exceed the size of the buffer
specified by
rsize, the system automatically allocates a new buffer in
the caller's address space and updates the
rbuf and
rsize members to
reflect this location. In this case, the caller is responsible for
reclaiming this area using
munmap(rbuf, rsize) when the buffer is no
longer required. See
munmap(2).
Descriptors passed in a
door_desc_t structure are identified by the
d_attributes member. The client marks the
d_attributes member with the
type of object being passed by logically OR-ing the value of object type.
Currently, the only object type that can be passed or returned is a file
descriptor, denoted by the
DOOR_DESCRIPTOR attribute. Additionally, the
DOOR_RELEASE attribute can be set, causing the descriptor to be closed in
the caller's address space after it is passed to the target. The
descriptor will be closed even if
door_call() returns an error, unless
that error is
EFAULT or
EBADF.
When file descriptors are passed or returned, a new descriptor is created
in the target address space and the
d_descriptor member in the target
argument is updated to reflect the new descriptor. In addition, the
system passes a system-wide unique number associated with each door in
the
d_id member and marks the
d_attributes member with other attributes
associated with a door including the following:
DOOR_LOCAL The door received was created by this process using
door_create(). See
door_create(3C).
DOOR_PRIVATE The door received has a private pool of server
threads associated with the door.
DOOR_UNREF The door received is expecting an unreferenced
notification.
DOOR_UNREF_MULTI Similar to
DOOR_UNREF, except multiple unreferenced
notifications may be delivered for the same door.
DOOR_REFUSE_DESC This door does not accept argument descriptors.
DOOR_NO_CANCEL This door does not cancel the server thread upon
client abort.
DOOR_REVOKED The door received has been revoked by the server.
The
door_call() function is not a restartable system call. It returns
EINTR if a signal was caught and handled by this thread. If the door
invocation is not idempotent the caller should mask any signals that may
be generated during a
door_call() operation. If the client aborts in the
middle of a
door_call() and the door was not created with the
DOOR_NO_CANCEL flag, the server thread is notified using the POSIX (see
standards(7)) thread cancellation mechanism. See
cancellation(7).
RETURN VALUES
Upon successful completion,
0 is returned. Otherwise,
-1 is returned and
errno is set to indicate the error.
ERRORS
The
door_call() function will fail if:
E2BIG Arguments were too big for server thread stack.
EAGAIN Server was out of available resources.
EBADF Invalid door descriptor was passed.
EFAULT Argument pointers pointed outside the allocated address
space.
EINTR A signal was caught in the client, the client called
fork(2), or the server exited during invocation.
EINVAL Bad arguments were passed.
EMFILE The client or server has too many open descriptors.
ENFILE The
desc_num argument is larger than the door's
DOOR_PARAM_DESC_MAX parameter (see
door_getparam(3C)), and
the door does not have the
DOOR_REFUSE_DESC set.
ENOBUFS The
data_size argument is larger than the door's
DOOR_PARAM_DATA_MAX parameter, or smaller than the door's
DOOR_PARAM_DATA_MIN parameter (see
door_getparam(3C)).
ENOTSUP The
desc_num argument is non-zero and the door has the
DOOR_REFUSE_DESC flag set.
EOVERFLOW System could not create overflow area in caller for results.
ATTRIBUTES
See
attributes(7) for descriptions of the following attributes:
+--------------------+-----------------+
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+--------------------+-----------------+
|Architecture | all |
+--------------------+-----------------+
|Interface Stability | Stable |
+--------------------+-----------------+
|MT-Level | Safe |
+--------------------+-----------------+
SEE ALSO
munmap(2),
door_create(3C),
door_getparam(3C),
door_info(3C),
door_return(3C),
libdoor(3LIB),
attributes(7),
cancellation(7),
standards(7) February 7, 2015
DOOR_CALL(3C)