From d993cb83958d44b76c7c56393113c24811dde5f7 Mon Sep 17 00:00:00 2001 From: Ryan Zezeski Date: Wed, 10 May 2017 22:03:31 -0600 Subject: [PATCH] 8202 doors man pages contain extra whitespace 5180 door_server_create(3c): Incomplete return type Reviewed by: Marcel Telka Reviewed by: Jason King Reviewed by: Peter Tribble Approved by: Robert Mustacchi --- usr/src/man/man3c/door_bind.3c | 19 ++++------ usr/src/man/man3c/door_call.3c | 36 +++++++++---------- usr/src/man/man3c/door_create.3c | 27 ++++++-------- usr/src/man/man3c/door_cred.3c | 12 ++----- usr/src/man/man3c/door_getparam.3c | 2 +- usr/src/man/man3c/door_info.3c | 17 ++++----- usr/src/man/man3c/door_return.3c | 9 ++--- usr/src/man/man3c/door_revoke.3c | 13 +++---- usr/src/man/man3c/door_server_create.3c | 64 ++++++++++++++++----------------- usr/src/man/man3c/door_ucred.3c | 7 +--- usr/src/man/man3lib/libdoor.3lib | 9 ++--- 11 files changed, 85 insertions(+), 130 deletions(-) diff --git a/usr/src/man/man3c/door_bind.3c b/usr/src/man/man3c/door_bind.3c index 277758508f..59f879d020 100644 --- a/usr/src/man/man3c/door_bind.3c +++ b/usr/src/man/man3c/door_bind.3c @@ -22,7 +22,6 @@ server pool .fi .SH DESCRIPTION -.sp .LP The \fBdoor_bind()\fR function associates the current thread with a door server pool. A door server pool is a private pool of server threads that is available @@ -34,22 +33,22 @@ removing any private door pool binding that is associated with the current thread. .sp .LP -Normally, door server threads are placed in a global pool of available threads +Normally, door server threads are placed in a global pool of available threads that invocations on any door can use to dispatch a door invocation. A door that has been created with \fBDOOR_PRIVATE\fR only uses server threads that have been associated with the door by \fBdoor_bind()\fR. It is therefore necessary -to bind at least one server thread to doors created with \fBDOOR_PRIVATE\fR. +to bind at least one server thread to doors created with \fBDOOR_PRIVATE\fR. .sp .LP The server thread create function, \fBdoor_server_create()\fR, is initially called by the system during a \fBdoor_create()\fR operation. See -\fBdoor_server_create\fR(3C) and \fBdoor_create\fR(3C). +\fBdoor_server_create\fR(3C) and \fBdoor_create\fR(3C). .sp .LP -The current thread is added to the private pool of server threads associated +The current thread is added to the private pool of server threads associated with a door during the next \fBdoor_return()\fR (that has been issued by the -current thread after an associated \fBdoor_bind()\fR). See -\fBdoor_return\fR(3C). A server thread performing a \fBdoor_bind()\fR on a +current thread after an associated \fBdoor_bind()\fR). See +\fBdoor_return\fR(3C). A server thread performing a \fBdoor_bind()\fR on a door that is already bound to a different door performs an implicit \fBdoor_unbind()\fR of the previous door. .sp @@ -58,14 +57,12 @@ If a process containing threads that have been bound to a door calls \fBfork\fR(2), the threads in the child process will be bound to an invalid door, and any calls to \fBdoor_return\fR(3C) will result in an error. .SH RETURN VALUES -.sp .LP Upon successful completion, a \fB0\fR is returned. Otherwise, \fB\(mi1\fR is returned and \fBerrno\fR is set to indicate the error. .SH ERRORS -.sp .LP -The \fBdoor_bind()\fR and \fBdoor_unbind()\fR functions fail if: +The \fBdoor_bind()\fR and \fBdoor_unbind()\fR functions fail if: .sp .ne 2 .na @@ -174,7 +171,6 @@ main() .in -2 .SH ATTRIBUTES -.sp .LP See \fBattributes\fR(5) for descriptions of the following attributes: .sp @@ -194,7 +190,6 @@ MT-Level Safe .TE .SH SEE ALSO -.sp .LP \fBfork\fR(2),\fBdoor_create\fR(3C), \fBdoor_return\fR(3C), \fBdoor_server_create\fR(3C), \fBattributes\fR(5) diff --git a/usr/src/man/man3c/door_call.3c b/usr/src/man/man3c/door_call.3c index f0c470fb24..c2e7515365 100644 --- a/usr/src/man/man3c/door_call.3c +++ b/usr/src/man/man3c/door_call.3c @@ -19,10 +19,10 @@ door_call \- invoke the function associated with a door descriptor .SH DESCRIPTION .LP The \fBdoor_call()\fR function invokes the function associated with the door -descriptor \fId\fR, and passes the arguments (if any) specified in -\fIparams\fR. All of the \fIparams\fR members are treated as in/out parameters -during a door invocation and may be updated upon returning from a door call. -Passing \fINULL\fR for \fIparams\fR indicates there are no arguments to be +descriptor \fId\fR, and passes the arguments (if any) specified in +\fIparams\fR. All of the \fIparams\fR members are treated as in/out parameters +during a door invocation and may be updated upon returning from a door call. +Passing \fINULL\fR for \fIparams\fR indicates there are no arguments to be passed and no results expected. .sp .LP @@ -34,7 +34,7 @@ typedef struct { char *data_ptr; /* Argument/result data */ size_t data_size; /* Argument/result data size */ door_desc_t *desc_ptr; /* Argument/result descriptors */ - uint_t desc_num; /* Argument/result num discriptors */ + uint_t desc_num; /* Argument/result num descriptors */ char *rbuf; /* Result area */ size_t rsize; /* Result size */ } door_arg_t; @@ -61,26 +61,26 @@ typedef struct { .sp .LP -Arguments are specified using the \fBdata_ptr\fR and \fBdesc_ptr\fR members of +Arguments are specified using the \fBdata_ptr\fR and \fBdesc_ptr\fR members of \fIparams\fR. The size of the argument data in bytes is passed in \fBdata_size\fR and the number of argument descriptors is passed in \fBdesc_num\fR. .sp .LP Results from the door invocation are placed in the buffer, \fBrbuf\fR. See -\fBdoor_return\fR(3C). The \fBdata_ptr\fR and \fBdesc_ptr\fR members of +\fBdoor_return\fR(3C). The \fBdata_ptr\fR and \fBdesc_ptr\fR members of \fIparams\fR are updated to reflect the location of the results within the \fBrbuf\fR buffer. The size of the data results and number of descriptors returned are updated in the \fBdata_size\fR and \fBdesc_num\fR members. It is -acceptable to use the same buffer for input argument data and results, so +acceptable to use the same buffer for input argument data and results, so \fBdoor_call()\fR may be called with \fBdata_ptr\fR and \fBdesc_ptr\fR pointing to the buffer \fBrbuf\fR. .sp .LP If the results of a door invocation exceed the size of the buffer specified by -\fBrsize\fR, the system automatically allocates a new buffer in the caller's -address space and updates the \fBrbuf\fR and \fBrsize\fR members to reflect -this location. In this case, the caller is responsible for reclaiming this +\fBrsize\fR, the system automatically allocates a new buffer in the caller's +address space and updates the \fBrbuf\fR and \fBrsize\fR members to reflect +this location. In this case, the caller is responsible for reclaiming this area using \fBmunmap(rbuf, rsize)\fR when the buffer is no longer required. See \fBmunmap\fR(2). .sp @@ -89,14 +89,14 @@ Descriptors passed in a \fBdoor_desc_t\fR structure are identified by the \fBd_attributes\fR member. The client marks the \fBd_attributes\fR member with the type of object being passed by logically OR-ing the value of object type. Currently, the only object type that can be passed or returned is a file -descriptor, denoted by the \fBDOOR_DESCRIPTOR\fR attribute. Additionally, the -\fBDOOR_RELEASE\fR attribute can be set, causing the descriptor to be closed +descriptor, denoted by the \fBDOOR_DESCRIPTOR\fR attribute. Additionally, the +\fBDOOR_RELEASE\fR attribute can be set, causing the descriptor to be closed in the caller's address space after it is passed to the target. The descriptor -will be closed even if \fBdoor_call()\fR returns an error, unless that error +will be closed even if \fBdoor_call()\fR returns an error, unless that error is \fBEFAULT\fR or \fBEBADF\fR. .sp .LP -When file descriptors are passed or returned, a new descriptor is created in +When file descriptors are passed or returned, a new descriptor is created in the target address space and the \fBd_descriptor\fR member in the target argument is updated to reflect the new descriptor. In addition, the system passes a system-wide unique number associated with each door in the @@ -108,7 +108,7 @@ attributes associated with a door including the following: \fB\fBDOOR_LOCAL\fR\fR .ad .RS 20n -The door received was created by this process using \fBdoor_create()\fR. See +The door received was created by this process using \fBdoor_create()\fR. See \fBdoor_create\fR(3C). .RE @@ -137,7 +137,7 @@ The door received is expecting an unreferenced notification. \fB\fBDOOR_UNREF_MULTI\fR\fR .ad .RS 20n -Similar to \fBDOOR_UNREF\fR, except multiple unreferenced notifications may be +Similar to \fBDOOR_UNREF\fR, except multiple unreferenced notifications may be delivered for the same door. .RE @@ -183,7 +183,7 @@ Upon successful completion, \fB0\fR is returned. Otherwise, \fB\(mi1\fR is returned and \fBerrno\fR is set to indicate the error. .SH ERRORS .LP -The \fBdoor_call()\fR function will fail if: +The \fBdoor_call()\fR function will fail if: .sp .ne 2 .na diff --git a/usr/src/man/man3c/door_create.3c b/usr/src/man/man3c/door_create.3c index 74965be5f4..0f04425dd8 100644 --- a/usr/src/man/man3c/door_create.3c +++ b/usr/src/man/man3c/door_create.3c @@ -18,18 +18,17 @@ door_create \- create a door descriptor .fi .SH DESCRIPTION -.sp .LP The \fBdoor_create()\fR function creates a door descriptor that describes the -procedure specified by the function \fIserver_procedure\fR. The data item, -\fIcookie\fR, is associated with the door descriptor, and is passed as an +procedure specified by the function \fIserver_procedure\fR. The data item, +\fIcookie\fR, is associated with the door descriptor, and is passed as an argument to the invoked function \fIserver_procedure\fR during -\fBdoor_call\fR(3C) invocations. Other arguments passed to +\fBdoor_call\fR(3C) invocations. Other arguments passed to \fIserver_procedure\fR from an associated \fBdoor_call()\fR are placed on the stack and include \fIargp\fR and \fIdp\fR. The \fIargp\fR argument points to \fIarg_size\fR bytes of data and the \fIdp\fR argument points to \fIn_desc\fR \fBdoor_desc_t\fR structures. The \fIattributes\fR argument specifies -attributes associated with the newly created door. Valid values for +attributes associated with the newly created door. Valid values for \fIattributes\fR are constructed by OR-ing one or more of the following values: .sp .ne 2 @@ -39,11 +38,11 @@ attributes associated with the newly created door. Valid values for .sp .6 .RS 4n 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 +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. \fBDOOR_UNREF_DATA\fR designates an unreferenced invocation, as the \fIargp\fR argument passed to \fIserver_procedure\fR. In the case of an unreferenced -invocation, the values for \fIarg_size\fR, \fIdp\fR and \fIn_did\fR are +invocation, the values for \fIarg_size\fR, \fIdp\fR and \fIn_did\fR are \fB0\fR. Only one unreferenced invocation is delivered on behalf of a door. .RE @@ -56,7 +55,7 @@ invocation, the values for \fIarg_size\fR, \fIdp\fR and \fIn_did\fR are .RS 4n Similar to \fBDOOR_UNREF\fR, 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 +drops to one more than once. Since an additional reference may have been passed by the time an unreferenced invocation arrives, the \fBDOOR_IS_UNREF\fR attribute returned by the \fBdoor_info\fR(3C) call can be used to determine if the door is still unreferenced. @@ -69,8 +68,8 @@ the door is still unreferenced. .ad .sp .6 .RS 4n -Maintains a separate pool of server threads on behalf of the door. Server -threads are associated with a door's private server pool using +Maintains a separate pool of server threads on behalf of the door. Server +threads are associated with a door's private server pool using \fBdoor_bind\fR(3C). .RE @@ -94,7 +93,7 @@ procedure will always be invoked with an \fIn_desc\fR argument of 0. .sp .6 .RS 4n Clients which abort calls to \fBdoor_call()\fR on this door will not cause the -cancellation of the server thread handling the request. See +cancellation of the server thread handling the request. See \fBcancellation\fR(5). .RE @@ -109,7 +108,7 @@ item \fIcookie\fR. .sp .LP By default, additional threads are created as needed to handle concurrent -\fBdoor_call()\fR invocations. See \fBdoor_server_create\fR(3C) for +\fBdoor_call()\fR invocations. See \fBdoor_server_create\fR(3C) for information on how to change this behavior. .sp .LP @@ -120,13 +119,11 @@ A process can advertise a door in the file system name space using After creation, \fBdoor_setparam\fR(3C) can be used to set limits on the amount of data and descriptors clients can send over the door. .SH RETURN VALUES -.sp .LP Upon successful completion, \fBdoor_create()\fR returns a non-negative value. Otherwise, \fBdoor_create\fR returns \fB\(mi1\fR and sets \fBerrno\fR to indicate the error. .SH ERRORS -.sp .LP The \fBdoor_create()\fR function will fail if: .sp @@ -202,7 +199,6 @@ main(int argc, char *argv[]) .in -2 .SH ATTRIBUTES -.sp .LP See \fBattributes\fR(5) for descriptions of the following attributes: .sp @@ -222,7 +218,6 @@ MT-Level Safe .TE .SH SEE ALSO -.sp .LP \fBdoor_bind\fR(3C), \fBdoor_call\fR(3C), \fBdoor_info\fR(3C), \fBdoor_revoke\fR(3C), \fBdoor_setparam\fR(3C), \fBdoor_server_create\fR(3C), diff --git a/usr/src/man/man3c/door_cred.3c b/usr/src/man/man3c/door_cred.3c index 41578519b1..b560bb80dc 100644 --- a/usr/src/man/man3c/door_cred.3c +++ b/usr/src/man/man3c/door_cred.3c @@ -16,10 +16,9 @@ door_cred \- return credential information associated with the client .fi .SH DESCRIPTION -.sp .LP -The \fBdoor_cred()\fR function returns credential information associated with -the client (if any) of the current door invocation. +The \fBdoor_cred()\fR function returns credential information associated with +the client (if any) of the current door invocation. .sp .LP The contents of the \fIinfo\fR argument include the following fields: @@ -40,15 +39,13 @@ The credential information associated with the client refers to the information from the immediate caller; not necessarily from the first thread in a chain of door calls. .SH RETURN VALUES -.sp .LP Upon successful completion, \fBdoor_cred()\fR returns \fB0\fR. Otherwise, \fBdoor_cred()\fR returns \fB\(mi1\fR and sets \fBerrno\fR to indicate the error. .SH ERRORS -.sp .LP -The \fBdoor_cred()\fR function will fail if: +The \fBdoor_cred()\fR function will fail if: .sp .ne 2 .na @@ -68,12 +65,10 @@ There is no associated door client. .RE .SH USAGE -.sp .LP The \fBdoor_cred()\fR function is obsolete. Applications should use the \fBdoor_ucred\fR(3C) function in place of \fBdoor_cred()\fR. .SH ATTRIBUTES -.sp .LP See \fBattributes\fR(5) for descriptions of the following attributes: .sp @@ -93,7 +88,6 @@ MT-Level Safe .TE .SH SEE ALSO -.sp .LP \fBdoor_call\fR(3C), \fBdoor_create\fR(3C), \fBdoor_ucred\fR(3C), \fBattributes\fR(5) diff --git a/usr/src/man/man3c/door_getparam.3c b/usr/src/man/man3c/door_getparam.3c index ae17a48dd7..a6109b6d59 100644 --- a/usr/src/man/man3c/door_getparam.3c +++ b/usr/src/man/man3c/door_getparam.3c @@ -78,7 +78,7 @@ The \fBdoor_setparam()\fR function can only affect doors that were created by the current process. .SH RETURN VALUES .LP -Upon successful completion, 0 is returned. Otherwise, -1 is returned and +Upon successful completion, 0 is returned. Otherwise, -1 is returned and \fBerrno\fR is set to indicate the error. .SH ERRORS .LP diff --git a/usr/src/man/man3c/door_info.3c b/usr/src/man/man3c/door_info.3c index c687f71cf9..19d11bc863 100644 --- a/usr/src/man/man3c/door_info.3c +++ b/usr/src/man/man3c/door_info.3c @@ -16,7 +16,6 @@ door_info \- return information associated with a door descriptor .fi .SH DESCRIPTION -.sp .LP The \fBdoor_info()\fR function returns information associated with a door descriptor. It obtains information about the door descriptor \fId\fR and places @@ -43,7 +42,7 @@ The \fBdi_target\fR member is the process \fBID\fR of the door server, or \fB\(mi1\fR if the door server process has exited. .sp .LP -The values for \fBdi_attributes\fR may be composed of the following: +The values for \fBdi_attributes\fR may be composed of the following: .sp .ne 2 .na @@ -122,21 +121,19 @@ The door has a separate pool of server threads associated with it. .sp .LP -The \fBdi_proc\fR and \fBdi_data\fR members are returned as \fBdoor_ptr_t\fR +The \fBdi_proc\fR and \fBdi_data\fR members are returned as \fBdoor_ptr_t\fR objects rather than \fBvoid\fR \fB*\fR pointers to allow clients and servers to interoperate in environments where the pointer sizes may vary in size (for example, 32-bit clients and 64-bit servers). Each door has a system-wide unique -number associated with it that is set when the door is created by +number associated with it that is set when the door is created by \fBdoor_create()\fR. This number is returned in \fBdi_uniquifier\fR. .SH RETURN VALUES -.sp .LP -Upon successful completion, \fB0\fR is returned. Otherwise, \fB\(mi1\fR is -returned and \fBerrno\fR is set to indicate the error. +Upon successful completion, \fB0\fR is returned. Otherwise, \fB\(mi1\fR is +returned and \fBerrno\fR is set to indicate the error. .SH ERRORS -.sp .LP -The \fBdoor_info()\fR function will fail if: +The \fBdoor_info()\fR function will fail if: .sp .ne 2 .na @@ -156,7 +153,6 @@ The address of argument \fIinfo\fR is an invalid address. .RE .SH ATTRIBUTES -.sp .LP See \fBattributes\fR(5) for descriptions of the following attributes: .sp @@ -176,7 +172,6 @@ MT-Level Safe .TE .SH SEE ALSO -.sp .LP \fBdoor_bind\fR(3C), \fBdoor_call\fR(3C), \fBdoor_create\fR(3C), \fBdoor_server_create\fR(3C), \fBattributes\fR(5), \fBcancellation\fR(5) diff --git a/usr/src/man/man3c/door_return.3c b/usr/src/man/man3c/door_return.3c index 9c30ea3db1..1386cb51f4 100644 --- a/usr/src/man/man3c/door_return.3c +++ b/usr/src/man/man3c/door_return.3c @@ -17,26 +17,23 @@ door_return \- return from a door invocation .fi .SH DESCRIPTION -.sp .LP The \fBdoor_return()\fR function returns from a door invocation. It returns control to the thread that issued the associated \fBdoor_call()\fR and blocks waiting for the next door invocation. See \fBdoor_call\fR(3C). Results, if any, -from the door invocation are passed back to the client in the buffers pointed +from the door invocation are passed back to the client in the buffers pointed to by \fIdata_ptr\fR and \fIdesc_ptr\fR. If there is not a client associated with the \fBdoor_return()\fR, the calling thread discards the results, releases any passed descriptors with the \fBDOOR_RELEASE\fR attribute, and blocks waiting for the next door invocation. .SH RETURN VALUES -.sp .LP Upon successful completion, \fBdoor_return()\fR does not return to the calling process. Otherwise, \fBdoor_return()\fR returns \fB\(mi1\fR to the calling process and sets \fBerrno\fR to indicate the error. .SH ERRORS -.sp .LP -The \fBdoor_return()\fR function fails and returns to the calling process if: +The \fBdoor_return()\fR function fails and returns to the calling process if: .sp .ne 2 .na @@ -75,7 +72,6 @@ The client has too many open descriptors. .RE .SH ATTRIBUTES -.sp .LP See \fBattributes\fR(5) for descriptions of the following attributes: .sp @@ -95,6 +91,5 @@ MT-Level Safe .TE .SH SEE ALSO -.sp .LP \fBdoor_call\fR(3C),\fBattributes\fR(5) diff --git a/usr/src/man/man3c/door_revoke.3c b/usr/src/man/man3c/door_revoke.3c index 5273d293eb..1e76083f76 100644 --- a/usr/src/man/man3c/door_revoke.3c +++ b/usr/src/man/man3c/door_revoke.3c @@ -16,26 +16,23 @@ door_revoke \- revoke access to a door descriptor .fi .SH DESCRIPTION -.sp .LP The \fBdoor_revoke()\fR function revokes access to a door descriptor. Door -descriptors are created with \fBdoor_create\fR(3C). The \fBdoor_revoke()\fR -function performs an implicit call to \fBclose\fR(2), marking the door +descriptors are created with \fBdoor_create\fR(3C). The \fBdoor_revoke()\fR +function performs an implicit call to \fBclose\fR(2), marking the door descriptor \fId\fR as invalid. .sp .LP -A door descriptor can be revoked only by the process that created it. Door +A door descriptor can be revoked only by the process that created it. Door invocations that are in progress during a \fBdoor_revoke()\fR invocation are allowed to complete normally. .SH RETURN VALUES -.sp .LP Upon successful completion, \fBdoor_revoke()\fR returns \fB0\fR. Otherwise, \fBdoor_revoke()\fR returns \(mi1 and sets \fBerrno\fR to indicate the error. .SH ERRORS -.sp .LP -The \fBdoor_revoke()\fR function will fail if: +The \fBdoor_revoke()\fR function will fail if: .sp .ne 2 .na @@ -56,7 +53,6 @@ The door descriptor was not created by this process (with .RE .SH ATTRIBUTES -.sp .LP See \fBattributes\fR(5) for descriptions of the following attributes: .sp @@ -76,6 +72,5 @@ MT-Level Safe .TE .SH SEE ALSO -.sp .LP \fBclose\fR(2), \fBdoor_create\fR(3C), \fBattributes\fR(5) diff --git a/usr/src/man/man3c/door_server_create.3c b/usr/src/man/man3c/door_server_create.3c index 1e8511fb04..cc2940b976 100644 --- a/usr/src/man/man3c/door_server_create.3c +++ b/usr/src/man/man3c/door_server_create.3c @@ -3,7 +3,7 @@ .\" 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. .\" 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. .\" 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] -.TH DOOR_SERVER_CREATE 3C "Mar 22, 2005" +.TH DOOR_SERVER_CREATE 3C "May 12, 2017" .SH NAME door_server_create \- specify an alternative door server thread creation function @@ -13,23 +13,22 @@ function \fBcc\fR \fB-mt\fR [ \fIflag\fR... ] \fIfile\fR... [ \fIlibrary\fR... ] #include -\fBvoid (*) ()\fR \fBdoor_server_create\fR(\fBvoid (*\fR\fIcreate_proc\fR)(door_info_t*)); +\fBvoid (*)(door_info_t *)\fR \fBdoor_server_create\fR(\fBvoid (*\fR\fIcreate_proc\fR)(door_info_t *)); .fi .SH DESCRIPTION -.sp .LP -Normally, the doors library creates new door server threads in response to +Normally, the doors library creates new door server threads in response to incoming concurrent door invocations automatically. There is no pre-defined -upper limit on the number of server threads that the system creates in -response to incoming invocations (1 server thread for each active door +upper limit on the number of server threads that the system creates in +response to incoming invocations (1 server thread for each active door invocation). These threads are created with the default thread stack size and -POSIX (see \fBstandards\fR(5)) threads cancellation disabled. The created -threads also have the \fBTHR_BOUND\fR | \fBTHR_DETACHED\fR attributes for -Solaris threads and the \fBPTHREAD_SCOPE_SYSTEM\fR | +POSIX (see \fBstandards\fR(5)) threads cancellation disabled. The created +threads also have the \fBTHR_BOUND\fR | \fBTHR_DETACHED\fR attributes for +Solaris threads and the \fBPTHREAD_SCOPE_SYSTEM\fR | \fBPTHREAD_CREATE_DETACHED\fR attributes for POSIX threads. The signal -disposition, and scheduling class of the newly created thread are inherited -from the calling thread (initially from the thread calling +disposition, and scheduling class of the newly created thread are inherited +from the calling thread (initially from the thread calling \fBdoor_create()\fR, and subsequently from the current active door server thread). .sp @@ -37,15 +36,15 @@ thread). The \fBdoor_server_create()\fR function allows control over the creation of server threads needed for door invocations. The procedure \fIcreate_proc\fR is called every time the available server thread pool is depleted. In the case of -private server pools associated with a door (see the \fBDOOR_PRIVATE\fR -attribute in \fBdoor_create()\fR), information on which pool is depleted is -passed to the create function in the form of a \fBdoor_info_t\fR structure. +private server pools associated with a door (see the \fBDOOR_PRIVATE\fR +attribute in \fBdoor_create()\fR), information on which pool is depleted is +passed to the create function in the form of a \fBdoor_info_t\fR structure. The \fBdi_proc\fR and \fBdi_data\fR members of the \fBdoor_info_t\fR structure -can be used as a door identifier associated with the depleted pool. The -\fIcreate_proc\fR procedure may limit the number of server threads created and -may also create server threads with appropriate attributes (stack size, +can be used as a door identifier associated with the depleted pool. The +\fIcreate_proc\fR procedure may limit the number of server threads created and +may also create server threads with appropriate attributes (stack size, thread-specific data, POSIX thread cancellation, signal mask, scheduling -attributes, and so forth) for use with door invocations. +attributes, and so forth) for use with door invocations. .sp .LP The overall amount of data and argument descriptors that can be sent through a @@ -54,21 +53,21 @@ the door itself. See \fBdoor_setparam\fR(3C). .sp .LP The specified server creation function should create user level threads using -\fBthr_create()\fR with the \fBTHR_BOUND\fR flag, or in the case of POSIX -threads, \fBpthread_create()\fR with the \fBPTHREAD_SCOPE_SYSTEM\fR attribute. +\fBthr_create()\fR with the \fBTHR_BOUND\fR flag, or in the case of POSIX +threads, \fBpthread_create()\fR with the \fBPTHREAD_SCOPE_SYSTEM\fR attribute. The server threads make themselves available for incoming door invocations on this process by issuing a \fBdoor_return\fR(\fBNULL, 0, NULL, 0\fR). In this -case, the \fBdoor_return()\fR arguments are ignored. See \fBdoor_return\fR(3C) +case, the \fBdoor_return()\fR arguments are ignored. See \fBdoor_return\fR(3C) and \fBthr_create\fR(3C). .sp .LP -The server threads created by default are enabled for POSIX thread -cancellations which may lead to unexpected thread terminations while holding -resources (such as locks) if the client aborts the associated +The server threads created by default are enabled for POSIX thread +cancellations which may lead to unexpected thread terminations while holding +resources (such as locks) if the client aborts the associated \fBdoor_call()\fR. See \fBdoor_call\fR(3C). Unless the server code is truly -interested in notifications of client aborts during a door invocation and is -prepared to handle such notifications using cancellation handlers, POSIX -thread cancellation should be disabled for server threads using +interested in notifications of client aborts during a door invocation and is +prepared to handle such notifications using cancellation handlers, POSIX +thread cancellation should be disabled for server threads using \fBpthread_setcancelstate\fR (\fBPTHREAD_CANCEL_DISABLE\fR, \fINULL\fR). If all doors are created with the \fBDOOR_NO_CANCEL\fR flag (see \fBdoor_create\fR(3C)), the threads will never be cancelled by an aborted @@ -77,12 +76,11 @@ doors are created with the \fBDOOR_NO_CANCEL\fR flag (see .LP The \fIcreate_proc\fR procedure need not create any additional server threads if there is at least one server thread currently active in the process (perhaps -handling another door invocation) or it may create as many as seen fit each +handling another door invocation) or it may create as many as seen fit each time it is called. If there are no available server threads during an incoming -door invocation, the associated \fBdoor_call()\fR blocks until a server thread -becomes available. The \fIcreate_proc\fR procedure must be MT-Safe. +door invocation, the associated \fBdoor_call()\fR blocks until a server thread +becomes available. The \fIcreate_proc\fR procedure must be MT-Safe. .SH RETURN VALUES -.sp .LP Upon successful completion, \fBdoor_server_create()\fR returns a pointer to the previous server creation function. This function has no failure mode (it cannot @@ -92,7 +90,7 @@ fail). \fBExample 1 \fRCreating door server threads. .sp .LP -The following example creates door server threads with cancellation disabled +The following example creates door server threads with cancellation disabled and an 8k stack instead of the default stack size: .sp @@ -123,7 +121,6 @@ main(\|) .in -2 .SH ATTRIBUTES -.sp .LP See \fBattributes\fR(5) for descriptions of the following attributes: .sp @@ -143,7 +140,6 @@ MT-Level Safe .TE .SH SEE ALSO -.sp .LP \fBdoor_bind\fR(3C), \fBdoor_call\fR(3C), \fBdoor_create\fR(3C), \fBdoor_return\fR(3C), \fBpthread_create\fR(3C), diff --git a/usr/src/man/man3c/door_ucred.3c b/usr/src/man/man3c/door_ucred.3c index 20aeff1250..e7b471d9d5 100644 --- a/usr/src/man/man3c/door_ucred.3c +++ b/usr/src/man/man3c/door_ucred.3c @@ -16,9 +16,8 @@ door_ucred \- return credential information associated with the client .fi .SH DESCRIPTION -.sp .LP -The \fBdoor_ucred()\fR function returns credential information associated with +The \fBdoor_ucred()\fR function returns credential information associated with the client, if any, of the current door invocation. .sp .LP @@ -39,13 +38,11 @@ The credential information associated with the client refers to the information from the immediate caller, not necessarily from the first thread in a chain of door calls. .SH RETURN VALUES -.sp .LP Upon successful completion, \fBdoor_ucred()\fR returns 0. Otherwise, -1 is returned and \fBerrno\fR is set to indicate the error, in which case the memory location pointed to by the \fIinfo\fR argument is unchanged. .SH ERRORS -.sp .LP The \fBdoor_ucred()\fR function will fail if: .sp @@ -87,7 +84,6 @@ sufficient to hold a ucred failed. .RE .SH ATTRIBUTES -.sp .LP See \fBattributes\fR(5) for descriptions of the following attributes: .sp @@ -105,7 +101,6 @@ MT-Level Safe .TE .SH SEE ALSO -.sp .LP \fBdoor_call\fR(3C), \fBdoor_create\fR(3C), \fBucred_get\fR(3C), \fBattributes\fR(5) diff --git a/usr/src/man/man3lib/libdoor.3lib b/usr/src/man/man3lib/libdoor.3lib index 19ef8ff409..a5552fee42 100644 --- a/usr/src/man/man3lib/libdoor.3lib +++ b/usr/src/man/man3lib/libdoor.3lib @@ -9,12 +9,11 @@ libdoor \- doors library .SH SYNOPSIS .LP .nf -cc [ \fIflag\fR... ] \fIfile\fR... [ \fIlibrary\fR... ] +cc [ \fIflag\fR... ] \fIfile\fR... [ \fIlibrary\fR... ] #include <\fBdoor.h\fR> .fi .SH DESCRIPTION -.sp .LP Historically, functions in this library provided programmatic access to doors, including the ability to create and call them. This functionality now resides @@ -24,7 +23,7 @@ in \fBlibc\fR(3LIB). Doors are a fast light-weight RPC mechanism for secure control transfer between processes on the same machine. Conceptually, a thread in one process can issue a call using a door descriptor that causes code to be executed in another -process and then returns using the traditional synchronous RPC model. Doors +process and then returns using the traditional synchronous RPC model. Doors can also be used to pass data and file descriptors between processes. .sp .LP @@ -32,7 +31,6 @@ This library is maintained to provide backward compatibility for both runtime and compilation environments. The shared object is implemented as a filter on \fBlibc.so.1\fR. New application development need not specify \fB-ldoor\fR. .SH INTERFACES -.sp .LP The shared object \fBlibdoor.so.1\fR provides the public interfaces defined below. See \fBIntro\fR(3) for additional information on shared object @@ -51,7 +49,6 @@ l l . .TE .SH FILES -.sp .ne 2 .na \fB\fB/lib/libdoor.so.1\fR\fR @@ -70,7 +67,6 @@ shared object .RE .SH ATTRIBUTES -.sp .LP See \fBattributes\fR(5) for descriptions of the following attributes: .sp @@ -85,7 +81,6 @@ MT-Level Safe .TE .SH SEE ALSO -.sp .LP \fBIntro\fR(3), \fBlibc\fR(3LIB), \fBattributes\fR(5) .sp -- 2.11.4.GIT