door_create(3c)

1door_create(3C)          Standard C Library Functions          door_create(3C)
2
3
4

NAME

6       door_create - create a door descriptor
7

SYNOPSIS

9       cc -mt [ flag... ] file... [ library... ]
10       #include <door.h>
11
12       int door_create(void (*server_procedure) (void *cookie, char *argp,
13            size_t arg_size, door_desc_t *dp, uint_t n_desc), void *cookie,
14            uint_t attributes);
15
16

DESCRIPTION

18       The door_create() function creates a door descriptor that describes the
19       procedure specified by  the function server_procedure. The  data  item,
20       cookie,  is  associated  with the door descriptor,  and is passed as an
21       argument to the invoked function server_procedure during  door_call(3C)
22       invocations.   Other arguments passed to server_procedure from an asso‐
23       ciated door_call() are placed on the stack and include argp and dp. The
24       argp  argument  points  to  arg_size  bytes of data and the dp argument
25       points to n_desc door_desc_t structures. The attributes argument speci‐
26       fies  attributes   associated with the newly created door. Valid values
27       for attributes are constructed by OR-ing one or more of  the  following
28       values:
29
30       DOOR_UNREF
31
32           Delivers  a  special  invocation  on  the  door  when the number of
33           descriptors that refer to  this door drops to  one.   In  order  to
34           trigger this condition, more than one descriptor must have referred
35           to this door at some time. DOOR_UNREF_DATA designates  an  unrefer‐
36           enced  invocation, as the argp argument passed to server_procedure.
37           In  the  case  of  an  unreferenced  invocation,  the  values   for
38           arg_size,  dp  and n_did are 0. Only one unreferenced invocation is
39           delivered on behalf of a door.
40
41
42       DOOR_UNREF_MULTI
43
44           Similar to DOOR_UNREF, except multiple unreferenced invocations can
45           be  delivered  on the same door if the number of descriptors refer‐
46           ring to the door drops to one more than once.  Since an  additional
47           reference  may have been passed by the time an unreferenced invoca‐
48           tion  arrives,  the  DOOR_IS_UNREF  attribute   returned   by   the
49           door_info(3C)  call  can  be used to determine if the door is still
50           unreferenced.
51
52
53       DOOR_PRIVATE
54
55           Maintains a separate pool of server threads on behalf  of the door.
56           Server  threads  are  associated with a door's  private server pool
57           using  door_bind(3C).
58
59
60       DOOR_REFUSE_DESC
61
62           Any attempt to  call  door_call(3C)  on  this  door  with  argument
63           descriptors  will  fail  with  ENOTSUP.  When this flag is set, the
64           door's server procedure will always be invoked with an n_desc argu‐
65           ment of 0.
66
67
68       DOOR_NO_CANCEL
69
70           Clients  which  abort  calls  to  door_call() on this door will not
71           cause the cancellation of the server thread handling  the  request.
72           See cancellation(5).
73
74
75
76       The  descriptor  returned from door_create() will be marked as close on
77       exec (FD_CLOEXEC). Information  about  a  door  is  available  for  all
78       clients  of a door using door_info(). Applications concerned with secu‐
79       rity should not place secure information in door data that is  accessi‐
80       ble  by door_info(). In particular, secure data should not be stored in
81       the data item cookie.
82
83
84       By default, additional threads are created as needed to handle  concur‐
85       rent door_call() invocations.   See door_server_create(3C) for informa‐
86       tion on how to change this behavior.
87
88
89       A process can advertise a door in the file system name space using fat‐
90       tach(3C).
91
92
93       After  creation,  door_setparam(3C)  can  be  used to set limits on the
94       amount of data and descriptors clients can send over the door.
95

RETURN VALUES

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

ERRORS

101       The door_create() function will fail if:
102
103       EINVAL    Invalid attributes are passed.
104
105
106       EMFILE    The process has too many open descriptors.
107
108

EXAMPLES

110       Example  1 Create a door and use fattach() to advertise the door in the
111       file system namespace.
112
113
114       The following example creates a door and uses  fattach()  to  advertise
115       the door in the file system namespace.
116
117
118         void
119         server(void *cookie, char *argp, size_t arg_size, door_desc_t *dp,
120             uint_t n_desc)
121         {
122             door_return(NULL, 0, NULL, 0);
123             /* NOTREACHED */
124         }
125
126         int
127         main(int argc, char *argv[])
128         {
129             int did;
130             struct stat buf;
131
132             if ((did = door_create(server, 0, 0)) < 0) {
133                 perror("door_create");
134                 exit(1);
135             }
136
137             /* make sure file system location exists */
138             if (stat("/tmp/door", &buf) < 0) {
139                 int newfd;
140                 if ((newfd = creat("/tmp/door", 0444)) < 0) {
141                     perror("creat");
142                     exit(1);
143                 }
144                 (void) close(newfd);
145             }
146
147             /* make sure nothing else is attached */
148             (void) fdetach("/tmp/door");
149
150             /* attach to file system */
151             if (fattach(did, "/tmp/door") < 0) {
152                 perror("fattach");
153                 exit(2);
154             }
155             [...]
156         }
157
158

ATTRIBUTES

160       See attributes(5) for descriptions of the following attributes:
161
162
163
164
165       ┌─────────────────────────────┬─────────────────────────────┐
166       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
167       ├─────────────────────────────┼─────────────────────────────┤
168       │Architecture                 │all                          │
169       ├─────────────────────────────┼─────────────────────────────┤
170       │Availability                 │SUNWcsu                      │
171       ├─────────────────────────────┼─────────────────────────────┤
172       │Interface Stability          │Committed                    │
173       ├─────────────────────────────┼─────────────────────────────┤
174       │MT-Level                     │Safe                         │
175       └─────────────────────────────┴─────────────────────────────┘
176