share/man/man3c/pthread_cond_init.3c

   1 .\"
   2 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for
   3 .\" permission to reproduce portions of its copyrighted documentation.
   4 .\" Original documentation from The Open Group can be obtained online at
   5 .\" http://www.opengroup.org/bookstore/.
   6 .\"
   7 .\" The Institute of Electrical and Electronics Engineers and The Open
   8 .\" Group, have given us permission to reprint portions of their
   9 .\" documentation.
  10 .\"
  11 .\" In the following statement, the phrase ``this text'' refers to portions
  12 .\" of the system documentation.
  13 .\"
  14 .\" Portions of this text are reprinted and reproduced in electronic form
  15 .\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition,
  16 .\" Standard for Information Technology -- Portable Operating System
  17 .\" Interface (POSIX), The Open Group Base Specifications Issue 6,
  18 .\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics
  19 .\" Engineers, Inc and The Open Group.  In the event of any discrepancy
  20 .\" between these versions and the original IEEE and The Open Group
  21 .\" Standard, the original IEEE and The Open Group Standard is the referee
  22 .\" document.  The original Standard can be obtained online at
  23 .\" http://www.opengroup.org/unix/online.html.
  24 .\"
  25 .\" This notice shall appear on any product containing this material.
  26 .\"
  27 .\" The contents of this file are subject to the terms of the
  28 .\" Common Development and Distribution License (the "License").
  29 .\" You may not use this file except in compliance with the License.
  30 .\"
  31 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
  32 .\" or http://www.opensolaris.org/os/licensing.
  33 .\" See the License for the specific language governing permissions
  34 .\" and limitations under the License.
  35 .\"
  36 .\" When distributing Covered Code, include this CDDL HEADER in each
  37 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
  38 .\" If applicable, add the following below this CDDL HEADER, with the
  39 .\" fields enclosed by brackets "[]" replaced with your own identifying
  40 .\" information: Portions Copyright [yyyy] [name of copyright owner]
  41 .\"
  42 .\"
  43 .\" Copyright 1991, 1992, 1994, The X/Open Company Ltd.
  44 .\" Copyright (c) 2001, The IEEE and The Open Group.  All Rights Reserved.
  45 .\" Copyright (c) 2008, Sun Microsystems, Inc.  All Rights Reserved.
  46 .\"
  47 .TH PTHREAD_COND_INIT 3C "Mar 23, 2005"
  48 .SH NAME
  49 pthread_cond_init, pthread_cond_destroy \- initialize or destroy condition
  50 variables
  51 .SH SYNOPSIS
  52 .LP
  53 .nf
  54 cc -mt [ \fIflag\fR... ] \fIfile\fR... -lpthread [ \fIlibrary\fR... ]
  55 #include <pthread.h>
  56
  57 \fBint\fR \fBpthread_cond_init\fR(\fBpthread_cond_t *restrict\fR \fIcond\fR,
  58      \fBconst pthread_condattr_t *restrict\fR \fIattr\fR);
  59 .fi
  60
  61 .LP
  62 .nf
  63 \fBint\fR \fBpthread_cond_destroy\fR(\fBpthread_cond_t *\fR\fIcond\fR
  64 .fi
  65
  66 .LP
  67 .nf
  68 \fBpthread_cond_t\fR \fIcond\fR= \fBPTHREAD_COND_INITIALIZER\fR;
  69 .fi
  70
  71 .SH DESCRIPTION
  72 .sp
  73 .LP
  74 The function \fBpthread_cond_init()\fR initializes the condition variable
  75 referenced by \fIcond\fR with attributes referenced by \fIattr\fR. If
  76 \fIattr\fR is  \fBNULL\fR, the default condition variable attributes are used;
  77 the effect is the same as passing the address of a default condition variable
  78 attributes object. See \fBpthread_condattr_init\fR(3C). Upon successful
  79 initialization, the state of the condition variable becomes initialized.
  80 .sp
  81 .LP
  82 Attempting to initialize an already initialized condition variable results in
  83 undefined behavior.
  84 .sp
  85 .LP
  86 The function \fBpthread_cond_destroy()\fR destroys the given condition variable
  87 specified by \fIcond\fR; the object becomes, in effect, uninitialized. An
  88 implementation may cause \fBpthread_cond_destroy()\fR to set the object
  89 referenced by \fIcond\fR to an invalid value. A destroyed condition variable
  90 object can be re-initialized using \fBpthread_cond_init()\fR; the results of
  91 otherwise referencing the object after it has been destroyed are undefined.
  92 .sp
  93 .LP
  94 It is safe to destroy an initialized condition variable upon which no threads
  95 are currently blocked. Attempting to destroy a condition variable upon which
  96 other threads are currently blocked results in undefined behavior.
  97 .sp
  98 .LP
  99 In cases where default condition variable attributes are appropriate, the macro
 100 \fBPTHREAD_COND_INITIALIZER\fR can be used to initialize condition variables
 101 that are statically allocated. The effect is equivalent to dynamic
 102 initialization by a call to \fBpthread_cond_init()\fR with parameter \fIattr\fR
 103 specified as  \fBNULL,\fR except that no error checks are performed.
 104 .SH RETURN VALUES
 105 .sp
 106 .LP
 107 If successful, the \fBpthread_cond_init()\fR and \fBpthread_cond_destroy()\fR
 108 functions return  \fB0\fR. Otherwise, an error number is returned to indicate
 109 the error. The \fBEBUSY\fR and \fBEINVAL\fR error checks, if implemented, act
 110 as if they were performed immediately at the beginning of processing for the
 111 function and caused an error return prior to modifying the state of the
 112 condition variable specified by \fIcond\fR.
 113 .SH ERRORS
 114 .sp
 115 .LP
 116 The  \fBpthread_cond_init()\fR function will fail if:
 117 .sp
 118 .ne 2
 119 .na
 120 \fB\fBEAGAIN\fR\fR
 121 .ad
 122 .RS 10n
 123 The system lacked the necessary resources (other than memory) to initialize
 124 another condition variable.
 125 .RE
 126
 127 .sp
 128 .ne 2
 129 .na
 130 \fB\fBENOMEM\fR\fR
 131 .ad
 132 .RS 10n
 133 Insufficient memory exists to initialize the condition variable.
 134 .RE
 135
 136 .sp
 137 .LP
 138 The \fBpthread_cond_init()\fR function may fail if:
 139 .sp
 140 .ne 2
 141 .na
 142 \fB\fBEBUSY\fR\fR
 143 .ad
 144 .RS 10n
 145 The implementation has detected an attempt to re-initialize the object
 146 referenced by \fIcond\fR, a previously initialized, but not yet destroyed,
 147 condition variable.
 148 .RE
 149
 150 .sp
 151 .ne 2
 152 .na
 153 \fB\fBEINVAL\fR\fR
 154 .ad
 155 .RS 10n
 156 The value specified by \fIattr\fR is invalid.
 157 .RE
 158
 159 .sp
 160 .LP
 161 The \fBpthread_cond_destroy()\fR function may fail if:
 162 .sp
 163 .ne 2
 164 .na
 165 \fB\fBEBUSY\fR\fR
 166 .ad
 167 .RS 10n
 168 The implementation has detected an attempt to destroy the object referenced by
 169 \fIcond\fR while it is referenced (for example, while being used in a
 170 \fBpthread_cond_wait()\fR or \fBpthread_cond_timedwait()\fR) by another thread.
 171 .RE
 172
 173 .sp
 174 .ne 2
 175 .na
 176 \fB\fBEINVAL\fR\fR
 177 .ad
 178 .RS 10n
 179 The value specified by \fIcond\fR is invalid.
 180 .RE
 181
 182 .SH ATTRIBUTES
 183 .sp
 184 .LP
 185 See \fBattributes\fR(5) for descriptions of the following attributes:
 186 .sp
 187
 188 .sp
 189 .TS
 190 box;
 191 c | c
 192 l | l .
 193 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 194 _
 195 Interface Stability     Standard
 196 _
 197 MT-Level        MT-Safe
 198 .TE
 199
 200 .SH SEE ALSO
 201 .sp
 202 .LP
 203 \fBpthread_cond_signal\fR(3C), \fBpthread_cond_broadcast\fR(3C),
 204 \fBpthread_cond_wait\fR(3C), \fBpthread_cond_timedwait\fR(3C),
 205 \fBpthread_condattr_init\fR(3C), \fBattributes\fR(5), \fBcondition\fR(5),
 206 \fBstandards\fR(5)