'\" te
.\" Copyright (c) 2005, Sun Microsystems, Inc.  All Rights Reserved.
.TH door_bind 3C "22 Mar 2005" "SunOS 5.11" "Standard C Library Functions"
.SH NAME
door_bind, door_unbind \- bind or unbind the current thread with the door server pool
.SH SYNOPSIS
.LP
.nf
\fBcc\fR \fB-mt\fR [ \fIflag\fR... ] \fIfile\fR... [ \fIlibrary\fR... ]
#include <door.h>

\fBint\fR \fBdoor_bind\fR(\fBint\fR \fIdid\fR);
.fi

.LP
.nf
\fBint\fR \fBdoor_unbind\fR(\fBvoid\fR);
.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 to serve door invocations associated with the door \fIdid\fR.
.sp
.LP
The \fBdoor_unbind()\fR function breaks the association of \fBdoor_bind()\fR by 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 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.
.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).
.sp
.LP
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 door that is already bound to a different door performs an implicit \fBdoor_unbind()\fR of the previous door.
.sp
.LP
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:
.sp
.ne 2
.mk
.na
\fB\fBEBADF\fR\fR
.ad
.RS 10n
.rt  
The \fIdid\fR argument is not a valid door.
.RE

.sp
.ne 2
.mk
.na
\fB\fBEBADF\fR\fR
.ad
.RS 10n
.rt  
The \fBdoor_unbind()\fR function was called by a thread that is currently not bound.
.RE

.sp
.ne 2
.mk
.na
\fB\fBEINVAL\fR\fR
.ad
.RS 10n
.rt  
\fIdid\fR was not created with the \fBDOOR_PRIVATE\fR attribute.
.RE

.SH EXAMPLES
.LP
\fBExample 1 \fRUse \fBdoor_bind()\fR to create private server pools for two doors.
.sp
.LP
The following example shows the use of \fBdoor_bind()\fR to create private server pools for two doors, \fBd1\fR and \fBd2\fR. Function \fBmy_create()\fR is called when a new server thread is needed; it creates a thread running function, \fBmy_server_create()\fR, which binds itself to one of the two doors.

.sp
.in +2
.nf
#include <door.h>
#include <thread.h>
#include <pthread.h>
thread_key_t door_key;
int d1 = -1;
int d2 = -1;
cond_t cv;       /* statically initialized to zero */
mutex_t lock;    /* statically initialized to zero */

extern void foo(void *, char *, size_t, door_desc_t *, uint_t);
extern void bar(void *, char *, size_t, door_desc_t *, uint_t);

static void *
my_server_create(void *arg)
{
        /* wait for d1 & d2 to be initialized */
        mutex_lock(&lock);
        while (d1 == -1 || d2 == -1)
                cond_wait(&cv, &lock);
        mutex_unlock(&lock);

        if (arg == (void *)foo){
                /* bind thread with pool associated with d1 */
                thr_setspecific(door_key, (void *)foo);
                if (door_bind(d1) < 0) {
                        perror("door_bind"); exit (-1);
                }
        } else if (arg == (void *)bar) {
                /* bind thread with pool associated with d2 */
                thr_setspecific(door_key, (void *)bar);
                if (door_bind(d2) < 0) {
                /* bind thread to d2 thread pool */
                        perror("door_bind"); exit (-1);
                }
        }
        pthread_setcancelstate(PTHREAD_CANCEL_DISABLE, NULL);
        door_return(NULL, 0, NULL, 0);  /* Wait for door invocation */
}

static void
my_create(door_info_t *dip)
{
        /* Pass the door identity information to create function */
        thr_create(NULL, 0, my_server_create, (void *)dip->di_proc,
                THR_BOUND | THR_DETACHED, NULL);
}

main()
{
        (void) door_server_create(my_create);
        if (thr_keycreate(&door_key, NULL) != 0) {
                perror("thr_keycreate");
                exit(1);
        }
        mutex_lock(&lock);
        d1 = door_create(foo, NULL, DOOR_PRIVATE); /* Private pool */
        d2 = door_create(bar, NULL, DOOR_PRIVATE); /* Private pool */
        cond_signal(&cv);
        mutex_unlock(&lock);
        while (1)
                pause();
}
.fi
.in -2

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
tab() box;
cw(2.75i) |cw(2.75i) 
lw(2.75i) |lw(2.75i) 
.
ATTRIBUTE TYPEATTRIBUTE VALUE
_
Architectureall
_
Availabilitysystem/core-os
_
Interface StabilityCommitted
_
MT-LevelSafe
.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)