door_create - create a door descriptor
cc -mt [ flag... ] file... [ library... ]
#include <door.h>
int door_create(void (*server_procedure) (void *cookie, char *argp,
size_t arg_size, door_desc_t *dp, uint_t n_desc), void *cookie,
uint_t attributes);
The door_create() function creates a door descriptor that describes the
procedure specified by the function server_procedure. The data item,
cookie, is associated with the door descriptor, and is passed as an
argument to the invoked function server_procedure during
door_call(3C) invocations. Other arguments passed to
server_procedure from an associated door_call() are placed on
the stack and include argp and dp. The argp argument
points to arg_size bytes of data and the dp argument points to
n_desc door_desc_t structures. The attributes argument
specifies attributes associated with the newly created door. Valid values for
attributes are constructed by OR-ing one or more of the following
values:
DOOR_UNREF
Delivers a special invocation on the door when the number
of descriptors that refer to this door drops to one. In order to trigger this
condition, more than one descriptor must have referred to this door at some
time. DOOR_UNREF_DATA designates an unreferenced invocation, as the
argp argument passed to server_procedure. In the case of an
unreferenced invocation, the values for arg_size, dp and
n_did are 0. Only one unreferenced invocation is delivered on
behalf of a door.
DOOR_UNREF_MULTI
Similar to
DOOR_UNREF, except multiple
unreferenced invocations can be delivered on the same door if the number of
descriptors referring to the door drops to one more than once. Since an
additional reference may have been passed by the time an unreferenced
invocation arrives, the
DOOR_IS_UNREF attribute returned by the
door_info(3C) call can be used to determine if the door is still
unreferenced.
DOOR_PRIVATE
Maintains a separate pool of server threads on behalf of
the door. Server threads are associated with a door's private server pool
using
door_bind(3C).
DOOR_REFUSE_DESC
Any attempt to call
door_call(3C) on this door
with argument descriptors will fail with
ENOTSUP. When this flag is
set, the door's server procedure will always be invoked with an
n_desc
argument of 0.
DOOR_NO_CANCEL
Clients which abort calls to
door_call() on this
door will not cause the cancellation of the server thread handling the
request. See
cancellation(7).
The descriptor returned from door_create() will be marked
as close on exec (FD_CLOEXEC). Information about a door is available
for all clients of a door using door_info(). Applications concerned
with security should not place secure information in door data that is
accessible by door_info(). In particular, secure data should not be
stored in the data item cookie.
By default, additional threads are created as needed to handle
concurrent door_call() invocations. See door_server_create(3C)
for information on how to change this behavior.
A process can advertise a door in the file system name space using
fattach(3C).
After creation, door_setparam(3C) can be used to set limits
on the amount of data and descriptors clients can send over the door.
Upon successful completion, door_create() returns a non-negative value.
Otherwise, door_create returns −1 and sets errno
to indicate the error.
The door_create() function will fail if:
EINVAL
Invalid attributes are passed.
EMFILE
The process has too many open descriptors.
Example 1 Create a door and use fattach() to advertise the door in
the file system namespace.
The following example creates a door and uses fattach() to
advertise the door in the file system namespace.
void
server(void *cookie, char *argp, size_t arg_size, door_desc_t *dp,
uint_t n_desc)
{
door_return(NULL, 0, NULL, 0);
/* NOTREACHED */
}
int
main(int argc, char *argv[])
{
int did;
struct stat buf;
if ((did = door_create(server, 0, 0)) < 0) {
perror("door_create");
exit(1);
}
/* make sure file system location exists */
if (stat("/tmp/door", &buf) < 0) {
int newfd;
if ((newfd = creat("/tmp/door", 0444)) < 0) {
perror("creat");
exit(1);
}
(void) close(newfd);
}
/* make sure nothing else is attached */
(void) fdetach("/tmp/door");
/* attach to file system */
if (fattach(did, "/tmp/door") < 0) {
perror("fattach");
exit(2);
}
[...]
}
See attributes(7) for descriptions of the following attributes:
| ATTRIBUTE
TYPE |
ATTRIBUTE VALUE |
| Architecture |
all |
| Interface Stability |
Committed |
| MT-Level |
Safe |