OSDN Git Service

(split) LDP: Release pages for LDP v3.39.
[linuxjm/LDP_man-pages.git] / release / man7 / feature_test_macros.7
1 .\" Hey Emacs! This file is -*- nroff -*- source.
2 .\"
3 .\" This manpage is Copyright (C) 2006, Michael Kerrisk
4 .\"
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 .\"
25 .\"*******************************************************************
26 .\"
27 .\" This file was generated with po4a. Translate the source file.
28 .\"
29 .\"*******************************************************************
30 .TH FEATURE_TEST_MACROS 7 2012\-01\-18 Linux "Linux Programmer's Manual"
31 .SH 名前
32 feature_test_macros \- 機能検査マクロ
33 .SH 書式
34 .nf
35 \fB#include <features.h>\fP
36 .fi
37 .SH 説明
38 機能検査マクロ (feature test macro) により、プログラマは プログラムがコンパイルされる際にシステムのヘッダファイルにより
39 公開される定義を制御することができる。
40
41 \fB注意:\fP 機能検査マクロを機能させるには、機能検査マクロの定義を 「どのヘッダファイルのインクルードよりも前で」行わなければならない。
42 これを実現するには、 コンパイルコマンドで指定する方法 (\fIcc \-DMACRO=value\fP)  と、ソースコード内で必要なマクロの定義を
43 どのヘッダのインクルードよりも前で行う方法がある。
44
45 機能検査マクロを使うと、非標準の定義が公開されないようにでき、 移植性のあるアプリケーションを作成するのに役立つ。
46 他のマクロを使うと、デフォルトでは公開されない非標準の定義を 公開することができる。 以下で説明する機能検査マクロのそれぞれの正確な影響を確認するには、
47 ヘッダファイル \fI<features.h>\fP を調べればよい。
48 .SS マニュアルページでの機能検査マクロの要件の規定
49 関数が機能検査マクロの定義を必要とする場合、 マニュアルページの書式 (SYNOPSIS) の節に 以下の形式の注釈を入れる (以下の例は
50 \fBacct\fP(2)  のマニュアルページからの引用である)。
51 .RS 8
52 .sp
53 \fB#include <unistd.h>\fP
54 .sp
55 \fBint acct(const char *\fP\fIfilename\fP\fB);\fP
56 .sp
57 .nf
58 .in -4n
59 glibc 向けの機能検査マクロの要件
60 (\fBfeature_test_macros\fP(7)
61 参照):
62 .fi
63 .in
64 .sp
65 \fBacct\fP(): _BSD_SOURCE || (_XOPEN_SOURCE && _XOPEN_SOURCE\ <\ 500)
66 .RE
67 .PP
68 \fB||\fP は、 \fBacct\fP(2)  の定義を \fI<unistd.h>\fP
69 から得るには、以下のマクロの定義のいずれかを、どのヘッダファイルの インクルードよりも前で行わなければならないことを意味する。
70 .RS
71 .nf
72
73 #define _BSD_SOURCE
74 #define _XOPEN_SOURCE        /* or any value < 500 */
75 .fi
76 .RE
77 .PP
78 別の方法としては、等価な定義をコンパイル用のコマンドで 指定することもできる。
79 .RS
80 .nf
81
82 cc \-D_BSD_SOURCE
83 cc \-D_XOPEN_SOURCE           # Or any value < 500
84 .fi
85 .RE
86 .PP
87 後で述べるが、 \fB「いくつかの機能検査マクロはデフォルトで定義される」\fP 点に注意すること。 このため、「書式」に記載された機能検査マクロを常に
88 明示的に指定する必要があるわけではない。
89
90 あまり多くないが、マニュアルページによっては、 機能検査マクロの要件を以下のように簡単な表現で記載する場合がある。 (以下の例は
91 \fBreadahead\fP(2)  のマニュアルページからの引用である)。
92 .RS
93 .nf
94
95 \fB#define _GNU_SOURCE\fP
96 \fB#include <fcntl.h>\fP
97 .sp
98 \fBssize_t readahead(int \fP\fIfd\fP\fB, off64_t *\fP\fIoffset\fP\fB, size_t \fP\fIcount\fP\fB);\fP
99 .fi
100 .RE
101 .PP
102 関数定義の公開に使える機能検査マクロが一つだけで、 デフォルトではそのマクロが定義されない場合に、 この形式の表現を利用する。
103 .SS "glibc が解釈する機能検査マクロ"
104 .\" The details in glibc 2.0 are simpler, but combining a
105 .\" a description of them with the details in later glibc versions
106 .\" would make for a complicated description.
107 以下では、Linux glibc 2.\fIx\fP (\fIx\fP > 0) において、 機能検査マクロがどのように扱われるかを説明する。
108
109 Linux/glibc は以下の機能検査マクロを解釈する:
110 .TP 
111 \fB__STRICT_ANSI__\fP
112 ISO 標準の C。 \fBgcc\fP(1)  を \fI\-std=c99\fP や \fI\-ansi\fP などのフラグを付けて起動した場合、
113 このマクロは暗黙のうちに定義される。
114 .TP 
115 \fB_POSIX_C_SOURCE\fP
116 このマクロを定義すると、ヘッダファイルで以下の定義が公開される。
117 .RS
118 .IP \(bu 3
119 値が 1 の場合、POSIX.1\-1990 と ISO C (1990) に準拠する定義が公開される。
120 .IP \(bu
121 値が 2 以上の場合、 POSIX.2\-1992 関連の定義も追加で公開される。
122 .IP \(bu
123 .\" 199506L functionality is only available since glibc 2.1
124 値が 199309 以上の場合、 POSIX.1b (リアルタイム拡張) 関連の定義が追加で公開される。
125 .IP \(bu
126 値が 199506 以上の場合、 POSIX.1c (スレッド) 関連の定義が追加で公開される。
127 .IP \(bu
128 (glibc 2.3.3 以降)  値が 200112L 以上の場合、 (XSI 拡張を除く) POSIX.1\-2001
129 基本仕様に対応する定義が公開される。
130 .IP \(bu
131 (glibc 2.10 以降)  値が 200809L 以上の場合、 (XSI 拡張を除く) POSIX.1\-2008
132 基本仕様に対応する定義が公開される。
133 .RE
134 .TP 
135 \fB_POSIX_SOURCE\fP
136 このマクロは廃止予定である。 このマクロが定義されると、値に関わらず、 \fB_POSIX_C_SOURCE\fP を値 1 で定義するのと等価となる。
137 .TP 
138 \fB_XOPEN_SOURCE\fP
139 このマクロを定義すると、ヘッダファイルで以下の定義が公開される。
140 .RS
141 .IP \(bu 3
142 どんな値でも、ヘッダファイルで POSIX.1, POSIX.2, XPG4 に準拠する定義が公開される。
143 .IP \(bu
144 値が 500 以上の場合、 SUSv2 (UNIX 98) 関連の定義が追加で公開される。
145 .IP \(bu
146 (glibc 2.2 以降)  値が 600 以上の場合、 SUSv3 (UNIX 03; POSIX.1\-2001 基本仕様 + XSI 拡張と同じ)
147 関連の定義と C99 での定義が追加で公開される。
148 .IP \(bu
149 (glibc 2.10 以降)  値が 700 以上の場合、 SUSv4 (POSIX.1\-2008 基本仕様 + XSI 拡張と同じ)
150 関連の定義が追加で公開される。
151 .RE
152 .TP 
153 \fB_XOPEN_SOURCE_EXTENDED\fP
154 このマクロが定義され、さらに \fB_XOPEN_SOURCE\fP が定義されていると、XPG4v2 (SUSv1) UNIX 拡張 (UNIX 95)
155 に対応する定義が公開される。 \fB_XOPEN_SOURCE\fP が 500 以上の値で定義された場合、このマクロは暗黙のうちに定義される。
156 .TP 
157 \fB_ISOC95_SOURCE\fP
158 ISO C (1990) Amendment 1 の定義 (C95 としても知られる) が公開される。
159 C95 における主要な変更点は国際化文字集合のサポートであった。
160 C95 の変更点は、これに続く C99 標準にも含まれた
161 (言い換えると、\fB_ISOC99_SOURCE\fP を定義すると暗黙のうちに \fB_ISOC95_SOURCE\fP
162 を定義されることを意味する)。
163 .TP 
164 \fB_ISOC99_SOURCE\fP
165 ISO C (1990) の C99 拡張を公開する。 このマクロは glibc 2.1.3 以降で認識される。 初期のバージョン 2.1.x の
166 glibc では、これと等価な \fB_ISOC9X_SOURCE\fP という名前のマクロが使われていた (なぜなら、C99
167 標準はまだ確定していなかったからである)。 \fB_ISOC9X_SOURCE\fP マクロの使用は廃止されているが、 glibc
168 は過去との互換性のため今でもこのマクロを認識する。
169 .TP 
170 \fB_ISOC11_SOURCE\fP
171 ISO C11 標準に準拠した宣言を公開する。
172 このマクロは glibc 2.16 以降で認識される。
173 .TP 
174 \fB_LARGEFILE64_SOURCE\fP
175 LFS (Large File Summit) により "暫定拡張 (transitional extension)" Single UNIX
176 Specification として規定された代替 API (alternative API) に関する定義を公開する
177 (http://opengroup.org/platform/lfs.html 参照)。 代替 API は新規オブジェクト (関数と型)
178 の集合で構成され、 その名前は "64" で終わる (例えば、 \fIoff_t\fP に対応するのは \fIoff64_t\fP、 \fBlseek\fP()
179 に対応するのは \fBlseek64\fP()  である)。 新しいプログラムではこのインタフェースを利用しないこと。 代わりに
180 \fI_FILE_OFFSET_BITS=64\fP を利用すること。
181 .TP 
182 \fB_FILE_OFFSET_BITS\fP
183 このマクロを値 64 で定義すると、ファイル I/O とファイルシステム操作に 関連する 32 ビット版の関数とデータタイプは自動的に 64 ビット版に
184 変換される。 これは、32 ビットシステムで大きなファイル (> 2 ギガバイト) の I/O を実行する際に役立つ
185 (このマクロを定義すると、コンパイルし直すだけで大きなファイルを 扱えるプログラムを書くことができる)。 64 ビットシステムは、もともと 2
186 ギガバイトより大きなファイルを 扱えるので、64 ビットシステムではこのマクロは効果を持たない。
187 .TP 
188 \fB_BSD_SOURCE\fP
189 このマクロを定義すると (値に関わらず) ヘッダファイルで BSD 由来の定義が公開される。
190 また、このマクロを定義すると、相容れない標準が存在する状況において BSD 由来の定義を優先するようになる。 ただし、 \fB_SVID_SOURCE\fP,
191 \fB_POSIX_SOURCE\fP, \fB_POSIX_C_SOURCE\fP, \fB_XOPEN_SOURCE\fP,
192 \fB_XOPEN_SOURCE_EXTENDED\fP, \fB_GNU_SOURCE\fP が一つでも定義された場合には、BSD 由来の定義は優先されなくなる。
193 .TP 
194 \fB_SVID_SOURCE\fP
195 このマクロを定義すると (値に関わらず) ヘッダファイルで System V 由来の定義が公開される (SVID == System V
196 Interface Definition; \fBstandards\fP(7)  参照)。
197 .TP 
198 \fB_ATFILE_SOURCE\fP (glibc 2.4 以降)
199 このマクロを定義すると (値に関わらず) ヘッダファイルで 名前の末尾が "at" の各種の関数の定義が公開される。 \fBopenat\fP(2)  参照。
200 glibc 2.10 以降では、 \fB_POSIX_C_SOURCE\fP が 200809L 以上の値で定義された場合には、
201 このマクロも暗黙のうちに定義される。
202 .TP 
203 \fB_GNU_SOURCE\fP
204 このマクロを定義すると (値に関わらず) 以下のマクロを定義するのと 等価になる: \fB_BSD_SOURCE\fP, \fB_SVID_SOURCE\fP,
205 \fB_ATFILE_SOURCE\fP, \fB_LARGEFILE64_SOURCE\fP, \fB_ISOC99_SOURCE\fP,
206 \fB_XOPEN_SOURCE_EXTENDED\fP, \fB_POSIX_SOURCE\fP, 値 200809L の \fB_POSIX_C_SOURCE\fP
207 (バージョン 2.10 より前の glibc では値は 200112L、 バージョン 2.5 より前の glibc では値は 199506L、
208 バージョン 2.1 より前の glibc では値は 199309L), 値 700 の \fB_XOPEN_SOURCE\fP (バージョン 2.10
209 より前の glibc では値は 600、 バージョン 2.2 より前の glibc では値は 500)。 さらに、各種の GNU
210 固有の拡張も公開される。 指定された標準に矛盾があった場合は、 BSD 由来の定義が優先されなくなる。
211 .TP 
212 \fB_REENTRANT\fP
213 このマクロを定義すると、いくつかのリエントラント (再入可能) な関数 定義が公開される。マルチスレッド・プログラムでは、この代わりに \fIcc\ \-pthread\fP を使用すること。
214 .TP 
215 \fB_THREAD_SAFE\fP
216 \fB_REENTRANT\fP の同義語。 他のいくつかの実装との互換性を提供するためのもの。
217 .TP 
218 \fB_FORTIFY_SOURCE\fP (glibc 2.3.4 以降)
219 .\" For more detail, see:
220 .\" http://gcc.gnu.org/ml/gcc-patches/2004-09/msg02055.html
221 .\" [PATCH] Object size checking to prevent (some) buffer overflows
222 .\" * From: Jakub Jelinek <jakub at redhat dot com>
223 .\" * To: gcc-patches at gcc dot gnu dot org
224 .\" * Date: Tue, 21 Sep 2004 04:16:40 -0400
225 このマクロを定義すると、文字列やメモリの操作を行う様々な関数を 使用する際にバッファオーバーフローを検出するための軽めのチェックが
226 実行されるようになる。すべてのバッファオーバーフローが検出される わけではなく、あくまでよくある例についてだけである。
227 現在の実装では、以下の関数にチェックが追加されている: \fBmemcpy\fP(3), \fBmempcpy\fP(3), \fBmemmove\fP(3),
228 \fBmemset\fP(3), \fBstpcpy\fP(3), \fBstrcpy\fP(3), \fBstrncpy\fP(3), \fBstrcat\fP(3),
229 \fBstrncat\fP(3), \fBsprintf\fP(3), \fBsnprintf\fP(3), \fBvsprintf\fP(3),
230 \fBvsnprintf\fP(3), \fBgets\fP(3).  \fB_FORTIFY_SOURCE\fP が 1 に設定された場合、コンパイラの最適化レベルが
231 1 (\fIgcc\ \-O1\fP)  かそれ以上であれば、規格に準拠するプログラムの振る舞いを 変化させないようなチェックが実行される。
232 \fB_FORTIFY_SOURCE\fP が 2 に設定された場合、さらなるチェックが追加されるが、
233 規格に準拠するプログラムのいくつかが失敗する可能性がある。 いくつかのチェックはコンパイル時に実行でき、コンパイラの警告として
234 表示される。他のチェックは実行時に行われ、チェックに失敗した場合 には実行時エラーとなる。 このマクロを使用するにはコンパイラの対応が必要であり、
235 バージョン 4.0 以降の \fBgcc\fP(1)  で利用できる。
236 .SS デフォルトの定義、暗黙の定義、組み合わせ定義
237 .PP
238 機能検査マクロが一つも明示的に定義されなかった場合、 デフォルトで機能検査マクロ \fB_BSD_SOURCE\fP, \fB_SVID_SOURCE\fP,
239 \fB_POSIX_SOURCE\fP, \fB_POSIX_C_SOURCE\fP=200809L が定義される (バージョン 2.10 より前の glibc
240 では値は 200112L、 バージョン 2.4 より前の glibc では値は 199506L、 バージョン 2.1 より前の glibc では値は
241 199309L)。
242 .PP
243 \fB__STRICT_ANSI__\fP, \fB_ISOC99_SOURCE\fP, \fB_POSIX_SOURCE\fP, \fB_POSIX_C_SOURCE\fP,
244 \fB_XOPEN_SOURCE\fP, \fB_XOPEN_SOURCE_EXTENDED\fP, \fB_BSD_SOURCE\fP, \fB_SVID_SOURCE\fP
245 のいずれかが明示的に定義された場合、 \fB_BSD_SOURCE\fP と \fB_SVID_SOURCE\fP はデフォルトでは定義されない。
246
247 \fB_POSIX_SOURCE\fP と \fB_POSIX_C_SOURCE\fP が明示的に定義されない場合で、 \fB__STRICT_ANSI__\fP
248 が定義されない、もしくは \fB_XOPEN_SOURCE\fP が 500 以上の値で定義されたときには、
249 .RS 3
250 .IP * 3
251 \fB_POSIX_SOURCE\fP が値 1 で定義され、かつ
252 .IP *
253 \fB_POSIX_C_SOURCE\fP は以下の値のいずれか一つで定義される。
254 .RS 6
255 .IP \(bu 3
256 2 (\fB_XOPEN_SOURCE\fP が 500 未満の値で定義された場合)
257 .IP \(bu
258 199506L (\fB_XOPEN_SOURCE\fP が 500 以上 600 未満の値で定義された場合)
259 .IP \(bu
260 (glibc 2.4 以降)  200112L (\fBXOPEN_SOURCE\fP が 600 以上 700 未満の値で定義された場合)
261 .IP \(bu
262 (glibc 2.10 以降)  200809L (\fBXOPEN_SOURCE\fP が 700 以上の値で定義された場合)
263 .IP \(bu
264 古いバージョンの glibc では \fB_POSIX_C_SOURCE\fP の値として 200112L や 200809L は存在せず、
265 \fB_POSIX_C_SOURCE\fP の値がどうなるかは glibc のバージョンにより異なる。
266 .IP \(bu
267 \fB_XOPEN_SOURCE\fP が未定義の場合、 \fB_POSIX_C_SOURCE\fP の値は glibc のバージョンにより異なる。 バージョン
268 2.4 より前の glibc では 199506L、 バージョン 2.4 以降 2.9 未満では 200112L、 glibc 2.10 以降では
269 200809L となる。
270 .RE
271 .RE
272 .PP
273 また、複数のマクロを定義することもできる。 この場合、定義したマクロはすべて有効になる。
274 .SH 準拠
275 POSIX.1 では \fB_POSIX_C_SOURCE\fP, \fB_POSIX_SOURCE\fP, \fB_XOPEN_SOURCE\fP が規定されている。
276 \fB_XOPEN_SOURCE_EXTENDED\fP は XPG4v2 (別名 SUSv1) で規定されていた。
277
278 \fB_FILE_OFFSET_BITS\fP はどの標準でも規定されていないが、 他のいくつかの実装で採用されている。
279
280 \fB_BSD_SOURCE\fP, \fB_SVID_SOURCE\fP, \fB_ATFILE_SOURCE\fP, \fB_GNU_SOURCE\fP,
281 \fB_FORTIFY_SOURCE\fP, \fB_REENTRANT\fP, \fB_THREAD_SAFE\fP は Linux (glibc) 固有である。
282 .SH 注意
283 \fI<features.h>\fP は Linux/glibc 固有のヘッダファイルである。
284 他のシステムにも同様の目的のファイルがあるが、普通は違う名前である。 このヘッダファイルは、他のヘッダファイルにより必要に応じて
285 自動的にインクルードされる。機能検査マクロを利用するために 明示的にインクルードする必要はない。
286
287 上記の機能検査マクロのうちどれが定義されたかにしたがって、 \fI<features.h>\fP は、他の glibc
288 ヘッダファイルでチェックされる各種の他のマクロを、 内部で定義する。これらのマクロの名前はアンダースコア 2つで始まる (例えば
289 \fB__USE_MISC\fP)。 ユーザプログラムはこれらのマクロを \fI決して\fP 直接定義すべきではない。
290 代わりに、上記のリストにある適切な機能検査マクロを利用すべきである。
291 .SH 例
292 下記のプログラムを使うと、各種の機能検査マクロが glibc のバージョン に応じてどのように設定されるかや、どの機能検査マクロが明示的に
293 設定されるか、を調べることができる。 以下に示すシェル・セッションは、 glibc 2.10 のシステムでの実行結果の例である。
294 .in +4n
295 .nf
296
297 $ \fBcc ftm.c\fP
298 $ \fB./a.out\fP
299 _POSIX_SOURCE defined
300 _POSIX_C_SOURCE defined: 200809L
301 _BSD_SOURCE defined
302 _SVID_SOURCE defined
303 _ATFILE_SOURCE defined
304 $ \fBcc \-D_XOPEN_SOURCE=500 ftm.c\fP
305 $ \fB./a.out\fP
306 _POSIX_SOURCE defined
307 _POSIX_C_SOURCE defined: 199506L
308 _XOPEN_SOURCE defined: 500
309 $ \fBcc \-D_GNU_SOURCE ftm.c\fP
310 $ \fB./a.out\fP
311 _POSIX_SOURCE defined
312 _POSIX_C_SOURCE defined: 200809L
313 _ISOC99_SOURCE defined
314 _XOPEN_SOURCE defined: 700
315 _XOPEN_SOURCE_EXTENDED defined
316 _LARGEFILE64_SOURCE defined
317 _BSD_SOURCE defined
318 _SVID_SOURCE defined
319 _ATFILE_SOURCE defined
320 _GNU_SOURCE defined
321 .fi
322 .in
323 .SS "Program source"
324 \&
325 .nf
326 /* ftm.c */
327
328 #include <stdio.h>
329 #include <unistd.h>
330 #include <stdlib.h>
331
332 int
333 main(int argc, char *argv[])
334 {
335 #ifdef _POSIX_SOURCE
336     printf("_POSIX_SOURCE defined\en");
337 #endif
338
339 #ifdef _POSIX_C_SOURCE
340     printf("_POSIX_C_SOURCE defined: %ldL\en", (long) _POSIX_C_SOURCE);
341 #endif
342
343 #ifdef _ISOC99_SOURCE
344     printf("_ISOC99_SOURCE defined\en");
345 #endif
346
347 #ifdef _XOPEN_SOURCE
348     printf("_XOPEN_SOURCE defined: %d\en", _XOPEN_SOURCE);
349 #endif
350
351 #ifdef _XOPEN_SOURCE_EXTENDED
352     printf("_XOPEN_SOURCE_EXTENDED defined\en");
353 #endif
354
355 #ifdef _LARGEFILE64_SOURCE
356     printf("_LARGEFILE64_SOURCE defined\en");
357 #endif
358
359 #ifdef _FILE_OFFSET_BITS
360     printf("_FILE_OFFSET_BITS defined: %d\en", _FILE_OFFSET_BITS);
361 #endif
362
363 #ifdef _BSD_SOURCE
364     printf("_BSD_SOURCE defined\en");
365 #endif
366
367 #ifdef _SVID_SOURCE
368     printf("_SVID_SOURCE defined\en");
369 #endif
370
371 #ifdef _ATFILE_SOURCE
372     printf("_ATFILE_SOURCE defined\en");
373 #endif
374
375 #ifdef _GNU_SOURCE
376     printf("_GNU_SOURCE defined\en");
377 #endif
378
379 #ifdef _REENTRANT
380     printf("_REENTRANT defined\en");
381 #endif
382
383 #ifdef _THREAD_SAFE
384     printf("_THREAD_SAFE defined\en");
385 #endif
386
387 #ifdef _FORTIFY_SOURCE
388     printf("_FORTIFY_SOURCE defined\en");
389 #endif
390
391     exit(EXIT_SUCCESS);
392 }
393 .fi
394 .SH 関連項目
395 \fBlibc\fP(7), \fBstandards\fP(7)
396 .sp
397 .\" But beware: the info libc document is out of date (Jul 07, mtk)
398 \fIinfo libc\fP の "Feature Test Macros" の節。
399 .sp
400 \fI/usr/include/features.h\fP