Tribblix: manual page: door

DOOR_CREATE(3C) Standard C Library Functions DOOR_CREATE(3C)

NAME

door_create - create a door descriptor

SYNOPSIS

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);

DESCRIPTION

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.

RETURN VALUES

Upon successful completion, door_create() returns a non-negative
value. Otherwise, door_create returns -1 and sets errno to indicate
the error.

ERRORS

The door_create() function will fail if:

EINVAL
Invalid attributes are passed.

EMFILE
The process has too many open descriptors.

EXAMPLES

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);
}
[...]
}

ATTRIBUTES