release/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 .SH 名前
  57 semget \- セマフォ集合の識別子を取得する
  58 .SH 書式
  59 .nf
  60 .B #include <sys/types.h>
  61 .B #include <sys/ipc.h>
  62 .B #include <sys/sem.h>
  63 .fi
  64 .sp
  65 .BI "int semget(key_t " key ,
  66 .BI "int " nsems ,
  67 .BI "int " semflg );
  68 .SH 説明
  69 .BR semget ()
  70 システムコールは、引き数
  71 .I key
  72 に対応するセマフォ集合 (semaphore set) の
  73 識別子 (identifier) を返す。
  74 .I key
  75 の値が
  76 .B IPC_PRIVATE
  77 の場合、もしくは
  78 .I semflg
  79 に
  80 .B IPC_CREAT
  81 が指定されていて、
  82 .I key
  83 に対応するセマフォ集合が存在しない場合、
  84 .I nsems
  85 個のセマフォからなる新しい集合が作成される。
  86 .PP
  87 .I semflg
  88 に
  89 .B IPC_CREAT
  90 と
  91 .B IPC_EXCL
  92 の両方が指定された場合、
  93 .I key
  94 に対応するセマフォ集合が既に存在すると、
  95 .BR semget ()
  96 は失敗し、
  97 .I errno
  98 に
  99 .B EEXIST
 100 が設定される
 101 (これは
 102 .BR open (2)
 103 に
 104 .B O_CREAT | O_EXCL
 105 が指定された場合の動作と同じである)。
 106 .PP
 107 セマフォ集合作成時に、引き数
 108 .I semflg
 109 の下位 9 ビットは、そのセマフォ集合の (所有者 (owner)、グループ (group)、
 110 他人 (others) に対する) アクセス許可の定義として使用される。
 111 これらのビットは
 112 .BR open (2)
 113 の引き数
 114 .I mode
 115 と同じ形式で同じ意味である
 116 (但し、実行 (execute) 許可はセマフォでは意味を持たず、
 117 書き込み (write) 許可はセマフォ値の変更 (alter) 許可として機能する)。
 118 .PP
 119 新しく作成されたセマフォ集合の各セマフォの値は不定である
 120 (この点は POSIX.1-2001 に明記されている)。
 121 Linux は他の多くの実装と同様にセマフォ値を 0 に初期化するが、
 122 移植性を考慮したアプリケーションではこの動作を前提にすべきではない。
 123 アプリケーションは明示的にセマフォを希望の値で初期化すべきである。
 124 .\" In truth, every one of the many implementations that I've tested sets
 125 .\" the values to zero, but I suppose there is/was some obscure
 126 .\" implementation out there that does not.
 127 .PP
 128 新規のセマフォ集合を作成する際、
 129 .BR semget ()
 130 はセマフォ集合の情報を保持するデータ構造体
 131 .I semid_ds
 132 を次のように初期化する
 133 .RI ( semid_ds
 134 については
 135 .BR semctl (2)
 136 を参照):
 137 .IP
 138 .I sem_perm.cuid
 139 と
 140 .I sem_perm.uid
 141 に、呼び出し元のプロセスの実効 (effective) ユーザ ID を設定する。
 142 .IP
 143 .I sem_perm.cgid
 144 と
 145 .I sem_perm.gid
 146 に、呼び出し元のプロセスの実効 (effective) グループ ID を設定する。
 147 .IP
 148 .I sem_perm.mode
 149 の下位 9 ビットに
 150 .I semflg
 151 の下位 9 ビットを設定する。
 152 .IP
 153 .I sem_nsems
 154 に
 155 .I nsems
 156 の値を設定する。
 157 .IP
 158 .I sem_otime
 159 に 0 を設定する。
 160 .IP
 161 .I sem_ctime
 162 に現在の時刻を設定する。
 163 .PP
 164 セマフォ集合の作成を行わない場合は、引き数
 165 .I nsems
 166 に (don't care を意味する) 0 を指定してもよい。
 167 そうでない場合は、
 168 .I nsems
 169 は 0 より大きい値でなければならず、セマフォ集合あたりのセマフォの最大数
 170 .RB ( SEMMSL )
 171 以下でなければならない。
 172 .PP
 173 セマフォ集合が既に存在した場合は、アクセス許可の検査が行われる。
 174 .\" 破壊 (destruction) マークがないかチェックされる。
 175 .SH 返り値
 176 成功した場合、セマフォ集合の識別子 (非負の整数) が返り値となる。
 177 失敗した場合は \-1 が返され、
 178 .I errno
 179 にエラーを示す値が設定される。
 180 .SH エラー
 181 失敗した場合、
 182 .I errno
 183 には以下の値のいずれか一つが設定される:
 184 .TP
 185 .B EACCES
 186 .I key
 187 に対応するセマフォ集合は存在するが、
 188 呼び出し元のプロセスはその集合へのアクセス許可がなく、
 189 .B CAP_IPC_OWNER
 190 ケーパビリティも持っていない。
 191 .TP
 192 .B EEXIST
 193 .I key
 194 に対応するセマフォ集合が存在し、
 195 .I semflg
 196 には
 197 .B IPC_CREAT
 198 と
 199 .B IPC_EXCL
 200 が指定されていた。
 201 .\" .TP
 202 .\" .B EIDRM
 203 .\" セマフォ集合に削除 (delete) マークがつけられている。
 204 .TP
 205 .B EINVAL
 206 .I nsems
 207 が 0 より小さいか、セマフォ集合あたりのセマフォの最大数
 208 .RB ( SEMMSL )
 209 より大きい。
 210 または、
 211 .I key
 212 に対応するセマフォ集合が既に存在し、
 213 .I nsems
 214 がその集合のセマフォ数よりも大きい。
 215 .TP
 216 .B ENOENT
 217 .I key
 218 に対応するセマフォ集合が存在せず、
 219 .I semflg
 220 に
 221 .B IPC_CREAT
 222 が指定されてもいない。
 223 .TP
 224 .B ENOMEM
 225 セマフォ集合を作成しようとしたが、新しいデータ構造体を
 226 作成するのに十分なメモリがシステムに存在しない。
 227 .TP
 228 .B ENOSPC
 229 セマフォ集合を作成しようとすると、システムのセマフォ集合の
 230 最大数
 231 .RB ( SEMMNI )
 232 か、システム全体のセマフォの最大数
 233 .RB ( SEMMNS )
 234 のいずれかを超えてしまう。
 235 .SH 準拠
 236 SVr4, POSIX.1-2001.
 237 .\" SVr4 には、追加で EFBIG, E2BIG, EAGAIN, ERANGE, EFAULT
 238 .\" のエラー状態についての記述がある。
 239 .SH 注意
 240 .B IPC_PRIVATE
 241 はフラグ・フィールドに指定するものではなく、
 242 .I key_t
 243 型である。
 244 この特別な値が
 245 .I key
 246 に指定されると、
 247 .BR semget ()
 248 .I semflg
 249 の下位 9 ビット以外は全て無視し、
 250 (成功した場合は) 新しいセマフォ集合を作成する。
 251 .PP
 252 セマフォ集合のリソースに関する制限のうち、
 253 .BR semget ()
 254 に影響を及ぼすものを以下に挙げる:
 255 .TP
 256 .B SEMMNI
 257 システム全体のセマフォ集合の最大数: 方針依存
 258 (Linux では、この制限値は
 259 .I /proc/sys/kernel/sem
 260 の第4フィールドに対応し、読み出しも変更もできる)。
 261 .\" この /proc ファイルは Linux 2.2 以前では利用できない -- MTK
 262 .TP
 263 .B SEMMSL
 264 semid あたりのセマフォの最大数: 実装依存
 265 (Linux では、この制限値は
 266 .I /proc/sys/kernel/sem
 267 の第1フィールドに対応し、読み出しも変更もできる)。
 268 .TP
 269 .B SEMMNS
 270 システム全体のセマフォの最大数: 方針依存
 271 (Linux では、この制限値は
 272 .I /proc/sys/kernel/sem
 273 の第2フィールドに対応し、読み出しも変更もできる)。
 274 .B SEMMSL * SEMMNI
 275 より大きな値は意味を持たない。
 276 .SH バグ
 277 .B IPC_PRIVATE
 278 という名前を選んだのはおそらく失敗であろう。
 279 .B IPC_NEW
 280 の方がより明確にその機能を表しているだろう。
 281 .LP
 282 セマフォ集合内のセマフォは
 283 .BR semget ()
 284 では初期化されない。
 285 .\" 実際は Linux ではセマフォは 0 に初期化されるが、
 286 .\" POSIX.1-2001 ではこうなることを規定している訳ではないので、
 287 .\" 移植を考慮するときにはこれを前提にしてはいけない。
 288 このセマフォを初期化するには、セマフォ集合に対して
 289 .BR semctl (2)
 290 を使って
 291 .B SETVAL
 292 か
 293 .B SETALL
 294 操作を実行する必要がある。
 295 (複数箇所からセマフォ集合の操作が行われる場面では、
 296 誰が最初に集合を初期化すればよいか分からない。
 297 この状況を避けるには、
 298 .BR semctl (2)
 299 の
 300 .B IPC_STAT
 301 操作で取得できるセマフォのデータ構造体の
 302 .I sem_otime
 303 が 0 以外になっているかをチェックすればよい。)
 304 .SH 関連項目
 305 .BR semctl (2),
 306 .BR semop (2),
 307 .BR ftok (3),
 308 .BR capabilities (7),
 309 .BR sem_overview (7),
 310 .BR svipc (7)