Standard C Library Functions doorcreate(3C)
NAME
doorcreate - create a door descriptor
SYNOPSIS
cc -mt [ flag... ] file... [ library... ]
#include
int doorcreate(void (*serverprocedure) (void *cookie, char *argp,
sizet argsize, doordesct *dp, uintt ndesc), void *cookie,
uintt attributes);
DESCRIPTION
The doorcreate() function creates a door descriptor that
describes the procedure specified by the function
serverprocedure. The data item, cookie, is associated with
the door descriptor, and is passed as an argument to the
invoked function serverprocedure during doorcall(3C) invo-
cations. Other arguments passed to serverprocedure from an
associated doorcall() are placed on the stack and include
argp and dp. The argp argument points to argsize bytes of
data and the dp argument points to ndesc doordesct struc-
tures. The attributes argument specifies attributes associ-
ated with the newly created door. Valid values for attri-
butes are constructed by OR-ing one or more of the following
values:
DORUNREF
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.
DORUNREFDATA designates an unreferenced invocation,
as the argp argument passed to serverprocedure. In the
case of an unreferenced invocation, the values for
argsize, dp and ndid are 0. Only one unreferenced
invocation is delivered on behalf of a door.
DORUNREFMULTI
Similar to DORUNREF, 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 DORISUNREF attribute returned by the
doorinfo(3C) call can be used to determine if the door
is still unreferenced.
SunOS 5.11 Last change: 22 Jan 2008 1
Standard C Library Functions doorcreate(3C)
DORPRIVATE
Maintains a separate pool of server threads on behalf
of the door. Server threads are associated with a door's
private server pool using doorbind(3C).
DOREFUSEDESC
Any attempt to call doorcall(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 ndesc argument of 0.
DORNOCANCEL
Clients which abort calls to doorcall() on this door
will not cause the cancellation of the server thread
handling the request. See cancellation(5).
The descriptor returned from doorcreate() will be 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.
By default, additional threads are created as needed to han-
dle concurrent doorcall() invocations. See
doorservercreate(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, doorsetparam(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, doorcreate() returns a non-
negative value. Otherwise, doorcreate returns -1 and sets
errno to indicate the error.
SunOS 5.11 Last change: 22 Jan 2008 2
Standard C Library Functions doorcreate(3C)
ERORS
The doorcreate() 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, sizet argsize, doordesct *dp,
uintt ndesc)
{
doorreturn(NUL, 0, NUL, 0);
/* NOTREACHED */
}
int
main(int argc, char *argv[])
{
int did;
struct stat buf;
if ((did = doorcreate(server, 0, 0)) < 0) {
perror("doorcreate");
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) {
SunOS 5.11 Last change: 22 Jan 2008 3
Standard C Library Functions doorcreate(3C)
perror("fattach");
exit(2);
}
[...]
}
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
Architecture all
Availability SUNWcsu
Interface Stability Committed
MT-Level Safe
SEE ALSO
doorbind(3C), doorcall(3C), doorinfo(3C),
doorrevoke(3C), doorsetparam(3C), doorservercreate(3C),
fattach(3C), libdoor(3LIB), attributes(5), cancellation(5)
SunOS 5.11 Last change: 22 Jan 2008 4
|
