.\" Copyright 1993 Giorgio Ciucci (giorgio@crcc.it)
.\" and Copyright (C) 2020 Michael Kerrisk <mtk.manpages@gmail.com>
.\"
.\" %%%LICENSE_START(VERBATIM)
.\" Permission is granted to make and distribute verbatim copies of this
.\" manual provided the copyright notice and this permission notice are
.\" preserved on all copies.
.\"
.\" Permission is granted to copy and distribute modified versions of this
.\" manual under the conditions for verbatim copying, provided that the
.\" entire resulting derived work is distributed under the terms of a
.\" permission notice identical to this one.
.\"
.\" Since the Linux kernel and libraries are constantly changing, this
.\" manual page may be incorrect or out-of-date.  The author(s) assume no
.\" responsibility for errors or omissions, or for damages resulting from
.\" the use of the information contained herein.  The author(s) may not
.\" have taken the same level of care in the production of this manual,
.\" which is licensed free of charge, as they might when working
.\" professionally.
.\"
.\" Formatted or processed versions of this manual, if unaccompanied by
.\" the source, must acknowledge the copyright and authors of this work.
.\" %%%LICENSE_END
.\"
.\" Modified Tue Oct 22 17:54:56 1996 by Eric S. Raymond <esr@thyrsus.com>
.\" Modified 1 Jan 2002, Martin Schulze <joey@infodrom.org>
.\" Modified 4 Jan 2002, Michael Kerrisk <mtk.manpages@gmail.com>
.\" Modified, 27 May 2004, Michael Kerrisk <mtk.manpages@gmail.com>
.\"     Added notes on capability requirements
.\" Modified, 11 Nov 2004, Michael Kerrisk <mtk.manpages@gmail.com>
.\"	Language and formatting clean-ups
.\"	Added notes on /proc files
.\"	Rewrote BUGS note about semget()'s failure to initialize
.\"		semaphore values
.\"
.\"*******************************************************************
.\"
.\" This file was generated with po4a. Translate the source file.
.\"
.\"*******************************************************************
.\"
.\" Japanese Version Copyright (c) 1997 HANATAKA Shinya
.\"         all rights reserved.
.\" Translated 1997-02-23, HANATAKA Shinya <hanataka@abyss.rim.or.jp>
.\" Updated 2003-04-08, Kentaro Shirakata <argrath@ub32.org>
.\" Updated 2005-03-01, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>
.\" Updated 2006-07-20, Akihiro MOTOKI, LDP v2.36
.\" Updated 2013-05-01, Akihiro MOTOKI <amotoki@gmail.com>
.\"
.TH SEMGET 2 2020\-04\-11 Linux "Linux Programmer's Manual"
.SH 名前
semget \- System V セマフォ集合の識別子を取得する
.SH 書式
.nf
\fB#include <sys/types.h>\fP
\fB#include <sys/ipc.h>\fP
\fB#include <sys/sem.h>\fP
.fi
.PP
\fBint semget(key_t \fP\fIkey\fP\fB,\fP \fBint \fP\fInsems\fP\fB,\fP \fBint \fP\fIsemflg\fP\fB);\fP
.SH 説明
The \fBsemget\fP()  system call returns the System\ V semaphore set identifier
associated with the argument \fIkey\fP.  It may be used either to obtain the
identifier of a previously created semaphore set (when \fIsemflg\fP is zero and
\fIkey\fP does not have the value \fBIPC_PRIVATE\fP), or to create a new set.
.PP
\fIkey\fP の値が \fBIPC_PRIVATE\fP の場合、もしくは \fIsemflg\fP に \fBIPC_CREAT\fP が指定されていて、 \fIkey\fP
に対応するセマフォ集合が存在しない場合、 \fInsems\fP 個のセマフォからなる新しい集合が作成される。
.PP
\fIsemflg\fP に \fBIPC_CREAT\fP と \fBIPC_EXCL\fP の両方が指定された場合、 \fIkey\fP
に対応するセマフォ集合が既に存在すると、 \fBsemget\fP()  は失敗し、 \fIerrno\fP に \fBEEXIST\fP が設定される (これは
\fBopen\fP(2)  に \fBO_CREAT | O_EXCL\fP が指定された場合の動作と同じである)。
.PP
セマフォ集合作成時に、引数 \fIsemflg\fP の下位 9 ビットは、そのセマフォ集合の (所有者 (owner)、グループ (group)、 他人
(others) に対する) アクセス許可の定義として使用される。 これらのビットは \fBopen\fP(2)  の引数 \fImode\fP
と同じ形式で同じ意味である (但し、実行 (execute) 許可はセマフォでは意味を持たず、 書き込み (write) 許可はセマフォ値の変更
(alter) 許可として機能する)。
.PP
新規のセマフォ集合を作成する際、 \fBsemget\fP()  はセマフォ集合の情報を保持するデータ構造体 \fIsemid_ds\fP を次のように初期化する
(\fIsemid_ds\fP については \fBsemctl\fP(2)  を参照):
.IP \(bu 2
\fIsem_perm.cuid\fP と \fIsem_perm.uid\fP に、呼び出し元のプロセスの実効 (effective) ユーザー ID
を設定する。
.IP \(bu
\fIsem_perm.cgid\fP と \fIsem_perm.gid\fP に、呼び出し元のプロセスの実効 (effective) グループ ID
を設定する。
.IP \(bu
\fIsem_perm.mode\fP の下位 9 ビットに \fIsemflg\fP の下位 9 ビットを設定する。
.IP \(bu
\fIsem_nsems\fP に \fInsems\fP の値を設定する。
.IP \(bu
\fIsem_otime\fP に 0 を設定する。
.IP \(bu
\fIsem_ctime\fP に現在の時刻を設定する。
.PP
セマフォ集合の作成を行わない場合は、引数 \fInsems\fP に (don't care を意味する) 0 を指定してもよい。 そうでない場合は、
\fInsems\fP は 0 より大きい値でなければならず、セマフォ集合あたりのセマフォの最大数 (\fBSEMMSL\fP)  以下でなければならない。
.PP
.\" and a check is made to see if it is marked for destruction.
セマフォ集合が既に存在した場合は、アクセス許可の検査が行われる。
.SH 返り値
成功した場合、セマフォ集合の識別子 (非負の整数) が返り値となる。 失敗した場合は \-1 が返され、 \fIerrno\fP にエラーを示す値が設定される。
.SH エラー
失敗した場合は \fIerrno\fP には以下の値のどれかが設定される:
.TP 
\fBEACCES\fP
A semaphore set exists for \fIkey\fP, but the calling process does not have
permission to access the set, and does not have the \fBCAP_IPC_OWNER\fP
capability in the user namespace that governs its IPC namespace.
.TP 
\fBEEXIST\fP
.\" .TP
.\" .B EIDRM
.\" The semaphore set is marked to be deleted.
\fIsemflg\fP に \fBIPC_CREAT\fP と \fBIPC_EXCL\fP が指定されたが、 \fIkey\fP に対応するセマフォ集合はすでに存在する。
.TP 
\fBEINVAL\fP
\fInsems\fP が 0 より小さいか、 セマフォ集合あたりのセマフォの最大数 (\fBSEMMSL\fP) より大きい。
.TP 
\fBEINVAL\fP
\fIkey\fP に対応するセマフォ集合が既に存在するが、 \fInsems\fP がその集合のセマフォ数よりも大きい。
.TP 
\fBENOENT\fP
\fIkey\fP に対応するセマフォ集合が存在せず、 \fIsemflg\fP に \fBIPC_CREAT\fP が指定されてもいない。
.TP 
\fBENOMEM\fP
セマフォ集合を作成しようとしたが、新しいデータ構造体を 作成するのに十分なメモリーがシステムに存在しない。
.TP 
\fBENOSPC\fP
セマフォ集合を作成しようとすると、システムのセマフォ集合の 最大数 (\fBSEMMNI\fP)  か、システム全体のセマフォの最大数 (\fBSEMMNS\fP)
のいずれかを超えてしまう。
.SH 準拠
.\" SVr4 documents additional error conditions EFBIG, E2BIG, EAGAIN,
.\" ERANGE, EFAULT.
SVr4, POSIX.1\-2001.
.SH 注意
.\" Like Linux, the FreeBSD man pages still document
.\" the inclusion of these header files.
Linux や POSIX の全てのバージョンでは、 \fI<sys/types.h>\fP と \fI<sys/ipc.h>\fP
のインクルードは必要ない。しかしながら、いくつかの古い実装ではこれらのヘッダーファイルのインクルードが必要であり、 SVID
でもこれらのインクルードをするように記載されている。このような古いシステムへの移植性を意図したアプリケーションではこれらのファイルをインクルードする必要があるかもしれない。
.PP
.\"
\fBIPC_PRIVATE\fP はフラグフィールドに指定するものではなく、 \fIkey_t\fP 型である。 この特別な値が \fIkey\fP に指定されると、
\fBsemget\fP()  \fIsemflg\fP の下位 9 ビット以外は全て無視し、 (成功した場合は) 新しいセマフォ集合を作成する。
.SS セマフォの初期化
.\" In truth, every one of the many implementations that I've tested sets
.\" the values to zero, but I suppose there is/was some obscure
.\" implementation out there that does not.
新しく作成されたセマフォ集合の各セマフォの値は不定である。 (この点は POSIX.1\-2001 と POSIX.1\-2008
に明記されている。ただし、POSIX.1\-2008 では POSIX の将来のバージョンではセマフォを 0
に初期化するように実装に要求する可能性が注記されている。) Linux は他の多くの実装と同様にセマフォ値を 0 に初期化するが、
移植性を考慮したアプリケーションではこの動作を前提にすべきではない。 アプリケーションは明示的にセマフォを希望の値で初期化すべきである。
.PP
.\"
\fBsemctl\fP(2) の \fBSETVAL\fP か \fBSETALL\fP 操作を使って初期化することができる。
複数箇所からセマフォ集合の操作が行われる場面では、 誰が最初に集合を初期化すればよいか分からない。 この状況を避けるには、 \fBsemctl\fP(2)
の \fBIPC_STAT\fP 操作で取得できるセマフォのデータ構造体の \fIsem_otime\fP が 0 以外になっているかをチェックすればよい。
.SS セマフォの上限
セマフォ集合のリソースに関する上限のうち、 \fBsemget\fP()  に影響を及ぼすものを以下に挙げる:
.TP 
\fBSEMMNI\fP
.\" commit e843e7d2c88b7db107a86bd2c7145dc715c058f4
.\" This /proc file is not available in Linux 2.2 and earlier -- MTK
System\-wide limit on the number of semaphore sets.  On Linux systems before
version 3.19, the default value for this limit was 128.  Since Linux 3.19,
the default value is 32,000.  On Linux, this limit can be read and modified
via the fourth field of \fI/proc/sys/kernel/sem\fP.
.TP 
\fBSEMMSL\fP
.\" commit e843e7d2c88b7db107a86bd2c7145dc715c058f4
Maximum number of semaphores per semaphore ID.  On Linux systems before
version 3.19, the default value for this limit was 250.  Since Linux 3.19,
the default value is 32,000.  On Linux, this limit can be read and modified
via the first field of \fI/proc/sys/kernel/sem\fP.
.TP 
\fBSEMMNS\fP
システム全体のセマフォ数の上限値: 方針依存 (Linux では、この上限値は \fI/proc/sys/kernel/sem\fP の第 2
フィールドであり、読み出しも変更もできる)。 システム全体のセマフォ数には、 \fBSEMMSL\fP と \fBSEMMNI\fP の積という上限もある。
.SH バグ
\fBIPC_PRIVATE\fP という名前を選んだのはおそらく失敗であろう。 \fBIPC_NEW\fP の方がより明確にその機能を表しているだろう。
.SH 例
The program shown below uses \fBsemget\fP()  to create a new semaphore set or
retrieve the ID of an existing set.  It generates the \fIkey\fP for \fBsemget\fP()
using \fBftok\fP(3).  The first two command\-line arguments are used as the
\fIpathname\fP and \fIproj_id\fP arguments for \fBftok\fP(3).  The third command\-line
argument is an integer that specifies the \fInsems\fP argument for
\fBsemget\fP().  Command\-line options can be used to specify the \fBIPC_CREAT\fP
(\fI\-c\fP)  and \fBIPC_EXCL\fP (\fI\-x\fP)  flags for the call to \fBsemget\fP().  The
usage of this program is demonstrated below.
.PP
We first create two files that will be used to generate keys using
\fBftok\fP(3), create two semaphore sets using those files, and then list the
sets using \fBipcs\fP(1):
.PP
.in +4n
.EX
$ \fBtouch mykey mykey2\fP
$ \fB./t_semget \-c mykey p 1\fP
ID = 9
$ \fB./t_semget \-c mykey2 p 2\fP
ID = 10
$ \fBipcs \-s\fP

\-\-\-\-\-\- Semaphore Arrays \-\-\-\-\-\-\-\-
key        semid      owner      perms      nsems
0x7004136d 9          mtk        600        1
0x70041368 10         mtk        600        2
.EE
.in
.PP
Next, we demonstrate that when \fBsemctl\fP(2)  is given the same \fIkey\fP (as
generated by the same arguments to \fBftok\fP(3)), it returns the ID of the
already existing semaphore set:
.PP
.in +4n
.EX
$ \fB./t_semget \-c mykey p 1\fP
ID = 9
.EE
.in
.PP
Finally, we demonstrate the kind of collision that can occur when \fBftok\fP(3)
is given different \fIpathname\fP arguments that have the same inode number:
.PP
.in +4n
.EX
$ \fBln mykey link\fP
$ \fBls \-i1 link mykey\fP
2233197 link
2233197 mykey
$ \fB./t_semget link p 1\fP       # Generates same key as \(aqmykey\(aq
ID = 9
.EE
.in
.SS プログラムのソース
\&
.EX
/* t_semget.c

   Licensed under GNU General Public License v2 or later.
*/
#include <sys/types.h>
#include <sys/ipc.h>
#include <sys/sem.h>
#include <sys/stat.h>
#include <stdio.h>
#include <stdlib.h>
#include <unistd.h>

static void
usage(const char *pname)
{
    fprintf(stderr, "Usage: %s [\-cx] pathname proj\-id num\-sems\en",
            pname);
    fprintf(stderr, "    \-c           Use IPC_CREAT flag\en");
    fprintf(stderr, "    \-x           Use IPC_EXCL flag\en");
    exit(EXIT_FAILURE);
}

int
main(int argc, char *argv[])
{
    int semid, nsems, flags, opt;
    key_t key;

    flags = 0;
    while ((opt = getopt(argc, argv, "cx")) != \-1) {
        switch (opt) {
        case \(aqc\(aq: flags |= IPC_CREAT;   break;
        case \(aqx\(aq: flags |= IPC_EXCL;    break;
        default:  usage(argv[0]);
        }
    }

    if (argc != optind + 3)
        usage(argv[0]);

    key = ftok(argv[optind], argv[optind + 1][0]);
    if (key == \-1) {
        perror("ftok");
        exit(EXIT_FAILURE);
    }

    nsems = atoi(argv[optind + 2]);

    semid = semget(key, nsems, flags | 0600);
    if (semid == \-1) {
        perror("semget");
        exit(EXIT_FAILURE);
    }

    printf("ID = %d\en", semid);

    exit(EXIT_SUCCESS);
}
.EE
.SH 関連項目
\fBsemctl\fP(2), \fBsemop\fP(2), \fBftok\fP(3), \fBcapabilities\fP(7),
\fBsem_overview\fP(7), \fBsysvipc\fP(7)
.SH この文書について
この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 5.10 の一部である。プロジェクトの説明とバグ報告に関する情報は
\%https://www.kernel.org/doc/man\-pages/ に書かれている。