usr/src/man/man3c/door_info.3c

   1 '\" te
   2 .\" Copyright (c) 2005, Sun Microsystems, Inc.  All Rights Reserved.
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH DOOR_INFO 3C "Mar 22, 2005"
   7 .SH NAME
   8 door_info \- return information associated with a door descriptor
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 \fBcc\fR \fB-mt\fR [ \fIflag\fR... ] \fIfile\fR... [ \fIlibrary\fR... ]
  13 #include <door.h>
  14
  15 \fBint\fR \fBdoor_info\fR(\fBint\fR \fId\fR, \fBstruct door_info *\fR\fIinfo\fR);
  16 .fi
  17
  18 .SH DESCRIPTION
  19 .LP
  20 The \fBdoor_info()\fR function returns information associated with a door
  21 descriptor. It obtains information about the door descriptor \fId\fR and places
  22 the information that is relevant to the door in the structure pointed to by the
  23 \fIinfo\fR argument.
  24 .sp
  25 .LP
  26 The \fBdoor_info\fR structure pointed to by the \fIinfo\fR argument contains
  27 the following members:
  28 .sp
  29 .in +2
  30 .nf
  31 pid_t           di_target;      /* door server pid */
  32 door_ptr_t      di_proc;        /* server function */
  33 door_ptr_t      di_data;        /* data cookie for invocation */
  34 door_attr_t     di_attributes;  /* door attributes */
  35 door_id_t       di_uniquifier;  /* unique id among all doors */
  36 .fi
  37 .in -2
  38
  39 .sp
  40 .LP
  41 The \fBdi_target\fR member is the process \fBID\fR of the door server, or
  42 \fB\(mi1\fR if the door server process has exited.
  43 .sp
  44 .LP
  45 The values for \fBdi_attributes\fR may be composed of the following:
  46 .sp
  47 .ne 2
  48 .na
  49 \fB\fBDOOR_LOCAL\fR\fR
  50 .ad
  51 .RS 20n
  52 The door descriptor refers to a service procedure in this process.
  53 .RE
  54
  55 .sp
  56 .ne 2
  57 .na
  58 \fB\fBDOOR_UNREF\fR\fR
  59 .ad
  60 .RS 20n
  61 The door has requested notification when all but the last reference has gone
  62 away.
  63 .RE
  64
  65 .sp
  66 .ne 2
  67 .na
  68 \fB\fBDOOR_UNREF_MULTI\fR\fR
  69 .ad
  70 .RS 20n
  71 Similar to \fBDOOR_UNREF\fR, except multiple unreferenced notifications may be
  72 delivered for this door.
  73 .RE
  74
  75 .sp
  76 .ne 2
  77 .na
  78 \fB\fBDOOR_IS_UNREF\fR\fR
  79 .ad
  80 .RS 20n
  81 There is currently only one descriptor referring to the door.
  82 .RE
  83
  84 .sp
  85 .ne 2
  86 .na
  87 \fB\fBDOOR_REFUSE_DESC\fR\fR
  88 .ad
  89 .RS 20n
  90 The door refuses any attempt to \fBdoor_call\fR(3C) it with argument
  91 descriptors.
  92 .RE
  93
  94 .sp
  95 .ne 2
  96 .na
  97 \fB\fBDOOR_NO_CANCEL\fR\fR
  98 .ad
  99 .RS 20n
 100 Clients who abort a \fBdoor_call\fR(3C) call on this door will not cause the
 101 \fBcancellation\fR(5) of the server thread handling the request.
 102 .RE
 103
 104 .sp
 105 .ne 2
 106 .na
 107 \fB\fBDOOR_REVOKED\fR\fR
 108 .ad
 109 .RS 20n
 110 The door descriptor refers to a door that has been revoked.
 111 .RE
 112
 113 .sp
 114 .ne 2
 115 .na
 116 \fB\fBDOOR_PRIVATE\fR\fR
 117 .ad
 118 .RS 20n
 119 The door has a separate pool of server threads associated with it.
 120 .RE
 121
 122 .sp
 123 .LP
 124 The \fBdi_proc\fR and \fBdi_data\fR members are returned as \fBdoor_ptr_t\fR
 125 objects rather than \fBvoid\fR \fB*\fR pointers to allow clients and servers to
 126 interoperate in environments where the pointer sizes may vary in size (for
 127 example, 32-bit clients and 64-bit servers). Each door has a system-wide unique
 128 number associated with it that is set when the door is created by
 129 \fBdoor_create()\fR. This number is returned in \fBdi_uniquifier\fR.
 130 .SH RETURN VALUES
 131 .LP
 132 Upon successful completion, \fB0\fR is returned. Otherwise, \fB\(mi1\fR is
 133 returned and \fBerrno\fR is set to indicate the error.
 134 .SH ERRORS
 135 .LP
 136 The \fBdoor_info()\fR function will fail if:
 137 .sp
 138 .ne 2
 139 .na
 140 \fB\fBEFAULT\fR\fR
 141 .ad
 142 .RS 10n
 143 The address of argument \fIinfo\fR is an invalid address.
 144 .RE
 145
 146 .sp
 147 .ne 2
 148 .na
 149 \fB\fBEBADF\fR\fR
 150 .ad
 151 .RS 10n
 152 \fId\fR is not a door descriptor.
 153 .RE
 154
 155 .SH ATTRIBUTES
 156 .LP
 157 See \fBattributes\fR(5) for descriptions of the following attributes:
 158 .sp
 159
 160 .sp
 161 .TS
 162 box;
 163 c | c
 164 l | l .
 165 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 166 _
 167 Architecture    all
 168 _
 169 Interface Stability     Stable
 170 _
 171 MT-Level        Safe
 172 .TE
 173
 174 .SH SEE ALSO
 175 .LP
 176 \fBdoor_bind\fR(3C), \fBdoor_call\fR(3C), \fBdoor_create\fR(3C),
 177 \fBdoor_server_create\fR(3C), \fBattributes\fR(5), \fBcancellation\fR(5)