manual/glibc-linuxthreads/draft/man3/sem_init.3

   1 .\"   Copyright (C) 1996-1999 Free Software Foundation, Inc.
   2 .\"
   3 .\"   Permission is granted to make and distribute verbatim copies of
   4 .\" this manual provided the copyright notice and this permission notice are
   5 .\" preserved on all copies.
   6 .\"
   7 .\"   Permission is granted to copy and distribute modified versions of
   8 .\" this manual under the conditions for verbatim copying, provided that
   9 .\" the entire resulting derived work is distributed under the terms of a
  10 .\" permission notice identical to this one.
  11 .\"
  12 .\"   Permission is granted to copy and distribute translations of this
  13 .\" manual into another language, under the above conditions for modified
  14 .\" versions, except that this permission notice may be stated in a
  15 .\" translation approved by the Foundation.
  16 .\"
  17 .\" Copyright (C) 1996 Xavier Leroy.
  18 .\"
  19 .\" Japanese Version Copyright (C) 2002-2003 Suzuki Takashi
  20 .\"         all rights reserved.
  21 .\" Translated Fri Jan  3 23:23:30 JST 2003
  22 .\"         by Suzuki Takashi.
  23 .\"
  24 .\"WORD:    semaphore           ¥»¥Þ¥Õ¥©
  25 .\"WORD:    atomically          °ìÂ©¤Ç
  26 .\"WORD:    semaphore object    ¥»¥Þ¥Õ¥©¥ª¥Ö¥¸¥§¥¯¥È
  27 .\"WORD:    atomic compare-and-swap ÉÔ²ÄÊ¬¤ÎÈæ³Ó¸ò´¹Ì¿Îá
  28 .\"WORD:    atomic operation    ÉÔ²ÄÊ¬Ì¿Îá
  29 .\"WORD:    wait on the semaphore   ¥»¥Þ¥Õ¥©¤Î³ÍÆÀÂÔ¤Á
  30 .\"
  31 .\"
  32 .TH SEMAPHORES 3 LinuxThreads
  33
  34
  35 .\"O .SH NAME
  36 .\"O sem_init, sem_wait, sem_trywait, sem_post, sem_getvalue, sem_destroy \- operations on semaphores
  37 .SH "Ì¾Á°"
  38 sem_init, sem_wait, sem_trywait, sem_post, sem_getvalue, sem_destroy \- ¥»¥Þ¥Õ¥©¤ÎÁàºî
  39
  40 .\"O .SH SYNOPSIS
  41 .SH "½ñ¼°"
  42 .B #include <semaphore.h>
  43
  44 .BI "int sem_init(sem_t *" sem ", int " pshared ", unsigned int " value ");"
  45
  46 .BI "int sem_wait(sem_t * " sem ");"
  47
  48 .BI "int sem_trywait(sem_t * " sem ");"
  49
  50 .BI "int sem_post(sem_t * " sem ");"
  51
  52 .BI "int sem_getvalue(sem_t * " sem ", int * " sval ");"
  53
  54 .BI "int sem_destroy(sem_t * " sem ");"
  55
  56 .\"O .SH DESCRIPTION
  57 .\"O This manual page documents POSIX 1003.1b semaphores, not to be
  58 .\"O confused with SystemV semaphores as described in
  59 .\"O .BR "ipc" (5),
  60 .\"O .BR "semctl" (2)
  61 .\"O and
  62 .\"O .BR "semop" (2).
  63 .SH "ÀâÌÀ"
  64 ¤³¤Î¥Þ¥Ë¥å¥¢¥ë¥Ú¡¼¥¸¤Ï POSIX 1003.1b ¤Î¥»¥Þ¥Õ¥©¤Ë¤Ä¤¤¤Æµ½Ò¤·¤Æ¤ª¤ê¡¢
  65 .BR "ipc" (5)
  66 ¤ä
  67 .BR "semctl" (2)
  68 ¡¢
  69 .BR "semop" (2)
  70 ¤Ëµ½Ò¤µ¤ì¤Æ¤¤¤ë SystemV ¥»¥Þ¥Õ¥©¤Èº®Æ±¤·¤Æ¤Ï¤Ê¤é¤Ê¤¤¡£
  71
  72 .\"O Semaphores are counters for resources shared between threads. The
  73 .\"O basic operations on semaphores are: increment the counter atomically,
  74 .\"O and wait until the counter is non-null and decrement it atomically.
  75 ¥»¥Þ¥Õ¥©¤Ï¥¹¥ì¥Ã¥É´Ö¤Ç¶¦Í¤µ¤ì¤ë»ñ¸»¤ò´ÉÍý¤¹¤ë¤¿¤á¤Î¥«¥¦¥ó¥¿¤Ç¤¢¤ë¡£
  76 ¥»¥Þ¥Õ¥©¤Ë´Ø¤¹¤ë´ðËÜÅª¤ÊÁàºî¤Ï¼¡¤Î 2 ¤Ä¤Ç¤¢¤ë:
  77 ¥«¥¦¥ó¥¿¤ò°ìÂ©¤Ç 1 ¤À¤±Áý²Ã¤µ¤»¤ë¤³¤È¤È¡¢
  78 ¥«¥¦¥ó¥¿¤¬ 0 ¤Ç¤Ê¤¯¤Ê¤ë¤Þ¤ÇÂÔ¤Ã¤¿¤¢¤È°ìÂ©¤Ç 1 ¤À¤±¸º¾¯¤µ¤»¤ë¤³¤È¤Ç¤¢¤ë¡£
  79
  80 .\"O .B "sem_init"
  81 .\"O initializes the semaphore object pointed to by
  82 .\"O .IR "sem" .
  83 .\"O The
  84 .\"O count associated with the semaphore is set initially to
  85 .\"O .IR "value" .
  86 .\"O The
  87 .\"O .I "pshared"
  88 .\"O argument indicates whether the semaphore is local to the
  89 .\"O current process (
  90 .\"O .I "pshared"
  91 .\"O is zero) or is to be shared between several
  92 .\"O processes (
  93 .\"O .I "pshared"
  94 .\"O is not zero). LinuxThreads currently does not
  95 .\"O support process-shared semaphores, thus
  96 .\"O .B "sem_init"
  97 .\"O always returns with
  98 .\"O error
  99 .\"O .B "ENOSYS"
 100 .\"O if
 101 .\"O .I "pshared"
 102 .\"O is not zero.
 103 .B "sem_init"
 104 ¤Ï
 105 .I "sem"
 106 ¤Ç»ØÄê¤µ¤ì¤ë¥»¥Þ¥Õ¥©¥ª¥Ö¥¸¥§¥¯¥È¤ò½é´ü²½¤¹¤ë¡£
 107 ¥»¥Þ¥Õ¥©¤Ë·ë¤ÓÉÕ¤±¤é¤ì¤ë¥«¥¦¥ó¥È¤Ï
 108 .I "value"
 109 ¤Ë½é´ü²½¤µ¤ì¤ë¡£
 110 °ú¿ô
 111 .I "pshared"
 112 ¤Ï¥»¥Þ¥Õ¥©¤¬¸½ºß¤Î¥×¥í¥»¥¹¤À¤±¤ÇÍ¸ú (
 113 .I "pshared"
 114 ¤¬ 0) ¤«Ê£¿ô¤Î¥×¥í¥»¥¹¤Ç¶¦Í¤µ¤ì¤ë (
 115 .I "pshared"
 116 ¤¬Èó 0) ¤«¤ò»ØÄê¤¹¤ë¡£LinuxThreads ¤Ï¸½ºß¤Î¤È¤³¤í
 117 ¥×¥í¥»¥¹´Ö¶¦Í¥»¥Þ¥Õ¥©¤Ï¥µ¥Ý¡¼¥È¤·¤Æ¤¤¤Ê¤¤¡£
 118 ¤½¤Î¤¿¤á¡¢
 119 .I "pshared"
 120 ¤¬ 0 ¤Ç¤Ê¤¤¾ì¹ç¤Ï¡¢
 121 .B "sem_init"
 122 ¤Ï¾ï¤Ë¥¨¥é¡¼
 123 .B "ENOSYS"
 124 ¤òÊÖ¤¹¡£
 125
 126 .\"O .B "sem_wait"
 127 .\"O suspends the calling thread until the semaphore pointed to
 128 .\"O by
 129 .\"O .I "sem"
 130 .\"O has non-zero count. It then atomically decreases the
 131 .\"O semaphore count.
 132 .B "sem_wait"
 133 ¤Ï¡¢
 134 .I "sem"
 135 ¤Ç»ØÄê¤µ¤ì¤ë¥»¥Þ¥Õ¥©¤Î¥«¥¦¥ó¥È¤¬Èó 0 ¤Ë¤Ê¤ë¤Þ¤Ç
 136 ¸Æ¤Ó½Ð¤·¥¹¥ì¥Ã¥É¤Î¼Â¹Ô¤òÄä»ß¤¹¤ë¡£
 137 ¤½¤·¤Æ¥»¥Þ¥Õ¥©¥«¥¦¥ó¥È¤ò°ìÂ©¤Ç 1 ¤À¤±¸º¾¯¤µ¤»¤ë¡£
 138
 139 .\"O .B "sem_trywait"
 140 .\"O is a non-blocking variant of
 141 .\"O .BR "sem_wait" .
 142 .\"O If the
 143 .\"O semaphore pointed to by
 144 .\"O .I "sem"
 145 .\"O has non-zero count, the count is
 146 .\"O atomically decreased and
 147 .\"O .B "sem_trywait"
 148 .\"O immediately returns 0.
 149 .\"O If the semaphore count is zero,
 150 .\"O .B "sem_trywait"
 151 .\"O immediately returns with
 152 .\"O error
 153 .\"O .BR "EAGAIN" .
 154 .B "sem_trywait"
 155 ¤Ï¥Ö¥í¥Ã¥¯¤ò¤È¤â¤Ê¤ï¤Ê¤¤
 156 .B "sem_wait"
 157 ¤Ç¤¢¤ë¡£
 158 .I "sem"
 159 ¤Ç»ØÄê¤µ¤ì¤ë¥»¥Þ¥Õ¥©¤Î¥«¥¦¥ó¥È¤¬Èó 0 ¤Î¾ì¹ç¤Ë¤Ï
 160 °ìÂ©¤Ç¥«¥¦¥ó¥È¤¬ 1 ¤À¤±¸º¾¯¤µ¤ì¤Æ
 161 .B "sem_trywait"
 162 ¤ÏÄ¾¤Á¤Ë 0 ¤òÊÖ¤¹¡£
 163 ¥»¥Þ¥Õ¥©¥«¥¦¥ó¥È¤¬ 0 ¤Î¾ì¹ç¤Ë¤Ï
 164 .B "sem_trywait"
 165 ¤ÏÄ¾¤Á¤Ë¥¨¥é¡¼
 166 .B "EAGAIN"
 167 ¤òÊÖ¤¹¡£
 168
 169 .\"O .B "sem_post"
 170 .\"O atomically increases the count of the semaphore pointed to
 171 .\"O by
 172 .\"O .IR "sem" .
 173 .\"O This function never blocks and can safely be used in
 174 .\"O asynchronous signal handlers.
 175 .B "sem_post"
 176 ¤Ï
 177 .I "sem"
 178 ¤Ç»ØÄê¤µ¤ì¤ë¥»¥Þ¥Õ¥©¤Î¥«¥¦¥ó¥È¤ò°ìÂ©¤Ç 1 ¤À¤±Áý²Ã¤µ¤»¤ë¡£
 179 ¤³¤Î´Ø¿ô¤Ï·è¤·¤Æ¥Ö¥í¥Ã¥¯¤¹¤ë¤³¤È¤Ï¤Ê¤¯¡¢
 180 ÈóÆ±´ü¥·¥°¥Ê¥ë¥Ï¥ó¥É¥é¤ÎÃæ¤Ç¤â°ÂÁ´¤Ë»ÈÍÑ¤¹¤ë¤³¤È¤¬¤Ç¤¤ë¡£
 181
 182 .\"O .B "sem_getvalue"
 183 .\"O stores in the location pointed to by
 184 .\"O .I "sval"
 185 .\"O the current
 186 .\"O count of the semaphore
 187 .\"O .IR "sem" .
 188 .B "sem_getvalue"
 189 ¤Ï
 190 .I "sval"
 191 ¤Ç»Ø¤·¼¨¤µ¤ì¤ëÎÎ°è¤Ë
 192 ¥»¥Þ¥Õ¥©
 193 .I "sem"
 194 ¤Î¸½ºß¤Î¥«¥¦¥ó¥È¤ò³ÊÇ¼¤¹¤ë¡£
 195
 196 .\"O .B "sem_destroy"
 197 .\"O destroys a semaphore object, freeing the resources it
 198 .\"O might hold. No threads should be waiting on the semaphore at the time
 199 .\"O .B "sem_destroy"
 200 .\"O is called. In the LinuxThreads implementation, no
 201 .\"O resources are associated with semaphore objects, thus
 202 .\"O .B "sem_destroy"
 203 .\"O actually does nothing except checking that no thread is waiting on the
 204 .\"O semaphore.
 205 .B "sem_destroy"
 206 ¤Ï¥»¥Þ¥Õ¥©¥ª¥Ö¥¸¥§¥¯¥È¤òÇË²õ¤·¡¢
 207 ¥»¥Þ¥Õ¥©¥ª¥Ö¥¸¥§¥¯¥È¤¬ÊÝ»ý¤·¤Æ¤¤¤¿»ñ¸»¤ò²òÊü¤¹¤ë¡£
 208 .B "sem_destroy"
 209 ¤¬¸Æ¤Ó½Ð¤µ¤ì¤ë¤È¤¤Ë¤½¤Î¥»¥Þ¥Õ¥©¤ò³ÍÆÀÂÔ¤Á¤·¤Æ¤¤¤ë
 210 ¥¹¥ì¥Ã¥É¤¬¤¢¤Ã¤Æ¤Ï¤Ê¤é¤Ê¤¤¡£
 211 LinuxThreads ¤Î¼ÂÁõ¤Ç¤Ï¡¢
 212 ¥»¥Þ¥Õ¥©¥ª¥Ö¥¸¥§¥¯¥È¤Ï²¿¤â»ñ¸»¤òÊÝ»ý¤·¤Ê¤¤¤¿¤á¡¢
 213 .B "sem_destroy"
 214 ¤Ï¤½¤Î¥¹¥ì¥Ã¥É¤ò³ÍÆÀÂÔ¤Á¤·¤Æ¤¤¤ë¥¹¥ì¥Ã¥É¤¬¤Ê¤¤¤³¤È¤ò
 215 ¥Á¥§¥Ã¥¯¤¹¤ë°Ê³°¤Ë²¿¤â¤·¤Ê¤¤¡£
 216
 217 .\"O .SH CANCELLATION
 218 .SH "¼è¤ê¾Ã¤·"
 219
 220 .\"O .B "sem_wait"
 221 .\"O is a cancellation point.
 222 .B "sem_wait"
 223 ¤Ï¼è¤ê¾Ã¤·¥Ý¥¤¥ó¥È¤Ç¤¢¤ë¡£
 224
 225 .\"O .SH "ASYNC-SIGNAL SAFETY"
 226 .SH "ÈóÆ±´ü¥·¥°¥Ê¥ë¤Î°ÂÁ´À"
 227
 228 .\"O On processors supporting atomic compare-and-swap (Intel 486, Pentium
 229 .\"O and later, Alpha, PowerPC, MIPS II, Motorola 68k), the
 230 .\"O .B "sem_post"
 231 .\"O function is async-signal safe and can therefore be
 232 .\"O called from signal handlers. This is the only thread synchronization
 233 .\"O function provided by POSIX threads that is async-signal safe.
 234 ÉÔ²ÄÊ¬¤ÎÈæ³Ó¸ò´¹Ì¿Îá (compare-and-swap) ¤ò¥µ¥Ý¡¼¥È¤·¤Æ¤¤¤ë
 235 CPU (Intel 486 ¤ä Pentium ¤ª¤è¤Ó¤½¤Î¸å·Ñ¡¢
 236 Alpha ¡¢ PowerPC ¡¢ MIPS II ¡¢ Motorola 68k) ¤Ç¤Ï¡¢
 237 ´Ø¿ô
 238 .B "sem_post"
 239 ¤ÏÈóÆ±´ü¥·¥°¥Ê¥ë¤ËÂÐ¤·¤Æ°ÂÁ´¤Ç¤¢¤ê¡¢
 240 ¤½¤Î¤¿¤á¥·¥°¥Ê¥ë¥Ï¥ó¥É¥é¤«¤é¸Æ¤Ó½Ð¤¹¤³¤È¤¬²ÄÇ½¤Ç¤¢¤ë¡£
 241 .B "sem_post"
 242 ¤Ï¡¢ÈóÆ±´ü¥·¥°¥Ê¥ë¤ËÂÐ¤·¤Æ°ÂÁ´¤Ê¡¢
 243 POSIX ¥¹¥ì¥Ã¥É¤ÇÄó¶¡¤µ¤ì¤ëÍ£°ì¤Î¥¹¥ì¥Ã¥ÉÆ±´ü´Ø¿ô¤Ç¤¢¤ë¡£
 244
 245 .\"O On the Intel 386 and the Sparc, the current LinuxThreads
 246 .\"O implementation of
 247 .\"O .B "sem_post"
 248 .\"O is not async-signal safe by lack of the
 249 .\"O required atomic operations.
 250 Intel 386 ¤È Sparc ¤Ë¤ª¤¤¤Æ¤Ï¡¢
 251 ¸½»þÅÀ¤Î LinuxThreads ¤Î¼ÂÁõ¤Ç¤Ï
 252 .B "sem_post"
 253 ¤ÏÈóÆ±´ü¥·¥°¥Ê¥ë¤ËÂÐ¤·¤Æ°ÂÁ´¤Ç¤Ê¤¤¡£
 254 ¤³¤ì¤ÏÉ¬Í×¤ÊÉÔ²ÄÊ¬Ì¿Îá¤¬Â¸ºß¤·¤Ê¤¤¤«¤é¤Ç¤¢¤ë¡£
 255
 256 .\"O .SH "RETURN VALUE"
 257 .SH "ÊÖ¤êÃÍ"
 258
 259 .\"O The
 260 .\"O .B "sem_wait"
 261 .\"O and
 262 .\"O .B "sem_getvalue"
 263 .\"O functions always return 0.
 264 .\"O All other semaphore functions return 0 on success and -1 on error, in
 265 .\"O addition to writing an error code in
 266 .\"O .BR "errno" .
 267 ´Ø¿ô
 268 .B "sem_wait"
 269 ¤ª¤è¤Ó
 270 .B "sem_getvalue"
 271 ¤Ï¾ï¤Ë 0 ¤òÊÖ¤¹¡£
 272 Â¾¤Î¥»¥Þ¥Õ¥©´Ø¿ô¤Ï¤¹¤Ù¤Æ¡¢
 273 À®¸ù¤¹¤ë¤È 0 ¤òÊÖ¤·¡¢
 274 ¥¨¥é¡¼¤Ê¤é¤Ð -1 ¤òÊÖ¤·¤Æ¥¨¥é¡¼¥³¡¼¥É¤ò
 275 .B "errno"
 276 ¤Ë³ÊÇ¼¤¹¤ë¡£
 277
 278 .\"O .SH ERRORS
 279 .SH "¥¨¥é¡¼"
 280
 281 .\"O The
 282 .\"O .B "sem_init"
 283 .\"O function sets
 284 .\"O .B "errno"
 285 .\"O to the following codes on error:
 286 .\"O .RS
 287 .\"O .TP
 288 .\"O .B "EINVAL"
 289 .\"O .I "value"
 290 .\"O exceeds the maximal counter value
 291 .\"O .B "SEM_VALUE_MAX"
 292 .\"O .TP
 293 .\"O .B "ENOSYS"
 294 .\"O .I "pshared"
 295 .\"O is not zero
 296 .\"O .RE
 297 ´Ø¿ô
 298 .B "sem_init"
 299 ¤Ï¥¨¥é¡¼¤Î¾ì¹ç¤Ë¼¡¤Î¤è¤¦¤Ê¥¨¥é¡¼¥³¡¼¥É¤ò
 300 .B "errno"
 301 ¤Ë³ÊÇ¼¤¹¤ë¡£
 302 .RS
 303 .TP
 304 .B "EINVAL"
 305 .I "value"
 306 ¤¬¥«¥¦¥ó¥¿¤ÎºÇÂçÃÍ
 307 .B "SEM_VALUE_MAX"
 308 ¤òÄ¶¤¨¤Æ¤¤¤ë¡£
 309 .TP
 310 .B "ENOSYS"
 311 .I "pshared"
 312 ¤¬ 0 ¤Ç¤Ê¤¤¡£
 313 .RE
 314
 315 .\"O The
 316 .\"O .B "sem_trywait"
 317 .\"O function sets
 318 .\"O .B "errno"
 319 .\"O to the following error code on error:
 320 .\"O .RS
 321 .\"O .TP
 322 .\"O .B "EAGAIN"
 323 .\"O the semaphore count is currently 0
 324 .\"O .RE
 325 ´Ø¿ô
 326 .B "sem_trywait"
 327 ¤Ï¥¨¥é¡¼¤Î¾ì¹ç¤Ë¼¡¤Î¤è¤¦¤Ê¥¨¥é¡¼¥³¡¼¥É¤ò
 328 .B "errno"
 329 ¤Ë³ÊÇ¼¤¹¤ë¡£
 330 .RS
 331 .TP
 332 .B "EAGAIN"
 333 ¸½»þÅÀ¤Î¥»¥Þ¥Õ¥©¥«¥¦¥ó¥È¤¬ 0 ¤Ç¤¢¤ë¡£
 334 .RE
 335
 336 .\"O The
 337 .\"O .B "sem_post"
 338 .\"O function sets
 339 .\"O .B "errno"
 340 .\"O to the following error code on error:
 341 .\"O .RS
 342 .\"O .TP
 343 .\"O .B "ERANGE"
 344 .\"O after incrementation, the semaphore value would exceed
 345 .\"O .B "SEM_VALUE_MAX"
 346 .\"O (the semaphore count is left unchanged in this case)
 347 .\"O .RE
 348 ´Ø¿ô
 349 .B "sem_post"
 350 ¤Ï¥¨¥é¡¼¤Î¾ì¹ç¤Ë¼¡¤Î¤è¤¦¤Ê¥¨¥é¡¼¥³¡¼¥É¤ò
 351 .B "errno"
 352 ¤Ë³ÊÇ¼¤¹¤ë¡£
 353 .RS
 354 .TP
 355 .B "ERANGE"
 356 ¥«¥¦¥ó¥¿¤òÁý²Ã¤¹¤ë¤È¡¢¥»¥Þ¥Õ¥©¤ÎÃÍ¤¬
 357 .B "SEM_VALUE_MAX"
 358 ¤òÄ¶¤¨¤Æ¤·¤Þ¤¦
 359 (¤³¤Î¾ì¹ç¡¢¥»¥Þ¥Õ¥©¥«¥¦¥ó¥È¤ÏÊÑ¹¹¤µ¤ì¤Ê¤¤) ¡£
 360 .RE
 361
 362 .\"O The
 363 .\"O .B "sem_destroy"
 364 .\"O function sets
 365 .\"O .B "errno"
 366 .\"O to the following error code on error:
 367 .\"O .RS
 368 .\"O .TP
 369 .\"O .B "EBUSY"
 370 .\"O some threads are currently blocked waiting on the semaphore.
 371 .\"O .RE
 372 ´Ø¿ô
 373 .B "sem_destroy"
 374 ¤Ï¥¨¥é¡¼¤Î¾ì¹ç¤Ë¼¡¤Î¤è¤¦¤Ê¥¨¥é¡¼¥³¡¼¥É¤ò
 375 .B "errno"
 376 ¤Ë³ÊÇ¼¤¹¤ë:
 377 .RS
 378 .TP
 379 .B "EBUSY"
 380 »ØÄê¤·¤¿¥»¥Þ¥Õ¥©¤Î³ÍÆÀÂÔ¤Á¤Ç¥Ö¥í¥Ã¥¯¤µ¤ì¤Æ¤¤¤ë¥¹¥ì¥Ã¥É¤¬¤¢¤ë¡£
 381 .RE
 382
 383 .\"O .SH AUTHOR
 384 .SH "Ãø¼Ô"
 385 Xavier Leroy <Xavier.Leroy@inria.fr>
 386
 387 .\"O .SH "SEE ALSO"
 388 .SH "´ØÏ¢»ö¹à"
 389 .BR "pthread_mutex_init" (3),
 390 .BR "pthread_cond_init" (3),
 391 .BR "pthread_cancel" (3),
 392 .BR "ipc" (5).