OSDN Git Service

50557692dadda032cca97f236109887e55b1940b
[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 .\" Japanese Version Copyright (c) 2006 Akihiro MOTOKI all rights reserved.
26 .\" Translated 2006-07-16, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>
27 .\" Updated 2007-05-01, Akihiro MOTOKI, LDP v2.46
28 .\" Updated 2007-09-08, Akihiro MOTOKI, LDP v2.64
29 .\" Updated 2009-04-23, Akihiro MOTOKI, LDP v3.21
30 .\"
31 .\"WORD:        feature test macro      機能検査マクロ
32 .\"WORD:        feature test macro requirements 機能検査マクロの要件
33 .\"
34 .TH FEATURE_TEST_MACROS 7 2010-09-10 "Linux" "Linux Programmer's Manual"
35 .SH 名前
36 feature_test_macros \- 機能検査マクロ
37 .SH 書式
38 .nf
39 .B #include <features.h>
40 .fi
41 .SH 説明
42 機能検査マクロ (feature test macro) により、プログラマは
43 プログラムがコンパイルされる際にシステムのヘッダファイルにより
44 公開される定義を制御することができる。
45
46 .B 注意:
47 機能検査マクロを機能させるには、機能検査マクロの定義を
48 「どのヘッダファイルのインクルードよりも前で」行わなければならない。
49 これを実現するには、
50 コンパイルコマンドで指定する方法
51 .RI ( "cc \-DMACRO=value" )
52 と、ソースコード内で必要なマクロの定義を
53 どのヘッダのインクルードよりも前で行う方法がある。
54
55 機能検査マクロを使うと、非標準の定義が公開されないようにでき、
56 移植性のあるアプリケーションを作成するのに役立つ。
57 他のマクロを使うと、デフォルトでは公開されない非標準の定義を
58 公開することができる。
59 以下で説明する機能検査マクロのそれぞれの正確な影響を確認するには、
60 ヘッダファイル
61 .I <features.h>
62 を調べればよい。
63
64 .SS マニュアルページでの機能検査マクロの要件の規定
65 関数が機能検査マクロの定義を必要とする場合、
66 マニュアルページの書式 (SYNOPSIS) の節に
67 以下の形式の注釈を入れる
68 (以下の例は
69 .BR acct (2)
70 のマニュアルページからの引用である)。
71 .RS 8
72 .sp
73 .B #include <unistd.h>
74 .sp
75 .BI "int acct(const char *" filename );
76 .sp
77 .nf
78 .in -4n
79 glibc 向けの機能検査マクロの要件
80 .RB ( feature_test_macros (7)
81 参照):
82 .fi
83 .in
84 .sp
85 .BR acct ():
86 _BSD_SOURCE || (_XOPEN_SOURCE && _XOPEN_SOURCE\ <\ 500)
87 .RE
88 .PP
89 \fB||\fP は、
90 .BR acct (2)
91 の定義を
92 .I <unistd.h>
93 から得るには、以下のマクロの定義のいずれかを、どのヘッダファイルの
94 インクルードよりも前で行わなければならないことを意味する。
95 .RS
96 .nf
97
98 #define _BSD_SOURCE
99 #define _XOPEN_SOURCE        /* or any value < 500 */
100 .fi
101 .RE
102 .PP
103 別の方法としては、等価な定義をコンパイル用のコマンドで
104 指定することもできる。
105 .RS
106 .nf
107
108 cc \-D_BSD_SOURCE
109 cc \-D_XOPEN_SOURCE           # Or any value < 500
110 .fi
111 .RE
112 .PP
113 後で述べるが、
114 .B 「いくつかの機能検査マクロはデフォルトで定義される」
115 点に注意すること。
116 このため、「書式」に記載された機能検査マクロを常に
117 明示的に指定する必要があるわけではない。
118
119 あまり多くないが、マニュアルページによっては、
120 機能検査マクロの要件を以下のように簡単な表現で記載する場合がある。
121 (以下の例は
122 .BR readahead (2)
123 のマニュアルページからの引用である)。
124 .RS
125 .nf
126
127 .B #define _GNU_SOURCE
128 .B #include <fcntl.h>
129 .sp
130 .BI "ssize_t readahead(int " fd ", off64_t *" offset ", size_t " count );
131 .fi
132 .RE
133 .PP
134 関数定義の公開に使える機能検査マクロが一つだけで、
135 デフォルトではそのマクロが定義されない場合に、
136 この形式の表現を利用する。
137 .SS glibc が解釈する機能検査マクロ
138 以下では、Linux glibc 2.\fIx\fP (\fIx\fP > 0) において、
139 機能検査マクロがどのように扱われるかを説明する。
140 .\" The details in glibc 2.0 are simpler, but combining a
141 .\" a description of them with the details in later glibc versions
142 .\" would make for a complicated description.
143
144 Linux/glibc は以下の機能検査マクロを解釈する:
145 .TP
146 .B __STRICT_ANSI__
147 ISO 標準の C。
148 .BR gcc (1)
149
150 .I -std=c99
151
152 .I -ansi
153 などのフラグを付けて起動した場合、
154 このマクロは暗黙のうちに定義される。
155 .TP
156 .B _POSIX_C_SOURCE
157 このマクロを定義すると、ヘッダファイルで
158 以下の定義が公開される。
159 .RS
160 .IP \(bu 3
161 値が 1 の場合、POSIX.1-1990 と ISO C (1990) に準拠する定義が公開される。
162 .IP \(bu
163 値が 2 以上の場合、
164 POSIX.2-1992 関連の定義も追加で公開される。
165 .IP \(bu
166 値が 199309 以上の場合、
167 POSIX.1b (リアルタイム拡張) 関連の定義が追加で公開される。
168 .\" 199506L functionality is only available since glibc 2.1
169 .IP \(bu
170 値が 199506 以上の場合、
171 POSIX.1c (スレッド) 関連の定義が追加で公開される。
172 .IP \(bu
173 (glibc 2.3.3 以降)
174 値が 200112L 以上の場合、
175 (XSI 拡張を除く) POSIX.1-2001 基本仕様に対応する定義が公開される。
176 .IP \(bu
177 (glibc 2.10 以降)
178 値が 200809L 以上の場合、
179 (XSI 拡張を除く) POSIX.1-2008 基本仕様に対応する定義が公開される。
180 .RE
181 .TP
182 .B _POSIX_SOURCE
183 このマクロは廃止予定である。
184 このマクロが定義されると、値に関わらず、
185 .B _POSIX_C_SOURCE
186 を値 1 で定義するのと等価となる。
187 .TP
188 .B _XOPEN_SOURCE
189 このマクロを定義すると、ヘッダファイルで以下の定義が公開される。
190 .RS
191 .IP \(bu 3
192 どんな値でも、ヘッダファイルで
193 POSIX.1, POSIX.2, XPG4 に準拠する定義が公開される。
194 .IP \(bu
195 値が 500 以上の場合、
196 SUSv2 (UNIX 98) 関連の定義が追加で公開される。
197 .IP \(bu
198 (glibc 2.2 以降)
199 値が 600 以上の場合、
200 SUSv3 (UNIX 03; POSIX.1-2001 基本仕様 + XSI 拡張と同じ)
201 関連の定義と C99 での定義が追加で公開される。
202 .IP \(bu
203 (glibc 2.10 以降)
204 値が 700 以上の場合、
205 SUSv4 (POSIX.1-2008 基本仕様 + XSI 拡張と同じ)
206 関連の定義が追加で公開される。
207 .RE
208 .TP
209 .B _XOPEN_SOURCE_EXTENDED
210 このマクロが定義され、さらに
211 .B _XOPEN_SOURCE
212 が定義されていると、XPG4v2 (SUSv1) UNIX 拡張 (UNIX 95)
213 に対応する定義が公開される。
214 .B _XOPEN_SOURCE
215 が 500 以上の値で定義された場合、このマクロは暗黙のうちに定義される。
216 .TP
217 .B _ISOC99_SOURCE
218 ISO C (1990) の C99 拡張を公開する。
219 このマクロは glibc 2.1.3 以降で認識される。
220 初期のバージョン 2.1.x の glibc では、これと等価な
221 .B _ISOC9X_SOURCE
222 という名前のマクロが使われていた
223 (なぜなら、C99 標準はまだ確定していなかったからである)。
224 .B _ISOC9X_SOURCE
225 マクロの使用は廃止されているが、
226 glibc は過去との互換性のため今でもこのマクロを認識する。
227 .TP
228 .B _LARGEFILE64_SOURCE
229 LFS (Large File Summit) により
230 "暫定拡張 (transitional extension)" Single UNIX Specification
231 として規定された代替 API (alternative API) に関する定義を公開する
232 (http://opengroup.org/platform/lfs.html 参照)。
233 代替 API は新規オブジェクト (関数と型) の集合で構成され、
234 その名前は "64" で終わる (例えば、
235 .I off_t
236 に対応するのは
237 .IR off64_t 、
238 .BR lseek ()
239 に対応するのは
240 .BR lseek64 ()
241 である)。
242 新しいプログラムではこのインタフェースを利用しないこと。
243 代わりに
244 .I _FILE_OFFSET_BITS=64
245 を利用すること。
246 .TP
247 .B _FILE_OFFSET_BITS
248 このマクロを値 64 で定義すると、ファイル I/O とファイルシステム操作に
249 関連する 32 ビット版の関数とデータタイプは自動的に 64 ビット版に
250 変換される。
251 これは、32 ビットシステムで大きなファイル (> 2 ギガバイト) の I/O
252 を実行する際に役立つ
253 (このマクロを定義すると、コンパイルし直すだけで大きなファイルを
254 扱えるプログラムを書くことができる)。
255 64 ビットシステムは、もともと 2 ギガバイトより大きなファイルを
256 扱えるので、64 ビットシステムではこのマクロは効果を持たない。
257 .TP
258 .B _BSD_SOURCE
259 このマクロを定義すると (値に関わらず) ヘッダファイルで
260 BSD 由来の定義が公開される。
261 また、このマクロを定義すると、相容れない標準が存在する状況において
262 BSD 由来の定義を優先するようになる。
263 ただし、
264 .BR _SVID_SOURCE ,
265 .BR _POSIX_SOURCE ,
266 .BR _POSIX_C_SOURCE ,
267 .BR _XOPEN_SOURCE ,
268 .BR _XOPEN_SOURCE_EXTENDED ,
269 .B _GNU_SOURCE
270 が一つでも定義された場合には、BSD 由来の定義は優先されなくなる。
271 .TP
272 .B _SVID_SOURCE
273 このマクロを定義すると (値に関わらず) ヘッダファイルで
274 System V 由来の定義が公開される
275 (SVID == System V Interface Definition;
276 .BR standards (7)
277 参照)。
278 .TP
279 .BR _ATFILE_SOURCE " (glibc 2.4 以降)"
280 このマクロを定義すると (値に関わらず) ヘッダファイルで
281 名前の末尾が "at" の各種の関数の定義が公開される。
282 .BR openat (2)
283 参照。
284 glibc 2.10 以降では、
285 .B _POSIX_C_SOURCE
286 が 200809L 以上の値で定義された場合には、
287 このマクロも暗黙のうちに定義される。
288 .TP
289 .B _GNU_SOURCE
290 このマクロを定義すると (値に関わらず) 以下のマクロを定義するのと
291 等価になる:
292 .BR _BSD_SOURCE ,
293 .BR _SVID_SOURCE ,
294 .BR _ATFILE_SOURCE ,
295 .BR _LARGEFILE64_SOURCE ,
296 .BR _ISOC99_SOURCE ,
297 .BR _XOPEN_SOURCE_EXTENDED ,
298 .BR _POSIX_SOURCE ,
299 値 200809L の
300 .B _POSIX_C_SOURCE
301 (バージョン 2.10 より前の glibc では値は 200112L、
302 バージョン 2.5 より前の glibc では値は 199506L、
303 バージョン 2.1 より前の glibc では値は 199309L),
304 値 700 の
305 .B _XOPEN_SOURCE
306 (バージョン 2.10 より前の glibc では値は 600、
307 バージョン 2.2 より前の glibc では値は 500)。
308 さらに、各種の GNU 固有の拡張も公開される。
309 指定された標準に矛盾があった場合は、
310 BSD 由来の定義が優先されなくなる。
311 .TP
312 .B _REENTRANT
313 このマクロを定義すると、いくつかのリエントラント (再入可能) な関数
314 定義が公開される。マルチスレッド・プログラムでは、この代わりに
315 .I "cc\ \-pthread"
316 を使用すること。
317 .TP
318 .B _THREAD_SAFE
319 .B _REENTRANT
320 の同義語。
321 他のいくつかの実装との互換性を提供するためのもの。
322 .TP
323 .BR _FORTIFY_SOURCE " (glibc 2.3.4 以降)"
324 .\" For more detail, see:
325 .\" http://gcc.gnu.org/ml/gcc-patches/2004-09/msg02055.html
326 .\" [PATCH] Object size checking to prevent (some) buffer overflows
327 .\" * From: Jakub Jelinek <jakub at redhat dot com>
328 .\" * To: gcc-patches at gcc dot gnu dot org
329 .\" * Date: Tue, 21 Sep 2004 04:16:40 -0400
330 このマクロを定義すると、文字列やメモリの操作を行う様々な関数を
331 使用する際にバッファオーバーフローを検出するための軽めのチェックが
332 実行されるようになる。すべてのバッファオーバーフローが検出される
333 わけではなく、あくまでよくある例についてだけである。
334 現在の実装では、以下の関数にチェックが追加されている:
335 .BR memcpy (3),
336 .BR mempcpy (3),
337 .BR memmove (3),
338 .BR memset (3),
339 .BR stpcpy (3),
340 .BR strcpy (3),
341 .BR strncpy (3),
342 .BR strcat (3),
343 .BR strncat (3),
344 .BR sprintf (3),
345 .BR snprintf (3),
346 .BR vsprintf (3),
347 .BR vsnprintf (3),
348 .BR gets (3).
349 .B _FORTIFY_SOURCE
350 が 1 に設定された場合、コンパイラの最適化レベルが 1
351 .RI ( "gcc\ \-O1" )
352 かそれ以上であれば、規格に準拠するプログラムの振る舞いを
353 変化させないようなチェックが実行される。
354 .B _FORTIFY_SOURCE
355 が 2 に設定された場合、さらなるチェックが追加されるが、
356 規格に準拠するプログラムのいくつかが失敗する可能性がある。
357 いくつかのチェックはコンパイル時に実行でき、コンパイラの警告として
358 表示される。他のチェックは実行時に行われ、チェックに失敗した場合
359 には実行時エラーとなる。
360 このマクロを使用するにはコンパイラの対応が必要であり、
361 バージョン 4.0 以降の
362 .BR gcc (1)
363 で利用できる。
364 .SS デフォルトの定義、暗黙の定義、組み合わせ定義
365 .PP
366 機能検査マクロが一つも明示的に定義されなかった場合、
367 デフォルトで機能検査マクロ
368 .BR _BSD_SOURCE ,
369 .BR _SVID_SOURCE ,
370 .BR _POSIX_SOURCE ,
371 .BR _POSIX_C_SOURCE =200809L
372 が定義される
373 (バージョン 2.10 より前の glibc では値は 200112L、
374 バージョン 2.4 より前の glibc では値は 199506L、
375 バージョン 2.1 より前の glibc では値は 199309L)。
376 .PP
377 .BR __STRICT_ANSI__ ,
378 .BR _ISOC99_SOURCE ,
379 .BR _POSIX_SOURCE ,
380 .BR _POSIX_C_SOURCE  ,
381 .BR _XOPEN_SOURCE ,
382 .BR _XOPEN_SOURCE_EXTENDED ,
383 .BR _BSD_SOURCE ,
384 .B _SVID_SOURCE
385 のいずれかが明示的に定義された場合、
386 .B _BSD_SOURCE
387
388 .B _SVID_SOURCE
389 はデフォルトでは定義されない。
390
391 .B _POSIX_SOURCE
392
393 .B _POSIX_C_SOURCE
394 が明示的に定義されない場合で、
395 .B __STRICT_ANSI__
396 が定義されない、もしくは
397 .B _XOPEN_SOURCE
398 が 500 以上の値で定義されたときには、
399 .RS 3
400 .IP * 3
401 .B _POSIX_SOURCE
402 が値 1 で定義され、かつ
403 .IP *
404 .B _POSIX_C_SOURCE
405 は以下の値のいずれか一つで定義される。
406 .RS 6
407 .IP \(bu 3
408 2
409 .RB ( _XOPEN_SOURCE
410 が 500 未満の値で定義された場合)
411 .IP \(bu
412 199506L
413 .RB ( _XOPEN_SOURCE
414 が 500 以上 600 未満の値で定義された場合)
415 .IP \(bu
416 (glibc 2.4 以降)
417 200112L
418 .RB ( XOPEN_SOURCE
419 が 600 以上 700 未満の値で定義された場合)
420 .IP \(bu
421 (glibc 2.10 以降)
422 200809L
423 .RB ( XOPEN_SOURCE
424 が 700 以上の値で定義された場合)
425 .IP \(bu
426 古いバージョンの glibc では
427 .B _POSIX_C_SOURCE
428 の値として 200112L や 200809L は存在せず、
429 .B _POSIX_C_SOURCE
430 の値がどうなるかは glibc のバージョンにより異なる。
431 .IP \(bu
432 .B _XOPEN_SOURCE
433 が未定義の場合、
434 .B _POSIX_C_SOURCE
435 の値は glibc のバージョンにより異なる。
436 バージョン 2.4 より前の glibc では 199506L、
437 バージョン 2.4 以降 2.9 未満では 200112L、
438 glibc 2.10 以降では 200809L となる。
439 .RE
440 .RE
441 .PP
442 また、複数のマクロを定義することもできる。
443 この場合、定義したマクロはすべて有効になる。
444 .SH 準拠
445 POSIX.1 では
446 .BR _POSIX_C_SOURCE ,
447 .BR _POSIX_SOURCE ,
448 .B _XOPEN_SOURCE
449 が規定されている。
450 .B _XOPEN_SOURCE_EXTENDED
451 は XPG4v2 (別名 SUSv1) で規定されていた。
452
453 .B _FILE_OFFSET_BITS
454 はどの標準でも規定されていないが、
455 他のいくつかの実装で採用されている。
456
457 .BR _BSD_SOURCE ,
458 .BR _SVID_SOURCE ,
459 .BR _ATFILE_SOURCE ,
460 .BR _GNU_SOURCE ,
461 .BR _FORTIFY_SOURCE ,
462 .BR _REENTRANT ,
463 .B _THREAD_SAFE
464 は Linux (glibc) 固有である。
465 .SH 注意
466 .I <features.h>
467 は Linux/glibc 固有のヘッダファイルである。
468 他のシステムにも同様の目的のファイルがあるが、普通は違う名前である。
469 このヘッダファイルは、他のヘッダファイルにより必要に応じて
470 自動的にインクルードされる。機能検査マクロを利用するために
471 明示的にインクルードする必要はない。
472
473 上記の機能検査マクロのうちどれが定義されたかにしたがって、
474 .I <features.h>
475 は、他の glibc ヘッダファイルでチェックされる各種の他のマクロを、
476 内部で定義する。これらのマクロの名前はアンダースコア 2つで始まる
477 (例えば
478 .BR __USE_MISC )。
479 ユーザプログラムはこれらのマクロを \fI決して\fP 直接定義すべきではない。
480 代わりに、上記のリストにある適切な機能検査マクロを利用すべきである。
481 .SH 例
482 下記のプログラムを使うと、各種の機能検査マクロが glibc のバージョン
483 に応じてどのように設定されるかや、どの機能検査マクロが明示的に
484 設定されるか、を調べることができる。
485 以下に示すシェル・セッションは、
486 glibc 2.10 のシステムでの実行結果の例である。
487 .in +4n
488 .nf
489
490 $ \fBcc ftm.c\fP
491 $ \fB./a.out\fP
492 _POSIX_SOURCE defined
493 _POSIX_C_SOURCE defined: 200809L
494 _BSD_SOURCE defined
495 _SVID_SOURCE defined
496 _ATFILE_SOURCE defined
497 $ \fBcc -D_XOPEN_SOURCE=500 ftm.c\fP
498 $ \fB./a.out\fP
499 _POSIX_SOURCE defined
500 _POSIX_C_SOURCE defined: 199506L
501 _XOPEN_SOURCE defined: 500
502 $ \fBcc -D_GNU_SOURCE ftm.c\fP
503 $ \fB./a.out\fP
504 _POSIX_SOURCE defined
505 _POSIX_C_SOURCE defined: 200809L
506 _ISOC99_SOURCE defined
507 _XOPEN_SOURCE defined: 700
508 _XOPEN_SOURCE_EXTENDED defined
509 _LARGEFILE64_SOURCE defined
510 _BSD_SOURCE defined
511 _SVID_SOURCE defined
512 _ATFILE_SOURCE defined
513 _GNU_SOURCE defined
514 .fi
515 .in
516 .SS Program source
517 \&
518 .nf
519 /* ftm.c */
520
521 #include <stdio.h>
522 #include <unistd.h>
523 #include <stdlib.h>
524
525 int
526 main(int argc, char *argv[])
527 {
528 #ifdef _POSIX_SOURCE
529     printf("_POSIX_SOURCE defined\\n");
530 #endif
531
532 #ifdef _POSIX_C_SOURCE
533     printf("_POSIX_C_SOURCE defined: %ldL\\n", (long) _POSIX_C_SOURCE);
534 #endif
535
536 #ifdef _ISOC99_SOURCE
537     printf("_ISOC99_SOURCE defined\\n");
538 #endif
539
540 #ifdef _XOPEN_SOURCE
541     printf("_XOPEN_SOURCE defined: %d\\n", _XOPEN_SOURCE);
542 #endif
543
544 #ifdef _XOPEN_SOURCE_EXTENDED
545     printf("_XOPEN_SOURCE_EXTENDED defined\\n");
546 #endif
547
548 #ifdef _LARGEFILE64_SOURCE
549     printf("_LARGEFILE64_SOURCE defined\\n");
550 #endif
551
552 #ifdef _FILE_OFFSET_BITS
553     printf("_FILE_OFFSET_BITS defined: %d\\n", _FILE_OFFSET_BITS);
554 #endif
555
556 #ifdef _BSD_SOURCE
557     printf("_BSD_SOURCE defined\\n");
558 #endif
559
560 #ifdef _SVID_SOURCE
561     printf("_SVID_SOURCE defined\\n");
562 #endif
563
564 #ifdef _ATFILE_SOURCE
565     printf("_ATFILE_SOURCE defined\\n");
566 #endif
567
568 #ifdef _GNU_SOURCE
569     printf("_GNU_SOURCE defined\\n");
570 #endif
571
572 #ifdef _REENTRANT
573     printf("_REENTRANT defined\\n");
574 #endif
575
576 #ifdef _THREAD_SAFE
577     printf("_THREAD_SAFE defined\\n");
578 #endif
579
580 #ifdef _FORTIFY_SOURCE
581     printf("_FORTIFY_SOURCE defined\\n");
582 #endif
583
584     exit(EXIT_SUCCESS);
585 }
586 .fi
587 .SH 関連項目
588 .BR libc (7),
589 .BR standards (7)
590 .sp
591 .I "info libc"
592 の "Feature Test Macros" の節。
593 .\" But beware: the info libc document is out of date (Jul 07, mtk)
594 .sp
595 .I /usr/include/features.h