manual/LDP_man-pages/draft/man2/shmop.2

   1 .\" Copyright 1993 Giorgio Ciucci (giorgio@crcc.it)
   2 .\" and Copyright 2020 Michael Kerrisk <mtk.manpages@gmail.com>
   3 .\"
   4 .\" %%%LICENSE_START(VERBATIM)
   5 .\" Permission is granted to make and distribute verbatim copies of this
   6 .\" manual provided the copyright notice and this permission notice are
   7 .\" preserved on all copies.
   8 .\"
   9 .\" Permission is granted to copy and distribute modified versions of this
  10 .\" manual under the conditions for verbatim copying, provided that the
  11 .\" entire resulting derived work is distributed under the terms of a
  12 .\" permission notice identical to this one.
  13 .\"
  14 .\" Since the Linux kernel and libraries are constantly changing, this
  15 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  16 .\" responsibility for errors or omissions, or for damages resulting from
  17 .\" the use of the information contained herein.  The author(s) may not
  18 .\" have taken the same level of care in the production of this manual,
  19 .\" which is licensed free of charge, as they might when working
  20 .\" professionally.
  21 .\"
  22 .\" Formatted or processed versions of this manual, if unaccompanied by
  23 .\" the source, must acknowledge the copyright and authors of this work.
  24 .\" %%%LICENSE_END
  25 .\"
  26 .\" Modified Sun Nov 28 17:06:19 1993, Rik Faith (faith@cs.unc.edu)
  27 .\"          with material from Luigi P. Bai (lpb@softint.com)
  28 .\" Portions Copyright 1993 Luigi P. Bai
  29 .\" Modified Tue Oct 22 22:04:23 1996 by Eric S. Raymond <esr@thyrsus.com>
  30 .\" Modified, 5 Jan 2002, Michael Kerrisk <mtk.manpages@gmail.com>
  31 .\" Modified, 19 Sep 2002, Michael Kerrisk <mtk.manpages@gmail.com>
  32 .\"     Added SHM_REMAP flag description
  33 .\" Modified, 27 May 2004, Michael Kerrisk <mtk.manpages@gmail.com>
  34 .\"     Added notes on capability requirements
  35 .\" Modified, 11 Nov 2004, Michael Kerrisk <mtk.manpages@gmail.com>
  36 .\"     Language and formatting clean-ups
  37 .\"     Changed wording and placement of sentence regarding attachment
  38 .\"             of segments marked for destruction
  39 .\"
  40 .\"*******************************************************************
  41 .\"
  42 .\" This file was generated with po4a. Translate the source file.
  43 .\"
  44 .\"*******************************************************************
  45 .\"
  46 .\" Japanese Version Copyright (c) 1997 HANATAKA Shinya
  47 .\"         all rights reserved.
  48 .\" Translated 1999-08-15, HANATAKA Shinya <hanataka@abyss.rim.or.jp>
  49 .\" Updated & Modified 2002-05-07, Yuichi SATO <ysato@h4.dion.ne.jp>
  50 .\" Updated & Modified 2003-01-18, Yuichi SATO <ysato444@yahoo.co.jp>
  51 .\" Updated & Modified 2005-01-07, Yuichi SATO
  52 .\" Updated 2005-12-05, Akihiro MOTOKI, Catch up to LDP man-pages 2.16
  53 .\" Updated 2006-04-14, Akihiro MOTOKI, Catch up to LDP man-pages 2.29
  54 .\" Updated 2013-03-26, Akihiro MOTOKI <amotoki@gmail.com>
  55 .\" Updated 2013-05-01, Akihiro MOTOKI <amotoki@gmail.com>
  56 .\" Updated 2013-07-24, Akihiro MOTOKI <amotoki@gmail.com>
  57 .\"
  58 .TH SHMOP 2 2020\-04\-11 Linux "Linux Programmer's Manual"
  59 .SH 名前
  60 shmat, shmdt \- System V 共有メモリー (shared memory) の操作
  61 .SH 書式
  62 .nf
  63 \fB#include <sys/types.h>\fP
  64 \fB#include <sys/shm.h>\fP
  65 .PP
  66 \fBvoid *shmat(int \fP\fIshmid\fP\fB, const void *\fP\fIshmaddr\fP\fB, int \fP\fIshmflg\fP\fB);\fP
  67 .PP
  68 \fBint shmdt(const void *\fP\fIshmaddr\fP\fB);\fP
  69 .fi
  70 .SH 説明
  71 .SS shmat()
  72 \fBshmat\fP()  は \fIshmid\fP で指定された System\ V 共有メモリーセグメント (shared memory segment)
  73 を コールしたプロセスのアドレス空間に付加 (attach) する。 付加するアドレスは \fIshmaddr\fP に以下のどれかの形式で指定する:
  74 .IP \(bu 2
  75 \fIshmaddr\fP が NULL ならば、システムはセグメントを付加するための 適切な (使用されていない) ページ境界のアドレスを選択する。
  76 .IP \(bu
  77 \fIshmaddr\fP が NULL でなく \fBSHM_RND\fP が \fIshmflg\fP に指定されている場合は、 \fIshmaddr\fP を
  78 \fBSHMLBA\fP の倍数へと切り捨てた (rounding down) のと等しいアドレスへ付加する。
  79 .IP \(bu
  80 その他の場合は \fIshmaddr\fP は付加を行なうアドレスで、ページ境界を指している必要がある。
  81 .PP
  82 \fBSHM_RND\fP に加えて、以下のフラグを \fIshmflg\fP ビットマスク引き数に指定できる。
  83 .TP
  84 \fBSHM_EXEC\fP (Linux 固有; Linux 2.6.9 以降)
  85 セグメントの内容を実行できる。 呼び出し元はセグメントに対する実行許可を持っていなければならない。
  86 .TP
  87 \fBSHM_RDONLY\fP
  88 セグメントを読み込み専用に付加する。 プロセスはそのセグメントへの読み込み許可を持っていなければならない。
  89 このフラグが指定されなかった場合、そのセグメントは読み込みと書き込みアクセスのために付加され、
  90 プロセスはそのセグメントに読み込みと書き込みの許可を持っていなければならない。 書き込み専用の共有メモリーセグメントという概念は存在しない。
  91 .TP
  92 \fBSHM_REMAP\fP (Linux 固有)
  93 このフラグは、 セグメントのマッピングを既存のマッピングに置き換えることを指示する。 マッピングの範囲は、 \fIshmaddr\fP
  94 から始まりセグメントのサイズ分だけある (通常 \fBEINVAL\fP エラーは、このアドレス範囲にマッピングが既に存在するために起る)。
  95 このフラグを指定する場合は、 \fIshmaddr\fP が NULL であってはならない。
  96 .PP
  97 呼び出したプロセスの \fBbrk\fP(2)  の値は付加によって変化しない。 そのセグメントはプロセスが終了 (exit) したら自動的に分離
  98 (detach) される。 同じセグメントをプロセスのアドレス空間に、読み込み専用および読み書き両用 として付加でき、また複数回付加することもできる。
  99 .PP
 100 成功した \fBshmat\fP()  コールは共有メモリーセグメントに関連する \fIshmid_ds\fP 構造体 (\fBshmctl\fP(2)  を参照)
 101 のメンバーを以下のように更新する:
 102 .IP \(bu 2
 103 \fIshm_atime\fP には現在の時刻を設定する。
 104 .IP \(bu
 105 \fIshm_lpid\fP には呼び出したプロセスのプロセス ID が設定される。
 106 .IP \(bu
 107 .\"
 108 \fIshm_nattch\fP を 1 増加させる。
 109 .SS shmdt()
 110 \fBshmdt\fP()  は呼び出したプロセスのアドレス空間から \fIshmaddr\fP で指定されたアドレスに配置された共有メモリーセグメントを分離
 111 (detach) する。 分離する共有メモリーセグメントは、現在 \fIshmaddr\fP に付加されているものでなければならない。 \fIshmaddr\fP
 112 は、それを付加した時に \fBshmat\fP()  が返した値に等しくなければならない。
 113 .PP
 114 成功した \fBshmdt\fP()  コールはその共有メモリーセグメントに関連する \fIshmid_ds\fP 構造体のメンバーを以下のように更新する:
 115 .IP \(bu 2
 116 \fIshm_dtime\fP には現在の時刻が設定される。
 117 .IP \(bu
 118 \fIshm_lpid\fP には呼び出したプロセスのプロセス ID が設定される。
 119 .IP \(bu
 120 \fIshm_nattch\fP を 1 減少させる。 もし 0 になり、削除マークがあった場合は そのセグメントは削除される。
 121 .SH 返り値
 122 \fBshmat\fP()  は、成功した場合、 付加された共有メモリーセグメントのアドレスを返す。 エラーの場合、 \fI(void\ *)\ \-1\fP
 123 を返し、 \fIerrno\fP にエラーの原因を示す値を設定する。
 124 .PP
 125 \fBshmdt\fP()  は、成功すると 0 を返す。 エラーの場合、\-1 を返し、 \fIerrno\fP にエラーの原因を示す値を設定する。
 126 .SH エラー
 127 \fBshmat\fP()  が失敗した場合、 \fIerrno\fP に以下の値のどれかを設定して返す:
 128 .TP
 129 \fBEACCES\fP
 130 The calling process does not have the required permissions for the requested
 131 attach type, and does not have the \fBCAP_IPC_OWNER\fP capability in the user
 132 namespace that governs its IPC namespace.
 133 .TP
 134 \fBEIDRM\fP
 135 \fIshmid\fP が削除 (remove) された識別子 (identifier) を指している。
 136 .TP
 137 \fBEINVAL\fP
 138 \fIshmid\fP の値が不正である。 \fIshmaddr\fP の値が境界違反 (unaligned) (つまり、ページ境界に合っておらず、
 139 \fBSHM_RND\fP が指定されていない) または が不正である。 \fIshmaddr\fP へのセグメントの付加に失敗した。 または
 140 \fBSHM_REMAP\fP が指定されているが、 \fIshmaddr\fP が NULL であった。
 141 .TP
 142 \fBENOMEM\fP
 143 ディスクリプター (descriptor) やページテーブルのためのメモリーを 割り当てることができない。
 144 .PP
 145 \fBshmdt\fP()  が失敗した場合、 \fBEINVAL\fP は以下のようにセットされる:
 146 .TP
 147 \fBEINVAL\fP
 148 .\" The following since 2.6.17-rc1:
 149 \fIshmaddr\fP に付加された共有メモリーセグメントが存在しない。 もしくは、 \fIshmaddr\fP がページ境界に合っていない。
 150 .SH 準拠
 151 .\" SVr4 documents an additional error condition EMFILE.
 152 POSIX.1\-2001, POSIX.1\-2008, SVr4.
 153 .PP
 154 SVID 3 で (たぶんそれより前だと思うが)  \fIshmaddr\fP 引き数の型は \fIchar\ *\fP から \fIconst void\ *\fP
 155 に、\fIshmat\fP() の返り値の型は \fIchar\ *\fP から \fIvoid\ *\fP に変更された。
 156 .SH 注意
 157 \fBfork\fP(2)  した後、子プロセスは付加された共有メモリーセグメントを継承する。
 158 .PP
 159 \fBexec\fP(2)  した後、全ての付加された共有メモリーセグメントはプロセスから分離される。
 160 .PP
 161 \fBexit\fP(2)  において、全ての付加された共有メモリーセグメントはプロセスから分離される。
 162 .PP
 163 共有メモリーセグメントを付加する場合の移植性の高い方法としては、 \fIshmaddr\fP を NULL にして \fBshmat\fP()
 164 を使用するのがよい。 このような方法で付加される共有メモリーセグメントは、 プロセスが異なれば別のアドレスに付加される、という点に注意すること。
 165 よって共有メモリー内で管理されるポインターは、 絶対アドレスではなく、 (一般的にはセグメントの開始アドレスからの)
 166 相対アドレスで作成するべきである。
 167 .PP
 168 Linux では共有メモリーセグメントに既に削除マークが付けられていても、 その共有メモリーセグメントを付加することができる。 しかし POSIX.1
 169 ではこのような動作を指定しておらず、 他の多くの実装もこれをサポートしていない。
 170 .PP
 171 以下のシステムパラメーターは、 \fBshmat\fP()  に影響する:
 172 .TP
 173 \fBSHMLBA\fP
 174 セグメントの下限アドレス倍数 (Segment low boundary address multiple)。 \fBshmat\fP()
 175 の呼び出しにおいて付加するアドレスを明示的に指定する際、 呼び出し元は指定するアドレスがこの値の倍数になるように保証しなければならない。
 176 これはいくつかのアーキテクチャーでは必要なことで、 CPU キャッシュの性能を保証するためであったり、 同じセグメントの別の付与を CPU
 177 キャッシュ内部で一貫して扱えるようにするためだったりする。 \fBSHMLBA\fP は通常はシステムページサイズの倍数である (Linux
 178 の多くのアーキテクチャーでは \fBSHMLBA\fP はシステムページサイズと同じである)。
 179 .PP
 180 現在の実装では、プロセスごとの 共有メモリーセグメントの最大数 (\fBSHMSEG\fP)  に関する実装依存の制限はない。
 181 .SH 例
 182 The two programs shown below exchange a string using a shared memory
 183 segment.  Further details about the programs are given below.  First, we
 184 show a shell session demonstrating their use.
 185 .PP
 186 In one terminal window, we run the "reader" program, which creates a System
 187 V shared memory segment and a System V semaphore set.  The program prints
 188 out the IDs of the created objects, and then waits for the semaphore to
 189 change value.
 190 .PP
 191 .in +4n
 192 .EX
 193 $ \fB./svshm_string_read\fP
 194 shmid = 1114194; semid = 15
 195 .EE
 196 .in
 197 .PP
 198 In another terminal window, we run the "writer" program.  The "writer"
 199 program takes three command\-line arguments: the IDs of the shared memory
 200 segment and semaphore set created by the "reader", and a string.  It
 201 attaches the existing shared memory segment, copies the string to the shared
 202 memory, and modifies the semaphore value.
 203 .PP
 204 .in +4n
 205 .EX
 206 $ \fB./svshm_string_write 1114194 15 \(aqHello, world\(aq\fP
 207 .EE
 208 .in
 209 .PP
 210 Returning to the terminal where the "reader" is running, we see that the
 211 program has ceased waiting on the semaphore and has printed the string that
 212 was copied into the shared memory segment by the writer:
 213 .PP
 214 .in +4n
 215 .EX
 216 Hello, world
 217 .EE
 218 .in
 219 .\"
 220 .SS "プログラムのソース: svshm_string.h"
 221 The following header file is included by the "reader" and "writer" programs.
 222 .PP
 223 .in +4n
 224 .EX
 225 #include <sys/types.h>
 226 #include <sys/ipc.h>
 227 #include <sys/shm.h>
 228 #include <sys/sem.h>
 229 #include <stdio.h>
 230 #include <stdlib.h>
 231 #include <string.h>
 232
 233 #define errExit(msg)    do { perror(msg); exit(EXIT_FAILURE); \e
 234                         } while (0)
 235
 236 union semun {                   /* Used in calls to semctl() */
 237     int                 val;
 238     struct semid_ds *   buf;
 239     unsigned short *    array;
 240 #if defined(__linux__)
 241     struct seminfo *    __buf;
 242 #endif
 243 };
 244
 245 #define MEM_SIZE 4096
 246 .EE
 247 .in
 248 .\"
 249 .SS "プログラムのソース: svshm_string_read.c"
 250 The "reader" program creates a shared memory segment and a semaphore set
 251 containing one semaphore.  It then attaches the shared memory object into
 252 its address space and initializes the semaphore value to 1.  Finally, the
 253 program waits for the semaphore value to become 0, and afterwards prints the
 254 string that has been copied into the shared memory segment by the "writer".
 255 .PP
 256 .in +4n
 257 .EX
 258 /* svshm_string_read.c
 259
 260    Licensed under GNU General Public License v2 or later.
 261 */
 262 #include "svshm_string.h"
 263
 264 int
 265 main(int argc, char *argv[])
 266 {
 267     int semid, shmid;
 268     union semun arg, dummy;
 269     struct sembuf sop;
 270     char *addr;
 271
 272     /* Create shared memory and semaphore set containing one
 273        semaphore */
 274
 275     shmid = shmget(IPC_PRIVATE, MEM_SIZE, IPC_CREAT | 0600);
 276     if (shmid == \-1)
 277         errExit("shmget");
 278
 279     semid = semget(IPC_PRIVATE, 1, IPC_CREAT | 0600);
 280     if (shmid == \-1)
 281         errExit("shmget");
 282
 283     /* Attach shared memory into our address space */
 284
 285     addr = shmat(shmid, NULL, SHM_RDONLY);
 286     if (addr == (void *) \-1)
 287         errExit("shmat");
 288
 289     /* Initialize semaphore 0 in set with value 1 */
 290
 291     arg.val = 1;
 292     if (semctl(semid, 0, SETVAL, arg) == \-1)
 293         errExit("semctl");
 294
 295     printf("shmid = %d; semid = %d\en", shmid, semid);
 296
 297     /* Wait for semaphore value to become 0 */
 298
 299     sop.sem_num = 0;
 300     sop.sem_op = 0;
 301     sop.sem_flg = 0;
 302
 303     if (semop(semid, &sop, 1) == \-1)
 304         errExit("semop");
 305
 306     /* Print the string from shared memory */
 307
 308     printf("%s\en", addr);
 309
 310     /* Remove shared memory and semaphore set */
 311
 312     if (shmctl(shmid, IPC_RMID, NULL) == \-1)
 313         errExit("shmctl");
 314     if (semctl(semid, 0, IPC_RMID, dummy) == \-1)
 315         errExit("semctl");
 316
 317     exit(EXIT_SUCCESS);
 318 }
 319 .EE
 320 .in
 321 .\"
 322 .SS "プログラムのソース: svshm_string_write.c"
 323 The writer program takes three command\-line arguments: the IDs of the shared
 324 memory segment and semaphore set that have already been created by the
 325 "reader", and a string.  It attaches the shared memory segment into its
 326 address space, and then decrements the semaphore value to 0 in order to
 327 inform the "reader" that it can now examine the contents of the shared
 328 memory.
 329 .PP
 330 .in +4n
 331 .EX
 332 /* svshm_string_write.c
 333
 334    Licensed under GNU General Public License v2 or later.
 335 */
 336 #include "svshm_string.h"
 337
 338 int
 339 main(int argc, char *argv[])
 340 {
 341     int semid, shmid;
 342     struct sembuf sop;
 343     char *addr;
 344     size_t len;
 345
 346     if (argc != 4) {
 347         fprintf(stderr, "Usage: %s shmid semid string\en", argv[0]);
 348         exit(EXIT_FAILURE);
 349     }
 350
 351     len = strlen(argv[3]) + 1;  /* +1 to include trailing \(aq\e0\(aq */
 352     if (len > MEM_SIZE) {
 353         fprintf(stderr, "String is too big!\en");
 354         exit(EXIT_FAILURE);
 355     }
 356
 357     /* Get object IDs from command\-line */
 358
 359     shmid = atoi(argv[1]);
 360     semid = atoi(argv[2]);
 361
 362     /* Attach shared memory into our address space and copy string
 363        (including trailing null byte) into memory. */
 364
 365     addr = shmat(shmid, NULL, 0);
 366     if (addr == (void *) \-1)
 367         errExit("shmat");
 368
 369     memcpy(addr, argv[3], len);
 370
 371     /* Decrement semaphore to 0 */
 372
 373     sop.sem_num = 0;
 374     sop.sem_op = \-1;
 375     sop.sem_flg = 0;
 376
 377     if (semop(semid, &sop, 1) == \-1)
 378         errExit("semop");
 379
 380     exit(EXIT_SUCCESS);
 381 }
 382 .EE
 383 .in
 384 .SH 関連項目
 385 \fBbrk\fP(2), \fBmmap\fP(2), \fBshmctl\fP(2), \fBshmget\fP(2), \fBcapabilities\fP(7),
 386 \fBshm_overview\fP(7), \fBsysvipc\fP(7)
 387 .SH この文書について
 388 この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 5.10 の一部である。プロジェクトの説明とバグ報告に関する情報は
 389 \%https://www.kernel.org/doc/man\-pages/ に書かれている。