Standard C Library Functions doorcall(3C)
NAME
doorcall - invoke the function associated with a door
descriptor
SYNOPSIS
cc -mt [ flag... ] file... [ library... ]
#include
int doorcall(int d, doorargt *params);
DESCRIPTION
The doorcall() 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
NUL for params indicates there are no arguments to be
passed and no results expected.
Arguments are specified using the dataptr and descptr
members of params. The size of the argument data in bytes is
passed in datasize and the number of argument descriptors
is passed in descnum.
Results from the door invocation are placed in the buffer,
rbuf. See doorreturn(3C). The dataptr and descptr
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 datasize and descnum members. It is acceptable to use
the same buffer for input argument data and results, so
doorcall() may be called with dataptr and descptr point-
ing to the buffer rbuf.
If the results of a door invocation exceed the size of the
buffer specified by rsize, the system automatically allo-
cates 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 doordesct structure are identified
by the dattributes member. The client marks the
dattributes 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
SunOS 5.11 Last change: 22 Mar 2005 1
Standard C Library Functions doorcall(3C)
descriptor, denoted by the DORDESCRIPTOR attribute. Addi-
tionally, the DORELEASE 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 doorcall() returns an error, unless that
error is EFAULT or EBADF.
The doordesct structure includes the following members:
typedef struct {
doorattrt dattributes; /* Describes the parameter */
union {
struct {
int ddescriptor; /* Descriptor */
dooridt did; /* Unique door id */
} ddesc;
} ddata;
} doordesct;
When file descriptors are passed or returned, a new
descriptor is created in the target address space and the
ddescriptor 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
doorid member and marks the dattributes member with other
attributes associated with a door including the following:
DORLOCAL The door received was created by this
process using doorcreate(). See
doorcreate(3C).
DORPRIVATE The door received has a private pool of
server threads associated with the door.
DORUNREF The door received is expecting an
unreferenced notification.
DORUNREFMULTI Similar to DORUNREF, except multiple
unreferenced notifications may be
delivered for the same door.
DOREFUSEDESC This door does not accept argument
descriptors.
SunOS 5.11 Last change: 22 Mar 2005 2
Standard C Library Functions doorcall(3C)
DORNOCANCEL This door does not cancel the server
thread upon client abort.
DOREVOKED The door received has been revoked by
the server.
The doorcall() 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
doorcall() operation. If the client aborts in the middle of
a doorcall() and the door was not created with the
DORNOCANCEL flag, the server thread is notified using the
POSIX (see standards(5)) thread cancellation mechanism. See
cancellation(5).
The descriptor returned from doorcreate() is marked as
close on exec(FDCLOEXEC). Information about a door is
available for all clients of a door using doorinfo().
Applications concerned with security should not place secure
information in door data that is accessible by doorinfo().
In particular, secure data should not be stored in the data
item cookie. See doorinfo(3C).
RETURN VALUES
Upon successful completion, 0 is returned. Otherwise, -1 is
returned and errno is set to indicate the error.
ERORS
The doorcall() 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.
SunOS 5.11 Last change: 22 Mar 2005 3
Standard C Library Functions doorcall(3C)
EINVAL Bad arguments were passed.
EMFILE The client or server has too many open descrip-
tors.
ENFILE The descnum argument is larger than the door's
DORPARAMDESCMAX parameter (see
doorgetparam(3C)), and the door does not have
the DOREFUSEDESC set.
ENOBUFS The datasize argument is larger than the
door's DORPARAMDATAMAX parameter, or
smaller than the door's DORPARAMDATAMIN
parameter (see doorgetparam(3C)).
ENOTSUP The descnum argument is non-zero and the door
has the DOREFUSEDESC flag set.
EOVERFLOW System could not create overflow area in caller
for results.
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
SunOS 5.11 Last change: 22 Mar 2005 4
Standard C Library Functions doorcall(3C)
ATRIBUTE TYPE ATRIBUTE VALUE
Architecture all
Availability SUNWcsu
Interface Stability Stable
MT-Level Safe
SEE ALSO
munmap(2), doorcreate(3C), doorgetparam(3C)doorinfo(3C),
doorreturn(3C), libdoor(3LIB), attributes(5), cancella-
tion(5), standards(5)
SunOS 5.11 Last change: 22 Mar 2005 5
|
