NAME

door_create − create a door descriptor

SYNOPSIS

#include <door.h>
int door_create (void (∗server_procedure) (void ∗cookie, char ∗argp,

size_t arg_size, door_desc_t ∗dp, size_t n_desc),

void ∗cookie, u_int 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(3X) invocations.  Other arguments passed to server_procedure from an associated door_call() are placed on the stack and include argp and dp. argp points to arg_size bytes of data and dp points to n_desc door_desc_t structures.  The attributes flag specifies attributes associated with the newly created door.  Valid values for attributes are constructed by OR-ing in 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_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(3X). 

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(3X).  Programs 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.

RETURN VALUES

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

ERRORS

The door_create() function fails if one or more of the following are true:

EINVAL Invalid attributes are passed. 

EMFILE The process has too many open descriptors. 

ATTRIBUTES

See attributes(5) for descriptions of the following attributes:

SEE ALSO

door_bind(3X), door_call(3X), door_info(3X), door_revoke(3X), door_server_create(3X), attributes(5)

SunOS 5.6  —  Last change: 13 Feb 1997