door_create(3DOOR) Door Library Functions door_create(3DOOR)
NAME
door_create - create a door descriptor
SYNOPSIS
cc -mt [ flag ... ] file ... -ldoor [ 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(3DOOR) 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(3DOOR) 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(3DOOR).
DOOR_REFUSE_DESC Any attempt to door_call(3DOOR) 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.
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(3DOOR). 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(3DOOR) invocations. See door_server_create(3DOOR) for
information on how to change this behavior.
A process can advertise a door in the file system name space using fattach(3C).
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;
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
See attributes(5) for descriptions of the following attributes:
+-----------------------------+-----------------------------+
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+-----------------------------+-----------------------------+
|Architecture |all |
+-----------------------------+-----------------------------+
|Availability |SUNWcsu |
+-----------------------------+-----------------------------+
|Interface Stability |Evolving |
+-----------------------------+-----------------------------+
|MT-Level |Safe |
+-----------------------------+-----------------------------+
SEE ALSO
door_bind(3DOOR), door_call(3DOOR), door_info(3DOOR), door_revoke(3DOOR), door_server_create(3DOOR), fattach(3C), libdoor(3LIB),
attributes(5)
SunOS 5.10 10 Mar 2003 door_create(3DOOR)