release/man3/mq_getattr.3

   1 .\" t
   2 .\" Copyright (C) 2006 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 .\"*******************************************************************
  27 .\"
  28 .\" This file was generated with po4a. Translate the source file.
  29 .\"
  30 .\"*******************************************************************
  31 .\"
  32 .\" Japanese Version Copyright (c) 2006 Akihiro MOTOKI all rights reserved.
  33 .\" Translated 2006-04-23, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>
  34 .\" Updated 2008-11-09, Akihiro MOTOKI, LDP v3.13
  35 .\"
  36 .TH MQ_GETATTR 3 2014\-10\-02 Linux "Linux Programmer's Manual"
  37 .SH 名前
  38 mq_getattr, mq_setattr \- メッセージキューの属性を設定/取得する
  39 .SH 書式
  40 .nf
  41 \fB#include <mqueue.h>\fP
  42 .sp
  43 \fBint mq_getattr(mqd_t \fP\fImqdes\fP\fB, struct mq_attr *\fP\fIattr\fP\fB);\fP
  44
  45 \fBint mq_setattr(mqd_t \fP\fImqdes\fP\fB, const struct mq_attr *\fP\fInewattr\fP\fB,\fP
  46 \fB                 struct mq_attr *\fP\fIoldattr\fP\fB);\fP
  47 .fi
  48 .sp
  49 \fI\-lrt\fP でリンクする。
  50 .SH 説明
  51 \fBmq_getattr\fP()  と \fBmq_setattr\fP()  は、記述子 \fImqdes\fP
  52 で参照されるメッセージキューの属性の取得と変更をそれぞれ行う。
  53
  54 \fBmq_getattr\fP()  は、 \fIattr\fP が指すバッファーに \fImq_attr\fP
  55 構造体を格納して返す。この構造体は以下のように定義されている:
  56 .in +4n
  57 .nf
  58
  59 struct mq_attr {
  60     long mq_flags;       /* フラグ: 0 か O_NONBLOCK */
  61     long mq_maxmsg;      /* キューの最大メッセージ数 */
  62     long mq_msgsize;     /* 最大メッセージサイズ (バイト単位) */
  63     long mq_curmsgs;     /* キューに現在入っているメッセージ数 */
  64 };
  65 .fi
  66 .in
  67 .PP
  68 \fImq_flags\fP フィールドには、オープンメッセージキュー記述 (open message queue description)
  69 に関連付けられているフラグが格納される。 このフィールドは \fBmq_open\fP(3)  でキューが作成される際に初期化される。
  70 このフィールドに現れるフラグは \fBO_NONBLOCK\fP だけである。
  71
  72 \fImq_maxmsg\fP と \fImq_msgsize\fP フィールドは \fBmq_open\fP(3)  でメッセージキューが作成される際にセットされる。
  73 \fImq_maxmsg\fP フィールドは、 \fBmq_send\fP(3)  を使ってキューに入れることができるメッセージ数の上限である。
  74 \fImq_msgsize\fP フィールドは、キューに入れることができるメッセージの 上限サイズである。 これらのフィールドはどちらも 0
  75 より大きな値でなければならない。 これらのフィールドに設定できる値の上限は \fI/proc\fP ファイルにより決まる。 \fI/proc\fP ファイルの詳細は
  76 \fBmq_overview\fP(7)  に説明されている。
  77
  78 \fImq_curmsgs\fP フィールドはキューに現在格納されているメッセージ数を返す。
  79
  80 \fBmq_setattr\fP()  は、 \fInewattr\fP が指す \fImq_attr\fP
  81 構造体で与えられた情報を使って、メッセージキューの属性を設定する。 変更することができる属性は、 \fImq_flags\fP の \fBO_NONBLOCK\fP
  82 フラグの設定だけである。 \fInewattr\fP の他のフィールドは無視される。 \fIoldattr\fP フィールドが NULL 以外の場合、
  83 \fBmq_getattr\fP()  が返すのと同じ情報を格納した \fImq_attr\fP 構造体を \fIoldattr\fP が指すバッファーに入れて返す。
  84 .SH 返り値
  85 成功すると、 \fImq_getattr ()\fP と \fImq_setattr ()\fP は 0 を返す。エラーの場合、\-1 を返し、 \fIerrno\fP
  86 にエラーを示す値を設定する。
  87 .SH エラー
  88 .TP
  89 \fBEBADF\fP
  90 \fImqdes\fP に指定されたディスクリプターが不正である。
  91 .TP
  92 \fBEINVAL\fP
  93 \fInewattr\->mq_flags\fP に \fBO_NONBLOCK\fP 以外のビットがセットされていた。
  94 .SH 属性
  95 .SS "マルチスレッディング (pthreads(7) 参照)"
  96 関数 \fBmq_getattr\fP() と \fBmq_setattr\fP() はスレッドセーフである。
  97 .SH 準拠
  98 POSIX.1\-2001.
  99 .SH 注意
 100 Linux では、 \fBmq_getattr\fP()  と \fBmq_setattr\fP()  はライブラリ関数であり、
 101 \fBmq_getsetattr\fP(2)  システムコールを用いて実装されている。
 102 .SH 例
 103 下記のプログラムを使うと、 \fIattr\fP 引き数に NULL を指定して \fBmq_open\fP(3)
 104 を呼び出した際に作成されるメッセージキューに割り当てられるデフォルトの \fImq_maxmsg\fP と \fImq_msgsize\fP の値を表示できる。
 105 このプログラムの実行例を以下に示す。
 106
 107 .in +4n
 108 .nf
 109 $ \fB./a.out /testq\fP
 110 Maximum # of messages on queue:   10
 111 Maximum message size:             8192
 112 .fi
 113 .in
 114
 115 Linux 3.5 以降では、 (\fBmq_overview\fP(7) に説明がある) 以下の \fI/proc\fP
 116 ファイルを使ってデフォルト値を制御できる。
 117
 118 .in +4n
 119 .nf
 120 $ \fBuname \-sr\fP
 121 Linux 3.8.0
 122 $ \fBcat /proc/sys/fs/mqueue/msg_default\fP
 123 10
 124 $ \fBcat /proc/sys/fs/mqueue/msgsize_default\fP
 125 8192
 126 .fi
 127 .in
 128 .SS プログラムのソース
 129 \&
 130 .nf
 131 #include <mqueue.h>
 132 #include <sys/stat.h>
 133 #include <fcntl.h>
 134 #include <stdio.h>
 135 #include <stdlib.h>
 136 #include <unistd.h>
 137
 138 #define errExit(msg)    do { perror(msg); exit(EXIT_FAILURE); \e
 139                         } while (0)
 140
 141 int
 142 main(int argc, char *argv[])
 143 {
 144     mqd_t mqd;
 145     struct mq_attr attr;
 146
 147     if (argc != 2) {
 148         fprintf(stderr, "Usage: %s mq\-name\en", argv[0]);
 149         exit(EXIT_FAILURE);
 150     }
 151
 152     mqd = mq_open(argv[1], O_CREAT | O_EXCL, S_IRUSR | S_IWUSR, NULL);
 153     if (mqd == (mqd_t) \-1)
 154         errExit("mq_open");
 155
 156     if (mq_getattr(mqd, &attr) == \-1)
 157         errExit("mq_getattr");
 158
 159     printf("Maximum # of messages on queue:   %ld\en", attr.mq_maxmsg);
 160     printf("Maximum message size:             %ld\en", attr.mq_msgsize);
 161
 162     if (mq_unlink(argv[1]) == \-1)
 163         errExit("mq_unlink");
 164
 165     exit(EXIT_SUCCESS);
 166 }
 167 .fi
 168 .SH 関連項目
 169 \fBmq_close\fP(3), \fBmq_notify\fP(3), \fBmq_open\fP(3), \fBmq_receive\fP(3),
 170 \fBmq_send\fP(3), \fBmq_unlink\fP(3), \fBmq_overview\fP(7)
 171 .SH この文書について
 172 この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.79 の一部
 173 である。プロジェクトの説明とバグ報告に関する情報は
 174 http://www.kernel.org/doc/man\-pages/ に書かれている。