draft/man2/semget.2

   1 .\" Copyright 1993 Giorgio Ciucci (giorgio@crcc.it)
   2 .\"
   3 .\" Permission is granted to make and distribute verbatim copies of this
   4 .\" 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 this
   8 .\" manual under the conditions for verbatim copying, provided that the
   9 .\" entire resulting derived work is distributed under the terms of a
  10 .\" permission notice identical to this one.
  11 .\"
  12 .\" Since the Linux kernel and libraries are constantly changing, this
  13 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  14 .\" responsibility for errors or omissions, or for damages resulting from
  15 .\" the use of the information contained herein.  The author(s) may not
  16 .\" have taken the same level of care in the production of this manual,
  17 .\" which is licensed free of charge, as they might when working
  18 .\" professionally.
  19 .\"
  20 .\" Formatted or processed versions of this manual, if unaccompanied by
  21 .\" the source, must acknowledge the copyright and authors of this work.
  22 .\"
  23 .\" Modified Tue Oct 22 17:54:56 1996 by Eric S. Raymond <esr@thyrsus.com>
  24 .\" Modified 1 Jan 2002, Martin Schulze <joey@infodrom.org>
  25 .\" Modified 4 Jan 2002, Michael Kerrisk <mtk.manpages@gmail.com>
  26 .\" Modified, 27 May 2004, Michael Kerrisk <mtk.manpages@gmail.com>
  27 .\"     Added notes on capability requirements
  28 .\" Modified, 11 Nov 2004, Michael Kerrisk <mtk.manpages@gmail.com>
  29 .\"     Language and formatting clean-ups
  30 .\"     Added notes on /proc files
  31 .\"     Rewrote BUGS note about semget()'s failure to initialize
  32 .\"             semaphore values
  33 .\"
  34 .\" Japanese Version Copyright (c) 1997 HANATAKA Shinya
  35 .\"         all rights reserved.
  36 .\" Translated 1997-02-23, HANATAKA Shinya <hanataka@abyss.rim.or.jp>
  37 .\" Updated 2003-04-08, Kentaro Shirakata <argrath@ub32.org>
  38 .\" Updated 2005-03-01, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>
  39 .\" Updated 2006-07-20, Akihiro MOTOKI, LDP v2.36
  40 .\"
  41 .\"WORD:        semaphore               セマフォ
  42 .\"WORD:        identifier              識別子
  43 .\"WORD:        owner                   所有者
  44 .\"WORD:        group                   グループ
  45 .\"WORD:        other                   他人
  46 .\"WORD:        effective user ID       実効ユーザー ID
  47 .\"WORD:        effective group ID      実効グループ ID
  48 .\"WORD:        calling process         呼び出し元のプロセス
  49 .\"WORD:        process                 プロセス
  50 .\"WORD:        policy                  方針
  51 .\"WORD:        structure               構造体
  52 .\"WORD:        initialize              初期化
  53 .\"WORD:        system call             システム・コール
  54 .\"
  55 .TH SEMGET 2 2004-05-27 "Linux" "Linux Programmer's Manual"
  56 .\"O .SH NAME
  57 .SH 名前
  58 .\"O semget \- get a semaphore set identifier
  59 semget \- セマフォ集合の識別子を取得する
  60 .\"O .SH SYNOPSIS
  61 .SH 書式
  62 .nf
  63 .B #include <sys/types.h>
  64 .B #include <sys/ipc.h>
  65 .B #include <sys/sem.h>
  66 .fi
  67 .sp
  68 .BI "int semget(key_t " key ,
  69 .BI "int " nsems ,
  70 .BI "int " semflg );
  71 .\"O .SH DESCRIPTION
  72 .SH 説明
  73 .\"O The
  74 .\"O .BR semget ()
  75 .\"O system call returns the semaphore set identifier
  76 .\"O associated with the argument
  77 .\"O .IR key .
  78 .BR semget ()
  79 システムコールは、引き数
  80 .I key
  81 に対応するセマフォ集合 (semaphore set) の
  82 識別子 (identifier) を返す。
  83 .\"O A new set of
  84 .\"O .I nsems
  85 .\"O semaphores is created if
  86 .\"O .I key
  87 .\"O has the value
  88 .\"O .B IPC_PRIVATE
  89 .\"O or if no existing semaphore set is associated with
  90 .\"O .I key
  91 .\"O and
  92 .\"O .B IPC_CREAT
  93 .\"O is specified in
  94 .\"O .IR semflg .
  95 .I key
  96 の値が
  97 .B IPC_PRIVATE
  98 の場合、もしくは
  99 .I semflg
 100 に
 101 .B IPC_CREAT
 102 が指定されていて、
 103 .I key
 104 に対応するセマフォ集合が存在しない場合、
 105 .I nsems
 106 個のセマフォからなる新しい集合が作成される。
 107 .PP
 108 .\"O If
 109 .\"O .I semflg
 110 .\"O specifies both
 111 .\"O .B IPC_CREAT
 112 .\"O and
 113 .\"O .B IPC_EXCL
 114 .\"O and a semaphore set already exists for
 115 .\"O .IR key ,
 116 .\"O then
 117 .\"O .BR semget ()
 118 .\"O fails with
 119 .\"O .I errno
 120 .\"O set to
 121 .\"O .BR EEXIST .
 122 .\"O (This is analogous to the effect of the combination
 123 .\"O .B O_CREAT | O_EXCL
 124 .\"O for
 125 .\"O .BR open (2).)
 126 .I semflg
 127 に
 128 .B IPC_CREAT
 129 と
 130 .B IPC_EXCL
 131 の両方が指定された場合、
 132 .I key
 133 に対応するセマフォ集合が既に存在すると、
 134 .BR semget ()
 135 は失敗し、
 136 .I errno
 137 に
 138 .B EEXIST
 139 が設定される
 140 (これは
 141 .BR open (2)
 142 に
 143 .B O_CREAT | O_EXCL
 144 が指定された場合の動作と同じである)。
 145 .PP
 146 .\"O Upon creation, the least significant 9 bits of the argument
 147 .\"O .I semflg
 148 .\"O define the permissions (for owner, group and others)
 149 .\"O for the semaphore set.
 150 .\"O These bits have the same format, and the same
 151 .\"O meaning, as the
 152 .\"O .I mode
 153 .\"O argument of
 154 .\"O .BR open (2)
 155 .\"O (though the execute permissions are
 156 .\"O not meaningful for semaphores, and write permissions mean permission
 157 .\"O to alter semaphore values).
 158 セマフォ集合作成時に、引き数
 159 .I semflg
 160 の下位 9 ビットは、そのセマフォ集合の (所有者 (owner)、グループ (group)、
 161 他人 (others) に対する) アクセス許可の定義として使用される。
 162 これらのビットは
 163 .BR open (2)
 164 の引き数
 165 .I mode
 166 と同じ形式で同じ意味である
 167 (但し、実行 (execute) 許可はセマフォでは意味を持たず、
 168 書き込み (write) 許可はセマフォ値の変更 (alter) 許可として機能する)。
 169 .PP
 170 .\"O The values of the semaphores in a newly created set are indeterminate.
 171 .\"O (POSIX.1-2001 is explicit on this point.)
 172 .\"O Although Linux, like many other implementations,
 173 .\"O initializes the semaphore values to 0,
 174 .\"O a portable application cannot rely on this:
 175 .\"O it should explicitly initialize the semaphores to the desired values.
 176 新しく作成されたセマフォ集合の各セマフォの値は不定である
 177 (この点は POSIX.1-2001 に明記されている)。
 178 Linux は他の多くの実装と同様にセマフォ値を 0 に初期化するが、
 179 移植性を考慮したアプリケーションではこの動作を前提にすべきではない。
 180 アプリケーションは明示的にセマフォを希望の値で初期化すべきである。
 181 .\" In truth, every one of the many implementations that I've tested sets
 182 .\" the values to zero, but I suppose there is/was some obscure
 183 .\" implementation out there that does not.
 184 .PP
 185 .\"O When creating a new semaphore set,
 186 .\"O .BR semget ()
 187 .\"O initializes the set's associated data structure,
 188 .\"O .I semid_ds
 189 .\"O (see
 190 .\"O .BR semctl (2)),
 191 .\"O as follows:
 192 新規のセマフォ集合を作成する際、
 193 .BR semget ()
 194 はセマフォ集合の情報を保持するデータ構造体
 195 .I semid_ds
 196 を次のように初期化する
 197 .RI ( semid_ds
 198 については
 199 .BR semctl (2)
 200 を参照):
 201 .IP
 202 .\"O .I sem_perm.cuid
 203 .\"O and
 204 .\"O .I sem_perm.uid
 205 .\"O are set to the effective user ID of the calling process.
 206 .I sem_perm.cuid
 207 と
 208 .I sem_perm.uid
 209 に、呼び出し元のプロセスの実効 (effective) ユーザ ID を設定する。
 210 .IP
 211 .\"O .I sem_perm.cgid
 212 .\"O and
 213 .\"O .I sem_perm.gid
 214 .\"O are set to the effective group ID of the calling process.
 215 .I sem_perm.cgid
 216 と
 217 .I sem_perm.gid
 218 に、呼び出し元のプロセスの実効 (effective) グループ ID を設定する。
 219 .IP
 220 .\"O The least significant 9 bits of
 221 .\"O .I sem_perm.mode
 222 .\"O are set to the least significant 9 bits of
 223 .\"O .IR semflg .
 224 .I sem_perm.mode
 225 の下位 9 ビットに
 226 .I semflg
 227 の下位 9 ビットを設定する。
 228 .IP
 229 .\"O .I sem_nsems
 230 .\"O is set to the value of
 231 .\"O .IR nsems .
 232 .I sem_nsems
 233 に
 234 .I nsems
 235 の値を設定する。
 236 .IP
 237 .\"O .I sem_otime
 238 .\"O is set to 0.
 239 .I sem_otime
 240 に 0 を設定する。
 241 .IP
 242 .\"O .I sem_ctime
 243 .\"O is set to the current time.
 244 .I sem_ctime
 245 に現在の時刻を設定する。
 246 .PP
 247 .\"O The argument
 248 .\"O .I nsems
 249 .\"O can be 0
 250 .\"O (a don't care)
 251 .\"O when a semaphore set is not being created.
 252 .\"O Otherwise
 253 .\"O .I nsems
 254 .\"O must be greater than 0
 255 .\"O and less than or equal to the maximum number of semaphores per semaphore set
 256 .\"O .RB ( SEMMSL ).
 257 セマフォ集合の作成を行わない場合は、引き数
 258 .I nsems
 259 に (don't care を意味する) 0 を指定してもよい。
 260 そうでない場合は、
 261 .I nsems
 262 は 0 より大きい値でなければならず、セマフォ集合あたりのセマフォの最大数
 263 .RB ( SEMMSL )
 264 以下でなければならない。
 265 .PP
 266 .\"O If the semaphore set already exists, the permissions are
 267 .\"O verified.
 268 セマフォ集合が既に存在した場合は、アクセス許可の検査が行われる。
 269 .\"O .\" and a check is made to see if it is marked for destruction.
 270 .\" 破壊 (destruction) マークがないかチェックされる。
 271 .\"O .SH "RETURN VALUE"
 272 .SH 返り値
 273 .\"O If successful, the return value will be the semaphore set identifier
 274 .\"O (a nonnegative integer), otherwise \-1
 275 .\"O is returned, with
 276 .\"O .I errno
 277 .\"O indicating the error.
 278 成功した場合、セマフォ集合の識別子 (非負の整数) が返り値となる。
 279 失敗した場合は \-1 が返され、
 280 .I errno
 281 にエラーを示す値が設定される。
 282 .\"O .SH ERRORS
 283 .SH エラー
 284 .\"O On failure
 285 .\"O .I errno
 286 .\"O will be set to one of the following:
 287 失敗した場合、
 288 .I errno
 289 には以下の値のいずれか一つが設定される:
 290 .TP
 291 .B EACCES
 292 .\"O A semaphore set exists for
 293 .\"O .IR key ,
 294 .\"O but the calling process does not have permission to access the set,
 295 .\"O and does not have the
 296 .\"O .B CAP_IPC_OWNER
 297 .\"O capability.
 298 .I key
 299 に対応するセマフォ集合は存在するが、
 300 呼び出し元のプロセスはその集合へのアクセス許可がなく、
 301 .B CAP_IPC_OWNER
 302 ケーパビリティも持っていない。
 303 .TP
 304 .B EEXIST
 305 .\"O A semaphore set exists for
 306 .\"O .I key
 307 .\"O and
 308 .\"O .I semflg
 309 .\"O specified both
 310 .\"O .B IPC_CREAT
 311 .\"O and
 312 .\"O .BR IPC_EXCL .
 313 .I key
 314 に対応するセマフォ集合が存在し、
 315 .I semflg
 316 には
 317 .B IPC_CREAT
 318 と
 319 .B IPC_EXCL
 320 が指定されていた。
 321 .\" .TP
 322 .\"O .\" .B EIDRM
 323 .\"O .\" The semaphore set is marked to be deleted.
 324 .\" .B EIDRM
 325 .\" セマフォ集合に削除 (delete) マークがつけられている。
 326 .TP
 327 .B EINVAL
 328 .\"O .I nsems
 329 .\"O is less than 0 or greater than the limit on the number
 330 .\"O of semaphores per semaphore set
 331 .\"O .RB ( SEMMSL ),
 332 .I nsems
 333 が 0 より小さいか、セマフォ集合あたりのセマフォの最大数
 334 .RB ( SEMMSL )
 335 より大きい。
 336 .\"O or a semaphore set corresponding to
 337 .\"O .I key
 338 .\"O already exists, and
 339 .\"O .I nsems
 340 .\"O is larger than the number of semaphores in that set.
 341 または、
 342 .I key
 343 に対応するセマフォ集合が既に存在し、
 344 .I nsems
 345 がその集合のセマフォ数よりも大きい。
 346 .TP
 347 .B ENOENT
 348 .\"O No semaphore set exists for
 349 .\"O .I key
 350 .\"O and
 351 .\"O .I semflg
 352 .\"O did not specify
 353 .\"O .BR IPC_CREAT .
 354 .I key
 355 に対応するセマフォ集合が存在せず、
 356 .I semflg
 357 に
 358 .B IPC_CREAT
 359 が指定されてもいない。
 360 .TP
 361 .B ENOMEM
 362 .\"O A semaphore set has to be created but the system does not have
 363 .\"O enough memory for the new data structure.
 364 セマフォ集合を作成しようとしたが、新しいデータ構造体を
 365 作成するのに十分なメモリがシステムに存在しない。
 366 .TP
 367 .B ENOSPC
 368 .\"O A semaphore set has to be created but the system limit for the maximum
 369 .\"O number of semaphore sets
 370 .\"O .RB ( SEMMNI ),
 371 .\"O or the system wide maximum number of semaphores
 372 .\"O .RB ( SEMMNS ),
 373 .\"O would be exceeded.
 374 セマフォ集合を作成しようとすると、システムのセマフォ集合の
 375 最大数
 376 .RB ( SEMMNI )
 377 か、システム全体のセマフォの最大数
 378 .RB ( SEMMNS )
 379 のいずれかを超えてしまう。
 380 .\"O .SH "CONFORMING TO"
 381 .SH 準拠
 382 SVr4, POSIX.1-2001.
 383 .\"O .\" SVr4 documents additional error conditions EFBIG, E2BIG, EAGAIN,
 384 .\"O .\" ERANGE, EFAULT.
 385 .\" SVr4 には、追加で EFBIG, E2BIG, EAGAIN, ERANGE, EFAULT
 386 .\" のエラー状態についての記述がある。
 387 .\"O .SH NOTES
 388 .SH 注意
 389 .\"O .B IPC_PRIVATE
 390 .\"O isn't a flag field but a
 391 .\"O .I key_t
 392 .\"O type.
 393 .B IPC_PRIVATE
 394 はフラグ・フィールドに指定するものではなく、
 395 .I key_t
 396 型である。
 397 .\"O If this special value is used for
 398 .\"O .IR key ,
 399 .\"O the system call ignores everything but the least significant 9 bits of
 400 .\"O .I semflg
 401 .\"O and creates a new semaphore set (on success).
 402 この特別な値が
 403 .I key
 404 に指定されると、
 405 .BR semget ()
 406 .I semflg
 407 の下位 9 ビット以外は全て無視し、
 408 (成功した場合は) 新しいセマフォ集合を作成する。
 409 .PP
 410 .\"O The following limits on semaphore set resources affect the
 411 .\"O .BR semget ()
 412 .\"O call:
 413 セマフォ集合のリソースに関する制限のうち、
 414 .BR semget ()
 415 に影響を及ぼすものを以下に挙げる:
 416 .TP
 417 .B SEMMNI
 418 .\"O System wide maximum number of semaphore sets: policy dependent
 419 .\"O (on Linux, this limit can be read and modified via the fourth field of
 420 .\"O .IR /proc/sys/kernel/sem ).
 421 .\"O .\" This /proc file is not available in Linux 2.2 and earlier -- MTK
 422 システム全体のセマフォ集合の最大数: 方針依存
 423 (Linux では、この制限値は
 424 .I /proc/sys/kernel/sem
 425 の第4フィールドに対応し、読み出しも変更もできる)。
 426 .\" この /proc ファイルは Linux 2.2 以前では利用できない -- MTK
 427 .TP
 428 .B SEMMSL
 429 .\"O Maximum number of semaphores per semid: implementation dependent
 430 .\"O (on Linux, this limit can be read and modified via the first field of
 431 .\"O .IR /proc/sys/kernel/sem ).
 432 semid あたりのセマフォの最大数: 実装依存
 433 (Linux では、この制限値は
 434 .I /proc/sys/kernel/sem
 435 の第1フィールドに対応し、読み出しも変更もできる)。
 436 .TP
 437 .B SEMMNS
 438 .\"O System wide maximum number of semaphores: policy dependent
 439 .\"O (on Linux, this limit can be read and modified via the second field of
 440 .\"O .IR /proc/sys/kernel/sem ).
 441 .\"O Values greater than
 442 .\"O .B SEMMSL * SEMMNI
 443 .\"O makes it irrelevant.
 444 システム全体のセマフォの最大数: 方針依存
 445 (Linux では、この制限値は
 446 .I /proc/sys/kernel/sem
 447 の第2フィールドに対応し、読み出しも変更もできる)。
 448 .B SEMMSL * SEMMNI
 449 より大きな値は意味を持たない。
 450 .\"O .SH BUGS
 451 .SH バグ
 452 .\"O The name choice
 453 .\"O .B IPC_PRIVATE
 454 .\"O was perhaps unfortunate,
 455 .\"O .B IPC_NEW
 456 .\"O would more clearly show its function.
 457 .B IPC_PRIVATE
 458 という名前を選んだのはおそらく失敗であろう。
 459 .B IPC_NEW
 460 の方がより明確にその機能を表しているだろう。
 461 .LP
 462 .\"O The semaphores in a set are not initialized by
 463 .\"O .BR semget ().
 464 .\"O .\" In fact they are initialized to zero on Linux, but POSIX.1-2001
 465 .\"O .\" does not specify this, and we can't portably rely on it.
 466 .\"O In order to initialize the semaphores,
 467 .\"O .BR semctl (2)
 468 .\"O must be used to perform a
 469 .\"O .B SETVAL
 470 .\"O or a
 471 .\"O .B SETALL
 472 .\"O operation on the semaphore set.
 473 セマフォ集合内のセマフォは
 474 .BR semget ()
 475 では初期化されない。
 476 .\" 実際は Linux ではセマフォは 0 に初期化されるが、
 477 .\" POSIX.1-2001 ではこうなることを規定している訳ではないので、
 478 .\" 移植を考慮するときにはこれを前提にしてはいけない。
 479 このセマフォを初期化するには、セマフォ集合に対して
 480 .BR semctl (2)
 481 を使って
 482 .B SETVAL
 483 か
 484 .B SETALL
 485 操作を実行する必要がある。
 486 .\"O (Where multiple peers do not know who will be the first to
 487 .\"O initialize the set, checking for a nonzero
 488 .\"O .I sem_otime
 489 .\"O in the associated data structure retrieved by a
 490 .\"O .BR semctl (2)
 491 .\"O .B IPC_STAT
 492 .\"O operation can be used to avoid races.)
 493 (複数箇所からセマフォ集合の操作が行われる場面では、
 494 誰が最初に集合を初期化すればよいか分からない。
 495 この状況を避けるには、
 496 .BR semctl (2)
 497 の
 498 .B IPC_STAT
 499 操作で取得できるセマフォのデータ構造体の
 500 .I sem_otime
 501 が 0 以外になっているかをチェックすればよい。)
 502 .\"O .SH "SEE ALSO"
 503 .SH 関連項目
 504 .BR semctl (2),
 505 .BR semop (2),
 506 .BR ftok (3),
 507 .BR capabilities (7),
 508 .BR sem_overview (7),
 509 .BR svipc (7)