Manual Pages for UNIX Operating System command usage for man door_create

Standard C Library Functions                      door_create(3C)



NAME
     door_create - create a door descriptor

SYNOPSIS
     cc -mt [ flag... ] file... [ library... ]
     #include 

     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) invo-
     cations.  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 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:

     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.





SunOS 5.11          Last change: 22 Jan 2008                    1






Standard C Library Functions                      door_create(3C)



     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(5).



     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 han-
     dle     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.





SunOS 5.11          Last change: 22 Jan 2008                    2






Standard C Library Functions                      door_create(3C)



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



SunOS 5.11          Last change: 22 Jan 2008                    3






Standard C Library Functions                      door_create(3C)



               perror("fattach");
               exit(2);
           }
           [...]
       }


ATTRIBUTES
     See attributes(5) for descriptions of the  following  attri-
     butes:



     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | Architecture                | all                         |
    |_____________________________|_____________________________|
    | Availability                | SUNWcs                      |
    |_____________________________|_____________________________|
    | Interface Stability         | Committed                   |
    |_____________________________|_____________________________|
    | MT-Level                    | Safe                        |
    |_____________________________|_____________________________|


SEE ALSO
     door_bind(3C),         door_call(3C),         door_info(3C),
     door_revoke(3C),  door_setparam(3C), door_server_create(3C),
     fattach(3C), libdoor(3LIB), attributes(5), cancellation(5)

























SunOS 5.11          Last change: 22 Jan 2008                    4