door_create man page on SmartOS

Man page or keyword search:  
man Server   16655 pages
apropos Keyword Search (all sections)
Output format
SmartOS logo
[printable version]

DOOR_CREATE(3C)						       DOOR_CREATE(3C)

NAME
       door_create - create a door descriptor

SYNOPSIS
       cc -mt [ flag... ] file... [ 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(3C)
       invocations.   Other arguments passed to server_procedure from an asso‐
       ciated 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 speci‐
       fies  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  unrefer‐
	   enced  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 refer‐
	   ring to the door drops to one more than once.  Since an  additional
	   reference  may have been passed by the time an unreferenced invoca‐
	   tion	 arrives,  the	DOOR_IS_UNREF  attribute   returned   by   the
	   door_info(3C)  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(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 argu‐
	   ment 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 secu‐
       rity should not place secure information in door data that is  accessi‐
       ble  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  concur‐
       rent door_call() invocations.   See door_server_create(3C) for informa‐
       tion on how to change this behavior.

       A process can advertise a door in the file system name space using fat‐
       tach(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.

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) {
		 perror("fattach");
		 exit(2);
	     }
	     [...]
	 }

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

       ┌────────────────────┬─────────────────┐
       │  ATTRIBUTE TYPE    │ ATTRIBUTE VALUE │
       ├────────────────────┼─────────────────┤
       │Architecture	    │ all	      │
       ├────────────────────┼─────────────────┤
       │Interface Stability │ Committed	      │
       ├────────────────────┼─────────────────┤
       │MT-Level	    │ Safe	      │
       └────────────────────┴─────────────────┘

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

				 Jan 22, 2008		       DOOR_CREATE(3C)
[top]

List of man pages available for SmartOS

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net