From 554fd8c5195424bdbcabf5de30fdc183aba391bd Mon Sep 17 00:00:00 2001 From: upstream source tree Date: Sun, 15 Mar 2015 20:14:05 -0400 Subject: obtained gcc-4.6.4.tar.bz2 from upstream website; verified gcc-4.6.4.tar.bz2.sig; imported gcc-4.6.4 source tree from verified upstream tarball. downloading a git-generated archive based on the 'upstream' tag should provide you with a source tree that is binary identical to the one extracted from the above tarball. if you have obtained the source via the command 'git clone', however, do note that line-endings of files in your working directory might differ from line-endings of the respective files in the upstream repository. --- gcc/doc/aot-compile.1 | 200 + gcc/doc/arm-neon-intrinsics.texi | 11265 +++++++++ gcc/doc/bugreport.texi | 91 + gcc/doc/cfg.texi | 659 + gcc/doc/collect2.texi | 89 + gcc/doc/compat.texi | 156 + gcc/doc/configfiles.texi | 64 + gcc/doc/configterms.texi | 61 + gcc/doc/contrib.texi | 1636 ++ gcc/doc/contribute.texi | 25 + gcc/doc/cpp.1 | 992 + gcc/doc/cpp.info | 5549 +++++ gcc/doc/cpp.texi | 4472 ++++ gcc/doc/cppenv.texi | 83 + gcc/doc/cppinternals.info | 1036 + gcc/doc/cppinternals.texi | 1068 + gcc/doc/cppopts.texi | 797 + gcc/doc/extend.texi | 14546 +++++++++++ gcc/doc/fragments.texi | 248 + gcc/doc/frontends.texi | 63 + gcc/doc/fsf-funding.7 | 184 + gcc/doc/g++.1 | 17436 +++++++++++++ gcc/doc/gc-analyze.1 | 222 + gcc/doc/gcc.1 | 17436 +++++++++++++ gcc/doc/gcc.info | 48624 +++++++++++++++++++++++++++++++++++++ gcc/doc/gcc.texi | 209 + gcc/doc/gccinstall.info | 4621 ++++ gcc/doc/gccint.info | 47923 ++++++++++++++++++++++++++++++++++++ gcc/doc/gccint.texi | 200 + gcc/doc/gcj-dbtool.1 | 238 + gcc/doc/gcj.1 | 584 + gcc/doc/gcj.info | 3694 +++ gcc/doc/gcov.1 | 635 + gcc/doc/gcov.texi | 578 + gcc/doc/generic.texi | 3345 +++ gcc/doc/gfdl.7 | 637 + gcc/doc/gfortran.1 | 1279 + gcc/doc/gij.1 | 286 + gcc/doc/gimple.texi | 2574 ++ gcc/doc/gnu.texi | 20 + gcc/doc/gpl.7 | 841 + gcc/doc/grmic.1 | 213 + gcc/doc/gty.texi | 538 + gcc/doc/headerdirs.texi | 32 + gcc/doc/hostconfig.texi | 231 + gcc/doc/implement-c.texi | 676 + gcc/doc/implement-cxx.texi | 61 + gcc/doc/include/fdl.texi | 540 + gcc/doc/include/funding.texi | 60 + gcc/doc/include/gcc-common.texi | 74 + gcc/doc/include/gpl.texi | 410 + gcc/doc/include/gpl_v3.texi | 733 + gcc/doc/include/texinfo.tex | 8978 +++++++ gcc/doc/install-old.texi | 194 + gcc/doc/install.texi | 4675 ++++ gcc/doc/install.texi2html | 58 + gcc/doc/interface.texi | 71 + gcc/doc/invoke.texi | 18730 ++++++++++++++ gcc/doc/jcf-dump.1 | 208 + gcc/doc/jv-convert.1 | 201 + gcc/doc/languages.texi | 36 + gcc/doc/libgcc.texi | 2305 ++ gcc/doc/loop.texi | 655 + gcc/doc/lto.texi | 568 + gcc/doc/makefile.texi | 193 + gcc/doc/md.texi | 8486 +++++++ gcc/doc/objc.texi | 1227 + gcc/doc/options.texi | 452 + gcc/doc/passes.texi | 940 + gcc/doc/plugins.texi | 440 + gcc/doc/portability.texi | 40 + gcc/doc/rebuild-gcj-db.1 | 172 + gcc/doc/rtl.texi | 4148 ++++ gcc/doc/service.texi | 28 + gcc/doc/sourcebuild.texi | 2582 ++ gcc/doc/standards.texi | 294 + gcc/doc/tm.texi | 11301 +++++++++ gcc/doc/tm.texi.in | 11241 +++++++++ gcc/doc/tree-ssa.texi | 923 + gcc/doc/trouble.texi | 1218 + 80 files changed, 278598 insertions(+) create mode 100644 gcc/doc/aot-compile.1 create mode 100644 gcc/doc/arm-neon-intrinsics.texi create mode 100644 gcc/doc/bugreport.texi create mode 100644 gcc/doc/cfg.texi create mode 100644 gcc/doc/collect2.texi create mode 100644 gcc/doc/compat.texi create mode 100644 gcc/doc/configfiles.texi create mode 100644 gcc/doc/configterms.texi create mode 100644 gcc/doc/contrib.texi create mode 100644 gcc/doc/contribute.texi create mode 100644 gcc/doc/cpp.1 create mode 100644 gcc/doc/cpp.info create mode 100644 gcc/doc/cpp.texi create mode 100644 gcc/doc/cppenv.texi create mode 100644 gcc/doc/cppinternals.info create mode 100644 gcc/doc/cppinternals.texi create mode 100644 gcc/doc/cppopts.texi create mode 100644 gcc/doc/extend.texi create mode 100644 gcc/doc/fragments.texi create mode 100644 gcc/doc/frontends.texi create mode 100644 gcc/doc/fsf-funding.7 create mode 100644 gcc/doc/g++.1 create mode 100644 gcc/doc/gc-analyze.1 create mode 100644 gcc/doc/gcc.1 create mode 100644 gcc/doc/gcc.info create mode 100644 gcc/doc/gcc.texi create mode 100644 gcc/doc/gccinstall.info create mode 100644 gcc/doc/gccint.info create mode 100644 gcc/doc/gccint.texi create mode 100644 gcc/doc/gcj-dbtool.1 create mode 100644 gcc/doc/gcj.1 create mode 100644 gcc/doc/gcj.info create mode 100644 gcc/doc/gcov.1 create mode 100644 gcc/doc/gcov.texi create mode 100644 gcc/doc/generic.texi create mode 100644 gcc/doc/gfdl.7 create mode 100644 gcc/doc/gfortran.1 create mode 100644 gcc/doc/gij.1 create mode 100644 gcc/doc/gimple.texi create mode 100644 gcc/doc/gnu.texi create mode 100644 gcc/doc/gpl.7 create mode 100644 gcc/doc/grmic.1 create mode 100644 gcc/doc/gty.texi create mode 100644 gcc/doc/headerdirs.texi create mode 100644 gcc/doc/hostconfig.texi create mode 100644 gcc/doc/implement-c.texi create mode 100644 gcc/doc/implement-cxx.texi create mode 100644 gcc/doc/include/fdl.texi create mode 100644 gcc/doc/include/funding.texi create mode 100644 gcc/doc/include/gcc-common.texi create mode 100644 gcc/doc/include/gpl.texi create mode 100644 gcc/doc/include/gpl_v3.texi create mode 100644 gcc/doc/include/texinfo.tex create mode 100644 gcc/doc/install-old.texi create mode 100644 gcc/doc/install.texi create mode 100755 gcc/doc/install.texi2html create mode 100644 gcc/doc/interface.texi create mode 100644 gcc/doc/invoke.texi create mode 100644 gcc/doc/jcf-dump.1 create mode 100644 gcc/doc/jv-convert.1 create mode 100644 gcc/doc/languages.texi create mode 100644 gcc/doc/libgcc.texi create mode 100644 gcc/doc/loop.texi create mode 100644 gcc/doc/lto.texi create mode 100644 gcc/doc/makefile.texi create mode 100644 gcc/doc/md.texi create mode 100644 gcc/doc/objc.texi create mode 100644 gcc/doc/options.texi create mode 100644 gcc/doc/passes.texi create mode 100644 gcc/doc/plugins.texi create mode 100644 gcc/doc/portability.texi create mode 100644 gcc/doc/rebuild-gcj-db.1 create mode 100644 gcc/doc/rtl.texi create mode 100644 gcc/doc/service.texi create mode 100644 gcc/doc/sourcebuild.texi create mode 100644 gcc/doc/standards.texi create mode 100644 gcc/doc/tm.texi create mode 100644 gcc/doc/tm.texi.in create mode 100644 gcc/doc/tree-ssa.texi create mode 100644 gcc/doc/trouble.texi (limited to 'gcc/doc') diff --git a/gcc/doc/aot-compile.1 b/gcc/doc/aot-compile.1 new file mode 100644 index 000000000..debf952c8 --- /dev/null +++ b/gcc/doc/aot-compile.1 @@ -0,0 +1,200 @@ +.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is turned on, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.ie \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. nr % 0 +. rr F +.\} +.el \{\ +. de IX +.. +.\} +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "AOT-COMPILE 1" +.TH AOT-COMPILE 1 "2013-04-12" "gcc-4.6.4" "GNU" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +aot\-compile \- Compile bytecode to native and generate databases +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +aot-compile [\fB\s-1OPTION\s0\fR] ... \fI\s-1SRCDIR\s0\fR \fI\s-1DSTDIR\s0\fR +.PP +aot-compile [\fB\-M, \-\-make\fR=\fI\s-1PATH\s0\fR] [\fB\-C, \-\-gcj\fR=\fI\s-1PATH\s0\fR] + [\fB\-D, \-\-dbtool\fR=\fI\s-1PATH\s0\fR] [\fB\-m, \-\-makeflags\fR=\fI\s-1FLAGS\s0\fR] + [\fB\-c, \-\-gcjflags\fR=\fI\s-1FLAGS\s0\fR] [\fB\-l, \-\-ldflags\fR=\fI\s-1FLAGS\s0\fR] + [\fB\-e, \-\-exclude\fR=\fI\s-1PATH\s0\fR] +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +\&\f(CW\*(C`aot\-compile\*(C'\fR is a script that searches a directory for Java bytecode +(as class files, or in jars) and uses \f(CW\*(C`gcj\*(C'\fR to compile it to native +code and generate the databases from it. +.SH "OPTIONS" +.IX Header "OPTIONS" +.IP "\fB\-M, \-\-make=\fR\fI\s-1PATH\s0\fR" 4 +.IX Item "-M, --make=PATH" +Specify the path to the \f(CW\*(C`make\*(C'\fR executable to use. +.IP "\fB\-C, \-\-gcj=\fR\fI\s-1PATH\s0\fR" 4 +.IX Item "-C, --gcj=PATH" +Specify the path to the \f(CW\*(C`gcj\*(C'\fR executable to use. +.IP "\fB\-D, \-\-dbtool=\fR\fI\s-1PATH\s0\fR" 4 +.IX Item "-D, --dbtool=PATH" +Specify the path to the \f(CW\*(C`gcj\-dbtool\*(C'\fR executable to use. +.IP "\fB\-m, \-\-makeflags=\fR\fI\s-1FLAGS\s0\fR" 4 +.IX Item "-m, --makeflags=FLAGS" +Specify flags to pass to \f(CW\*(C`make\*(C'\fR during the build. +.IP "\fB\-c, \-\-gcjflags=\fR\fI\s-1FLAGS\s0\fR" 4 +.IX Item "-c, --gcjflags=FLAGS" +Specify flags to pass to \f(CW\*(C`gcj\*(C'\fR during compilation, in addition to +\&'\-fPIC \-findirect\-dispatch \-fjni'. +.IP "\fB\-l, \-\-ldflags=\fR\fI\s-1FLAGS\s0\fR" 4 +.IX Item "-l, --ldflags=FLAGS" +Specify flags to pass to \f(CW\*(C`gcj\*(C'\fR during linking, in addition to +\&'\-Wl,\-Bsymbolic'. +.IP "\fB\-e, \-\-exclude=\fR\fI\s-1PATH\s0\fR" 4 +.IX Item "-e, --exclude=PATH" +Do not compile \fI\s-1PATH\s0\fR. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fIgcc\fR\|(1), \fIgcj\fR\|(1), \fIgcjh\fR\|(1), \fIjcf\-dump\fR\|(1), \fIgfdl\fR\|(7), +and the Info entries for \fIgcj\fR and \fIgcc\fR. +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2010 Free Software Foundation, Inc. +.PP +Permission is granted to copy, distribute and/or modify this document +under the terms of the \s-1GNU\s0 Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with no +Invariant Sections, the Front-Cover Texts being (a) (see below), and +with the Back-Cover Texts being (b) (see below). +A copy of the license is included in the +man page \fIgfdl\fR\|(7). +.PP +(a) The \s-1FSF\s0's Front-Cover Text is: +.PP +.Vb 1 +\& A GNU Manual +.Ve +.PP +(b) The \s-1FSF\s0's Back-Cover Text is: +.PP +.Vb 3 +\& You have freedom to copy and modify this GNU Manual, like GNU +\& software. Copies published by the Free Software Foundation raise +\& funds for GNU development. +.Ve diff --git a/gcc/doc/arm-neon-intrinsics.texi b/gcc/doc/arm-neon-intrinsics.texi new file mode 100644 index 000000000..a75e5821e --- /dev/null +++ b/gcc/doc/arm-neon-intrinsics.texi @@ -0,0 +1,11265 @@ +@c Copyright (C) 2006 Free Software Foundation, Inc. +@c This is part of the GCC manual. +@c For copying conditions, see the file gcc.texi. + +@c This file is generated automatically using gcc/config/arm/neon-docgen.ml +@c Please do not edit manually. +@subsubsection Addition + +@itemize @bullet +@item uint32x2_t vadd_u32 (uint32x2_t, uint32x2_t) +@*@emph{Form of expected instruction(s):} @code{vadd.i32 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint16x4_t vadd_u16 (uint16x4_t, uint16x4_t) +@*@emph{Form of expected instruction(s):} @code{vadd.i16 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint8x8_t vadd_u8 (uint8x8_t, uint8x8_t) +@*@emph{Form of expected instruction(s):} @code{vadd.i8 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int32x2_t vadd_s32 (int32x2_t, int32x2_t) +@*@emph{Form of expected instruction(s):} @code{vadd.i32 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int16x4_t vadd_s16 (int16x4_t, int16x4_t) +@*@emph{Form of expected instruction(s):} @code{vadd.i16 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int8x8_t vadd_s8 (int8x8_t, int8x8_t) +@*@emph{Form of expected instruction(s):} @code{vadd.i8 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item float32x2_t vadd_f32 (float32x2_t, float32x2_t) +@*@emph{Form of expected instruction(s):} @code{vadd.f32 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint64x1_t vadd_u64 (uint64x1_t, uint64x1_t) +@end itemize + + +@itemize @bullet +@item int64x1_t vadd_s64 (int64x1_t, int64x1_t) +@end itemize + + +@itemize @bullet +@item uint32x4_t vaddq_u32 (uint32x4_t, uint32x4_t) +@*@emph{Form of expected instruction(s):} @code{vadd.i32 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint16x8_t vaddq_u16 (uint16x8_t, uint16x8_t) +@*@emph{Form of expected instruction(s):} @code{vadd.i16 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint8x16_t vaddq_u8 (uint8x16_t, uint8x16_t) +@*@emph{Form of expected instruction(s):} @code{vadd.i8 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int32x4_t vaddq_s32 (int32x4_t, int32x4_t) +@*@emph{Form of expected instruction(s):} @code{vadd.i32 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int16x8_t vaddq_s16 (int16x8_t, int16x8_t) +@*@emph{Form of expected instruction(s):} @code{vadd.i16 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int8x16_t vaddq_s8 (int8x16_t, int8x16_t) +@*@emph{Form of expected instruction(s):} @code{vadd.i8 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint64x2_t vaddq_u64 (uint64x2_t, uint64x2_t) +@*@emph{Form of expected instruction(s):} @code{vadd.i64 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int64x2_t vaddq_s64 (int64x2_t, int64x2_t) +@*@emph{Form of expected instruction(s):} @code{vadd.i64 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item float32x4_t vaddq_f32 (float32x4_t, float32x4_t) +@*@emph{Form of expected instruction(s):} @code{vadd.f32 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint64x2_t vaddl_u32 (uint32x2_t, uint32x2_t) +@*@emph{Form of expected instruction(s):} @code{vaddl.u32 @var{q0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint32x4_t vaddl_u16 (uint16x4_t, uint16x4_t) +@*@emph{Form of expected instruction(s):} @code{vaddl.u16 @var{q0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint16x8_t vaddl_u8 (uint8x8_t, uint8x8_t) +@*@emph{Form of expected instruction(s):} @code{vaddl.u8 @var{q0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int64x2_t vaddl_s32 (int32x2_t, int32x2_t) +@*@emph{Form of expected instruction(s):} @code{vaddl.s32 @var{q0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int32x4_t vaddl_s16 (int16x4_t, int16x4_t) +@*@emph{Form of expected instruction(s):} @code{vaddl.s16 @var{q0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int16x8_t vaddl_s8 (int8x8_t, int8x8_t) +@*@emph{Form of expected instruction(s):} @code{vaddl.s8 @var{q0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint64x2_t vaddw_u32 (uint64x2_t, uint32x2_t) +@*@emph{Form of expected instruction(s):} @code{vaddw.u32 @var{q0}, @var{q0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint32x4_t vaddw_u16 (uint32x4_t, uint16x4_t) +@*@emph{Form of expected instruction(s):} @code{vaddw.u16 @var{q0}, @var{q0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint16x8_t vaddw_u8 (uint16x8_t, uint8x8_t) +@*@emph{Form of expected instruction(s):} @code{vaddw.u8 @var{q0}, @var{q0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int64x2_t vaddw_s32 (int64x2_t, int32x2_t) +@*@emph{Form of expected instruction(s):} @code{vaddw.s32 @var{q0}, @var{q0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int32x4_t vaddw_s16 (int32x4_t, int16x4_t) +@*@emph{Form of expected instruction(s):} @code{vaddw.s16 @var{q0}, @var{q0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int16x8_t vaddw_s8 (int16x8_t, int8x8_t) +@*@emph{Form of expected instruction(s):} @code{vaddw.s8 @var{q0}, @var{q0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint32x2_t vhadd_u32 (uint32x2_t, uint32x2_t) +@*@emph{Form of expected instruction(s):} @code{vhadd.u32 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint16x4_t vhadd_u16 (uint16x4_t, uint16x4_t) +@*@emph{Form of expected instruction(s):} @code{vhadd.u16 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint8x8_t vhadd_u8 (uint8x8_t, uint8x8_t) +@*@emph{Form of expected instruction(s):} @code{vhadd.u8 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int32x2_t vhadd_s32 (int32x2_t, int32x2_t) +@*@emph{Form of expected instruction(s):} @code{vhadd.s32 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int16x4_t vhadd_s16 (int16x4_t, int16x4_t) +@*@emph{Form of expected instruction(s):} @code{vhadd.s16 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int8x8_t vhadd_s8 (int8x8_t, int8x8_t) +@*@emph{Form of expected instruction(s):} @code{vhadd.s8 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint32x4_t vhaddq_u32 (uint32x4_t, uint32x4_t) +@*@emph{Form of expected instruction(s):} @code{vhadd.u32 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint16x8_t vhaddq_u16 (uint16x8_t, uint16x8_t) +@*@emph{Form of expected instruction(s):} @code{vhadd.u16 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint8x16_t vhaddq_u8 (uint8x16_t, uint8x16_t) +@*@emph{Form of expected instruction(s):} @code{vhadd.u8 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int32x4_t vhaddq_s32 (int32x4_t, int32x4_t) +@*@emph{Form of expected instruction(s):} @code{vhadd.s32 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int16x8_t vhaddq_s16 (int16x8_t, int16x8_t) +@*@emph{Form of expected instruction(s):} @code{vhadd.s16 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int8x16_t vhaddq_s8 (int8x16_t, int8x16_t) +@*@emph{Form of expected instruction(s):} @code{vhadd.s8 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint32x2_t vrhadd_u32 (uint32x2_t, uint32x2_t) +@*@emph{Form of expected instruction(s):} @code{vrhadd.u32 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint16x4_t vrhadd_u16 (uint16x4_t, uint16x4_t) +@*@emph{Form of expected instruction(s):} @code{vrhadd.u16 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint8x8_t vrhadd_u8 (uint8x8_t, uint8x8_t) +@*@emph{Form of expected instruction(s):} @code{vrhadd.u8 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int32x2_t vrhadd_s32 (int32x2_t, int32x2_t) +@*@emph{Form of expected instruction(s):} @code{vrhadd.s32 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int16x4_t vrhadd_s16 (int16x4_t, int16x4_t) +@*@emph{Form of expected instruction(s):} @code{vrhadd.s16 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int8x8_t vrhadd_s8 (int8x8_t, int8x8_t) +@*@emph{Form of expected instruction(s):} @code{vrhadd.s8 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint32x4_t vrhaddq_u32 (uint32x4_t, uint32x4_t) +@*@emph{Form of expected instruction(s):} @code{vrhadd.u32 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint16x8_t vrhaddq_u16 (uint16x8_t, uint16x8_t) +@*@emph{Form of expected instruction(s):} @code{vrhadd.u16 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint8x16_t vrhaddq_u8 (uint8x16_t, uint8x16_t) +@*@emph{Form of expected instruction(s):} @code{vrhadd.u8 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int32x4_t vrhaddq_s32 (int32x4_t, int32x4_t) +@*@emph{Form of expected instruction(s):} @code{vrhadd.s32 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int16x8_t vrhaddq_s16 (int16x8_t, int16x8_t) +@*@emph{Form of expected instruction(s):} @code{vrhadd.s16 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int8x16_t vrhaddq_s8 (int8x16_t, int8x16_t) +@*@emph{Form of expected instruction(s):} @code{vrhadd.s8 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint32x2_t vqadd_u32 (uint32x2_t, uint32x2_t) +@*@emph{Form of expected instruction(s):} @code{vqadd.u32 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint16x4_t vqadd_u16 (uint16x4_t, uint16x4_t) +@*@emph{Form of expected instruction(s):} @code{vqadd.u16 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint8x8_t vqadd_u8 (uint8x8_t, uint8x8_t) +@*@emph{Form of expected instruction(s):} @code{vqadd.u8 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int32x2_t vqadd_s32 (int32x2_t, int32x2_t) +@*@emph{Form of expected instruction(s):} @code{vqadd.s32 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int16x4_t vqadd_s16 (int16x4_t, int16x4_t) +@*@emph{Form of expected instruction(s):} @code{vqadd.s16 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int8x8_t vqadd_s8 (int8x8_t, int8x8_t) +@*@emph{Form of expected instruction(s):} @code{vqadd.s8 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint64x1_t vqadd_u64 (uint64x1_t, uint64x1_t) +@*@emph{Form of expected instruction(s):} @code{vqadd.u64 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int64x1_t vqadd_s64 (int64x1_t, int64x1_t) +@*@emph{Form of expected instruction(s):} @code{vqadd.s64 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint32x4_t vqaddq_u32 (uint32x4_t, uint32x4_t) +@*@emph{Form of expected instruction(s):} @code{vqadd.u32 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint16x8_t vqaddq_u16 (uint16x8_t, uint16x8_t) +@*@emph{Form of expected instruction(s):} @code{vqadd.u16 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint8x16_t vqaddq_u8 (uint8x16_t, uint8x16_t) +@*@emph{Form of expected instruction(s):} @code{vqadd.u8 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int32x4_t vqaddq_s32 (int32x4_t, int32x4_t) +@*@emph{Form of expected instruction(s):} @code{vqadd.s32 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int16x8_t vqaddq_s16 (int16x8_t, int16x8_t) +@*@emph{Form of expected instruction(s):} @code{vqadd.s16 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int8x16_t vqaddq_s8 (int8x16_t, int8x16_t) +@*@emph{Form of expected instruction(s):} @code{vqadd.s8 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint64x2_t vqaddq_u64 (uint64x2_t, uint64x2_t) +@*@emph{Form of expected instruction(s):} @code{vqadd.u64 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int64x2_t vqaddq_s64 (int64x2_t, int64x2_t) +@*@emph{Form of expected instruction(s):} @code{vqadd.s64 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint32x2_t vaddhn_u64 (uint64x2_t, uint64x2_t) +@*@emph{Form of expected instruction(s):} @code{vaddhn.i64 @var{d0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint16x4_t vaddhn_u32 (uint32x4_t, uint32x4_t) +@*@emph{Form of expected instruction(s):} @code{vaddhn.i32 @var{d0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint8x8_t vaddhn_u16 (uint16x8_t, uint16x8_t) +@*@emph{Form of expected instruction(s):} @code{vaddhn.i16 @var{d0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int32x2_t vaddhn_s64 (int64x2_t, int64x2_t) +@*@emph{Form of expected instruction(s):} @code{vaddhn.i64 @var{d0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int16x4_t vaddhn_s32 (int32x4_t, int32x4_t) +@*@emph{Form of expected instruction(s):} @code{vaddhn.i32 @var{d0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int8x8_t vaddhn_s16 (int16x8_t, int16x8_t) +@*@emph{Form of expected instruction(s):} @code{vaddhn.i16 @var{d0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint32x2_t vraddhn_u64 (uint64x2_t, uint64x2_t) +@*@emph{Form of expected instruction(s):} @code{vraddhn.i64 @var{d0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint16x4_t vraddhn_u32 (uint32x4_t, uint32x4_t) +@*@emph{Form of expected instruction(s):} @code{vraddhn.i32 @var{d0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint8x8_t vraddhn_u16 (uint16x8_t, uint16x8_t) +@*@emph{Form of expected instruction(s):} @code{vraddhn.i16 @var{d0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int32x2_t vraddhn_s64 (int64x2_t, int64x2_t) +@*@emph{Form of expected instruction(s):} @code{vraddhn.i64 @var{d0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int16x4_t vraddhn_s32 (int32x4_t, int32x4_t) +@*@emph{Form of expected instruction(s):} @code{vraddhn.i32 @var{d0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int8x8_t vraddhn_s16 (int16x8_t, int16x8_t) +@*@emph{Form of expected instruction(s):} @code{vraddhn.i16 @var{d0}, @var{q0}, @var{q0}} +@end itemize + + + + +@subsubsection Multiplication + +@itemize @bullet +@item uint32x2_t vmul_u32 (uint32x2_t, uint32x2_t) +@*@emph{Form of expected instruction(s):} @code{vmul.i32 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint16x4_t vmul_u16 (uint16x4_t, uint16x4_t) +@*@emph{Form of expected instruction(s):} @code{vmul.i16 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint8x8_t vmul_u8 (uint8x8_t, uint8x8_t) +@*@emph{Form of expected instruction(s):} @code{vmul.i8 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int32x2_t vmul_s32 (int32x2_t, int32x2_t) +@*@emph{Form of expected instruction(s):} @code{vmul.i32 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int16x4_t vmul_s16 (int16x4_t, int16x4_t) +@*@emph{Form of expected instruction(s):} @code{vmul.i16 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int8x8_t vmul_s8 (int8x8_t, int8x8_t) +@*@emph{Form of expected instruction(s):} @code{vmul.i8 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item float32x2_t vmul_f32 (float32x2_t, float32x2_t) +@*@emph{Form of expected instruction(s):} @code{vmul.f32 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item poly8x8_t vmul_p8 (poly8x8_t, poly8x8_t) +@*@emph{Form of expected instruction(s):} @code{vmul.p8 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint32x4_t vmulq_u32 (uint32x4_t, uint32x4_t) +@*@emph{Form of expected instruction(s):} @code{vmul.i32 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint16x8_t vmulq_u16 (uint16x8_t, uint16x8_t) +@*@emph{Form of expected instruction(s):} @code{vmul.i16 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint8x16_t vmulq_u8 (uint8x16_t, uint8x16_t) +@*@emph{Form of expected instruction(s):} @code{vmul.i8 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int32x4_t vmulq_s32 (int32x4_t, int32x4_t) +@*@emph{Form of expected instruction(s):} @code{vmul.i32 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int16x8_t vmulq_s16 (int16x8_t, int16x8_t) +@*@emph{Form of expected instruction(s):} @code{vmul.i16 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int8x16_t vmulq_s8 (int8x16_t, int8x16_t) +@*@emph{Form of expected instruction(s):} @code{vmul.i8 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item float32x4_t vmulq_f32 (float32x4_t, float32x4_t) +@*@emph{Form of expected instruction(s):} @code{vmul.f32 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item poly8x16_t vmulq_p8 (poly8x16_t, poly8x16_t) +@*@emph{Form of expected instruction(s):} @code{vmul.p8 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int32x2_t vqdmulh_s32 (int32x2_t, int32x2_t) +@*@emph{Form of expected instruction(s):} @code{vqdmulh.s32 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int16x4_t vqdmulh_s16 (int16x4_t, int16x4_t) +@*@emph{Form of expected instruction(s):} @code{vqdmulh.s16 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int32x4_t vqdmulhq_s32 (int32x4_t, int32x4_t) +@*@emph{Form of expected instruction(s):} @code{vqdmulh.s32 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int16x8_t vqdmulhq_s16 (int16x8_t, int16x8_t) +@*@emph{Form of expected instruction(s):} @code{vqdmulh.s16 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int32x2_t vqrdmulh_s32 (int32x2_t, int32x2_t) +@*@emph{Form of expected instruction(s):} @code{vqrdmulh.s32 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int16x4_t vqrdmulh_s16 (int16x4_t, int16x4_t) +@*@emph{Form of expected instruction(s):} @code{vqrdmulh.s16 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int32x4_t vqrdmulhq_s32 (int32x4_t, int32x4_t) +@*@emph{Form of expected instruction(s):} @code{vqrdmulh.s32 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int16x8_t vqrdmulhq_s16 (int16x8_t, int16x8_t) +@*@emph{Form of expected instruction(s):} @code{vqrdmulh.s16 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint64x2_t vmull_u32 (uint32x2_t, uint32x2_t) +@*@emph{Form of expected instruction(s):} @code{vmull.u32 @var{q0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint32x4_t vmull_u16 (uint16x4_t, uint16x4_t) +@*@emph{Form of expected instruction(s):} @code{vmull.u16 @var{q0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint16x8_t vmull_u8 (uint8x8_t, uint8x8_t) +@*@emph{Form of expected instruction(s):} @code{vmull.u8 @var{q0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int64x2_t vmull_s32 (int32x2_t, int32x2_t) +@*@emph{Form of expected instruction(s):} @code{vmull.s32 @var{q0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int32x4_t vmull_s16 (int16x4_t, int16x4_t) +@*@emph{Form of expected instruction(s):} @code{vmull.s16 @var{q0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int16x8_t vmull_s8 (int8x8_t, int8x8_t) +@*@emph{Form of expected instruction(s):} @code{vmull.s8 @var{q0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item poly16x8_t vmull_p8 (poly8x8_t, poly8x8_t) +@*@emph{Form of expected instruction(s):} @code{vmull.p8 @var{q0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int64x2_t vqdmull_s32 (int32x2_t, int32x2_t) +@*@emph{Form of expected instruction(s):} @code{vqdmull.s32 @var{q0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int32x4_t vqdmull_s16 (int16x4_t, int16x4_t) +@*@emph{Form of expected instruction(s):} @code{vqdmull.s16 @var{q0}, @var{d0}, @var{d0}} +@end itemize + + + + +@subsubsection Multiply-accumulate + +@itemize @bullet +@item uint32x2_t vmla_u32 (uint32x2_t, uint32x2_t, uint32x2_t) +@*@emph{Form of expected instruction(s):} @code{vmla.i32 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint16x4_t vmla_u16 (uint16x4_t, uint16x4_t, uint16x4_t) +@*@emph{Form of expected instruction(s):} @code{vmla.i16 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint8x8_t vmla_u8 (uint8x8_t, uint8x8_t, uint8x8_t) +@*@emph{Form of expected instruction(s):} @code{vmla.i8 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int32x2_t vmla_s32 (int32x2_t, int32x2_t, int32x2_t) +@*@emph{Form of expected instruction(s):} @code{vmla.i32 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int16x4_t vmla_s16 (int16x4_t, int16x4_t, int16x4_t) +@*@emph{Form of expected instruction(s):} @code{vmla.i16 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int8x8_t vmla_s8 (int8x8_t, int8x8_t, int8x8_t) +@*@emph{Form of expected instruction(s):} @code{vmla.i8 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item float32x2_t vmla_f32 (float32x2_t, float32x2_t, float32x2_t) +@*@emph{Form of expected instruction(s):} @code{vmla.f32 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint32x4_t vmlaq_u32 (uint32x4_t, uint32x4_t, uint32x4_t) +@*@emph{Form of expected instruction(s):} @code{vmla.i32 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint16x8_t vmlaq_u16 (uint16x8_t, uint16x8_t, uint16x8_t) +@*@emph{Form of expected instruction(s):} @code{vmla.i16 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint8x16_t vmlaq_u8 (uint8x16_t, uint8x16_t, uint8x16_t) +@*@emph{Form of expected instruction(s):} @code{vmla.i8 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int32x4_t vmlaq_s32 (int32x4_t, int32x4_t, int32x4_t) +@*@emph{Form of expected instruction(s):} @code{vmla.i32 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int16x8_t vmlaq_s16 (int16x8_t, int16x8_t, int16x8_t) +@*@emph{Form of expected instruction(s):} @code{vmla.i16 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int8x16_t vmlaq_s8 (int8x16_t, int8x16_t, int8x16_t) +@*@emph{Form of expected instruction(s):} @code{vmla.i8 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item float32x4_t vmlaq_f32 (float32x4_t, float32x4_t, float32x4_t) +@*@emph{Form of expected instruction(s):} @code{vmla.f32 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint64x2_t vmlal_u32 (uint64x2_t, uint32x2_t, uint32x2_t) +@*@emph{Form of expected instruction(s):} @code{vmlal.u32 @var{q0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint32x4_t vmlal_u16 (uint32x4_t, uint16x4_t, uint16x4_t) +@*@emph{Form of expected instruction(s):} @code{vmlal.u16 @var{q0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint16x8_t vmlal_u8 (uint16x8_t, uint8x8_t, uint8x8_t) +@*@emph{Form of expected instruction(s):} @code{vmlal.u8 @var{q0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int64x2_t vmlal_s32 (int64x2_t, int32x2_t, int32x2_t) +@*@emph{Form of expected instruction(s):} @code{vmlal.s32 @var{q0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int32x4_t vmlal_s16 (int32x4_t, int16x4_t, int16x4_t) +@*@emph{Form of expected instruction(s):} @code{vmlal.s16 @var{q0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int16x8_t vmlal_s8 (int16x8_t, int8x8_t, int8x8_t) +@*@emph{Form of expected instruction(s):} @code{vmlal.s8 @var{q0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int64x2_t vqdmlal_s32 (int64x2_t, int32x2_t, int32x2_t) +@*@emph{Form of expected instruction(s):} @code{vqdmlal.s32 @var{q0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int32x4_t vqdmlal_s16 (int32x4_t, int16x4_t, int16x4_t) +@*@emph{Form of expected instruction(s):} @code{vqdmlal.s16 @var{q0}, @var{d0}, @var{d0}} +@end itemize + + + + +@subsubsection Multiply-subtract + +@itemize @bullet +@item uint32x2_t vmls_u32 (uint32x2_t, uint32x2_t, uint32x2_t) +@*@emph{Form of expected instruction(s):} @code{vmls.i32 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint16x4_t vmls_u16 (uint16x4_t, uint16x4_t, uint16x4_t) +@*@emph{Form of expected instruction(s):} @code{vmls.i16 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint8x8_t vmls_u8 (uint8x8_t, uint8x8_t, uint8x8_t) +@*@emph{Form of expected instruction(s):} @code{vmls.i8 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int32x2_t vmls_s32 (int32x2_t, int32x2_t, int32x2_t) +@*@emph{Form of expected instruction(s):} @code{vmls.i32 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int16x4_t vmls_s16 (int16x4_t, int16x4_t, int16x4_t) +@*@emph{Form of expected instruction(s):} @code{vmls.i16 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int8x8_t vmls_s8 (int8x8_t, int8x8_t, int8x8_t) +@*@emph{Form of expected instruction(s):} @code{vmls.i8 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item float32x2_t vmls_f32 (float32x2_t, float32x2_t, float32x2_t) +@*@emph{Form of expected instruction(s):} @code{vmls.f32 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint32x4_t vmlsq_u32 (uint32x4_t, uint32x4_t, uint32x4_t) +@*@emph{Form of expected instruction(s):} @code{vmls.i32 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint16x8_t vmlsq_u16 (uint16x8_t, uint16x8_t, uint16x8_t) +@*@emph{Form of expected instruction(s):} @code{vmls.i16 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint8x16_t vmlsq_u8 (uint8x16_t, uint8x16_t, uint8x16_t) +@*@emph{Form of expected instruction(s):} @code{vmls.i8 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int32x4_t vmlsq_s32 (int32x4_t, int32x4_t, int32x4_t) +@*@emph{Form of expected instruction(s):} @code{vmls.i32 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int16x8_t vmlsq_s16 (int16x8_t, int16x8_t, int16x8_t) +@*@emph{Form of expected instruction(s):} @code{vmls.i16 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int8x16_t vmlsq_s8 (int8x16_t, int8x16_t, int8x16_t) +@*@emph{Form of expected instruction(s):} @code{vmls.i8 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item float32x4_t vmlsq_f32 (float32x4_t, float32x4_t, float32x4_t) +@*@emph{Form of expected instruction(s):} @code{vmls.f32 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint64x2_t vmlsl_u32 (uint64x2_t, uint32x2_t, uint32x2_t) +@*@emph{Form of expected instruction(s):} @code{vmlsl.u32 @var{q0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint32x4_t vmlsl_u16 (uint32x4_t, uint16x4_t, uint16x4_t) +@*@emph{Form of expected instruction(s):} @code{vmlsl.u16 @var{q0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint16x8_t vmlsl_u8 (uint16x8_t, uint8x8_t, uint8x8_t) +@*@emph{Form of expected instruction(s):} @code{vmlsl.u8 @var{q0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int64x2_t vmlsl_s32 (int64x2_t, int32x2_t, int32x2_t) +@*@emph{Form of expected instruction(s):} @code{vmlsl.s32 @var{q0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int32x4_t vmlsl_s16 (int32x4_t, int16x4_t, int16x4_t) +@*@emph{Form of expected instruction(s):} @code{vmlsl.s16 @var{q0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int16x8_t vmlsl_s8 (int16x8_t, int8x8_t, int8x8_t) +@*@emph{Form of expected instruction(s):} @code{vmlsl.s8 @var{q0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int64x2_t vqdmlsl_s32 (int64x2_t, int32x2_t, int32x2_t) +@*@emph{Form of expected instruction(s):} @code{vqdmlsl.s32 @var{q0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int32x4_t vqdmlsl_s16 (int32x4_t, int16x4_t, int16x4_t) +@*@emph{Form of expected instruction(s):} @code{vqdmlsl.s16 @var{q0}, @var{d0}, @var{d0}} +@end itemize + + + + +@subsubsection Subtraction + +@itemize @bullet +@item uint32x2_t vsub_u32 (uint32x2_t, uint32x2_t) +@*@emph{Form of expected instruction(s):} @code{vsub.i32 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint16x4_t vsub_u16 (uint16x4_t, uint16x4_t) +@*@emph{Form of expected instruction(s):} @code{vsub.i16 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint8x8_t vsub_u8 (uint8x8_t, uint8x8_t) +@*@emph{Form of expected instruction(s):} @code{vsub.i8 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int32x2_t vsub_s32 (int32x2_t, int32x2_t) +@*@emph{Form of expected instruction(s):} @code{vsub.i32 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int16x4_t vsub_s16 (int16x4_t, int16x4_t) +@*@emph{Form of expected instruction(s):} @code{vsub.i16 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int8x8_t vsub_s8 (int8x8_t, int8x8_t) +@*@emph{Form of expected instruction(s):} @code{vsub.i8 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item float32x2_t vsub_f32 (float32x2_t, float32x2_t) +@*@emph{Form of expected instruction(s):} @code{vsub.f32 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint64x1_t vsub_u64 (uint64x1_t, uint64x1_t) +@end itemize + + +@itemize @bullet +@item int64x1_t vsub_s64 (int64x1_t, int64x1_t) +@end itemize + + +@itemize @bullet +@item uint32x4_t vsubq_u32 (uint32x4_t, uint32x4_t) +@*@emph{Form of expected instruction(s):} @code{vsub.i32 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint16x8_t vsubq_u16 (uint16x8_t, uint16x8_t) +@*@emph{Form of expected instruction(s):} @code{vsub.i16 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint8x16_t vsubq_u8 (uint8x16_t, uint8x16_t) +@*@emph{Form of expected instruction(s):} @code{vsub.i8 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int32x4_t vsubq_s32 (int32x4_t, int32x4_t) +@*@emph{Form of expected instruction(s):} @code{vsub.i32 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int16x8_t vsubq_s16 (int16x8_t, int16x8_t) +@*@emph{Form of expected instruction(s):} @code{vsub.i16 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int8x16_t vsubq_s8 (int8x16_t, int8x16_t) +@*@emph{Form of expected instruction(s):} @code{vsub.i8 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint64x2_t vsubq_u64 (uint64x2_t, uint64x2_t) +@*@emph{Form of expected instruction(s):} @code{vsub.i64 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int64x2_t vsubq_s64 (int64x2_t, int64x2_t) +@*@emph{Form of expected instruction(s):} @code{vsub.i64 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item float32x4_t vsubq_f32 (float32x4_t, float32x4_t) +@*@emph{Form of expected instruction(s):} @code{vsub.f32 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint64x2_t vsubl_u32 (uint32x2_t, uint32x2_t) +@*@emph{Form of expected instruction(s):} @code{vsubl.u32 @var{q0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint32x4_t vsubl_u16 (uint16x4_t, uint16x4_t) +@*@emph{Form of expected instruction(s):} @code{vsubl.u16 @var{q0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint16x8_t vsubl_u8 (uint8x8_t, uint8x8_t) +@*@emph{Form of expected instruction(s):} @code{vsubl.u8 @var{q0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int64x2_t vsubl_s32 (int32x2_t, int32x2_t) +@*@emph{Form of expected instruction(s):} @code{vsubl.s32 @var{q0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int32x4_t vsubl_s16 (int16x4_t, int16x4_t) +@*@emph{Form of expected instruction(s):} @code{vsubl.s16 @var{q0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int16x8_t vsubl_s8 (int8x8_t, int8x8_t) +@*@emph{Form of expected instruction(s):} @code{vsubl.s8 @var{q0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint64x2_t vsubw_u32 (uint64x2_t, uint32x2_t) +@*@emph{Form of expected instruction(s):} @code{vsubw.u32 @var{q0}, @var{q0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint32x4_t vsubw_u16 (uint32x4_t, uint16x4_t) +@*@emph{Form of expected instruction(s):} @code{vsubw.u16 @var{q0}, @var{q0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint16x8_t vsubw_u8 (uint16x8_t, uint8x8_t) +@*@emph{Form of expected instruction(s):} @code{vsubw.u8 @var{q0}, @var{q0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int64x2_t vsubw_s32 (int64x2_t, int32x2_t) +@*@emph{Form of expected instruction(s):} @code{vsubw.s32 @var{q0}, @var{q0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int32x4_t vsubw_s16 (int32x4_t, int16x4_t) +@*@emph{Form of expected instruction(s):} @code{vsubw.s16 @var{q0}, @var{q0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int16x8_t vsubw_s8 (int16x8_t, int8x8_t) +@*@emph{Form of expected instruction(s):} @code{vsubw.s8 @var{q0}, @var{q0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint32x2_t vhsub_u32 (uint32x2_t, uint32x2_t) +@*@emph{Form of expected instruction(s):} @code{vhsub.u32 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint16x4_t vhsub_u16 (uint16x4_t, uint16x4_t) +@*@emph{Form of expected instruction(s):} @code{vhsub.u16 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint8x8_t vhsub_u8 (uint8x8_t, uint8x8_t) +@*@emph{Form of expected instruction(s):} @code{vhsub.u8 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int32x2_t vhsub_s32 (int32x2_t, int32x2_t) +@*@emph{Form of expected instruction(s):} @code{vhsub.s32 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int16x4_t vhsub_s16 (int16x4_t, int16x4_t) +@*@emph{Form of expected instruction(s):} @code{vhsub.s16 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int8x8_t vhsub_s8 (int8x8_t, int8x8_t) +@*@emph{Form of expected instruction(s):} @code{vhsub.s8 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint32x4_t vhsubq_u32 (uint32x4_t, uint32x4_t) +@*@emph{Form of expected instruction(s):} @code{vhsub.u32 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint16x8_t vhsubq_u16 (uint16x8_t, uint16x8_t) +@*@emph{Form of expected instruction(s):} @code{vhsub.u16 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint8x16_t vhsubq_u8 (uint8x16_t, uint8x16_t) +@*@emph{Form of expected instruction(s):} @code{vhsub.u8 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int32x4_t vhsubq_s32 (int32x4_t, int32x4_t) +@*@emph{Form of expected instruction(s):} @code{vhsub.s32 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int16x8_t vhsubq_s16 (int16x8_t, int16x8_t) +@*@emph{Form of expected instruction(s):} @code{vhsub.s16 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int8x16_t vhsubq_s8 (int8x16_t, int8x16_t) +@*@emph{Form of expected instruction(s):} @code{vhsub.s8 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint32x2_t vqsub_u32 (uint32x2_t, uint32x2_t) +@*@emph{Form of expected instruction(s):} @code{vqsub.u32 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint16x4_t vqsub_u16 (uint16x4_t, uint16x4_t) +@*@emph{Form of expected instruction(s):} @code{vqsub.u16 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint8x8_t vqsub_u8 (uint8x8_t, uint8x8_t) +@*@emph{Form of expected instruction(s):} @code{vqsub.u8 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int32x2_t vqsub_s32 (int32x2_t, int32x2_t) +@*@emph{Form of expected instruction(s):} @code{vqsub.s32 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int16x4_t vqsub_s16 (int16x4_t, int16x4_t) +@*@emph{Form of expected instruction(s):} @code{vqsub.s16 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int8x8_t vqsub_s8 (int8x8_t, int8x8_t) +@*@emph{Form of expected instruction(s):} @code{vqsub.s8 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint64x1_t vqsub_u64 (uint64x1_t, uint64x1_t) +@*@emph{Form of expected instruction(s):} @code{vqsub.u64 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int64x1_t vqsub_s64 (int64x1_t, int64x1_t) +@*@emph{Form of expected instruction(s):} @code{vqsub.s64 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint32x4_t vqsubq_u32 (uint32x4_t, uint32x4_t) +@*@emph{Form of expected instruction(s):} @code{vqsub.u32 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint16x8_t vqsubq_u16 (uint16x8_t, uint16x8_t) +@*@emph{Form of expected instruction(s):} @code{vqsub.u16 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint8x16_t vqsubq_u8 (uint8x16_t, uint8x16_t) +@*@emph{Form of expected instruction(s):} @code{vqsub.u8 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int32x4_t vqsubq_s32 (int32x4_t, int32x4_t) +@*@emph{Form of expected instruction(s):} @code{vqsub.s32 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int16x8_t vqsubq_s16 (int16x8_t, int16x8_t) +@*@emph{Form of expected instruction(s):} @code{vqsub.s16 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int8x16_t vqsubq_s8 (int8x16_t, int8x16_t) +@*@emph{Form of expected instruction(s):} @code{vqsub.s8 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint64x2_t vqsubq_u64 (uint64x2_t, uint64x2_t) +@*@emph{Form of expected instruction(s):} @code{vqsub.u64 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int64x2_t vqsubq_s64 (int64x2_t, int64x2_t) +@*@emph{Form of expected instruction(s):} @code{vqsub.s64 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint32x2_t vsubhn_u64 (uint64x2_t, uint64x2_t) +@*@emph{Form of expected instruction(s):} @code{vsubhn.i64 @var{d0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint16x4_t vsubhn_u32 (uint32x4_t, uint32x4_t) +@*@emph{Form of expected instruction(s):} @code{vsubhn.i32 @var{d0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint8x8_t vsubhn_u16 (uint16x8_t, uint16x8_t) +@*@emph{Form of expected instruction(s):} @code{vsubhn.i16 @var{d0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int32x2_t vsubhn_s64 (int64x2_t, int64x2_t) +@*@emph{Form of expected instruction(s):} @code{vsubhn.i64 @var{d0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int16x4_t vsubhn_s32 (int32x4_t, int32x4_t) +@*@emph{Form of expected instruction(s):} @code{vsubhn.i32 @var{d0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int8x8_t vsubhn_s16 (int16x8_t, int16x8_t) +@*@emph{Form of expected instruction(s):} @code{vsubhn.i16 @var{d0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint32x2_t vrsubhn_u64 (uint64x2_t, uint64x2_t) +@*@emph{Form of expected instruction(s):} @code{vrsubhn.i64 @var{d0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint16x4_t vrsubhn_u32 (uint32x4_t, uint32x4_t) +@*@emph{Form of expected instruction(s):} @code{vrsubhn.i32 @var{d0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint8x8_t vrsubhn_u16 (uint16x8_t, uint16x8_t) +@*@emph{Form of expected instruction(s):} @code{vrsubhn.i16 @var{d0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int32x2_t vrsubhn_s64 (int64x2_t, int64x2_t) +@*@emph{Form of expected instruction(s):} @code{vrsubhn.i64 @var{d0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int16x4_t vrsubhn_s32 (int32x4_t, int32x4_t) +@*@emph{Form of expected instruction(s):} @code{vrsubhn.i32 @var{d0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int8x8_t vrsubhn_s16 (int16x8_t, int16x8_t) +@*@emph{Form of expected instruction(s):} @code{vrsubhn.i16 @var{d0}, @var{q0}, @var{q0}} +@end itemize + + + + +@subsubsection Comparison (equal-to) + +@itemize @bullet +@item uint32x2_t vceq_u32 (uint32x2_t, uint32x2_t) +@*@emph{Form of expected instruction(s):} @code{vceq.i32 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint16x4_t vceq_u16 (uint16x4_t, uint16x4_t) +@*@emph{Form of expected instruction(s):} @code{vceq.i16 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint8x8_t vceq_u8 (uint8x8_t, uint8x8_t) +@*@emph{Form of expected instruction(s):} @code{vceq.i8 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint32x2_t vceq_s32 (int32x2_t, int32x2_t) +@*@emph{Form of expected instruction(s):} @code{vceq.i32 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint16x4_t vceq_s16 (int16x4_t, int16x4_t) +@*@emph{Form of expected instruction(s):} @code{vceq.i16 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint8x8_t vceq_s8 (int8x8_t, int8x8_t) +@*@emph{Form of expected instruction(s):} @code{vceq.i8 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint32x2_t vceq_f32 (float32x2_t, float32x2_t) +@*@emph{Form of expected instruction(s):} @code{vceq.f32 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint8x8_t vceq_p8 (poly8x8_t, poly8x8_t) +@*@emph{Form of expected instruction(s):} @code{vceq.i8 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint32x4_t vceqq_u32 (uint32x4_t, uint32x4_t) +@*@emph{Form of expected instruction(s):} @code{vceq.i32 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint16x8_t vceqq_u16 (uint16x8_t, uint16x8_t) +@*@emph{Form of expected instruction(s):} @code{vceq.i16 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint8x16_t vceqq_u8 (uint8x16_t, uint8x16_t) +@*@emph{Form of expected instruction(s):} @code{vceq.i8 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint32x4_t vceqq_s32 (int32x4_t, int32x4_t) +@*@emph{Form of expected instruction(s):} @code{vceq.i32 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint16x8_t vceqq_s16 (int16x8_t, int16x8_t) +@*@emph{Form of expected instruction(s):} @code{vceq.i16 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint8x16_t vceqq_s8 (int8x16_t, int8x16_t) +@*@emph{Form of expected instruction(s):} @code{vceq.i8 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint32x4_t vceqq_f32 (float32x4_t, float32x4_t) +@*@emph{Form of expected instruction(s):} @code{vceq.f32 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint8x16_t vceqq_p8 (poly8x16_t, poly8x16_t) +@*@emph{Form of expected instruction(s):} @code{vceq.i8 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + + + +@subsubsection Comparison (greater-than-or-equal-to) + +@itemize @bullet +@item uint32x2_t vcge_u32 (uint32x2_t, uint32x2_t) +@*@emph{Form of expected instruction(s):} @code{vcge.u32 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint16x4_t vcge_u16 (uint16x4_t, uint16x4_t) +@*@emph{Form of expected instruction(s):} @code{vcge.u16 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint8x8_t vcge_u8 (uint8x8_t, uint8x8_t) +@*@emph{Form of expected instruction(s):} @code{vcge.u8 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint32x2_t vcge_s32 (int32x2_t, int32x2_t) +@*@emph{Form of expected instruction(s):} @code{vcge.s32 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint16x4_t vcge_s16 (int16x4_t, int16x4_t) +@*@emph{Form of expected instruction(s):} @code{vcge.s16 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint8x8_t vcge_s8 (int8x8_t, int8x8_t) +@*@emph{Form of expected instruction(s):} @code{vcge.s8 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint32x2_t vcge_f32 (float32x2_t, float32x2_t) +@*@emph{Form of expected instruction(s):} @code{vcge.f32 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint32x4_t vcgeq_u32 (uint32x4_t, uint32x4_t) +@*@emph{Form of expected instruction(s):} @code{vcge.u32 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint16x8_t vcgeq_u16 (uint16x8_t, uint16x8_t) +@*@emph{Form of expected instruction(s):} @code{vcge.u16 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint8x16_t vcgeq_u8 (uint8x16_t, uint8x16_t) +@*@emph{Form of expected instruction(s):} @code{vcge.u8 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint32x4_t vcgeq_s32 (int32x4_t, int32x4_t) +@*@emph{Form of expected instruction(s):} @code{vcge.s32 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint16x8_t vcgeq_s16 (int16x8_t, int16x8_t) +@*@emph{Form of expected instruction(s):} @code{vcge.s16 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint8x16_t vcgeq_s8 (int8x16_t, int8x16_t) +@*@emph{Form of expected instruction(s):} @code{vcge.s8 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint32x4_t vcgeq_f32 (float32x4_t, float32x4_t) +@*@emph{Form of expected instruction(s):} @code{vcge.f32 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + + + +@subsubsection Comparison (less-than-or-equal-to) + +@itemize @bullet +@item uint32x2_t vcle_u32 (uint32x2_t, uint32x2_t) +@*@emph{Form of expected instruction(s):} @code{vcge.u32 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint16x4_t vcle_u16 (uint16x4_t, uint16x4_t) +@*@emph{Form of expected instruction(s):} @code{vcge.u16 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint8x8_t vcle_u8 (uint8x8_t, uint8x8_t) +@*@emph{Form of expected instruction(s):} @code{vcge.u8 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint32x2_t vcle_s32 (int32x2_t, int32x2_t) +@*@emph{Form of expected instruction(s):} @code{vcge.s32 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint16x4_t vcle_s16 (int16x4_t, int16x4_t) +@*@emph{Form of expected instruction(s):} @code{vcge.s16 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint8x8_t vcle_s8 (int8x8_t, int8x8_t) +@*@emph{Form of expected instruction(s):} @code{vcge.s8 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint32x2_t vcle_f32 (float32x2_t, float32x2_t) +@*@emph{Form of expected instruction(s):} @code{vcge.f32 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint32x4_t vcleq_u32 (uint32x4_t, uint32x4_t) +@*@emph{Form of expected instruction(s):} @code{vcge.u32 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint16x8_t vcleq_u16 (uint16x8_t, uint16x8_t) +@*@emph{Form of expected instruction(s):} @code{vcge.u16 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint8x16_t vcleq_u8 (uint8x16_t, uint8x16_t) +@*@emph{Form of expected instruction(s):} @code{vcge.u8 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint32x4_t vcleq_s32 (int32x4_t, int32x4_t) +@*@emph{Form of expected instruction(s):} @code{vcge.s32 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint16x8_t vcleq_s16 (int16x8_t, int16x8_t) +@*@emph{Form of expected instruction(s):} @code{vcge.s16 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint8x16_t vcleq_s8 (int8x16_t, int8x16_t) +@*@emph{Form of expected instruction(s):} @code{vcge.s8 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint32x4_t vcleq_f32 (float32x4_t, float32x4_t) +@*@emph{Form of expected instruction(s):} @code{vcge.f32 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + + + +@subsubsection Comparison (greater-than) + +@itemize @bullet +@item uint32x2_t vcgt_u32 (uint32x2_t, uint32x2_t) +@*@emph{Form of expected instruction(s):} @code{vcgt.u32 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint16x4_t vcgt_u16 (uint16x4_t, uint16x4_t) +@*@emph{Form of expected instruction(s):} @code{vcgt.u16 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint8x8_t vcgt_u8 (uint8x8_t, uint8x8_t) +@*@emph{Form of expected instruction(s):} @code{vcgt.u8 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint32x2_t vcgt_s32 (int32x2_t, int32x2_t) +@*@emph{Form of expected instruction(s):} @code{vcgt.s32 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint16x4_t vcgt_s16 (int16x4_t, int16x4_t) +@*@emph{Form of expected instruction(s):} @code{vcgt.s16 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint8x8_t vcgt_s8 (int8x8_t, int8x8_t) +@*@emph{Form of expected instruction(s):} @code{vcgt.s8 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint32x2_t vcgt_f32 (float32x2_t, float32x2_t) +@*@emph{Form of expected instruction(s):} @code{vcgt.f32 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint32x4_t vcgtq_u32 (uint32x4_t, uint32x4_t) +@*@emph{Form of expected instruction(s):} @code{vcgt.u32 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint16x8_t vcgtq_u16 (uint16x8_t, uint16x8_t) +@*@emph{Form of expected instruction(s):} @code{vcgt.u16 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint8x16_t vcgtq_u8 (uint8x16_t, uint8x16_t) +@*@emph{Form of expected instruction(s):} @code{vcgt.u8 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint32x4_t vcgtq_s32 (int32x4_t, int32x4_t) +@*@emph{Form of expected instruction(s):} @code{vcgt.s32 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint16x8_t vcgtq_s16 (int16x8_t, int16x8_t) +@*@emph{Form of expected instruction(s):} @code{vcgt.s16 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint8x16_t vcgtq_s8 (int8x16_t, int8x16_t) +@*@emph{Form of expected instruction(s):} @code{vcgt.s8 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint32x4_t vcgtq_f32 (float32x4_t, float32x4_t) +@*@emph{Form of expected instruction(s):} @code{vcgt.f32 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + + + +@subsubsection Comparison (less-than) + +@itemize @bullet +@item uint32x2_t vclt_u32 (uint32x2_t, uint32x2_t) +@*@emph{Form of expected instruction(s):} @code{vcgt.u32 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint16x4_t vclt_u16 (uint16x4_t, uint16x4_t) +@*@emph{Form of expected instruction(s):} @code{vcgt.u16 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint8x8_t vclt_u8 (uint8x8_t, uint8x8_t) +@*@emph{Form of expected instruction(s):} @code{vcgt.u8 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint32x2_t vclt_s32 (int32x2_t, int32x2_t) +@*@emph{Form of expected instruction(s):} @code{vcgt.s32 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint16x4_t vclt_s16 (int16x4_t, int16x4_t) +@*@emph{Form of expected instruction(s):} @code{vcgt.s16 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint8x8_t vclt_s8 (int8x8_t, int8x8_t) +@*@emph{Form of expected instruction(s):} @code{vcgt.s8 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint32x2_t vclt_f32 (float32x2_t, float32x2_t) +@*@emph{Form of expected instruction(s):} @code{vcgt.f32 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint32x4_t vcltq_u32 (uint32x4_t, uint32x4_t) +@*@emph{Form of expected instruction(s):} @code{vcgt.u32 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint16x8_t vcltq_u16 (uint16x8_t, uint16x8_t) +@*@emph{Form of expected instruction(s):} @code{vcgt.u16 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint8x16_t vcltq_u8 (uint8x16_t, uint8x16_t) +@*@emph{Form of expected instruction(s):} @code{vcgt.u8 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint32x4_t vcltq_s32 (int32x4_t, int32x4_t) +@*@emph{Form of expected instruction(s):} @code{vcgt.s32 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint16x8_t vcltq_s16 (int16x8_t, int16x8_t) +@*@emph{Form of expected instruction(s):} @code{vcgt.s16 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint8x16_t vcltq_s8 (int8x16_t, int8x16_t) +@*@emph{Form of expected instruction(s):} @code{vcgt.s8 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint32x4_t vcltq_f32 (float32x4_t, float32x4_t) +@*@emph{Form of expected instruction(s):} @code{vcgt.f32 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + + + +@subsubsection Comparison (absolute greater-than-or-equal-to) + +@itemize @bullet +@item uint32x2_t vcage_f32 (float32x2_t, float32x2_t) +@*@emph{Form of expected instruction(s):} @code{vacge.f32 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint32x4_t vcageq_f32 (float32x4_t, float32x4_t) +@*@emph{Form of expected instruction(s):} @code{vacge.f32 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + + + +@subsubsection Comparison (absolute less-than-or-equal-to) + +@itemize @bullet +@item uint32x2_t vcale_f32 (float32x2_t, float32x2_t) +@*@emph{Form of expected instruction(s):} @code{vacge.f32 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint32x4_t vcaleq_f32 (float32x4_t, float32x4_t) +@*@emph{Form of expected instruction(s):} @code{vacge.f32 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + + + +@subsubsection Comparison (absolute greater-than) + +@itemize @bullet +@item uint32x2_t vcagt_f32 (float32x2_t, float32x2_t) +@*@emph{Form of expected instruction(s):} @code{vacgt.f32 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint32x4_t vcagtq_f32 (float32x4_t, float32x4_t) +@*@emph{Form of expected instruction(s):} @code{vacgt.f32 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + + + +@subsubsection Comparison (absolute less-than) + +@itemize @bullet +@item uint32x2_t vcalt_f32 (float32x2_t, float32x2_t) +@*@emph{Form of expected instruction(s):} @code{vacgt.f32 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint32x4_t vcaltq_f32 (float32x4_t, float32x4_t) +@*@emph{Form of expected instruction(s):} @code{vacgt.f32 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + + + +@subsubsection Test bits + +@itemize @bullet +@item uint32x2_t vtst_u32 (uint32x2_t, uint32x2_t) +@*@emph{Form of expected instruction(s):} @code{vtst.32 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint16x4_t vtst_u16 (uint16x4_t, uint16x4_t) +@*@emph{Form of expected instruction(s):} @code{vtst.16 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint8x8_t vtst_u8 (uint8x8_t, uint8x8_t) +@*@emph{Form of expected instruction(s):} @code{vtst.8 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint32x2_t vtst_s32 (int32x2_t, int32x2_t) +@*@emph{Form of expected instruction(s):} @code{vtst.32 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint16x4_t vtst_s16 (int16x4_t, int16x4_t) +@*@emph{Form of expected instruction(s):} @code{vtst.16 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint8x8_t vtst_s8 (int8x8_t, int8x8_t) +@*@emph{Form of expected instruction(s):} @code{vtst.8 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint8x8_t vtst_p8 (poly8x8_t, poly8x8_t) +@*@emph{Form of expected instruction(s):} @code{vtst.8 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint32x4_t vtstq_u32 (uint32x4_t, uint32x4_t) +@*@emph{Form of expected instruction(s):} @code{vtst.32 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint16x8_t vtstq_u16 (uint16x8_t, uint16x8_t) +@*@emph{Form of expected instruction(s):} @code{vtst.16 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint8x16_t vtstq_u8 (uint8x16_t, uint8x16_t) +@*@emph{Form of expected instruction(s):} @code{vtst.8 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint32x4_t vtstq_s32 (int32x4_t, int32x4_t) +@*@emph{Form of expected instruction(s):} @code{vtst.32 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint16x8_t vtstq_s16 (int16x8_t, int16x8_t) +@*@emph{Form of expected instruction(s):} @code{vtst.16 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint8x16_t vtstq_s8 (int8x16_t, int8x16_t) +@*@emph{Form of expected instruction(s):} @code{vtst.8 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint8x16_t vtstq_p8 (poly8x16_t, poly8x16_t) +@*@emph{Form of expected instruction(s):} @code{vtst.8 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + + + +@subsubsection Absolute difference + +@itemize @bullet +@item uint32x2_t vabd_u32 (uint32x2_t, uint32x2_t) +@*@emph{Form of expected instruction(s):} @code{vabd.u32 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint16x4_t vabd_u16 (uint16x4_t, uint16x4_t) +@*@emph{Form of expected instruction(s):} @code{vabd.u16 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint8x8_t vabd_u8 (uint8x8_t, uint8x8_t) +@*@emph{Form of expected instruction(s):} @code{vabd.u8 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int32x2_t vabd_s32 (int32x2_t, int32x2_t) +@*@emph{Form of expected instruction(s):} @code{vabd.s32 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int16x4_t vabd_s16 (int16x4_t, int16x4_t) +@*@emph{Form of expected instruction(s):} @code{vabd.s16 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int8x8_t vabd_s8 (int8x8_t, int8x8_t) +@*@emph{Form of expected instruction(s):} @code{vabd.s8 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item float32x2_t vabd_f32 (float32x2_t, float32x2_t) +@*@emph{Form of expected instruction(s):} @code{vabd.f32 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint32x4_t vabdq_u32 (uint32x4_t, uint32x4_t) +@*@emph{Form of expected instruction(s):} @code{vabd.u32 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint16x8_t vabdq_u16 (uint16x8_t, uint16x8_t) +@*@emph{Form of expected instruction(s):} @code{vabd.u16 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint8x16_t vabdq_u8 (uint8x16_t, uint8x16_t) +@*@emph{Form of expected instruction(s):} @code{vabd.u8 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int32x4_t vabdq_s32 (int32x4_t, int32x4_t) +@*@emph{Form of expected instruction(s):} @code{vabd.s32 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int16x8_t vabdq_s16 (int16x8_t, int16x8_t) +@*@emph{Form of expected instruction(s):} @code{vabd.s16 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int8x16_t vabdq_s8 (int8x16_t, int8x16_t) +@*@emph{Form of expected instruction(s):} @code{vabd.s8 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item float32x4_t vabdq_f32 (float32x4_t, float32x4_t) +@*@emph{Form of expected instruction(s):} @code{vabd.f32 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint64x2_t vabdl_u32 (uint32x2_t, uint32x2_t) +@*@emph{Form of expected instruction(s):} @code{vabdl.u32 @var{q0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint32x4_t vabdl_u16 (uint16x4_t, uint16x4_t) +@*@emph{Form of expected instruction(s):} @code{vabdl.u16 @var{q0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint16x8_t vabdl_u8 (uint8x8_t, uint8x8_t) +@*@emph{Form of expected instruction(s):} @code{vabdl.u8 @var{q0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int64x2_t vabdl_s32 (int32x2_t, int32x2_t) +@*@emph{Form of expected instruction(s):} @code{vabdl.s32 @var{q0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int32x4_t vabdl_s16 (int16x4_t, int16x4_t) +@*@emph{Form of expected instruction(s):} @code{vabdl.s16 @var{q0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int16x8_t vabdl_s8 (int8x8_t, int8x8_t) +@*@emph{Form of expected instruction(s):} @code{vabdl.s8 @var{q0}, @var{d0}, @var{d0}} +@end itemize + + + + +@subsubsection Absolute difference and accumulate + +@itemize @bullet +@item uint32x2_t vaba_u32 (uint32x2_t, uint32x2_t, uint32x2_t) +@*@emph{Form of expected instruction(s):} @code{vaba.u32 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint16x4_t vaba_u16 (uint16x4_t, uint16x4_t, uint16x4_t) +@*@emph{Form of expected instruction(s):} @code{vaba.u16 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint8x8_t vaba_u8 (uint8x8_t, uint8x8_t, uint8x8_t) +@*@emph{Form of expected instruction(s):} @code{vaba.u8 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int32x2_t vaba_s32 (int32x2_t, int32x2_t, int32x2_t) +@*@emph{Form of expected instruction(s):} @code{vaba.s32 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int16x4_t vaba_s16 (int16x4_t, int16x4_t, int16x4_t) +@*@emph{Form of expected instruction(s):} @code{vaba.s16 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int8x8_t vaba_s8 (int8x8_t, int8x8_t, int8x8_t) +@*@emph{Form of expected instruction(s):} @code{vaba.s8 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint32x4_t vabaq_u32 (uint32x4_t, uint32x4_t, uint32x4_t) +@*@emph{Form of expected instruction(s):} @code{vaba.u32 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint16x8_t vabaq_u16 (uint16x8_t, uint16x8_t, uint16x8_t) +@*@emph{Form of expected instruction(s):} @code{vaba.u16 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint8x16_t vabaq_u8 (uint8x16_t, uint8x16_t, uint8x16_t) +@*@emph{Form of expected instruction(s):} @code{vaba.u8 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int32x4_t vabaq_s32 (int32x4_t, int32x4_t, int32x4_t) +@*@emph{Form of expected instruction(s):} @code{vaba.s32 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int16x8_t vabaq_s16 (int16x8_t, int16x8_t, int16x8_t) +@*@emph{Form of expected instruction(s):} @code{vaba.s16 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int8x16_t vabaq_s8 (int8x16_t, int8x16_t, int8x16_t) +@*@emph{Form of expected instruction(s):} @code{vaba.s8 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint64x2_t vabal_u32 (uint64x2_t, uint32x2_t, uint32x2_t) +@*@emph{Form of expected instruction(s):} @code{vabal.u32 @var{q0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint32x4_t vabal_u16 (uint32x4_t, uint16x4_t, uint16x4_t) +@*@emph{Form of expected instruction(s):} @code{vabal.u16 @var{q0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint16x8_t vabal_u8 (uint16x8_t, uint8x8_t, uint8x8_t) +@*@emph{Form of expected instruction(s):} @code{vabal.u8 @var{q0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int64x2_t vabal_s32 (int64x2_t, int32x2_t, int32x2_t) +@*@emph{Form of expected instruction(s):} @code{vabal.s32 @var{q0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int32x4_t vabal_s16 (int32x4_t, int16x4_t, int16x4_t) +@*@emph{Form of expected instruction(s):} @code{vabal.s16 @var{q0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int16x8_t vabal_s8 (int16x8_t, int8x8_t, int8x8_t) +@*@emph{Form of expected instruction(s):} @code{vabal.s8 @var{q0}, @var{d0}, @var{d0}} +@end itemize + + + + +@subsubsection Maximum + +@itemize @bullet +@item uint32x2_t vmax_u32 (uint32x2_t, uint32x2_t) +@*@emph{Form of expected instruction(s):} @code{vmax.u32 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint16x4_t vmax_u16 (uint16x4_t, uint16x4_t) +@*@emph{Form of expected instruction(s):} @code{vmax.u16 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint8x8_t vmax_u8 (uint8x8_t, uint8x8_t) +@*@emph{Form of expected instruction(s):} @code{vmax.u8 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int32x2_t vmax_s32 (int32x2_t, int32x2_t) +@*@emph{Form of expected instruction(s):} @code{vmax.s32 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int16x4_t vmax_s16 (int16x4_t, int16x4_t) +@*@emph{Form of expected instruction(s):} @code{vmax.s16 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int8x8_t vmax_s8 (int8x8_t, int8x8_t) +@*@emph{Form of expected instruction(s):} @code{vmax.s8 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item float32x2_t vmax_f32 (float32x2_t, float32x2_t) +@*@emph{Form of expected instruction(s):} @code{vmax.f32 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint32x4_t vmaxq_u32 (uint32x4_t, uint32x4_t) +@*@emph{Form of expected instruction(s):} @code{vmax.u32 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint16x8_t vmaxq_u16 (uint16x8_t, uint16x8_t) +@*@emph{Form of expected instruction(s):} @code{vmax.u16 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint8x16_t vmaxq_u8 (uint8x16_t, uint8x16_t) +@*@emph{Form of expected instruction(s):} @code{vmax.u8 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int32x4_t vmaxq_s32 (int32x4_t, int32x4_t) +@*@emph{Form of expected instruction(s):} @code{vmax.s32 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int16x8_t vmaxq_s16 (int16x8_t, int16x8_t) +@*@emph{Form of expected instruction(s):} @code{vmax.s16 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int8x16_t vmaxq_s8 (int8x16_t, int8x16_t) +@*@emph{Form of expected instruction(s):} @code{vmax.s8 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item float32x4_t vmaxq_f32 (float32x4_t, float32x4_t) +@*@emph{Form of expected instruction(s):} @code{vmax.f32 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + + + +@subsubsection Minimum + +@itemize @bullet +@item uint32x2_t vmin_u32 (uint32x2_t, uint32x2_t) +@*@emph{Form of expected instruction(s):} @code{vmin.u32 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint16x4_t vmin_u16 (uint16x4_t, uint16x4_t) +@*@emph{Form of expected instruction(s):} @code{vmin.u16 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint8x8_t vmin_u8 (uint8x8_t, uint8x8_t) +@*@emph{Form of expected instruction(s):} @code{vmin.u8 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int32x2_t vmin_s32 (int32x2_t, int32x2_t) +@*@emph{Form of expected instruction(s):} @code{vmin.s32 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int16x4_t vmin_s16 (int16x4_t, int16x4_t) +@*@emph{Form of expected instruction(s):} @code{vmin.s16 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int8x8_t vmin_s8 (int8x8_t, int8x8_t) +@*@emph{Form of expected instruction(s):} @code{vmin.s8 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item float32x2_t vmin_f32 (float32x2_t, float32x2_t) +@*@emph{Form of expected instruction(s):} @code{vmin.f32 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint32x4_t vminq_u32 (uint32x4_t, uint32x4_t) +@*@emph{Form of expected instruction(s):} @code{vmin.u32 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint16x8_t vminq_u16 (uint16x8_t, uint16x8_t) +@*@emph{Form of expected instruction(s):} @code{vmin.u16 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint8x16_t vminq_u8 (uint8x16_t, uint8x16_t) +@*@emph{Form of expected instruction(s):} @code{vmin.u8 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int32x4_t vminq_s32 (int32x4_t, int32x4_t) +@*@emph{Form of expected instruction(s):} @code{vmin.s32 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int16x8_t vminq_s16 (int16x8_t, int16x8_t) +@*@emph{Form of expected instruction(s):} @code{vmin.s16 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int8x16_t vminq_s8 (int8x16_t, int8x16_t) +@*@emph{Form of expected instruction(s):} @code{vmin.s8 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item float32x4_t vminq_f32 (float32x4_t, float32x4_t) +@*@emph{Form of expected instruction(s):} @code{vmin.f32 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + + + +@subsubsection Pairwise add + +@itemize @bullet +@item uint32x2_t vpadd_u32 (uint32x2_t, uint32x2_t) +@*@emph{Form of expected instruction(s):} @code{vpadd.i32 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint16x4_t vpadd_u16 (uint16x4_t, uint16x4_t) +@*@emph{Form of expected instruction(s):} @code{vpadd.i16 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint8x8_t vpadd_u8 (uint8x8_t, uint8x8_t) +@*@emph{Form of expected instruction(s):} @code{vpadd.i8 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int32x2_t vpadd_s32 (int32x2_t, int32x2_t) +@*@emph{Form of expected instruction(s):} @code{vpadd.i32 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int16x4_t vpadd_s16 (int16x4_t, int16x4_t) +@*@emph{Form of expected instruction(s):} @code{vpadd.i16 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int8x8_t vpadd_s8 (int8x8_t, int8x8_t) +@*@emph{Form of expected instruction(s):} @code{vpadd.i8 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item float32x2_t vpadd_f32 (float32x2_t, float32x2_t) +@*@emph{Form of expected instruction(s):} @code{vpadd.f32 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint64x1_t vpaddl_u32 (uint32x2_t) +@*@emph{Form of expected instruction(s):} @code{vpaddl.u32 @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint32x2_t vpaddl_u16 (uint16x4_t) +@*@emph{Form of expected instruction(s):} @code{vpaddl.u16 @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint16x4_t vpaddl_u8 (uint8x8_t) +@*@emph{Form of expected instruction(s):} @code{vpaddl.u8 @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int64x1_t vpaddl_s32 (int32x2_t) +@*@emph{Form of expected instruction(s):} @code{vpaddl.s32 @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int32x2_t vpaddl_s16 (int16x4_t) +@*@emph{Form of expected instruction(s):} @code{vpaddl.s16 @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int16x4_t vpaddl_s8 (int8x8_t) +@*@emph{Form of expected instruction(s):} @code{vpaddl.s8 @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint64x2_t vpaddlq_u32 (uint32x4_t) +@*@emph{Form of expected instruction(s):} @code{vpaddl.u32 @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint32x4_t vpaddlq_u16 (uint16x8_t) +@*@emph{Form of expected instruction(s):} @code{vpaddl.u16 @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint16x8_t vpaddlq_u8 (uint8x16_t) +@*@emph{Form of expected instruction(s):} @code{vpaddl.u8 @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int64x2_t vpaddlq_s32 (int32x4_t) +@*@emph{Form of expected instruction(s):} @code{vpaddl.s32 @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int32x4_t vpaddlq_s16 (int16x8_t) +@*@emph{Form of expected instruction(s):} @code{vpaddl.s16 @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int16x8_t vpaddlq_s8 (int8x16_t) +@*@emph{Form of expected instruction(s):} @code{vpaddl.s8 @var{q0}, @var{q0}} +@end itemize + + + + +@subsubsection Pairwise add, single_opcode widen and accumulate + +@itemize @bullet +@item uint64x1_t vpadal_u32 (uint64x1_t, uint32x2_t) +@*@emph{Form of expected instruction(s):} @code{vpadal.u32 @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint32x2_t vpadal_u16 (uint32x2_t, uint16x4_t) +@*@emph{Form of expected instruction(s):} @code{vpadal.u16 @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint16x4_t vpadal_u8 (uint16x4_t, uint8x8_t) +@*@emph{Form of expected instruction(s):} @code{vpadal.u8 @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int64x1_t vpadal_s32 (int64x1_t, int32x2_t) +@*@emph{Form of expected instruction(s):} @code{vpadal.s32 @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int32x2_t vpadal_s16 (int32x2_t, int16x4_t) +@*@emph{Form of expected instruction(s):} @code{vpadal.s16 @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int16x4_t vpadal_s8 (int16x4_t, int8x8_t) +@*@emph{Form of expected instruction(s):} @code{vpadal.s8 @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint64x2_t vpadalq_u32 (uint64x2_t, uint32x4_t) +@*@emph{Form of expected instruction(s):} @code{vpadal.u32 @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint32x4_t vpadalq_u16 (uint32x4_t, uint16x8_t) +@*@emph{Form of expected instruction(s):} @code{vpadal.u16 @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint16x8_t vpadalq_u8 (uint16x8_t, uint8x16_t) +@*@emph{Form of expected instruction(s):} @code{vpadal.u8 @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int64x2_t vpadalq_s32 (int64x2_t, int32x4_t) +@*@emph{Form of expected instruction(s):} @code{vpadal.s32 @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int32x4_t vpadalq_s16 (int32x4_t, int16x8_t) +@*@emph{Form of expected instruction(s):} @code{vpadal.s16 @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int16x8_t vpadalq_s8 (int16x8_t, int8x16_t) +@*@emph{Form of expected instruction(s):} @code{vpadal.s8 @var{q0}, @var{q0}} +@end itemize + + + + +@subsubsection Folding maximum + +@itemize @bullet +@item uint32x2_t vpmax_u32 (uint32x2_t, uint32x2_t) +@*@emph{Form of expected instruction(s):} @code{vpmax.u32 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint16x4_t vpmax_u16 (uint16x4_t, uint16x4_t) +@*@emph{Form of expected instruction(s):} @code{vpmax.u16 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint8x8_t vpmax_u8 (uint8x8_t, uint8x8_t) +@*@emph{Form of expected instruction(s):} @code{vpmax.u8 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int32x2_t vpmax_s32 (int32x2_t, int32x2_t) +@*@emph{Form of expected instruction(s):} @code{vpmax.s32 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int16x4_t vpmax_s16 (int16x4_t, int16x4_t) +@*@emph{Form of expected instruction(s):} @code{vpmax.s16 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int8x8_t vpmax_s8 (int8x8_t, int8x8_t) +@*@emph{Form of expected instruction(s):} @code{vpmax.s8 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item float32x2_t vpmax_f32 (float32x2_t, float32x2_t) +@*@emph{Form of expected instruction(s):} @code{vpmax.f32 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + + + +@subsubsection Folding minimum + +@itemize @bullet +@item uint32x2_t vpmin_u32 (uint32x2_t, uint32x2_t) +@*@emph{Form of expected instruction(s):} @code{vpmin.u32 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint16x4_t vpmin_u16 (uint16x4_t, uint16x4_t) +@*@emph{Form of expected instruction(s):} @code{vpmin.u16 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint8x8_t vpmin_u8 (uint8x8_t, uint8x8_t) +@*@emph{Form of expected instruction(s):} @code{vpmin.u8 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int32x2_t vpmin_s32 (int32x2_t, int32x2_t) +@*@emph{Form of expected instruction(s):} @code{vpmin.s32 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int16x4_t vpmin_s16 (int16x4_t, int16x4_t) +@*@emph{Form of expected instruction(s):} @code{vpmin.s16 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int8x8_t vpmin_s8 (int8x8_t, int8x8_t) +@*@emph{Form of expected instruction(s):} @code{vpmin.s8 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item float32x2_t vpmin_f32 (float32x2_t, float32x2_t) +@*@emph{Form of expected instruction(s):} @code{vpmin.f32 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + + + +@subsubsection Reciprocal step + +@itemize @bullet +@item float32x2_t vrecps_f32 (float32x2_t, float32x2_t) +@*@emph{Form of expected instruction(s):} @code{vrecps.f32 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item float32x4_t vrecpsq_f32 (float32x4_t, float32x4_t) +@*@emph{Form of expected instruction(s):} @code{vrecps.f32 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item float32x2_t vrsqrts_f32 (float32x2_t, float32x2_t) +@*@emph{Form of expected instruction(s):} @code{vrsqrts.f32 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item float32x4_t vrsqrtsq_f32 (float32x4_t, float32x4_t) +@*@emph{Form of expected instruction(s):} @code{vrsqrts.f32 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + + + +@subsubsection Vector shift left + +@itemize @bullet +@item uint32x2_t vshl_u32 (uint32x2_t, int32x2_t) +@*@emph{Form of expected instruction(s):} @code{vshl.u32 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint16x4_t vshl_u16 (uint16x4_t, int16x4_t) +@*@emph{Form of expected instruction(s):} @code{vshl.u16 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint8x8_t vshl_u8 (uint8x8_t, int8x8_t) +@*@emph{Form of expected instruction(s):} @code{vshl.u8 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int32x2_t vshl_s32 (int32x2_t, int32x2_t) +@*@emph{Form of expected instruction(s):} @code{vshl.s32 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int16x4_t vshl_s16 (int16x4_t, int16x4_t) +@*@emph{Form of expected instruction(s):} @code{vshl.s16 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int8x8_t vshl_s8 (int8x8_t, int8x8_t) +@*@emph{Form of expected instruction(s):} @code{vshl.s8 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint64x1_t vshl_u64 (uint64x1_t, int64x1_t) +@*@emph{Form of expected instruction(s):} @code{vshl.u64 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int64x1_t vshl_s64 (int64x1_t, int64x1_t) +@*@emph{Form of expected instruction(s):} @code{vshl.s64 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint32x4_t vshlq_u32 (uint32x4_t, int32x4_t) +@*@emph{Form of expected instruction(s):} @code{vshl.u32 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint16x8_t vshlq_u16 (uint16x8_t, int16x8_t) +@*@emph{Form of expected instruction(s):} @code{vshl.u16 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint8x16_t vshlq_u8 (uint8x16_t, int8x16_t) +@*@emph{Form of expected instruction(s):} @code{vshl.u8 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int32x4_t vshlq_s32 (int32x4_t, int32x4_t) +@*@emph{Form of expected instruction(s):} @code{vshl.s32 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int16x8_t vshlq_s16 (int16x8_t, int16x8_t) +@*@emph{Form of expected instruction(s):} @code{vshl.s16 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int8x16_t vshlq_s8 (int8x16_t, int8x16_t) +@*@emph{Form of expected instruction(s):} @code{vshl.s8 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint64x2_t vshlq_u64 (uint64x2_t, int64x2_t) +@*@emph{Form of expected instruction(s):} @code{vshl.u64 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int64x2_t vshlq_s64 (int64x2_t, int64x2_t) +@*@emph{Form of expected instruction(s):} @code{vshl.s64 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint32x2_t vrshl_u32 (uint32x2_t, int32x2_t) +@*@emph{Form of expected instruction(s):} @code{vrshl.u32 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint16x4_t vrshl_u16 (uint16x4_t, int16x4_t) +@*@emph{Form of expected instruction(s):} @code{vrshl.u16 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint8x8_t vrshl_u8 (uint8x8_t, int8x8_t) +@*@emph{Form of expected instruction(s):} @code{vrshl.u8 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int32x2_t vrshl_s32 (int32x2_t, int32x2_t) +@*@emph{Form of expected instruction(s):} @code{vrshl.s32 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int16x4_t vrshl_s16 (int16x4_t, int16x4_t) +@*@emph{Form of expected instruction(s):} @code{vrshl.s16 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int8x8_t vrshl_s8 (int8x8_t, int8x8_t) +@*@emph{Form of expected instruction(s):} @code{vrshl.s8 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint64x1_t vrshl_u64 (uint64x1_t, int64x1_t) +@*@emph{Form of expected instruction(s):} @code{vrshl.u64 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int64x1_t vrshl_s64 (int64x1_t, int64x1_t) +@*@emph{Form of expected instruction(s):} @code{vrshl.s64 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint32x4_t vrshlq_u32 (uint32x4_t, int32x4_t) +@*@emph{Form of expected instruction(s):} @code{vrshl.u32 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint16x8_t vrshlq_u16 (uint16x8_t, int16x8_t) +@*@emph{Form of expected instruction(s):} @code{vrshl.u16 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint8x16_t vrshlq_u8 (uint8x16_t, int8x16_t) +@*@emph{Form of expected instruction(s):} @code{vrshl.u8 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int32x4_t vrshlq_s32 (int32x4_t, int32x4_t) +@*@emph{Form of expected instruction(s):} @code{vrshl.s32 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int16x8_t vrshlq_s16 (int16x8_t, int16x8_t) +@*@emph{Form of expected instruction(s):} @code{vrshl.s16 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int8x16_t vrshlq_s8 (int8x16_t, int8x16_t) +@*@emph{Form of expected instruction(s):} @code{vrshl.s8 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint64x2_t vrshlq_u64 (uint64x2_t, int64x2_t) +@*@emph{Form of expected instruction(s):} @code{vrshl.u64 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int64x2_t vrshlq_s64 (int64x2_t, int64x2_t) +@*@emph{Form of expected instruction(s):} @code{vrshl.s64 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint32x2_t vqshl_u32 (uint32x2_t, int32x2_t) +@*@emph{Form of expected instruction(s):} @code{vqshl.u32 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint16x4_t vqshl_u16 (uint16x4_t, int16x4_t) +@*@emph{Form of expected instruction(s):} @code{vqshl.u16 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint8x8_t vqshl_u8 (uint8x8_t, int8x8_t) +@*@emph{Form of expected instruction(s):} @code{vqshl.u8 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int32x2_t vqshl_s32 (int32x2_t, int32x2_t) +@*@emph{Form of expected instruction(s):} @code{vqshl.s32 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int16x4_t vqshl_s16 (int16x4_t, int16x4_t) +@*@emph{Form of expected instruction(s):} @code{vqshl.s16 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int8x8_t vqshl_s8 (int8x8_t, int8x8_t) +@*@emph{Form of expected instruction(s):} @code{vqshl.s8 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint64x1_t vqshl_u64 (uint64x1_t, int64x1_t) +@*@emph{Form of expected instruction(s):} @code{vqshl.u64 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int64x1_t vqshl_s64 (int64x1_t, int64x1_t) +@*@emph{Form of expected instruction(s):} @code{vqshl.s64 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint32x4_t vqshlq_u32 (uint32x4_t, int32x4_t) +@*@emph{Form of expected instruction(s):} @code{vqshl.u32 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint16x8_t vqshlq_u16 (uint16x8_t, int16x8_t) +@*@emph{Form of expected instruction(s):} @code{vqshl.u16 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint8x16_t vqshlq_u8 (uint8x16_t, int8x16_t) +@*@emph{Form of expected instruction(s):} @code{vqshl.u8 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int32x4_t vqshlq_s32 (int32x4_t, int32x4_t) +@*@emph{Form of expected instruction(s):} @code{vqshl.s32 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int16x8_t vqshlq_s16 (int16x8_t, int16x8_t) +@*@emph{Form of expected instruction(s):} @code{vqshl.s16 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int8x16_t vqshlq_s8 (int8x16_t, int8x16_t) +@*@emph{Form of expected instruction(s):} @code{vqshl.s8 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint64x2_t vqshlq_u64 (uint64x2_t, int64x2_t) +@*@emph{Form of expected instruction(s):} @code{vqshl.u64 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int64x2_t vqshlq_s64 (int64x2_t, int64x2_t) +@*@emph{Form of expected instruction(s):} @code{vqshl.s64 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint32x2_t vqrshl_u32 (uint32x2_t, int32x2_t) +@*@emph{Form of expected instruction(s):} @code{vqrshl.u32 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint16x4_t vqrshl_u16 (uint16x4_t, int16x4_t) +@*@emph{Form of expected instruction(s):} @code{vqrshl.u16 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint8x8_t vqrshl_u8 (uint8x8_t, int8x8_t) +@*@emph{Form of expected instruction(s):} @code{vqrshl.u8 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int32x2_t vqrshl_s32 (int32x2_t, int32x2_t) +@*@emph{Form of expected instruction(s):} @code{vqrshl.s32 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int16x4_t vqrshl_s16 (int16x4_t, int16x4_t) +@*@emph{Form of expected instruction(s):} @code{vqrshl.s16 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int8x8_t vqrshl_s8 (int8x8_t, int8x8_t) +@*@emph{Form of expected instruction(s):} @code{vqrshl.s8 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint64x1_t vqrshl_u64 (uint64x1_t, int64x1_t) +@*@emph{Form of expected instruction(s):} @code{vqrshl.u64 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int64x1_t vqrshl_s64 (int64x1_t, int64x1_t) +@*@emph{Form of expected instruction(s):} @code{vqrshl.s64 @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint32x4_t vqrshlq_u32 (uint32x4_t, int32x4_t) +@*@emph{Form of expected instruction(s):} @code{vqrshl.u32 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint16x8_t vqrshlq_u16 (uint16x8_t, int16x8_t) +@*@emph{Form of expected instruction(s):} @code{vqrshl.u16 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint8x16_t vqrshlq_u8 (uint8x16_t, int8x16_t) +@*@emph{Form of expected instruction(s):} @code{vqrshl.u8 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int32x4_t vqrshlq_s32 (int32x4_t, int32x4_t) +@*@emph{Form of expected instruction(s):} @code{vqrshl.s32 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int16x8_t vqrshlq_s16 (int16x8_t, int16x8_t) +@*@emph{Form of expected instruction(s):} @code{vqrshl.s16 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int8x16_t vqrshlq_s8 (int8x16_t, int8x16_t) +@*@emph{Form of expected instruction(s):} @code{vqrshl.s8 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint64x2_t vqrshlq_u64 (uint64x2_t, int64x2_t) +@*@emph{Form of expected instruction(s):} @code{vqrshl.u64 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int64x2_t vqrshlq_s64 (int64x2_t, int64x2_t) +@*@emph{Form of expected instruction(s):} @code{vqrshl.s64 @var{q0}, @var{q0}, @var{q0}} +@end itemize + + + + +@subsubsection Vector shift left by constant + +@itemize @bullet +@item uint32x2_t vshl_n_u32 (uint32x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vshl.i32 @var{d0}, @var{d0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item uint16x4_t vshl_n_u16 (uint16x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vshl.i16 @var{d0}, @var{d0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item uint8x8_t vshl_n_u8 (uint8x8_t, const int) +@*@emph{Form of expected instruction(s):} @code{vshl.i8 @var{d0}, @var{d0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item int32x2_t vshl_n_s32 (int32x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vshl.i32 @var{d0}, @var{d0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item int16x4_t vshl_n_s16 (int16x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vshl.i16 @var{d0}, @var{d0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item int8x8_t vshl_n_s8 (int8x8_t, const int) +@*@emph{Form of expected instruction(s):} @code{vshl.i8 @var{d0}, @var{d0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item uint64x1_t vshl_n_u64 (uint64x1_t, const int) +@*@emph{Form of expected instruction(s):} @code{vshl.i64 @var{d0}, @var{d0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item int64x1_t vshl_n_s64 (int64x1_t, const int) +@*@emph{Form of expected instruction(s):} @code{vshl.i64 @var{d0}, @var{d0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item uint32x4_t vshlq_n_u32 (uint32x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vshl.i32 @var{q0}, @var{q0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item uint16x8_t vshlq_n_u16 (uint16x8_t, const int) +@*@emph{Form of expected instruction(s):} @code{vshl.i16 @var{q0}, @var{q0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item uint8x16_t vshlq_n_u8 (uint8x16_t, const int) +@*@emph{Form of expected instruction(s):} @code{vshl.i8 @var{q0}, @var{q0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item int32x4_t vshlq_n_s32 (int32x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vshl.i32 @var{q0}, @var{q0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item int16x8_t vshlq_n_s16 (int16x8_t, const int) +@*@emph{Form of expected instruction(s):} @code{vshl.i16 @var{q0}, @var{q0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item int8x16_t vshlq_n_s8 (int8x16_t, const int) +@*@emph{Form of expected instruction(s):} @code{vshl.i8 @var{q0}, @var{q0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item uint64x2_t vshlq_n_u64 (uint64x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vshl.i64 @var{q0}, @var{q0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item int64x2_t vshlq_n_s64 (int64x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vshl.i64 @var{q0}, @var{q0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item uint32x2_t vqshl_n_u32 (uint32x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vqshl.u32 @var{d0}, @var{d0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item uint16x4_t vqshl_n_u16 (uint16x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vqshl.u16 @var{d0}, @var{d0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item uint8x8_t vqshl_n_u8 (uint8x8_t, const int) +@*@emph{Form of expected instruction(s):} @code{vqshl.u8 @var{d0}, @var{d0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item int32x2_t vqshl_n_s32 (int32x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vqshl.s32 @var{d0}, @var{d0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item int16x4_t vqshl_n_s16 (int16x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vqshl.s16 @var{d0}, @var{d0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item int8x8_t vqshl_n_s8 (int8x8_t, const int) +@*@emph{Form of expected instruction(s):} @code{vqshl.s8 @var{d0}, @var{d0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item uint64x1_t vqshl_n_u64 (uint64x1_t, const int) +@*@emph{Form of expected instruction(s):} @code{vqshl.u64 @var{d0}, @var{d0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item int64x1_t vqshl_n_s64 (int64x1_t, const int) +@*@emph{Form of expected instruction(s):} @code{vqshl.s64 @var{d0}, @var{d0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item uint32x4_t vqshlq_n_u32 (uint32x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vqshl.u32 @var{q0}, @var{q0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item uint16x8_t vqshlq_n_u16 (uint16x8_t, const int) +@*@emph{Form of expected instruction(s):} @code{vqshl.u16 @var{q0}, @var{q0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item uint8x16_t vqshlq_n_u8 (uint8x16_t, const int) +@*@emph{Form of expected instruction(s):} @code{vqshl.u8 @var{q0}, @var{q0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item int32x4_t vqshlq_n_s32 (int32x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vqshl.s32 @var{q0}, @var{q0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item int16x8_t vqshlq_n_s16 (int16x8_t, const int) +@*@emph{Form of expected instruction(s):} @code{vqshl.s16 @var{q0}, @var{q0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item int8x16_t vqshlq_n_s8 (int8x16_t, const int) +@*@emph{Form of expected instruction(s):} @code{vqshl.s8 @var{q0}, @var{q0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item uint64x2_t vqshlq_n_u64 (uint64x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vqshl.u64 @var{q0}, @var{q0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item int64x2_t vqshlq_n_s64 (int64x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vqshl.s64 @var{q0}, @var{q0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item uint64x1_t vqshlu_n_s64 (int64x1_t, const int) +@*@emph{Form of expected instruction(s):} @code{vqshlu.s64 @var{d0}, @var{d0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item uint32x2_t vqshlu_n_s32 (int32x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vqshlu.s32 @var{d0}, @var{d0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item uint16x4_t vqshlu_n_s16 (int16x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vqshlu.s16 @var{d0}, @var{d0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item uint8x8_t vqshlu_n_s8 (int8x8_t, const int) +@*@emph{Form of expected instruction(s):} @code{vqshlu.s8 @var{d0}, @var{d0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item uint64x2_t vqshluq_n_s64 (int64x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vqshlu.s64 @var{q0}, @var{q0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item uint32x4_t vqshluq_n_s32 (int32x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vqshlu.s32 @var{q0}, @var{q0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item uint16x8_t vqshluq_n_s16 (int16x8_t, const int) +@*@emph{Form of expected instruction(s):} @code{vqshlu.s16 @var{q0}, @var{q0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item uint8x16_t vqshluq_n_s8 (int8x16_t, const int) +@*@emph{Form of expected instruction(s):} @code{vqshlu.s8 @var{q0}, @var{q0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item uint64x2_t vshll_n_u32 (uint32x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vshll.u32 @var{q0}, @var{d0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item uint32x4_t vshll_n_u16 (uint16x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vshll.u16 @var{q0}, @var{d0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item uint16x8_t vshll_n_u8 (uint8x8_t, const int) +@*@emph{Form of expected instruction(s):} @code{vshll.u8 @var{q0}, @var{d0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item int64x2_t vshll_n_s32 (int32x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vshll.s32 @var{q0}, @var{d0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item int32x4_t vshll_n_s16 (int16x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vshll.s16 @var{q0}, @var{d0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item int16x8_t vshll_n_s8 (int8x8_t, const int) +@*@emph{Form of expected instruction(s):} @code{vshll.s8 @var{q0}, @var{d0}, #@var{0}} +@end itemize + + + + +@subsubsection Vector shift right by constant + +@itemize @bullet +@item uint32x2_t vshr_n_u32 (uint32x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vshr.u32 @var{d0}, @var{d0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item uint16x4_t vshr_n_u16 (uint16x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vshr.u16 @var{d0}, @var{d0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item uint8x8_t vshr_n_u8 (uint8x8_t, const int) +@*@emph{Form of expected instruction(s):} @code{vshr.u8 @var{d0}, @var{d0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item int32x2_t vshr_n_s32 (int32x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vshr.s32 @var{d0}, @var{d0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item int16x4_t vshr_n_s16 (int16x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vshr.s16 @var{d0}, @var{d0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item int8x8_t vshr_n_s8 (int8x8_t, const int) +@*@emph{Form of expected instruction(s):} @code{vshr.s8 @var{d0}, @var{d0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item uint64x1_t vshr_n_u64 (uint64x1_t, const int) +@*@emph{Form of expected instruction(s):} @code{vshr.u64 @var{d0}, @var{d0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item int64x1_t vshr_n_s64 (int64x1_t, const int) +@*@emph{Form of expected instruction(s):} @code{vshr.s64 @var{d0}, @var{d0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item uint32x4_t vshrq_n_u32 (uint32x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vshr.u32 @var{q0}, @var{q0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item uint16x8_t vshrq_n_u16 (uint16x8_t, const int) +@*@emph{Form of expected instruction(s):} @code{vshr.u16 @var{q0}, @var{q0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item uint8x16_t vshrq_n_u8 (uint8x16_t, const int) +@*@emph{Form of expected instruction(s):} @code{vshr.u8 @var{q0}, @var{q0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item int32x4_t vshrq_n_s32 (int32x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vshr.s32 @var{q0}, @var{q0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item int16x8_t vshrq_n_s16 (int16x8_t, const int) +@*@emph{Form of expected instruction(s):} @code{vshr.s16 @var{q0}, @var{q0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item int8x16_t vshrq_n_s8 (int8x16_t, const int) +@*@emph{Form of expected instruction(s):} @code{vshr.s8 @var{q0}, @var{q0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item uint64x2_t vshrq_n_u64 (uint64x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vshr.u64 @var{q0}, @var{q0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item int64x2_t vshrq_n_s64 (int64x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vshr.s64 @var{q0}, @var{q0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item uint32x2_t vrshr_n_u32 (uint32x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vrshr.u32 @var{d0}, @var{d0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item uint16x4_t vrshr_n_u16 (uint16x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vrshr.u16 @var{d0}, @var{d0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item uint8x8_t vrshr_n_u8 (uint8x8_t, const int) +@*@emph{Form of expected instruction(s):} @code{vrshr.u8 @var{d0}, @var{d0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item int32x2_t vrshr_n_s32 (int32x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vrshr.s32 @var{d0}, @var{d0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item int16x4_t vrshr_n_s16 (int16x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vrshr.s16 @var{d0}, @var{d0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item int8x8_t vrshr_n_s8 (int8x8_t, const int) +@*@emph{Form of expected instruction(s):} @code{vrshr.s8 @var{d0}, @var{d0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item uint64x1_t vrshr_n_u64 (uint64x1_t, const int) +@*@emph{Form of expected instruction(s):} @code{vrshr.u64 @var{d0}, @var{d0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item int64x1_t vrshr_n_s64 (int64x1_t, const int) +@*@emph{Form of expected instruction(s):} @code{vrshr.s64 @var{d0}, @var{d0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item uint32x4_t vrshrq_n_u32 (uint32x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vrshr.u32 @var{q0}, @var{q0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item uint16x8_t vrshrq_n_u16 (uint16x8_t, const int) +@*@emph{Form of expected instruction(s):} @code{vrshr.u16 @var{q0}, @var{q0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item uint8x16_t vrshrq_n_u8 (uint8x16_t, const int) +@*@emph{Form of expected instruction(s):} @code{vrshr.u8 @var{q0}, @var{q0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item int32x4_t vrshrq_n_s32 (int32x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vrshr.s32 @var{q0}, @var{q0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item int16x8_t vrshrq_n_s16 (int16x8_t, const int) +@*@emph{Form of expected instruction(s):} @code{vrshr.s16 @var{q0}, @var{q0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item int8x16_t vrshrq_n_s8 (int8x16_t, const int) +@*@emph{Form of expected instruction(s):} @code{vrshr.s8 @var{q0}, @var{q0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item uint64x2_t vrshrq_n_u64 (uint64x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vrshr.u64 @var{q0}, @var{q0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item int64x2_t vrshrq_n_s64 (int64x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vrshr.s64 @var{q0}, @var{q0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item uint32x2_t vshrn_n_u64 (uint64x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vshrn.i64 @var{d0}, @var{q0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item uint16x4_t vshrn_n_u32 (uint32x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vshrn.i32 @var{d0}, @var{q0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item uint8x8_t vshrn_n_u16 (uint16x8_t, const int) +@*@emph{Form of expected instruction(s):} @code{vshrn.i16 @var{d0}, @var{q0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item int32x2_t vshrn_n_s64 (int64x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vshrn.i64 @var{d0}, @var{q0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item int16x4_t vshrn_n_s32 (int32x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vshrn.i32 @var{d0}, @var{q0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item int8x8_t vshrn_n_s16 (int16x8_t, const int) +@*@emph{Form of expected instruction(s):} @code{vshrn.i16 @var{d0}, @var{q0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item uint32x2_t vrshrn_n_u64 (uint64x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vrshrn.i64 @var{d0}, @var{q0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item uint16x4_t vrshrn_n_u32 (uint32x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vrshrn.i32 @var{d0}, @var{q0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item uint8x8_t vrshrn_n_u16 (uint16x8_t, const int) +@*@emph{Form of expected instruction(s):} @code{vrshrn.i16 @var{d0}, @var{q0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item int32x2_t vrshrn_n_s64 (int64x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vrshrn.i64 @var{d0}, @var{q0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item int16x4_t vrshrn_n_s32 (int32x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vrshrn.i32 @var{d0}, @var{q0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item int8x8_t vrshrn_n_s16 (int16x8_t, const int) +@*@emph{Form of expected instruction(s):} @code{vrshrn.i16 @var{d0}, @var{q0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item uint32x2_t vqshrn_n_u64 (uint64x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vqshrn.u64 @var{d0}, @var{q0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item uint16x4_t vqshrn_n_u32 (uint32x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vqshrn.u32 @var{d0}, @var{q0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item uint8x8_t vqshrn_n_u16 (uint16x8_t, const int) +@*@emph{Form of expected instruction(s):} @code{vqshrn.u16 @var{d0}, @var{q0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item int32x2_t vqshrn_n_s64 (int64x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vqshrn.s64 @var{d0}, @var{q0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item int16x4_t vqshrn_n_s32 (int32x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vqshrn.s32 @var{d0}, @var{q0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item int8x8_t vqshrn_n_s16 (int16x8_t, const int) +@*@emph{Form of expected instruction(s):} @code{vqshrn.s16 @var{d0}, @var{q0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item uint32x2_t vqrshrn_n_u64 (uint64x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vqrshrn.u64 @var{d0}, @var{q0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item uint16x4_t vqrshrn_n_u32 (uint32x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vqrshrn.u32 @var{d0}, @var{q0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item uint8x8_t vqrshrn_n_u16 (uint16x8_t, const int) +@*@emph{Form of expected instruction(s):} @code{vqrshrn.u16 @var{d0}, @var{q0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item int32x2_t vqrshrn_n_s64 (int64x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vqrshrn.s64 @var{d0}, @var{q0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item int16x4_t vqrshrn_n_s32 (int32x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vqrshrn.s32 @var{d0}, @var{q0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item int8x8_t vqrshrn_n_s16 (int16x8_t, const int) +@*@emph{Form of expected instruction(s):} @code{vqrshrn.s16 @var{d0}, @var{q0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item uint32x2_t vqshrun_n_s64 (int64x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vqshrun.s64 @var{d0}, @var{q0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item uint16x4_t vqshrun_n_s32 (int32x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vqshrun.s32 @var{d0}, @var{q0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item uint8x8_t vqshrun_n_s16 (int16x8_t, const int) +@*@emph{Form of expected instruction(s):} @code{vqshrun.s16 @var{d0}, @var{q0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item uint32x2_t vqrshrun_n_s64 (int64x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vqrshrun.s64 @var{d0}, @var{q0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item uint16x4_t vqrshrun_n_s32 (int32x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vqrshrun.s32 @var{d0}, @var{q0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item uint8x8_t vqrshrun_n_s16 (int16x8_t, const int) +@*@emph{Form of expected instruction(s):} @code{vqrshrun.s16 @var{d0}, @var{q0}, #@var{0}} +@end itemize + + + + +@subsubsection Vector shift right by constant and accumulate + +@itemize @bullet +@item uint32x2_t vsra_n_u32 (uint32x2_t, uint32x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vsra.u32 @var{d0}, @var{d0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item uint16x4_t vsra_n_u16 (uint16x4_t, uint16x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vsra.u16 @var{d0}, @var{d0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item uint8x8_t vsra_n_u8 (uint8x8_t, uint8x8_t, const int) +@*@emph{Form of expected instruction(s):} @code{vsra.u8 @var{d0}, @var{d0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item int32x2_t vsra_n_s32 (int32x2_t, int32x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vsra.s32 @var{d0}, @var{d0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item int16x4_t vsra_n_s16 (int16x4_t, int16x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vsra.s16 @var{d0}, @var{d0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item int8x8_t vsra_n_s8 (int8x8_t, int8x8_t, const int) +@*@emph{Form of expected instruction(s):} @code{vsra.s8 @var{d0}, @var{d0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item uint64x1_t vsra_n_u64 (uint64x1_t, uint64x1_t, const int) +@*@emph{Form of expected instruction(s):} @code{vsra.u64 @var{d0}, @var{d0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item int64x1_t vsra_n_s64 (int64x1_t, int64x1_t, const int) +@*@emph{Form of expected instruction(s):} @code{vsra.s64 @var{d0}, @var{d0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item uint32x4_t vsraq_n_u32 (uint32x4_t, uint32x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vsra.u32 @var{q0}, @var{q0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item uint16x8_t vsraq_n_u16 (uint16x8_t, uint16x8_t, const int) +@*@emph{Form of expected instruction(s):} @code{vsra.u16 @var{q0}, @var{q0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item uint8x16_t vsraq_n_u8 (uint8x16_t, uint8x16_t, const int) +@*@emph{Form of expected instruction(s):} @code{vsra.u8 @var{q0}, @var{q0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item int32x4_t vsraq_n_s32 (int32x4_t, int32x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vsra.s32 @var{q0}, @var{q0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item int16x8_t vsraq_n_s16 (int16x8_t, int16x8_t, const int) +@*@emph{Form of expected instruction(s):} @code{vsra.s16 @var{q0}, @var{q0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item int8x16_t vsraq_n_s8 (int8x16_t, int8x16_t, const int) +@*@emph{Form of expected instruction(s):} @code{vsra.s8 @var{q0}, @var{q0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item uint64x2_t vsraq_n_u64 (uint64x2_t, uint64x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vsra.u64 @var{q0}, @var{q0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item int64x2_t vsraq_n_s64 (int64x2_t, int64x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vsra.s64 @var{q0}, @var{q0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item uint32x2_t vrsra_n_u32 (uint32x2_t, uint32x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vrsra.u32 @var{d0}, @var{d0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item uint16x4_t vrsra_n_u16 (uint16x4_t, uint16x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vrsra.u16 @var{d0}, @var{d0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item uint8x8_t vrsra_n_u8 (uint8x8_t, uint8x8_t, const int) +@*@emph{Form of expected instruction(s):} @code{vrsra.u8 @var{d0}, @var{d0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item int32x2_t vrsra_n_s32 (int32x2_t, int32x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vrsra.s32 @var{d0}, @var{d0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item int16x4_t vrsra_n_s16 (int16x4_t, int16x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vrsra.s16 @var{d0}, @var{d0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item int8x8_t vrsra_n_s8 (int8x8_t, int8x8_t, const int) +@*@emph{Form of expected instruction(s):} @code{vrsra.s8 @var{d0}, @var{d0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item uint64x1_t vrsra_n_u64 (uint64x1_t, uint64x1_t, const int) +@*@emph{Form of expected instruction(s):} @code{vrsra.u64 @var{d0}, @var{d0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item int64x1_t vrsra_n_s64 (int64x1_t, int64x1_t, const int) +@*@emph{Form of expected instruction(s):} @code{vrsra.s64 @var{d0}, @var{d0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item uint32x4_t vrsraq_n_u32 (uint32x4_t, uint32x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vrsra.u32 @var{q0}, @var{q0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item uint16x8_t vrsraq_n_u16 (uint16x8_t, uint16x8_t, const int) +@*@emph{Form of expected instruction(s):} @code{vrsra.u16 @var{q0}, @var{q0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item uint8x16_t vrsraq_n_u8 (uint8x16_t, uint8x16_t, const int) +@*@emph{Form of expected instruction(s):} @code{vrsra.u8 @var{q0}, @var{q0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item int32x4_t vrsraq_n_s32 (int32x4_t, int32x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vrsra.s32 @var{q0}, @var{q0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item int16x8_t vrsraq_n_s16 (int16x8_t, int16x8_t, const int) +@*@emph{Form of expected instruction(s):} @code{vrsra.s16 @var{q0}, @var{q0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item int8x16_t vrsraq_n_s8 (int8x16_t, int8x16_t, const int) +@*@emph{Form of expected instruction(s):} @code{vrsra.s8 @var{q0}, @var{q0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item uint64x2_t vrsraq_n_u64 (uint64x2_t, uint64x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vrsra.u64 @var{q0}, @var{q0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item int64x2_t vrsraq_n_s64 (int64x2_t, int64x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vrsra.s64 @var{q0}, @var{q0}, #@var{0}} +@end itemize + + + + +@subsubsection Vector shift right and insert + +@itemize @bullet +@item uint32x2_t vsri_n_u32 (uint32x2_t, uint32x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vsri.32 @var{d0}, @var{d0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item uint16x4_t vsri_n_u16 (uint16x4_t, uint16x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vsri.16 @var{d0}, @var{d0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item uint8x8_t vsri_n_u8 (uint8x8_t, uint8x8_t, const int) +@*@emph{Form of expected instruction(s):} @code{vsri.8 @var{d0}, @var{d0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item int32x2_t vsri_n_s32 (int32x2_t, int32x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vsri.32 @var{d0}, @var{d0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item int16x4_t vsri_n_s16 (int16x4_t, int16x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vsri.16 @var{d0}, @var{d0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item int8x8_t vsri_n_s8 (int8x8_t, int8x8_t, const int) +@*@emph{Form of expected instruction(s):} @code{vsri.8 @var{d0}, @var{d0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item uint64x1_t vsri_n_u64 (uint64x1_t, uint64x1_t, const int) +@*@emph{Form of expected instruction(s):} @code{vsri.64 @var{d0}, @var{d0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item int64x1_t vsri_n_s64 (int64x1_t, int64x1_t, const int) +@*@emph{Form of expected instruction(s):} @code{vsri.64 @var{d0}, @var{d0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item poly16x4_t vsri_n_p16 (poly16x4_t, poly16x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vsri.16 @var{d0}, @var{d0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item poly8x8_t vsri_n_p8 (poly8x8_t, poly8x8_t, const int) +@*@emph{Form of expected instruction(s):} @code{vsri.8 @var{d0}, @var{d0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item uint32x4_t vsriq_n_u32 (uint32x4_t, uint32x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vsri.32 @var{q0}, @var{q0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item uint16x8_t vsriq_n_u16 (uint16x8_t, uint16x8_t, const int) +@*@emph{Form of expected instruction(s):} @code{vsri.16 @var{q0}, @var{q0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item uint8x16_t vsriq_n_u8 (uint8x16_t, uint8x16_t, const int) +@*@emph{Form of expected instruction(s):} @code{vsri.8 @var{q0}, @var{q0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item int32x4_t vsriq_n_s32 (int32x4_t, int32x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vsri.32 @var{q0}, @var{q0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item int16x8_t vsriq_n_s16 (int16x8_t, int16x8_t, const int) +@*@emph{Form of expected instruction(s):} @code{vsri.16 @var{q0}, @var{q0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item int8x16_t vsriq_n_s8 (int8x16_t, int8x16_t, const int) +@*@emph{Form of expected instruction(s):} @code{vsri.8 @var{q0}, @var{q0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item uint64x2_t vsriq_n_u64 (uint64x2_t, uint64x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vsri.64 @var{q0}, @var{q0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item int64x2_t vsriq_n_s64 (int64x2_t, int64x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vsri.64 @var{q0}, @var{q0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item poly16x8_t vsriq_n_p16 (poly16x8_t, poly16x8_t, const int) +@*@emph{Form of expected instruction(s):} @code{vsri.16 @var{q0}, @var{q0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item poly8x16_t vsriq_n_p8 (poly8x16_t, poly8x16_t, const int) +@*@emph{Form of expected instruction(s):} @code{vsri.8 @var{q0}, @var{q0}, #@var{0}} +@end itemize + + + + +@subsubsection Vector shift left and insert + +@itemize @bullet +@item uint32x2_t vsli_n_u32 (uint32x2_t, uint32x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vsli.32 @var{d0}, @var{d0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item uint16x4_t vsli_n_u16 (uint16x4_t, uint16x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vsli.16 @var{d0}, @var{d0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item uint8x8_t vsli_n_u8 (uint8x8_t, uint8x8_t, const int) +@*@emph{Form of expected instruction(s):} @code{vsli.8 @var{d0}, @var{d0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item int32x2_t vsli_n_s32 (int32x2_t, int32x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vsli.32 @var{d0}, @var{d0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item int16x4_t vsli_n_s16 (int16x4_t, int16x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vsli.16 @var{d0}, @var{d0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item int8x8_t vsli_n_s8 (int8x8_t, int8x8_t, const int) +@*@emph{Form of expected instruction(s):} @code{vsli.8 @var{d0}, @var{d0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item uint64x1_t vsli_n_u64 (uint64x1_t, uint64x1_t, const int) +@*@emph{Form of expected instruction(s):} @code{vsli.64 @var{d0}, @var{d0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item int64x1_t vsli_n_s64 (int64x1_t, int64x1_t, const int) +@*@emph{Form of expected instruction(s):} @code{vsli.64 @var{d0}, @var{d0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item poly16x4_t vsli_n_p16 (poly16x4_t, poly16x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vsli.16 @var{d0}, @var{d0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item poly8x8_t vsli_n_p8 (poly8x8_t, poly8x8_t, const int) +@*@emph{Form of expected instruction(s):} @code{vsli.8 @var{d0}, @var{d0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item uint32x4_t vsliq_n_u32 (uint32x4_t, uint32x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vsli.32 @var{q0}, @var{q0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item uint16x8_t vsliq_n_u16 (uint16x8_t, uint16x8_t, const int) +@*@emph{Form of expected instruction(s):} @code{vsli.16 @var{q0}, @var{q0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item uint8x16_t vsliq_n_u8 (uint8x16_t, uint8x16_t, const int) +@*@emph{Form of expected instruction(s):} @code{vsli.8 @var{q0}, @var{q0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item int32x4_t vsliq_n_s32 (int32x4_t, int32x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vsli.32 @var{q0}, @var{q0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item int16x8_t vsliq_n_s16 (int16x8_t, int16x8_t, const int) +@*@emph{Form of expected instruction(s):} @code{vsli.16 @var{q0}, @var{q0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item int8x16_t vsliq_n_s8 (int8x16_t, int8x16_t, const int) +@*@emph{Form of expected instruction(s):} @code{vsli.8 @var{q0}, @var{q0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item uint64x2_t vsliq_n_u64 (uint64x2_t, uint64x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vsli.64 @var{q0}, @var{q0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item int64x2_t vsliq_n_s64 (int64x2_t, int64x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vsli.64 @var{q0}, @var{q0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item poly16x8_t vsliq_n_p16 (poly16x8_t, poly16x8_t, const int) +@*@emph{Form of expected instruction(s):} @code{vsli.16 @var{q0}, @var{q0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item poly8x16_t vsliq_n_p8 (poly8x16_t, poly8x16_t, const int) +@*@emph{Form of expected instruction(s):} @code{vsli.8 @var{q0}, @var{q0}, #@var{0}} +@end itemize + + + + +@subsubsection Absolute value + +@itemize @bullet +@item float32x2_t vabs_f32 (float32x2_t) +@*@emph{Form of expected instruction(s):} @code{vabs.f32 @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int32x2_t vabs_s32 (int32x2_t) +@*@emph{Form of expected instruction(s):} @code{vabs.s32 @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int16x4_t vabs_s16 (int16x4_t) +@*@emph{Form of expected instruction(s):} @code{vabs.s16 @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int8x8_t vabs_s8 (int8x8_t) +@*@emph{Form of expected instruction(s):} @code{vabs.s8 @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item float32x4_t vabsq_f32 (float32x4_t) +@*@emph{Form of expected instruction(s):} @code{vabs.f32 @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int32x4_t vabsq_s32 (int32x4_t) +@*@emph{Form of expected instruction(s):} @code{vabs.s32 @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int16x8_t vabsq_s16 (int16x8_t) +@*@emph{Form of expected instruction(s):} @code{vabs.s16 @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int8x16_t vabsq_s8 (int8x16_t) +@*@emph{Form of expected instruction(s):} @code{vabs.s8 @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int32x2_t vqabs_s32 (int32x2_t) +@*@emph{Form of expected instruction(s):} @code{vqabs.s32 @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int16x4_t vqabs_s16 (int16x4_t) +@*@emph{Form of expected instruction(s):} @code{vqabs.s16 @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int8x8_t vqabs_s8 (int8x8_t) +@*@emph{Form of expected instruction(s):} @code{vqabs.s8 @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int32x4_t vqabsq_s32 (int32x4_t) +@*@emph{Form of expected instruction(s):} @code{vqabs.s32 @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int16x8_t vqabsq_s16 (int16x8_t) +@*@emph{Form of expected instruction(s):} @code{vqabs.s16 @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int8x16_t vqabsq_s8 (int8x16_t) +@*@emph{Form of expected instruction(s):} @code{vqabs.s8 @var{q0}, @var{q0}} +@end itemize + + + + +@subsubsection Negation + +@itemize @bullet +@item float32x2_t vneg_f32 (float32x2_t) +@*@emph{Form of expected instruction(s):} @code{vneg.f32 @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int32x2_t vneg_s32 (int32x2_t) +@*@emph{Form of expected instruction(s):} @code{vneg.s32 @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int16x4_t vneg_s16 (int16x4_t) +@*@emph{Form of expected instruction(s):} @code{vneg.s16 @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int8x8_t vneg_s8 (int8x8_t) +@*@emph{Form of expected instruction(s):} @code{vneg.s8 @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item float32x4_t vnegq_f32 (float32x4_t) +@*@emph{Form of expected instruction(s):} @code{vneg.f32 @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int32x4_t vnegq_s32 (int32x4_t) +@*@emph{Form of expected instruction(s):} @code{vneg.s32 @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int16x8_t vnegq_s16 (int16x8_t) +@*@emph{Form of expected instruction(s):} @code{vneg.s16 @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int8x16_t vnegq_s8 (int8x16_t) +@*@emph{Form of expected instruction(s):} @code{vneg.s8 @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int32x2_t vqneg_s32 (int32x2_t) +@*@emph{Form of expected instruction(s):} @code{vqneg.s32 @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int16x4_t vqneg_s16 (int16x4_t) +@*@emph{Form of expected instruction(s):} @code{vqneg.s16 @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int8x8_t vqneg_s8 (int8x8_t) +@*@emph{Form of expected instruction(s):} @code{vqneg.s8 @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int32x4_t vqnegq_s32 (int32x4_t) +@*@emph{Form of expected instruction(s):} @code{vqneg.s32 @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int16x8_t vqnegq_s16 (int16x8_t) +@*@emph{Form of expected instruction(s):} @code{vqneg.s16 @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int8x16_t vqnegq_s8 (int8x16_t) +@*@emph{Form of expected instruction(s):} @code{vqneg.s8 @var{q0}, @var{q0}} +@end itemize + + + + +@subsubsection Bitwise not + +@itemize @bullet +@item uint32x2_t vmvn_u32 (uint32x2_t) +@*@emph{Form of expected instruction(s):} @code{vmvn @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint16x4_t vmvn_u16 (uint16x4_t) +@*@emph{Form of expected instruction(s):} @code{vmvn @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint8x8_t vmvn_u8 (uint8x8_t) +@*@emph{Form of expected instruction(s):} @code{vmvn @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int32x2_t vmvn_s32 (int32x2_t) +@*@emph{Form of expected instruction(s):} @code{vmvn @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int16x4_t vmvn_s16 (int16x4_t) +@*@emph{Form of expected instruction(s):} @code{vmvn @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int8x8_t vmvn_s8 (int8x8_t) +@*@emph{Form of expected instruction(s):} @code{vmvn @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item poly8x8_t vmvn_p8 (poly8x8_t) +@*@emph{Form of expected instruction(s):} @code{vmvn @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint32x4_t vmvnq_u32 (uint32x4_t) +@*@emph{Form of expected instruction(s):} @code{vmvn @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint16x8_t vmvnq_u16 (uint16x8_t) +@*@emph{Form of expected instruction(s):} @code{vmvn @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint8x16_t vmvnq_u8 (uint8x16_t) +@*@emph{Form of expected instruction(s):} @code{vmvn @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int32x4_t vmvnq_s32 (int32x4_t) +@*@emph{Form of expected instruction(s):} @code{vmvn @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int16x8_t vmvnq_s16 (int16x8_t) +@*@emph{Form of expected instruction(s):} @code{vmvn @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int8x16_t vmvnq_s8 (int8x16_t) +@*@emph{Form of expected instruction(s):} @code{vmvn @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item poly8x16_t vmvnq_p8 (poly8x16_t) +@*@emph{Form of expected instruction(s):} @code{vmvn @var{q0}, @var{q0}} +@end itemize + + + + +@subsubsection Count leading sign bits + +@itemize @bullet +@item int32x2_t vcls_s32 (int32x2_t) +@*@emph{Form of expected instruction(s):} @code{vcls.s32 @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int16x4_t vcls_s16 (int16x4_t) +@*@emph{Form of expected instruction(s):} @code{vcls.s16 @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int8x8_t vcls_s8 (int8x8_t) +@*@emph{Form of expected instruction(s):} @code{vcls.s8 @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int32x4_t vclsq_s32 (int32x4_t) +@*@emph{Form of expected instruction(s):} @code{vcls.s32 @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int16x8_t vclsq_s16 (int16x8_t) +@*@emph{Form of expected instruction(s):} @code{vcls.s16 @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int8x16_t vclsq_s8 (int8x16_t) +@*@emph{Form of expected instruction(s):} @code{vcls.s8 @var{q0}, @var{q0}} +@end itemize + + + + +@subsubsection Count leading zeros + +@itemize @bullet +@item uint32x2_t vclz_u32 (uint32x2_t) +@*@emph{Form of expected instruction(s):} @code{vclz.i32 @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint16x4_t vclz_u16 (uint16x4_t) +@*@emph{Form of expected instruction(s):} @code{vclz.i16 @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint8x8_t vclz_u8 (uint8x8_t) +@*@emph{Form of expected instruction(s):} @code{vclz.i8 @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int32x2_t vclz_s32 (int32x2_t) +@*@emph{Form of expected instruction(s):} @code{vclz.i32 @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int16x4_t vclz_s16 (int16x4_t) +@*@emph{Form of expected instruction(s):} @code{vclz.i16 @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int8x8_t vclz_s8 (int8x8_t) +@*@emph{Form of expected instruction(s):} @code{vclz.i8 @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint32x4_t vclzq_u32 (uint32x4_t) +@*@emph{Form of expected instruction(s):} @code{vclz.i32 @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint16x8_t vclzq_u16 (uint16x8_t) +@*@emph{Form of expected instruction(s):} @code{vclz.i16 @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint8x16_t vclzq_u8 (uint8x16_t) +@*@emph{Form of expected instruction(s):} @code{vclz.i8 @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int32x4_t vclzq_s32 (int32x4_t) +@*@emph{Form of expected instruction(s):} @code{vclz.i32 @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int16x8_t vclzq_s16 (int16x8_t) +@*@emph{Form of expected instruction(s):} @code{vclz.i16 @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int8x16_t vclzq_s8 (int8x16_t) +@*@emph{Form of expected instruction(s):} @code{vclz.i8 @var{q0}, @var{q0}} +@end itemize + + + + +@subsubsection Count number of set bits + +@itemize @bullet +@item uint8x8_t vcnt_u8 (uint8x8_t) +@*@emph{Form of expected instruction(s):} @code{vcnt.8 @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int8x8_t vcnt_s8 (int8x8_t) +@*@emph{Form of expected instruction(s):} @code{vcnt.8 @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item poly8x8_t vcnt_p8 (poly8x8_t) +@*@emph{Form of expected instruction(s):} @code{vcnt.8 @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint8x16_t vcntq_u8 (uint8x16_t) +@*@emph{Form of expected instruction(s):} @code{vcnt.8 @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int8x16_t vcntq_s8 (int8x16_t) +@*@emph{Form of expected instruction(s):} @code{vcnt.8 @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item poly8x16_t vcntq_p8 (poly8x16_t) +@*@emph{Form of expected instruction(s):} @code{vcnt.8 @var{q0}, @var{q0}} +@end itemize + + + + +@subsubsection Reciprocal estimate + +@itemize @bullet +@item float32x2_t vrecpe_f32 (float32x2_t) +@*@emph{Form of expected instruction(s):} @code{vrecpe.f32 @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint32x2_t vrecpe_u32 (uint32x2_t) +@*@emph{Form of expected instruction(s):} @code{vrecpe.u32 @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item float32x4_t vrecpeq_f32 (float32x4_t) +@*@emph{Form of expected instruction(s):} @code{vrecpe.f32 @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint32x4_t vrecpeq_u32 (uint32x4_t) +@*@emph{Form of expected instruction(s):} @code{vrecpe.u32 @var{q0}, @var{q0}} +@end itemize + + + + +@subsubsection Reciprocal square-root estimate + +@itemize @bullet +@item float32x2_t vrsqrte_f32 (float32x2_t) +@*@emph{Form of expected instruction(s):} @code{vrsqrte.f32 @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint32x2_t vrsqrte_u32 (uint32x2_t) +@*@emph{Form of expected instruction(s):} @code{vrsqrte.u32 @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item float32x4_t vrsqrteq_f32 (float32x4_t) +@*@emph{Form of expected instruction(s):} @code{vrsqrte.f32 @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint32x4_t vrsqrteq_u32 (uint32x4_t) +@*@emph{Form of expected instruction(s):} @code{vrsqrte.u32 @var{q0}, @var{q0}} +@end itemize + + + + +@subsubsection Get lanes from a vector + +@itemize @bullet +@item uint32_t vget_lane_u32 (uint32x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vmov.32 @var{r0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item uint16_t vget_lane_u16 (uint16x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vmov.u16 @var{r0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item uint8_t vget_lane_u8 (uint8x8_t, const int) +@*@emph{Form of expected instruction(s):} @code{vmov.u8 @var{r0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item int32_t vget_lane_s32 (int32x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vmov.32 @var{r0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item int16_t vget_lane_s16 (int16x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vmov.s16 @var{r0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item int8_t vget_lane_s8 (int8x8_t, const int) +@*@emph{Form of expected instruction(s):} @code{vmov.s8 @var{r0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item float32_t vget_lane_f32 (float32x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vmov.32 @var{r0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item poly16_t vget_lane_p16 (poly16x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vmov.u16 @var{r0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item poly8_t vget_lane_p8 (poly8x8_t, const int) +@*@emph{Form of expected instruction(s):} @code{vmov.u8 @var{r0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item uint64_t vget_lane_u64 (uint64x1_t, const int) +@end itemize + + +@itemize @bullet +@item int64_t vget_lane_s64 (int64x1_t, const int) +@end itemize + + +@itemize @bullet +@item uint32_t vgetq_lane_u32 (uint32x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vmov.32 @var{r0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item uint16_t vgetq_lane_u16 (uint16x8_t, const int) +@*@emph{Form of expected instruction(s):} @code{vmov.u16 @var{r0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item uint8_t vgetq_lane_u8 (uint8x16_t, const int) +@*@emph{Form of expected instruction(s):} @code{vmov.u8 @var{r0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item int32_t vgetq_lane_s32 (int32x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vmov.32 @var{r0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item int16_t vgetq_lane_s16 (int16x8_t, const int) +@*@emph{Form of expected instruction(s):} @code{vmov.s16 @var{r0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item int8_t vgetq_lane_s8 (int8x16_t, const int) +@*@emph{Form of expected instruction(s):} @code{vmov.s8 @var{r0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item float32_t vgetq_lane_f32 (float32x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vmov.32 @var{r0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item poly16_t vgetq_lane_p16 (poly16x8_t, const int) +@*@emph{Form of expected instruction(s):} @code{vmov.u16 @var{r0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item poly8_t vgetq_lane_p8 (poly8x16_t, const int) +@*@emph{Form of expected instruction(s):} @code{vmov.u8 @var{r0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item uint64_t vgetq_lane_u64 (uint64x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vmov @var{r0}, @var{r0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int64_t vgetq_lane_s64 (int64x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vmov @var{r0}, @var{r0}, @var{d0}} +@end itemize + + + + +@subsubsection Set lanes in a vector + +@itemize @bullet +@item uint32x2_t vset_lane_u32 (uint32_t, uint32x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vmov.32 @var{d0}[@var{0}], @var{r0}} +@end itemize + + +@itemize @bullet +@item uint16x4_t vset_lane_u16 (uint16_t, uint16x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vmov.16 @var{d0}[@var{0}], @var{r0}} +@end itemize + + +@itemize @bullet +@item uint8x8_t vset_lane_u8 (uint8_t, uint8x8_t, const int) +@*@emph{Form of expected instruction(s):} @code{vmov.8 @var{d0}[@var{0}], @var{r0}} +@end itemize + + +@itemize @bullet +@item int32x2_t vset_lane_s32 (int32_t, int32x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vmov.32 @var{d0}[@var{0}], @var{r0}} +@end itemize + + +@itemize @bullet +@item int16x4_t vset_lane_s16 (int16_t, int16x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vmov.16 @var{d0}[@var{0}], @var{r0}} +@end itemize + + +@itemize @bullet +@item int8x8_t vset_lane_s8 (int8_t, int8x8_t, const int) +@*@emph{Form of expected instruction(s):} @code{vmov.8 @var{d0}[@var{0}], @var{r0}} +@end itemize + + +@itemize @bullet +@item float32x2_t vset_lane_f32 (float32_t, float32x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vmov.32 @var{d0}[@var{0}], @var{r0}} +@end itemize + + +@itemize @bullet +@item poly16x4_t vset_lane_p16 (poly16_t, poly16x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vmov.16 @var{d0}[@var{0}], @var{r0}} +@end itemize + + +@itemize @bullet +@item poly8x8_t vset_lane_p8 (poly8_t, poly8x8_t, const int) +@*@emph{Form of expected instruction(s):} @code{vmov.8 @var{d0}[@var{0}], @var{r0}} +@end itemize + + +@itemize @bullet +@item uint64x1_t vset_lane_u64 (uint64_t, uint64x1_t, const int) +@end itemize + + +@itemize @bullet +@item int64x1_t vset_lane_s64 (int64_t, int64x1_t, const int) +@end itemize + + +@itemize @bullet +@item uint32x4_t vsetq_lane_u32 (uint32_t, uint32x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vmov.32 @var{d0}[@var{0}], @var{r0}} +@end itemize + + +@itemize @bullet +@item uint16x8_t vsetq_lane_u16 (uint16_t, uint16x8_t, const int) +@*@emph{Form of expected instruction(s):} @code{vmov.16 @var{d0}[@var{0}], @var{r0}} +@end itemize + + +@itemize @bullet +@item uint8x16_t vsetq_lane_u8 (uint8_t, uint8x16_t, const int) +@*@emph{Form of expected instruction(s):} @code{vmov.8 @var{d0}[@var{0}], @var{r0}} +@end itemize + + +@itemize @bullet +@item int32x4_t vsetq_lane_s32 (int32_t, int32x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vmov.32 @var{d0}[@var{0}], @var{r0}} +@end itemize + + +@itemize @bullet +@item int16x8_t vsetq_lane_s16 (int16_t, int16x8_t, const int) +@*@emph{Form of expected instruction(s):} @code{vmov.16 @var{d0}[@var{0}], @var{r0}} +@end itemize + + +@itemize @bullet +@item int8x16_t vsetq_lane_s8 (int8_t, int8x16_t, const int) +@*@emph{Form of expected instruction(s):} @code{vmov.8 @var{d0}[@var{0}], @var{r0}} +@end itemize + + +@itemize @bullet +@item float32x4_t vsetq_lane_f32 (float32_t, float32x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vmov.32 @var{d0}[@var{0}], @var{r0}} +@end itemize + + +@itemize @bullet +@item poly16x8_t vsetq_lane_p16 (poly16_t, poly16x8_t, const int) +@*@emph{Form of expected instruction(s):} @code{vmov.16 @var{d0}[@var{0}], @var{r0}} +@end itemize + + +@itemize @bullet +@item poly8x16_t vsetq_lane_p8 (poly8_t, poly8x16_t, const int) +@*@emph{Form of expected instruction(s):} @code{vmov.8 @var{d0}[@var{0}], @var{r0}} +@end itemize + + +@itemize @bullet +@item uint64x2_t vsetq_lane_u64 (uint64_t, uint64x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vmov @var{d0}, @var{r0}, @var{r0}} +@end itemize + + +@itemize @bullet +@item int64x2_t vsetq_lane_s64 (int64_t, int64x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vmov @var{d0}, @var{r0}, @var{r0}} +@end itemize + + + + +@subsubsection Create vector from literal bit pattern + +@itemize @bullet +@item uint32x2_t vcreate_u32 (uint64_t) +@end itemize + + +@itemize @bullet +@item uint16x4_t vcreate_u16 (uint64_t) +@end itemize + + +@itemize @bullet +@item uint8x8_t vcreate_u8 (uint64_t) +@end itemize + + +@itemize @bullet +@item int32x2_t vcreate_s32 (uint64_t) +@end itemize + + +@itemize @bullet +@item int16x4_t vcreate_s16 (uint64_t) +@end itemize + + +@itemize @bullet +@item int8x8_t vcreate_s8 (uint64_t) +@end itemize + + +@itemize @bullet +@item uint64x1_t vcreate_u64 (uint64_t) +@end itemize + + +@itemize @bullet +@item int64x1_t vcreate_s64 (uint64_t) +@end itemize + + +@itemize @bullet +@item float32x2_t vcreate_f32 (uint64_t) +@end itemize + + +@itemize @bullet +@item poly16x4_t vcreate_p16 (uint64_t) +@end itemize + + +@itemize @bullet +@item poly8x8_t vcreate_p8 (uint64_t) +@end itemize + + + + +@subsubsection Set all lanes to the same value + +@itemize @bullet +@item uint32x2_t vdup_n_u32 (uint32_t) +@*@emph{Form of expected instruction(s):} @code{vdup.32 @var{d0}, @var{r0}} +@end itemize + + +@itemize @bullet +@item uint16x4_t vdup_n_u16 (uint16_t) +@*@emph{Form of expected instruction(s):} @code{vdup.16 @var{d0}, @var{r0}} +@end itemize + + +@itemize @bullet +@item uint8x8_t vdup_n_u8 (uint8_t) +@*@emph{Form of expected instruction(s):} @code{vdup.8 @var{d0}, @var{r0}} +@end itemize + + +@itemize @bullet +@item int32x2_t vdup_n_s32 (int32_t) +@*@emph{Form of expected instruction(s):} @code{vdup.32 @var{d0}, @var{r0}} +@end itemize + + +@itemize @bullet +@item int16x4_t vdup_n_s16 (int16_t) +@*@emph{Form of expected instruction(s):} @code{vdup.16 @var{d0}, @var{r0}} +@end itemize + + +@itemize @bullet +@item int8x8_t vdup_n_s8 (int8_t) +@*@emph{Form of expected instruction(s):} @code{vdup.8 @var{d0}, @var{r0}} +@end itemize + + +@itemize @bullet +@item float32x2_t vdup_n_f32 (float32_t) +@*@emph{Form of expected instruction(s):} @code{vdup.32 @var{d0}, @var{r0}} +@end itemize + + +@itemize @bullet +@item poly16x4_t vdup_n_p16 (poly16_t) +@*@emph{Form of expected instruction(s):} @code{vdup.16 @var{d0}, @var{r0}} +@end itemize + + +@itemize @bullet +@item poly8x8_t vdup_n_p8 (poly8_t) +@*@emph{Form of expected instruction(s):} @code{vdup.8 @var{d0}, @var{r0}} +@end itemize + + +@itemize @bullet +@item uint64x1_t vdup_n_u64 (uint64_t) +@end itemize + + +@itemize @bullet +@item int64x1_t vdup_n_s64 (int64_t) +@end itemize + + +@itemize @bullet +@item uint32x4_t vdupq_n_u32 (uint32_t) +@*@emph{Form of expected instruction(s):} @code{vdup.32 @var{q0}, @var{r0}} +@end itemize + + +@itemize @bullet +@item uint16x8_t vdupq_n_u16 (uint16_t) +@*@emph{Form of expected instruction(s):} @code{vdup.16 @var{q0}, @var{r0}} +@end itemize + + +@itemize @bullet +@item uint8x16_t vdupq_n_u8 (uint8_t) +@*@emph{Form of expected instruction(s):} @code{vdup.8 @var{q0}, @var{r0}} +@end itemize + + +@itemize @bullet +@item int32x4_t vdupq_n_s32 (int32_t) +@*@emph{Form of expected instruction(s):} @code{vdup.32 @var{q0}, @var{r0}} +@end itemize + + +@itemize @bullet +@item int16x8_t vdupq_n_s16 (int16_t) +@*@emph{Form of expected instruction(s):} @code{vdup.16 @var{q0}, @var{r0}} +@end itemize + + +@itemize @bullet +@item int8x16_t vdupq_n_s8 (int8_t) +@*@emph{Form of expected instruction(s):} @code{vdup.8 @var{q0}, @var{r0}} +@end itemize + + +@itemize @bullet +@item float32x4_t vdupq_n_f32 (float32_t) +@*@emph{Form of expected instruction(s):} @code{vdup.32 @var{q0}, @var{r0}} +@end itemize + + +@itemize @bullet +@item poly16x8_t vdupq_n_p16 (poly16_t) +@*@emph{Form of expected instruction(s):} @code{vdup.16 @var{q0}, @var{r0}} +@end itemize + + +@itemize @bullet +@item poly8x16_t vdupq_n_p8 (poly8_t) +@*@emph{Form of expected instruction(s):} @code{vdup.8 @var{q0}, @var{r0}} +@end itemize + + +@itemize @bullet +@item uint64x2_t vdupq_n_u64 (uint64_t) +@end itemize + + +@itemize @bullet +@item int64x2_t vdupq_n_s64 (int64_t) +@end itemize + + +@itemize @bullet +@item uint32x2_t vmov_n_u32 (uint32_t) +@*@emph{Form of expected instruction(s):} @code{vdup.32 @var{d0}, @var{r0}} +@end itemize + + +@itemize @bullet +@item uint16x4_t vmov_n_u16 (uint16_t) +@*@emph{Form of expected instruction(s):} @code{vdup.16 @var{d0}, @var{r0}} +@end itemize + + +@itemize @bullet +@item uint8x8_t vmov_n_u8 (uint8_t) +@*@emph{Form of expected instruction(s):} @code{vdup.8 @var{d0}, @var{r0}} +@end itemize + + +@itemize @bullet +@item int32x2_t vmov_n_s32 (int32_t) +@*@emph{Form of expected instruction(s):} @code{vdup.32 @var{d0}, @var{r0}} +@end itemize + + +@itemize @bullet +@item int16x4_t vmov_n_s16 (int16_t) +@*@emph{Form of expected instruction(s):} @code{vdup.16 @var{d0}, @var{r0}} +@end itemize + + +@itemize @bullet +@item int8x8_t vmov_n_s8 (int8_t) +@*@emph{Form of expected instruction(s):} @code{vdup.8 @var{d0}, @var{r0}} +@end itemize + + +@itemize @bullet +@item float32x2_t vmov_n_f32 (float32_t) +@*@emph{Form of expected instruction(s):} @code{vdup.32 @var{d0}, @var{r0}} +@end itemize + + +@itemize @bullet +@item poly16x4_t vmov_n_p16 (poly16_t) +@*@emph{Form of expected instruction(s):} @code{vdup.16 @var{d0}, @var{r0}} +@end itemize + + +@itemize @bullet +@item poly8x8_t vmov_n_p8 (poly8_t) +@*@emph{Form of expected instruction(s):} @code{vdup.8 @var{d0}, @var{r0}} +@end itemize + + +@itemize @bullet +@item uint64x1_t vmov_n_u64 (uint64_t) +@end itemize + + +@itemize @bullet +@item int64x1_t vmov_n_s64 (int64_t) +@end itemize + + +@itemize @bullet +@item uint32x4_t vmovq_n_u32 (uint32_t) +@*@emph{Form of expected instruction(s):} @code{vdup.32 @var{q0}, @var{r0}} +@end itemize + + +@itemize @bullet +@item uint16x8_t vmovq_n_u16 (uint16_t) +@*@emph{Form of expected instruction(s):} @code{vdup.16 @var{q0}, @var{r0}} +@end itemize + + +@itemize @bullet +@item uint8x16_t vmovq_n_u8 (uint8_t) +@*@emph{Form of expected instruction(s):} @code{vdup.8 @var{q0}, @var{r0}} +@end itemize + + +@itemize @bullet +@item int32x4_t vmovq_n_s32 (int32_t) +@*@emph{Form of expected instruction(s):} @code{vdup.32 @var{q0}, @var{r0}} +@end itemize + + +@itemize @bullet +@item int16x8_t vmovq_n_s16 (int16_t) +@*@emph{Form of expected instruction(s):} @code{vdup.16 @var{q0}, @var{r0}} +@end itemize + + +@itemize @bullet +@item int8x16_t vmovq_n_s8 (int8_t) +@*@emph{Form of expected instruction(s):} @code{vdup.8 @var{q0}, @var{r0}} +@end itemize + + +@itemize @bullet +@item float32x4_t vmovq_n_f32 (float32_t) +@*@emph{Form of expected instruction(s):} @code{vdup.32 @var{q0}, @var{r0}} +@end itemize + + +@itemize @bullet +@item poly16x8_t vmovq_n_p16 (poly16_t) +@*@emph{Form of expected instruction(s):} @code{vdup.16 @var{q0}, @var{r0}} +@end itemize + + +@itemize @bullet +@item poly8x16_t vmovq_n_p8 (poly8_t) +@*@emph{Form of expected instruction(s):} @code{vdup.8 @var{q0}, @var{r0}} +@end itemize + + +@itemize @bullet +@item uint64x2_t vmovq_n_u64 (uint64_t) +@end itemize + + +@itemize @bullet +@item int64x2_t vmovq_n_s64 (int64_t) +@end itemize + + +@itemize @bullet +@item uint32x2_t vdup_lane_u32 (uint32x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vdup.32 @var{d0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item uint16x4_t vdup_lane_u16 (uint16x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vdup.16 @var{d0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item uint8x8_t vdup_lane_u8 (uint8x8_t, const int) +@*@emph{Form of expected instruction(s):} @code{vdup.8 @var{d0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item int32x2_t vdup_lane_s32 (int32x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vdup.32 @var{d0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item int16x4_t vdup_lane_s16 (int16x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vdup.16 @var{d0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item int8x8_t vdup_lane_s8 (int8x8_t, const int) +@*@emph{Form of expected instruction(s):} @code{vdup.8 @var{d0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item float32x2_t vdup_lane_f32 (float32x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vdup.32 @var{d0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item poly16x4_t vdup_lane_p16 (poly16x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vdup.16 @var{d0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item poly8x8_t vdup_lane_p8 (poly8x8_t, const int) +@*@emph{Form of expected instruction(s):} @code{vdup.8 @var{d0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item uint64x1_t vdup_lane_u64 (uint64x1_t, const int) +@end itemize + + +@itemize @bullet +@item int64x1_t vdup_lane_s64 (int64x1_t, const int) +@end itemize + + +@itemize @bullet +@item uint32x4_t vdupq_lane_u32 (uint32x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vdup.32 @var{q0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item uint16x8_t vdupq_lane_u16 (uint16x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vdup.16 @var{q0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item uint8x16_t vdupq_lane_u8 (uint8x8_t, const int) +@*@emph{Form of expected instruction(s):} @code{vdup.8 @var{q0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item int32x4_t vdupq_lane_s32 (int32x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vdup.32 @var{q0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item int16x8_t vdupq_lane_s16 (int16x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vdup.16 @var{q0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item int8x16_t vdupq_lane_s8 (int8x8_t, const int) +@*@emph{Form of expected instruction(s):} @code{vdup.8 @var{q0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item float32x4_t vdupq_lane_f32 (float32x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vdup.32 @var{q0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item poly16x8_t vdupq_lane_p16 (poly16x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vdup.16 @var{q0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item poly8x16_t vdupq_lane_p8 (poly8x8_t, const int) +@*@emph{Form of expected instruction(s):} @code{vdup.8 @var{q0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item uint64x2_t vdupq_lane_u64 (uint64x1_t, const int) +@end itemize + + +@itemize @bullet +@item int64x2_t vdupq_lane_s64 (int64x1_t, const int) +@end itemize + + + + +@subsubsection Combining vectors + +@itemize @bullet +@item uint32x4_t vcombine_u32 (uint32x2_t, uint32x2_t) +@end itemize + + +@itemize @bullet +@item uint16x8_t vcombine_u16 (uint16x4_t, uint16x4_t) +@end itemize + + +@itemize @bullet +@item uint8x16_t vcombine_u8 (uint8x8_t, uint8x8_t) +@end itemize + + +@itemize @bullet +@item int32x4_t vcombine_s32 (int32x2_t, int32x2_t) +@end itemize + + +@itemize @bullet +@item int16x8_t vcombine_s16 (int16x4_t, int16x4_t) +@end itemize + + +@itemize @bullet +@item int8x16_t vcombine_s8 (int8x8_t, int8x8_t) +@end itemize + + +@itemize @bullet +@item uint64x2_t vcombine_u64 (uint64x1_t, uint64x1_t) +@end itemize + + +@itemize @bullet +@item int64x2_t vcombine_s64 (int64x1_t, int64x1_t) +@end itemize + + +@itemize @bullet +@item float32x4_t vcombine_f32 (float32x2_t, float32x2_t) +@end itemize + + +@itemize @bullet +@item poly16x8_t vcombine_p16 (poly16x4_t, poly16x4_t) +@end itemize + + +@itemize @bullet +@item poly8x16_t vcombine_p8 (poly8x8_t, poly8x8_t) +@end itemize + + + + +@subsubsection Splitting vectors + +@itemize @bullet +@item uint32x2_t vget_high_u32 (uint32x4_t) +@end itemize + + +@itemize @bullet +@item uint16x4_t vget_high_u16 (uint16x8_t) +@end itemize + + +@itemize @bullet +@item uint8x8_t vget_high_u8 (uint8x16_t) +@end itemize + + +@itemize @bullet +@item int32x2_t vget_high_s32 (int32x4_t) +@end itemize + + +@itemize @bullet +@item int16x4_t vget_high_s16 (int16x8_t) +@end itemize + + +@itemize @bullet +@item int8x8_t vget_high_s8 (int8x16_t) +@end itemize + + +@itemize @bullet +@item uint64x1_t vget_high_u64 (uint64x2_t) +@end itemize + + +@itemize @bullet +@item int64x1_t vget_high_s64 (int64x2_t) +@end itemize + + +@itemize @bullet +@item float32x2_t vget_high_f32 (float32x4_t) +@end itemize + + +@itemize @bullet +@item poly16x4_t vget_high_p16 (poly16x8_t) +@end itemize + + +@itemize @bullet +@item poly8x8_t vget_high_p8 (poly8x16_t) +@end itemize + + +@itemize @bullet +@item uint32x2_t vget_low_u32 (uint32x4_t) +@*@emph{Form of expected instruction(s):} @code{vmov @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint16x4_t vget_low_u16 (uint16x8_t) +@*@emph{Form of expected instruction(s):} @code{vmov @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint8x8_t vget_low_u8 (uint8x16_t) +@*@emph{Form of expected instruction(s):} @code{vmov @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int32x2_t vget_low_s32 (int32x4_t) +@*@emph{Form of expected instruction(s):} @code{vmov @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int16x4_t vget_low_s16 (int16x8_t) +@*@emph{Form of expected instruction(s):} @code{vmov @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int8x8_t vget_low_s8 (int8x16_t) +@*@emph{Form of expected instruction(s):} @code{vmov @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item float32x2_t vget_low_f32 (float32x4_t) +@*@emph{Form of expected instruction(s):} @code{vmov @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item poly16x4_t vget_low_p16 (poly16x8_t) +@*@emph{Form of expected instruction(s):} @code{vmov @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item poly8x8_t vget_low_p8 (poly8x16_t) +@*@emph{Form of expected instruction(s):} @code{vmov @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint64x1_t vget_low_u64 (uint64x2_t) +@end itemize + + +@itemize @bullet +@item int64x1_t vget_low_s64 (int64x2_t) +@end itemize + + + + +@subsubsection Conversions + +@itemize @bullet +@item float32x2_t vcvt_f32_u32 (uint32x2_t) +@*@emph{Form of expected instruction(s):} @code{vcvt.f32.u32 @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item float32x2_t vcvt_f32_s32 (int32x2_t) +@*@emph{Form of expected instruction(s):} @code{vcvt.f32.s32 @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint32x2_t vcvt_u32_f32 (float32x2_t) +@*@emph{Form of expected instruction(s):} @code{vcvt.u32.f32 @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int32x2_t vcvt_s32_f32 (float32x2_t) +@*@emph{Form of expected instruction(s):} @code{vcvt.s32.f32 @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item float32x4_t vcvtq_f32_u32 (uint32x4_t) +@*@emph{Form of expected instruction(s):} @code{vcvt.f32.u32 @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item float32x4_t vcvtq_f32_s32 (int32x4_t) +@*@emph{Form of expected instruction(s):} @code{vcvt.f32.s32 @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint32x4_t vcvtq_u32_f32 (float32x4_t) +@*@emph{Form of expected instruction(s):} @code{vcvt.u32.f32 @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int32x4_t vcvtq_s32_f32 (float32x4_t) +@*@emph{Form of expected instruction(s):} @code{vcvt.s32.f32 @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item float32x2_t vcvt_n_f32_u32 (uint32x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vcvt.f32.u32 @var{d0}, @var{d0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item float32x2_t vcvt_n_f32_s32 (int32x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vcvt.f32.s32 @var{d0}, @var{d0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item uint32x2_t vcvt_n_u32_f32 (float32x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vcvt.u32.f32 @var{d0}, @var{d0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item int32x2_t vcvt_n_s32_f32 (float32x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vcvt.s32.f32 @var{d0}, @var{d0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item float32x4_t vcvtq_n_f32_u32 (uint32x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vcvt.f32.u32 @var{q0}, @var{q0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item float32x4_t vcvtq_n_f32_s32 (int32x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vcvt.f32.s32 @var{q0}, @var{q0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item uint32x4_t vcvtq_n_u32_f32 (float32x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vcvt.u32.f32 @var{q0}, @var{q0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item int32x4_t vcvtq_n_s32_f32 (float32x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vcvt.s32.f32 @var{q0}, @var{q0}, #@var{0}} +@end itemize + + + + +@subsubsection Move, single_opcode narrowing + +@itemize @bullet +@item uint32x2_t vmovn_u64 (uint64x2_t) +@*@emph{Form of expected instruction(s):} @code{vmovn.i64 @var{d0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint16x4_t vmovn_u32 (uint32x4_t) +@*@emph{Form of expected instruction(s):} @code{vmovn.i32 @var{d0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint8x8_t vmovn_u16 (uint16x8_t) +@*@emph{Form of expected instruction(s):} @code{vmovn.i16 @var{d0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int32x2_t vmovn_s64 (int64x2_t) +@*@emph{Form of expected instruction(s):} @code{vmovn.i64 @var{d0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int16x4_t vmovn_s32 (int32x4_t) +@*@emph{Form of expected instruction(s):} @code{vmovn.i32 @var{d0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int8x8_t vmovn_s16 (int16x8_t) +@*@emph{Form of expected instruction(s):} @code{vmovn.i16 @var{d0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint32x2_t vqmovn_u64 (uint64x2_t) +@*@emph{Form of expected instruction(s):} @code{vqmovn.u64 @var{d0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint16x4_t vqmovn_u32 (uint32x4_t) +@*@emph{Form of expected instruction(s):} @code{vqmovn.u32 @var{d0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint8x8_t vqmovn_u16 (uint16x8_t) +@*@emph{Form of expected instruction(s):} @code{vqmovn.u16 @var{d0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int32x2_t vqmovn_s64 (int64x2_t) +@*@emph{Form of expected instruction(s):} @code{vqmovn.s64 @var{d0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int16x4_t vqmovn_s32 (int32x4_t) +@*@emph{Form of expected instruction(s):} @code{vqmovn.s32 @var{d0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int8x8_t vqmovn_s16 (int16x8_t) +@*@emph{Form of expected instruction(s):} @code{vqmovn.s16 @var{d0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint32x2_t vqmovun_s64 (int64x2_t) +@*@emph{Form of expected instruction(s):} @code{vqmovun.s64 @var{d0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint16x4_t vqmovun_s32 (int32x4_t) +@*@emph{Form of expected instruction(s):} @code{vqmovun.s32 @var{d0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint8x8_t vqmovun_s16 (int16x8_t) +@*@emph{Form of expected instruction(s):} @code{vqmovun.s16 @var{d0}, @var{q0}} +@end itemize + + + + +@subsubsection Move, single_opcode long + +@itemize @bullet +@item uint64x2_t vmovl_u32 (uint32x2_t) +@*@emph{Form of expected instruction(s):} @code{vmovl.u32 @var{q0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint32x4_t vmovl_u16 (uint16x4_t) +@*@emph{Form of expected instruction(s):} @code{vmovl.u16 @var{q0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint16x8_t vmovl_u8 (uint8x8_t) +@*@emph{Form of expected instruction(s):} @code{vmovl.u8 @var{q0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int64x2_t vmovl_s32 (int32x2_t) +@*@emph{Form of expected instruction(s):} @code{vmovl.s32 @var{q0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int32x4_t vmovl_s16 (int16x4_t) +@*@emph{Form of expected instruction(s):} @code{vmovl.s16 @var{q0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int16x8_t vmovl_s8 (int8x8_t) +@*@emph{Form of expected instruction(s):} @code{vmovl.s8 @var{q0}, @var{d0}} +@end itemize + + + + +@subsubsection Table lookup + +@itemize @bullet +@item poly8x8_t vtbl1_p8 (poly8x8_t, uint8x8_t) +@*@emph{Form of expected instruction(s):} @code{vtbl.8 @var{d0}, @{@var{d0}@}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int8x8_t vtbl1_s8 (int8x8_t, int8x8_t) +@*@emph{Form of expected instruction(s):} @code{vtbl.8 @var{d0}, @{@var{d0}@}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint8x8_t vtbl1_u8 (uint8x8_t, uint8x8_t) +@*@emph{Form of expected instruction(s):} @code{vtbl.8 @var{d0}, @{@var{d0}@}, @var{d0}} +@end itemize + + +@itemize @bullet +@item poly8x8_t vtbl2_p8 (poly8x8x2_t, uint8x8_t) +@*@emph{Form of expected instruction(s):} @code{vtbl.8 @var{d0}, @{@var{d0}, @var{d1}@}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int8x8_t vtbl2_s8 (int8x8x2_t, int8x8_t) +@*@emph{Form of expected instruction(s):} @code{vtbl.8 @var{d0}, @{@var{d0}, @var{d1}@}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint8x8_t vtbl2_u8 (uint8x8x2_t, uint8x8_t) +@*@emph{Form of expected instruction(s):} @code{vtbl.8 @var{d0}, @{@var{d0}, @var{d1}@}, @var{d0}} +@end itemize + + +@itemize @bullet +@item poly8x8_t vtbl3_p8 (poly8x8x3_t, uint8x8_t) +@*@emph{Form of expected instruction(s):} @code{vtbl.8 @var{d0}, @{@var{d0}, @var{d1}, @var{d2}@}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int8x8_t vtbl3_s8 (int8x8x3_t, int8x8_t) +@*@emph{Form of expected instruction(s):} @code{vtbl.8 @var{d0}, @{@var{d0}, @var{d1}, @var{d2}@}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint8x8_t vtbl3_u8 (uint8x8x3_t, uint8x8_t) +@*@emph{Form of expected instruction(s):} @code{vtbl.8 @var{d0}, @{@var{d0}, @var{d1}, @var{d2}@}, @var{d0}} +@end itemize + + +@itemize @bullet +@item poly8x8_t vtbl4_p8 (poly8x8x4_t, uint8x8_t) +@*@emph{Form of expected instruction(s):} @code{vtbl.8 @var{d0}, @{@var{d0}, @var{d1}, @var{d2}, @var{d3}@}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int8x8_t vtbl4_s8 (int8x8x4_t, int8x8_t) +@*@emph{Form of expected instruction(s):} @code{vtbl.8 @var{d0}, @{@var{d0}, @var{d1}, @var{d2}, @var{d3}@}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint8x8_t vtbl4_u8 (uint8x8x4_t, uint8x8_t) +@*@emph{Form of expected instruction(s):} @code{vtbl.8 @var{d0}, @{@var{d0}, @var{d1}, @var{d2}, @var{d3}@}, @var{d0}} +@end itemize + + + + +@subsubsection Extended table lookup + +@itemize @bullet +@item poly8x8_t vtbx1_p8 (poly8x8_t, poly8x8_t, uint8x8_t) +@*@emph{Form of expected instruction(s):} @code{vtbx.8 @var{d0}, @{@var{d0}@}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int8x8_t vtbx1_s8 (int8x8_t, int8x8_t, int8x8_t) +@*@emph{Form of expected instruction(s):} @code{vtbx.8 @var{d0}, @{@var{d0}@}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint8x8_t vtbx1_u8 (uint8x8_t, uint8x8_t, uint8x8_t) +@*@emph{Form of expected instruction(s):} @code{vtbx.8 @var{d0}, @{@var{d0}@}, @var{d0}} +@end itemize + + +@itemize @bullet +@item poly8x8_t vtbx2_p8 (poly8x8_t, poly8x8x2_t, uint8x8_t) +@*@emph{Form of expected instruction(s):} @code{vtbx.8 @var{d0}, @{@var{d0}, @var{d1}@}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int8x8_t vtbx2_s8 (int8x8_t, int8x8x2_t, int8x8_t) +@*@emph{Form of expected instruction(s):} @code{vtbx.8 @var{d0}, @{@var{d0}, @var{d1}@}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint8x8_t vtbx2_u8 (uint8x8_t, uint8x8x2_t, uint8x8_t) +@*@emph{Form of expected instruction(s):} @code{vtbx.8 @var{d0}, @{@var{d0}, @var{d1}@}, @var{d0}} +@end itemize + + +@itemize @bullet +@item poly8x8_t vtbx3_p8 (poly8x8_t, poly8x8x3_t, uint8x8_t) +@*@emph{Form of expected instruction(s):} @code{vtbx.8 @var{d0}, @{@var{d0}, @var{d1}, @var{d2}@}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int8x8_t vtbx3_s8 (int8x8_t, int8x8x3_t, int8x8_t) +@*@emph{Form of expected instruction(s):} @code{vtbx.8 @var{d0}, @{@var{d0}, @var{d1}, @var{d2}@}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint8x8_t vtbx3_u8 (uint8x8_t, uint8x8x3_t, uint8x8_t) +@*@emph{Form of expected instruction(s):} @code{vtbx.8 @var{d0}, @{@var{d0}, @var{d1}, @var{d2}@}, @var{d0}} +@end itemize + + +@itemize @bullet +@item poly8x8_t vtbx4_p8 (poly8x8_t, poly8x8x4_t, uint8x8_t) +@*@emph{Form of expected instruction(s):} @code{vtbx.8 @var{d0}, @{@var{d0}, @var{d1}, @var{d2}, @var{d3}@}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int8x8_t vtbx4_s8 (int8x8_t, int8x8x4_t, int8x8_t) +@*@emph{Form of expected instruction(s):} @code{vtbx.8 @var{d0}, @{@var{d0}, @var{d1}, @var{d2}, @var{d3}@}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint8x8_t vtbx4_u8 (uint8x8_t, uint8x8x4_t, uint8x8_t) +@*@emph{Form of expected instruction(s):} @code{vtbx.8 @var{d0}, @{@var{d0}, @var{d1}, @var{d2}, @var{d3}@}, @var{d0}} +@end itemize + + + + +@subsubsection Multiply, lane + +@itemize @bullet +@item float32x2_t vmul_lane_f32 (float32x2_t, float32x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vmul.f32 @var{d0}, @var{d0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item uint32x2_t vmul_lane_u32 (uint32x2_t, uint32x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vmul.i32 @var{d0}, @var{d0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item uint16x4_t vmul_lane_u16 (uint16x4_t, uint16x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vmul.i16 @var{d0}, @var{d0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item int32x2_t vmul_lane_s32 (int32x2_t, int32x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vmul.i32 @var{d0}, @var{d0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item int16x4_t vmul_lane_s16 (int16x4_t, int16x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vmul.i16 @var{d0}, @var{d0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item float32x4_t vmulq_lane_f32 (float32x4_t, float32x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vmul.f32 @var{q0}, @var{q0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item uint32x4_t vmulq_lane_u32 (uint32x4_t, uint32x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vmul.i32 @var{q0}, @var{q0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item uint16x8_t vmulq_lane_u16 (uint16x8_t, uint16x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vmul.i16 @var{q0}, @var{q0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item int32x4_t vmulq_lane_s32 (int32x4_t, int32x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vmul.i32 @var{q0}, @var{q0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item int16x8_t vmulq_lane_s16 (int16x8_t, int16x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vmul.i16 @var{q0}, @var{q0}, @var{d0}[@var{0}]} +@end itemize + + + + +@subsubsection Long multiply, lane + +@itemize @bullet +@item uint64x2_t vmull_lane_u32 (uint32x2_t, uint32x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vmull.u32 @var{q0}, @var{d0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item uint32x4_t vmull_lane_u16 (uint16x4_t, uint16x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vmull.u16 @var{q0}, @var{d0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item int64x2_t vmull_lane_s32 (int32x2_t, int32x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vmull.s32 @var{q0}, @var{d0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item int32x4_t vmull_lane_s16 (int16x4_t, int16x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vmull.s16 @var{q0}, @var{d0}, @var{d0}[@var{0}]} +@end itemize + + + + +@subsubsection Saturating doubling long multiply, lane + +@itemize @bullet +@item int64x2_t vqdmull_lane_s32 (int32x2_t, int32x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vqdmull.s32 @var{q0}, @var{d0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item int32x4_t vqdmull_lane_s16 (int16x4_t, int16x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vqdmull.s16 @var{q0}, @var{d0}, @var{d0}[@var{0}]} +@end itemize + + + + +@subsubsection Saturating doubling multiply high, lane + +@itemize @bullet +@item int32x4_t vqdmulhq_lane_s32 (int32x4_t, int32x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vqdmulh.s32 @var{q0}, @var{q0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item int16x8_t vqdmulhq_lane_s16 (int16x8_t, int16x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vqdmulh.s16 @var{q0}, @var{q0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item int32x2_t vqdmulh_lane_s32 (int32x2_t, int32x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vqdmulh.s32 @var{d0}, @var{d0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item int16x4_t vqdmulh_lane_s16 (int16x4_t, int16x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vqdmulh.s16 @var{d0}, @var{d0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item int32x4_t vqrdmulhq_lane_s32 (int32x4_t, int32x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vqrdmulh.s32 @var{q0}, @var{q0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item int16x8_t vqrdmulhq_lane_s16 (int16x8_t, int16x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vqrdmulh.s16 @var{q0}, @var{q0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item int32x2_t vqrdmulh_lane_s32 (int32x2_t, int32x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vqrdmulh.s32 @var{d0}, @var{d0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item int16x4_t vqrdmulh_lane_s16 (int16x4_t, int16x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vqrdmulh.s16 @var{d0}, @var{d0}, @var{d0}[@var{0}]} +@end itemize + + + + +@subsubsection Multiply-accumulate, lane + +@itemize @bullet +@item float32x2_t vmla_lane_f32 (float32x2_t, float32x2_t, float32x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vmla.f32 @var{d0}, @var{d0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item uint32x2_t vmla_lane_u32 (uint32x2_t, uint32x2_t, uint32x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vmla.i32 @var{d0}, @var{d0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item uint16x4_t vmla_lane_u16 (uint16x4_t, uint16x4_t, uint16x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vmla.i16 @var{d0}, @var{d0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item int32x2_t vmla_lane_s32 (int32x2_t, int32x2_t, int32x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vmla.i32 @var{d0}, @var{d0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item int16x4_t vmla_lane_s16 (int16x4_t, int16x4_t, int16x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vmla.i16 @var{d0}, @var{d0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item float32x4_t vmlaq_lane_f32 (float32x4_t, float32x4_t, float32x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vmla.f32 @var{q0}, @var{q0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item uint32x4_t vmlaq_lane_u32 (uint32x4_t, uint32x4_t, uint32x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vmla.i32 @var{q0}, @var{q0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item uint16x8_t vmlaq_lane_u16 (uint16x8_t, uint16x8_t, uint16x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vmla.i16 @var{q0}, @var{q0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item int32x4_t vmlaq_lane_s32 (int32x4_t, int32x4_t, int32x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vmla.i32 @var{q0}, @var{q0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item int16x8_t vmlaq_lane_s16 (int16x8_t, int16x8_t, int16x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vmla.i16 @var{q0}, @var{q0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item uint64x2_t vmlal_lane_u32 (uint64x2_t, uint32x2_t, uint32x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vmlal.u32 @var{q0}, @var{d0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item uint32x4_t vmlal_lane_u16 (uint32x4_t, uint16x4_t, uint16x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vmlal.u16 @var{q0}, @var{d0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item int64x2_t vmlal_lane_s32 (int64x2_t, int32x2_t, int32x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vmlal.s32 @var{q0}, @var{d0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item int32x4_t vmlal_lane_s16 (int32x4_t, int16x4_t, int16x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vmlal.s16 @var{q0}, @var{d0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item int64x2_t vqdmlal_lane_s32 (int64x2_t, int32x2_t, int32x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vqdmlal.s32 @var{q0}, @var{d0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item int32x4_t vqdmlal_lane_s16 (int32x4_t, int16x4_t, int16x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vqdmlal.s16 @var{q0}, @var{d0}, @var{d0}[@var{0}]} +@end itemize + + + + +@subsubsection Multiply-subtract, lane + +@itemize @bullet +@item float32x2_t vmls_lane_f32 (float32x2_t, float32x2_t, float32x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vmls.f32 @var{d0}, @var{d0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item uint32x2_t vmls_lane_u32 (uint32x2_t, uint32x2_t, uint32x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vmls.i32 @var{d0}, @var{d0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item uint16x4_t vmls_lane_u16 (uint16x4_t, uint16x4_t, uint16x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vmls.i16 @var{d0}, @var{d0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item int32x2_t vmls_lane_s32 (int32x2_t, int32x2_t, int32x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vmls.i32 @var{d0}, @var{d0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item int16x4_t vmls_lane_s16 (int16x4_t, int16x4_t, int16x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vmls.i16 @var{d0}, @var{d0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item float32x4_t vmlsq_lane_f32 (float32x4_t, float32x4_t, float32x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vmls.f32 @var{q0}, @var{q0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item uint32x4_t vmlsq_lane_u32 (uint32x4_t, uint32x4_t, uint32x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vmls.i32 @var{q0}, @var{q0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item uint16x8_t vmlsq_lane_u16 (uint16x8_t, uint16x8_t, uint16x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vmls.i16 @var{q0}, @var{q0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item int32x4_t vmlsq_lane_s32 (int32x4_t, int32x4_t, int32x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vmls.i32 @var{q0}, @var{q0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item int16x8_t vmlsq_lane_s16 (int16x8_t, int16x8_t, int16x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vmls.i16 @var{q0}, @var{q0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item uint64x2_t vmlsl_lane_u32 (uint64x2_t, uint32x2_t, uint32x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vmlsl.u32 @var{q0}, @var{d0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item uint32x4_t vmlsl_lane_u16 (uint32x4_t, uint16x4_t, uint16x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vmlsl.u16 @var{q0}, @var{d0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item int64x2_t vmlsl_lane_s32 (int64x2_t, int32x2_t, int32x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vmlsl.s32 @var{q0}, @var{d0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item int32x4_t vmlsl_lane_s16 (int32x4_t, int16x4_t, int16x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vmlsl.s16 @var{q0}, @var{d0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item int64x2_t vqdmlsl_lane_s32 (int64x2_t, int32x2_t, int32x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vqdmlsl.s32 @var{q0}, @var{d0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item int32x4_t vqdmlsl_lane_s16 (int32x4_t, int16x4_t, int16x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vqdmlsl.s16 @var{q0}, @var{d0}, @var{d0}[@var{0}]} +@end itemize + + + + +@subsubsection Vector multiply by scalar + +@itemize @bullet +@item float32x2_t vmul_n_f32 (float32x2_t, float32_t) +@*@emph{Form of expected instruction(s):} @code{vmul.f32 @var{d0}, @var{d0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item uint32x2_t vmul_n_u32 (uint32x2_t, uint32_t) +@*@emph{Form of expected instruction(s):} @code{vmul.i32 @var{d0}, @var{d0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item uint16x4_t vmul_n_u16 (uint16x4_t, uint16_t) +@*@emph{Form of expected instruction(s):} @code{vmul.i16 @var{d0}, @var{d0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item int32x2_t vmul_n_s32 (int32x2_t, int32_t) +@*@emph{Form of expected instruction(s):} @code{vmul.i32 @var{d0}, @var{d0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item int16x4_t vmul_n_s16 (int16x4_t, int16_t) +@*@emph{Form of expected instruction(s):} @code{vmul.i16 @var{d0}, @var{d0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item float32x4_t vmulq_n_f32 (float32x4_t, float32_t) +@*@emph{Form of expected instruction(s):} @code{vmul.f32 @var{q0}, @var{q0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item uint32x4_t vmulq_n_u32 (uint32x4_t, uint32_t) +@*@emph{Form of expected instruction(s):} @code{vmul.i32 @var{q0}, @var{q0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item uint16x8_t vmulq_n_u16 (uint16x8_t, uint16_t) +@*@emph{Form of expected instruction(s):} @code{vmul.i16 @var{q0}, @var{q0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item int32x4_t vmulq_n_s32 (int32x4_t, int32_t) +@*@emph{Form of expected instruction(s):} @code{vmul.i32 @var{q0}, @var{q0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item int16x8_t vmulq_n_s16 (int16x8_t, int16_t) +@*@emph{Form of expected instruction(s):} @code{vmul.i16 @var{q0}, @var{q0}, @var{d0}[@var{0}]} +@end itemize + + + + +@subsubsection Vector long multiply by scalar + +@itemize @bullet +@item uint64x2_t vmull_n_u32 (uint32x2_t, uint32_t) +@*@emph{Form of expected instruction(s):} @code{vmull.u32 @var{q0}, @var{d0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item uint32x4_t vmull_n_u16 (uint16x4_t, uint16_t) +@*@emph{Form of expected instruction(s):} @code{vmull.u16 @var{q0}, @var{d0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item int64x2_t vmull_n_s32 (int32x2_t, int32_t) +@*@emph{Form of expected instruction(s):} @code{vmull.s32 @var{q0}, @var{d0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item int32x4_t vmull_n_s16 (int16x4_t, int16_t) +@*@emph{Form of expected instruction(s):} @code{vmull.s16 @var{q0}, @var{d0}, @var{d0}[@var{0}]} +@end itemize + + + + +@subsubsection Vector saturating doubling long multiply by scalar + +@itemize @bullet +@item int64x2_t vqdmull_n_s32 (int32x2_t, int32_t) +@*@emph{Form of expected instruction(s):} @code{vqdmull.s32 @var{q0}, @var{d0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item int32x4_t vqdmull_n_s16 (int16x4_t, int16_t) +@*@emph{Form of expected instruction(s):} @code{vqdmull.s16 @var{q0}, @var{d0}, @var{d0}[@var{0}]} +@end itemize + + + + +@subsubsection Vector saturating doubling multiply high by scalar + +@itemize @bullet +@item int32x4_t vqdmulhq_n_s32 (int32x4_t, int32_t) +@*@emph{Form of expected instruction(s):} @code{vqdmulh.s32 @var{q0}, @var{q0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item int16x8_t vqdmulhq_n_s16 (int16x8_t, int16_t) +@*@emph{Form of expected instruction(s):} @code{vqdmulh.s16 @var{q0}, @var{q0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item int32x2_t vqdmulh_n_s32 (int32x2_t, int32_t) +@*@emph{Form of expected instruction(s):} @code{vqdmulh.s32 @var{d0}, @var{d0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item int16x4_t vqdmulh_n_s16 (int16x4_t, int16_t) +@*@emph{Form of expected instruction(s):} @code{vqdmulh.s16 @var{d0}, @var{d0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item int32x4_t vqrdmulhq_n_s32 (int32x4_t, int32_t) +@*@emph{Form of expected instruction(s):} @code{vqrdmulh.s32 @var{q0}, @var{q0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item int16x8_t vqrdmulhq_n_s16 (int16x8_t, int16_t) +@*@emph{Form of expected instruction(s):} @code{vqrdmulh.s16 @var{q0}, @var{q0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item int32x2_t vqrdmulh_n_s32 (int32x2_t, int32_t) +@*@emph{Form of expected instruction(s):} @code{vqrdmulh.s32 @var{d0}, @var{d0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item int16x4_t vqrdmulh_n_s16 (int16x4_t, int16_t) +@*@emph{Form of expected instruction(s):} @code{vqrdmulh.s16 @var{d0}, @var{d0}, @var{d0}[@var{0}]} +@end itemize + + + + +@subsubsection Vector multiply-accumulate by scalar + +@itemize @bullet +@item float32x2_t vmla_n_f32 (float32x2_t, float32x2_t, float32_t) +@*@emph{Form of expected instruction(s):} @code{vmla.f32 @var{d0}, @var{d0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item uint32x2_t vmla_n_u32 (uint32x2_t, uint32x2_t, uint32_t) +@*@emph{Form of expected instruction(s):} @code{vmla.i32 @var{d0}, @var{d0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item uint16x4_t vmla_n_u16 (uint16x4_t, uint16x4_t, uint16_t) +@*@emph{Form of expected instruction(s):} @code{vmla.i16 @var{d0}, @var{d0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item int32x2_t vmla_n_s32 (int32x2_t, int32x2_t, int32_t) +@*@emph{Form of expected instruction(s):} @code{vmla.i32 @var{d0}, @var{d0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item int16x4_t vmla_n_s16 (int16x4_t, int16x4_t, int16_t) +@*@emph{Form of expected instruction(s):} @code{vmla.i16 @var{d0}, @var{d0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item float32x4_t vmlaq_n_f32 (float32x4_t, float32x4_t, float32_t) +@*@emph{Form of expected instruction(s):} @code{vmla.f32 @var{q0}, @var{q0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item uint32x4_t vmlaq_n_u32 (uint32x4_t, uint32x4_t, uint32_t) +@*@emph{Form of expected instruction(s):} @code{vmla.i32 @var{q0}, @var{q0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item uint16x8_t vmlaq_n_u16 (uint16x8_t, uint16x8_t, uint16_t) +@*@emph{Form of expected instruction(s):} @code{vmla.i16 @var{q0}, @var{q0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item int32x4_t vmlaq_n_s32 (int32x4_t, int32x4_t, int32_t) +@*@emph{Form of expected instruction(s):} @code{vmla.i32 @var{q0}, @var{q0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item int16x8_t vmlaq_n_s16 (int16x8_t, int16x8_t, int16_t) +@*@emph{Form of expected instruction(s):} @code{vmla.i16 @var{q0}, @var{q0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item uint64x2_t vmlal_n_u32 (uint64x2_t, uint32x2_t, uint32_t) +@*@emph{Form of expected instruction(s):} @code{vmlal.u32 @var{q0}, @var{d0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item uint32x4_t vmlal_n_u16 (uint32x4_t, uint16x4_t, uint16_t) +@*@emph{Form of expected instruction(s):} @code{vmlal.u16 @var{q0}, @var{d0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item int64x2_t vmlal_n_s32 (int64x2_t, int32x2_t, int32_t) +@*@emph{Form of expected instruction(s):} @code{vmlal.s32 @var{q0}, @var{d0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item int32x4_t vmlal_n_s16 (int32x4_t, int16x4_t, int16_t) +@*@emph{Form of expected instruction(s):} @code{vmlal.s16 @var{q0}, @var{d0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item int64x2_t vqdmlal_n_s32 (int64x2_t, int32x2_t, int32_t) +@*@emph{Form of expected instruction(s):} @code{vqdmlal.s32 @var{q0}, @var{d0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item int32x4_t vqdmlal_n_s16 (int32x4_t, int16x4_t, int16_t) +@*@emph{Form of expected instruction(s):} @code{vqdmlal.s16 @var{q0}, @var{d0}, @var{d0}[@var{0}]} +@end itemize + + + + +@subsubsection Vector multiply-subtract by scalar + +@itemize @bullet +@item float32x2_t vmls_n_f32 (float32x2_t, float32x2_t, float32_t) +@*@emph{Form of expected instruction(s):} @code{vmls.f32 @var{d0}, @var{d0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item uint32x2_t vmls_n_u32 (uint32x2_t, uint32x2_t, uint32_t) +@*@emph{Form of expected instruction(s):} @code{vmls.i32 @var{d0}, @var{d0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item uint16x4_t vmls_n_u16 (uint16x4_t, uint16x4_t, uint16_t) +@*@emph{Form of expected instruction(s):} @code{vmls.i16 @var{d0}, @var{d0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item int32x2_t vmls_n_s32 (int32x2_t, int32x2_t, int32_t) +@*@emph{Form of expected instruction(s):} @code{vmls.i32 @var{d0}, @var{d0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item int16x4_t vmls_n_s16 (int16x4_t, int16x4_t, int16_t) +@*@emph{Form of expected instruction(s):} @code{vmls.i16 @var{d0}, @var{d0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item float32x4_t vmlsq_n_f32 (float32x4_t, float32x4_t, float32_t) +@*@emph{Form of expected instruction(s):} @code{vmls.f32 @var{q0}, @var{q0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item uint32x4_t vmlsq_n_u32 (uint32x4_t, uint32x4_t, uint32_t) +@*@emph{Form of expected instruction(s):} @code{vmls.i32 @var{q0}, @var{q0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item uint16x8_t vmlsq_n_u16 (uint16x8_t, uint16x8_t, uint16_t) +@*@emph{Form of expected instruction(s):} @code{vmls.i16 @var{q0}, @var{q0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item int32x4_t vmlsq_n_s32 (int32x4_t, int32x4_t, int32_t) +@*@emph{Form of expected instruction(s):} @code{vmls.i32 @var{q0}, @var{q0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item int16x8_t vmlsq_n_s16 (int16x8_t, int16x8_t, int16_t) +@*@emph{Form of expected instruction(s):} @code{vmls.i16 @var{q0}, @var{q0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item uint64x2_t vmlsl_n_u32 (uint64x2_t, uint32x2_t, uint32_t) +@*@emph{Form of expected instruction(s):} @code{vmlsl.u32 @var{q0}, @var{d0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item uint32x4_t vmlsl_n_u16 (uint32x4_t, uint16x4_t, uint16_t) +@*@emph{Form of expected instruction(s):} @code{vmlsl.u16 @var{q0}, @var{d0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item int64x2_t vmlsl_n_s32 (int64x2_t, int32x2_t, int32_t) +@*@emph{Form of expected instruction(s):} @code{vmlsl.s32 @var{q0}, @var{d0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item int32x4_t vmlsl_n_s16 (int32x4_t, int16x4_t, int16_t) +@*@emph{Form of expected instruction(s):} @code{vmlsl.s16 @var{q0}, @var{d0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item int64x2_t vqdmlsl_n_s32 (int64x2_t, int32x2_t, int32_t) +@*@emph{Form of expected instruction(s):} @code{vqdmlsl.s32 @var{q0}, @var{d0}, @var{d0}[@var{0}]} +@end itemize + + +@itemize @bullet +@item int32x4_t vqdmlsl_n_s16 (int32x4_t, int16x4_t, int16_t) +@*@emph{Form of expected instruction(s):} @code{vqdmlsl.s16 @var{q0}, @var{d0}, @var{d0}[@var{0}]} +@end itemize + + + + +@subsubsection Vector extract + +@itemize @bullet +@item uint32x2_t vext_u32 (uint32x2_t, uint32x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vext.32 @var{d0}, @var{d0}, @var{d0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item uint16x4_t vext_u16 (uint16x4_t, uint16x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vext.16 @var{d0}, @var{d0}, @var{d0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item uint8x8_t vext_u8 (uint8x8_t, uint8x8_t, const int) +@*@emph{Form of expected instruction(s):} @code{vext.8 @var{d0}, @var{d0}, @var{d0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item int32x2_t vext_s32 (int32x2_t, int32x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vext.32 @var{d0}, @var{d0}, @var{d0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item int16x4_t vext_s16 (int16x4_t, int16x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vext.16 @var{d0}, @var{d0}, @var{d0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item int8x8_t vext_s8 (int8x8_t, int8x8_t, const int) +@*@emph{Form of expected instruction(s):} @code{vext.8 @var{d0}, @var{d0}, @var{d0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item uint64x1_t vext_u64 (uint64x1_t, uint64x1_t, const int) +@*@emph{Form of expected instruction(s):} @code{vext.64 @var{d0}, @var{d0}, @var{d0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item int64x1_t vext_s64 (int64x1_t, int64x1_t, const int) +@*@emph{Form of expected instruction(s):} @code{vext.64 @var{d0}, @var{d0}, @var{d0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item float32x2_t vext_f32 (float32x2_t, float32x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vext.32 @var{d0}, @var{d0}, @var{d0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item poly16x4_t vext_p16 (poly16x4_t, poly16x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vext.16 @var{d0}, @var{d0}, @var{d0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item poly8x8_t vext_p8 (poly8x8_t, poly8x8_t, const int) +@*@emph{Form of expected instruction(s):} @code{vext.8 @var{d0}, @var{d0}, @var{d0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item uint32x4_t vextq_u32 (uint32x4_t, uint32x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vext.32 @var{q0}, @var{q0}, @var{q0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item uint16x8_t vextq_u16 (uint16x8_t, uint16x8_t, const int) +@*@emph{Form of expected instruction(s):} @code{vext.16 @var{q0}, @var{q0}, @var{q0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item uint8x16_t vextq_u8 (uint8x16_t, uint8x16_t, const int) +@*@emph{Form of expected instruction(s):} @code{vext.8 @var{q0}, @var{q0}, @var{q0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item int32x4_t vextq_s32 (int32x4_t, int32x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vext.32 @var{q0}, @var{q0}, @var{q0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item int16x8_t vextq_s16 (int16x8_t, int16x8_t, const int) +@*@emph{Form of expected instruction(s):} @code{vext.16 @var{q0}, @var{q0}, @var{q0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item int8x16_t vextq_s8 (int8x16_t, int8x16_t, const int) +@*@emph{Form of expected instruction(s):} @code{vext.8 @var{q0}, @var{q0}, @var{q0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item uint64x2_t vextq_u64 (uint64x2_t, uint64x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vext.64 @var{q0}, @var{q0}, @var{q0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item int64x2_t vextq_s64 (int64x2_t, int64x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vext.64 @var{q0}, @var{q0}, @var{q0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item float32x4_t vextq_f32 (float32x4_t, float32x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vext.32 @var{q0}, @var{q0}, @var{q0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item poly16x8_t vextq_p16 (poly16x8_t, poly16x8_t, const int) +@*@emph{Form of expected instruction(s):} @code{vext.16 @var{q0}, @var{q0}, @var{q0}, #@var{0}} +@end itemize + + +@itemize @bullet +@item poly8x16_t vextq_p8 (poly8x16_t, poly8x16_t, const int) +@*@emph{Form of expected instruction(s):} @code{vext.8 @var{q0}, @var{q0}, @var{q0}, #@var{0}} +@end itemize + + + + +@subsubsection Reverse elements + +@itemize @bullet +@item uint32x2_t vrev64_u32 (uint32x2_t) +@*@emph{Form of expected instruction(s):} @code{vrev64.32 @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint16x4_t vrev64_u16 (uint16x4_t) +@*@emph{Form of expected instruction(s):} @code{vrev64.16 @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint8x8_t vrev64_u8 (uint8x8_t) +@*@emph{Form of expected instruction(s):} @code{vrev64.8 @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int32x2_t vrev64_s32 (int32x2_t) +@*@emph{Form of expected instruction(s):} @code{vrev64.32 @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int16x4_t vrev64_s16 (int16x4_t) +@*@emph{Form of expected instruction(s):} @code{vrev64.16 @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int8x8_t vrev64_s8 (int8x8_t) +@*@emph{Form of expected instruction(s):} @code{vrev64.8 @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item float32x2_t vrev64_f32 (float32x2_t) +@*@emph{Form of expected instruction(s):} @code{vrev64.32 @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item poly16x4_t vrev64_p16 (poly16x4_t) +@*@emph{Form of expected instruction(s):} @code{vrev64.16 @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item poly8x8_t vrev64_p8 (poly8x8_t) +@*@emph{Form of expected instruction(s):} @code{vrev64.8 @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint32x4_t vrev64q_u32 (uint32x4_t) +@*@emph{Form of expected instruction(s):} @code{vrev64.32 @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint16x8_t vrev64q_u16 (uint16x8_t) +@*@emph{Form of expected instruction(s):} @code{vrev64.16 @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint8x16_t vrev64q_u8 (uint8x16_t) +@*@emph{Form of expected instruction(s):} @code{vrev64.8 @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int32x4_t vrev64q_s32 (int32x4_t) +@*@emph{Form of expected instruction(s):} @code{vrev64.32 @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int16x8_t vrev64q_s16 (int16x8_t) +@*@emph{Form of expected instruction(s):} @code{vrev64.16 @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int8x16_t vrev64q_s8 (int8x16_t) +@*@emph{Form of expected instruction(s):} @code{vrev64.8 @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item float32x4_t vrev64q_f32 (float32x4_t) +@*@emph{Form of expected instruction(s):} @code{vrev64.32 @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item poly16x8_t vrev64q_p16 (poly16x8_t) +@*@emph{Form of expected instruction(s):} @code{vrev64.16 @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item poly8x16_t vrev64q_p8 (poly8x16_t) +@*@emph{Form of expected instruction(s):} @code{vrev64.8 @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint16x4_t vrev32_u16 (uint16x4_t) +@*@emph{Form of expected instruction(s):} @code{vrev32.16 @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int16x4_t vrev32_s16 (int16x4_t) +@*@emph{Form of expected instruction(s):} @code{vrev32.16 @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint8x8_t vrev32_u8 (uint8x8_t) +@*@emph{Form of expected instruction(s):} @code{vrev32.8 @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int8x8_t vrev32_s8 (int8x8_t) +@*@emph{Form of expected instruction(s):} @code{vrev32.8 @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item poly16x4_t vrev32_p16 (poly16x4_t) +@*@emph{Form of expected instruction(s):} @code{vrev32.16 @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item poly8x8_t vrev32_p8 (poly8x8_t) +@*@emph{Form of expected instruction(s):} @code{vrev32.8 @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint16x8_t vrev32q_u16 (uint16x8_t) +@*@emph{Form of expected instruction(s):} @code{vrev32.16 @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int16x8_t vrev32q_s16 (int16x8_t) +@*@emph{Form of expected instruction(s):} @code{vrev32.16 @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint8x16_t vrev32q_u8 (uint8x16_t) +@*@emph{Form of expected instruction(s):} @code{vrev32.8 @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int8x16_t vrev32q_s8 (int8x16_t) +@*@emph{Form of expected instruction(s):} @code{vrev32.8 @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item poly16x8_t vrev32q_p16 (poly16x8_t) +@*@emph{Form of expected instruction(s):} @code{vrev32.16 @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item poly8x16_t vrev32q_p8 (poly8x16_t) +@*@emph{Form of expected instruction(s):} @code{vrev32.8 @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint8x8_t vrev16_u8 (uint8x8_t) +@*@emph{Form of expected instruction(s):} @code{vrev16.8 @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int8x8_t vrev16_s8 (int8x8_t) +@*@emph{Form of expected instruction(s):} @code{vrev16.8 @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item poly8x8_t vrev16_p8 (poly8x8_t) +@*@emph{Form of expected instruction(s):} @code{vrev16.8 @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint8x16_t vrev16q_u8 (uint8x16_t) +@*@emph{Form of expected instruction(s):} @code{vrev16.8 @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int8x16_t vrev16q_s8 (int8x16_t) +@*@emph{Form of expected instruction(s):} @code{vrev16.8 @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item poly8x16_t vrev16q_p8 (poly8x16_t) +@*@emph{Form of expected instruction(s):} @code{vrev16.8 @var{q0}, @var{q0}} +@end itemize + + + + +@subsubsection Bit selection + +@itemize @bullet +@item uint32x2_t vbsl_u32 (uint32x2_t, uint32x2_t, uint32x2_t) +@*@emph{Form of expected instruction(s):} @code{vbsl @var{d0}, @var{d0}, @var{d0}} @emph{or} @code{vbit @var{d0}, @var{d0}, @var{d0}} @emph{or} @code{vbif @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint16x4_t vbsl_u16 (uint16x4_t, uint16x4_t, uint16x4_t) +@*@emph{Form of expected instruction(s):} @code{vbsl @var{d0}, @var{d0}, @var{d0}} @emph{or} @code{vbit @var{d0}, @var{d0}, @var{d0}} @emph{or} @code{vbif @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint8x8_t vbsl_u8 (uint8x8_t, uint8x8_t, uint8x8_t) +@*@emph{Form of expected instruction(s):} @code{vbsl @var{d0}, @var{d0}, @var{d0}} @emph{or} @code{vbit @var{d0}, @var{d0}, @var{d0}} @emph{or} @code{vbif @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int32x2_t vbsl_s32 (uint32x2_t, int32x2_t, int32x2_t) +@*@emph{Form of expected instruction(s):} @code{vbsl @var{d0}, @var{d0}, @var{d0}} @emph{or} @code{vbit @var{d0}, @var{d0}, @var{d0}} @emph{or} @code{vbif @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int16x4_t vbsl_s16 (uint16x4_t, int16x4_t, int16x4_t) +@*@emph{Form of expected instruction(s):} @code{vbsl @var{d0}, @var{d0}, @var{d0}} @emph{or} @code{vbit @var{d0}, @var{d0}, @var{d0}} @emph{or} @code{vbif @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int8x8_t vbsl_s8 (uint8x8_t, int8x8_t, int8x8_t) +@*@emph{Form of expected instruction(s):} @code{vbsl @var{d0}, @var{d0}, @var{d0}} @emph{or} @code{vbit @var{d0}, @var{d0}, @var{d0}} @emph{or} @code{vbif @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint64x1_t vbsl_u64 (uint64x1_t, uint64x1_t, uint64x1_t) +@*@emph{Form of expected instruction(s):} @code{vbsl @var{d0}, @var{d0}, @var{d0}} @emph{or} @code{vbit @var{d0}, @var{d0}, @var{d0}} @emph{or} @code{vbif @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int64x1_t vbsl_s64 (uint64x1_t, int64x1_t, int64x1_t) +@*@emph{Form of expected instruction(s):} @code{vbsl @var{d0}, @var{d0}, @var{d0}} @emph{or} @code{vbit @var{d0}, @var{d0}, @var{d0}} @emph{or} @code{vbif @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item float32x2_t vbsl_f32 (uint32x2_t, float32x2_t, float32x2_t) +@*@emph{Form of expected instruction(s):} @code{vbsl @var{d0}, @var{d0}, @var{d0}} @emph{or} @code{vbit @var{d0}, @var{d0}, @var{d0}} @emph{or} @code{vbif @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item poly16x4_t vbsl_p16 (uint16x4_t, poly16x4_t, poly16x4_t) +@*@emph{Form of expected instruction(s):} @code{vbsl @var{d0}, @var{d0}, @var{d0}} @emph{or} @code{vbit @var{d0}, @var{d0}, @var{d0}} @emph{or} @code{vbif @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item poly8x8_t vbsl_p8 (uint8x8_t, poly8x8_t, poly8x8_t) +@*@emph{Form of expected instruction(s):} @code{vbsl @var{d0}, @var{d0}, @var{d0}} @emph{or} @code{vbit @var{d0}, @var{d0}, @var{d0}} @emph{or} @code{vbif @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint32x4_t vbslq_u32 (uint32x4_t, uint32x4_t, uint32x4_t) +@*@emph{Form of expected instruction(s):} @code{vbsl @var{q0}, @var{q0}, @var{q0}} @emph{or} @code{vbit @var{q0}, @var{q0}, @var{q0}} @emph{or} @code{vbif @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint16x8_t vbslq_u16 (uint16x8_t, uint16x8_t, uint16x8_t) +@*@emph{Form of expected instruction(s):} @code{vbsl @var{q0}, @var{q0}, @var{q0}} @emph{or} @code{vbit @var{q0}, @var{q0}, @var{q0}} @emph{or} @code{vbif @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint8x16_t vbslq_u8 (uint8x16_t, uint8x16_t, uint8x16_t) +@*@emph{Form of expected instruction(s):} @code{vbsl @var{q0}, @var{q0}, @var{q0}} @emph{or} @code{vbit @var{q0}, @var{q0}, @var{q0}} @emph{or} @code{vbif @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int32x4_t vbslq_s32 (uint32x4_t, int32x4_t, int32x4_t) +@*@emph{Form of expected instruction(s):} @code{vbsl @var{q0}, @var{q0}, @var{q0}} @emph{or} @code{vbit @var{q0}, @var{q0}, @var{q0}} @emph{or} @code{vbif @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int16x8_t vbslq_s16 (uint16x8_t, int16x8_t, int16x8_t) +@*@emph{Form of expected instruction(s):} @code{vbsl @var{q0}, @var{q0}, @var{q0}} @emph{or} @code{vbit @var{q0}, @var{q0}, @var{q0}} @emph{or} @code{vbif @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int8x16_t vbslq_s8 (uint8x16_t, int8x16_t, int8x16_t) +@*@emph{Form of expected instruction(s):} @code{vbsl @var{q0}, @var{q0}, @var{q0}} @emph{or} @code{vbit @var{q0}, @var{q0}, @var{q0}} @emph{or} @code{vbif @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint64x2_t vbslq_u64 (uint64x2_t, uint64x2_t, uint64x2_t) +@*@emph{Form of expected instruction(s):} @code{vbsl @var{q0}, @var{q0}, @var{q0}} @emph{or} @code{vbit @var{q0}, @var{q0}, @var{q0}} @emph{or} @code{vbif @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int64x2_t vbslq_s64 (uint64x2_t, int64x2_t, int64x2_t) +@*@emph{Form of expected instruction(s):} @code{vbsl @var{q0}, @var{q0}, @var{q0}} @emph{or} @code{vbit @var{q0}, @var{q0}, @var{q0}} @emph{or} @code{vbif @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item float32x4_t vbslq_f32 (uint32x4_t, float32x4_t, float32x4_t) +@*@emph{Form of expected instruction(s):} @code{vbsl @var{q0}, @var{q0}, @var{q0}} @emph{or} @code{vbit @var{q0}, @var{q0}, @var{q0}} @emph{or} @code{vbif @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item poly16x8_t vbslq_p16 (uint16x8_t, poly16x8_t, poly16x8_t) +@*@emph{Form of expected instruction(s):} @code{vbsl @var{q0}, @var{q0}, @var{q0}} @emph{or} @code{vbit @var{q0}, @var{q0}, @var{q0}} @emph{or} @code{vbif @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item poly8x16_t vbslq_p8 (uint8x16_t, poly8x16_t, poly8x16_t) +@*@emph{Form of expected instruction(s):} @code{vbsl @var{q0}, @var{q0}, @var{q0}} @emph{or} @code{vbit @var{q0}, @var{q0}, @var{q0}} @emph{or} @code{vbif @var{q0}, @var{q0}, @var{q0}} +@end itemize + + + + +@subsubsection Transpose elements + +@itemize @bullet +@item uint32x2x2_t vtrn_u32 (uint32x2_t, uint32x2_t) +@*@emph{Form of expected instruction(s):} @code{vtrn.32 @var{d0}, @var{d1}} +@end itemize + + +@itemize @bullet +@item uint16x4x2_t vtrn_u16 (uint16x4_t, uint16x4_t) +@*@emph{Form of expected instruction(s):} @code{vtrn.16 @var{d0}, @var{d1}} +@end itemize + + +@itemize @bullet +@item uint8x8x2_t vtrn_u8 (uint8x8_t, uint8x8_t) +@*@emph{Form of expected instruction(s):} @code{vtrn.8 @var{d0}, @var{d1}} +@end itemize + + +@itemize @bullet +@item int32x2x2_t vtrn_s32 (int32x2_t, int32x2_t) +@*@emph{Form of expected instruction(s):} @code{vtrn.32 @var{d0}, @var{d1}} +@end itemize + + +@itemize @bullet +@item int16x4x2_t vtrn_s16 (int16x4_t, int16x4_t) +@*@emph{Form of expected instruction(s):} @code{vtrn.16 @var{d0}, @var{d1}} +@end itemize + + +@itemize @bullet +@item int8x8x2_t vtrn_s8 (int8x8_t, int8x8_t) +@*@emph{Form of expected instruction(s):} @code{vtrn.8 @var{d0}, @var{d1}} +@end itemize + + +@itemize @bullet +@item float32x2x2_t vtrn_f32 (float32x2_t, float32x2_t) +@*@emph{Form of expected instruction(s):} @code{vtrn.32 @var{d0}, @var{d1}} +@end itemize + + +@itemize @bullet +@item poly16x4x2_t vtrn_p16 (poly16x4_t, poly16x4_t) +@*@emph{Form of expected instruction(s):} @code{vtrn.16 @var{d0}, @var{d1}} +@end itemize + + +@itemize @bullet +@item poly8x8x2_t vtrn_p8 (poly8x8_t, poly8x8_t) +@*@emph{Form of expected instruction(s):} @code{vtrn.8 @var{d0}, @var{d1}} +@end itemize + + +@itemize @bullet +@item uint32x4x2_t vtrnq_u32 (uint32x4_t, uint32x4_t) +@*@emph{Form of expected instruction(s):} @code{vtrn.32 @var{q0}, @var{q1}} +@end itemize + + +@itemize @bullet +@item uint16x8x2_t vtrnq_u16 (uint16x8_t, uint16x8_t) +@*@emph{Form of expected instruction(s):} @code{vtrn.16 @var{q0}, @var{q1}} +@end itemize + + +@itemize @bullet +@item uint8x16x2_t vtrnq_u8 (uint8x16_t, uint8x16_t) +@*@emph{Form of expected instruction(s):} @code{vtrn.8 @var{q0}, @var{q1}} +@end itemize + + +@itemize @bullet +@item int32x4x2_t vtrnq_s32 (int32x4_t, int32x4_t) +@*@emph{Form of expected instruction(s):} @code{vtrn.32 @var{q0}, @var{q1}} +@end itemize + + +@itemize @bullet +@item int16x8x2_t vtrnq_s16 (int16x8_t, int16x8_t) +@*@emph{Form of expected instruction(s):} @code{vtrn.16 @var{q0}, @var{q1}} +@end itemize + + +@itemize @bullet +@item int8x16x2_t vtrnq_s8 (int8x16_t, int8x16_t) +@*@emph{Form of expected instruction(s):} @code{vtrn.8 @var{q0}, @var{q1}} +@end itemize + + +@itemize @bullet +@item float32x4x2_t vtrnq_f32 (float32x4_t, float32x4_t) +@*@emph{Form of expected instruction(s):} @code{vtrn.32 @var{q0}, @var{q1}} +@end itemize + + +@itemize @bullet +@item poly16x8x2_t vtrnq_p16 (poly16x8_t, poly16x8_t) +@*@emph{Form of expected instruction(s):} @code{vtrn.16 @var{q0}, @var{q1}} +@end itemize + + +@itemize @bullet +@item poly8x16x2_t vtrnq_p8 (poly8x16_t, poly8x16_t) +@*@emph{Form of expected instruction(s):} @code{vtrn.8 @var{q0}, @var{q1}} +@end itemize + + + + +@subsubsection Zip elements + +@itemize @bullet +@item uint32x2x2_t vzip_u32 (uint32x2_t, uint32x2_t) +@*@emph{Form of expected instruction(s):} @code{vzip.32 @var{d0}, @var{d1}} +@end itemize + + +@itemize @bullet +@item uint16x4x2_t vzip_u16 (uint16x4_t, uint16x4_t) +@*@emph{Form of expected instruction(s):} @code{vzip.16 @var{d0}, @var{d1}} +@end itemize + + +@itemize @bullet +@item uint8x8x2_t vzip_u8 (uint8x8_t, uint8x8_t) +@*@emph{Form of expected instruction(s):} @code{vzip.8 @var{d0}, @var{d1}} +@end itemize + + +@itemize @bullet +@item int32x2x2_t vzip_s32 (int32x2_t, int32x2_t) +@*@emph{Form of expected instruction(s):} @code{vzip.32 @var{d0}, @var{d1}} +@end itemize + + +@itemize @bullet +@item int16x4x2_t vzip_s16 (int16x4_t, int16x4_t) +@*@emph{Form of expected instruction(s):} @code{vzip.16 @var{d0}, @var{d1}} +@end itemize + + +@itemize @bullet +@item int8x8x2_t vzip_s8 (int8x8_t, int8x8_t) +@*@emph{Form of expected instruction(s):} @code{vzip.8 @var{d0}, @var{d1}} +@end itemize + + +@itemize @bullet +@item float32x2x2_t vzip_f32 (float32x2_t, float32x2_t) +@*@emph{Form of expected instruction(s):} @code{vzip.32 @var{d0}, @var{d1}} +@end itemize + + +@itemize @bullet +@item poly16x4x2_t vzip_p16 (poly16x4_t, poly16x4_t) +@*@emph{Form of expected instruction(s):} @code{vzip.16 @var{d0}, @var{d1}} +@end itemize + + +@itemize @bullet +@item poly8x8x2_t vzip_p8 (poly8x8_t, poly8x8_t) +@*@emph{Form of expected instruction(s):} @code{vzip.8 @var{d0}, @var{d1}} +@end itemize + + +@itemize @bullet +@item uint32x4x2_t vzipq_u32 (uint32x4_t, uint32x4_t) +@*@emph{Form of expected instruction(s):} @code{vzip.32 @var{q0}, @var{q1}} +@end itemize + + +@itemize @bullet +@item uint16x8x2_t vzipq_u16 (uint16x8_t, uint16x8_t) +@*@emph{Form of expected instruction(s):} @code{vzip.16 @var{q0}, @var{q1}} +@end itemize + + +@itemize @bullet +@item uint8x16x2_t vzipq_u8 (uint8x16_t, uint8x16_t) +@*@emph{Form of expected instruction(s):} @code{vzip.8 @var{q0}, @var{q1}} +@end itemize + + +@itemize @bullet +@item int32x4x2_t vzipq_s32 (int32x4_t, int32x4_t) +@*@emph{Form of expected instruction(s):} @code{vzip.32 @var{q0}, @var{q1}} +@end itemize + + +@itemize @bullet +@item int16x8x2_t vzipq_s16 (int16x8_t, int16x8_t) +@*@emph{Form of expected instruction(s):} @code{vzip.16 @var{q0}, @var{q1}} +@end itemize + + +@itemize @bullet +@item int8x16x2_t vzipq_s8 (int8x16_t, int8x16_t) +@*@emph{Form of expected instruction(s):} @code{vzip.8 @var{q0}, @var{q1}} +@end itemize + + +@itemize @bullet +@item float32x4x2_t vzipq_f32 (float32x4_t, float32x4_t) +@*@emph{Form of expected instruction(s):} @code{vzip.32 @var{q0}, @var{q1}} +@end itemize + + +@itemize @bullet +@item poly16x8x2_t vzipq_p16 (poly16x8_t, poly16x8_t) +@*@emph{Form of expected instruction(s):} @code{vzip.16 @var{q0}, @var{q1}} +@end itemize + + +@itemize @bullet +@item poly8x16x2_t vzipq_p8 (poly8x16_t, poly8x16_t) +@*@emph{Form of expected instruction(s):} @code{vzip.8 @var{q0}, @var{q1}} +@end itemize + + + + +@subsubsection Unzip elements + +@itemize @bullet +@item uint32x2x2_t vuzp_u32 (uint32x2_t, uint32x2_t) +@*@emph{Form of expected instruction(s):} @code{vuzp.32 @var{d0}, @var{d1}} +@end itemize + + +@itemize @bullet +@item uint16x4x2_t vuzp_u16 (uint16x4_t, uint16x4_t) +@*@emph{Form of expected instruction(s):} @code{vuzp.16 @var{d0}, @var{d1}} +@end itemize + + +@itemize @bullet +@item uint8x8x2_t vuzp_u8 (uint8x8_t, uint8x8_t) +@*@emph{Form of expected instruction(s):} @code{vuzp.8 @var{d0}, @var{d1}} +@end itemize + + +@itemize @bullet +@item int32x2x2_t vuzp_s32 (int32x2_t, int32x2_t) +@*@emph{Form of expected instruction(s):} @code{vuzp.32 @var{d0}, @var{d1}} +@end itemize + + +@itemize @bullet +@item int16x4x2_t vuzp_s16 (int16x4_t, int16x4_t) +@*@emph{Form of expected instruction(s):} @code{vuzp.16 @var{d0}, @var{d1}} +@end itemize + + +@itemize @bullet +@item int8x8x2_t vuzp_s8 (int8x8_t, int8x8_t) +@*@emph{Form of expected instruction(s):} @code{vuzp.8 @var{d0}, @var{d1}} +@end itemize + + +@itemize @bullet +@item float32x2x2_t vuzp_f32 (float32x2_t, float32x2_t) +@*@emph{Form of expected instruction(s):} @code{vuzp.32 @var{d0}, @var{d1}} +@end itemize + + +@itemize @bullet +@item poly16x4x2_t vuzp_p16 (poly16x4_t, poly16x4_t) +@*@emph{Form of expected instruction(s):} @code{vuzp.16 @var{d0}, @var{d1}} +@end itemize + + +@itemize @bullet +@item poly8x8x2_t vuzp_p8 (poly8x8_t, poly8x8_t) +@*@emph{Form of expected instruction(s):} @code{vuzp.8 @var{d0}, @var{d1}} +@end itemize + + +@itemize @bullet +@item uint32x4x2_t vuzpq_u32 (uint32x4_t, uint32x4_t) +@*@emph{Form of expected instruction(s):} @code{vuzp.32 @var{q0}, @var{q1}} +@end itemize + + +@itemize @bullet +@item uint16x8x2_t vuzpq_u16 (uint16x8_t, uint16x8_t) +@*@emph{Form of expected instruction(s):} @code{vuzp.16 @var{q0}, @var{q1}} +@end itemize + + +@itemize @bullet +@item uint8x16x2_t vuzpq_u8 (uint8x16_t, uint8x16_t) +@*@emph{Form of expected instruction(s):} @code{vuzp.8 @var{q0}, @var{q1}} +@end itemize + + +@itemize @bullet +@item int32x4x2_t vuzpq_s32 (int32x4_t, int32x4_t) +@*@emph{Form of expected instruction(s):} @code{vuzp.32 @var{q0}, @var{q1}} +@end itemize + + +@itemize @bullet +@item int16x8x2_t vuzpq_s16 (int16x8_t, int16x8_t) +@*@emph{Form of expected instruction(s):} @code{vuzp.16 @var{q0}, @var{q1}} +@end itemize + + +@itemize @bullet +@item int8x16x2_t vuzpq_s8 (int8x16_t, int8x16_t) +@*@emph{Form of expected instruction(s):} @code{vuzp.8 @var{q0}, @var{q1}} +@end itemize + + +@itemize @bullet +@item float32x4x2_t vuzpq_f32 (float32x4_t, float32x4_t) +@*@emph{Form of expected instruction(s):} @code{vuzp.32 @var{q0}, @var{q1}} +@end itemize + + +@itemize @bullet +@item poly16x8x2_t vuzpq_p16 (poly16x8_t, poly16x8_t) +@*@emph{Form of expected instruction(s):} @code{vuzp.16 @var{q0}, @var{q1}} +@end itemize + + +@itemize @bullet +@item poly8x16x2_t vuzpq_p8 (poly8x16_t, poly8x16_t) +@*@emph{Form of expected instruction(s):} @code{vuzp.8 @var{q0}, @var{q1}} +@end itemize + + + + +@subsubsection Element/structure loads, VLD1 variants + +@itemize @bullet +@item uint32x2_t vld1_u32 (const uint32_t *) +@*@emph{Form of expected instruction(s):} @code{vld1.32 @{@var{d0}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item uint16x4_t vld1_u16 (const uint16_t *) +@*@emph{Form of expected instruction(s):} @code{vld1.16 @{@var{d0}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item uint8x8_t vld1_u8 (const uint8_t *) +@*@emph{Form of expected instruction(s):} @code{vld1.8 @{@var{d0}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item int32x2_t vld1_s32 (const int32_t *) +@*@emph{Form of expected instruction(s):} @code{vld1.32 @{@var{d0}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item int16x4_t vld1_s16 (const int16_t *) +@*@emph{Form of expected instruction(s):} @code{vld1.16 @{@var{d0}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item int8x8_t vld1_s8 (const int8_t *) +@*@emph{Form of expected instruction(s):} @code{vld1.8 @{@var{d0}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item uint64x1_t vld1_u64 (const uint64_t *) +@*@emph{Form of expected instruction(s):} @code{vld1.64 @{@var{d0}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item int64x1_t vld1_s64 (const int64_t *) +@*@emph{Form of expected instruction(s):} @code{vld1.64 @{@var{d0}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item float32x2_t vld1_f32 (const float32_t *) +@*@emph{Form of expected instruction(s):} @code{vld1.32 @{@var{d0}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item poly16x4_t vld1_p16 (const poly16_t *) +@*@emph{Form of expected instruction(s):} @code{vld1.16 @{@var{d0}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item poly8x8_t vld1_p8 (const poly8_t *) +@*@emph{Form of expected instruction(s):} @code{vld1.8 @{@var{d0}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item uint32x4_t vld1q_u32 (const uint32_t *) +@*@emph{Form of expected instruction(s):} @code{vld1.32 @{@var{d0}, @var{d1}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item uint16x8_t vld1q_u16 (const uint16_t *) +@*@emph{Form of expected instruction(s):} @code{vld1.16 @{@var{d0}, @var{d1}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item uint8x16_t vld1q_u8 (const uint8_t *) +@*@emph{Form of expected instruction(s):} @code{vld1.8 @{@var{d0}, @var{d1}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item int32x4_t vld1q_s32 (const int32_t *) +@*@emph{Form of expected instruction(s):} @code{vld1.32 @{@var{d0}, @var{d1}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item int16x8_t vld1q_s16 (const int16_t *) +@*@emph{Form of expected instruction(s):} @code{vld1.16 @{@var{d0}, @var{d1}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item int8x16_t vld1q_s8 (const int8_t *) +@*@emph{Form of expected instruction(s):} @code{vld1.8 @{@var{d0}, @var{d1}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item uint64x2_t vld1q_u64 (const uint64_t *) +@*@emph{Form of expected instruction(s):} @code{vld1.64 @{@var{d0}, @var{d1}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item int64x2_t vld1q_s64 (const int64_t *) +@*@emph{Form of expected instruction(s):} @code{vld1.64 @{@var{d0}, @var{d1}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item float32x4_t vld1q_f32 (const float32_t *) +@*@emph{Form of expected instruction(s):} @code{vld1.32 @{@var{d0}, @var{d1}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item poly16x8_t vld1q_p16 (const poly16_t *) +@*@emph{Form of expected instruction(s):} @code{vld1.16 @{@var{d0}, @var{d1}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item poly8x16_t vld1q_p8 (const poly8_t *) +@*@emph{Form of expected instruction(s):} @code{vld1.8 @{@var{d0}, @var{d1}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item uint32x2_t vld1_lane_u32 (const uint32_t *, uint32x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vld1.32 @{@var{d0}[@var{0}]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item uint16x4_t vld1_lane_u16 (const uint16_t *, uint16x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vld1.16 @{@var{d0}[@var{0}]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item uint8x8_t vld1_lane_u8 (const uint8_t *, uint8x8_t, const int) +@*@emph{Form of expected instruction(s):} @code{vld1.8 @{@var{d0}[@var{0}]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item int32x2_t vld1_lane_s32 (const int32_t *, int32x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vld1.32 @{@var{d0}[@var{0}]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item int16x4_t vld1_lane_s16 (const int16_t *, int16x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vld1.16 @{@var{d0}[@var{0}]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item int8x8_t vld1_lane_s8 (const int8_t *, int8x8_t, const int) +@*@emph{Form of expected instruction(s):} @code{vld1.8 @{@var{d0}[@var{0}]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item float32x2_t vld1_lane_f32 (const float32_t *, float32x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vld1.32 @{@var{d0}[@var{0}]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item poly16x4_t vld1_lane_p16 (const poly16_t *, poly16x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vld1.16 @{@var{d0}[@var{0}]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item poly8x8_t vld1_lane_p8 (const poly8_t *, poly8x8_t, const int) +@*@emph{Form of expected instruction(s):} @code{vld1.8 @{@var{d0}[@var{0}]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item uint64x1_t vld1_lane_u64 (const uint64_t *, uint64x1_t, const int) +@*@emph{Form of expected instruction(s):} @code{vld1.64 @{@var{d0}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item int64x1_t vld1_lane_s64 (const int64_t *, int64x1_t, const int) +@*@emph{Form of expected instruction(s):} @code{vld1.64 @{@var{d0}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item uint32x4_t vld1q_lane_u32 (const uint32_t *, uint32x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vld1.32 @{@var{d0}[@var{0}]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item uint16x8_t vld1q_lane_u16 (const uint16_t *, uint16x8_t, const int) +@*@emph{Form of expected instruction(s):} @code{vld1.16 @{@var{d0}[@var{0}]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item uint8x16_t vld1q_lane_u8 (const uint8_t *, uint8x16_t, const int) +@*@emph{Form of expected instruction(s):} @code{vld1.8 @{@var{d0}[@var{0}]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item int32x4_t vld1q_lane_s32 (const int32_t *, int32x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vld1.32 @{@var{d0}[@var{0}]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item int16x8_t vld1q_lane_s16 (const int16_t *, int16x8_t, const int) +@*@emph{Form of expected instruction(s):} @code{vld1.16 @{@var{d0}[@var{0}]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item int8x16_t vld1q_lane_s8 (const int8_t *, int8x16_t, const int) +@*@emph{Form of expected instruction(s):} @code{vld1.8 @{@var{d0}[@var{0}]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item float32x4_t vld1q_lane_f32 (const float32_t *, float32x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vld1.32 @{@var{d0}[@var{0}]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item poly16x8_t vld1q_lane_p16 (const poly16_t *, poly16x8_t, const int) +@*@emph{Form of expected instruction(s):} @code{vld1.16 @{@var{d0}[@var{0}]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item poly8x16_t vld1q_lane_p8 (const poly8_t *, poly8x16_t, const int) +@*@emph{Form of expected instruction(s):} @code{vld1.8 @{@var{d0}[@var{0}]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item uint64x2_t vld1q_lane_u64 (const uint64_t *, uint64x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vld1.64 @{@var{d0}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item int64x2_t vld1q_lane_s64 (const int64_t *, int64x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vld1.64 @{@var{d0}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item uint32x2_t vld1_dup_u32 (const uint32_t *) +@*@emph{Form of expected instruction(s):} @code{vld1.32 @{@var{d0}[]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item uint16x4_t vld1_dup_u16 (const uint16_t *) +@*@emph{Form of expected instruction(s):} @code{vld1.16 @{@var{d0}[]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item uint8x8_t vld1_dup_u8 (const uint8_t *) +@*@emph{Form of expected instruction(s):} @code{vld1.8 @{@var{d0}[]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item int32x2_t vld1_dup_s32 (const int32_t *) +@*@emph{Form of expected instruction(s):} @code{vld1.32 @{@var{d0}[]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item int16x4_t vld1_dup_s16 (const int16_t *) +@*@emph{Form of expected instruction(s):} @code{vld1.16 @{@var{d0}[]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item int8x8_t vld1_dup_s8 (const int8_t *) +@*@emph{Form of expected instruction(s):} @code{vld1.8 @{@var{d0}[]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item float32x2_t vld1_dup_f32 (const float32_t *) +@*@emph{Form of expected instruction(s):} @code{vld1.32 @{@var{d0}[]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item poly16x4_t vld1_dup_p16 (const poly16_t *) +@*@emph{Form of expected instruction(s):} @code{vld1.16 @{@var{d0}[]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item poly8x8_t vld1_dup_p8 (const poly8_t *) +@*@emph{Form of expected instruction(s):} @code{vld1.8 @{@var{d0}[]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item uint64x1_t vld1_dup_u64 (const uint64_t *) +@*@emph{Form of expected instruction(s):} @code{vld1.64 @{@var{d0}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item int64x1_t vld1_dup_s64 (const int64_t *) +@*@emph{Form of expected instruction(s):} @code{vld1.64 @{@var{d0}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item uint32x4_t vld1q_dup_u32 (const uint32_t *) +@*@emph{Form of expected instruction(s):} @code{vld1.32 @{@var{d0}[], @var{d1}[]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item uint16x8_t vld1q_dup_u16 (const uint16_t *) +@*@emph{Form of expected instruction(s):} @code{vld1.16 @{@var{d0}[], @var{d1}[]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item uint8x16_t vld1q_dup_u8 (const uint8_t *) +@*@emph{Form of expected instruction(s):} @code{vld1.8 @{@var{d0}[], @var{d1}[]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item int32x4_t vld1q_dup_s32 (const int32_t *) +@*@emph{Form of expected instruction(s):} @code{vld1.32 @{@var{d0}[], @var{d1}[]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item int16x8_t vld1q_dup_s16 (const int16_t *) +@*@emph{Form of expected instruction(s):} @code{vld1.16 @{@var{d0}[], @var{d1}[]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item int8x16_t vld1q_dup_s8 (const int8_t *) +@*@emph{Form of expected instruction(s):} @code{vld1.8 @{@var{d0}[], @var{d1}[]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item float32x4_t vld1q_dup_f32 (const float32_t *) +@*@emph{Form of expected instruction(s):} @code{vld1.32 @{@var{d0}[], @var{d1}[]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item poly16x8_t vld1q_dup_p16 (const poly16_t *) +@*@emph{Form of expected instruction(s):} @code{vld1.16 @{@var{d0}[], @var{d1}[]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item poly8x16_t vld1q_dup_p8 (const poly8_t *) +@*@emph{Form of expected instruction(s):} @code{vld1.8 @{@var{d0}[], @var{d1}[]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item uint64x2_t vld1q_dup_u64 (const uint64_t *) +@*@emph{Form of expected instruction(s):} @code{vld1.64 @{@var{d0}, @var{d1}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item int64x2_t vld1q_dup_s64 (const int64_t *) +@*@emph{Form of expected instruction(s):} @code{vld1.64 @{@var{d0}, @var{d1}@}, [@var{r0}]} +@end itemize + + + + +@subsubsection Element/structure stores, VST1 variants + +@itemize @bullet +@item void vst1_u32 (uint32_t *, uint32x2_t) +@*@emph{Form of expected instruction(s):} @code{vst1.32 @{@var{d0}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst1_u16 (uint16_t *, uint16x4_t) +@*@emph{Form of expected instruction(s):} @code{vst1.16 @{@var{d0}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst1_u8 (uint8_t *, uint8x8_t) +@*@emph{Form of expected instruction(s):} @code{vst1.8 @{@var{d0}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst1_s32 (int32_t *, int32x2_t) +@*@emph{Form of expected instruction(s):} @code{vst1.32 @{@var{d0}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst1_s16 (int16_t *, int16x4_t) +@*@emph{Form of expected instruction(s):} @code{vst1.16 @{@var{d0}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst1_s8 (int8_t *, int8x8_t) +@*@emph{Form of expected instruction(s):} @code{vst1.8 @{@var{d0}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst1_u64 (uint64_t *, uint64x1_t) +@*@emph{Form of expected instruction(s):} @code{vst1.64 @{@var{d0}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst1_s64 (int64_t *, int64x1_t) +@*@emph{Form of expected instruction(s):} @code{vst1.64 @{@var{d0}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst1_f32 (float32_t *, float32x2_t) +@*@emph{Form of expected instruction(s):} @code{vst1.32 @{@var{d0}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst1_p16 (poly16_t *, poly16x4_t) +@*@emph{Form of expected instruction(s):} @code{vst1.16 @{@var{d0}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst1_p8 (poly8_t *, poly8x8_t) +@*@emph{Form of expected instruction(s):} @code{vst1.8 @{@var{d0}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst1q_u32 (uint32_t *, uint32x4_t) +@*@emph{Form of expected instruction(s):} @code{vst1.32 @{@var{d0}, @var{d1}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst1q_u16 (uint16_t *, uint16x8_t) +@*@emph{Form of expected instruction(s):} @code{vst1.16 @{@var{d0}, @var{d1}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst1q_u8 (uint8_t *, uint8x16_t) +@*@emph{Form of expected instruction(s):} @code{vst1.8 @{@var{d0}, @var{d1}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst1q_s32 (int32_t *, int32x4_t) +@*@emph{Form of expected instruction(s):} @code{vst1.32 @{@var{d0}, @var{d1}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst1q_s16 (int16_t *, int16x8_t) +@*@emph{Form of expected instruction(s):} @code{vst1.16 @{@var{d0}, @var{d1}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst1q_s8 (int8_t *, int8x16_t) +@*@emph{Form of expected instruction(s):} @code{vst1.8 @{@var{d0}, @var{d1}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst1q_u64 (uint64_t *, uint64x2_t) +@*@emph{Form of expected instruction(s):} @code{vst1.64 @{@var{d0}, @var{d1}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst1q_s64 (int64_t *, int64x2_t) +@*@emph{Form of expected instruction(s):} @code{vst1.64 @{@var{d0}, @var{d1}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst1q_f32 (float32_t *, float32x4_t) +@*@emph{Form of expected instruction(s):} @code{vst1.32 @{@var{d0}, @var{d1}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst1q_p16 (poly16_t *, poly16x8_t) +@*@emph{Form of expected instruction(s):} @code{vst1.16 @{@var{d0}, @var{d1}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst1q_p8 (poly8_t *, poly8x16_t) +@*@emph{Form of expected instruction(s):} @code{vst1.8 @{@var{d0}, @var{d1}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst1_lane_u32 (uint32_t *, uint32x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vst1.32 @{@var{d0}[@var{0}]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst1_lane_u16 (uint16_t *, uint16x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vst1.16 @{@var{d0}[@var{0}]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst1_lane_u8 (uint8_t *, uint8x8_t, const int) +@*@emph{Form of expected instruction(s):} @code{vst1.8 @{@var{d0}[@var{0}]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst1_lane_s32 (int32_t *, int32x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vst1.32 @{@var{d0}[@var{0}]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst1_lane_s16 (int16_t *, int16x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vst1.16 @{@var{d0}[@var{0}]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst1_lane_s8 (int8_t *, int8x8_t, const int) +@*@emph{Form of expected instruction(s):} @code{vst1.8 @{@var{d0}[@var{0}]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst1_lane_f32 (float32_t *, float32x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vst1.32 @{@var{d0}[@var{0}]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst1_lane_p16 (poly16_t *, poly16x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vst1.16 @{@var{d0}[@var{0}]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst1_lane_p8 (poly8_t *, poly8x8_t, const int) +@*@emph{Form of expected instruction(s):} @code{vst1.8 @{@var{d0}[@var{0}]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst1_lane_s64 (int64_t *, int64x1_t, const int) +@*@emph{Form of expected instruction(s):} @code{vst1.64 @{@var{d0}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst1_lane_u64 (uint64_t *, uint64x1_t, const int) +@*@emph{Form of expected instruction(s):} @code{vst1.64 @{@var{d0}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst1q_lane_u32 (uint32_t *, uint32x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vst1.32 @{@var{d0}[@var{0}]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst1q_lane_u16 (uint16_t *, uint16x8_t, const int) +@*@emph{Form of expected instruction(s):} @code{vst1.16 @{@var{d0}[@var{0}]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst1q_lane_u8 (uint8_t *, uint8x16_t, const int) +@*@emph{Form of expected instruction(s):} @code{vst1.8 @{@var{d0}[@var{0}]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst1q_lane_s32 (int32_t *, int32x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vst1.32 @{@var{d0}[@var{0}]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst1q_lane_s16 (int16_t *, int16x8_t, const int) +@*@emph{Form of expected instruction(s):} @code{vst1.16 @{@var{d0}[@var{0}]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst1q_lane_s8 (int8_t *, int8x16_t, const int) +@*@emph{Form of expected instruction(s):} @code{vst1.8 @{@var{d0}[@var{0}]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst1q_lane_f32 (float32_t *, float32x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vst1.32 @{@var{d0}[@var{0}]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst1q_lane_p16 (poly16_t *, poly16x8_t, const int) +@*@emph{Form of expected instruction(s):} @code{vst1.16 @{@var{d0}[@var{0}]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst1q_lane_p8 (poly8_t *, poly8x16_t, const int) +@*@emph{Form of expected instruction(s):} @code{vst1.8 @{@var{d0}[@var{0}]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst1q_lane_s64 (int64_t *, int64x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vst1.64 @{@var{d0}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst1q_lane_u64 (uint64_t *, uint64x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vst1.64 @{@var{d0}@}, [@var{r0}]} +@end itemize + + + + +@subsubsection Element/structure loads, VLD2 variants + +@itemize @bullet +@item uint32x2x2_t vld2_u32 (const uint32_t *) +@*@emph{Form of expected instruction(s):} @code{vld2.32 @{@var{d0}, @var{d1}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item uint16x4x2_t vld2_u16 (const uint16_t *) +@*@emph{Form of expected instruction(s):} @code{vld2.16 @{@var{d0}, @var{d1}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item uint8x8x2_t vld2_u8 (const uint8_t *) +@*@emph{Form of expected instruction(s):} @code{vld2.8 @{@var{d0}, @var{d1}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item int32x2x2_t vld2_s32 (const int32_t *) +@*@emph{Form of expected instruction(s):} @code{vld2.32 @{@var{d0}, @var{d1}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item int16x4x2_t vld2_s16 (const int16_t *) +@*@emph{Form of expected instruction(s):} @code{vld2.16 @{@var{d0}, @var{d1}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item int8x8x2_t vld2_s8 (const int8_t *) +@*@emph{Form of expected instruction(s):} @code{vld2.8 @{@var{d0}, @var{d1}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item float32x2x2_t vld2_f32 (const float32_t *) +@*@emph{Form of expected instruction(s):} @code{vld2.32 @{@var{d0}, @var{d1}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item poly16x4x2_t vld2_p16 (const poly16_t *) +@*@emph{Form of expected instruction(s):} @code{vld2.16 @{@var{d0}, @var{d1}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item poly8x8x2_t vld2_p8 (const poly8_t *) +@*@emph{Form of expected instruction(s):} @code{vld2.8 @{@var{d0}, @var{d1}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item uint64x1x2_t vld2_u64 (const uint64_t *) +@*@emph{Form of expected instruction(s):} @code{vld1.64 @{@var{d0}, @var{d1}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item int64x1x2_t vld2_s64 (const int64_t *) +@*@emph{Form of expected instruction(s):} @code{vld1.64 @{@var{d0}, @var{d1}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item uint32x4x2_t vld2q_u32 (const uint32_t *) +@*@emph{Form of expected instruction(s):} @code{vld2.32 @{@var{d0}, @var{d1}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item uint16x8x2_t vld2q_u16 (const uint16_t *) +@*@emph{Form of expected instruction(s):} @code{vld2.16 @{@var{d0}, @var{d1}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item uint8x16x2_t vld2q_u8 (const uint8_t *) +@*@emph{Form of expected instruction(s):} @code{vld2.8 @{@var{d0}, @var{d1}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item int32x4x2_t vld2q_s32 (const int32_t *) +@*@emph{Form of expected instruction(s):} @code{vld2.32 @{@var{d0}, @var{d1}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item int16x8x2_t vld2q_s16 (const int16_t *) +@*@emph{Form of expected instruction(s):} @code{vld2.16 @{@var{d0}, @var{d1}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item int8x16x2_t vld2q_s8 (const int8_t *) +@*@emph{Form of expected instruction(s):} @code{vld2.8 @{@var{d0}, @var{d1}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item float32x4x2_t vld2q_f32 (const float32_t *) +@*@emph{Form of expected instruction(s):} @code{vld2.32 @{@var{d0}, @var{d1}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item poly16x8x2_t vld2q_p16 (const poly16_t *) +@*@emph{Form of expected instruction(s):} @code{vld2.16 @{@var{d0}, @var{d1}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item poly8x16x2_t vld2q_p8 (const poly8_t *) +@*@emph{Form of expected instruction(s):} @code{vld2.8 @{@var{d0}, @var{d1}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item uint32x2x2_t vld2_lane_u32 (const uint32_t *, uint32x2x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vld2.32 @{@var{d0}[@var{0}], @var{d1}[@var{0}]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item uint16x4x2_t vld2_lane_u16 (const uint16_t *, uint16x4x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vld2.16 @{@var{d0}[@var{0}], @var{d1}[@var{0}]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item uint8x8x2_t vld2_lane_u8 (const uint8_t *, uint8x8x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vld2.8 @{@var{d0}[@var{0}], @var{d1}[@var{0}]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item int32x2x2_t vld2_lane_s32 (const int32_t *, int32x2x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vld2.32 @{@var{d0}[@var{0}], @var{d1}[@var{0}]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item int16x4x2_t vld2_lane_s16 (const int16_t *, int16x4x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vld2.16 @{@var{d0}[@var{0}], @var{d1}[@var{0}]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item int8x8x2_t vld2_lane_s8 (const int8_t *, int8x8x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vld2.8 @{@var{d0}[@var{0}], @var{d1}[@var{0}]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item float32x2x2_t vld2_lane_f32 (const float32_t *, float32x2x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vld2.32 @{@var{d0}[@var{0}], @var{d1}[@var{0}]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item poly16x4x2_t vld2_lane_p16 (const poly16_t *, poly16x4x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vld2.16 @{@var{d0}[@var{0}], @var{d1}[@var{0}]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item poly8x8x2_t vld2_lane_p8 (const poly8_t *, poly8x8x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vld2.8 @{@var{d0}[@var{0}], @var{d1}[@var{0}]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item int32x4x2_t vld2q_lane_s32 (const int32_t *, int32x4x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vld2.32 @{@var{d0}[@var{0}], @var{d1}[@var{0}]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item int16x8x2_t vld2q_lane_s16 (const int16_t *, int16x8x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vld2.16 @{@var{d0}[@var{0}], @var{d1}[@var{0}]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item uint32x4x2_t vld2q_lane_u32 (const uint32_t *, uint32x4x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vld2.32 @{@var{d0}[@var{0}], @var{d1}[@var{0}]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item uint16x8x2_t vld2q_lane_u16 (const uint16_t *, uint16x8x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vld2.16 @{@var{d0}[@var{0}], @var{d1}[@var{0}]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item float32x4x2_t vld2q_lane_f32 (const float32_t *, float32x4x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vld2.32 @{@var{d0}[@var{0}], @var{d1}[@var{0}]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item poly16x8x2_t vld2q_lane_p16 (const poly16_t *, poly16x8x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vld2.16 @{@var{d0}[@var{0}], @var{d1}[@var{0}]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item uint32x2x2_t vld2_dup_u32 (const uint32_t *) +@*@emph{Form of expected instruction(s):} @code{vld2.32 @{@var{d0}[], @var{d1}[]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item uint16x4x2_t vld2_dup_u16 (const uint16_t *) +@*@emph{Form of expected instruction(s):} @code{vld2.16 @{@var{d0}[], @var{d1}[]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item uint8x8x2_t vld2_dup_u8 (const uint8_t *) +@*@emph{Form of expected instruction(s):} @code{vld2.8 @{@var{d0}[], @var{d1}[]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item int32x2x2_t vld2_dup_s32 (const int32_t *) +@*@emph{Form of expected instruction(s):} @code{vld2.32 @{@var{d0}[], @var{d1}[]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item int16x4x2_t vld2_dup_s16 (const int16_t *) +@*@emph{Form of expected instruction(s):} @code{vld2.16 @{@var{d0}[], @var{d1}[]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item int8x8x2_t vld2_dup_s8 (const int8_t *) +@*@emph{Form of expected instruction(s):} @code{vld2.8 @{@var{d0}[], @var{d1}[]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item float32x2x2_t vld2_dup_f32 (const float32_t *) +@*@emph{Form of expected instruction(s):} @code{vld2.32 @{@var{d0}[], @var{d1}[]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item poly16x4x2_t vld2_dup_p16 (const poly16_t *) +@*@emph{Form of expected instruction(s):} @code{vld2.16 @{@var{d0}[], @var{d1}[]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item poly8x8x2_t vld2_dup_p8 (const poly8_t *) +@*@emph{Form of expected instruction(s):} @code{vld2.8 @{@var{d0}[], @var{d1}[]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item uint64x1x2_t vld2_dup_u64 (const uint64_t *) +@*@emph{Form of expected instruction(s):} @code{vld1.64 @{@var{d0}, @var{d1}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item int64x1x2_t vld2_dup_s64 (const int64_t *) +@*@emph{Form of expected instruction(s):} @code{vld1.64 @{@var{d0}, @var{d1}@}, [@var{r0}]} +@end itemize + + + + +@subsubsection Element/structure stores, VST2 variants + +@itemize @bullet +@item void vst2_u32 (uint32_t *, uint32x2x2_t) +@*@emph{Form of expected instruction(s):} @code{vst2.32 @{@var{d0}, @var{d1}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst2_u16 (uint16_t *, uint16x4x2_t) +@*@emph{Form of expected instruction(s):} @code{vst2.16 @{@var{d0}, @var{d1}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst2_u8 (uint8_t *, uint8x8x2_t) +@*@emph{Form of expected instruction(s):} @code{vst2.8 @{@var{d0}, @var{d1}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst2_s32 (int32_t *, int32x2x2_t) +@*@emph{Form of expected instruction(s):} @code{vst2.32 @{@var{d0}, @var{d1}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst2_s16 (int16_t *, int16x4x2_t) +@*@emph{Form of expected instruction(s):} @code{vst2.16 @{@var{d0}, @var{d1}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst2_s8 (int8_t *, int8x8x2_t) +@*@emph{Form of expected instruction(s):} @code{vst2.8 @{@var{d0}, @var{d1}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst2_f32 (float32_t *, float32x2x2_t) +@*@emph{Form of expected instruction(s):} @code{vst2.32 @{@var{d0}, @var{d1}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst2_p16 (poly16_t *, poly16x4x2_t) +@*@emph{Form of expected instruction(s):} @code{vst2.16 @{@var{d0}, @var{d1}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst2_p8 (poly8_t *, poly8x8x2_t) +@*@emph{Form of expected instruction(s):} @code{vst2.8 @{@var{d0}, @var{d1}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst2_u64 (uint64_t *, uint64x1x2_t) +@*@emph{Form of expected instruction(s):} @code{vst1.64 @{@var{d0}, @var{d1}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst2_s64 (int64_t *, int64x1x2_t) +@*@emph{Form of expected instruction(s):} @code{vst1.64 @{@var{d0}, @var{d1}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst2q_u32 (uint32_t *, uint32x4x2_t) +@*@emph{Form of expected instruction(s):} @code{vst2.32 @{@var{d0}, @var{d1}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst2q_u16 (uint16_t *, uint16x8x2_t) +@*@emph{Form of expected instruction(s):} @code{vst2.16 @{@var{d0}, @var{d1}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst2q_u8 (uint8_t *, uint8x16x2_t) +@*@emph{Form of expected instruction(s):} @code{vst2.8 @{@var{d0}, @var{d1}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst2q_s32 (int32_t *, int32x4x2_t) +@*@emph{Form of expected instruction(s):} @code{vst2.32 @{@var{d0}, @var{d1}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst2q_s16 (int16_t *, int16x8x2_t) +@*@emph{Form of expected instruction(s):} @code{vst2.16 @{@var{d0}, @var{d1}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst2q_s8 (int8_t *, int8x16x2_t) +@*@emph{Form of expected instruction(s):} @code{vst2.8 @{@var{d0}, @var{d1}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst2q_f32 (float32_t *, float32x4x2_t) +@*@emph{Form of expected instruction(s):} @code{vst2.32 @{@var{d0}, @var{d1}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst2q_p16 (poly16_t *, poly16x8x2_t) +@*@emph{Form of expected instruction(s):} @code{vst2.16 @{@var{d0}, @var{d1}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst2q_p8 (poly8_t *, poly8x16x2_t) +@*@emph{Form of expected instruction(s):} @code{vst2.8 @{@var{d0}, @var{d1}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst2_lane_u32 (uint32_t *, uint32x2x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vst2.32 @{@var{d0}[@var{0}], @var{d1}[@var{0}]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst2_lane_u16 (uint16_t *, uint16x4x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vst2.16 @{@var{d0}[@var{0}], @var{d1}[@var{0}]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst2_lane_u8 (uint8_t *, uint8x8x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vst2.8 @{@var{d0}[@var{0}], @var{d1}[@var{0}]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst2_lane_s32 (int32_t *, int32x2x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vst2.32 @{@var{d0}[@var{0}], @var{d1}[@var{0}]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst2_lane_s16 (int16_t *, int16x4x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vst2.16 @{@var{d0}[@var{0}], @var{d1}[@var{0}]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst2_lane_s8 (int8_t *, int8x8x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vst2.8 @{@var{d0}[@var{0}], @var{d1}[@var{0}]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst2_lane_f32 (float32_t *, float32x2x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vst2.32 @{@var{d0}[@var{0}], @var{d1}[@var{0}]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst2_lane_p16 (poly16_t *, poly16x4x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vst2.16 @{@var{d0}[@var{0}], @var{d1}[@var{0}]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst2_lane_p8 (poly8_t *, poly8x8x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vst2.8 @{@var{d0}[@var{0}], @var{d1}[@var{0}]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst2q_lane_s32 (int32_t *, int32x4x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vst2.32 @{@var{d0}[@var{0}], @var{d1}[@var{0}]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst2q_lane_s16 (int16_t *, int16x8x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vst2.16 @{@var{d0}[@var{0}], @var{d1}[@var{0}]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst2q_lane_u32 (uint32_t *, uint32x4x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vst2.32 @{@var{d0}[@var{0}], @var{d1}[@var{0}]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst2q_lane_u16 (uint16_t *, uint16x8x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vst2.16 @{@var{d0}[@var{0}], @var{d1}[@var{0}]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst2q_lane_f32 (float32_t *, float32x4x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vst2.32 @{@var{d0}[@var{0}], @var{d1}[@var{0}]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst2q_lane_p16 (poly16_t *, poly16x8x2_t, const int) +@*@emph{Form of expected instruction(s):} @code{vst2.16 @{@var{d0}[@var{0}], @var{d1}[@var{0}]@}, [@var{r0}]} +@end itemize + + + + +@subsubsection Element/structure loads, VLD3 variants + +@itemize @bullet +@item uint32x2x3_t vld3_u32 (const uint32_t *) +@*@emph{Form of expected instruction(s):} @code{vld3.32 @{@var{d0}, @var{d1}, @var{d2}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item uint16x4x3_t vld3_u16 (const uint16_t *) +@*@emph{Form of expected instruction(s):} @code{vld3.16 @{@var{d0}, @var{d1}, @var{d2}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item uint8x8x3_t vld3_u8 (const uint8_t *) +@*@emph{Form of expected instruction(s):} @code{vld3.8 @{@var{d0}, @var{d1}, @var{d2}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item int32x2x3_t vld3_s32 (const int32_t *) +@*@emph{Form of expected instruction(s):} @code{vld3.32 @{@var{d0}, @var{d1}, @var{d2}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item int16x4x3_t vld3_s16 (const int16_t *) +@*@emph{Form of expected instruction(s):} @code{vld3.16 @{@var{d0}, @var{d1}, @var{d2}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item int8x8x3_t vld3_s8 (const int8_t *) +@*@emph{Form of expected instruction(s):} @code{vld3.8 @{@var{d0}, @var{d1}, @var{d2}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item float32x2x3_t vld3_f32 (const float32_t *) +@*@emph{Form of expected instruction(s):} @code{vld3.32 @{@var{d0}, @var{d1}, @var{d2}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item poly16x4x3_t vld3_p16 (const poly16_t *) +@*@emph{Form of expected instruction(s):} @code{vld3.16 @{@var{d0}, @var{d1}, @var{d2}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item poly8x8x3_t vld3_p8 (const poly8_t *) +@*@emph{Form of expected instruction(s):} @code{vld3.8 @{@var{d0}, @var{d1}, @var{d2}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item uint64x1x3_t vld3_u64 (const uint64_t *) +@*@emph{Form of expected instruction(s):} @code{vld1.64 @{@var{d0}, @var{d1}, @var{d2}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item int64x1x3_t vld3_s64 (const int64_t *) +@*@emph{Form of expected instruction(s):} @code{vld1.64 @{@var{d0}, @var{d1}, @var{d2}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item uint32x4x3_t vld3q_u32 (const uint32_t *) +@*@emph{Form of expected instruction(s):} @code{vld3.32 @{@var{d0}, @var{d1}, @var{d2}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item uint16x8x3_t vld3q_u16 (const uint16_t *) +@*@emph{Form of expected instruction(s):} @code{vld3.16 @{@var{d0}, @var{d1}, @var{d2}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item uint8x16x3_t vld3q_u8 (const uint8_t *) +@*@emph{Form of expected instruction(s):} @code{vld3.8 @{@var{d0}, @var{d1}, @var{d2}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item int32x4x3_t vld3q_s32 (const int32_t *) +@*@emph{Form of expected instruction(s):} @code{vld3.32 @{@var{d0}, @var{d1}, @var{d2}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item int16x8x3_t vld3q_s16 (const int16_t *) +@*@emph{Form of expected instruction(s):} @code{vld3.16 @{@var{d0}, @var{d1}, @var{d2}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item int8x16x3_t vld3q_s8 (const int8_t *) +@*@emph{Form of expected instruction(s):} @code{vld3.8 @{@var{d0}, @var{d1}, @var{d2}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item float32x4x3_t vld3q_f32 (const float32_t *) +@*@emph{Form of expected instruction(s):} @code{vld3.32 @{@var{d0}, @var{d1}, @var{d2}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item poly16x8x3_t vld3q_p16 (const poly16_t *) +@*@emph{Form of expected instruction(s):} @code{vld3.16 @{@var{d0}, @var{d1}, @var{d2}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item poly8x16x3_t vld3q_p8 (const poly8_t *) +@*@emph{Form of expected instruction(s):} @code{vld3.8 @{@var{d0}, @var{d1}, @var{d2}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item uint32x2x3_t vld3_lane_u32 (const uint32_t *, uint32x2x3_t, const int) +@*@emph{Form of expected instruction(s):} @code{vld3.32 @{@var{d0}[@var{0}], @var{d1}[@var{0}], @var{d2}[@var{0}]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item uint16x4x3_t vld3_lane_u16 (const uint16_t *, uint16x4x3_t, const int) +@*@emph{Form of expected instruction(s):} @code{vld3.16 @{@var{d0}[@var{0}], @var{d1}[@var{0}], @var{d2}[@var{0}]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item uint8x8x3_t vld3_lane_u8 (const uint8_t *, uint8x8x3_t, const int) +@*@emph{Form of expected instruction(s):} @code{vld3.8 @{@var{d0}[@var{0}], @var{d1}[@var{0}], @var{d2}[@var{0}]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item int32x2x3_t vld3_lane_s32 (const int32_t *, int32x2x3_t, const int) +@*@emph{Form of expected instruction(s):} @code{vld3.32 @{@var{d0}[@var{0}], @var{d1}[@var{0}], @var{d2}[@var{0}]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item int16x4x3_t vld3_lane_s16 (const int16_t *, int16x4x3_t, const int) +@*@emph{Form of expected instruction(s):} @code{vld3.16 @{@var{d0}[@var{0}], @var{d1}[@var{0}], @var{d2}[@var{0}]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item int8x8x3_t vld3_lane_s8 (const int8_t *, int8x8x3_t, const int) +@*@emph{Form of expected instruction(s):} @code{vld3.8 @{@var{d0}[@var{0}], @var{d1}[@var{0}], @var{d2}[@var{0}]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item float32x2x3_t vld3_lane_f32 (const float32_t *, float32x2x3_t, const int) +@*@emph{Form of expected instruction(s):} @code{vld3.32 @{@var{d0}[@var{0}], @var{d1}[@var{0}], @var{d2}[@var{0}]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item poly16x4x3_t vld3_lane_p16 (const poly16_t *, poly16x4x3_t, const int) +@*@emph{Form of expected instruction(s):} @code{vld3.16 @{@var{d0}[@var{0}], @var{d1}[@var{0}], @var{d2}[@var{0}]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item poly8x8x3_t vld3_lane_p8 (const poly8_t *, poly8x8x3_t, const int) +@*@emph{Form of expected instruction(s):} @code{vld3.8 @{@var{d0}[@var{0}], @var{d1}[@var{0}], @var{d2}[@var{0}]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item int32x4x3_t vld3q_lane_s32 (const int32_t *, int32x4x3_t, const int) +@*@emph{Form of expected instruction(s):} @code{vld3.32 @{@var{d0}[@var{0}], @var{d1}[@var{0}], @var{d2}[@var{0}]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item int16x8x3_t vld3q_lane_s16 (const int16_t *, int16x8x3_t, const int) +@*@emph{Form of expected instruction(s):} @code{vld3.16 @{@var{d0}[@var{0}], @var{d1}[@var{0}], @var{d2}[@var{0}]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item uint32x4x3_t vld3q_lane_u32 (const uint32_t *, uint32x4x3_t, const int) +@*@emph{Form of expected instruction(s):} @code{vld3.32 @{@var{d0}[@var{0}], @var{d1}[@var{0}], @var{d2}[@var{0}]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item uint16x8x3_t vld3q_lane_u16 (const uint16_t *, uint16x8x3_t, const int) +@*@emph{Form of expected instruction(s):} @code{vld3.16 @{@var{d0}[@var{0}], @var{d1}[@var{0}], @var{d2}[@var{0}]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item float32x4x3_t vld3q_lane_f32 (const float32_t *, float32x4x3_t, const int) +@*@emph{Form of expected instruction(s):} @code{vld3.32 @{@var{d0}[@var{0}], @var{d1}[@var{0}], @var{d2}[@var{0}]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item poly16x8x3_t vld3q_lane_p16 (const poly16_t *, poly16x8x3_t, const int) +@*@emph{Form of expected instruction(s):} @code{vld3.16 @{@var{d0}[@var{0}], @var{d1}[@var{0}], @var{d2}[@var{0}]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item uint32x2x3_t vld3_dup_u32 (const uint32_t *) +@*@emph{Form of expected instruction(s):} @code{vld3.32 @{@var{d0}[], @var{d1}[], @var{d2}[]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item uint16x4x3_t vld3_dup_u16 (const uint16_t *) +@*@emph{Form of expected instruction(s):} @code{vld3.16 @{@var{d0}[], @var{d1}[], @var{d2}[]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item uint8x8x3_t vld3_dup_u8 (const uint8_t *) +@*@emph{Form of expected instruction(s):} @code{vld3.8 @{@var{d0}[], @var{d1}[], @var{d2}[]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item int32x2x3_t vld3_dup_s32 (const int32_t *) +@*@emph{Form of expected instruction(s):} @code{vld3.32 @{@var{d0}[], @var{d1}[], @var{d2}[]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item int16x4x3_t vld3_dup_s16 (const int16_t *) +@*@emph{Form of expected instruction(s):} @code{vld3.16 @{@var{d0}[], @var{d1}[], @var{d2}[]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item int8x8x3_t vld3_dup_s8 (const int8_t *) +@*@emph{Form of expected instruction(s):} @code{vld3.8 @{@var{d0}[], @var{d1}[], @var{d2}[]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item float32x2x3_t vld3_dup_f32 (const float32_t *) +@*@emph{Form of expected instruction(s):} @code{vld3.32 @{@var{d0}[], @var{d1}[], @var{d2}[]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item poly16x4x3_t vld3_dup_p16 (const poly16_t *) +@*@emph{Form of expected instruction(s):} @code{vld3.16 @{@var{d0}[], @var{d1}[], @var{d2}[]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item poly8x8x3_t vld3_dup_p8 (const poly8_t *) +@*@emph{Form of expected instruction(s):} @code{vld3.8 @{@var{d0}[], @var{d1}[], @var{d2}[]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item uint64x1x3_t vld3_dup_u64 (const uint64_t *) +@*@emph{Form of expected instruction(s):} @code{vld1.64 @{@var{d0}, @var{d1}, @var{d2}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item int64x1x3_t vld3_dup_s64 (const int64_t *) +@*@emph{Form of expected instruction(s):} @code{vld1.64 @{@var{d0}, @var{d1}, @var{d2}@}, [@var{r0}]} +@end itemize + + + + +@subsubsection Element/structure stores, VST3 variants + +@itemize @bullet +@item void vst3_u32 (uint32_t *, uint32x2x3_t) +@*@emph{Form of expected instruction(s):} @code{vst3.32 @{@var{d0}, @var{d1}, @var{d2}, @var{d3}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst3_u16 (uint16_t *, uint16x4x3_t) +@*@emph{Form of expected instruction(s):} @code{vst3.16 @{@var{d0}, @var{d1}, @var{d2}, @var{d3}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst3_u8 (uint8_t *, uint8x8x3_t) +@*@emph{Form of expected instruction(s):} @code{vst3.8 @{@var{d0}, @var{d1}, @var{d2}, @var{d3}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst3_s32 (int32_t *, int32x2x3_t) +@*@emph{Form of expected instruction(s):} @code{vst3.32 @{@var{d0}, @var{d1}, @var{d2}, @var{d3}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst3_s16 (int16_t *, int16x4x3_t) +@*@emph{Form of expected instruction(s):} @code{vst3.16 @{@var{d0}, @var{d1}, @var{d2}, @var{d3}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst3_s8 (int8_t *, int8x8x3_t) +@*@emph{Form of expected instruction(s):} @code{vst3.8 @{@var{d0}, @var{d1}, @var{d2}, @var{d3}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst3_f32 (float32_t *, float32x2x3_t) +@*@emph{Form of expected instruction(s):} @code{vst3.32 @{@var{d0}, @var{d1}, @var{d2}, @var{d3}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst3_p16 (poly16_t *, poly16x4x3_t) +@*@emph{Form of expected instruction(s):} @code{vst3.16 @{@var{d0}, @var{d1}, @var{d2}, @var{d3}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst3_p8 (poly8_t *, poly8x8x3_t) +@*@emph{Form of expected instruction(s):} @code{vst3.8 @{@var{d0}, @var{d1}, @var{d2}, @var{d3}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst3_u64 (uint64_t *, uint64x1x3_t) +@*@emph{Form of expected instruction(s):} @code{vst1.64 @{@var{d0}, @var{d1}, @var{d2}, @var{d3}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst3_s64 (int64_t *, int64x1x3_t) +@*@emph{Form of expected instruction(s):} @code{vst1.64 @{@var{d0}, @var{d1}, @var{d2}, @var{d3}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst3q_u32 (uint32_t *, uint32x4x3_t) +@*@emph{Form of expected instruction(s):} @code{vst3.32 @{@var{d0}, @var{d1}, @var{d2}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst3q_u16 (uint16_t *, uint16x8x3_t) +@*@emph{Form of expected instruction(s):} @code{vst3.16 @{@var{d0}, @var{d1}, @var{d2}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst3q_u8 (uint8_t *, uint8x16x3_t) +@*@emph{Form of expected instruction(s):} @code{vst3.8 @{@var{d0}, @var{d1}, @var{d2}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst3q_s32 (int32_t *, int32x4x3_t) +@*@emph{Form of expected instruction(s):} @code{vst3.32 @{@var{d0}, @var{d1}, @var{d2}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst3q_s16 (int16_t *, int16x8x3_t) +@*@emph{Form of expected instruction(s):} @code{vst3.16 @{@var{d0}, @var{d1}, @var{d2}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst3q_s8 (int8_t *, int8x16x3_t) +@*@emph{Form of expected instruction(s):} @code{vst3.8 @{@var{d0}, @var{d1}, @var{d2}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst3q_f32 (float32_t *, float32x4x3_t) +@*@emph{Form of expected instruction(s):} @code{vst3.32 @{@var{d0}, @var{d1}, @var{d2}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst3q_p16 (poly16_t *, poly16x8x3_t) +@*@emph{Form of expected instruction(s):} @code{vst3.16 @{@var{d0}, @var{d1}, @var{d2}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst3q_p8 (poly8_t *, poly8x16x3_t) +@*@emph{Form of expected instruction(s):} @code{vst3.8 @{@var{d0}, @var{d1}, @var{d2}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst3_lane_u32 (uint32_t *, uint32x2x3_t, const int) +@*@emph{Form of expected instruction(s):} @code{vst3.32 @{@var{d0}[@var{0}], @var{d1}[@var{0}], @var{d2}[@var{0}]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst3_lane_u16 (uint16_t *, uint16x4x3_t, const int) +@*@emph{Form of expected instruction(s):} @code{vst3.16 @{@var{d0}[@var{0}], @var{d1}[@var{0}], @var{d2}[@var{0}]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst3_lane_u8 (uint8_t *, uint8x8x3_t, const int) +@*@emph{Form of expected instruction(s):} @code{vst3.8 @{@var{d0}[@var{0}], @var{d1}[@var{0}], @var{d2}[@var{0}]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst3_lane_s32 (int32_t *, int32x2x3_t, const int) +@*@emph{Form of expected instruction(s):} @code{vst3.32 @{@var{d0}[@var{0}], @var{d1}[@var{0}], @var{d2}[@var{0}]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst3_lane_s16 (int16_t *, int16x4x3_t, const int) +@*@emph{Form of expected instruction(s):} @code{vst3.16 @{@var{d0}[@var{0}], @var{d1}[@var{0}], @var{d2}[@var{0}]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst3_lane_s8 (int8_t *, int8x8x3_t, const int) +@*@emph{Form of expected instruction(s):} @code{vst3.8 @{@var{d0}[@var{0}], @var{d1}[@var{0}], @var{d2}[@var{0}]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst3_lane_f32 (float32_t *, float32x2x3_t, const int) +@*@emph{Form of expected instruction(s):} @code{vst3.32 @{@var{d0}[@var{0}], @var{d1}[@var{0}], @var{d2}[@var{0}]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst3_lane_p16 (poly16_t *, poly16x4x3_t, const int) +@*@emph{Form of expected instruction(s):} @code{vst3.16 @{@var{d0}[@var{0}], @var{d1}[@var{0}], @var{d2}[@var{0}]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst3_lane_p8 (poly8_t *, poly8x8x3_t, const int) +@*@emph{Form of expected instruction(s):} @code{vst3.8 @{@var{d0}[@var{0}], @var{d1}[@var{0}], @var{d2}[@var{0}]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst3q_lane_s32 (int32_t *, int32x4x3_t, const int) +@*@emph{Form of expected instruction(s):} @code{vst3.32 @{@var{d0}[@var{0}], @var{d1}[@var{0}], @var{d2}[@var{0}]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst3q_lane_s16 (int16_t *, int16x8x3_t, const int) +@*@emph{Form of expected instruction(s):} @code{vst3.16 @{@var{d0}[@var{0}], @var{d1}[@var{0}], @var{d2}[@var{0}]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst3q_lane_u32 (uint32_t *, uint32x4x3_t, const int) +@*@emph{Form of expected instruction(s):} @code{vst3.32 @{@var{d0}[@var{0}], @var{d1}[@var{0}], @var{d2}[@var{0}]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst3q_lane_u16 (uint16_t *, uint16x8x3_t, const int) +@*@emph{Form of expected instruction(s):} @code{vst3.16 @{@var{d0}[@var{0}], @var{d1}[@var{0}], @var{d2}[@var{0}]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst3q_lane_f32 (float32_t *, float32x4x3_t, const int) +@*@emph{Form of expected instruction(s):} @code{vst3.32 @{@var{d0}[@var{0}], @var{d1}[@var{0}], @var{d2}[@var{0}]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst3q_lane_p16 (poly16_t *, poly16x8x3_t, const int) +@*@emph{Form of expected instruction(s):} @code{vst3.16 @{@var{d0}[@var{0}], @var{d1}[@var{0}], @var{d2}[@var{0}]@}, [@var{r0}]} +@end itemize + + + + +@subsubsection Element/structure loads, VLD4 variants + +@itemize @bullet +@item uint32x2x4_t vld4_u32 (const uint32_t *) +@*@emph{Form of expected instruction(s):} @code{vld4.32 @{@var{d0}, @var{d1}, @var{d2}, @var{d3}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item uint16x4x4_t vld4_u16 (const uint16_t *) +@*@emph{Form of expected instruction(s):} @code{vld4.16 @{@var{d0}, @var{d1}, @var{d2}, @var{d3}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item uint8x8x4_t vld4_u8 (const uint8_t *) +@*@emph{Form of expected instruction(s):} @code{vld4.8 @{@var{d0}, @var{d1}, @var{d2}, @var{d3}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item int32x2x4_t vld4_s32 (const int32_t *) +@*@emph{Form of expected instruction(s):} @code{vld4.32 @{@var{d0}, @var{d1}, @var{d2}, @var{d3}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item int16x4x4_t vld4_s16 (const int16_t *) +@*@emph{Form of expected instruction(s):} @code{vld4.16 @{@var{d0}, @var{d1}, @var{d2}, @var{d3}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item int8x8x4_t vld4_s8 (const int8_t *) +@*@emph{Form of expected instruction(s):} @code{vld4.8 @{@var{d0}, @var{d1}, @var{d2}, @var{d3}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item float32x2x4_t vld4_f32 (const float32_t *) +@*@emph{Form of expected instruction(s):} @code{vld4.32 @{@var{d0}, @var{d1}, @var{d2}, @var{d3}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item poly16x4x4_t vld4_p16 (const poly16_t *) +@*@emph{Form of expected instruction(s):} @code{vld4.16 @{@var{d0}, @var{d1}, @var{d2}, @var{d3}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item poly8x8x4_t vld4_p8 (const poly8_t *) +@*@emph{Form of expected instruction(s):} @code{vld4.8 @{@var{d0}, @var{d1}, @var{d2}, @var{d3}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item uint64x1x4_t vld4_u64 (const uint64_t *) +@*@emph{Form of expected instruction(s):} @code{vld1.64 @{@var{d0}, @var{d1}, @var{d2}, @var{d3}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item int64x1x4_t vld4_s64 (const int64_t *) +@*@emph{Form of expected instruction(s):} @code{vld1.64 @{@var{d0}, @var{d1}, @var{d2}, @var{d3}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item uint32x4x4_t vld4q_u32 (const uint32_t *) +@*@emph{Form of expected instruction(s):} @code{vld4.32 @{@var{d0}, @var{d1}, @var{d2}, @var{d3}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item uint16x8x4_t vld4q_u16 (const uint16_t *) +@*@emph{Form of expected instruction(s):} @code{vld4.16 @{@var{d0}, @var{d1}, @var{d2}, @var{d3}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item uint8x16x4_t vld4q_u8 (const uint8_t *) +@*@emph{Form of expected instruction(s):} @code{vld4.8 @{@var{d0}, @var{d1}, @var{d2}, @var{d3}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item int32x4x4_t vld4q_s32 (const int32_t *) +@*@emph{Form of expected instruction(s):} @code{vld4.32 @{@var{d0}, @var{d1}, @var{d2}, @var{d3}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item int16x8x4_t vld4q_s16 (const int16_t *) +@*@emph{Form of expected instruction(s):} @code{vld4.16 @{@var{d0}, @var{d1}, @var{d2}, @var{d3}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item int8x16x4_t vld4q_s8 (const int8_t *) +@*@emph{Form of expected instruction(s):} @code{vld4.8 @{@var{d0}, @var{d1}, @var{d2}, @var{d3}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item float32x4x4_t vld4q_f32 (const float32_t *) +@*@emph{Form of expected instruction(s):} @code{vld4.32 @{@var{d0}, @var{d1}, @var{d2}, @var{d3}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item poly16x8x4_t vld4q_p16 (const poly16_t *) +@*@emph{Form of expected instruction(s):} @code{vld4.16 @{@var{d0}, @var{d1}, @var{d2}, @var{d3}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item poly8x16x4_t vld4q_p8 (const poly8_t *) +@*@emph{Form of expected instruction(s):} @code{vld4.8 @{@var{d0}, @var{d1}, @var{d2}, @var{d3}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item uint32x2x4_t vld4_lane_u32 (const uint32_t *, uint32x2x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vld4.32 @{@var{d0}[@var{0}], @var{d1}[@var{0}], @var{d2}[@var{0}], @var{d3}[@var{0}]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item uint16x4x4_t vld4_lane_u16 (const uint16_t *, uint16x4x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vld4.16 @{@var{d0}[@var{0}], @var{d1}[@var{0}], @var{d2}[@var{0}], @var{d3}[@var{0}]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item uint8x8x4_t vld4_lane_u8 (const uint8_t *, uint8x8x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vld4.8 @{@var{d0}[@var{0}], @var{d1}[@var{0}], @var{d2}[@var{0}], @var{d3}[@var{0}]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item int32x2x4_t vld4_lane_s32 (const int32_t *, int32x2x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vld4.32 @{@var{d0}[@var{0}], @var{d1}[@var{0}], @var{d2}[@var{0}], @var{d3}[@var{0}]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item int16x4x4_t vld4_lane_s16 (const int16_t *, int16x4x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vld4.16 @{@var{d0}[@var{0}], @var{d1}[@var{0}], @var{d2}[@var{0}], @var{d3}[@var{0}]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item int8x8x4_t vld4_lane_s8 (const int8_t *, int8x8x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vld4.8 @{@var{d0}[@var{0}], @var{d1}[@var{0}], @var{d2}[@var{0}], @var{d3}[@var{0}]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item float32x2x4_t vld4_lane_f32 (const float32_t *, float32x2x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vld4.32 @{@var{d0}[@var{0}], @var{d1}[@var{0}], @var{d2}[@var{0}], @var{d3}[@var{0}]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item poly16x4x4_t vld4_lane_p16 (const poly16_t *, poly16x4x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vld4.16 @{@var{d0}[@var{0}], @var{d1}[@var{0}], @var{d2}[@var{0}], @var{d3}[@var{0}]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item poly8x8x4_t vld4_lane_p8 (const poly8_t *, poly8x8x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vld4.8 @{@var{d0}[@var{0}], @var{d1}[@var{0}], @var{d2}[@var{0}], @var{d3}[@var{0}]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item int32x4x4_t vld4q_lane_s32 (const int32_t *, int32x4x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vld4.32 @{@var{d0}[@var{0}], @var{d1}[@var{0}], @var{d2}[@var{0}], @var{d3}[@var{0}]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item int16x8x4_t vld4q_lane_s16 (const int16_t *, int16x8x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vld4.16 @{@var{d0}[@var{0}], @var{d1}[@var{0}], @var{d2}[@var{0}], @var{d3}[@var{0}]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item uint32x4x4_t vld4q_lane_u32 (const uint32_t *, uint32x4x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vld4.32 @{@var{d0}[@var{0}], @var{d1}[@var{0}], @var{d2}[@var{0}], @var{d3}[@var{0}]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item uint16x8x4_t vld4q_lane_u16 (const uint16_t *, uint16x8x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vld4.16 @{@var{d0}[@var{0}], @var{d1}[@var{0}], @var{d2}[@var{0}], @var{d3}[@var{0}]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item float32x4x4_t vld4q_lane_f32 (const float32_t *, float32x4x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vld4.32 @{@var{d0}[@var{0}], @var{d1}[@var{0}], @var{d2}[@var{0}], @var{d3}[@var{0}]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item poly16x8x4_t vld4q_lane_p16 (const poly16_t *, poly16x8x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vld4.16 @{@var{d0}[@var{0}], @var{d1}[@var{0}], @var{d2}[@var{0}], @var{d3}[@var{0}]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item uint32x2x4_t vld4_dup_u32 (const uint32_t *) +@*@emph{Form of expected instruction(s):} @code{vld4.32 @{@var{d0}[], @var{d1}[], @var{d2}[], @var{d3}[]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item uint16x4x4_t vld4_dup_u16 (const uint16_t *) +@*@emph{Form of expected instruction(s):} @code{vld4.16 @{@var{d0}[], @var{d1}[], @var{d2}[], @var{d3}[]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item uint8x8x4_t vld4_dup_u8 (const uint8_t *) +@*@emph{Form of expected instruction(s):} @code{vld4.8 @{@var{d0}[], @var{d1}[], @var{d2}[], @var{d3}[]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item int32x2x4_t vld4_dup_s32 (const int32_t *) +@*@emph{Form of expected instruction(s):} @code{vld4.32 @{@var{d0}[], @var{d1}[], @var{d2}[], @var{d3}[]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item int16x4x4_t vld4_dup_s16 (const int16_t *) +@*@emph{Form of expected instruction(s):} @code{vld4.16 @{@var{d0}[], @var{d1}[], @var{d2}[], @var{d3}[]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item int8x8x4_t vld4_dup_s8 (const int8_t *) +@*@emph{Form of expected instruction(s):} @code{vld4.8 @{@var{d0}[], @var{d1}[], @var{d2}[], @var{d3}[]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item float32x2x4_t vld4_dup_f32 (const float32_t *) +@*@emph{Form of expected instruction(s):} @code{vld4.32 @{@var{d0}[], @var{d1}[], @var{d2}[], @var{d3}[]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item poly16x4x4_t vld4_dup_p16 (const poly16_t *) +@*@emph{Form of expected instruction(s):} @code{vld4.16 @{@var{d0}[], @var{d1}[], @var{d2}[], @var{d3}[]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item poly8x8x4_t vld4_dup_p8 (const poly8_t *) +@*@emph{Form of expected instruction(s):} @code{vld4.8 @{@var{d0}[], @var{d1}[], @var{d2}[], @var{d3}[]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item uint64x1x4_t vld4_dup_u64 (const uint64_t *) +@*@emph{Form of expected instruction(s):} @code{vld1.64 @{@var{d0}, @var{d1}, @var{d2}, @var{d3}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item int64x1x4_t vld4_dup_s64 (const int64_t *) +@*@emph{Form of expected instruction(s):} @code{vld1.64 @{@var{d0}, @var{d1}, @var{d2}, @var{d3}@}, [@var{r0}]} +@end itemize + + + + +@subsubsection Element/structure stores, VST4 variants + +@itemize @bullet +@item void vst4_u32 (uint32_t *, uint32x2x4_t) +@*@emph{Form of expected instruction(s):} @code{vst4.32 @{@var{d0}, @var{d1}, @var{d2}, @var{d3}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst4_u16 (uint16_t *, uint16x4x4_t) +@*@emph{Form of expected instruction(s):} @code{vst4.16 @{@var{d0}, @var{d1}, @var{d2}, @var{d3}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst4_u8 (uint8_t *, uint8x8x4_t) +@*@emph{Form of expected instruction(s):} @code{vst4.8 @{@var{d0}, @var{d1}, @var{d2}, @var{d3}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst4_s32 (int32_t *, int32x2x4_t) +@*@emph{Form of expected instruction(s):} @code{vst4.32 @{@var{d0}, @var{d1}, @var{d2}, @var{d3}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst4_s16 (int16_t *, int16x4x4_t) +@*@emph{Form of expected instruction(s):} @code{vst4.16 @{@var{d0}, @var{d1}, @var{d2}, @var{d3}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst4_s8 (int8_t *, int8x8x4_t) +@*@emph{Form of expected instruction(s):} @code{vst4.8 @{@var{d0}, @var{d1}, @var{d2}, @var{d3}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst4_f32 (float32_t *, float32x2x4_t) +@*@emph{Form of expected instruction(s):} @code{vst4.32 @{@var{d0}, @var{d1}, @var{d2}, @var{d3}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst4_p16 (poly16_t *, poly16x4x4_t) +@*@emph{Form of expected instruction(s):} @code{vst4.16 @{@var{d0}, @var{d1}, @var{d2}, @var{d3}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst4_p8 (poly8_t *, poly8x8x4_t) +@*@emph{Form of expected instruction(s):} @code{vst4.8 @{@var{d0}, @var{d1}, @var{d2}, @var{d3}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst4_u64 (uint64_t *, uint64x1x4_t) +@*@emph{Form of expected instruction(s):} @code{vst1.64 @{@var{d0}, @var{d1}, @var{d2}, @var{d3}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst4_s64 (int64_t *, int64x1x4_t) +@*@emph{Form of expected instruction(s):} @code{vst1.64 @{@var{d0}, @var{d1}, @var{d2}, @var{d3}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst4q_u32 (uint32_t *, uint32x4x4_t) +@*@emph{Form of expected instruction(s):} @code{vst4.32 @{@var{d0}, @var{d1}, @var{d2}, @var{d3}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst4q_u16 (uint16_t *, uint16x8x4_t) +@*@emph{Form of expected instruction(s):} @code{vst4.16 @{@var{d0}, @var{d1}, @var{d2}, @var{d3}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst4q_u8 (uint8_t *, uint8x16x4_t) +@*@emph{Form of expected instruction(s):} @code{vst4.8 @{@var{d0}, @var{d1}, @var{d2}, @var{d3}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst4q_s32 (int32_t *, int32x4x4_t) +@*@emph{Form of expected instruction(s):} @code{vst4.32 @{@var{d0}, @var{d1}, @var{d2}, @var{d3}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst4q_s16 (int16_t *, int16x8x4_t) +@*@emph{Form of expected instruction(s):} @code{vst4.16 @{@var{d0}, @var{d1}, @var{d2}, @var{d3}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst4q_s8 (int8_t *, int8x16x4_t) +@*@emph{Form of expected instruction(s):} @code{vst4.8 @{@var{d0}, @var{d1}, @var{d2}, @var{d3}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst4q_f32 (float32_t *, float32x4x4_t) +@*@emph{Form of expected instruction(s):} @code{vst4.32 @{@var{d0}, @var{d1}, @var{d2}, @var{d3}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst4q_p16 (poly16_t *, poly16x8x4_t) +@*@emph{Form of expected instruction(s):} @code{vst4.16 @{@var{d0}, @var{d1}, @var{d2}, @var{d3}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst4q_p8 (poly8_t *, poly8x16x4_t) +@*@emph{Form of expected instruction(s):} @code{vst4.8 @{@var{d0}, @var{d1}, @var{d2}, @var{d3}@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst4_lane_u32 (uint32_t *, uint32x2x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vst4.32 @{@var{d0}[@var{0}], @var{d1}[@var{0}], @var{d2}[@var{0}], @var{d3}[@var{0}]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst4_lane_u16 (uint16_t *, uint16x4x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vst4.16 @{@var{d0}[@var{0}], @var{d1}[@var{0}], @var{d2}[@var{0}], @var{d3}[@var{0}]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst4_lane_u8 (uint8_t *, uint8x8x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vst4.8 @{@var{d0}[@var{0}], @var{d1}[@var{0}], @var{d2}[@var{0}], @var{d3}[@var{0}]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst4_lane_s32 (int32_t *, int32x2x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vst4.32 @{@var{d0}[@var{0}], @var{d1}[@var{0}], @var{d2}[@var{0}], @var{d3}[@var{0}]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst4_lane_s16 (int16_t *, int16x4x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vst4.16 @{@var{d0}[@var{0}], @var{d1}[@var{0}], @var{d2}[@var{0}], @var{d3}[@var{0}]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst4_lane_s8 (int8_t *, int8x8x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vst4.8 @{@var{d0}[@var{0}], @var{d1}[@var{0}], @var{d2}[@var{0}], @var{d3}[@var{0}]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst4_lane_f32 (float32_t *, float32x2x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vst4.32 @{@var{d0}[@var{0}], @var{d1}[@var{0}], @var{d2}[@var{0}], @var{d3}[@var{0}]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst4_lane_p16 (poly16_t *, poly16x4x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vst4.16 @{@var{d0}[@var{0}], @var{d1}[@var{0}], @var{d2}[@var{0}], @var{d3}[@var{0}]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst4_lane_p8 (poly8_t *, poly8x8x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vst4.8 @{@var{d0}[@var{0}], @var{d1}[@var{0}], @var{d2}[@var{0}], @var{d3}[@var{0}]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst4q_lane_s32 (int32_t *, int32x4x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vst4.32 @{@var{d0}[@var{0}], @var{d1}[@var{0}], @var{d2}[@var{0}], @var{d3}[@var{0}]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst4q_lane_s16 (int16_t *, int16x8x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vst4.16 @{@var{d0}[@var{0}], @var{d1}[@var{0}], @var{d2}[@var{0}], @var{d3}[@var{0}]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst4q_lane_u32 (uint32_t *, uint32x4x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vst4.32 @{@var{d0}[@var{0}], @var{d1}[@var{0}], @var{d2}[@var{0}], @var{d3}[@var{0}]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst4q_lane_u16 (uint16_t *, uint16x8x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vst4.16 @{@var{d0}[@var{0}], @var{d1}[@var{0}], @var{d2}[@var{0}], @var{d3}[@var{0}]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst4q_lane_f32 (float32_t *, float32x4x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vst4.32 @{@var{d0}[@var{0}], @var{d1}[@var{0}], @var{d2}[@var{0}], @var{d3}[@var{0}]@}, [@var{r0}]} +@end itemize + + +@itemize @bullet +@item void vst4q_lane_p16 (poly16_t *, poly16x8x4_t, const int) +@*@emph{Form of expected instruction(s):} @code{vst4.16 @{@var{d0}[@var{0}], @var{d1}[@var{0}], @var{d2}[@var{0}], @var{d3}[@var{0}]@}, [@var{r0}]} +@end itemize + + + + +@subsubsection Logical operations (AND) + +@itemize @bullet +@item uint32x2_t vand_u32 (uint32x2_t, uint32x2_t) +@*@emph{Form of expected instruction(s):} @code{vand @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint16x4_t vand_u16 (uint16x4_t, uint16x4_t) +@*@emph{Form of expected instruction(s):} @code{vand @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint8x8_t vand_u8 (uint8x8_t, uint8x8_t) +@*@emph{Form of expected instruction(s):} @code{vand @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int32x2_t vand_s32 (int32x2_t, int32x2_t) +@*@emph{Form of expected instruction(s):} @code{vand @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int16x4_t vand_s16 (int16x4_t, int16x4_t) +@*@emph{Form of expected instruction(s):} @code{vand @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int8x8_t vand_s8 (int8x8_t, int8x8_t) +@*@emph{Form of expected instruction(s):} @code{vand @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint64x1_t vand_u64 (uint64x1_t, uint64x1_t) +@end itemize + + +@itemize @bullet +@item int64x1_t vand_s64 (int64x1_t, int64x1_t) +@end itemize + + +@itemize @bullet +@item uint32x4_t vandq_u32 (uint32x4_t, uint32x4_t) +@*@emph{Form of expected instruction(s):} @code{vand @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint16x8_t vandq_u16 (uint16x8_t, uint16x8_t) +@*@emph{Form of expected instruction(s):} @code{vand @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint8x16_t vandq_u8 (uint8x16_t, uint8x16_t) +@*@emph{Form of expected instruction(s):} @code{vand @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int32x4_t vandq_s32 (int32x4_t, int32x4_t) +@*@emph{Form of expected instruction(s):} @code{vand @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int16x8_t vandq_s16 (int16x8_t, int16x8_t) +@*@emph{Form of expected instruction(s):} @code{vand @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int8x16_t vandq_s8 (int8x16_t, int8x16_t) +@*@emph{Form of expected instruction(s):} @code{vand @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint64x2_t vandq_u64 (uint64x2_t, uint64x2_t) +@*@emph{Form of expected instruction(s):} @code{vand @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int64x2_t vandq_s64 (int64x2_t, int64x2_t) +@*@emph{Form of expected instruction(s):} @code{vand @var{q0}, @var{q0}, @var{q0}} +@end itemize + + + + +@subsubsection Logical operations (OR) + +@itemize @bullet +@item uint32x2_t vorr_u32 (uint32x2_t, uint32x2_t) +@*@emph{Form of expected instruction(s):} @code{vorr @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint16x4_t vorr_u16 (uint16x4_t, uint16x4_t) +@*@emph{Form of expected instruction(s):} @code{vorr @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint8x8_t vorr_u8 (uint8x8_t, uint8x8_t) +@*@emph{Form of expected instruction(s):} @code{vorr @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int32x2_t vorr_s32 (int32x2_t, int32x2_t) +@*@emph{Form of expected instruction(s):} @code{vorr @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int16x4_t vorr_s16 (int16x4_t, int16x4_t) +@*@emph{Form of expected instruction(s):} @code{vorr @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int8x8_t vorr_s8 (int8x8_t, int8x8_t) +@*@emph{Form of expected instruction(s):} @code{vorr @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint64x1_t vorr_u64 (uint64x1_t, uint64x1_t) +@end itemize + + +@itemize @bullet +@item int64x1_t vorr_s64 (int64x1_t, int64x1_t) +@end itemize + + +@itemize @bullet +@item uint32x4_t vorrq_u32 (uint32x4_t, uint32x4_t) +@*@emph{Form of expected instruction(s):} @code{vorr @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint16x8_t vorrq_u16 (uint16x8_t, uint16x8_t) +@*@emph{Form of expected instruction(s):} @code{vorr @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint8x16_t vorrq_u8 (uint8x16_t, uint8x16_t) +@*@emph{Form of expected instruction(s):} @code{vorr @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int32x4_t vorrq_s32 (int32x4_t, int32x4_t) +@*@emph{Form of expected instruction(s):} @code{vorr @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int16x8_t vorrq_s16 (int16x8_t, int16x8_t) +@*@emph{Form of expected instruction(s):} @code{vorr @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int8x16_t vorrq_s8 (int8x16_t, int8x16_t) +@*@emph{Form of expected instruction(s):} @code{vorr @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint64x2_t vorrq_u64 (uint64x2_t, uint64x2_t) +@*@emph{Form of expected instruction(s):} @code{vorr @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int64x2_t vorrq_s64 (int64x2_t, int64x2_t) +@*@emph{Form of expected instruction(s):} @code{vorr @var{q0}, @var{q0}, @var{q0}} +@end itemize + + + + +@subsubsection Logical operations (exclusive OR) + +@itemize @bullet +@item uint32x2_t veor_u32 (uint32x2_t, uint32x2_t) +@*@emph{Form of expected instruction(s):} @code{veor @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint16x4_t veor_u16 (uint16x4_t, uint16x4_t) +@*@emph{Form of expected instruction(s):} @code{veor @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint8x8_t veor_u8 (uint8x8_t, uint8x8_t) +@*@emph{Form of expected instruction(s):} @code{veor @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int32x2_t veor_s32 (int32x2_t, int32x2_t) +@*@emph{Form of expected instruction(s):} @code{veor @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int16x4_t veor_s16 (int16x4_t, int16x4_t) +@*@emph{Form of expected instruction(s):} @code{veor @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int8x8_t veor_s8 (int8x8_t, int8x8_t) +@*@emph{Form of expected instruction(s):} @code{veor @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint64x1_t veor_u64 (uint64x1_t, uint64x1_t) +@end itemize + + +@itemize @bullet +@item int64x1_t veor_s64 (int64x1_t, int64x1_t) +@end itemize + + +@itemize @bullet +@item uint32x4_t veorq_u32 (uint32x4_t, uint32x4_t) +@*@emph{Form of expected instruction(s):} @code{veor @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint16x8_t veorq_u16 (uint16x8_t, uint16x8_t) +@*@emph{Form of expected instruction(s):} @code{veor @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint8x16_t veorq_u8 (uint8x16_t, uint8x16_t) +@*@emph{Form of expected instruction(s):} @code{veor @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int32x4_t veorq_s32 (int32x4_t, int32x4_t) +@*@emph{Form of expected instruction(s):} @code{veor @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int16x8_t veorq_s16 (int16x8_t, int16x8_t) +@*@emph{Form of expected instruction(s):} @code{veor @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int8x16_t veorq_s8 (int8x16_t, int8x16_t) +@*@emph{Form of expected instruction(s):} @code{veor @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint64x2_t veorq_u64 (uint64x2_t, uint64x2_t) +@*@emph{Form of expected instruction(s):} @code{veor @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int64x2_t veorq_s64 (int64x2_t, int64x2_t) +@*@emph{Form of expected instruction(s):} @code{veor @var{q0}, @var{q0}, @var{q0}} +@end itemize + + + + +@subsubsection Logical operations (AND-NOT) + +@itemize @bullet +@item uint32x2_t vbic_u32 (uint32x2_t, uint32x2_t) +@*@emph{Form of expected instruction(s):} @code{vbic @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint16x4_t vbic_u16 (uint16x4_t, uint16x4_t) +@*@emph{Form of expected instruction(s):} @code{vbic @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint8x8_t vbic_u8 (uint8x8_t, uint8x8_t) +@*@emph{Form of expected instruction(s):} @code{vbic @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int32x2_t vbic_s32 (int32x2_t, int32x2_t) +@*@emph{Form of expected instruction(s):} @code{vbic @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int16x4_t vbic_s16 (int16x4_t, int16x4_t) +@*@emph{Form of expected instruction(s):} @code{vbic @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int8x8_t vbic_s8 (int8x8_t, int8x8_t) +@*@emph{Form of expected instruction(s):} @code{vbic @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint64x1_t vbic_u64 (uint64x1_t, uint64x1_t) +@end itemize + + +@itemize @bullet +@item int64x1_t vbic_s64 (int64x1_t, int64x1_t) +@end itemize + + +@itemize @bullet +@item uint32x4_t vbicq_u32 (uint32x4_t, uint32x4_t) +@*@emph{Form of expected instruction(s):} @code{vbic @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint16x8_t vbicq_u16 (uint16x8_t, uint16x8_t) +@*@emph{Form of expected instruction(s):} @code{vbic @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint8x16_t vbicq_u8 (uint8x16_t, uint8x16_t) +@*@emph{Form of expected instruction(s):} @code{vbic @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int32x4_t vbicq_s32 (int32x4_t, int32x4_t) +@*@emph{Form of expected instruction(s):} @code{vbic @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int16x8_t vbicq_s16 (int16x8_t, int16x8_t) +@*@emph{Form of expected instruction(s):} @code{vbic @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int8x16_t vbicq_s8 (int8x16_t, int8x16_t) +@*@emph{Form of expected instruction(s):} @code{vbic @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint64x2_t vbicq_u64 (uint64x2_t, uint64x2_t) +@*@emph{Form of expected instruction(s):} @code{vbic @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int64x2_t vbicq_s64 (int64x2_t, int64x2_t) +@*@emph{Form of expected instruction(s):} @code{vbic @var{q0}, @var{q0}, @var{q0}} +@end itemize + + + + +@subsubsection Logical operations (OR-NOT) + +@itemize @bullet +@item uint32x2_t vorn_u32 (uint32x2_t, uint32x2_t) +@*@emph{Form of expected instruction(s):} @code{vorn @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint16x4_t vorn_u16 (uint16x4_t, uint16x4_t) +@*@emph{Form of expected instruction(s):} @code{vorn @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint8x8_t vorn_u8 (uint8x8_t, uint8x8_t) +@*@emph{Form of expected instruction(s):} @code{vorn @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int32x2_t vorn_s32 (int32x2_t, int32x2_t) +@*@emph{Form of expected instruction(s):} @code{vorn @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int16x4_t vorn_s16 (int16x4_t, int16x4_t) +@*@emph{Form of expected instruction(s):} @code{vorn @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item int8x8_t vorn_s8 (int8x8_t, int8x8_t) +@*@emph{Form of expected instruction(s):} @code{vorn @var{d0}, @var{d0}, @var{d0}} +@end itemize + + +@itemize @bullet +@item uint64x1_t vorn_u64 (uint64x1_t, uint64x1_t) +@end itemize + + +@itemize @bullet +@item int64x1_t vorn_s64 (int64x1_t, int64x1_t) +@end itemize + + +@itemize @bullet +@item uint32x4_t vornq_u32 (uint32x4_t, uint32x4_t) +@*@emph{Form of expected instruction(s):} @code{vorn @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint16x8_t vornq_u16 (uint16x8_t, uint16x8_t) +@*@emph{Form of expected instruction(s):} @code{vorn @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint8x16_t vornq_u8 (uint8x16_t, uint8x16_t) +@*@emph{Form of expected instruction(s):} @code{vorn @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int32x4_t vornq_s32 (int32x4_t, int32x4_t) +@*@emph{Form of expected instruction(s):} @code{vorn @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int16x8_t vornq_s16 (int16x8_t, int16x8_t) +@*@emph{Form of expected instruction(s):} @code{vorn @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int8x16_t vornq_s8 (int8x16_t, int8x16_t) +@*@emph{Form of expected instruction(s):} @code{vorn @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item uint64x2_t vornq_u64 (uint64x2_t, uint64x2_t) +@*@emph{Form of expected instruction(s):} @code{vorn @var{q0}, @var{q0}, @var{q0}} +@end itemize + + +@itemize @bullet +@item int64x2_t vornq_s64 (int64x2_t, int64x2_t) +@*@emph{Form of expected instruction(s):} @code{vorn @var{q0}, @var{q0}, @var{q0}} +@end itemize + + + + +@subsubsection Reinterpret casts + +@itemize @bullet +@item poly8x8_t vreinterpret_p8_u32 (uint32x2_t) +@end itemize + + +@itemize @bullet +@item poly8x8_t vreinterpret_p8_u16 (uint16x4_t) +@end itemize + + +@itemize @bullet +@item poly8x8_t vreinterpret_p8_u8 (uint8x8_t) +@end itemize + + +@itemize @bullet +@item poly8x8_t vreinterpret_p8_s32 (int32x2_t) +@end itemize + + +@itemize @bullet +@item poly8x8_t vreinterpret_p8_s16 (int16x4_t) +@end itemize + + +@itemize @bullet +@item poly8x8_t vreinterpret_p8_s8 (int8x8_t) +@end itemize + + +@itemize @bullet +@item poly8x8_t vreinterpret_p8_u64 (uint64x1_t) +@end itemize + + +@itemize @bullet +@item poly8x8_t vreinterpret_p8_s64 (int64x1_t) +@end itemize + + +@itemize @bullet +@item poly8x8_t vreinterpret_p8_f32 (float32x2_t) +@end itemize + + +@itemize @bullet +@item poly8x8_t vreinterpret_p8_p16 (poly16x4_t) +@end itemize + + +@itemize @bullet +@item poly8x16_t vreinterpretq_p8_u32 (uint32x4_t) +@end itemize + + +@itemize @bullet +@item poly8x16_t vreinterpretq_p8_u16 (uint16x8_t) +@end itemize + + +@itemize @bullet +@item poly8x16_t vreinterpretq_p8_u8 (uint8x16_t) +@end itemize + + +@itemize @bullet +@item poly8x16_t vreinterpretq_p8_s32 (int32x4_t) +@end itemize + + +@itemize @bullet +@item poly8x16_t vreinterpretq_p8_s16 (int16x8_t) +@end itemize + + +@itemize @bullet +@item poly8x16_t vreinterpretq_p8_s8 (int8x16_t) +@end itemize + + +@itemize @bullet +@item poly8x16_t vreinterpretq_p8_u64 (uint64x2_t) +@end itemize + + +@itemize @bullet +@item poly8x16_t vreinterpretq_p8_s64 (int64x2_t) +@end itemize + + +@itemize @bullet +@item poly8x16_t vreinterpretq_p8_f32 (float32x4_t) +@end itemize + + +@itemize @bullet +@item poly8x16_t vreinterpretq_p8_p16 (poly16x8_t) +@end itemize + + +@itemize @bullet +@item poly16x4_t vreinterpret_p16_u32 (uint32x2_t) +@end itemize + + +@itemize @bullet +@item poly16x4_t vreinterpret_p16_u16 (uint16x4_t) +@end itemize + + +@itemize @bullet +@item poly16x4_t vreinterpret_p16_u8 (uint8x8_t) +@end itemize + + +@itemize @bullet +@item poly16x4_t vreinterpret_p16_s32 (int32x2_t) +@end itemize + + +@itemize @bullet +@item poly16x4_t vreinterpret_p16_s16 (int16x4_t) +@end itemize + + +@itemize @bullet +@item poly16x4_t vreinterpret_p16_s8 (int8x8_t) +@end itemize + + +@itemize @bullet +@item poly16x4_t vreinterpret_p16_u64 (uint64x1_t) +@end itemize + + +@itemize @bullet +@item poly16x4_t vreinterpret_p16_s64 (int64x1_t) +@end itemize + + +@itemize @bullet +@item poly16x4_t vreinterpret_p16_f32 (float32x2_t) +@end itemize + + +@itemize @bullet +@item poly16x4_t vreinterpret_p16_p8 (poly8x8_t) +@end itemize + + +@itemize @bullet +@item poly16x8_t vreinterpretq_p16_u32 (uint32x4_t) +@end itemize + + +@itemize @bullet +@item poly16x8_t vreinterpretq_p16_u16 (uint16x8_t) +@end itemize + + +@itemize @bullet +@item poly16x8_t vreinterpretq_p16_u8 (uint8x16_t) +@end itemize + + +@itemize @bullet +@item poly16x8_t vreinterpretq_p16_s32 (int32x4_t) +@end itemize + + +@itemize @bullet +@item poly16x8_t vreinterpretq_p16_s16 (int16x8_t) +@end itemize + + +@itemize @bullet +@item poly16x8_t vreinterpretq_p16_s8 (int8x16_t) +@end itemize + + +@itemize @bullet +@item poly16x8_t vreinterpretq_p16_u64 (uint64x2_t) +@end itemize + + +@itemize @bullet +@item poly16x8_t vreinterpretq_p16_s64 (int64x2_t) +@end itemize + + +@itemize @bullet +@item poly16x8_t vreinterpretq_p16_f32 (float32x4_t) +@end itemize + + +@itemize @bullet +@item poly16x8_t vreinterpretq_p16_p8 (poly8x16_t) +@end itemize + + +@itemize @bullet +@item float32x2_t vreinterpret_f32_u32 (uint32x2_t) +@end itemize + + +@itemize @bullet +@item float32x2_t vreinterpret_f32_u16 (uint16x4_t) +@end itemize + + +@itemize @bullet +@item float32x2_t vreinterpret_f32_u8 (uint8x8_t) +@end itemize + + +@itemize @bullet +@item float32x2_t vreinterpret_f32_s32 (int32x2_t) +@end itemize + + +@itemize @bullet +@item float32x2_t vreinterpret_f32_s16 (int16x4_t) +@end itemize + + +@itemize @bullet +@item float32x2_t vreinterpret_f32_s8 (int8x8_t) +@end itemize + + +@itemize @bullet +@item float32x2_t vreinterpret_f32_u64 (uint64x1_t) +@end itemize + + +@itemize @bullet +@item float32x2_t vreinterpret_f32_s64 (int64x1_t) +@end itemize + + +@itemize @bullet +@item float32x2_t vreinterpret_f32_p16 (poly16x4_t) +@end itemize + + +@itemize @bullet +@item float32x2_t vreinterpret_f32_p8 (poly8x8_t) +@end itemize + + +@itemize @bullet +@item float32x4_t vreinterpretq_f32_u32 (uint32x4_t) +@end itemize + + +@itemize @bullet +@item float32x4_t vreinterpretq_f32_u16 (uint16x8_t) +@end itemize + + +@itemize @bullet +@item float32x4_t vreinterpretq_f32_u8 (uint8x16_t) +@end itemize + + +@itemize @bullet +@item float32x4_t vreinterpretq_f32_s32 (int32x4_t) +@end itemize + + +@itemize @bullet +@item float32x4_t vreinterpretq_f32_s16 (int16x8_t) +@end itemize + + +@itemize @bullet +@item float32x4_t vreinterpretq_f32_s8 (int8x16_t) +@end itemize + + +@itemize @bullet +@item float32x4_t vreinterpretq_f32_u64 (uint64x2_t) +@end itemize + + +@itemize @bullet +@item float32x4_t vreinterpretq_f32_s64 (int64x2_t) +@end itemize + + +@itemize @bullet +@item float32x4_t vreinterpretq_f32_p16 (poly16x8_t) +@end itemize + + +@itemize @bullet +@item float32x4_t vreinterpretq_f32_p8 (poly8x16_t) +@end itemize + + +@itemize @bullet +@item int64x1_t vreinterpret_s64_u32 (uint32x2_t) +@end itemize + + +@itemize @bullet +@item int64x1_t vreinterpret_s64_u16 (uint16x4_t) +@end itemize + + +@itemize @bullet +@item int64x1_t vreinterpret_s64_u8 (uint8x8_t) +@end itemize + + +@itemize @bullet +@item int64x1_t vreinterpret_s64_s32 (int32x2_t) +@end itemize + + +@itemize @bullet +@item int64x1_t vreinterpret_s64_s16 (int16x4_t) +@end itemize + + +@itemize @bullet +@item int64x1_t vreinterpret_s64_s8 (int8x8_t) +@end itemize + + +@itemize @bullet +@item int64x1_t vreinterpret_s64_u64 (uint64x1_t) +@end itemize + + +@itemize @bullet +@item int64x1_t vreinterpret_s64_f32 (float32x2_t) +@end itemize + + +@itemize @bullet +@item int64x1_t vreinterpret_s64_p16 (poly16x4_t) +@end itemize + + +@itemize @bullet +@item int64x1_t vreinterpret_s64_p8 (poly8x8_t) +@end itemize + + +@itemize @bullet +@item int64x2_t vreinterpretq_s64_u32 (uint32x4_t) +@end itemize + + +@itemize @bullet +@item int64x2_t vreinterpretq_s64_u16 (uint16x8_t) +@end itemize + + +@itemize @bullet +@item int64x2_t vreinterpretq_s64_u8 (uint8x16_t) +@end itemize + + +@itemize @bullet +@item int64x2_t vreinterpretq_s64_s32 (int32x4_t) +@end itemize + + +@itemize @bullet +@item int64x2_t vreinterpretq_s64_s16 (int16x8_t) +@end itemize + + +@itemize @bullet +@item int64x2_t vreinterpretq_s64_s8 (int8x16_t) +@end itemize + + +@itemize @bullet +@item int64x2_t vreinterpretq_s64_u64 (uint64x2_t) +@end itemize + + +@itemize @bullet +@item int64x2_t vreinterpretq_s64_f32 (float32x4_t) +@end itemize + + +@itemize @bullet +@item int64x2_t vreinterpretq_s64_p16 (poly16x8_t) +@end itemize + + +@itemize @bullet +@item int64x2_t vreinterpretq_s64_p8 (poly8x16_t) +@end itemize + + +@itemize @bullet +@item uint64x1_t vreinterpret_u64_u32 (uint32x2_t) +@end itemize + + +@itemize @bullet +@item uint64x1_t vreinterpret_u64_u16 (uint16x4_t) +@end itemize + + +@itemize @bullet +@item uint64x1_t vreinterpret_u64_u8 (uint8x8_t) +@end itemize + + +@itemize @bullet +@item uint64x1_t vreinterpret_u64_s32 (int32x2_t) +@end itemize + + +@itemize @bullet +@item uint64x1_t vreinterpret_u64_s16 (int16x4_t) +@end itemize + + +@itemize @bullet +@item uint64x1_t vreinterpret_u64_s8 (int8x8_t) +@end itemize + + +@itemize @bullet +@item uint64x1_t vreinterpret_u64_s64 (int64x1_t) +@end itemize + + +@itemize @bullet +@item uint64x1_t vreinterpret_u64_f32 (float32x2_t) +@end itemize + + +@itemize @bullet +@item uint64x1_t vreinterpret_u64_p16 (poly16x4_t) +@end itemize + + +@itemize @bullet +@item uint64x1_t vreinterpret_u64_p8 (poly8x8_t) +@end itemize + + +@itemize @bullet +@item uint64x2_t vreinterpretq_u64_u32 (uint32x4_t) +@end itemize + + +@itemize @bullet +@item uint64x2_t vreinterpretq_u64_u16 (uint16x8_t) +@end itemize + + +@itemize @bullet +@item uint64x2_t vreinterpretq_u64_u8 (uint8x16_t) +@end itemize + + +@itemize @bullet +@item uint64x2_t vreinterpretq_u64_s32 (int32x4_t) +@end itemize + + +@itemize @bullet +@item uint64x2_t vreinterpretq_u64_s16 (int16x8_t) +@end itemize + + +@itemize @bullet +@item uint64x2_t vreinterpretq_u64_s8 (int8x16_t) +@end itemize + + +@itemize @bullet +@item uint64x2_t vreinterpretq_u64_s64 (int64x2_t) +@end itemize + + +@itemize @bullet +@item uint64x2_t vreinterpretq_u64_f32 (float32x4_t) +@end itemize + + +@itemize @bullet +@item uint64x2_t vreinterpretq_u64_p16 (poly16x8_t) +@end itemize + + +@itemize @bullet +@item uint64x2_t vreinterpretq_u64_p8 (poly8x16_t) +@end itemize + + +@itemize @bullet +@item int8x8_t vreinterpret_s8_u32 (uint32x2_t) +@end itemize + + +@itemize @bullet +@item int8x8_t vreinterpret_s8_u16 (uint16x4_t) +@end itemize + + +@itemize @bullet +@item int8x8_t vreinterpret_s8_u8 (uint8x8_t) +@end itemize + + +@itemize @bullet +@item int8x8_t vreinterpret_s8_s32 (int32x2_t) +@end itemize + + +@itemize @bullet +@item int8x8_t vreinterpret_s8_s16 (int16x4_t) +@end itemize + + +@itemize @bullet +@item int8x8_t vreinterpret_s8_u64 (uint64x1_t) +@end itemize + + +@itemize @bullet +@item int8x8_t vreinterpret_s8_s64 (int64x1_t) +@end itemize + + +@itemize @bullet +@item int8x8_t vreinterpret_s8_f32 (float32x2_t) +@end itemize + + +@itemize @bullet +@item int8x8_t vreinterpret_s8_p16 (poly16x4_t) +@end itemize + + +@itemize @bullet +@item int8x8_t vreinterpret_s8_p8 (poly8x8_t) +@end itemize + + +@itemize @bullet +@item int8x16_t vreinterpretq_s8_u32 (uint32x4_t) +@end itemize + + +@itemize @bullet +@item int8x16_t vreinterpretq_s8_u16 (uint16x8_t) +@end itemize + + +@itemize @bullet +@item int8x16_t vreinterpretq_s8_u8 (uint8x16_t) +@end itemize + + +@itemize @bullet +@item int8x16_t vreinterpretq_s8_s32 (int32x4_t) +@end itemize + + +@itemize @bullet +@item int8x16_t vreinterpretq_s8_s16 (int16x8_t) +@end itemize + + +@itemize @bullet +@item int8x16_t vreinterpretq_s8_u64 (uint64x2_t) +@end itemize + + +@itemize @bullet +@item int8x16_t vreinterpretq_s8_s64 (int64x2_t) +@end itemize + + +@itemize @bullet +@item int8x16_t vreinterpretq_s8_f32 (float32x4_t) +@end itemize + + +@itemize @bullet +@item int8x16_t vreinterpretq_s8_p16 (poly16x8_t) +@end itemize + + +@itemize @bullet +@item int8x16_t vreinterpretq_s8_p8 (poly8x16_t) +@end itemize + + +@itemize @bullet +@item int16x4_t vreinterpret_s16_u32 (uint32x2_t) +@end itemize + + +@itemize @bullet +@item int16x4_t vreinterpret_s16_u16 (uint16x4_t) +@end itemize + + +@itemize @bullet +@item int16x4_t vreinterpret_s16_u8 (uint8x8_t) +@end itemize + + +@itemize @bullet +@item int16x4_t vreinterpret_s16_s32 (int32x2_t) +@end itemize + + +@itemize @bullet +@item int16x4_t vreinterpret_s16_s8 (int8x8_t) +@end itemize + + +@itemize @bullet +@item int16x4_t vreinterpret_s16_u64 (uint64x1_t) +@end itemize + + +@itemize @bullet +@item int16x4_t vreinterpret_s16_s64 (int64x1_t) +@end itemize + + +@itemize @bullet +@item int16x4_t vreinterpret_s16_f32 (float32x2_t) +@end itemize + + +@itemize @bullet +@item int16x4_t vreinterpret_s16_p16 (poly16x4_t) +@end itemize + + +@itemize @bullet +@item int16x4_t vreinterpret_s16_p8 (poly8x8_t) +@end itemize + + +@itemize @bullet +@item int16x8_t vreinterpretq_s16_u32 (uint32x4_t) +@end itemize + + +@itemize @bullet +@item int16x8_t vreinterpretq_s16_u16 (uint16x8_t) +@end itemize + + +@itemize @bullet +@item int16x8_t vreinterpretq_s16_u8 (uint8x16_t) +@end itemize + + +@itemize @bullet +@item int16x8_t vreinterpretq_s16_s32 (int32x4_t) +@end itemize + + +@itemize @bullet +@item int16x8_t vreinterpretq_s16_s8 (int8x16_t) +@end itemize + + +@itemize @bullet +@item int16x8_t vreinterpretq_s16_u64 (uint64x2_t) +@end itemize + + +@itemize @bullet +@item int16x8_t vreinterpretq_s16_s64 (int64x2_t) +@end itemize + + +@itemize @bullet +@item int16x8_t vreinterpretq_s16_f32 (float32x4_t) +@end itemize + + +@itemize @bullet +@item int16x8_t vreinterpretq_s16_p16 (poly16x8_t) +@end itemize + + +@itemize @bullet +@item int16x8_t vreinterpretq_s16_p8 (poly8x16_t) +@end itemize + + +@itemize @bullet +@item int32x2_t vreinterpret_s32_u32 (uint32x2_t) +@end itemize + + +@itemize @bullet +@item int32x2_t vreinterpret_s32_u16 (uint16x4_t) +@end itemize + + +@itemize @bullet +@item int32x2_t vreinterpret_s32_u8 (uint8x8_t) +@end itemize + + +@itemize @bullet +@item int32x2_t vreinterpret_s32_s16 (int16x4_t) +@end itemize + + +@itemize @bullet +@item int32x2_t vreinterpret_s32_s8 (int8x8_t) +@end itemize + + +@itemize @bullet +@item int32x2_t vreinterpret_s32_u64 (uint64x1_t) +@end itemize + + +@itemize @bullet +@item int32x2_t vreinterpret_s32_s64 (int64x1_t) +@end itemize + + +@itemize @bullet +@item int32x2_t vreinterpret_s32_f32 (float32x2_t) +@end itemize + + +@itemize @bullet +@item int32x2_t vreinterpret_s32_p16 (poly16x4_t) +@end itemize + + +@itemize @bullet +@item int32x2_t vreinterpret_s32_p8 (poly8x8_t) +@end itemize + + +@itemize @bullet +@item int32x4_t vreinterpretq_s32_u32 (uint32x4_t) +@end itemize + + +@itemize @bullet +@item int32x4_t vreinterpretq_s32_u16 (uint16x8_t) +@end itemize + + +@itemize @bullet +@item int32x4_t vreinterpretq_s32_u8 (uint8x16_t) +@end itemize + + +@itemize @bullet +@item int32x4_t vreinterpretq_s32_s16 (int16x8_t) +@end itemize + + +@itemize @bullet +@item int32x4_t vreinterpretq_s32_s8 (int8x16_t) +@end itemize + + +@itemize @bullet +@item int32x4_t vreinterpretq_s32_u64 (uint64x2_t) +@end itemize + + +@itemize @bullet +@item int32x4_t vreinterpretq_s32_s64 (int64x2_t) +@end itemize + + +@itemize @bullet +@item int32x4_t vreinterpretq_s32_f32 (float32x4_t) +@end itemize + + +@itemize @bullet +@item int32x4_t vreinterpretq_s32_p16 (poly16x8_t) +@end itemize + + +@itemize @bullet +@item int32x4_t vreinterpretq_s32_p8 (poly8x16_t) +@end itemize + + +@itemize @bullet +@item uint8x8_t vreinterpret_u8_u32 (uint32x2_t) +@end itemize + + +@itemize @bullet +@item uint8x8_t vreinterpret_u8_u16 (uint16x4_t) +@end itemize + + +@itemize @bullet +@item uint8x8_t vreinterpret_u8_s32 (int32x2_t) +@end itemize + + +@itemize @bullet +@item uint8x8_t vreinterpret_u8_s16 (int16x4_t) +@end itemize + + +@itemize @bullet +@item uint8x8_t vreinterpret_u8_s8 (int8x8_t) +@end itemize + + +@itemize @bullet +@item uint8x8_t vreinterpret_u8_u64 (uint64x1_t) +@end itemize + + +@itemize @bullet +@item uint8x8_t vreinterpret_u8_s64 (int64x1_t) +@end itemize + + +@itemize @bullet +@item uint8x8_t vreinterpret_u8_f32 (float32x2_t) +@end itemize + + +@itemize @bullet +@item uint8x8_t vreinterpret_u8_p16 (poly16x4_t) +@end itemize + + +@itemize @bullet +@item uint8x8_t vreinterpret_u8_p8 (poly8x8_t) +@end itemize + + +@itemize @bullet +@item uint8x16_t vreinterpretq_u8_u32 (uint32x4_t) +@end itemize + + +@itemize @bullet +@item uint8x16_t vreinterpretq_u8_u16 (uint16x8_t) +@end itemize + + +@itemize @bullet +@item uint8x16_t vreinterpretq_u8_s32 (int32x4_t) +@end itemize + + +@itemize @bullet +@item uint8x16_t vreinterpretq_u8_s16 (int16x8_t) +@end itemize + + +@itemize @bullet +@item uint8x16_t vreinterpretq_u8_s8 (int8x16_t) +@end itemize + + +@itemize @bullet +@item uint8x16_t vreinterpretq_u8_u64 (uint64x2_t) +@end itemize + + +@itemize @bullet +@item uint8x16_t vreinterpretq_u8_s64 (int64x2_t) +@end itemize + + +@itemize @bullet +@item uint8x16_t vreinterpretq_u8_f32 (float32x4_t) +@end itemize + + +@itemize @bullet +@item uint8x16_t vreinterpretq_u8_p16 (poly16x8_t) +@end itemize + + +@itemize @bullet +@item uint8x16_t vreinterpretq_u8_p8 (poly8x16_t) +@end itemize + + +@itemize @bullet +@item uint16x4_t vreinterpret_u16_u32 (uint32x2_t) +@end itemize + + +@itemize @bullet +@item uint16x4_t vreinterpret_u16_u8 (uint8x8_t) +@end itemize + + +@itemize @bullet +@item uint16x4_t vreinterpret_u16_s32 (int32x2_t) +@end itemize + + +@itemize @bullet +@item uint16x4_t vreinterpret_u16_s16 (int16x4_t) +@end itemize + + +@itemize @bullet +@item uint16x4_t vreinterpret_u16_s8 (int8x8_t) +@end itemize + + +@itemize @bullet +@item uint16x4_t vreinterpret_u16_u64 (uint64x1_t) +@end itemize + + +@itemize @bullet +@item uint16x4_t vreinterpret_u16_s64 (int64x1_t) +@end itemize + + +@itemize @bullet +@item uint16x4_t vreinterpret_u16_f32 (float32x2_t) +@end itemize + + +@itemize @bullet +@item uint16x4_t vreinterpret_u16_p16 (poly16x4_t) +@end itemize + + +@itemize @bullet +@item uint16x4_t vreinterpret_u16_p8 (poly8x8_t) +@end itemize + + +@itemize @bullet +@item uint16x8_t vreinterpretq_u16_u32 (uint32x4_t) +@end itemize + + +@itemize @bullet +@item uint16x8_t vreinterpretq_u16_u8 (uint8x16_t) +@end itemize + + +@itemize @bullet +@item uint16x8_t vreinterpretq_u16_s32 (int32x4_t) +@end itemize + + +@itemize @bullet +@item uint16x8_t vreinterpretq_u16_s16 (int16x8_t) +@end itemize + + +@itemize @bullet +@item uint16x8_t vreinterpretq_u16_s8 (int8x16_t) +@end itemize + + +@itemize @bullet +@item uint16x8_t vreinterpretq_u16_u64 (uint64x2_t) +@end itemize + + +@itemize @bullet +@item uint16x8_t vreinterpretq_u16_s64 (int64x2_t) +@end itemize + + +@itemize @bullet +@item uint16x8_t vreinterpretq_u16_f32 (float32x4_t) +@end itemize + + +@itemize @bullet +@item uint16x8_t vreinterpretq_u16_p16 (poly16x8_t) +@end itemize + + +@itemize @bullet +@item uint16x8_t vreinterpretq_u16_p8 (poly8x16_t) +@end itemize + + +@itemize @bullet +@item uint32x2_t vreinterpret_u32_u16 (uint16x4_t) +@end itemize + + +@itemize @bullet +@item uint32x2_t vreinterpret_u32_u8 (uint8x8_t) +@end itemize + + +@itemize @bullet +@item uint32x2_t vreinterpret_u32_s32 (int32x2_t) +@end itemize + + +@itemize @bullet +@item uint32x2_t vreinterpret_u32_s16 (int16x4_t) +@end itemize + + +@itemize @bullet +@item uint32x2_t vreinterpret_u32_s8 (int8x8_t) +@end itemize + + +@itemize @bullet +@item uint32x2_t vreinterpret_u32_u64 (uint64x1_t) +@end itemize + + +@itemize @bullet +@item uint32x2_t vreinterpret_u32_s64 (int64x1_t) +@end itemize + + +@itemize @bullet +@item uint32x2_t vreinterpret_u32_f32 (float32x2_t) +@end itemize + + +@itemize @bullet +@item uint32x2_t vreinterpret_u32_p16 (poly16x4_t) +@end itemize + + +@itemize @bullet +@item uint32x2_t vreinterpret_u32_p8 (poly8x8_t) +@end itemize + + +@itemize @bullet +@item uint32x4_t vreinterpretq_u32_u16 (uint16x8_t) +@end itemize + + +@itemize @bullet +@item uint32x4_t vreinterpretq_u32_u8 (uint8x16_t) +@end itemize + + +@itemize @bullet +@item uint32x4_t vreinterpretq_u32_s32 (int32x4_t) +@end itemize + + +@itemize @bullet +@item uint32x4_t vreinterpretq_u32_s16 (int16x8_t) +@end itemize + + +@itemize @bullet +@item uint32x4_t vreinterpretq_u32_s8 (int8x16_t) +@end itemize + + +@itemize @bullet +@item uint32x4_t vreinterpretq_u32_u64 (uint64x2_t) +@end itemize + + +@itemize @bullet +@item uint32x4_t vreinterpretq_u32_s64 (int64x2_t) +@end itemize + + +@itemize @bullet +@item uint32x4_t vreinterpretq_u32_f32 (float32x4_t) +@end itemize + + +@itemize @bullet +@item uint32x4_t vreinterpretq_u32_p16 (poly16x8_t) +@end itemize + + +@itemize @bullet +@item uint32x4_t vreinterpretq_u32_p8 (poly8x16_t) +@end itemize + + + + diff --git a/gcc/doc/bugreport.texi b/gcc/doc/bugreport.texi new file mode 100644 index 000000000..536f934b0 --- /dev/null +++ b/gcc/doc/bugreport.texi @@ -0,0 +1,91 @@ +@c Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998, +@c 1999, 2000, 2001, 2003, 2004, 2007 Free Software Foundation, Inc. +@c This is part of the GCC manual. +@c For copying conditions, see the file gcc.texi. + +@node Bugs +@chapter Reporting Bugs +@cindex bugs +@cindex reporting bugs + +Your bug reports play an essential role in making GCC reliable. + +When you encounter a problem, the first thing to do is to see if it is +already known. @xref{Trouble}. If it isn't known, then you should +report the problem. + +@menu +* Criteria: Bug Criteria. Have you really found a bug? +* Reporting: Bug Reporting. How to report a bug effectively. +* Known: Trouble. Known problems. +* Help: Service. Where to ask for help. +@end menu + +@node Bug Criteria,Bug Reporting,,Bugs +@section Have You Found a Bug? +@cindex bug criteria + +If you are not sure whether you have found a bug, here are some guidelines: + +@itemize @bullet +@cindex fatal signal +@cindex core dump +@item +If the compiler gets a fatal signal, for any input whatever, that is a +compiler bug. Reliable compilers never crash. + +@cindex invalid assembly code +@cindex assembly code, invalid +@item +If the compiler produces invalid assembly code, for any input whatever +(except an @code{asm} statement), that is a compiler bug, unless the +compiler reports errors (not just warnings) which would ordinarily +prevent the assembler from being run. + +@cindex undefined behavior +@cindex undefined function value +@cindex increment operators +@item +If the compiler produces valid assembly code that does not correctly +execute the input source code, that is a compiler bug. + +However, you must double-check to make sure, because you may have a +program whose behavior is undefined, which happened by chance to give +the desired results with another C or C++ compiler. + +For example, in many nonoptimizing compilers, you can write @samp{x;} +at the end of a function instead of @samp{return x;}, with the same +results. But the value of the function is undefined if @code{return} +is omitted; it is not a bug when GCC produces different results. + +Problems often result from expressions with two increment operators, +as in @code{f (*p++, *p++)}. Your previous compiler might have +interpreted that expression the way you intended; GCC might +interpret it another way. Neither compiler is wrong. The bug is +in your code. + +After you have localized the error to a single source line, it should +be easy to check for these things. If your program is correct and +well defined, you have found a compiler bug. + +@item +If the compiler produces an error message for valid input, that is a +compiler bug. + +@cindex invalid input +@item +If the compiler does not produce an error message for invalid input, +that is a compiler bug. However, you should note that your idea of +``invalid input'' might be someone else's idea of ``an extension'' or +``support for traditional practice''. + +@item +If you are an experienced user of one of the languages GCC supports, your +suggestions for improvement of GCC are welcome in any case. +@end itemize + +@node Bug Reporting,,Bug Criteria,Bugs +@section How and where to Report Bugs +@cindex compiler bugs, reporting + +Bugs should be reported to the bug database at @value{BUGURL}. diff --git a/gcc/doc/cfg.texi b/gcc/doc/cfg.texi new file mode 100644 index 000000000..7f9364832 --- /dev/null +++ b/gcc/doc/cfg.texi @@ -0,0 +1,659 @@ +@c -*-texinfo-*- +@c Copyright (C) 2001, 2003, 2004, 2005, 2006, 2007, 2008 Free Software +@c Foundation, Inc. +@c This is part of the GCC manual. +@c For copying conditions, see the file gcc.texi. + +@c --------------------------------------------------------------------- +@c Control Flow Graph +@c --------------------------------------------------------------------- + +@node Control Flow +@chapter Control Flow Graph +@cindex CFG, Control Flow Graph +@findex basic-block.h + +A control flow graph (CFG) is a data structure built on top of the +intermediate code representation (the RTL or @code{tree} instruction +stream) abstracting the control flow behavior of a function that is +being compiled. The CFG is a directed graph where the vertices +represent basic blocks and edges represent possible transfer of +control flow from one basic block to another. The data structures +used to represent the control flow graph are defined in +@file{basic-block.h}. + +@menu +* Basic Blocks:: The definition and representation of basic blocks. +* Edges:: Types of edges and their representation. +* Profile information:: Representation of frequencies and probabilities. +* Maintaining the CFG:: Keeping the control flow graph and up to date. +* Liveness information:: Using and maintaining liveness information. +@end menu + + +@node Basic Blocks +@section Basic Blocks + +@cindex basic block +@findex basic_block +A basic block is a straight-line sequence of code with only one entry +point and only one exit. In GCC, basic blocks are represented using +the @code{basic_block} data type. + +@findex next_bb, prev_bb, FOR_EACH_BB +Two pointer members of the @code{basic_block} structure are the +pointers @code{next_bb} and @code{prev_bb}. These are used to keep +doubly linked chain of basic blocks in the same order as the +underlying instruction stream. The chain of basic blocks is updated +transparently by the provided API for manipulating the CFG@. The macro +@code{FOR_EACH_BB} can be used to visit all the basic blocks in +lexicographical order. Dominator traversals are also possible using +@code{walk_dominator_tree}. Given two basic blocks A and B, block A +dominates block B if A is @emph{always} executed before B@. + +@findex BASIC_BLOCK +The @code{BASIC_BLOCK} array contains all basic blocks in an +unspecified order. Each @code{basic_block} structure has a field +that holds a unique integer identifier @code{index} that is the +index of the block in the @code{BASIC_BLOCK} array. +The total number of basic blocks in the function is +@code{n_basic_blocks}. Both the basic block indices and +the total number of basic blocks may vary during the compilation +process, as passes reorder, create, duplicate, and destroy basic +blocks. The index for any block should never be greater than +@code{last_basic_block}. + +@findex ENTRY_BLOCK_PTR, EXIT_BLOCK_PTR +Special basic blocks represent possible entry and exit points of a +function. These blocks are called @code{ENTRY_BLOCK_PTR} and +@code{EXIT_BLOCK_PTR}. These blocks do not contain any code, and are +not elements of the @code{BASIC_BLOCK} array. Therefore they have +been assigned unique, negative index numbers. + +Each @code{basic_block} also contains pointers to the first +instruction (the @dfn{head}) and the last instruction (the @dfn{tail}) +or @dfn{end} of the instruction stream contained in a basic block. In +fact, since the @code{basic_block} data type is used to represent +blocks in both major intermediate representations of GCC (@code{tree} +and RTL), there are pointers to the head and end of a basic block for +both representations. + +@findex NOTE_INSN_BASIC_BLOCK, CODE_LABEL, notes +For RTL, these pointers are @code{rtx head, end}. In the RTL function +representation, the head pointer always points either to a +@code{NOTE_INSN_BASIC_BLOCK} or to a @code{CODE_LABEL}, if present. +In the RTL representation of a function, the instruction stream +contains not only the ``real'' instructions, but also @dfn{notes}. +Any function that moves or duplicates the basic blocks needs +to take care of updating of these notes. Many of these notes expect +that the instruction stream consists of linear regions, making such +updates difficult. The @code{NOTE_INSN_BASIC_BLOCK} note is the only +kind of note that may appear in the instruction stream contained in a +basic block. The instruction stream of a basic block always follows a +@code{NOTE_INSN_BASIC_BLOCK}, but zero or more @code{CODE_LABEL} +nodes can precede the block note. A basic block ends by control flow +instruction or last instruction before following @code{CODE_LABEL} or +@code{NOTE_INSN_BASIC_BLOCK}. A @code{CODE_LABEL} cannot appear in +the instruction stream of a basic block. + +@findex can_fallthru +@cindex table jump +In addition to notes, the jump table vectors are also represented as +``pseudo-instructions'' inside the insn stream. These vectors never +appear in the basic block and should always be placed just after the +table jump instructions referencing them. After removing the +table-jump it is often difficult to eliminate the code computing the +address and referencing the vector, so cleaning up these vectors is +postponed until after liveness analysis. Thus the jump table vectors +may appear in the insn stream unreferenced and without any purpose. +Before any edge is made @dfn{fall-thru}, the existence of such +construct in the way needs to be checked by calling +@code{can_fallthru} function. + +@cindex block statement iterators +For the @code{tree} representation, the head and end of the basic block +are being pointed to by the @code{stmt_list} field, but this special +@code{tree} should never be referenced directly. Instead, at the tree +level abstract containers and iterators are used to access statements +and expressions in basic blocks. These iterators are called +@dfn{block statement iterators} (BSIs). Grep for @code{^bsi} +in the various @file{tree-*} files. +The following snippet will pretty-print all the statements of the +program in the GIMPLE representation. + +@smallexample +FOR_EACH_BB (bb) + @{ + block_stmt_iterator si; + + for (si = bsi_start (bb); !bsi_end_p (si); bsi_next (&si)) + @{ + tree stmt = bsi_stmt (si); + print_generic_stmt (stderr, stmt, 0); + @} + @} +@end smallexample + + +@node Edges +@section Edges + +@cindex edge in the flow graph +@findex edge +Edges represent possible control flow transfers from the end of some +basic block A to the head of another basic block B@. We say that A is +a predecessor of B, and B is a successor of A@. Edges are represented +in GCC with the @code{edge} data type. Each @code{edge} acts as a +link between two basic blocks: the @code{src} member of an edge +points to the predecessor basic block of the @code{dest} basic block. +The members @code{preds} and @code{succs} of the @code{basic_block} data +type point to type-safe vectors of edges to the predecessors and +successors of the block. + +@cindex edge iterators +When walking the edges in an edge vector, @dfn{edge iterators} should +be used. Edge iterators are constructed using the +@code{edge_iterator} data structure and several methods are available +to operate on them: + +@ftable @code +@item ei_start +This function initializes an @code{edge_iterator} that points to the +first edge in a vector of edges. + +@item ei_last +This function initializes an @code{edge_iterator} that points to the +last edge in a vector of edges. + +@item ei_end_p +This predicate is @code{true} if an @code{edge_iterator} represents +the last edge in an edge vector. + +@item ei_one_before_end_p +This predicate is @code{true} if an @code{edge_iterator} represents +the second last edge in an edge vector. + +@item ei_next +This function takes a pointer to an @code{edge_iterator} and makes it +point to the next edge in the sequence. + +@item ei_prev +This function takes a pointer to an @code{edge_iterator} and makes it +point to the previous edge in the sequence. + +@item ei_edge +This function returns the @code{edge} currently pointed to by an +@code{edge_iterator}. + +@item ei_safe_safe +This function returns the @code{edge} currently pointed to by an +@code{edge_iterator}, but returns @code{NULL} if the iterator is +pointing at the end of the sequence. This function has been provided +for existing code makes the assumption that a @code{NULL} edge +indicates the end of the sequence. + +@end ftable + +The convenience macro @code{FOR_EACH_EDGE} can be used to visit all of +the edges in a sequence of predecessor or successor edges. It must +not be used when an element might be removed during the traversal, +otherwise elements will be missed. Here is an example of how to use +the macro: + +@smallexample +edge e; +edge_iterator ei; + +FOR_EACH_EDGE (e, ei, bb->succs) + @{ + if (e->flags & EDGE_FALLTHRU) + break; + @} +@end smallexample + +@findex fall-thru +There are various reasons why control flow may transfer from one block +to another. One possibility is that some instruction, for example a +@code{CODE_LABEL}, in a linearized instruction stream just always +starts a new basic block. In this case a @dfn{fall-thru} edge links +the basic block to the first following basic block. But there are +several other reasons why edges may be created. The @code{flags} +field of the @code{edge} data type is used to store information +about the type of edge we are dealing with. Each edge is of one of +the following types: + +@table @emph +@item jump +No type flags are set for edges corresponding to jump instructions. +These edges are used for unconditional or conditional jumps and in +RTL also for table jumps. They are the easiest to manipulate as they +may be freely redirected when the flow graph is not in SSA form. + +@item fall-thru +@findex EDGE_FALLTHRU, force_nonfallthru +Fall-thru edges are present in case where the basic block may continue +execution to the following one without branching. These edges have +the @code{EDGE_FALLTHRU} flag set. Unlike other types of edges, these +edges must come into the basic block immediately following in the +instruction stream. The function @code{force_nonfallthru} is +available to insert an unconditional jump in the case that redirection +is needed. Note that this may require creation of a new basic block. + +@item exception handling +@cindex exception handling +@findex EDGE_ABNORMAL, EDGE_EH +Exception handling edges represent possible control transfers from a +trapping instruction to an exception handler. The definition of +``trapping'' varies. In C++, only function calls can throw, but for +Java, exceptions like division by zero or segmentation fault are +defined and thus each instruction possibly throwing this kind of +exception needs to be handled as control flow instruction. Exception +edges have the @code{EDGE_ABNORMAL} and @code{EDGE_EH} flags set. + +@findex purge_dead_edges +When updating the instruction stream it is easy to change possibly +trapping instruction to non-trapping, by simply removing the exception +edge. The opposite conversion is difficult, but should not happen +anyway. The edges can be eliminated via @code{purge_dead_edges} call. + +@findex REG_EH_REGION, EDGE_ABNORMAL_CALL +In the RTL representation, the destination of an exception edge is +specified by @code{REG_EH_REGION} note attached to the insn. +In case of a trapping call the @code{EDGE_ABNORMAL_CALL} flag is set +too. In the @code{tree} representation, this extra flag is not set. + +@findex may_trap_p, tree_could_trap_p +In the RTL representation, the predicate @code{may_trap_p} may be used +to check whether instruction still may trap or not. For the tree +representation, the @code{tree_could_trap_p} predicate is available, +but this predicate only checks for possible memory traps, as in +dereferencing an invalid pointer location. + + +@item sibling calls +@cindex sibling call +@findex EDGE_ABNORMAL, EDGE_SIBCALL +Sibling calls or tail calls terminate the function in a non-standard +way and thus an edge to the exit must be present. +@code{EDGE_SIBCALL} and @code{EDGE_ABNORMAL} are set in such case. +These edges only exist in the RTL representation. + +@item computed jumps +@cindex computed jump +@findex EDGE_ABNORMAL +Computed jumps contain edges to all labels in the function referenced +from the code. All those edges have @code{EDGE_ABNORMAL} flag set. +The edges used to represent computed jumps often cause compile time +performance problems, since functions consisting of many taken labels +and many computed jumps may have @emph{very} dense flow graphs, so +these edges need to be handled with special care. During the earlier +stages of the compilation process, GCC tries to avoid such dense flow +graphs by factoring computed jumps. For example, given the following +series of jumps, + +@smallexample + goto *x; + [ @dots{} ] + + goto *x; + [ @dots{} ] + + goto *x; + [ @dots{} ] +@end smallexample + +@noindent +factoring the computed jumps results in the following code sequence +which has a much simpler flow graph: + +@smallexample + goto y; + [ @dots{} ] + + goto y; + [ @dots{} ] + + goto y; + [ @dots{} ] + +y: + goto *x; +@end smallexample + +However, the classic problem with this transformation is that it has a +runtime cost in there resulting code: An extra jump. Therefore, the +computed jumps are un-factored in the later passes of the compiler. +Be aware of that when you work on passes in that area. There have +been numerous examples already where the compile time for code with +unfactored computed jumps caused some serious headaches. + +@item nonlocal goto handlers +@cindex nonlocal goto handler +@findex EDGE_ABNORMAL, EDGE_ABNORMAL_CALL +GCC allows nested functions to return into caller using a @code{goto} +to a label passed to as an argument to the callee. The labels passed +to nested functions contain special code to cleanup after function +call. Such sections of code are referred to as ``nonlocal goto +receivers''. If a function contains such nonlocal goto receivers, an +edge from the call to the label is created with the +@code{EDGE_ABNORMAL} and @code{EDGE_ABNORMAL_CALL} flags set. + +@item function entry points +@cindex function entry point, alternate function entry point +@findex LABEL_ALTERNATE_NAME +By definition, execution of function starts at basic block 0, so there +is always an edge from the @code{ENTRY_BLOCK_PTR} to basic block 0. +There is no @code{tree} representation for alternate entry points at +this moment. In RTL, alternate entry points are specified by +@code{CODE_LABEL} with @code{LABEL_ALTERNATE_NAME} defined. This +feature is currently used for multiple entry point prologues and is +limited to post-reload passes only. This can be used by back-ends to +emit alternate prologues for functions called from different contexts. +In future full support for multiple entry functions defined by Fortran +90 needs to be implemented. + +@item function exits +In the pre-reload representation a function terminates after the last +instruction in the insn chain and no explicit return instructions are +used. This corresponds to the fall-thru edge into exit block. After +reload, optimal RTL epilogues are used that use explicit (conditional) +return instructions that are represented by edges with no flags set. + +@end table + + +@node Profile information +@section Profile information + +@cindex profile representation +In many cases a compiler must make a choice whether to trade speed in +one part of code for speed in another, or to trade code size for code +speed. In such cases it is useful to know information about how often +some given block will be executed. That is the purpose for +maintaining profile within the flow graph. +GCC can handle profile information obtained through @dfn{profile +feedback}, but it can also estimate branch probabilities based on +statics and heuristics. + +@cindex profile feedback +The feedback based profile is produced by compiling the program with +instrumentation, executing it on a train run and reading the numbers +of executions of basic blocks and edges back to the compiler while +re-compiling the program to produce the final executable. This method +provides very accurate information about where a program spends most +of its time on the train run. Whether it matches the average run of +course depends on the choice of train data set, but several studies +have shown that the behavior of a program usually changes just +marginally over different data sets. + +@cindex Static profile estimation +@cindex branch prediction +@findex predict.def +When profile feedback is not available, the compiler may be asked to +attempt to predict the behavior of each branch in the program using a +set of heuristics (see @file{predict.def} for details) and compute +estimated frequencies of each basic block by propagating the +probabilities over the graph. + +@findex frequency, count, BB_FREQ_BASE +Each @code{basic_block} contains two integer fields to represent +profile information: @code{frequency} and @code{count}. The +@code{frequency} is an estimation how often is basic block executed +within a function. It is represented as an integer scaled in the +range from 0 to @code{BB_FREQ_BASE}. The most frequently executed +basic block in function is initially set to @code{BB_FREQ_BASE} and +the rest of frequencies are scaled accordingly. During optimization, +the frequency of the most frequent basic block can both decrease (for +instance by loop unrolling) or grow (for instance by cross-jumping +optimization), so scaling sometimes has to be performed multiple +times. + +@findex gcov_type +The @code{count} contains hard-counted numbers of execution measured +during training runs and is nonzero only when profile feedback is +available. This value is represented as the host's widest integer +(typically a 64 bit integer) of the special type @code{gcov_type}. + +Most optimization passes can use only the frequency information of a +basic block, but a few passes may want to know hard execution counts. +The frequencies should always match the counts after scaling, however +during updating of the profile information numerical error may +accumulate into quite large errors. + +@findex REG_BR_PROB_BASE, EDGE_FREQUENCY +Each edge also contains a branch probability field: an integer in the +range from 0 to @code{REG_BR_PROB_BASE}. It represents probability of +passing control from the end of the @code{src} basic block to the +@code{dest} basic block, i.e.@: the probability that control will flow +along this edge. The @code{EDGE_FREQUENCY} macro is available to +compute how frequently a given edge is taken. There is a @code{count} +field for each edge as well, representing same information as for a +basic block. + +The basic block frequencies are not represented in the instruction +stream, but in the RTL representation the edge frequencies are +represented for conditional jumps (via the @code{REG_BR_PROB} +macro) since they are used when instructions are output to the +assembly file and the flow graph is no longer maintained. + +@cindex reverse probability +The probability that control flow arrives via a given edge to its +destination basic block is called @dfn{reverse probability} and is not +directly represented, but it may be easily computed from frequencies +of basic blocks. + +@findex redirect_edge_and_branch +Updating profile information is a delicate task that can unfortunately +not be easily integrated with the CFG manipulation API@. Many of the +functions and hooks to modify the CFG, such as +@code{redirect_edge_and_branch}, do not have enough information to +easily update the profile, so updating it is in the majority of cases +left up to the caller. It is difficult to uncover bugs in the profile +updating code, because they manifest themselves only by producing +worse code, and checking profile consistency is not possible because +of numeric error accumulation. Hence special attention needs to be +given to this issue in each pass that modifies the CFG@. + +@findex REG_BR_PROB_BASE, BB_FREQ_BASE, count +It is important to point out that @code{REG_BR_PROB_BASE} and +@code{BB_FREQ_BASE} are both set low enough to be possible to compute +second power of any frequency or probability in the flow graph, it is +not possible to even square the @code{count} field, as modern CPUs are +fast enough to execute $2^32$ operations quickly. + + +@node Maintaining the CFG +@section Maintaining the CFG +@findex cfghooks.h + +An important task of each compiler pass is to keep both the control +flow graph and all profile information up-to-date. Reconstruction of +the control flow graph after each pass is not an option, since it may be +very expensive and lost profile information cannot be reconstructed at +all. + +GCC has two major intermediate representations, and both use the +@code{basic_block} and @code{edge} data types to represent control +flow. Both representations share as much of the CFG maintenance code +as possible. For each representation, a set of @dfn{hooks} is defined +so that each representation can provide its own implementation of CFG +manipulation routines when necessary. These hooks are defined in +@file{cfghooks.h}. There are hooks for almost all common CFG +manipulations, including block splitting and merging, edge redirection +and creating and deleting basic blocks. These hooks should provide +everything you need to maintain and manipulate the CFG in both the RTL +and @code{tree} representation. + +At the moment, the basic block boundaries are maintained transparently +when modifying instructions, so there rarely is a need to move them +manually (such as in case someone wants to output instruction outside +basic block explicitly). +Often the CFG may be better viewed as integral part of instruction +chain, than structure built on the top of it. However, in principle +the control flow graph for the @code{tree} representation is +@emph{not} an integral part of the representation, in that a function +tree may be expanded without first building a flow graph for the +@code{tree} representation at all. This happens when compiling +without any @code{tree} optimization enabled. When the @code{tree} +optimizations are enabled and the instruction stream is rewritten in +SSA form, the CFG is very tightly coupled with the instruction stream. +In particular, statement insertion and removal has to be done with +care. In fact, the whole @code{tree} representation can not be easily +used or maintained without proper maintenance of the CFG +simultaneously. + +@findex BLOCK_FOR_INSN, bb_for_stmt +In the RTL representation, each instruction has a +@code{BLOCK_FOR_INSN} value that represents pointer to the basic block +that contains the instruction. In the @code{tree} representation, the +function @code{bb_for_stmt} returns a pointer to the basic block +containing the queried statement. + +@cindex block statement iterators +When changes need to be applied to a function in its @code{tree} +representation, @dfn{block statement iterators} should be used. These +iterators provide an integrated abstraction of the flow graph and the +instruction stream. Block statement iterators are constructed using +the @code{block_stmt_iterator} data structure and several modifier are +available, including the following: + +@ftable @code +@item bsi_start +This function initializes a @code{block_stmt_iterator} that points to +the first non-empty statement in a basic block. + +@item bsi_last +This function initializes a @code{block_stmt_iterator} that points to +the last statement in a basic block. + +@item bsi_end_p +This predicate is @code{true} if a @code{block_stmt_iterator} +represents the end of a basic block. + +@item bsi_next +This function takes a @code{block_stmt_iterator} and makes it point to +its successor. + +@item bsi_prev +This function takes a @code{block_stmt_iterator} and makes it point to +its predecessor. + +@item bsi_insert_after +This function inserts a statement after the @code{block_stmt_iterator} +passed in. The final parameter determines whether the statement +iterator is updated to point to the newly inserted statement, or left +pointing to the original statement. + +@item bsi_insert_before +This function inserts a statement before the @code{block_stmt_iterator} +passed in. The final parameter determines whether the statement +iterator is updated to point to the newly inserted statement, or left +pointing to the original statement. + +@item bsi_remove +This function removes the @code{block_stmt_iterator} passed in and +rechains the remaining statements in a basic block, if any. +@end ftable + +@findex BB_HEAD, BB_END +In the RTL representation, the macros @code{BB_HEAD} and @code{BB_END} +may be used to get the head and end @code{rtx} of a basic block. No +abstract iterators are defined for traversing the insn chain, but you +can just use @code{NEXT_INSN} and @code{PREV_INSN} instead. @xref{Insns}. + +@findex purge_dead_edges +Usually a code manipulating pass simplifies the instruction stream and +the flow of control, possibly eliminating some edges. This may for +example happen when a conditional jump is replaced with an +unconditional jump, but also when simplifying possibly trapping +instruction to non-trapping while compiling Java. Updating of edges +is not transparent and each optimization pass is required to do so +manually. However only few cases occur in practice. The pass may +call @code{purge_dead_edges} on a given basic block to remove +superfluous edges, if any. + +@findex redirect_edge_and_branch, redirect_jump +Another common scenario is redirection of branch instructions, but +this is best modeled as redirection of edges in the control flow graph +and thus use of @code{redirect_edge_and_branch} is preferred over more +low level functions, such as @code{redirect_jump} that operate on RTL +chain only. The CFG hooks defined in @file{cfghooks.h} should provide +the complete API required for manipulating and maintaining the CFG@. + +@findex split_block +It is also possible that a pass has to insert control flow instruction +into the middle of a basic block, thus creating an entry point in the +middle of the basic block, which is impossible by definition: The +block must be split to make sure it only has one entry point, i.e.@: the +head of the basic block. The CFG hook @code{split_block} may be used +when an instruction in the middle of a basic block has to become the +target of a jump or branch instruction. + +@findex insert_insn_on_edge +@findex commit_edge_insertions +@findex bsi_insert_on_edge +@findex bsi_commit_edge_inserts +@cindex edge splitting +For a global optimizer, a common operation is to split edges in the +flow graph and insert instructions on them. In the RTL +representation, this can be easily done using the +@code{insert_insn_on_edge} function that emits an instruction +``on the edge'', caching it for a later @code{commit_edge_insertions} +call that will take care of moving the inserted instructions off the +edge into the instruction stream contained in a basic block. This +includes the creation of new basic blocks where needed. In the +@code{tree} representation, the equivalent functions are +@code{bsi_insert_on_edge} which inserts a block statement +iterator on an edge, and @code{bsi_commit_edge_inserts} which flushes +the instruction to actual instruction stream. + +While debugging the optimization pass, a @code{verify_flow_info} +function may be useful to find bugs in the control flow graph updating +code. + +Note that at present, the representation of control flow in the +@code{tree} representation is discarded before expanding to RTL@. +Long term the CFG should be maintained and ``expanded'' to the +RTL representation along with the function @code{tree} itself. + + +@node Liveness information +@section Liveness information +@cindex Liveness representation +Liveness information is useful to determine whether some register is +``live'' at given point of program, i.e.@: that it contains a value that +may be used at a later point in the program. This information is +used, for instance, during register allocation, as the pseudo +registers only need to be assigned to a unique hard register or to a +stack slot if they are live. The hard registers and stack slots may +be freely reused for other values when a register is dead. + +Liveness information is available in the back end starting with +@code{pass_df_initialize} and ending with @code{pass_df_finish}. Three +flavors of live analysis are available: With @code{LR}, it is possible +to determine at any point @code{P} in the function if the register may be +used on some path from @code{P} to the end of the function. With +@code{UR}, it is possible to determine if there is a path from the +beginning of the function to @code{P} that defines the variable. +@code{LIVE} is the intersection of the @code{LR} and @code{UR} and a +variable is live at @code{P} if there is both an assignment that reaches +it from the beginning of the function and a use that can be reached on +some path from @code{P} to the end of the function. + +In general @code{LIVE} is the most useful of the three. The macros +@code{DF_[LR,UR,LIVE]_[IN,OUT]} can be used to access this information. +The macros take a basic block number and return a bitmap that is indexed +by the register number. This information is only guaranteed to be up to +date after calls are made to @code{df_analyze}. See the file +@code{df-core.c} for details on using the dataflow. + + +@findex REG_DEAD, REG_UNUSED +The liveness information is stored partly in the RTL instruction stream +and partly in the flow graph. Local information is stored in the +instruction stream: Each instruction may contain @code{REG_DEAD} notes +representing that the value of a given register is no longer needed, or +@code{REG_UNUSED} notes representing that the value computed by the +instruction is never used. The second is useful for instructions +computing multiple values at once. + diff --git a/gcc/doc/collect2.texi b/gcc/doc/collect2.texi new file mode 100644 index 000000000..7cd5c9355 --- /dev/null +++ b/gcc/doc/collect2.texi @@ -0,0 +1,89 @@ +@c Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001 Free Software Foundation, Inc. +@c This is part of the GCC manual. +@c For copying conditions, see the file gcc.texi. + +@node Collect2 +@chapter @code{collect2} + +GCC uses a utility called @code{collect2} on nearly all systems to arrange +to call various initialization functions at start time. + +The program @code{collect2} works by linking the program once and +looking through the linker output file for symbols with particular names +indicating they are constructor functions. If it finds any, it +creates a new temporary @samp{.c} file containing a table of them, +compiles it, and links the program a second time including that file. + +@findex __main +@cindex constructors, automatic calls +The actual calls to the constructors are carried out by a subroutine +called @code{__main}, which is called (automatically) at the beginning +of the body of @code{main} (provided @code{main} was compiled with GNU +CC)@. Calling @code{__main} is necessary, even when compiling C code, to +allow linking C and C++ object code together. (If you use +@option{-nostdlib}, you get an unresolved reference to @code{__main}, +since it's defined in the standard GCC library. Include @option{-lgcc} at +the end of your compiler command line to resolve this reference.) + +The program @code{collect2} is installed as @code{ld} in the directory +where the passes of the compiler are installed. When @code{collect2} +needs to find the @emph{real} @code{ld}, it tries the following file +names: + +@itemize @bullet +@item +a hard coded linker file name, if GCC was configured with the +@option{--with-ld} option. + +@item +@file{real-ld} in the directories listed in the compiler's search +directories. + +@item +@file{real-ld} in the directories listed in the environment variable +@code{PATH}. + +@item +The file specified in the @code{REAL_LD_FILE_NAME} configuration macro, +if specified. + +@item +@file{ld} in the compiler's search directories, except that +@code{collect2} will not execute itself recursively. + +@item +@file{ld} in @code{PATH}. +@end itemize + +``The compiler's search directories'' means all the directories where +@command{gcc} searches for passes of the compiler. This includes +directories that you specify with @option{-B}. + +Cross-compilers search a little differently: + +@itemize @bullet +@item +@file{real-ld} in the compiler's search directories. + +@item +@file{@var{target}-real-ld} in @code{PATH}. + +@item +The file specified in the @code{REAL_LD_FILE_NAME} configuration macro, +if specified. + +@item +@file{ld} in the compiler's search directories. + +@item +@file{@var{target}-ld} in @code{PATH}. +@end itemize + +@code{collect2} explicitly avoids running @code{ld} using the file name +under which @code{collect2} itself was invoked. In fact, it remembers +up a list of such names---in case one copy of @code{collect2} finds +another copy (or version) of @code{collect2} installed as @code{ld} in a +second place in the search path. + +@code{collect2} searches for the utilities @code{nm} and @code{strip} +using the same algorithm as above for @code{ld}. diff --git a/gcc/doc/compat.texi b/gcc/doc/compat.texi new file mode 100644 index 000000000..4e65b4582 --- /dev/null +++ b/gcc/doc/compat.texi @@ -0,0 +1,156 @@ +@c Copyright (C) 2002, 2004 Free Software Foundation, Inc. +@c This is part of the GCC manual. +@c For copying conditions, see the file gcc.texi. + +@node Compatibility +@chapter Binary Compatibility +@cindex binary compatibility +@cindex ABI +@cindex application binary interface + +Binary compatibility encompasses several related concepts: + +@table @dfn +@item application binary interface (ABI) +The set of runtime conventions followed by all of the tools that deal +with binary representations of a program, including compilers, assemblers, +linkers, and language runtime support. +Some ABIs are formal with a written specification, possibly designed +by multiple interested parties. Others are simply the way things are +actually done by a particular set of tools. + +@item ABI conformance +A compiler conforms to an ABI if it generates code that follows all of +the specifications enumerated by that ABI@. +A library conforms to an ABI if it is implemented according to that ABI@. +An application conforms to an ABI if it is built using tools that conform +to that ABI and does not contain source code that specifically changes +behavior specified by the ABI@. + +@item calling conventions +Calling conventions are a subset of an ABI that specify of how arguments +are passed and function results are returned. + +@item interoperability +Different sets of tools are interoperable if they generate files that +can be used in the same program. The set of tools includes compilers, +assemblers, linkers, libraries, header files, startup files, and debuggers. +Binaries produced by different sets of tools are not interoperable unless +they implement the same ABI@. This applies to different versions of the +same tools as well as tools from different vendors. + +@item intercallability +Whether a function in a binary built by one set of tools can call a +function in a binary built by a different set of tools is a subset +of interoperability. + +@item implementation-defined features +Language standards include lists of implementation-defined features whose +behavior can vary from one implementation to another. Some of these +features are normally covered by a platform's ABI and others are not. +The features that are not covered by an ABI generally affect how a +program behaves, but not intercallability. + +@item compatibility +Conformance to the same ABI and the same behavior of implementation-defined +features are both relevant for compatibility. +@end table + +The application binary interface implemented by a C or C++ compiler +affects code generation and runtime support for: + +@itemize @bullet +@item +size and alignment of data types +@item +layout of structured types +@item +calling conventions +@item +register usage conventions +@item +interfaces for runtime arithmetic support +@item +object file formats +@end itemize + +In addition, the application binary interface implemented by a C++ compiler +affects code generation and runtime support for: +@itemize @bullet +@item +name mangling +@item +exception handling +@item +invoking constructors and destructors +@item +layout, alignment, and padding of classes +@item +layout and alignment of virtual tables +@end itemize + +Some GCC compilation options cause the compiler to generate code that +does not conform to the platform's default ABI@. Other options cause +different program behavior for implementation-defined features that are +not covered by an ABI@. These options are provided for consistency with +other compilers that do not follow the platform's default ABI or the +usual behavior of implementation-defined features for the platform. +Be very careful about using such options. + +Most platforms have a well-defined ABI that covers C code, but ABIs +that cover C++ functionality are not yet common. + +Starting with GCC 3.2, GCC binary conventions for C++ are based on a +written, vendor-neutral C++ ABI that was designed to be specific to +64-bit Itanium but also includes generic specifications that apply to +any platform. +This C++ ABI is also implemented by other compiler vendors on some +platforms, notably GNU/Linux and BSD systems. +We have tried hard to provide a stable ABI that will be compatible with +future GCC releases, but it is possible that we will encounter problems +that make this difficult. Such problems could include different +interpretations of the C++ ABI by different vendors, bugs in the ABI, or +bugs in the implementation of the ABI in different compilers. +GCC's @option{-Wabi} switch warns when G++ generates code that is +probably not compatible with the C++ ABI@. + +The C++ library used with a C++ compiler includes the Standard C++ +Library, with functionality defined in the C++ Standard, plus language +runtime support. The runtime support is included in a C++ ABI, but there +is no formal ABI for the Standard C++ Library. Two implementations +of that library are interoperable if one follows the de-facto ABI of the +other and if they are both built with the same compiler, or with compilers +that conform to the same ABI for C++ compiler and runtime support. + +When G++ and another C++ compiler conform to the same C++ ABI, but the +implementations of the Standard C++ Library that they normally use do not +follow the same ABI for the Standard C++ Library, object files built with +those compilers can be used in the same program only if they use the same +C++ library. This requires specifying the location of the C++ library +header files when invoking the compiler whose usual library is not being +used. The location of GCC's C++ header files depends on how the GCC +build was configured, but can be seen by using the G++ @option{-v} option. +With default configuration options for G++ 3.3 the compile line for a +different C++ compiler needs to include + +@smallexample + -I@var{gcc_install_directory}/include/c++/3.3 +@end smallexample + +Similarly, compiling code with G++ that must use a C++ library other +than the GNU C++ library requires specifying the location of the header +files for that other library. + +The most straightforward way to link a program to use a particular +C++ library is to use a C++ driver that specifies that C++ library by +default. The @command{g++} driver, for example, tells the linker where +to find GCC's C++ library (@file{libstdc++}) plus the other libraries +and startup files it needs, in the proper order. + +If a program must use a different C++ library and it's not possible +to do the final link using a C++ driver that uses that library by default, +it is necessary to tell @command{g++} the location and name of that +library. It might also be necessary to specify different startup files +and other runtime support libraries, and to suppress the use of GCC's +support libraries with one or more of the options @option{-nostdlib}, +@option{-nostartfiles}, and @option{-nodefaultlibs}. diff --git a/gcc/doc/configfiles.texi b/gcc/doc/configfiles.texi new file mode 100644 index 000000000..d122225f3 --- /dev/null +++ b/gcc/doc/configfiles.texi @@ -0,0 +1,64 @@ +@c Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998, +@c 1999, 2000, 2001, 2002, 2010 Free Software Foundation, Inc. +@c This is part of the GCC manual. +@c For copying conditions, see the file gcc.texi. + +@node Configuration Files +@subsubsection Files Created by @code{configure} + +Here we spell out what files will be set up by @file{configure} in the +@file{gcc} directory. Some other files are created as temporary files +in the configuration process, and are not used in the subsequent +build; these are not documented. + +@itemize @bullet +@item +@file{Makefile} is constructed from @file{Makefile.in}, together with +the host and target fragments (@pxref{Fragments, , Makefile +Fragments}) @file{t-@var{target}} and @file{x-@var{host}} from +@file{config}, if any, and language Makefile fragments +@file{@var{language}/Make-lang.in}. +@item +@file{auto-host.h} contains information about the host machine +determined by @file{configure}. If the host machine is different from +the build machine, then @file{auto-build.h} is also created, +containing such information about the build machine. +@item +@file{config.status} is a script that may be run to recreate the +current configuration. +@item +@file{configargs.h} is a header containing details of the arguments +passed to @file{configure} to configure GCC, and of the thread model +used. +@item +@file{cstamp-h} is used as a timestamp. +@item +If a language @file{config-lang.in} file (@pxref{Front End Config, , +The Front End @file{config-lang.in} File}) sets @code{outputs}, then +the files listed in @code{outputs} there are also generated. +@end itemize + +The following configuration headers are created from the Makefile, +using @file{mkconfig.sh}, rather than directly by @file{configure}. +@file{config.h}, @file{bconfig.h} and @file{tconfig.h} all contain the +@file{xm-@var{machine}.h} header, if any, appropriate to the host, +build and target machines respectively, the configuration headers for +the target, and some definitions; for the host and build machines, +these include the autoconfigured headers generated by +@file{configure}. The other configuration headers are determined by +@file{config.gcc}. They also contain the typedefs for @code{rtx}, +@code{rtvec} and @code{tree}. + +@itemize @bullet +@item +@file{config.h}, for use in programs that run on the host machine. +@item +@file{bconfig.h}, for use in programs that run on the build machine. +@item +@file{tconfig.h}, for use in programs and libraries for the target +machine. +@item +@file{tm_p.h}, which includes the header @file{@var{machine}-protos.h} +that contains prototypes for functions in the target @file{.c} file. +FIXME: why is such a separate header necessary? +@end itemize diff --git a/gcc/doc/configterms.texi b/gcc/doc/configterms.texi new file mode 100644 index 000000000..d24416992 --- /dev/null +++ b/gcc/doc/configterms.texi @@ -0,0 +1,61 @@ +@c Copyright (C) 2001, 2002, 2004, 2008 Free Software Foundation, Inc. +@c This is part of the GCC manual. +@c For copying conditions, see the file gcc.texi. + +@node Configure Terms +@section Configure Terms and History +@cindex configure terms +@cindex canadian + +The configure and build process has a long and colorful history, and can +be confusing to anyone who doesn't know why things are the way they are. +While there are other documents which describe the configuration process +in detail, here are a few things that everyone working on GCC should +know. + +There are three system names that the build knows about: the machine you +are building on (@dfn{build}), the machine that you are building for +(@dfn{host}), and the machine that GCC will produce code for +(@dfn{target}). When you configure GCC, you specify these with +@option{--build=}, @option{--host=}, and @option{--target=}. + +Specifying the host without specifying the build should be avoided, as +@command{configure} may (and once did) assume that the host you specify +is also the build, which may not be true. + +If build, host, and target are all the same, this is called a +@dfn{native}. If build and host are the same but target is different, +this is called a @dfn{cross}. If build, host, and target are all +different this is called a @dfn{canadian} (for obscure reasons dealing +with Canada's political party and the background of the person working +on the build at that time). If host and target are the same, but build +is different, you are using a cross-compiler to build a native for a +different system. Some people call this a @dfn{host-x-host}, +@dfn{crossed native}, or @dfn{cross-built native}. If build and target +are the same, but host is different, you are using a cross compiler to +build a cross compiler that produces code for the machine you're +building on. This is rare, so there is no common way of describing it. +There is a proposal to call this a @dfn{crossback}. + +If build and host are the same, the GCC you are building will also be +used to build the target libraries (like @code{libstdc++}). If build and host +are different, you must have already built and installed a cross +compiler that will be used to build the target libraries (if you +configured with @option{--target=foo-bar}, this compiler will be called +@command{foo-bar-gcc}). + +In the case of target libraries, the machine you're building for is the +machine you specified with @option{--target}. So, build is the machine +you're building on (no change there), host is the machine you're +building for (the target libraries are built for the target, so host is +the target you specified), and target doesn't apply (because you're not +building a compiler, you're building libraries). The configure/make +process will adjust these variables as needed. It also sets +@code{$with_cross_host} to the original @option{--host} value in case you +need it. + +The @code{libiberty} support library is built up to three times: once +for the host, once for the target (even if they are the same), and once +for the build if build and host are different. This allows it to be +used by all programs which are generated in the course of the build +process. diff --git a/gcc/doc/contrib.texi b/gcc/doc/contrib.texi new file mode 100644 index 000000000..e52dcf9be --- /dev/null +++ b/gcc/doc/contrib.texi @@ -0,0 +1,1636 @@ +@c Copyright (C) 1988,1989,1992,1993,1994,1995,1996,1997,1998,1999,2000, +@c 2001,2002,2003,2004,2005,2006,2007,2008,2009, 2010 +@c Free Software Foundation, Inc. +@c This is part of the GCC manual. +@c For copying conditions, see the file gcc.texi. + +@node Contributors +@unnumbered Contributors to GCC +@cindex contributors + +The GCC project would like to thank its many contributors. Without them the +project would not have been nearly as successful as it has been. Any omissions +in this list are accidental. Feel free to contact +@email{law@@redhat.com} or @email{gerald@@pfeifer.com} if you have been left +out or some of your contributions are not listed. Please keep this list in +alphabetical order. + +@itemize @bullet + +@item +Analog Devices helped implement the support for complex data types +and iterators. + +@item +John David Anglin for threading-related fixes and improvements to +libstdc++-v3, and the HP-UX port. + +@item +James van Artsdalen wrote the code that makes efficient use of +the Intel 80387 register stack. + +@item +Abramo and Roberto Bagnara for the SysV68 Motorola 3300 Delta Series +port. + +@item +Alasdair Baird for various bug fixes. + +@item +Giovanni Bajo for analyzing lots of complicated C++ problem reports. + +@item +Peter Barada for his work to improve code generation for new +ColdFire cores. + +@item +Gerald Baumgartner added the signature extension to the C++ front end. + +@item +Godmar Back for his Java improvements and encouragement. + +@item +Scott Bambrough for help porting the Java compiler. + +@item +Wolfgang Bangerth for processing tons of bug reports. + +@item +Jon Beniston for his Microsoft Windows port of Java and port to Lattice Mico32. + +@item +Daniel Berlin for better DWARF2 support, faster/better optimizations, +improved alias analysis, plus migrating GCC to Bugzilla. + +@item +Geoff Berry for his Java object serialization work and various patches. + +@item +Uros Bizjak for the implementation of x87 math built-in functions and +for various middle end and i386 back end improvements and bug fixes. + +@item +Eric Blake for helping to make GCJ and libgcj conform to the +specifications. + +@item +Janne Blomqvist for contributions to GNU Fortran. + +@item +Segher Boessenkool for various fixes. + +@item +Hans-J. Boehm for his @uref{http://www.hpl.hp.com/@/personal/@/Hans_Boehm/@/gc/,, +garbage collector}, IA-64 libffi port, and other Java work. + +@item +Neil Booth for work on cpplib, lang hooks, debug hooks and other +miscellaneous clean-ups. + +@item +Steven Bosscher for integrating the GNU Fortran front end into GCC and for +contributing to the tree-ssa branch. + +@item +Eric Botcazou for fixing middle- and backend bugs left and right. + +@item +Per Bothner for his direction via the steering committee and various +improvements to the infrastructure for supporting new languages. Chill +front end implementation. Initial implementations of +cpplib, fix-header, config.guess, libio, and past C++ library (libg++) +maintainer. Dreaming up, designing and implementing much of GCJ@. + +@item +Devon Bowen helped port GCC to the Tahoe. + +@item +Don Bowman for mips-vxworks contributions. + +@item +Dave Brolley for work on cpplib and Chill. + +@item +Paul Brook for work on the ARM architecture and maintaining GNU Fortran. + +@item +Robert Brown implemented the support for Encore 32000 systems. + +@item +Christian Bruel for improvements to local store elimination. + +@item +Herman A.J. ten Brugge for various fixes. + +@item +Joerg Brunsmann for Java compiler hacking and help with the GCJ FAQ@. + +@item +Joe Buck for his direction via the steering committee. + +@item +Craig Burley for leadership of the G77 Fortran effort. + +@item +Stephan Buys for contributing Doxygen notes for libstdc++. + +@item +Paolo Carlini for libstdc++ work: lots of efficiency improvements to +the C++ strings, streambufs and formatted I/O, hard detective work on +the frustrating localization issues, and keeping up with the problem reports. + +@item +John Carr for his alias work, SPARC hacking, infrastructure improvements, +previous contributions to the steering committee, loop optimizations, etc. + +@item +Stephane Carrez for 68HC11 and 68HC12 ports. + +@item +Steve Chamberlain for support for the Renesas SH and H8 processors +and the PicoJava processor, and for GCJ config fixes. + +@item +Glenn Chambers for help with the GCJ FAQ@. + +@item +John-Marc Chandonia for various libgcj patches. + +@item +Denis Chertykov for contributing and maintaining the AVR port, the first GCC port +for an 8-bit architecture. + +@item +Scott Christley for his Objective-C contributions. + +@item +Eric Christopher for his Java porting help and clean-ups. + +@item +Branko Cibej for more warning contributions. + +@item +The @uref{http://www.gnu.org/software/classpath/,,GNU Classpath project} +for all of their merged runtime code. + +@item +Nick Clifton for arm, mcore, fr30, v850, m32r, rx work, +@option{--help}, and other random hacking. + +@item +Michael Cook for libstdc++ cleanup patches to reduce warnings. + +@item +R. Kelley Cook for making GCC buildable from a read-only directory as +well as other miscellaneous build process and documentation clean-ups. + +@item +Ralf Corsepius for SH testing and minor bug fixing. + +@item +Stan Cox for care and feeding of the x86 port and lots of behind +the scenes hacking. + +@item +Alex Crain provided changes for the 3b1. + +@item +Ian Dall for major improvements to the NS32k port. + +@item +Paul Dale for his work to add uClinux platform support to the +m68k backend. + +@item +Dario Dariol contributed the four varieties of sample programs +that print a copy of their source. + +@item +Russell Davidson for fstream and stringstream fixes in libstdc++. + +@item +Bud Davis for work on the G77 and GNU Fortran compilers. + +@item +Mo DeJong for GCJ and libgcj bug fixes. + +@item +DJ Delorie for the DJGPP port, build and libiberty maintenance, +various bug fixes, and the M32C and MeP ports. + +@item +Arnaud Desitter for helping to debug GNU Fortran. + +@item +Gabriel Dos Reis for contributions to G++, contributions and +maintenance of GCC diagnostics infrastructure, libstdc++-v3, +including @code{valarray<>}, @code{complex<>}, maintaining the numerics library +(including that pesky @code{} :-) and keeping up-to-date anything +to do with numbers. + +@item +Ulrich Drepper for his work on glibc, testing of GCC using glibc, ISO C99 +support, CFG dumping support, etc., plus support of the C++ runtime +libraries including for all kinds of C interface issues, contributing and +maintaining @code{complex<>}, sanity checking and disbursement, configuration +architecture, libio maintenance, and early math work. + +@item +Zdenek Dvorak for a new loop unroller and various fixes. + +@item +Michael Eager for his work on the Xilinx MicroBlaze port. + +@item +Richard Earnshaw for his ongoing work with the ARM@. + +@item +David Edelsohn for his direction via the steering committee, ongoing work +with the RS6000/PowerPC port, help cleaning up Haifa loop changes, +doing the entire AIX port of libstdc++ with his bare hands, and for +ensuring GCC properly keeps working on AIX@. + +@item +Kevin Ediger for the floating point formatting of num_put::do_put in +libstdc++. + +@item +Phil Edwards for libstdc++ work including configuration hackery, +documentation maintainer, chief breaker of the web pages, the occasional +iostream bug fix, and work on shared library symbol versioning. + +@item +Paul Eggert for random hacking all over GCC@. + +@item +Mark Elbrecht for various DJGPP improvements, and for libstdc++ +configuration support for locales and fstream-related fixes. + +@item +Vadim Egorov for libstdc++ fixes in strings, streambufs, and iostreams. + +@item +Christian Ehrhardt for dealing with bug reports. + +@item +Ben Elliston for his work to move the Objective-C runtime into its +own subdirectory and for his work on autoconf. + +@item +Revital Eres for work on the PowerPC 750CL port. + +@item +Marc Espie for OpenBSD support. + +@item +Doug Evans for much of the global optimization framework, arc, m32r, +and SPARC work. + +@item +Christopher Faylor for his work on the Cygwin port and for caring and +feeding the gcc.gnu.org box and saving its users tons of spam. + +@item +Fred Fish for BeOS support and Ada fixes. + +@item +Ivan Fontes Garcia for the Portuguese translation of the GCJ FAQ@. + +@item +Peter Gerwinski for various bug fixes and the Pascal front end. + +@item +Kaveh R.@: Ghazi for his direction via the steering committee, amazing +work to make @samp{-W -Wall -W* -Werror} useful, and continuously +testing GCC on a plethora of platforms. Kaveh extends his gratitude to +the @uref{http://www.caip.rutgers.edu,,CAIP Center} at Rutgers +University for providing him with computing resources to work on Free +Software since the late 1980s. + +@item +John Gilmore for a donation to the FSF earmarked improving GNU Java. + +@item +Judy Goldberg for c++ contributions. + +@item +Torbjorn Granlund for various fixes and the c-torture testsuite, +multiply- and divide-by-constant optimization, improved long long +support, improved leaf function register allocation, and his direction +via the steering committee. + +@item +Anthony Green for his @option{-Os} contributions, the moxie port, and +Java front end work. + +@item +Stu Grossman for gdb hacking, allowing GCJ developers to debug Java code. + +@item +Michael K. Gschwind contributed the port to the PDP-11. + +@item +Richard Guenther for his ongoing middle-end contributions and bug fixes +and for release management. + +@item +Ron Guilmette implemented the @command{protoize} and @command{unprotoize} +tools, the support for Dwarf symbolic debugging information, and much of +the support for System V Release 4. He has also worked heavily on the +Intel 386 and 860 support. + +@item +Mostafa Hagog for Swing Modulo Scheduling (SMS) and post reload GCSE@. + +@item +Bruno Haible for improvements in the runtime overhead for EH, new +warnings and assorted bug fixes. + +@item +Andrew Haley for his amazing Java compiler and library efforts. + +@item +Chris Hanson assisted in making GCC work on HP-UX for the 9000 series 300. + +@item +Michael Hayes for various thankless work he's done trying to get +the c30/c40 ports functional. Lots of loop and unroll improvements and +fixes. + +@item +Dara Hazeghi for wading through myriads of target-specific bug reports. + +@item +Kate Hedstrom for staking the G77 folks with an initial testsuite. + +@item +Richard Henderson for his ongoing SPARC, alpha, ia32, and ia64 work, loop +opts, and generally fixing lots of old problems we've ignored for +years, flow rewrite and lots of further stuff, including reviewing +tons of patches. + +@item +Aldy Hernandez for working on the PowerPC port, SIMD support, and +various fixes. + +@item +Nobuyuki Hikichi of Software Research Associates, Tokyo, contributed +the support for the Sony NEWS machine. + +@item +Kazu Hirata for caring and feeding the Renesas H8/300 port and various fixes. + +@item +Katherine Holcomb for work on GNU Fortran. + +@item +Manfred Hollstein for his ongoing work to keep the m88k alive, lots +of testing and bug fixing, particularly of GCC configury code. + +@item +Steve Holmgren for MachTen patches. + +@item +Jan Hubicka for his x86 port improvements. + +@item +Falk Hueffner for working on C and optimization bug reports. + +@item +Bernardo Innocenti for his m68k work, including merging of +ColdFire improvements and uClinux support. + +@item +Christian Iseli for various bug fixes. + +@item +Kamil Iskra for general m68k hacking. + +@item +Lee Iverson for random fixes and MIPS testing. + +@item +Andreas Jaeger for testing and benchmarking of GCC and various bug fixes. + +@item +Jakub Jelinek for his SPARC work and sibling call optimizations as well +as lots of bug fixes and test cases, and for improving the Java build +system. + +@item +Janis Johnson for ia64 testing and fixes, her quality improvement +sidetracks, and web page maintenance. + +@item +Kean Johnston for SCO OpenServer support and various fixes. + +@item +Tim Josling for the sample language treelang based originally on Richard +Kenner's ``toy'' language. + +@item +Nicolai Josuttis for additional libstdc++ documentation. + +@item +Klaus Kaempf for his ongoing work to make alpha-vms a viable target. + +@item +Steven G. Kargl for work on GNU Fortran. + +@item +David Kashtan of SRI adapted GCC to VMS@. + +@item +Ryszard Kabatek for many, many libstdc++ bug fixes and optimizations of +strings, especially member functions, and for auto_ptr fixes. + +@item +Geoffrey Keating for his ongoing work to make the PPC work for GNU/Linux +and his automatic regression tester. + +@item +Brendan Kehoe for his ongoing work with G++ and for a lot of early work +in just about every part of libstdc++. + +@item +Oliver M. Kellogg of Deutsche Aerospace contributed the port to the +MIL-STD-1750A@. + +@item +Richard Kenner of the New York University Ultracomputer Research +Laboratory wrote the machine descriptions for the AMD 29000, the DEC +Alpha, the IBM RT PC, and the IBM RS/6000 as well as the support for +instruction attributes. He also made changes to better support RISC +processors including changes to common subexpression elimination, +strength reduction, function calling sequence handling, and condition +code support, in addition to generalizing the code for frame pointer +elimination and delay slot scheduling. Richard Kenner was also the +head maintainer of GCC for several years. + +@item +Mumit Khan for various contributions to the Cygwin and Mingw32 ports and +maintaining binary releases for Microsoft Windows hosts, and for massive libstdc++ +porting work to Cygwin/Mingw32. + +@item +Robin Kirkham for cpu32 support. + +@item +Mark Klein for PA improvements. + +@item +Thomas Koenig for various bug fixes. + +@item +Bruce Korb for the new and improved fixincludes code. + +@item +Benjamin Kosnik for his G++ work and for leading the libstdc++-v3 effort. + +@item +Charles LaBrec contributed the support for the Integrated Solutions +68020 system. + +@item +Asher Langton and Mike Kumbera for contributing Cray pointer support +to GNU Fortran, and for other GNU Fortran improvements. + +@item +Jeff Law for his direction via the steering committee, coordinating the +entire egcs project and GCC 2.95, rolling out snapshots and releases, +handling merges from GCC2, reviewing tons of patches that might have +fallen through the cracks else, and random but extensive hacking. + +@item +Marc Lehmann for his direction via the steering committee and helping +with analysis and improvements of x86 performance. + +@item +Victor Leikehman for work on GNU Fortran. + +@item +Ted Lemon wrote parts of the RTL reader and printer. + +@item +Kriang Lerdsuwanakij for C++ improvements including template as template +parameter support, and many C++ fixes. + +@item +Warren Levy for tremendous work on libgcj (Java Runtime Library) and +random work on the Java front end. + +@item +Alain Lichnewsky ported GCC to the MIPS CPU@. + +@item +Oskar Liljeblad for hacking on AWT and his many Java bug reports and +patches. + +@item +Robert Lipe for OpenServer support, new testsuites, testing, etc. + +@item +Chen Liqin for various S+core related fixes/improvement, and for +maintaining the S+core port. + +@item +Weiwen Liu for testing and various bug fixes. + +@item +Manuel L@'opez-Ib@'a@~nez for improving @option{-Wconversion} and +many other diagnostics fixes and improvements. + +@item +Dave Love for his ongoing work with the Fortran front end and +runtime libraries. + +@item +Martin von L@"owis for internal consistency checking infrastructure, +various C++ improvements including namespace support, and tons of +assistance with libstdc++/compiler merges. + +@item +H.J. Lu for his previous contributions to the steering committee, many x86 +bug reports, prototype patches, and keeping the GNU/Linux ports working. + +@item +Greg McGary for random fixes and (someday) bounded pointers. + +@item +Andrew MacLeod for his ongoing work in building a real EH system, +various code generation improvements, work on the global optimizer, etc. + +@item +Vladimir Makarov for hacking some ugly i960 problems, PowerPC hacking +improvements to compile-time performance, overall knowledge and +direction in the area of instruction scheduling, and design and +implementation of the automaton based instruction scheduler. + +@item +Bob Manson for his behind the scenes work on dejagnu. + +@item +Philip Martin for lots of libstdc++ string and vector iterator fixes and +improvements, and string clean up and testsuites. + +@item +All of the Mauve project +@uref{http://sourceware.org/cgi-bin/cvsweb.cgi/~checkout~/mauve/THANKS?rev=1.2&cvsroot=mauve&only_with_tag=HEAD,,contributors}, +for Java test code. + +@item +Bryce McKinlay for numerous GCJ and libgcj fixes and improvements. + +@item +Adam Megacz for his work on the Microsoft Windows port of GCJ@. + +@item +Michael Meissner for LRS framework, ia32, m32r, v850, m88k, MIPS, +powerpc, haifa, ECOFF debug support, and other assorted hacking. + +@item +Jason Merrill for his direction via the steering committee and leading +the G++ effort. + +@item +Martin Michlmayr for testing GCC on several architectures using the +entire Debian archive. + +@item +David Miller for his direction via the steering committee, lots of +SPARC work, improvements in jump.c and interfacing with the Linux kernel +developers. + +@item +Gary Miller ported GCC to Charles River Data Systems machines. + +@item +Alfred Minarik for libstdc++ string and ios bug fixes, and turning the +entire libstdc++ testsuite namespace-compatible. + +@item +Mark Mitchell for his direction via the steering committee, mountains of +C++ work, load/store hoisting out of loops, alias analysis improvements, +ISO C @code{restrict} support, and serving as release manager for GCC 3.x. + +@item +Alan Modra for various GNU/Linux bits and testing. + +@item +Toon Moene for his direction via the steering committee, Fortran +maintenance, and his ongoing work to make us make Fortran run fast. + +@item +Jason Molenda for major help in the care and feeding of all the services +on the gcc.gnu.org (formerly egcs.cygnus.com) machine---mail, web +services, ftp services, etc etc. Doing all this work on scrap paper and +the backs of envelopes would have been@dots{} difficult. + +@item +Catherine Moore for fixing various ugly problems we have sent her +way, including the haifa bug which was killing the Alpha & PowerPC +Linux kernels. + +@item +Mike Moreton for his various Java patches. + +@item +David Mosberger-Tang for various Alpha improvements, and for the initial +IA-64 port. + +@item +Stephen Moshier contributed the floating point emulator that assists in +cross-compilation and permits support for floating point numbers wider +than 64 bits and for ISO C99 support. + +@item +Bill Moyer for his behind the scenes work on various issues. + +@item +Philippe De Muyter for his work on the m68k port. + +@item +Joseph S. Myers for his work on the PDP-11 port, format checking and ISO +C99 support, and continuous emphasis on (and contributions to) documentation. + +@item +Nathan Myers for his work on libstdc++-v3: architecture and authorship +through the first three snapshots, including implementation of locale +infrastructure, string, shadow C headers, and the initial project +documentation (DESIGN, CHECKLIST, and so forth). Later, more work on +MT-safe string and shadow headers. + +@item +Felix Natter for documentation on porting libstdc++. + +@item +Nathanael Nerode for cleaning up the configuration/build process. + +@item +NeXT, Inc.@: donated the front end that supports the Objective-C +language. + +@item +Hans-Peter Nilsson for the CRIS and MMIX ports, improvements to the search +engine setup, various documentation fixes and other small fixes. + +@item +Geoff Noer for his work on getting cygwin native builds working. + +@item +Diego Novillo for his work on Tree SSA, OpenMP, SPEC performance +tracking web pages, GIMPLE tuples, and assorted fixes. + +@item +David O'Brien for the FreeBSD/alpha, FreeBSD/AMD x86-64, FreeBSD/ARM, +FreeBSD/PowerPC, and FreeBSD/SPARC64 ports and related infrastructure +improvements. + +@item +Alexandre Oliva for various build infrastructure improvements, scripts and +amazing testing work, including keeping libtool issues sane and happy. + +@item +Stefan Olsson for work on mt_alloc. + +@item +Melissa O'Neill for various NeXT fixes. + +@item +Rainer Orth for random MIPS work, including improvements to GCC's o32 +ABI support, improvements to dejagnu's MIPS support, Java configuration +clean-ups and porting work, and maintaining the IRIX, Solaris 2, and +Tru64 UNIX ports. + +@item +Hartmut Penner for work on the s390 port. + +@item +Paul Petersen wrote the machine description for the Alliant FX/8. + +@item +Alexandre Petit-Bianco for implementing much of the Java compiler and +continued Java maintainership. + +@item +Matthias Pfaller for major improvements to the NS32k port. + +@item +Gerald Pfeifer for his direction via the steering committee, pointing +out lots of problems we need to solve, maintenance of the web pages, and +taking care of documentation maintenance in general. + +@item +Andrew Pinski for processing bug reports by the dozen. + +@item +Ovidiu Predescu for his work on the Objective-C front end and runtime +libraries. + +@item +Jerry Quinn for major performance improvements in C++ formatted I/O@. + +@item +Ken Raeburn for various improvements to checker, MIPS ports and various +cleanups in the compiler. + +@item +Rolf W. Rasmussen for hacking on AWT@. + +@item +David Reese of Sun Microsystems contributed to the Solaris on PowerPC +port. + +@item +Volker Reichelt for keeping up with the problem reports. + +@item +Joern Rennecke for maintaining the sh port, loop, regmove & reload +hacking. + +@item +Loren J. Rittle for improvements to libstdc++-v3 including the FreeBSD +port, threading fixes, thread-related configury changes, critical +threading documentation, and solutions to really tricky I/O problems, +as well as keeping GCC properly working on FreeBSD and continuous testing. + +@item +Craig Rodrigues for processing tons of bug reports. + +@item +Ola R@"onnerup for work on mt_alloc. + +@item +Gavin Romig-Koch for lots of behind the scenes MIPS work. + +@item +David Ronis inspired and encouraged Craig to rewrite the G77 +documentation in texinfo format by contributing a first pass at a +translation of the old @file{g77-0.5.16/f/DOC} file. + +@item +Ken Rose for fixes to GCC's delay slot filling code. + +@item +Paul Rubin wrote most of the preprocessor. + +@item +P@'etur Run@'olfsson for major performance improvements in C++ formatted I/O and +large file support in C++ filebuf. + +@item +Chip Salzenberg for libstdc++ patches and improvements to locales, traits, +Makefiles, libio, libtool hackery, and ``long long'' support. + +@item +Juha Sarlin for improvements to the H8 code generator. + +@item +Greg Satz assisted in making GCC work on HP-UX for the 9000 series 300. + +@item +Roger Sayle for improvements to constant folding and GCC's RTL optimizers +as well as for fixing numerous bugs. + +@item +Bradley Schatz for his work on the GCJ FAQ@. + +@item +Peter Schauer wrote the code to allow debugging to work on the Alpha. + +@item +William Schelter did most of the work on the Intel 80386 support. + +@item +Tobias Schl@"uter for work on GNU Fortran. + +@item +Bernd Schmidt for various code generation improvements and major +work in the reload pass as well a serving as release manager for +GCC 2.95.3. + +@item +Peter Schmid for constant testing of libstdc++---especially application +testing, going above and beyond what was requested for the release +criteria---and libstdc++ header file tweaks. + +@item +Jason Schroeder for jcf-dump patches. + +@item +Andreas Schwab for his work on the m68k port. + +@item +Lars Segerlund for work on GNU Fortran. + +@item +Dodji Seketeli for numerous C++ bug fixes and debug info improvements. + +@item +Joel Sherrill for his direction via the steering committee, RTEMS +contributions and RTEMS testing. + +@item +Nathan Sidwell for many C++ fixes/improvements. + +@item +Jeffrey Siegal for helping RMS with the original design of GCC, some +code which handles the parse tree and RTL data structures, constant +folding and help with the original VAX & m68k ports. + +@item +Kenny Simpson for prompting libstdc++ fixes due to defect reports from +the LWG (thereby keeping GCC in line with updates from the ISO)@. + +@item +Franz Sirl for his ongoing work with making the PPC port stable +for GNU/Linux. + +@item +Andrey Slepuhin for assorted AIX hacking. + +@item +Trevor Smigiel for contributing the SPU port. + +@item +Christopher Smith did the port for Convex machines. + +@item +Danny Smith for his major efforts on the Mingw (and Cygwin) ports. + +@item +Randy Smith finished the Sun FPA support. + +@item +Scott Snyder for queue, iterator, istream, and string fixes and libstdc++ +testsuite entries. Also for providing the patch to G77 to add +rudimentary support for @code{INTEGER*1}, @code{INTEGER*2}, and +@code{LOGICAL*1}. + +@item +Brad Spencer for contributions to the GLIBCPP_FORCE_NEW technique. + +@item +Richard Stallman, for writing the original GCC and launching the GNU project. + +@item +Jan Stein of the Chalmers Computer Society provided support for +Genix, as well as part of the 32000 machine description. + +@item +Nigel Stephens for various mips16 related fixes/improvements. + +@item +Jonathan Stone wrote the machine description for the Pyramid computer. + +@item +Graham Stott for various infrastructure improvements. + +@item +John Stracke for his Java HTTP protocol fixes. + +@item +Mike Stump for his Elxsi port, G++ contributions over the years and more +recently his vxworks contributions + +@item +Jeff Sturm for Java porting help, bug fixes, and encouragement. + +@item +Shigeya Suzuki for this fixes for the bsdi platforms. + +@item +Ian Lance Taylor for the Go frontend, the initial mips16 and mips64 +support, general configury hacking, fixincludes, etc. + +@item +Holger Teutsch provided the support for the Clipper CPU@. + +@item +Gary Thomas for his ongoing work to make the PPC work for GNU/Linux. + +@item +Philipp Thomas for random bug fixes throughout the compiler + +@item +Jason Thorpe for thread support in libstdc++ on NetBSD@. + +@item +Kresten Krab Thorup wrote the run time support for the Objective-C +language and the fantastic Java bytecode interpreter. + +@item +Michael Tiemann for random bug fixes, the first instruction scheduler, +initial C++ support, function integration, NS32k, SPARC and M88k +machine description work, delay slot scheduling. + +@item +Andreas Tobler for his work porting libgcj to Darwin. + +@item +Teemu Torma for thread safe exception handling support. + +@item +Leonard Tower wrote parts of the parser, RTL generator, and RTL +definitions, and of the VAX machine description. + +@item +Daniel Towner and Hariharan Sandanagobalane contributed and +maintain the picoChip port. + +@item +Tom Tromey for internationalization support and for his many Java +contributions and libgcj maintainership. + +@item +Lassi Tuura for improvements to config.guess to determine HP processor +types. + +@item +Petter Urkedal for libstdc++ CXXFLAGS, math, and algorithms fixes. + +@item +Andy Vaught for the design and initial implementation of the GNU Fortran +front end. + +@item +Brent Verner for work with the libstdc++ cshadow files and their +associated configure steps. + +@item +Todd Vierling for contributions for NetBSD ports. + +@item +Jonathan Wakely for contributing libstdc++ Doxygen notes and XHTML +guidance. + +@item +Dean Wakerley for converting the install documentation from HTML to texinfo +in time for GCC 3.0. + +@item +Krister Walfridsson for random bug fixes. + +@item +Feng Wang for contributions to GNU Fortran. + +@item +Stephen M. Webb for time and effort on making libstdc++ shadow files +work with the tricky Solaris 8+ headers, and for pushing the build-time +header tree. + +@item +John Wehle for various improvements for the x86 code generator, +related infrastructure improvements to help x86 code generation, +value range propagation and other work, WE32k port. + +@item +Ulrich Weigand for work on the s390 port. + +@item +Zack Weinberg for major work on cpplib and various other bug fixes. + +@item +Matt Welsh for help with Linux Threads support in GCJ@. + +@item +Urban Widmark for help fixing java.io. + +@item +Mark Wielaard for new Java library code and his work integrating with +Classpath. + +@item +Dale Wiles helped port GCC to the Tahoe. + +@item +Bob Wilson from Tensilica, Inc.@: for the Xtensa port. + +@item +Jim Wilson for his direction via the steering committee, tackling hard +problems in various places that nobody else wanted to work on, strength +reduction and other loop optimizations. + +@item +Paul Woegerer and Tal Agmon for the CRX port. + +@item +Carlo Wood for various fixes. + +@item +Tom Wood for work on the m88k port. + +@item +Canqun Yang for work on GNU Fortran. + +@item +Masanobu Yuhara of Fujitsu Laboratories implemented the machine +description for the Tron architecture (specifically, the Gmicro). + +@item +Kevin Zachmann helped port GCC to the Tahoe. + +@item +Ayal Zaks for Swing Modulo Scheduling (SMS). + +@item +Xiaoqiang Zhang for work on GNU Fortran. + +@item +Gilles Zunino for help porting Java to Irix. + +@end itemize + +The following people are recognized for their contributions to GNAT, +the Ada front end of GCC: +@itemize @bullet +@item +Bernard Banner + +@item +Romain Berrendonner + +@item +Geert Bosch + +@item +Emmanuel Briot + +@item +Joel Brobecker + +@item +Ben Brosgol + +@item +Vincent Celier + +@item +Arnaud Charlet + +@item +Chien Chieng + +@item +Cyrille Comar + +@item +Cyrille Crozes + +@item +Robert Dewar + +@item +Gary Dismukes + +@item +Robert Duff + +@item +Ed Falis + +@item +Ramon Fernandez + +@item +Sam Figueroa + +@item +Vasiliy Fofanov + +@item +Michael Friess + +@item +Franco Gasperoni + +@item +Ted Giering + +@item +Matthew Gingell + +@item +Laurent Guerby + +@item +Jerome Guitton + +@item +Olivier Hainque + +@item +Jerome Hugues + +@item +Hristian Kirtchev + +@item +Jerome Lambourg + +@item +Bruno Leclerc + +@item +Albert Lee + +@item +Sean McNeil + +@item +Javier Miranda + +@item +Laurent Nana + +@item +Pascal Obry + +@item +Dong-Ik Oh + +@item +Laurent Pautet + +@item +Brett Porter + +@item +Thomas Quinot + +@item +Nicolas Roche + +@item +Pat Rogers + +@item +Jose Ruiz + +@item +Douglas Rupp + +@item +Sergey Rybin + +@item +Gail Schenker + +@item +Ed Schonberg + +@item +Nicolas Setton + +@item +Samuel Tardieu + +@end itemize + + +The following people are recognized for their contributions of new +features, bug reports, testing and integration of classpath/libgcj for +GCC version 4.1: +@itemize @bullet +@item +Lillian Angel for @code{JTree} implementation and lots Free Swing +additions and bug fixes. + +@item +Wolfgang Baer for @code{GapContent} bug fixes. + +@item +Anthony Balkissoon for @code{JList}, Free Swing 1.5 updates and mouse event +fixes, lots of Free Swing work including @code{JTable} editing. + +@item +Stuart Ballard for RMI constant fixes. + +@item +Goffredo Baroncelli for @code{HTTPURLConnection} fixes. + +@item +Gary Benson for @code{MessageFormat} fixes. + +@item +Daniel Bonniot for @code{Serialization} fixes. + +@item +Chris Burdess for lots of gnu.xml and http protocol fixes, @code{StAX} +and @code{DOM xml:id} support. + +@item +Ka-Hing Cheung for @code{TreePath} and @code{TreeSelection} fixes. + +@item +Archie Cobbs for build fixes, VM interface updates, +@code{URLClassLoader} updates. + +@item +Kelley Cook for build fixes. + +@item +Martin Cordova for Suggestions for better @code{SocketTimeoutException}. + +@item +David Daney for @code{BitSet} bug fixes, @code{HttpURLConnection} +rewrite and improvements. + +@item +Thomas Fitzsimmons for lots of upgrades to the gtk+ AWT and Cairo 2D +support. Lots of imageio framework additions, lots of AWT and Free +Swing bug fixes. + +@item +Jeroen Frijters for @code{ClassLoader} and nio cleanups, serialization fixes, +better @code{Proxy} support, bug fixes and IKVM integration. + +@item +Santiago Gala for @code{AccessControlContext} fixes. + +@item +Nicolas Geoffray for @code{VMClassLoader} and @code{AccessController} +improvements. + +@item +David Gilbert for @code{basic} and @code{metal} icon and plaf support +and lots of documenting, Lots of Free Swing and metal theme +additions. @code{MetalIconFactory} implementation. + +@item +Anthony Green for @code{MIDI} framework, @code{ALSA} and @code{DSSI} +providers. + +@item +Andrew Haley for @code{Serialization} and @code{URLClassLoader} fixes, +gcj build speedups. + +@item +Kim Ho for @code{JFileChooser} implementation. + +@item +Andrew John Hughes for @code{Locale} and net fixes, URI RFC2986 +updates, @code{Serialization} fixes, @code{Properties} XML support and +generic branch work, VMIntegration guide update. + +@item +Bastiaan Huisman for @code{TimeZone} bug fixing. + +@item +Andreas Jaeger for mprec updates. + +@item +Paul Jenner for better @option{-Werror} support. + +@item +Ito Kazumitsu for @code{NetworkInterface} implementation and updates. + +@item +Roman Kennke for @code{BoxLayout}, @code{GrayFilter} and +@code{SplitPane}, plus bug fixes all over. Lots of Free Swing work +including styled text. + +@item +Simon Kitching for @code{String} cleanups and optimization suggestions. + +@item +Michael Koch for configuration fixes, @code{Locale} updates, bug and +build fixes. + +@item +Guilhem Lavaux for configuration, thread and channel fixes and Kaffe +integration. JCL native @code{Pointer} updates. Logger bug fixes. + +@item +David Lichteblau for JCL support library global/local reference +cleanups. + +@item +Aaron Luchko for JDWP updates and documentation fixes. + +@item +Ziga Mahkovec for @code{Graphics2D} upgraded to Cairo 0.5 and new regex +features. + +@item +Sven de Marothy for BMP imageio support, CSS and @code{TextLayout} +fixes. @code{GtkImage} rewrite, 2D, awt, free swing and date/time fixes and +implementing the Qt4 peers. + +@item +Casey Marshall for crypto algorithm fixes, @code{FileChannel} lock, +@code{SystemLogger} and @code{FileHandler} rotate implementations, NIO +@code{FileChannel.map} support, security and policy updates. + +@item +Bryce McKinlay for RMI work. + +@item +Audrius Meskauskas for lots of Free Corba, RMI and HTML work plus +testing and documenting. + +@item +Kalle Olavi Niemitalo for build fixes. + +@item +Rainer Orth for build fixes. + +@item +Andrew Overholt for @code{File} locking fixes. + +@item +Ingo Proetel for @code{Image}, @code{Logger} and @code{URLClassLoader} +updates. + +@item +Olga Rodimina for @code{MenuSelectionManager} implementation. + +@item +Jan Roehrich for @code{BasicTreeUI} and @code{JTree} fixes. + +@item +Julian Scheid for documentation updates and gjdoc support. + +@item +Christian Schlichtherle for zip fixes and cleanups. + +@item +Robert Schuster for documentation updates and beans fixes, +@code{TreeNode} enumerations and @code{ActionCommand} and various +fixes, XML and URL, AWT and Free Swing bug fixes. + +@item +Keith Seitz for lots of JDWP work. + +@item +Christian Thalinger for 64-bit cleanups, Configuration and VM +interface fixes and @code{CACAO} integration, @code{fdlibm} updates. + +@item +Gael Thomas for @code{VMClassLoader} boot packages support suggestions. + +@item +Andreas Tobler for Darwin and Solaris testing and fixing, @code{Qt4} +support for Darwin/OS X, @code{Graphics2D} support, @code{gtk+} +updates. + +@item +Dalibor Topic for better @code{DEBUG} support, build cleanups and +Kaffe integration. @code{Qt4} build infrastructure, @code{SHA1PRNG} +and @code{GdkPixbugDecoder} updates. + +@item +Tom Tromey for Eclipse integration, generics work, lots of bug fixes +and gcj integration including coordinating The Big Merge. + +@item +Mark Wielaard for bug fixes, packaging and release management, +@code{Clipboard} implementation, system call interrupts and network +timeouts and @code{GdkPixpufDecoder} fixes. + +@end itemize + + +In addition to the above, all of which also contributed time and energy in +testing GCC, we would like to thank the following for their contributions +to testing: + +@itemize @bullet +@item +Michael Abd-El-Malek + +@item +Thomas Arend + +@item +Bonzo Armstrong + +@item +Steven Ashe + +@item +Chris Baldwin + +@item +David Billinghurst + +@item +Jim Blandy + +@item +Stephane Bortzmeyer + +@item +Horst von Brand + +@item +Frank Braun + +@item +Rodney Brown + +@item +Sidney Cadot + +@item +Bradford Castalia + +@item +Robert Clark + +@item +Jonathan Corbet + +@item +Ralph Doncaster + +@item +Richard Emberson + +@item +Levente Farkas + +@item +Graham Fawcett + +@item +Mark Fernyhough + +@item +Robert A. French + +@item +J@"orgen Freyh + +@item +Mark K. Gardner + +@item +Charles-Antoine Gauthier + +@item +Yung Shing Gene + +@item +David Gilbert + +@item +Simon Gornall + +@item +Fred Gray + +@item +John Griffin + +@item +Patrik Hagglund + +@item +Phil Hargett + +@item +Amancio Hasty + +@item +Takafumi Hayashi + +@item +Bryan W. Headley + +@item +Kevin B. Hendricks + +@item +Joep Jansen + +@item +Christian Joensson + +@item +Michel Kern + +@item +David Kidd + +@item +Tobias Kuipers + +@item +Anand Krishnaswamy + +@item +A. O. V. Le Blanc + +@item +llewelly + +@item +Damon Love + +@item +Brad Lucier + +@item +Matthias Klose + +@item +Martin Knoblauch + +@item +Rick Lutowski + +@item +Jesse Macnish + +@item +Stefan Morrell + +@item +Anon A. Mous + +@item +Matthias Mueller + +@item +Pekka Nikander + +@item +Rick Niles + +@item +Jon Olson + +@item +Magnus Persson + +@item +Chris Pollard + +@item +Richard Polton + +@item +Derk Reefman + +@item +David Rees + +@item +Paul Reilly + +@item +Tom Reilly + +@item +Torsten Rueger + +@item +Danny Sadinoff + +@item +Marc Schifer + +@item +Erik Schnetter + +@item +Wayne K. Schroll + +@item +David Schuler + +@item +Vin Shelton + +@item +Tim Souder + +@item +Adam Sulmicki + +@item +Bill Thorson + +@item +George Talbot + +@item +Pedro A. M. Vazquez + +@item +Gregory Warnes + +@item +Ian Watson + +@item +David E. Young + +@item +And many others +@end itemize + +And finally we'd like to thank everyone who uses the compiler, provides +feedback and generally reminds us why we're doing this work in the first +place. diff --git a/gcc/doc/contribute.texi b/gcc/doc/contribute.texi new file mode 100644 index 000000000..55049f1b7 --- /dev/null +++ b/gcc/doc/contribute.texi @@ -0,0 +1,25 @@ +@c Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998, +@c 1999, 2000, 2001, 2004, 2006 Free Software Foundation, Inc. +@c This is part of the GCC manual. +@c For copying conditions, see the file gcc.texi. + +@node Contributing +@chapter Contributing to GCC Development + +If you would like to help pretest GCC releases to assure they work well, +current development sources are available by SVN (see +@uref{http://gcc.gnu.org/svn.html}). Source and binary snapshots are +also available for FTP; see @uref{http://gcc.gnu.org/snapshots.html}. + +If you would like to work on improvements to GCC, please read the +advice at these URLs: + +@smallexample +@uref{http://gcc.gnu.org/contribute.html} +@uref{http://gcc.gnu.org/contributewhy.html} +@end smallexample + +@noindent +for information on how to make useful contributions and avoid +duplication of effort. Suggested projects are listed at +@uref{http://gcc.gnu.org/projects/}. diff --git a/gcc/doc/cpp.1 b/gcc/doc/cpp.1 new file mode 100644 index 000000000..2f4065f9b --- /dev/null +++ b/gcc/doc/cpp.1 @@ -0,0 +1,992 @@ +.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is turned on, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.ie \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. nr % 0 +. rr F +.\} +.el \{\ +. de IX +.. +.\} +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "CPP 1" +.TH CPP 1 "2013-04-12" "gcc-4.6.4" "GNU" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +cpp \- The C Preprocessor +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +cpp [\fB\-D\fR\fImacro\fR[=\fIdefn\fR]...] [\fB\-U\fR\fImacro\fR] + [\fB\-I\fR\fIdir\fR...] [\fB\-iquote\fR\fIdir\fR...] + [\fB\-W\fR\fIwarn\fR...] + [\fB\-M\fR|\fB\-MM\fR] [\fB\-MG\fR] [\fB\-MF\fR \fIfilename\fR] + [\fB\-MP\fR] [\fB\-MQ\fR \fItarget\fR...] + [\fB\-MT\fR \fItarget\fR...] + [\fB\-P\fR] [\fB\-fno\-working\-directory\fR] + [\fB\-x\fR \fIlanguage\fR] [\fB\-std=\fR\fIstandard\fR] + \fIinfile\fR \fIoutfile\fR +.PP +Only the most useful options are listed here; see below for the remainder. +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +The C preprocessor, often known as \fIcpp\fR, is a \fImacro processor\fR +that is used automatically by the C compiler to transform your program +before compilation. It is called a macro processor because it allows +you to define \fImacros\fR, which are brief abbreviations for longer +constructs. +.PP +The C preprocessor is intended to be used only with C, \*(C+, and +Objective-C source code. In the past, it has been abused as a general +text processor. It will choke on input which does not obey C's lexical +rules. For example, apostrophes will be interpreted as the beginning of +character constants, and cause errors. Also, you cannot rely on it +preserving characteristics of the input which are not significant to +C\-family languages. If a Makefile is preprocessed, all the hard tabs +will be removed, and the Makefile will not work. +.PP +Having said that, you can often get away with using cpp on things which +are not C. Other Algol-ish programming languages are often safe +(Pascal, Ada, etc.) So is assembly, with caution. \fB\-traditional\-cpp\fR +mode preserves more white space, and is otherwise more permissive. Many +of the problems can be avoided by writing C or \*(C+ style comments +instead of native language comments, and keeping macros simple. +.PP +Wherever possible, you should use a preprocessor geared to the language +you are writing in. Modern versions of the \s-1GNU\s0 assembler have macro +facilities. Most high level programming languages have their own +conditional compilation and inclusion mechanism. If all else fails, +try a true general text processor, such as \s-1GNU\s0 M4. +.PP +C preprocessors vary in some details. This manual discusses the \s-1GNU\s0 C +preprocessor, which provides a small superset of the features of \s-1ISO\s0 +Standard C. In its default mode, the \s-1GNU\s0 C preprocessor does not do a +few things required by the standard. These are features which are +rarely, if ever, used, and may cause surprising changes to the meaning +of a program which does not expect them. To get strict \s-1ISO\s0 Standard C, +you should use the \fB\-std=c90\fR, \fB\-std=c99\fR or +\&\fB\-std=c1x\fR options, depending +on which version of the standard you want. To get all the mandatory +diagnostics, you must also use \fB\-pedantic\fR. +.PP +This manual describes the behavior of the \s-1ISO\s0 preprocessor. To +minimize gratuitous differences, where the \s-1ISO\s0 preprocessor's +behavior does not conflict with traditional semantics, the +traditional preprocessor should behave the same way. The various +differences that do exist are detailed in the section \fBTraditional +Mode\fR. +.PP +For clarity, unless noted otherwise, references to \fB\s-1CPP\s0\fR in this +manual refer to \s-1GNU\s0 \s-1CPP\s0. +.SH "OPTIONS" +.IX Header "OPTIONS" +The C preprocessor expects two file names as arguments, \fIinfile\fR and +\&\fIoutfile\fR. The preprocessor reads \fIinfile\fR together with any +other files it specifies with \fB#include\fR. All the output generated +by the combined input files is written in \fIoutfile\fR. +.PP +Either \fIinfile\fR or \fIoutfile\fR may be \fB\-\fR, which as +\&\fIinfile\fR means to read from standard input and as \fIoutfile\fR +means to write to standard output. Also, if either file is omitted, it +means the same as if \fB\-\fR had been specified for that file. +.PP +Unless otherwise noted, or the option ends in \fB=\fR, all options +which take an argument may have that argument appear either immediately +after the option, or with a space between option and argument: +\&\fB\-Ifoo\fR and \fB\-I foo\fR have the same effect. +.PP +Many options have multi-letter names; therefore multiple single-letter +options may \fInot\fR be grouped: \fB\-dM\fR is very different from +\&\fB\-d\ \-M\fR. +.IP "\fB\-D\fR \fIname\fR" 4 +.IX Item "-D name" +Predefine \fIname\fR as a macro, with definition \f(CW1\fR. +.IP "\fB\-D\fR \fIname\fR\fB=\fR\fIdefinition\fR" 4 +.IX Item "-D name=definition" +The contents of \fIdefinition\fR are tokenized and processed as if +they appeared during translation phase three in a \fB#define\fR +directive. In particular, the definition will be truncated by +embedded newline characters. +.Sp +If you are invoking the preprocessor from a shell or shell-like +program you may need to use the shell's quoting syntax to protect +characters such as spaces that have a meaning in the shell syntax. +.Sp +If you wish to define a function-like macro on the command line, write +its argument list with surrounding parentheses before the equals sign +(if any). Parentheses are meaningful to most shells, so you will need +to quote the option. With \fBsh\fR and \fBcsh\fR, +\&\fB\-D'\fR\fIname\fR\fB(\fR\fIargs...\fR\fB)=\fR\fIdefinition\fR\fB'\fR works. +.Sp +\&\fB\-D\fR and \fB\-U\fR options are processed in the order they +are given on the command line. All \fB\-imacros\fR \fIfile\fR and +\&\fB\-include\fR \fIfile\fR options are processed after all +\&\fB\-D\fR and \fB\-U\fR options. +.IP "\fB\-U\fR \fIname\fR" 4 +.IX Item "-U name" +Cancel any previous definition of \fIname\fR, either built in or +provided with a \fB\-D\fR option. +.IP "\fB\-undef\fR" 4 +.IX Item "-undef" +Do not predefine any system-specific or GCC-specific macros. The +standard predefined macros remain defined. +.IP "\fB\-I\fR \fIdir\fR" 4 +.IX Item "-I dir" +Add the directory \fIdir\fR to the list of directories to be searched +for header files. +.Sp +Directories named by \fB\-I\fR are searched before the standard +system include directories. If the directory \fIdir\fR is a standard +system include directory, the option is ignored to ensure that the +default search order for system directories and the special treatment +of system headers are not defeated +\&. +If \fIdir\fR begins with \f(CW\*(C`=\*(C'\fR, then the \f(CW\*(C`=\*(C'\fR will be replaced +by the sysroot prefix; see \fB\-\-sysroot\fR and \fB\-isysroot\fR. +.IP "\fB\-o\fR \fIfile\fR" 4 +.IX Item "-o file" +Write output to \fIfile\fR. This is the same as specifying \fIfile\fR +as the second non-option argument to \fBcpp\fR. \fBgcc\fR has a +different interpretation of a second non-option argument, so you must +use \fB\-o\fR to specify the output file. +.IP "\fB\-Wall\fR" 4 +.IX Item "-Wall" +Turns on all optional warnings which are desirable for normal code. +At present this is \fB\-Wcomment\fR, \fB\-Wtrigraphs\fR, +\&\fB\-Wmultichar\fR and a warning about integer promotion causing a +change of sign in \f(CW\*(C`#if\*(C'\fR expressions. Note that many of the +preprocessor's warnings are on by default and have no options to +control them. +.IP "\fB\-Wcomment\fR" 4 +.IX Item "-Wcomment" +.PD 0 +.IP "\fB\-Wcomments\fR" 4 +.IX Item "-Wcomments" +.PD +Warn whenever a comment-start sequence \fB/*\fR appears in a \fB/*\fR +comment, or whenever a backslash-newline appears in a \fB//\fR comment. +(Both forms have the same effect.) +.IP "\fB\-Wtrigraphs\fR" 4 +.IX Item "-Wtrigraphs" +Most trigraphs in comments cannot affect the meaning of the program. +However, a trigraph that would form an escaped newline (\fB??/\fR at +the end of a line) can, by changing where the comment begins or ends. +Therefore, only trigraphs that would form escaped newlines produce +warnings inside a comment. +.Sp +This option is implied by \fB\-Wall\fR. If \fB\-Wall\fR is not +given, this option is still enabled unless trigraphs are enabled. To +get trigraph conversion without warnings, but get the other +\&\fB\-Wall\fR warnings, use \fB\-trigraphs \-Wall \-Wno\-trigraphs\fR. +.IP "\fB\-Wtraditional\fR" 4 +.IX Item "-Wtraditional" +Warn about certain constructs that behave differently in traditional and +\&\s-1ISO\s0 C. Also warn about \s-1ISO\s0 C constructs that have no traditional C +equivalent, and problematic constructs which should be avoided. +.IP "\fB\-Wundef\fR" 4 +.IX Item "-Wundef" +Warn whenever an identifier which is not a macro is encountered in an +\&\fB#if\fR directive, outside of \fBdefined\fR. Such identifiers are +replaced with zero. +.IP "\fB\-Wunused\-macros\fR" 4 +.IX Item "-Wunused-macros" +Warn about macros defined in the main file that are unused. A macro +is \fIused\fR if it is expanded or tested for existence at least once. +The preprocessor will also warn if the macro has not been used at the +time it is redefined or undefined. +.Sp +Built-in macros, macros defined on the command line, and macros +defined in include files are not warned about. +.Sp +\&\fINote:\fR If a macro is actually used, but only used in skipped +conditional blocks, then \s-1CPP\s0 will report it as unused. To avoid the +warning in such a case, you might improve the scope of the macro's +definition by, for example, moving it into the first skipped block. +Alternatively, you could provide a dummy use with something like: +.Sp +.Vb 2 +\& #if defined the_macro_causing_the_warning +\& #endif +.Ve +.IP "\fB\-Wendif\-labels\fR" 4 +.IX Item "-Wendif-labels" +Warn whenever an \fB#else\fR or an \fB#endif\fR are followed by text. +This usually happens in code of the form +.Sp +.Vb 5 +\& #if FOO +\& ... +\& #else FOO +\& ... +\& #endif FOO +.Ve +.Sp +The second and third \f(CW\*(C`FOO\*(C'\fR should be in comments, but often are not +in older programs. This warning is on by default. +.IP "\fB\-Werror\fR" 4 +.IX Item "-Werror" +Make all warnings into hard errors. Source code which triggers warnings +will be rejected. +.IP "\fB\-Wsystem\-headers\fR" 4 +.IX Item "-Wsystem-headers" +Issue warnings for code in system headers. These are normally unhelpful +in finding bugs in your own code, therefore suppressed. If you are +responsible for the system library, you may want to see them. +.IP "\fB\-w\fR" 4 +.IX Item "-w" +Suppress all warnings, including those which \s-1GNU\s0 \s-1CPP\s0 issues by default. +.IP "\fB\-pedantic\fR" 4 +.IX Item "-pedantic" +Issue all the mandatory diagnostics listed in the C standard. Some of +them are left out by default, since they trigger frequently on harmless +code. +.IP "\fB\-pedantic\-errors\fR" 4 +.IX Item "-pedantic-errors" +Issue all the mandatory diagnostics, and make all mandatory diagnostics +into errors. This includes mandatory diagnostics that \s-1GCC\s0 issues +without \fB\-pedantic\fR but treats as warnings. +.IP "\fB\-M\fR" 4 +.IX Item "-M" +Instead of outputting the result of preprocessing, output a rule +suitable for \fBmake\fR describing the dependencies of the main +source file. The preprocessor outputs one \fBmake\fR rule containing +the object file name for that source file, a colon, and the names of all +the included files, including those coming from \fB\-include\fR or +\&\fB\-imacros\fR command line options. +.Sp +Unless specified explicitly (with \fB\-MT\fR or \fB\-MQ\fR), the +object file name consists of the name of the source file with any +suffix replaced with object file suffix and with any leading directory +parts removed. If there are many included files then the rule is +split into several lines using \fB\e\fR\-newline. The rule has no +commands. +.Sp +This option does not suppress the preprocessor's debug output, such as +\&\fB\-dM\fR. To avoid mixing such debug output with the dependency +rules you should explicitly specify the dependency output file with +\&\fB\-MF\fR, or use an environment variable like +\&\fB\s-1DEPENDENCIES_OUTPUT\s0\fR. Debug output +will still be sent to the regular output stream as normal. +.Sp +Passing \fB\-M\fR to the driver implies \fB\-E\fR, and suppresses +warnings with an implicit \fB\-w\fR. +.IP "\fB\-MM\fR" 4 +.IX Item "-MM" +Like \fB\-M\fR but do not mention header files that are found in +system header directories, nor header files that are included, +directly or indirectly, from such a header. +.Sp +This implies that the choice of angle brackets or double quotes in an +\&\fB#include\fR directive does not in itself determine whether that +header will appear in \fB\-MM\fR dependency output. This is a +slight change in semantics from \s-1GCC\s0 versions 3.0 and earlier. +.IP "\fB\-MF\fR \fIfile\fR" 4 +.IX Item "-MF file" +When used with \fB\-M\fR or \fB\-MM\fR, specifies a +file to write the dependencies to. If no \fB\-MF\fR switch is given +the preprocessor sends the rules to the same place it would have sent +preprocessed output. +.Sp +When used with the driver options \fB\-MD\fR or \fB\-MMD\fR, +\&\fB\-MF\fR overrides the default dependency output file. +.IP "\fB\-MG\fR" 4 +.IX Item "-MG" +In conjunction with an option such as \fB\-M\fR requesting +dependency generation, \fB\-MG\fR assumes missing header files are +generated files and adds them to the dependency list without raising +an error. The dependency filename is taken directly from the +\&\f(CW\*(C`#include\*(C'\fR directive without prepending any path. \fB\-MG\fR +also suppresses preprocessed output, as a missing header file renders +this useless. +.Sp +This feature is used in automatic updating of makefiles. +.IP "\fB\-MP\fR" 4 +.IX Item "-MP" +This option instructs \s-1CPP\s0 to add a phony target for each dependency +other than the main file, causing each to depend on nothing. These +dummy rules work around errors \fBmake\fR gives if you remove header +files without updating the \fIMakefile\fR to match. +.Sp +This is typical output: +.Sp +.Vb 1 +\& test.o: test.c test.h +\& +\& test.h: +.Ve +.IP "\fB\-MT\fR \fItarget\fR" 4 +.IX Item "-MT target" +Change the target of the rule emitted by dependency generation. By +default \s-1CPP\s0 takes the name of the main input file, deletes any +directory components and any file suffix such as \fB.c\fR, and +appends the platform's usual object suffix. The result is the target. +.Sp +An \fB\-MT\fR option will set the target to be exactly the string you +specify. If you want multiple targets, you can specify them as a single +argument to \fB\-MT\fR, or use multiple \fB\-MT\fR options. +.Sp +For example, \fB\-MT\ '$(objpfx)foo.o'\fR might give +.Sp +.Vb 1 +\& $(objpfx)foo.o: foo.c +.Ve +.IP "\fB\-MQ\fR \fItarget\fR" 4 +.IX Item "-MQ target" +Same as \fB\-MT\fR, but it quotes any characters which are special to +Make. \fB\-MQ\ '$(objpfx)foo.o'\fR gives +.Sp +.Vb 1 +\& $$(objpfx)foo.o: foo.c +.Ve +.Sp +The default target is automatically quoted, as if it were given with +\&\fB\-MQ\fR. +.IP "\fB\-MD\fR" 4 +.IX Item "-MD" +\&\fB\-MD\fR is equivalent to \fB\-M \-MF\fR \fIfile\fR, except that +\&\fB\-E\fR is not implied. The driver determines \fIfile\fR based on +whether an \fB\-o\fR option is given. If it is, the driver uses its +argument but with a suffix of \fI.d\fR, otherwise it takes the name +of the input file, removes any directory components and suffix, and +applies a \fI.d\fR suffix. +.Sp +If \fB\-MD\fR is used in conjunction with \fB\-E\fR, any +\&\fB\-o\fR switch is understood to specify the dependency output file, but if used without \fB\-E\fR, each \fB\-o\fR +is understood to specify a target object file. +.Sp +Since \fB\-E\fR is not implied, \fB\-MD\fR can be used to generate +a dependency output file as a side-effect of the compilation process. +.IP "\fB\-MMD\fR" 4 +.IX Item "-MMD" +Like \fB\-MD\fR except mention only user header files, not system +header files. +.IP "\fB\-x c\fR" 4 +.IX Item "-x c" +.PD 0 +.IP "\fB\-x c++\fR" 4 +.IX Item "-x c++" +.IP "\fB\-x objective-c\fR" 4 +.IX Item "-x objective-c" +.IP "\fB\-x assembler-with-cpp\fR" 4 +.IX Item "-x assembler-with-cpp" +.PD +Specify the source language: C, \*(C+, Objective-C, or assembly. This has +nothing to do with standards conformance or extensions; it merely +selects which base syntax to expect. If you give none of these options, +cpp will deduce the language from the extension of the source file: +\&\fB.c\fR, \fB.cc\fR, \fB.m\fR, or \fB.S\fR. Some other common +extensions for \*(C+ and assembly are also recognized. If cpp does not +recognize the extension, it will treat the file as C; this is the most +generic mode. +.Sp +\&\fINote:\fR Previous versions of cpp accepted a \fB\-lang\fR option +which selected both the language and the standards conformance level. +This option has been removed, because it conflicts with the \fB\-l\fR +option. +.IP "\fB\-std=\fR\fIstandard\fR" 4 +.IX Item "-std=standard" +.PD 0 +.IP "\fB\-ansi\fR" 4 +.IX Item "-ansi" +.PD +Specify the standard to which the code should conform. Currently \s-1CPP\s0 +knows about C and \*(C+ standards; others may be added in the future. +.Sp +\&\fIstandard\fR +may be one of: +.RS 4 +.ie n .IP """c90""" 4 +.el .IP "\f(CWc90\fR" 4 +.IX Item "c90" +.PD 0 +.ie n .IP """c89""" 4 +.el .IP "\f(CWc89\fR" 4 +.IX Item "c89" +.ie n .IP """iso9899:1990""" 4 +.el .IP "\f(CWiso9899:1990\fR" 4 +.IX Item "iso9899:1990" +.PD +The \s-1ISO\s0 C standard from 1990. \fBc90\fR is the customary shorthand for +this version of the standard. +.Sp +The \fB\-ansi\fR option is equivalent to \fB\-std=c90\fR. +.ie n .IP """iso9899:199409""" 4 +.el .IP "\f(CWiso9899:199409\fR" 4 +.IX Item "iso9899:199409" +The 1990 C standard, as amended in 1994. +.ie n .IP """iso9899:1999""" 4 +.el .IP "\f(CWiso9899:1999\fR" 4 +.IX Item "iso9899:1999" +.PD 0 +.ie n .IP """c99""" 4 +.el .IP "\f(CWc99\fR" 4 +.IX Item "c99" +.ie n .IP """iso9899:199x""" 4 +.el .IP "\f(CWiso9899:199x\fR" 4 +.IX Item "iso9899:199x" +.ie n .IP """c9x""" 4 +.el .IP "\f(CWc9x\fR" 4 +.IX Item "c9x" +.PD +The revised \s-1ISO\s0 C standard, published in December 1999. Before +publication, this was known as C9X. +.ie n .IP """c1x""" 4 +.el .IP "\f(CWc1x\fR" 4 +.IX Item "c1x" +The next version of the \s-1ISO\s0 C standard, still under development. +.ie n .IP """gnu90""" 4 +.el .IP "\f(CWgnu90\fR" 4 +.IX Item "gnu90" +.PD 0 +.ie n .IP """gnu89""" 4 +.el .IP "\f(CWgnu89\fR" 4 +.IX Item "gnu89" +.PD +The 1990 C standard plus \s-1GNU\s0 extensions. This is the default. +.ie n .IP """gnu99""" 4 +.el .IP "\f(CWgnu99\fR" 4 +.IX Item "gnu99" +.PD 0 +.ie n .IP """gnu9x""" 4 +.el .IP "\f(CWgnu9x\fR" 4 +.IX Item "gnu9x" +.PD +The 1999 C standard plus \s-1GNU\s0 extensions. +.ie n .IP """gnu1x""" 4 +.el .IP "\f(CWgnu1x\fR" 4 +.IX Item "gnu1x" +The next version of the \s-1ISO\s0 C standard, still under development, plus +\&\s-1GNU\s0 extensions. +.ie n .IP """c++98""" 4 +.el .IP "\f(CWc++98\fR" 4 +.IX Item "c++98" +The 1998 \s-1ISO\s0 \*(C+ standard plus amendments. +.ie n .IP """gnu++98""" 4 +.el .IP "\f(CWgnu++98\fR" 4 +.IX Item "gnu++98" +The same as \fB\-std=c++98\fR plus \s-1GNU\s0 extensions. This is the +default for \*(C+ code. +.RE +.RS 4 +.RE +.IP "\fB\-I\-\fR" 4 +.IX Item "-I-" +Split the include path. Any directories specified with \fB\-I\fR +options before \fB\-I\-\fR are searched only for headers requested with +\&\f(CW\*(C`#include\ "\f(CIfile\f(CW"\*(C'\fR; they are not searched for +\&\f(CW\*(C`#include\ <\f(CIfile\f(CW>\*(C'\fR. If additional directories are +specified with \fB\-I\fR options after the \fB\-I\-\fR, those +directories are searched for all \fB#include\fR directives. +.Sp +In addition, \fB\-I\-\fR inhibits the use of the directory of the current +file directory as the first search directory for \f(CW\*(C`#include\ "\f(CIfile\f(CW"\*(C'\fR. +.Sp +This option has been deprecated. +.IP "\fB\-nostdinc\fR" 4 +.IX Item "-nostdinc" +Do not search the standard system directories for header files. +Only the directories you have specified with \fB\-I\fR options +(and the directory of the current file, if appropriate) are searched. +.IP "\fB\-nostdinc++\fR" 4 +.IX Item "-nostdinc++" +Do not search for header files in the \*(C+\-specific standard directories, +but do still search the other standard directories. (This option is +used when building the \*(C+ library.) +.IP "\fB\-include\fR \fIfile\fR" 4 +.IX Item "-include file" +Process \fIfile\fR as if \f(CW\*(C`#include "file"\*(C'\fR appeared as the first +line of the primary source file. However, the first directory searched +for \fIfile\fR is the preprocessor's working directory \fIinstead of\fR +the directory containing the main source file. If not found there, it +is searched for in the remainder of the \f(CW\*(C`#include "..."\*(C'\fR search +chain as normal. +.Sp +If multiple \fB\-include\fR options are given, the files are included +in the order they appear on the command line. +.IP "\fB\-imacros\fR \fIfile\fR" 4 +.IX Item "-imacros file" +Exactly like \fB\-include\fR, except that any output produced by +scanning \fIfile\fR is thrown away. Macros it defines remain defined. +This allows you to acquire all the macros from a header without also +processing its declarations. +.Sp +All files specified by \fB\-imacros\fR are processed before all files +specified by \fB\-include\fR. +.IP "\fB\-idirafter\fR \fIdir\fR" 4 +.IX Item "-idirafter dir" +Search \fIdir\fR for header files, but do it \fIafter\fR all +directories specified with \fB\-I\fR and the standard system directories +have been exhausted. \fIdir\fR is treated as a system include directory. +If \fIdir\fR begins with \f(CW\*(C`=\*(C'\fR, then the \f(CW\*(C`=\*(C'\fR will be replaced +by the sysroot prefix; see \fB\-\-sysroot\fR and \fB\-isysroot\fR. +.IP "\fB\-iprefix\fR \fIprefix\fR" 4 +.IX Item "-iprefix prefix" +Specify \fIprefix\fR as the prefix for subsequent \fB\-iwithprefix\fR +options. If the prefix represents a directory, you should include the +final \fB/\fR. +.IP "\fB\-iwithprefix\fR \fIdir\fR" 4 +.IX Item "-iwithprefix dir" +.PD 0 +.IP "\fB\-iwithprefixbefore\fR \fIdir\fR" 4 +.IX Item "-iwithprefixbefore dir" +.PD +Append \fIdir\fR to the prefix specified previously with +\&\fB\-iprefix\fR, and add the resulting directory to the include search +path. \fB\-iwithprefixbefore\fR puts it in the same place \fB\-I\fR +would; \fB\-iwithprefix\fR puts it where \fB\-idirafter\fR would. +.IP "\fB\-isysroot\fR \fIdir\fR" 4 +.IX Item "-isysroot dir" +This option is like the \fB\-\-sysroot\fR option, but applies only to +header files (except for Darwin targets, where it applies to both header +files and libraries). See the \fB\-\-sysroot\fR option for more +information. +.IP "\fB\-imultilib\fR \fIdir\fR" 4 +.IX Item "-imultilib dir" +Use \fIdir\fR as a subdirectory of the directory containing +target-specific \*(C+ headers. +.IP "\fB\-isystem\fR \fIdir\fR" 4 +.IX Item "-isystem dir" +Search \fIdir\fR for header files, after all directories specified by +\&\fB\-I\fR but before the standard system directories. Mark it +as a system directory, so that it gets the same special treatment as +is applied to the standard system directories. +.Sp +If \fIdir\fR begins with \f(CW\*(C`=\*(C'\fR, then the \f(CW\*(C`=\*(C'\fR will be replaced +by the sysroot prefix; see \fB\-\-sysroot\fR and \fB\-isysroot\fR. +.IP "\fB\-iquote\fR \fIdir\fR" 4 +.IX Item "-iquote dir" +Search \fIdir\fR only for header files requested with +\&\f(CW\*(C`#include\ "\f(CIfile\f(CW"\*(C'\fR; they are not searched for +\&\f(CW\*(C`#include\ <\f(CIfile\f(CW>\*(C'\fR, before all directories specified by +\&\fB\-I\fR and before the standard system directories. +.Sp +If \fIdir\fR begins with \f(CW\*(C`=\*(C'\fR, then the \f(CW\*(C`=\*(C'\fR will be replaced +by the sysroot prefix; see \fB\-\-sysroot\fR and \fB\-isysroot\fR. +.IP "\fB\-fdirectives\-only\fR" 4 +.IX Item "-fdirectives-only" +When preprocessing, handle directives, but do not expand macros. +.Sp +The option's behavior depends on the \fB\-E\fR and \fB\-fpreprocessed\fR +options. +.Sp +With \fB\-E\fR, preprocessing is limited to the handling of directives +such as \f(CW\*(C`#define\*(C'\fR, \f(CW\*(C`#ifdef\*(C'\fR, and \f(CW\*(C`#error\*(C'\fR. Other +preprocessor operations, such as macro expansion and trigraph +conversion are not performed. In addition, the \fB\-dD\fR option is +implicitly enabled. +.Sp +With \fB\-fpreprocessed\fR, predefinition of command line and most +builtin macros is disabled. Macros such as \f(CW\*(C`_\|_LINE_\|_\*(C'\fR, which are +contextually dependent, are handled normally. This enables compilation of +files previously preprocessed with \f(CW\*(C`\-E \-fdirectives\-only\*(C'\fR. +.Sp +With both \fB\-E\fR and \fB\-fpreprocessed\fR, the rules for +\&\fB\-fpreprocessed\fR take precedence. This enables full preprocessing of +files previously preprocessed with \f(CW\*(C`\-E \-fdirectives\-only\*(C'\fR. +.IP "\fB\-fdollars\-in\-identifiers\fR" 4 +.IX Item "-fdollars-in-identifiers" +Accept \fB$\fR in identifiers. +.IP "\fB\-fextended\-identifiers\fR" 4 +.IX Item "-fextended-identifiers" +Accept universal character names in identifiers. This option is +experimental; in a future version of \s-1GCC\s0, it will be enabled by +default for C99 and \*(C+. +.IP "\fB\-fpreprocessed\fR" 4 +.IX Item "-fpreprocessed" +Indicate to the preprocessor that the input file has already been +preprocessed. This suppresses things like macro expansion, trigraph +conversion, escaped newline splicing, and processing of most directives. +The preprocessor still recognizes and removes comments, so that you can +pass a file preprocessed with \fB\-C\fR to the compiler without +problems. In this mode the integrated preprocessor is little more than +a tokenizer for the front ends. +.Sp +\&\fB\-fpreprocessed\fR is implicit if the input file has one of the +extensions \fB.i\fR, \fB.ii\fR or \fB.mi\fR. These are the +extensions that \s-1GCC\s0 uses for preprocessed files created by +\&\fB\-save\-temps\fR. +.IP "\fB\-ftabstop=\fR\fIwidth\fR" 4 +.IX Item "-ftabstop=width" +Set the distance between tab stops. This helps the preprocessor report +correct column numbers in warnings or errors, even if tabs appear on the +line. If the value is less than 1 or greater than 100, the option is +ignored. The default is 8. +.IP "\fB\-fexec\-charset=\fR\fIcharset\fR" 4 +.IX Item "-fexec-charset=charset" +Set the execution character set, used for string and character +constants. The default is \s-1UTF\-8\s0. \fIcharset\fR can be any encoding +supported by the system's \f(CW\*(C`iconv\*(C'\fR library routine. +.IP "\fB\-fwide\-exec\-charset=\fR\fIcharset\fR" 4 +.IX Item "-fwide-exec-charset=charset" +Set the wide execution character set, used for wide string and +character constants. The default is \s-1UTF\-32\s0 or \s-1UTF\-16\s0, whichever +corresponds to the width of \f(CW\*(C`wchar_t\*(C'\fR. As with +\&\fB\-fexec\-charset\fR, \fIcharset\fR can be any encoding supported +by the system's \f(CW\*(C`iconv\*(C'\fR library routine; however, you will have +problems with encodings that do not fit exactly in \f(CW\*(C`wchar_t\*(C'\fR. +.IP "\fB\-finput\-charset=\fR\fIcharset\fR" 4 +.IX Item "-finput-charset=charset" +Set the input character set, used for translation from the character +set of the input file to the source character set used by \s-1GCC\s0. If the +locale does not specify, or \s-1GCC\s0 cannot get this information from the +locale, the default is \s-1UTF\-8\s0. This can be overridden by either the locale +or this command line option. Currently the command line option takes +precedence if there's a conflict. \fIcharset\fR can be any encoding +supported by the system's \f(CW\*(C`iconv\*(C'\fR library routine. +.IP "\fB\-fworking\-directory\fR" 4 +.IX Item "-fworking-directory" +Enable generation of linemarkers in the preprocessor output that will +let the compiler know the current working directory at the time of +preprocessing. When this option is enabled, the preprocessor will +emit, after the initial linemarker, a second linemarker with the +current working directory followed by two slashes. \s-1GCC\s0 will use this +directory, when it's present in the preprocessed input, as the +directory emitted as the current working directory in some debugging +information formats. This option is implicitly enabled if debugging +information is enabled, but this can be inhibited with the negated +form \fB\-fno\-working\-directory\fR. If the \fB\-P\fR flag is +present in the command line, this option has no effect, since no +\&\f(CW\*(C`#line\*(C'\fR directives are emitted whatsoever. +.IP "\fB\-fno\-show\-column\fR" 4 +.IX Item "-fno-show-column" +Do not print column numbers in diagnostics. This may be necessary if +diagnostics are being scanned by a program that does not understand the +column numbers, such as \fBdejagnu\fR. +.IP "\fB\-A\fR \fIpredicate\fR\fB=\fR\fIanswer\fR" 4 +.IX Item "-A predicate=answer" +Make an assertion with the predicate \fIpredicate\fR and answer +\&\fIanswer\fR. This form is preferred to the older form \fB\-A\fR +\&\fIpredicate\fR\fB(\fR\fIanswer\fR\fB)\fR, which is still supported, because +it does not use shell special characters. +.IP "\fB\-A \-\fR\fIpredicate\fR\fB=\fR\fIanswer\fR" 4 +.IX Item "-A -predicate=answer" +Cancel an assertion with the predicate \fIpredicate\fR and answer +\&\fIanswer\fR. +.IP "\fB\-dCHARS\fR" 4 +.IX Item "-dCHARS" +\&\fI\s-1CHARS\s0\fR is a sequence of one or more of the following characters, +and must not be preceded by a space. Other characters are interpreted +by the compiler proper, or reserved for future versions of \s-1GCC\s0, and so +are silently ignored. If you specify characters whose behavior +conflicts, the result is undefined. +.RS 4 +.IP "\fBM\fR" 4 +.IX Item "M" +Instead of the normal output, generate a list of \fB#define\fR +directives for all the macros defined during the execution of the +preprocessor, including predefined macros. This gives you a way of +finding out what is predefined in your version of the preprocessor. +Assuming you have no file \fIfoo.h\fR, the command +.Sp +.Vb 1 +\& touch foo.h; cpp \-dM foo.h +.Ve +.Sp +will show all the predefined macros. +.Sp +If you use \fB\-dM\fR without the \fB\-E\fR option, \fB\-dM\fR is +interpreted as a synonym for \fB\-fdump\-rtl\-mach\fR. +.IP "\fBD\fR" 4 +.IX Item "D" +Like \fBM\fR except in two respects: it does \fInot\fR include the +predefined macros, and it outputs \fIboth\fR the \fB#define\fR +directives and the result of preprocessing. Both kinds of output go to +the standard output file. +.IP "\fBN\fR" 4 +.IX Item "N" +Like \fBD\fR, but emit only the macro names, not their expansions. +.IP "\fBI\fR" 4 +.IX Item "I" +Output \fB#include\fR directives in addition to the result of +preprocessing. +.IP "\fBU\fR" 4 +.IX Item "U" +Like \fBD\fR except that only macros that are expanded, or whose +definedness is tested in preprocessor directives, are output; the +output is delayed until the use or test of the macro; and +\&\fB#undef\fR directives are also output for macros tested but +undefined at the time. +.RE +.RS 4 +.RE +.IP "\fB\-P\fR" 4 +.IX Item "-P" +Inhibit generation of linemarkers in the output from the preprocessor. +This might be useful when running the preprocessor on something that is +not C code, and will be sent to a program which might be confused by the +linemarkers. +.IP "\fB\-C\fR" 4 +.IX Item "-C" +Do not discard comments. All comments are passed through to the output +file, except for comments in processed directives, which are deleted +along with the directive. +.Sp +You should be prepared for side effects when using \fB\-C\fR; it +causes the preprocessor to treat comments as tokens in their own right. +For example, comments appearing at the start of what would be a +directive line have the effect of turning that line into an ordinary +source line, since the first token on the line is no longer a \fB#\fR. +.IP "\fB\-CC\fR" 4 +.IX Item "-CC" +Do not discard comments, including during macro expansion. This is +like \fB\-C\fR, except that comments contained within macros are +also passed through to the output file where the macro is expanded. +.Sp +In addition to the side-effects of the \fB\-C\fR option, the +\&\fB\-CC\fR option causes all \*(C+\-style comments inside a macro +to be converted to C\-style comments. This is to prevent later use +of that macro from inadvertently commenting out the remainder of +the source line. +.Sp +The \fB\-CC\fR option is generally used to support lint comments. +.IP "\fB\-traditional\-cpp\fR" 4 +.IX Item "-traditional-cpp" +Try to imitate the behavior of old-fashioned C preprocessors, as +opposed to \s-1ISO\s0 C preprocessors. +.IP "\fB\-trigraphs\fR" 4 +.IX Item "-trigraphs" +Process trigraph sequences. +.IP "\fB\-remap\fR" 4 +.IX Item "-remap" +Enable special code to work around file systems which only permit very +short file names, such as MS-DOS. +.IP "\fB\-\-help\fR" 4 +.IX Item "--help" +.PD 0 +.IP "\fB\-\-target\-help\fR" 4 +.IX Item "--target-help" +.PD +Print text describing all the command line options instead of +preprocessing anything. +.IP "\fB\-v\fR" 4 +.IX Item "-v" +Verbose mode. Print out \s-1GNU\s0 \s-1CPP\s0's version number at the beginning of +execution, and report the final form of the include path. +.IP "\fB\-H\fR" 4 +.IX Item "-H" +Print the name of each header file used, in addition to other normal +activities. Each name is indented to show how deep in the +\&\fB#include\fR stack it is. Precompiled header files are also +printed, even if they are found to be invalid; an invalid precompiled +header file is printed with \fB...x\fR and a valid one with \fB...!\fR . +.IP "\fB\-version\fR" 4 +.IX Item "-version" +.PD 0 +.IP "\fB\-\-version\fR" 4 +.IX Item "--version" +.PD +Print out \s-1GNU\s0 \s-1CPP\s0's version number. With one dash, proceed to +preprocess as normal. With two dashes, exit immediately. +.SH "ENVIRONMENT" +.IX Header "ENVIRONMENT" +This section describes the environment variables that affect how \s-1CPP\s0 +operates. You can use them to specify directories or prefixes to use +when searching for include files, or to control dependency output. +.PP +Note that you can also specify places to search using options such as +\&\fB\-I\fR, and control dependency output with options like +\&\fB\-M\fR. These take precedence over +environment variables, which in turn take precedence over the +configuration of \s-1GCC\s0. +.IP "\fB\s-1CPATH\s0\fR" 4 +.IX Item "CPATH" +.PD 0 +.IP "\fBC_INCLUDE_PATH\fR" 4 +.IX Item "C_INCLUDE_PATH" +.IP "\fB\s-1CPLUS_INCLUDE_PATH\s0\fR" 4 +.IX Item "CPLUS_INCLUDE_PATH" +.IP "\fB\s-1OBJC_INCLUDE_PATH\s0\fR" 4 +.IX Item "OBJC_INCLUDE_PATH" +.PD +Each variable's value is a list of directories separated by a special +character, much like \fB\s-1PATH\s0\fR, in which to look for header files. +The special character, \f(CW\*(C`PATH_SEPARATOR\*(C'\fR, is target-dependent and +determined at \s-1GCC\s0 build time. For Microsoft Windows-based targets it is a +semicolon, and for almost all other targets it is a colon. +.Sp +\&\fB\s-1CPATH\s0\fR specifies a list of directories to be searched as if +specified with \fB\-I\fR, but after any paths given with \fB\-I\fR +options on the command line. This environment variable is used +regardless of which language is being preprocessed. +.Sp +The remaining environment variables apply only when preprocessing the +particular language indicated. Each specifies a list of directories +to be searched as if specified with \fB\-isystem\fR, but after any +paths given with \fB\-isystem\fR options on the command line. +.Sp +In all these variables, an empty element instructs the compiler to +search its current working directory. Empty elements can appear at the +beginning or end of a path. For instance, if the value of +\&\fB\s-1CPATH\s0\fR is \f(CW\*(C`:/special/include\*(C'\fR, that has the same +effect as \fB\-I.\ \-I/special/include\fR. +.IP "\fB\s-1DEPENDENCIES_OUTPUT\s0\fR" 4 +.IX Item "DEPENDENCIES_OUTPUT" +If this variable is set, its value specifies how to output +dependencies for Make based on the non-system header files processed +by the compiler. System header files are ignored in the dependency +output. +.Sp +The value of \fB\s-1DEPENDENCIES_OUTPUT\s0\fR can be just a file name, in +which case the Make rules are written to that file, guessing the target +name from the source file name. Or the value can have the form +\&\fIfile\fR\fB \fR\fItarget\fR, in which case the rules are written to +file \fIfile\fR using \fItarget\fR as the target name. +.Sp +In other words, this environment variable is equivalent to combining +the options \fB\-MM\fR and \fB\-MF\fR, +with an optional \fB\-MT\fR switch too. +.IP "\fB\s-1SUNPRO_DEPENDENCIES\s0\fR" 4 +.IX Item "SUNPRO_DEPENDENCIES" +This variable is the same as \fB\s-1DEPENDENCIES_OUTPUT\s0\fR (see above), +except that system header files are not ignored, so it implies +\&\fB\-M\fR rather than \fB\-MM\fR. However, the dependence on the +main input file is omitted. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fIgpl\fR\|(7), \fIgfdl\fR\|(7), \fIfsf\-funding\fR\|(7), +\&\fIgcc\fR\|(1), \fIas\fR\|(1), \fIld\fR\|(1), and the Info entries for \fIcpp\fR, \fIgcc\fR, and +\&\fIbinutils\fR. +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright (c) 1987, 1989, 1991, 1992, 1993, 1994, 1995, 1996, +1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, +2008, 2009, 2010, 2011 +Free Software Foundation, Inc. +.PP +Permission is granted to copy, distribute and/or modify this document +under the terms of the \s-1GNU\s0 Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation. A copy of +the license is included in the +man page \fIgfdl\fR\|(7). +This manual contains no Invariant Sections. The Front-Cover Texts are +(a) (see below), and the Back-Cover Texts are (b) (see below). +.PP +(a) The \s-1FSF\s0's Front-Cover Text is: +.PP +.Vb 1 +\& A GNU Manual +.Ve +.PP +(b) The \s-1FSF\s0's Back-Cover Text is: +.PP +.Vb 3 +\& You have freedom to copy and modify this GNU Manual, like GNU +\& software. Copies published by the Free Software Foundation raise +\& funds for GNU development. +.Ve diff --git a/gcc/doc/cpp.info b/gcc/doc/cpp.info new file mode 100644 index 000000000..6f042b002 --- /dev/null +++ b/gcc/doc/cpp.info @@ -0,0 +1,5549 @@ +This is doc/cpp.info, produced by makeinfo version 4.13 from +/home/jakub/gcc-4.6.4/gcc-4.6.4/gcc/doc/cpp.texi. + +Copyright (C) 1987, 1989, 1991, 1992, 1993, 1994, 1995, 1996, 1997, +1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, +2010, 2011 Free Software Foundation, Inc. + + Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation. A copy of +the license is included in the section entitled "GNU Free Documentation +License". + + This manual contains no Invariant Sections. The Front-Cover Texts +are (a) (see below), and the Back-Cover Texts are (b) (see below). + + (a) The FSF's Front-Cover Text is: + + A GNU Manual + + (b) The FSF's Back-Cover Text is: + + You have freedom to copy and modify this GNU Manual, like GNU +software. Copies published by the Free Software Foundation raise +funds for GNU development. + +INFO-DIR-SECTION Software development +START-INFO-DIR-ENTRY +* Cpp: (cpp). The GNU C preprocessor. +END-INFO-DIR-ENTRY + + +File: cpp.info, Node: Top, Next: Overview, Up: (dir) + +The C Preprocessor +****************** + +The C preprocessor implements the macro language used to transform C, +C++, and Objective-C programs before they are compiled. It can also be +useful on its own. + +* Menu: + +* Overview:: +* Header Files:: +* Macros:: +* Conditionals:: +* Diagnostics:: +* Line Control:: +* Pragmas:: +* Other Directives:: +* Preprocessor Output:: +* Traditional Mode:: +* Implementation Details:: +* Invocation:: +* Environment Variables:: +* GNU Free Documentation License:: +* Index of Directives:: +* Option Index:: +* Concept Index:: + + --- The Detailed Node Listing --- + +Overview + +* Character sets:: +* Initial processing:: +* Tokenization:: +* The preprocessing language:: + +Header Files + +* Include Syntax:: +* Include Operation:: +* Search Path:: +* Once-Only Headers:: +* Alternatives to Wrapper #ifndef:: +* Computed Includes:: +* Wrapper Headers:: +* System Headers:: + +Macros + +* Object-like Macros:: +* Function-like Macros:: +* Macro Arguments:: +* Stringification:: +* Concatenation:: +* Variadic Macros:: +* Predefined Macros:: +* Undefining and Redefining Macros:: +* Directives Within Macro Arguments:: +* Macro Pitfalls:: + +Predefined Macros + +* Standard Predefined Macros:: +* Common Predefined Macros:: +* System-specific Predefined Macros:: +* C++ Named Operators:: + +Macro Pitfalls + +* Misnesting:: +* Operator Precedence Problems:: +* Swallowing the Semicolon:: +* Duplication of Side Effects:: +* Self-Referential Macros:: +* Argument Prescan:: +* Newlines in Arguments:: + +Conditionals + +* Conditional Uses:: +* Conditional Syntax:: +* Deleted Code:: + +Conditional Syntax + +* Ifdef:: +* If:: +* Defined:: +* Else:: +* Elif:: + +Implementation Details + +* Implementation-defined behavior:: +* Implementation limits:: +* Obsolete Features:: +* Differences from previous versions:: + +Obsolete Features + +* Obsolete Features:: + + Copyright (C) 1987, 1989, 1991, 1992, 1993, 1994, 1995, 1996, 1997, +1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, +2010, 2011 Free Software Foundation, Inc. + + Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation. A copy of +the license is included in the section entitled "GNU Free Documentation +License". + + This manual contains no Invariant Sections. The Front-Cover Texts +are (a) (see below), and the Back-Cover Texts are (b) (see below). + + (a) The FSF's Front-Cover Text is: + + A GNU Manual + + (b) The FSF's Back-Cover Text is: + + You have freedom to copy and modify this GNU Manual, like GNU +software. Copies published by the Free Software Foundation raise +funds for GNU development. + + +File: cpp.info, Node: Overview, Next: Header Files, Prev: Top, Up: Top + +1 Overview +********** + +The C preprocessor, often known as "cpp", is a "macro processor" that +is used automatically by the C compiler to transform your program +before compilation. It is called a macro processor because it allows +you to define "macros", which are brief abbreviations for longer +constructs. + + The C preprocessor is intended to be used only with C, C++, and +Objective-C source code. In the past, it has been abused as a general +text processor. It will choke on input which does not obey C's lexical +rules. For example, apostrophes will be interpreted as the beginning of +character constants, and cause errors. Also, you cannot rely on it +preserving characteristics of the input which are not significant to +C-family languages. If a Makefile is preprocessed, all the hard tabs +will be removed, and the Makefile will not work. + + Having said that, you can often get away with using cpp on things +which are not C. Other Algol-ish programming languages are often safe +(Pascal, Ada, etc.) So is assembly, with caution. `-traditional-cpp' +mode preserves more white space, and is otherwise more permissive. Many +of the problems can be avoided by writing C or C++ style comments +instead of native language comments, and keeping macros simple. + + Wherever possible, you should use a preprocessor geared to the +language you are writing in. Modern versions of the GNU assembler have +macro facilities. Most high level programming languages have their own +conditional compilation and inclusion mechanism. If all else fails, +try a true general text processor, such as GNU M4. + + C preprocessors vary in some details. This manual discusses the GNU +C preprocessor, which provides a small superset of the features of ISO +Standard C. In its default mode, the GNU C preprocessor does not do a +few things required by the standard. These are features which are +rarely, if ever, used, and may cause surprising changes to the meaning +of a program which does not expect them. To get strict ISO Standard C, +you should use the `-std=c90', `-std=c99' or `-std=c1x' options, +depending on which version of the standard you want. To get all the +mandatory diagnostics, you must also use `-pedantic'. *Note +Invocation::. + + This manual describes the behavior of the ISO preprocessor. To +minimize gratuitous differences, where the ISO preprocessor's behavior +does not conflict with traditional semantics, the traditional +preprocessor should behave the same way. The various differences that +do exist are detailed in the section *note Traditional Mode::. + + For clarity, unless noted otherwise, references to `CPP' in this +manual refer to GNU CPP. + +* Menu: + +* Character sets:: +* Initial processing:: +* Tokenization:: +* The preprocessing language:: + + +File: cpp.info, Node: Character sets, Next: Initial processing, Up: Overview + +1.1 Character sets +================== + +Source code character set processing in C and related languages is +rather complicated. The C standard discusses two character sets, but +there are really at least four. + + The files input to CPP might be in any character set at all. CPP's +very first action, before it even looks for line boundaries, is to +convert the file into the character set it uses for internal +processing. That set is what the C standard calls the "source" +character set. It must be isomorphic with ISO 10646, also known as +Unicode. CPP uses the UTF-8 encoding of Unicode. + + The character sets of the input files are specified using the +`-finput-charset=' option. + + All preprocessing work (the subject of the rest of this manual) is +carried out in the source character set. If you request textual output +from the preprocessor with the `-E' option, it will be in UTF-8. + + After preprocessing is complete, string and character constants are +converted again, into the "execution" character set. This character +set is under control of the user; the default is UTF-8, matching the +source character set. Wide string and character constants have their +own character set, which is not called out specifically in the +standard. Again, it is under control of the user. The default is +UTF-16 or UTF-32, whichever fits in the target's `wchar_t' type, in the +target machine's byte order.(1) Octal and hexadecimal escape sequences +do not undergo conversion; '\x12' has the value 0x12 regardless of the +currently selected execution character set. All other escapes are +replaced by the character in the source character set that they +represent, then converted to the execution character set, just like +unescaped characters. + + Unless the experimental `-fextended-identifiers' option is used, GCC +does not permit the use of characters outside the ASCII range, nor `\u' +and `\U' escapes, in identifiers. Even with that option, characters +outside the ASCII range can only be specified with the `\u' and `\U' +escapes, not used directly in identifiers. + + ---------- Footnotes ---------- + + (1) UTF-16 does not meet the requirements of the C standard for a +wide character set, but the choice of 16-bit `wchar_t' is enshrined in +some system ABIs so we cannot fix this. + + +File: cpp.info, Node: Initial processing, Next: Tokenization, Prev: Character sets, Up: Overview + +1.2 Initial processing +====================== + +The preprocessor performs a series of textual transformations on its +input. These happen before all other processing. Conceptually, they +happen in a rigid order, and the entire file is run through each +transformation before the next one begins. CPP actually does them all +at once, for performance reasons. These transformations correspond +roughly to the first three "phases of translation" described in the C +standard. + + 1. The input file is read into memory and broken into lines. + + Different systems use different conventions to indicate the end of + a line. GCC accepts the ASCII control sequences `LF', `CR LF' and + `CR' as end-of-line markers. These are the canonical sequences + used by Unix, DOS and VMS, and the classic Mac OS (before OSX) + respectively. You may therefore safely copy source code written + on any of those systems to a different one and use it without + conversion. (GCC may lose track of the current line number if a + file doesn't consistently use one convention, as sometimes happens + when it is edited on computers with different conventions that + share a network file system.) + + If the last line of any input file lacks an end-of-line marker, + the end of the file is considered to implicitly supply one. The C + standard says that this condition provokes undefined behavior, so + GCC will emit a warning message. + + 2. If trigraphs are enabled, they are replaced by their corresponding + single characters. By default GCC ignores trigraphs, but if you + request a strictly conforming mode with the `-std' option, or you + specify the `-trigraphs' option, then it converts them. + + These are nine three-character sequences, all starting with `??', + that are defined by ISO C to stand for single characters. They + permit obsolete systems that lack some of C's punctuation to use + C. For example, `??/' stands for `\', so '??/n' is a character + constant for a newline. + + Trigraphs are not popular and many compilers implement them + incorrectly. Portable code should not rely on trigraphs being + either converted or ignored. With `-Wtrigraphs' GCC will warn you + when a trigraph may change the meaning of your program if it were + converted. *Note Wtrigraphs::. + + In a string constant, you can prevent a sequence of question marks + from being confused with a trigraph by inserting a backslash + between the question marks, or by separating the string literal at + the trigraph and making use of string literal concatenation. + "(??\?)" is the string `(???)', not `(?]'. Traditional C + compilers do not recognize these idioms. + + The nine trigraphs and their replacements are + + Trigraph: ??( ??) ??< ??> ??= ??/ ??' ??! ??- + Replacement: [ ] { } # \ ^ | ~ + + 3. Continued lines are merged into one long line. + + A continued line is a line which ends with a backslash, `\'. The + backslash is removed and the following line is joined with the + current one. No space is inserted, so you may split a line + anywhere, even in the middle of a word. (It is generally more + readable to split lines only at white space.) + + The trailing backslash on a continued line is commonly referred to + as a "backslash-newline". + + If there is white space between a backslash and the end of a line, + that is still a continued line. However, as this is usually the + result of an editing mistake, and many compilers will not accept + it as a continued line, GCC will warn you about it. + + 4. All comments are replaced with single spaces. + + There are two kinds of comments. "Block comments" begin with `/*' + and continue until the next `*/'. Block comments do not nest: + + /* this is /* one comment */ text outside comment + + "Line comments" begin with `//' and continue to the end of the + current line. Line comments do not nest either, but it does not + matter, because they would end in the same place anyway. + + // this is // one comment + text outside comment + + It is safe to put line comments inside block comments, or vice versa. + + /* block comment + // contains line comment + yet more comment + */ outside comment + + // line comment /* contains block comment */ + + But beware of commenting out one end of a block comment with a line +comment. + + // l.c. /* block comment begins + oops! this isn't a comment anymore */ + + Comments are not recognized within string literals. "/* blah */" is +the string constant `/* blah */', not an empty string. + + Line comments are not in the 1989 edition of the C standard, but they +are recognized by GCC as an extension. In C++ and in the 1999 edition +of the C standard, they are an official part of the language. + + Since these transformations happen before all other processing, you +can split a line mechanically with backslash-newline anywhere. You can +comment out the end of a line. You can continue a line comment onto the +next line with backslash-newline. You can even split `/*', `*/', and +`//' onto multiple lines with backslash-newline. For example: + + /\ + * + */ # /* + */ defi\ + ne FO\ + O 10\ + 20 + +is equivalent to `#define FOO 1020'. All these tricks are extremely +confusing and should not be used in code intended to be readable. + + There is no way to prevent a backslash at the end of a line from +being interpreted as a backslash-newline. This cannot affect any +correct program, however. + + +File: cpp.info, Node: Tokenization, Next: The preprocessing language, Prev: Initial processing, Up: Overview + +1.3 Tokenization +================ + +After the textual transformations are finished, the input file is +converted into a sequence of "preprocessing tokens". These mostly +correspond to the syntactic tokens used by the C compiler, but there are +a few differences. White space separates tokens; it is not itself a +token of any kind. Tokens do not have to be separated by white space, +but it is often necessary to avoid ambiguities. + + When faced with a sequence of characters that has more than one +possible tokenization, the preprocessor is greedy. It always makes +each token, starting from the left, as big as possible before moving on +to the next token. For instance, `a+++++b' is interpreted as +`a ++ ++ + b', not as `a ++ + ++ b', even though the latter +tokenization could be part of a valid C program and the former could +not. + + Once the input file is broken into tokens, the token boundaries never +change, except when the `##' preprocessing operator is used to paste +tokens together. *Note Concatenation::. For example, + + #define foo() bar + foo()baz + ==> bar baz + _not_ + ==> barbaz + + The compiler does not re-tokenize the preprocessor's output. Each +preprocessing token becomes one compiler token. + + Preprocessing tokens fall into five broad classes: identifiers, +preprocessing numbers, string literals, punctuators, and other. An +"identifier" is the same as an identifier in C: any sequence of +letters, digits, or underscores, which begins with a letter or +underscore. Keywords of C have no significance to the preprocessor; +they are ordinary identifiers. You can define a macro whose name is a +keyword, for instance. The only identifier which can be considered a +preprocessing keyword is `defined'. *Note Defined::. + + This is mostly true of other languages which use the C preprocessor. +However, a few of the keywords of C++ are significant even in the +preprocessor. *Note C++ Named Operators::. + + In the 1999 C standard, identifiers may contain letters which are not +part of the "basic source character set", at the implementation's +discretion (such as accented Latin letters, Greek letters, or Chinese +ideograms). This may be done with an extended character set, or the +`\u' and `\U' escape sequences. The implementation of this feature in +GCC is experimental; such characters are only accepted in the `\u' and +`\U' forms and only if `-fextended-identifiers' is used. + + As an extension, GCC treats `$' as a letter. This is for +compatibility with some systems, such as VMS, where `$' is commonly +used in system-defined function and object names. `$' is not a letter +in strictly conforming mode, or if you specify the `-$' option. *Note +Invocation::. + + A "preprocessing number" has a rather bizarre definition. The +category includes all the normal integer and floating point constants +one expects of C, but also a number of other things one might not +initially recognize as a number. Formally, preprocessing numbers begin +with an optional period, a required decimal digit, and then continue +with any sequence of letters, digits, underscores, periods, and +exponents. Exponents are the two-character sequences `e+', `e-', `E+', +`E-', `p+', `p-', `P+', and `P-'. (The exponents that begin with `p' +or `P' are new to C99. They are used for hexadecimal floating-point +constants.) + + The purpose of this unusual definition is to isolate the preprocessor +from the full complexity of numeric constants. It does not have to +distinguish between lexically valid and invalid floating-point numbers, +which is complicated. The definition also permits you to split an +identifier at any position and get exactly two tokens, which can then be +pasted back together with the `##' operator. + + It's possible for preprocessing numbers to cause programs to be +misinterpreted. For example, `0xE+12' is a preprocessing number which +does not translate to any valid numeric constant, therefore a syntax +error. It does not mean `0xE + 12', which is what you might have +intended. + + "String literals" are string constants, character constants, and +header file names (the argument of `#include').(1) String constants +and character constants are straightforward: "..." or '...'. In either +case embedded quotes should be escaped with a backslash: '\'' is the +character constant for `''. There is no limit on the length of a +character constant, but the value of a character constant that contains +more than one character is implementation-defined. *Note +Implementation Details::. + + Header file names either look like string constants, "...", or are +written with angle brackets instead, <...>. In either case, backslash +is an ordinary character. There is no way to escape the closing quote +or angle bracket. The preprocessor looks for the header file in +different places depending on which form you use. *Note Include +Operation::. + + No string literal may extend past the end of a line. Older versions +of GCC accepted multi-line string constants. You may use continued +lines instead, or string constant concatenation. *Note Differences +from previous versions::. + + "Punctuators" are all the usual bits of punctuation which are +meaningful to C and C++. All but three of the punctuation characters in +ASCII are C punctuators. The exceptions are `@', `$', and ``'. In +addition, all the two- and three-character operators are punctuators. +There are also six "digraphs", which the C++ standard calls +"alternative tokens", which are merely alternate ways to spell other +punctuators. This is a second attempt to work around missing +punctuation in obsolete systems. It has no negative side effects, +unlike trigraphs, but does not cover as much ground. The digraphs and +their corresponding normal punctuators are: + + Digraph: <% %> <: :> %: %:%: + Punctuator: { } [ ] # ## + + Any other single character is considered "other". It is passed on to +the preprocessor's output unmolested. The C compiler will almost +certainly reject source code containing "other" tokens. In ASCII, the +only other characters are `@', `$', ``', and control characters other +than NUL (all bits zero). (Note that `$' is normally considered a +letter.) All characters with the high bit set (numeric range +0x7F-0xFF) are also "other" in the present implementation. This will +change when proper support for international character sets is added to +GCC. + + NUL is a special case because of the high probability that its +appearance is accidental, and because it may be invisible to the user +(many terminals do not display NUL at all). Within comments, NULs are +silently ignored, just as any other character would be. In running +text, NUL is considered white space. For example, these two directives +have the same meaning. + + #define X^@1 + #define X 1 + +(where `^@' is ASCII NUL). Within string or character constants, NULs +are preserved. In the latter two cases the preprocessor emits a +warning message. + + ---------- Footnotes ---------- + + (1) The C standard uses the term "string literal" to refer only to +what we are calling "string constants". + + +File: cpp.info, Node: The preprocessing language, Prev: Tokenization, Up: Overview + +1.4 The preprocessing language +============================== + +After tokenization, the stream of tokens may simply be passed straight +to the compiler's parser. However, if it contains any operations in the +"preprocessing language", it will be transformed first. This stage +corresponds roughly to the standard's "translation phase 4" and is what +most people think of as the preprocessor's job. + + The preprocessing language consists of "directives" to be executed +and "macros" to be expanded. Its primary capabilities are: + + * Inclusion of header files. These are files of declarations that + can be substituted into your program. + + * Macro expansion. You can define "macros", which are abbreviations + for arbitrary fragments of C code. The preprocessor will replace + the macros with their definitions throughout the program. Some + macros are automatically defined for you. + + * Conditional compilation. You can include or exclude parts of the + program according to various conditions. + + * Line control. If you use a program to combine or rearrange source + files into an intermediate file which is then compiled, you can + use line control to inform the compiler where each source line + originally came from. + + * Diagnostics. You can detect problems at compile time and issue + errors or warnings. + + There are a few more, less useful, features. + + Except for expansion of predefined macros, all these operations are +triggered with "preprocessing directives". Preprocessing directives +are lines in your program that start with `#'. Whitespace is allowed +before and after the `#'. The `#' is followed by an identifier, the +"directive name". It specifies the operation to perform. Directives +are commonly referred to as `#NAME' where NAME is the directive name. +For example, `#define' is the directive that defines a macro. + + The `#' which begins a directive cannot come from a macro expansion. +Also, the directive name is not macro expanded. Thus, if `foo' is +defined as a macro expanding to `define', that does not make `#foo' a +valid preprocessing directive. + + The set of valid directive names is fixed. Programs cannot define +new preprocessing directives. + + Some directives require arguments; these make up the rest of the +directive line and must be separated from the directive name by +whitespace. For example, `#define' must be followed by a macro name +and the intended expansion of the macro. + + A preprocessing directive cannot cover more than one line. The line +may, however, be continued with backslash-newline, or by a block comment +which extends past the end of the line. In either case, when the +directive is processed, the continuations have already been merged with +the first line to make one long line. + + +File: cpp.info, Node: Header Files, Next: Macros, Prev: Overview, Up: Top + +2 Header Files +************** + +A header file is a file containing C declarations and macro definitions +(*note Macros::) to be shared between several source files. You request +the use of a header file in your program by "including" it, with the C +preprocessing directive `#include'. + + Header files serve two purposes. + + * System header files declare the interfaces to parts of the + operating system. You include them in your program to supply the + definitions and declarations you need to invoke system calls and + libraries. + + * Your own header files contain declarations for interfaces between + the source files of your program. Each time you have a group of + related declarations and macro definitions all or most of which + are needed in several different source files, it is a good idea to + create a header file for them. + + Including a header file produces the same results as copying the +header file into each source file that needs it. Such copying would be +time-consuming and error-prone. With a header file, the related +declarations appear in only one place. If they need to be changed, they +can be changed in one place, and programs that include the header file +will automatically use the new version when next recompiled. The header +file eliminates the labor of finding and changing all the copies as well +as the risk that a failure to find one copy will result in +inconsistencies within a program. + + In C, the usual convention is to give header files names that end +with `.h'. It is most portable to use only letters, digits, dashes, and +underscores in header file names, and at most one dot. + +* Menu: + +* Include Syntax:: +* Include Operation:: +* Search Path:: +* Once-Only Headers:: +* Alternatives to Wrapper #ifndef:: +* Computed Includes:: +* Wrapper Headers:: +* System Headers:: + + +File: cpp.info, Node: Include Syntax, Next: Include Operation, Up: Header Files + +2.1 Include Syntax +================== + +Both user and system header files are included using the preprocessing +directive `#include'. It has two variants: + +`#include ' + This variant is used for system header files. It searches for a + file named FILE in a standard list of system directories. You can + prepend directories to this list with the `-I' option (*note + Invocation::). + +`#include "FILE"' + This variant is used for header files of your own program. It + searches for a file named FILE first in the directory containing + the current file, then in the quote directories and then the same + directories used for `'. You can prepend directories to the + list of quote directories with the `-iquote' option. + + The argument of `#include', whether delimited with quote marks or +angle brackets, behaves like a string constant in that comments are not +recognized, and macro names are not expanded. Thus, `#include ' +specifies inclusion of a system header file named `x/*y'. + + However, if backslashes occur within FILE, they are considered +ordinary text characters, not escape characters. None of the character +escape sequences appropriate to string constants in C are processed. +Thus, `#include "x\n\\y"' specifies a filename containing three +backslashes. (Some systems interpret `\' as a pathname separator. All +of these also interpret `/' the same way. It is most portable to use +only `/'.) + + It is an error if there is anything (other than comments) on the line +after the file name. + + +File: cpp.info, Node: Include Operation, Next: Search Path, Prev: Include Syntax, Up: Header Files + +2.2 Include Operation +===================== + +The `#include' directive works by directing the C preprocessor to scan +the specified file as input before continuing with the rest of the +current file. The output from the preprocessor contains the output +already generated, followed by the output resulting from the included +file, followed by the output that comes from the text after the +`#include' directive. For example, if you have a header file +`header.h' as follows, + + char *test (void); + +and a main program called `program.c' that uses the header file, like +this, + + int x; + #include "header.h" + + int + main (void) + { + puts (test ()); + } + +the compiler will see the same token stream as it would if `program.c' +read + + int x; + char *test (void); + + int + main (void) + { + puts (test ()); + } + + Included files are not limited to declarations and macro definitions; +those are merely the typical uses. Any fragment of a C program can be +included from another file. The include file could even contain the +beginning of a statement that is concluded in the containing file, or +the end of a statement that was started in the including file. However, +an included file must consist of complete tokens. Comments and string +literals which have not been closed by the end of an included file are +invalid. For error recovery, they are considered to end at the end of +the file. + + To avoid confusion, it is best if header files contain only complete +syntactic units--function declarations or definitions, type +declarations, etc. + + The line following the `#include' directive is always treated as a +separate line by the C preprocessor, even if the included file lacks a +final newline. + + +File: cpp.info, Node: Search Path, Next: Once-Only Headers, Prev: Include Operation, Up: Header Files + +2.3 Search Path +=============== + +GCC looks in several different places for headers. On a normal Unix +system, if you do not instruct it otherwise, it will look for headers +requested with `#include ' in: + + /usr/local/include + LIBDIR/gcc/TARGET/VERSION/include + /usr/TARGET/include + /usr/include + + For C++ programs, it will also look in `/usr/include/g++-v3', first. +In the above, TARGET is the canonical name of the system GCC was +configured to compile code for; often but not always the same as the +canonical name of the system it runs on. VERSION is the version of GCC +in use. + + You can add to this list with the `-IDIR' command line option. All +the directories named by `-I' are searched, in left-to-right order, +_before_ the default directories. The only exception is when `dir' is +already searched by default. In this case, the option is ignored and +the search order for system directories remains unchanged. + + Duplicate directories are removed from the quote and bracket search +chains before the two chains are merged to make the final search chain. +Thus, it is possible for a directory to occur twice in the final search +chain if it was specified in both the quote and bracket chains. + + You can prevent GCC from searching any of the default directories +with the `-nostdinc' option. This is useful when you are compiling an +operating system kernel or some other program that does not use the +standard C library facilities, or the standard C library itself. `-I' +options are not ignored as described above when `-nostdinc' is in +effect. + + GCC looks for headers requested with `#include "FILE"' first in the +directory containing the current file, then in the directories as +specified by `-iquote' options, then in the same places it would have +looked for a header requested with angle brackets. For example, if +`/usr/include/sys/stat.h' contains `#include "types.h"', GCC looks for +`types.h' first in `/usr/include/sys', then in its usual search path. + + `#line' (*note Line Control::) does not change GCC's idea of the +directory containing the current file. + + You may put `-I-' at any point in your list of `-I' options. This +has two effects. First, directories appearing before the `-I-' in the +list are searched only for headers requested with quote marks. +Directories after `-I-' are searched for all headers. Second, the +directory containing the current file is not searched for anything, +unless it happens to be one of the directories named by an `-I' switch. +`-I-' is deprecated, `-iquote' should be used instead. + + `-I. -I-' is not the same as no `-I' options at all, and does not +cause the same behavior for `<>' includes that `""' includes get with +no special options. `-I.' searches the compiler's current working +directory for header files. That may or may not be the same as the +directory containing the current file. + + If you need to look for headers in a directory named `-', write +`-I./-'. + + There are several more ways to adjust the header search path. They +are generally less useful. *Note Invocation::. + + +File: cpp.info, Node: Once-Only Headers, Next: Alternatives to Wrapper #ifndef, Prev: Search Path, Up: Header Files + +2.4 Once-Only Headers +===================== + +If a header file happens to be included twice, the compiler will process +its contents twice. This is very likely to cause an error, e.g. when +the compiler sees the same structure definition twice. Even if it does +not, it will certainly waste time. + + The standard way to prevent this is to enclose the entire real +contents of the file in a conditional, like this: + + /* File foo. */ + #ifndef FILE_FOO_SEEN + #define FILE_FOO_SEEN + + THE ENTIRE FILE + + #endif /* !FILE_FOO_SEEN */ + + This construct is commonly known as a "wrapper #ifndef". When the +header is included again, the conditional will be false, because +`FILE_FOO_SEEN' is defined. The preprocessor will skip over the entire +contents of the file, and the compiler will not see it twice. + + CPP optimizes even further. It remembers when a header file has a +wrapper `#ifndef'. If a subsequent `#include' specifies that header, +and the macro in the `#ifndef' is still defined, it does not bother to +rescan the file at all. + + You can put comments outside the wrapper. They will not interfere +with this optimization. + + The macro `FILE_FOO_SEEN' is called the "controlling macro" or +"guard macro". In a user header file, the macro name should not begin +with `_'. In a system header file, it should begin with `__' to avoid +conflicts with user programs. In any kind of header file, the macro +name should contain the name of the file and some additional text, to +avoid conflicts with other header files. + + +File: cpp.info, Node: Alternatives to Wrapper #ifndef, Next: Computed Includes, Prev: Once-Only Headers, Up: Header Files + +2.5 Alternatives to Wrapper #ifndef +=================================== + +CPP supports two more ways of indicating that a header file should be +read only once. Neither one is as portable as a wrapper `#ifndef' and +we recommend you do not use them in new programs, with the caveat that +`#import' is standard practice in Objective-C. + + CPP supports a variant of `#include' called `#import' which includes +a file, but does so at most once. If you use `#import' instead of +`#include', then you don't need the conditionals inside the header file +to prevent multiple inclusion of the contents. `#import' is standard +in Objective-C, but is considered a deprecated extension in C and C++. + + `#import' is not a well designed feature. It requires the users of +a header file to know that it should only be included once. It is much +better for the header file's implementor to write the file so that users +don't need to know this. Using a wrapper `#ifndef' accomplishes this +goal. + + In the present implementation, a single use of `#import' will +prevent the file from ever being read again, by either `#import' or +`#include'. You should not rely on this; do not use both `#import' and +`#include' to refer to the same header file. + + Another way to prevent a header file from being included more than +once is with the `#pragma once' directive. If `#pragma once' is seen +when scanning a header file, that file will never be read again, no +matter what. + + `#pragma once' does not have the problems that `#import' does, but +it is not recognized by all preprocessors, so you cannot rely on it in +a portable program. + + +File: cpp.info, Node: Computed Includes, Next: Wrapper Headers, Prev: Alternatives to Wrapper #ifndef, Up: Header Files + +2.6 Computed Includes +===================== + +Sometimes it is necessary to select one of several different header +files to be included into your program. They might specify +configuration parameters to be used on different sorts of operating +systems, for instance. You could do this with a series of conditionals, + + #if SYSTEM_1 + # include "system_1.h" + #elif SYSTEM_2 + # include "system_2.h" + #elif SYSTEM_3 + ... + #endif + + That rapidly becomes tedious. Instead, the preprocessor offers the +ability to use a macro for the header name. This is called a "computed +include". Instead of writing a header name as the direct argument of +`#include', you simply put a macro name there instead: + + #define SYSTEM_H "system_1.h" + ... + #include SYSTEM_H + +`SYSTEM_H' will be expanded, and the preprocessor will look for +`system_1.h' as if the `#include' had been written that way originally. +`SYSTEM_H' could be defined by your Makefile with a `-D' option. + + You must be careful when you define the macro. `#define' saves +tokens, not text. The preprocessor has no way of knowing that the macro +will be used as the argument of `#include', so it generates ordinary +tokens, not a header name. This is unlikely to cause problems if you +use double-quote includes, which are close enough to string constants. +If you use angle brackets, however, you may have trouble. + + The syntax of a computed include is actually a bit more general than +the above. If the first non-whitespace character after `#include' is +not `"' or `<', then the entire line is macro-expanded like running +text would be. + + If the line expands to a single string constant, the contents of that +string constant are the file to be included. CPP does not re-examine +the string for embedded quotes, but neither does it process backslash +escapes in the string. Therefore + + #define HEADER "a\"b" + #include HEADER + +looks for a file named `a\"b'. CPP searches for the file according to +the rules for double-quoted includes. + + If the line expands to a token stream beginning with a `<' token and +including a `>' token, then the tokens between the `<' and the first +`>' are combined to form the filename to be included. Any whitespace +between tokens is reduced to a single space; then any space after the +initial `<' is retained, but a trailing space before the closing `>' is +ignored. CPP searches for the file according to the rules for +angle-bracket includes. + + In either case, if there are any tokens on the line after the file +name, an error occurs and the directive is not processed. It is also +an error if the result of expansion does not match either of the two +expected forms. + + These rules are implementation-defined behavior according to the C +standard. To minimize the risk of different compilers interpreting your +computed includes differently, we recommend you use only a single +object-like macro which expands to a string constant. This will also +minimize confusion for people reading your program. + + +File: cpp.info, Node: Wrapper Headers, Next: System Headers, Prev: Computed Includes, Up: Header Files + +2.7 Wrapper Headers +=================== + +Sometimes it is necessary to adjust the contents of a system-provided +header file without editing it directly. GCC's `fixincludes' operation +does this, for example. One way to do that would be to create a new +header file with the same name and insert it in the search path before +the original header. That works fine as long as you're willing to +replace the old header entirely. But what if you want to refer to the +old header from the new one? + + You cannot simply include the old header with `#include'. That will +start from the beginning, and find your new header again. If your +header is not protected from multiple inclusion (*note Once-Only +Headers::), it will recurse infinitely and cause a fatal error. + + You could include the old header with an absolute pathname: + #include "/usr/include/old-header.h" + This works, but is not clean; should the system headers ever move, +you would have to edit the new headers to match. + + There is no way to solve this problem within the C standard, but you +can use the GNU extension `#include_next'. It means, "Include the +_next_ file with this name". This directive works like `#include' +except in searching for the specified file: it starts searching the +list of header file directories _after_ the directory in which the +current file was found. + + Suppose you specify `-I /usr/local/include', and the list of +directories to search also includes `/usr/include'; and suppose both +directories contain `signal.h'. Ordinary `#include ' finds +the file under `/usr/local/include'. If that file contains +`#include_next ', it starts searching after that directory, +and finds the file in `/usr/include'. + + `#include_next' does not distinguish between `' and `"FILE"' +inclusion, nor does it check that the file you specify has the same +name as the current file. It simply looks for the file named, starting +with the directory in the search path after the one where the current +file was found. + + The use of `#include_next' can lead to great confusion. We +recommend it be used only when there is no other alternative. In +particular, it should not be used in the headers belonging to a specific +program; it should be used only to make global corrections along the +lines of `fixincludes'. + + +File: cpp.info, Node: System Headers, Prev: Wrapper Headers, Up: Header Files + +2.8 System Headers +================== + +The header files declaring interfaces to the operating system and +runtime libraries often cannot be written in strictly conforming C. +Therefore, GCC gives code found in "system headers" special treatment. +All warnings, other than those generated by `#warning' (*note +Diagnostics::), are suppressed while GCC is processing a system header. +Macros defined in a system header are immune to a few warnings wherever +they are expanded. This immunity is granted on an ad-hoc basis, when +we find that a warning generates lots of false positives because of +code in macros defined in system headers. + + Normally, only the headers found in specific directories are +considered system headers. These directories are determined when GCC +is compiled. There are, however, two ways to make normal headers into +system headers. + + The `-isystem' command line option adds its argument to the list of +directories to search for headers, just like `-I'. Any headers found +in that directory will be considered system headers. + + All directories named by `-isystem' are searched _after_ all +directories named by `-I', no matter what their order was on the +command line. If the same directory is named by both `-I' and +`-isystem', the `-I' option is ignored. GCC provides an informative +message when this occurs if `-v' is used. + + There is also a directive, `#pragma GCC system_header', which tells +GCC to consider the rest of the current include file a system header, +no matter where it was found. Code that comes before the `#pragma' in +the file will not be affected. `#pragma GCC system_header' has no +effect in the primary source file. + + On very old systems, some of the pre-defined system header +directories get even more special treatment. GNU C++ considers code in +headers found in those directories to be surrounded by an `extern "C"' +block. There is no way to request this behavior with a `#pragma', or +from the command line. + + +File: cpp.info, Node: Macros, Next: Conditionals, Prev: Header Files, Up: Top + +3 Macros +******** + +A "macro" is a fragment of code which has been given a name. Whenever +the name is used, it is replaced by the contents of the macro. There +are two kinds of macros. They differ mostly in what they look like +when they are used. "Object-like" macros resemble data objects when +used, "function-like" macros resemble function calls. + + You may define any valid identifier as a macro, even if it is a C +keyword. The preprocessor does not know anything about keywords. This +can be useful if you wish to hide a keyword such as `const' from an +older compiler that does not understand it. However, the preprocessor +operator `defined' (*note Defined::) can never be defined as a macro, +and C++'s named operators (*note C++ Named Operators::) cannot be +macros when you are compiling C++. + +* Menu: + +* Object-like Macros:: +* Function-like Macros:: +* Macro Arguments:: +* Stringification:: +* Concatenation:: +* Variadic Macros:: +* Predefined Macros:: +* Undefining and Redefining Macros:: +* Directives Within Macro Arguments:: +* Macro Pitfalls:: + + +File: cpp.info, Node: Object-like Macros, Next: Function-like Macros, Up: Macros + +3.1 Object-like Macros +====================== + +An "object-like macro" is a simple identifier which will be replaced by +a code fragment. It is called object-like because it looks like a data +object in code that uses it. They are most commonly used to give +symbolic names to numeric constants. + + You create macros with the `#define' directive. `#define' is +followed by the name of the macro and then the token sequence it should +be an abbreviation for, which is variously referred to as the macro's +"body", "expansion" or "replacement list". For example, + + #define BUFFER_SIZE 1024 + +defines a macro named `BUFFER_SIZE' as an abbreviation for the token +`1024'. If somewhere after this `#define' directive there comes a C +statement of the form + + foo = (char *) malloc (BUFFER_SIZE); + +then the C preprocessor will recognize and "expand" the macro +`BUFFER_SIZE'. The C compiler will see the same tokens as it would if +you had written + + foo = (char *) malloc (1024); + + By convention, macro names are written in uppercase. Programs are +easier to read when it is possible to tell at a glance which names are +macros. + + The macro's body ends at the end of the `#define' line. You may +continue the definition onto multiple lines, if necessary, using +backslash-newline. When the macro is expanded, however, it will all +come out on one line. For example, + + #define NUMBERS 1, \ + 2, \ + 3 + int x[] = { NUMBERS }; + ==> int x[] = { 1, 2, 3 }; + +The most common visible consequence of this is surprising line numbers +in error messages. + + There is no restriction on what can go in a macro body provided it +decomposes into valid preprocessing tokens. Parentheses need not +balance, and the body need not resemble valid C code. (If it does not, +you may get error messages from the C compiler when you use the macro.) + + The C preprocessor scans your program sequentially. Macro +definitions take effect at the place you write them. Therefore, the +following input to the C preprocessor + + foo = X; + #define X 4 + bar = X; + +produces + + foo = X; + bar = 4; + + When the preprocessor expands a macro name, the macro's expansion +replaces the macro invocation, then the expansion is examined for more +macros to expand. For example, + + #define TABLESIZE BUFSIZE + #define BUFSIZE 1024 + TABLESIZE + ==> BUFSIZE + ==> 1024 + +`TABLESIZE' is expanded first to produce `BUFSIZE', then that macro is +expanded to produce the final result, `1024'. + + Notice that `BUFSIZE' was not defined when `TABLESIZE' was defined. +The `#define' for `TABLESIZE' uses exactly the expansion you +specify--in this case, `BUFSIZE'--and does not check to see whether it +too contains macro names. Only when you _use_ `TABLESIZE' is the +result of its expansion scanned for more macro names. + + This makes a difference if you change the definition of `BUFSIZE' at +some point in the source file. `TABLESIZE', defined as shown, will +always expand using the definition of `BUFSIZE' that is currently in +effect: + + #define BUFSIZE 1020 + #define TABLESIZE BUFSIZE + #undef BUFSIZE + #define BUFSIZE 37 + +Now `TABLESIZE' expands (in two stages) to `37'. + + If the expansion of a macro contains its own name, either directly or +via intermediate macros, it is not expanded again when the expansion is +examined for more macros. This prevents infinite recursion. *Note +Self-Referential Macros::, for the precise details. + + +File: cpp.info, Node: Function-like Macros, Next: Macro Arguments, Prev: Object-like Macros, Up: Macros + +3.2 Function-like Macros +======================== + +You can also define macros whose use looks like a function call. These +are called "function-like macros". To define a function-like macro, +you use the same `#define' directive, but you put a pair of parentheses +immediately after the macro name. For example, + + #define lang_init() c_init() + lang_init() + ==> c_init() + + A function-like macro is only expanded if its name appears with a +pair of parentheses after it. If you write just the name, it is left +alone. This can be useful when you have a function and a macro of the +same name, and you wish to use the function sometimes. + + extern void foo(void); + #define foo() /* optimized inline version */ + ... + foo(); + funcptr = foo; + + Here the call to `foo()' will use the macro, but the function +pointer will get the address of the real function. If the macro were to +be expanded, it would cause a syntax error. + + If you put spaces between the macro name and the parentheses in the +macro definition, that does not define a function-like macro, it defines +an object-like macro whose expansion happens to begin with a pair of +parentheses. + + #define lang_init () c_init() + lang_init() + ==> () c_init()() + + The first two pairs of parentheses in this expansion come from the +macro. The third is the pair that was originally after the macro +invocation. Since `lang_init' is an object-like macro, it does not +consume those parentheses. + + +File: cpp.info, Node: Macro Arguments, Next: Stringification, Prev: Function-like Macros, Up: Macros + +3.3 Macro Arguments +=================== + +Function-like macros can take "arguments", just like true functions. +To define a macro that uses arguments, you insert "parameters" between +the pair of parentheses in the macro definition that make the macro +function-like. The parameters must be valid C identifiers, separated +by commas and optionally whitespace. + + To invoke a macro that takes arguments, you write the name of the +macro followed by a list of "actual arguments" in parentheses, separated +by commas. The invocation of the macro need not be restricted to a +single logical line--it can cross as many lines in the source file as +you wish. The number of arguments you give must match the number of +parameters in the macro definition. When the macro is expanded, each +use of a parameter in its body is replaced by the tokens of the +corresponding argument. (You need not use all of the parameters in the +macro body.) + + As an example, here is a macro that computes the minimum of two +numeric values, as it is defined in many C programs, and some uses. + + #define min(X, Y) ((X) < (Y) ? (X) : (Y)) + x = min(a, b); ==> x = ((a) < (b) ? (a) : (b)); + y = min(1, 2); ==> y = ((1) < (2) ? (1) : (2)); + z = min(a + 28, *p); ==> z = ((a + 28) < (*p) ? (a + 28) : (*p)); + +(In this small example you can already see several of the dangers of +macro arguments. *Note Macro Pitfalls::, for detailed explanations.) + + Leading and trailing whitespace in each argument is dropped, and all +whitespace between the tokens of an argument is reduced to a single +space. Parentheses within each argument must balance; a comma within +such parentheses does not end the argument. However, there is no +requirement for square brackets or braces to balance, and they do not +prevent a comma from separating arguments. Thus, + + macro (array[x = y, x + 1]) + +passes two arguments to `macro': `array[x = y' and `x + 1]'. If you +want to supply `array[x = y, x + 1]' as an argument, you can write it +as `array[(x = y, x + 1)]', which is equivalent C code. + + All arguments to a macro are completely macro-expanded before they +are substituted into the macro body. After substitution, the complete +text is scanned again for macros to expand, including the arguments. +This rule may seem strange, but it is carefully designed so you need +not worry about whether any function call is actually a macro +invocation. You can run into trouble if you try to be too clever, +though. *Note Argument Prescan::, for detailed discussion. + + For example, `min (min (a, b), c)' is first expanded to + + min (((a) < (b) ? (a) : (b)), (c)) + +and then to + + ((((a) < (b) ? (a) : (b))) < (c) + ? (((a) < (b) ? (a) : (b))) + : (c)) + +(Line breaks shown here for clarity would not actually be generated.) + + You can leave macro arguments empty; this is not an error to the +preprocessor (but many macros will then expand to invalid code). You +cannot leave out arguments entirely; if a macro takes two arguments, +there must be exactly one comma at the top level of its argument list. +Here are some silly examples using `min': + + min(, b) ==> (( ) < (b) ? ( ) : (b)) + min(a, ) ==> ((a ) < ( ) ? (a ) : ( )) + min(,) ==> (( ) < ( ) ? ( ) : ( )) + min((,),) ==> (((,)) < ( ) ? ((,)) : ( )) + + min() error--> macro "min" requires 2 arguments, but only 1 given + min(,,) error--> macro "min" passed 3 arguments, but takes just 2 + + Whitespace is not a preprocessing token, so if a macro `foo' takes +one argument, `foo ()' and `foo ( )' both supply it an empty argument. +Previous GNU preprocessor implementations and documentation were +incorrect on this point, insisting that a function-like macro that +takes a single argument be passed a space if an empty argument was +required. + + Macro parameters appearing inside string literals are not replaced by +their corresponding actual arguments. + + #define foo(x) x, "x" + foo(bar) ==> bar, "x" + + +File: cpp.info, Node: Stringification, Next: Concatenation, Prev: Macro Arguments, Up: Macros + +3.4 Stringification +=================== + +Sometimes you may want to convert a macro argument into a string +constant. Parameters are not replaced inside string constants, but you +can use the `#' preprocessing operator instead. When a macro parameter +is used with a leading `#', the preprocessor replaces it with the +literal text of the actual argument, converted to a string constant. +Unlike normal parameter replacement, the argument is not macro-expanded +first. This is called "stringification". + + There is no way to combine an argument with surrounding text and +stringify it all together. Instead, you can write a series of adjacent +string constants and stringified arguments. The preprocessor will +replace the stringified arguments with string constants. The C +compiler will then combine all the adjacent string constants into one +long string. + + Here is an example of a macro definition that uses stringification: + + #define WARN_IF(EXP) \ + do { if (EXP) \ + fprintf (stderr, "Warning: " #EXP "\n"); } \ + while (0) + WARN_IF (x == 0); + ==> do { if (x == 0) + fprintf (stderr, "Warning: " "x == 0" "\n"); } while (0); + +The argument for `EXP' is substituted once, as-is, into the `if' +statement, and once, stringified, into the argument to `fprintf'. If +`x' were a macro, it would be expanded in the `if' statement, but not +in the string. + + The `do' and `while (0)' are a kludge to make it possible to write +`WARN_IF (ARG);', which the resemblance of `WARN_IF' to a function +would make C programmers want to do; see *note Swallowing the +Semicolon::. + + Stringification in C involves more than putting double-quote +characters around the fragment. The preprocessor backslash-escapes the +quotes surrounding embedded string constants, and all backslashes +within string and character constants, in order to get a valid C string +constant with the proper contents. Thus, stringifying `p = "foo\n";' +results in "p = \"foo\\n\";". However, backslashes that are not inside +string or character constants are not duplicated: `\n' by itself +stringifies to "\n". + + All leading and trailing whitespace in text being stringified is +ignored. Any sequence of whitespace in the middle of the text is +converted to a single space in the stringified result. Comments are +replaced by whitespace long before stringification happens, so they +never appear in stringified text. + + There is no way to convert a macro argument into a character +constant. + + If you want to stringify the result of expansion of a macro argument, +you have to use two levels of macros. + + #define xstr(s) str(s) + #define str(s) #s + #define foo 4 + str (foo) + ==> "foo" + xstr (foo) + ==> xstr (4) + ==> str (4) + ==> "4" + + `s' is stringified when it is used in `str', so it is not +macro-expanded first. But `s' is an ordinary argument to `xstr', so it +is completely macro-expanded before `xstr' itself is expanded (*note +Argument Prescan::). Therefore, by the time `str' gets to its +argument, it has already been macro-expanded. + + +File: cpp.info, Node: Concatenation, Next: Variadic Macros, Prev: Stringification, Up: Macros + +3.5 Concatenation +================= + +It is often useful to merge two tokens into one while expanding macros. +This is called "token pasting" or "token concatenation". The `##' +preprocessing operator performs token pasting. When a macro is +expanded, the two tokens on either side of each `##' operator are +combined into a single token, which then replaces the `##' and the two +original tokens in the macro expansion. Usually both will be +identifiers, or one will be an identifier and the other a preprocessing +number. When pasted, they make a longer identifier. This isn't the +only valid case. It is also possible to concatenate two numbers (or a +number and a name, such as `1.5' and `e3') into a number. Also, +multi-character operators such as `+=' can be formed by token pasting. + + However, two tokens that don't together form a valid token cannot be +pasted together. For example, you cannot concatenate `x' with `+' in +either order. If you try, the preprocessor issues a warning and emits +the two tokens. Whether it puts white space between the tokens is +undefined. It is common to find unnecessary uses of `##' in complex +macros. If you get this warning, it is likely that you can simply +remove the `##'. + + Both the tokens combined by `##' could come from the macro body, but +you could just as well write them as one token in the first place. +Token pasting is most useful when one or both of the tokens comes from a +macro argument. If either of the tokens next to an `##' is a parameter +name, it is replaced by its actual argument before `##' executes. As +with stringification, the actual argument is not macro-expanded first. +If the argument is empty, that `##' has no effect. + + Keep in mind that the C preprocessor converts comments to whitespace +before macros are even considered. Therefore, you cannot create a +comment by concatenating `/' and `*'. You can put as much whitespace +between `##' and its operands as you like, including comments, and you +can put comments in arguments that will be concatenated. However, it +is an error if `##' appears at either end of a macro body. + + Consider a C program that interprets named commands. There probably +needs to be a table of commands, perhaps an array of structures declared +as follows: + + struct command + { + char *name; + void (*function) (void); + }; + + struct command commands[] = + { + { "quit", quit_command }, + { "help", help_command }, + ... + }; + + It would be cleaner not to have to give each command name twice, +once in the string constant and once in the function name. A macro +which takes the name of a command as an argument can make this +unnecessary. The string constant can be created with stringification, +and the function name by concatenating the argument with `_command'. +Here is how it is done: + + #define COMMAND(NAME) { #NAME, NAME ## _command } + + struct command commands[] = + { + COMMAND (quit), + COMMAND (help), + ... + }; + + +File: cpp.info, Node: Variadic Macros, Next: Predefined Macros, Prev: Concatenation, Up: Macros + +3.6 Variadic Macros +=================== + +A macro can be declared to accept a variable number of arguments much as +a function can. The syntax for defining the macro is similar to that of +a function. Here is an example: + + #define eprintf(...) fprintf (stderr, __VA_ARGS__) + + This kind of macro is called "variadic". When the macro is invoked, +all the tokens in its argument list after the last named argument (this +macro has none), including any commas, become the "variable argument". +This sequence of tokens replaces the identifier `__VA_ARGS__' in the +macro body wherever it appears. Thus, we have this expansion: + + eprintf ("%s:%d: ", input_file, lineno) + ==> fprintf (stderr, "%s:%d: ", input_file, lineno) + + The variable argument is completely macro-expanded before it is +inserted into the macro expansion, just like an ordinary argument. You +may use the `#' and `##' operators to stringify the variable argument +or to paste its leading or trailing token with another token. (But see +below for an important special case for `##'.) + + If your macro is complicated, you may want a more descriptive name +for the variable argument than `__VA_ARGS__'. CPP permits this, as an +extension. You may write an argument name immediately before the +`...'; that name is used for the variable argument. The `eprintf' +macro above could be written + + #define eprintf(args...) fprintf (stderr, args) + +using this extension. You cannot use `__VA_ARGS__' and this extension +in the same macro. + + You can have named arguments as well as variable arguments in a +variadic macro. We could define `eprintf' like this, instead: + + #define eprintf(format, ...) fprintf (stderr, format, __VA_ARGS__) + +This formulation looks more descriptive, but unfortunately it is less +flexible: you must now supply at least one argument after the format +string. In standard C, you cannot omit the comma separating the named +argument from the variable arguments. Furthermore, if you leave the +variable argument empty, you will get a syntax error, because there +will be an extra comma after the format string. + + eprintf("success!\n", ); + ==> fprintf(stderr, "success!\n", ); + + GNU CPP has a pair of extensions which deal with this problem. +First, you are allowed to leave the variable argument out entirely: + + eprintf ("success!\n") + ==> fprintf(stderr, "success!\n", ); + +Second, the `##' token paste operator has a special meaning when placed +between a comma and a variable argument. If you write + + #define eprintf(format, ...) fprintf (stderr, format, ##__VA_ARGS__) + +and the variable argument is left out when the `eprintf' macro is used, +then the comma before the `##' will be deleted. This does _not_ happen +if you pass an empty argument, nor does it happen if the token +preceding `##' is anything other than a comma. + + eprintf ("success!\n") + ==> fprintf(stderr, "success!\n"); + +The above explanation is ambiguous about the case where the only macro +parameter is a variable arguments parameter, as it is meaningless to +try to distinguish whether no argument at all is an empty argument or a +missing argument. In this case the C99 standard is clear that the +comma must remain, however the existing GCC extension used to swallow +the comma. So CPP retains the comma when conforming to a specific C +standard, and drops it otherwise. + + C99 mandates that the only place the identifier `__VA_ARGS__' can +appear is in the replacement list of a variadic macro. It may not be +used as a macro name, macro argument name, or within a different type +of macro. It may also be forbidden in open text; the standard is +ambiguous. We recommend you avoid using it except for its defined +purpose. + + Variadic macros are a new feature in C99. GNU CPP has supported them +for a long time, but only with a named variable argument (`args...', +not `...' and `__VA_ARGS__'). If you are concerned with portability to +previous versions of GCC, you should use only named variable arguments. +On the other hand, if you are concerned with portability to other +conforming implementations of C99, you should use only `__VA_ARGS__'. + + Previous versions of CPP implemented the comma-deletion extension +much more generally. We have restricted it in this release to minimize +the differences from C99. To get the same effect with both this and +previous versions of GCC, the token preceding the special `##' must be +a comma, and there must be white space between that comma and whatever +comes immediately before it: + + #define eprintf(format, args...) fprintf (stderr, format , ##args) + +*Note Differences from previous versions::, for the gory details. + + +File: cpp.info, Node: Predefined Macros, Next: Undefining and Redefining Macros, Prev: Variadic Macros, Up: Macros + +3.7 Predefined Macros +===================== + +Several object-like macros are predefined; you use them without +supplying their definitions. They fall into three classes: standard, +common, and system-specific. + + In C++, there is a fourth category, the named operators. They act +like predefined macros, but you cannot undefine them. + +* Menu: + +* Standard Predefined Macros:: +* Common Predefined Macros:: +* System-specific Predefined Macros:: +* C++ Named Operators:: + + +File: cpp.info, Node: Standard Predefined Macros, Next: Common Predefined Macros, Up: Predefined Macros + +3.7.1 Standard Predefined Macros +-------------------------------- + +The standard predefined macros are specified by the relevant language +standards, so they are available with all compilers that implement +those standards. Older compilers may not provide all of them. Their +names all start with double underscores. + +`__FILE__' + This macro expands to the name of the current input file, in the + form of a C string constant. This is the path by which the + preprocessor opened the file, not the short name specified in + `#include' or as the input file name argument. For example, + `"/usr/local/include/myheader.h"' is a possible expansion of this + macro. + +`__LINE__' + This macro expands to the current input line number, in the form + of a decimal integer constant. While we call it a predefined + macro, it's a pretty strange macro, since its "definition" changes + with each new line of source code. + + `__FILE__' and `__LINE__' are useful in generating an error message +to report an inconsistency detected by the program; the message can +state the source line at which the inconsistency was detected. For +example, + + fprintf (stderr, "Internal error: " + "negative string length " + "%d at %s, line %d.", + length, __FILE__, __LINE__); + + An `#include' directive changes the expansions of `__FILE__' and +`__LINE__' to correspond to the included file. At the end of that +file, when processing resumes on the input file that contained the +`#include' directive, the expansions of `__FILE__' and `__LINE__' +revert to the values they had before the `#include' (but `__LINE__' is +then incremented by one as processing moves to the line after the +`#include'). + + A `#line' directive changes `__LINE__', and may change `__FILE__' as +well. *Note Line Control::. + + C99 introduces `__func__', and GCC has provided `__FUNCTION__' for a +long time. Both of these are strings containing the name of the +current function (there are slight semantic differences; see the GCC +manual). Neither of them is a macro; the preprocessor does not know the +name of the current function. They tend to be useful in conjunction +with `__FILE__' and `__LINE__', though. + +`__DATE__' + This macro expands to a string constant that describes the date on + which the preprocessor is being run. The string constant contains + eleven characters and looks like `"Feb 12 1996"'. If the day of + the month is less than 10, it is padded with a space on the left. + + If GCC cannot determine the current date, it will emit a warning + message (once per compilation) and `__DATE__' will expand to + `"??? ?? ????"'. + +`__TIME__' + This macro expands to a string constant that describes the time at + which the preprocessor is being run. The string constant contains + eight characters and looks like `"23:59:01"'. + + If GCC cannot determine the current time, it will emit a warning + message (once per compilation) and `__TIME__' will expand to + `"??:??:??"'. + +`__STDC__' + In normal operation, this macro expands to the constant 1, to + signify that this compiler conforms to ISO Standard C. If GNU CPP + is used with a compiler other than GCC, this is not necessarily + true; however, the preprocessor always conforms to the standard + unless the `-traditional-cpp' option is used. + + This macro is not defined if the `-traditional-cpp' option is used. + + On some hosts, the system compiler uses a different convention, + where `__STDC__' is normally 0, but is 1 if the user specifies + strict conformance to the C Standard. CPP follows the host + convention when processing system header files, but when + processing user files `__STDC__' is always 1. This has been + reported to cause problems; for instance, some versions of Solaris + provide X Windows headers that expect `__STDC__' to be either + undefined or 1. *Note Invocation::. + +`__STDC_VERSION__' + This macro expands to the C Standard's version number, a long + integer constant of the form `YYYYMML' where YYYY and MM are the + year and month of the Standard version. This signifies which + version of the C Standard the compiler conforms to. Like + `__STDC__', this is not necessarily accurate for the entire + implementation, unless GNU CPP is being used with GCC. + + The value `199409L' signifies the 1989 C standard as amended in + 1994, which is the current default; the value `199901L' signifies + the 1999 revision of the C standard. Support for the 1999 + revision is not yet complete. + + This macro is not defined if the `-traditional-cpp' option is + used, nor when compiling C++ or Objective-C. + +`__STDC_HOSTED__' + This macro is defined, with value 1, if the compiler's target is a + "hosted environment". A hosted environment has the complete + facilities of the standard C library available. + +`__cplusplus' + This macro is defined when the C++ compiler is in use. You can use + `__cplusplus' to test whether a header is compiled by a C compiler + or a C++ compiler. This macro is similar to `__STDC_VERSION__', in + that it expands to a version number. A fully conforming + implementation of the 1998 C++ standard will define this macro to + `199711L'. The GNU C++ compiler is not yet fully conforming, so + it uses `1' instead. It is hoped to complete the implementation + of standard C++ in the near future. + +`__OBJC__' + This macro is defined, with value 1, when the Objective-C compiler + is in use. You can use `__OBJC__' to test whether a header is + compiled by a C compiler or an Objective-C compiler. + +`__ASSEMBLER__' + This macro is defined with value 1 when preprocessing assembly + language. + + + +File: cpp.info, Node: Common Predefined Macros, Next: System-specific Predefined Macros, Prev: Standard Predefined Macros, Up: Predefined Macros + +3.7.2 Common Predefined Macros +------------------------------ + +The common predefined macros are GNU C extensions. They are available +with the same meanings regardless of the machine or operating system on +which you are using GNU C or GNU Fortran. Their names all start with +double underscores. + +`__COUNTER__' + This macro expands to sequential integral values starting from 0. + In conjunction with the `##' operator, this provides a convenient + means to generate unique identifiers. Care must be taken to + ensure that `__COUNTER__' is not expanded prior to inclusion of + precompiled headers which use it. Otherwise, the precompiled + headers will not be used. + +`__GFORTRAN__' + The GNU Fortran compiler defines this. + +`__GNUC__' +`__GNUC_MINOR__' +`__GNUC_PATCHLEVEL__' + These macros are defined by all GNU compilers that use the C + preprocessor: C, C++, Objective-C and Fortran. Their values are + the major version, minor version, and patch level of the compiler, + as integer constants. For example, GCC 3.2.1 will define + `__GNUC__' to 3, `__GNUC_MINOR__' to 2, and `__GNUC_PATCHLEVEL__' + to 1. These macros are also defined if you invoke the + preprocessor directly. + + `__GNUC_PATCHLEVEL__' is new to GCC 3.0; it is also present in the + widely-used development snapshots leading up to 3.0 (which identify + themselves as GCC 2.96 or 2.97, depending on which snapshot you + have). + + If all you need to know is whether or not your program is being + compiled by GCC, or a non-GCC compiler that claims to accept the + GNU C dialects, you can simply test `__GNUC__'. If you need to + write code which depends on a specific version, you must be more + careful. Each time the minor version is increased, the patch + level is reset to zero; each time the major version is increased + (which happens rarely), the minor version and patch level are + reset. If you wish to use the predefined macros directly in the + conditional, you will need to write it like this: + + /* Test for GCC > 3.2.0 */ + #if __GNUC__ > 3 || \ + (__GNUC__ == 3 && (__GNUC_MINOR__ > 2 || \ + (__GNUC_MINOR__ == 2 && \ + __GNUC_PATCHLEVEL__ > 0)) + + Another approach is to use the predefined macros to calculate a + single number, then compare that against a threshold: + + #define GCC_VERSION (__GNUC__ * 10000 \ + + __GNUC_MINOR__ * 100 \ + + __GNUC_PATCHLEVEL__) + ... + /* Test for GCC > 3.2.0 */ + #if GCC_VERSION > 30200 + + Many people find this form easier to understand. + +`__GNUG__' + The GNU C++ compiler defines this. Testing it is equivalent to + testing `(__GNUC__ && __cplusplus)'. + +`__STRICT_ANSI__' + GCC defines this macro if and only if the `-ansi' switch, or a + `-std' switch specifying strict conformance to some version of ISO + C, was specified when GCC was invoked. It is defined to `1'. + This macro exists primarily to direct GNU libc's header files to + restrict their definitions to the minimal set found in the 1989 C + standard. + +`__BASE_FILE__' + This macro expands to the name of the main input file, in the form + of a C string constant. This is the source file that was specified + on the command line of the preprocessor or C compiler. + +`__INCLUDE_LEVEL__' + This macro expands to a decimal integer constant that represents + the depth of nesting in include files. The value of this macro is + incremented on every `#include' directive and decremented at the + end of every included file. It starts out at 0, its value within + the base file specified on the command line. + +`__ELF__' + This macro is defined if the target uses the ELF object format. + +`__VERSION__' + This macro expands to a string constant which describes the + version of the compiler in use. You should not rely on its + contents having any particular form, but it can be counted on to + contain at least the release number. + +`__OPTIMIZE__' +`__OPTIMIZE_SIZE__' +`__NO_INLINE__' + These macros describe the compilation mode. `__OPTIMIZE__' is + defined in all optimizing compilations. `__OPTIMIZE_SIZE__' is + defined if the compiler is optimizing for size, not speed. + `__NO_INLINE__' is defined if no functions will be inlined into + their callers (when not optimizing, or when inlining has been + specifically disabled by `-fno-inline'). + + These macros cause certain GNU header files to provide optimized + definitions, using macros or inline functions, of system library + functions. You should not use these macros in any way unless you + make sure that programs will execute with the same effect whether + or not they are defined. If they are defined, their value is 1. + +`__GNUC_GNU_INLINE__' + GCC defines this macro if functions declared `inline' will be + handled in GCC's traditional gnu90 mode. Object files will contain + externally visible definitions of all functions declared `inline' + without `extern' or `static'. They will not contain any + definitions of any functions declared `extern inline'. + +`__GNUC_STDC_INLINE__' + GCC defines this macro if functions declared `inline' will be + handled according to the ISO C99 standard. Object files will + contain externally visible definitions of all functions declared + `extern inline'. They will not contain definitions of any + functions declared `inline' without `extern'. + + If this macro is defined, GCC supports the `gnu_inline' function + attribute as a way to always get the gnu90 behavior. Support for + this and `__GNUC_GNU_INLINE__' was added in GCC 4.1.3. If neither + macro is defined, an older version of GCC is being used: `inline' + functions will be compiled in gnu90 mode, and the `gnu_inline' + function attribute will not be recognized. + +`__CHAR_UNSIGNED__' + GCC defines this macro if and only if the data type `char' is + unsigned on the target machine. It exists to cause the standard + header file `limits.h' to work correctly. You should not use this + macro yourself; instead, refer to the standard macros defined in + `limits.h'. + +`__WCHAR_UNSIGNED__' + Like `__CHAR_UNSIGNED__', this macro is defined if and only if the + data type `wchar_t' is unsigned and the front-end is in C++ mode. + +`__REGISTER_PREFIX__' + This macro expands to a single token (not a string constant) which + is the prefix applied to CPU register names in assembly language + for this target. You can use it to write assembly that is usable + in multiple environments. For example, in the `m68k-aout' + environment it expands to nothing, but in the `m68k-coff' + environment it expands to a single `%'. + +`__USER_LABEL_PREFIX__' + This macro expands to a single token which is the prefix applied to + user labels (symbols visible to C code) in assembly. For example, + in the `m68k-aout' environment it expands to an `_', but in the + `m68k-coff' environment it expands to nothing. + + This macro will have the correct definition even if + `-f(no-)underscores' is in use, but it will not be correct if + target-specific options that adjust this prefix are used (e.g. the + OSF/rose `-mno-underscores' option). + +`__SIZE_TYPE__' +`__PTRDIFF_TYPE__' +`__WCHAR_TYPE__' +`__WINT_TYPE__' +`__INTMAX_TYPE__' +`__UINTMAX_TYPE__' +`__SIG_ATOMIC_TYPE__' +`__INT8_TYPE__' +`__INT16_TYPE__' +`__INT32_TYPE__' +`__INT64_TYPE__' +`__UINT8_TYPE__' +`__UINT16_TYPE__' +`__UINT32_TYPE__' +`__UINT64_TYPE__' +`__INT_LEAST8_TYPE__' +`__INT_LEAST16_TYPE__' +`__INT_LEAST32_TYPE__' +`__INT_LEAST64_TYPE__' +`__UINT_LEAST8_TYPE__' +`__UINT_LEAST16_TYPE__' +`__UINT_LEAST32_TYPE__' +`__UINT_LEAST64_TYPE__' +`__INT_FAST8_TYPE__' +`__INT_FAST16_TYPE__' +`__INT_FAST32_TYPE__' +`__INT_FAST64_TYPE__' +`__UINT_FAST8_TYPE__' +`__UINT_FAST16_TYPE__' +`__UINT_FAST32_TYPE__' +`__UINT_FAST64_TYPE__' +`__INTPTR_TYPE__' +`__UINTPTR_TYPE__' + These macros are defined to the correct underlying types for the + `size_t', `ptrdiff_t', `wchar_t', `wint_t', `intmax_t', + `uintmax_t', `sig_atomic_t', `int8_t', `int16_t', `int32_t', + `int64_t', `uint8_t', `uint16_t', `uint32_t', `uint64_t', + `int_least8_t', `int_least16_t', `int_least32_t', `int_least64_t', + `uint_least8_t', `uint_least16_t', `uint_least32_t', + `uint_least64_t', `int_fast8_t', `int_fast16_t', `int_fast32_t', + `int_fast64_t', `uint_fast8_t', `uint_fast16_t', `uint_fast32_t', + `uint_fast64_t', `intptr_t', and `uintptr_t' typedefs, + respectively. They exist to make the standard header files + `stddef.h', `stdint.h', and `wchar.h' work correctly. You should + not use these macros directly; instead, include the appropriate + headers and use the typedefs. Some of these macros may not be + defined on particular systems if GCC does not provide a `stdint.h' + header on those systems. + +`__CHAR_BIT__' + Defined to the number of bits used in the representation of the + `char' data type. It exists to make the standard header given + numerical limits work correctly. You should not use this macro + directly; instead, include the appropriate headers. + +`__SCHAR_MAX__' +`__WCHAR_MAX__' +`__SHRT_MAX__' +`__INT_MAX__' +`__LONG_MAX__' +`__LONG_LONG_MAX__' +`__WINT_MAX__' +`__SIZE_MAX__' +`__PTRDIFF_MAX__' +`__INTMAX_MAX__' +`__UINTMAX_MAX__' +`__SIG_ATOMIC_MAX__' +`__INT8_MAX__' +`__INT16_MAX__' +`__INT32_MAX__' +`__INT64_MAX__' +`__UINT8_MAX__' +`__UINT16_MAX__' +`__UINT32_MAX__' +`__UINT64_MAX__' +`__INT_LEAST8_MAX__' +`__INT_LEAST16_MAX__' +`__INT_LEAST32_MAX__' +`__INT_LEAST64_MAX__' +`__UINT_LEAST8_MAX__' +`__UINT_LEAST16_MAX__' +`__UINT_LEAST32_MAX__' +`__UINT_LEAST64_MAX__' +`__INT_FAST8_MAX__' +`__INT_FAST16_MAX__' +`__INT_FAST32_MAX__' +`__INT_FAST64_MAX__' +`__UINT_FAST8_MAX__' +`__UINT_FAST16_MAX__' +`__UINT_FAST32_MAX__' +`__UINT_FAST64_MAX__' +`__INTPTR_MAX__' +`__UINTPTR_MAX__' +`__WCHAR_MIN__' +`__WINT_MIN__' +`__SIG_ATOMIC_MIN__' + Defined to the maximum value of the `signed char', `wchar_t', + `signed short', `signed int', `signed long', `signed long long', + `wint_t', `size_t', `ptrdiff_t', `intmax_t', `uintmax_t', + `sig_atomic_t', `int8_t', `int16_t', `int32_t', `int64_t', + `uint8_t', `uint16_t', `uint32_t', `uint64_t', `int_least8_t', + `int_least16_t', `int_least32_t', `int_least64_t', + `uint_least8_t', `uint_least16_t', `uint_least32_t', + `uint_least64_t', `int_fast8_t', `int_fast16_t', `int_fast32_t', + `int_fast64_t', `uint_fast8_t', `uint_fast16_t', `uint_fast32_t', + `uint_fast64_t', `intptr_t', and `uintptr_t' types and to the + minimum value of the `wchar_t', `wint_t', and `sig_atomic_t' types + respectively. They exist to make the standard header given + numerical limits work correctly. You should not use these macros + directly; instead, include the appropriate headers. Some of these + macros may not be defined on particular systems if GCC does not + provide a `stdint.h' header on those systems. + +`__INT8_C' +`__INT16_C' +`__INT32_C' +`__INT64_C' +`__UINT8_C' +`__UINT16_C' +`__UINT32_C' +`__UINT64_C' +`__INTMAX_C' +`__UINTMAX_C' + Defined to implementations of the standard `stdint.h' macros with + the same names without the leading `__'. They exist the make the + implementation of that header work correctly. You should not use + these macros directly; instead, include the appropriate headers. + Some of these macros may not be defined on particular systems if + GCC does not provide a `stdint.h' header on those systems. + +`__SIZEOF_INT__' +`__SIZEOF_LONG__' +`__SIZEOF_LONG_LONG__' +`__SIZEOF_SHORT__' +`__SIZEOF_POINTER__' +`__SIZEOF_FLOAT__' +`__SIZEOF_DOUBLE__' +`__SIZEOF_LONG_DOUBLE__' +`__SIZEOF_SIZE_T__' +`__SIZEOF_WCHAR_T__' +`__SIZEOF_WINT_T__' +`__SIZEOF_PTRDIFF_T__' + Defined to the number of bytes of the C standard data types: `int', + `long', `long long', `short', `void *', `float', `double', `long + double', `size_t', `wchar_t', `wint_t' and `ptrdiff_t'. + +`__BYTE_ORDER__' +`__ORDER_LITTLE_ENDIAN__' +`__ORDER_BIG_ENDIAN__' +`__ORDER_PDP_ENDIAN__' + `__BYTE_ORDER__' is defined to one of the values + `__ORDER_LITTLE_ENDIAN__', `__ORDER_BIG_ENDIAN__', or + `__ORDER_PDP_ENDIAN__' to reflect the layout of multi-byte and + multi-word quantities in memory. If `__BYTE_ORDER__' is equal to + `__ORDER_LITTLE_ENDIAN__' or `__ORDER_BIG_ENDIAN__', then + multi-byte and multi-word quantities are laid out identically: the + byte (word) at the lowest address is the least significant or most + significant byte (word) of the quantity, respectively. If + `__BYTE_ORDER__' is equal to `__ORDER_PDP_ENDIAN__', then bytes in + 16-bit words are laid out in a little-endian fashion, whereas the + 16-bit subwords of a 32-bit quantity are laid out in big-endian + fashion. + + You should use these macros for testing like this: + + /* Test for a little-endian machine */ + #if __BYTE_ORDER__ == __ORDER_LITTLE_ENDIAN__ + +`__FLOAT_WORD_ORDER__' + `__FLOAT_WORD_ORDER__' is defined to one of the values + `__ORDER_LITTLE_ENDIAN__' or `__ORDER_BIG_ENDIAN__' to reflect the + layout of the words of multi-word floating-point quantities. + +`__DEPRECATED' + This macro is defined, with value 1, when compiling a C++ source + file with warnings about deprecated constructs enabled. These + warnings are enabled by default, but can be disabled with + `-Wno-deprecated'. + +`__EXCEPTIONS' + This macro is defined, with value 1, when compiling a C++ source + file with exceptions enabled. If `-fno-exceptions' is used when + compiling the file, then this macro is not defined. + +`__GXX_RTTI' + This macro is defined, with value 1, when compiling a C++ source + file with runtime type identification enabled. If `-fno-rtti' is + used when compiling the file, then this macro is not defined. + +`__USING_SJLJ_EXCEPTIONS__' + This macro is defined, with value 1, if the compiler uses the old + mechanism based on `setjmp' and `longjmp' for exception handling. + +`__GXX_EXPERIMENTAL_CXX0X__' + This macro is defined when compiling a C++ source file with the + option `-std=c++0x' or `-std=gnu++0x'. It indicates that some + features likely to be included in C++0x are available. Note that + these features are experimental, and may change or be removed in + future versions of GCC. + +`__GXX_WEAK__' + This macro is defined when compiling a C++ source file. It has the + value 1 if the compiler will use weak symbols, COMDAT sections, or + other similar techniques to collapse symbols with "vague linkage" + that are defined in multiple translation units. If the compiler + will not collapse such symbols, this macro is defined with value + 0. In general, user code should not need to make use of this + macro; the purpose of this macro is to ease implementation of the + C++ runtime library provided with G++. + +`__NEXT_RUNTIME__' + This macro is defined, with value 1, if (and only if) the NeXT + runtime (as in `-fnext-runtime') is in use for Objective-C. If + the GNU runtime is used, this macro is not defined, so that you + can use this macro to determine which runtime (NeXT or GNU) is + being used. + +`__LP64__' +`_LP64' + These macros are defined, with value 1, if (and only if) the + compilation is for a target where `long int' and pointer both use + 64-bits and `int' uses 32-bit. + +`__SSP__' + This macro is defined, with value 1, when `-fstack-protector' is in + use. + +`__SSP_ALL__' + This macro is defined, with value 2, when `-fstack-protector-all' + is in use. + +`__TIMESTAMP__' + This macro expands to a string constant that describes the date + and time of the last modification of the current source file. The + string constant contains abbreviated day of the week, month, day + of the month, time in hh:mm:ss form, year and looks like + `"Sun Sep 16 01:03:52 1973"'. If the day of the month is less + than 10, it is padded with a space on the left. + + If GCC cannot determine the current date, it will emit a warning + message (once per compilation) and `__TIMESTAMP__' will expand to + `"??? ??? ?? ??:??:?? ????"'. + +`__GCC_HAVE_SYNC_COMPARE_AND_SWAP_1' +`__GCC_HAVE_SYNC_COMPARE_AND_SWAP_2' +`__GCC_HAVE_SYNC_COMPARE_AND_SWAP_4' +`__GCC_HAVE_SYNC_COMPARE_AND_SWAP_8' +`__GCC_HAVE_SYNC_COMPARE_AND_SWAP_16' + These macros are defined when the target processor supports atomic + compare and swap operations on operands 1, 2, 4, 8 or 16 bytes in + length, respectively. + +`__GCC_HAVE_DWARF2_CFI_ASM' + This macro is defined when the compiler is emitting Dwarf2 CFI + directives to the assembler. When this is defined, it is possible + to emit those same directives in inline assembly. + +`__FP_FAST_FMA' +`__FP_FAST_FMAF' +`__FP_FAST_FMAL' + These macros are defined with value 1 if the backend supports the + `fma', `fmaf', and `fmal' builtin functions, so that the include + file `math.h' can define the macros `FP_FAST_FMA', `FP_FAST_FMAF', + and `FP_FAST_FMAL' for compatibility with the 1999 C standard. + + +File: cpp.info, Node: System-specific Predefined Macros, Next: C++ Named Operators, Prev: Common Predefined Macros, Up: Predefined Macros + +3.7.3 System-specific Predefined Macros +--------------------------------------- + +The C preprocessor normally predefines several macros that indicate what +type of system and machine is in use. They are obviously different on +each target supported by GCC. This manual, being for all systems and +machines, cannot tell you what their names are, but you can use `cpp +-dM' to see them all. *Note Invocation::. All system-specific +predefined macros expand to the constant 1, so you can test them with +either `#ifdef' or `#if'. + + The C standard requires that all system-specific macros be part of +the "reserved namespace". All names which begin with two underscores, +or an underscore and a capital letter, are reserved for the compiler and +library to use as they wish. However, historically system-specific +macros have had names with no special prefix; for instance, it is common +to find `unix' defined on Unix systems. For all such macros, GCC +provides a parallel macro with two underscores added at the beginning +and the end. If `unix' is defined, `__unix__' will be defined too. +There will never be more than two underscores; the parallel of `_mips' +is `__mips__'. + + When the `-ansi' option, or any `-std' option that requests strict +conformance, is given to the compiler, all the system-specific +predefined macros outside the reserved namespace are suppressed. The +parallel macros, inside the reserved namespace, remain defined. + + We are slowly phasing out all predefined macros which are outside the +reserved namespace. You should never use them in new programs, and we +encourage you to correct older code to use the parallel macros whenever +you find it. We don't recommend you use the system-specific macros that +are in the reserved namespace, either. It is better in the long run to +check specifically for features you need, using a tool such as +`autoconf'. + + +File: cpp.info, Node: C++ Named Operators, Prev: System-specific Predefined Macros, Up: Predefined Macros + +3.7.4 C++ Named Operators +------------------------- + +In C++, there are eleven keywords which are simply alternate spellings +of operators normally written with punctuation. These keywords are +treated as such even in the preprocessor. They function as operators in +`#if', and they cannot be defined as macros or poisoned. In C, you can +request that those keywords take their C++ meaning by including +`iso646.h'. That header defines each one as a normal object-like macro +expanding to the appropriate punctuator. + + These are the named operators and their corresponding punctuators: + +Named Operator Punctuator +`and' `&&' +`and_eq' `&=' +`bitand' `&' +`bitor' `|' +`compl' `~' +`not' `!' +`not_eq' `!=' +`or' `||' +`or_eq' `|=' +`xor' `^' +`xor_eq' `^=' + + +File: cpp.info, Node: Undefining and Redefining Macros, Next: Directives Within Macro Arguments, Prev: Predefined Macros, Up: Macros + +3.8 Undefining and Redefining Macros +==================================== + +If a macro ceases to be useful, it may be "undefined" with the `#undef' +directive. `#undef' takes a single argument, the name of the macro to +undefine. You use the bare macro name, even if the macro is +function-like. It is an error if anything appears on the line after +the macro name. `#undef' has no effect if the name is not a macro. + + #define FOO 4 + x = FOO; ==> x = 4; + #undef FOO + x = FOO; ==> x = FOO; + + Once a macro has been undefined, that identifier may be "redefined" +as a macro by a subsequent `#define' directive. The new definition +need not have any resemblance to the old definition. + + However, if an identifier which is currently a macro is redefined, +then the new definition must be "effectively the same" as the old one. +Two macro definitions are effectively the same if: + * Both are the same type of macro (object- or function-like). + + * All the tokens of the replacement list are the same. + + * If there are any parameters, they are the same. + + * Whitespace appears in the same places in both. It need not be + exactly the same amount of whitespace, though. Remember that + comments count as whitespace. + +These definitions are effectively the same: + #define FOUR (2 + 2) + #define FOUR (2 + 2) + #define FOUR (2 /* two */ + 2) + but these are not: + #define FOUR (2 + 2) + #define FOUR ( 2+2 ) + #define FOUR (2 * 2) + #define FOUR(score,and,seven,years,ago) (2 + 2) + + If a macro is redefined with a definition that is not effectively the +same as the old one, the preprocessor issues a warning and changes the +macro to use the new definition. If the new definition is effectively +the same, the redefinition is silently ignored. This allows, for +instance, two different headers to define a common macro. The +preprocessor will only complain if the definitions do not match. + + +File: cpp.info, Node: Directives Within Macro Arguments, Next: Macro Pitfalls, Prev: Undefining and Redefining Macros, Up: Macros + +3.9 Directives Within Macro Arguments +===================================== + +Occasionally it is convenient to use preprocessor directives within the +arguments of a macro. The C and C++ standards declare that behavior in +these cases is undefined. + + Versions of CPP prior to 3.2 would reject such constructs with an +error message. This was the only syntactic difference between normal +functions and function-like macros, so it seemed attractive to remove +this limitation, and people would often be surprised that they could +not use macros in this way. Moreover, sometimes people would use +conditional compilation in the argument list to a normal library +function like `printf', only to find that after a library upgrade +`printf' had changed to be a function-like macro, and their code would +no longer compile. So from version 3.2 we changed CPP to successfully +process arbitrary directives within macro arguments in exactly the same +way as it would have processed the directive were the function-like +macro invocation not present. + + If, within a macro invocation, that macro is redefined, then the new +definition takes effect in time for argument pre-expansion, but the +original definition is still used for argument replacement. Here is a +pathological example: + + #define f(x) x x + f (1 + #undef f + #define f 2 + f) + +which expands to + + 1 2 1 2 + +with the semantics described above. + + +File: cpp.info, Node: Macro Pitfalls, Prev: Directives Within Macro Arguments, Up: Macros + +3.10 Macro Pitfalls +=================== + +In this section we describe some special rules that apply to macros and +macro expansion, and point out certain cases in which the rules have +counter-intuitive consequences that you must watch out for. + +* Menu: + +* Misnesting:: +* Operator Precedence Problems:: +* Swallowing the Semicolon:: +* Duplication of Side Effects:: +* Self-Referential Macros:: +* Argument Prescan:: +* Newlines in Arguments:: + + +File: cpp.info, Node: Misnesting, Next: Operator Precedence Problems, Up: Macro Pitfalls + +3.10.1 Misnesting +----------------- + +When a macro is called with arguments, the arguments are substituted +into the macro body and the result is checked, together with the rest of +the input file, for more macro calls. It is possible to piece together +a macro call coming partially from the macro body and partially from the +arguments. For example, + + #define twice(x) (2*(x)) + #define call_with_1(x) x(1) + call_with_1 (twice) + ==> twice(1) + ==> (2*(1)) + + Macro definitions do not have to have balanced parentheses. By +writing an unbalanced open parenthesis in a macro body, it is possible +to create a macro call that begins inside the macro body but ends +outside of it. For example, + + #define strange(file) fprintf (file, "%s %d", + ... + strange(stderr) p, 35) + ==> fprintf (stderr, "%s %d", p, 35) + + The ability to piece together a macro call can be useful, but the +use of unbalanced open parentheses in a macro body is just confusing, +and should be avoided. + + +File: cpp.info, Node: Operator Precedence Problems, Next: Swallowing the Semicolon, Prev: Misnesting, Up: Macro Pitfalls + +3.10.2 Operator Precedence Problems +----------------------------------- + +You may have noticed that in most of the macro definition examples shown +above, each occurrence of a macro argument name had parentheses around +it. In addition, another pair of parentheses usually surround the +entire macro definition. Here is why it is best to write macros that +way. + + Suppose you define a macro as follows, + + #define ceil_div(x, y) (x + y - 1) / y + +whose purpose is to divide, rounding up. (One use for this operation is +to compute how many `int' objects are needed to hold a certain number +of `char' objects.) Then suppose it is used as follows: + + a = ceil_div (b & c, sizeof (int)); + ==> a = (b & c + sizeof (int) - 1) / sizeof (int); + +This does not do what is intended. The operator-precedence rules of C +make it equivalent to this: + + a = (b & (c + sizeof (int) - 1)) / sizeof (int); + +What we want is this: + + a = ((b & c) + sizeof (int) - 1)) / sizeof (int); + +Defining the macro as + + #define ceil_div(x, y) ((x) + (y) - 1) / (y) + +provides the desired result. + + Unintended grouping can result in another way. Consider `sizeof +ceil_div(1, 2)'. That has the appearance of a C expression that would +compute the size of the type of `ceil_div (1, 2)', but in fact it means +something very different. Here is what it expands to: + + sizeof ((1) + (2) - 1) / (2) + +This would take the size of an integer and divide it by two. The +precedence rules have put the division outside the `sizeof' when it was +intended to be inside. + + Parentheses around the entire macro definition prevent such problems. +Here, then, is the recommended way to define `ceil_div': + + #define ceil_div(x, y) (((x) + (y) - 1) / (y)) + + +File: cpp.info, Node: Swallowing the Semicolon, Next: Duplication of Side Effects, Prev: Operator Precedence Problems, Up: Macro Pitfalls + +3.10.3 Swallowing the Semicolon +------------------------------- + +Often it is desirable to define a macro that expands into a compound +statement. Consider, for example, the following macro, that advances a +pointer (the argument `p' says where to find it) across whitespace +characters: + + #define SKIP_SPACES(p, limit) \ + { char *lim = (limit); \ + while (p < lim) { \ + if (*p++ != ' ') { \ + p--; break; }}} + +Here backslash-newline is used to split the macro definition, which must +be a single logical line, so that it resembles the way such code would +be laid out if not part of a macro definition. + + A call to this macro might be `SKIP_SPACES (p, lim)'. Strictly +speaking, the call expands to a compound statement, which is a complete +statement with no need for a semicolon to end it. However, since it +looks like a function call, it minimizes confusion if you can use it +like a function call, writing a semicolon afterward, as in `SKIP_SPACES +(p, lim);' + + This can cause trouble before `else' statements, because the +semicolon is actually a null statement. Suppose you write + + if (*p != 0) + SKIP_SPACES (p, lim); + else ... + +The presence of two statements--the compound statement and a null +statement--in between the `if' condition and the `else' makes invalid C +code. + + The definition of the macro `SKIP_SPACES' can be altered to solve +this problem, using a `do ... while' statement. Here is how: + + #define SKIP_SPACES(p, limit) \ + do { char *lim = (limit); \ + while (p < lim) { \ + if (*p++ != ' ') { \ + p--; break; }}} \ + while (0) + + Now `SKIP_SPACES (p, lim);' expands into + + do {...} while (0); + +which is one statement. The loop executes exactly once; most compilers +generate no extra code for it. + + +File: cpp.info, Node: Duplication of Side Effects, Next: Self-Referential Macros, Prev: Swallowing the Semicolon, Up: Macro Pitfalls + +3.10.4 Duplication of Side Effects +---------------------------------- + +Many C programs define a macro `min', for "minimum", like this: + + #define min(X, Y) ((X) < (Y) ? (X) : (Y)) + + When you use this macro with an argument containing a side effect, +as shown here, + + next = min (x + y, foo (z)); + +it expands as follows: + + next = ((x + y) < (foo (z)) ? (x + y) : (foo (z))); + +where `x + y' has been substituted for `X' and `foo (z)' for `Y'. + + The function `foo' is used only once in the statement as it appears +in the program, but the expression `foo (z)' has been substituted twice +into the macro expansion. As a result, `foo' might be called two times +when the statement is executed. If it has side effects or if it takes +a long time to compute, the results might not be what you intended. We +say that `min' is an "unsafe" macro. + + The best solution to this problem is to define `min' in a way that +computes the value of `foo (z)' only once. The C language offers no +standard way to do this, but it can be done with GNU extensions as +follows: + + #define min(X, Y) \ + ({ typeof (X) x_ = (X); \ + typeof (Y) y_ = (Y); \ + (x_ < y_) ? x_ : y_; }) + + The `({ ... })' notation produces a compound statement that acts as +an expression. Its value is the value of its last statement. This +permits us to define local variables and assign each argument to one. +The local variables have underscores after their names to reduce the +risk of conflict with an identifier of wider scope (it is impossible to +avoid this entirely). Now each argument is evaluated exactly once. + + If you do not wish to use GNU C extensions, the only solution is to +be careful when _using_ the macro `min'. For example, you can +calculate the value of `foo (z)', save it in a variable, and use that +variable in `min': + + #define min(X, Y) ((X) < (Y) ? (X) : (Y)) + ... + { + int tem = foo (z); + next = min (x + y, tem); + } + +(where we assume that `foo' returns type `int'). + + +File: cpp.info, Node: Self-Referential Macros, Next: Argument Prescan, Prev: Duplication of Side Effects, Up: Macro Pitfalls + +3.10.5 Self-Referential Macros +------------------------------ + +A "self-referential" macro is one whose name appears in its definition. +Recall that all macro definitions are rescanned for more macros to +replace. If the self-reference were considered a use of the macro, it +would produce an infinitely large expansion. To prevent this, the +self-reference is not considered a macro call. It is passed into the +preprocessor output unchanged. Consider an example: + + #define foo (4 + foo) + +where `foo' is also a variable in your program. + + Following the ordinary rules, each reference to `foo' will expand +into `(4 + foo)'; then this will be rescanned and will expand into `(4 ++ (4 + foo))'; and so on until the computer runs out of memory. + + The self-reference rule cuts this process short after one step, at +`(4 + foo)'. Therefore, this macro definition has the possibly useful +effect of causing the program to add 4 to the value of `foo' wherever +`foo' is referred to. + + In most cases, it is a bad idea to take advantage of this feature. A +person reading the program who sees that `foo' is a variable will not +expect that it is a macro as well. The reader will come across the +identifier `foo' in the program and think its value should be that of +the variable `foo', whereas in fact the value is four greater. + + One common, useful use of self-reference is to create a macro which +expands to itself. If you write + + #define EPERM EPERM + +then the macro `EPERM' expands to `EPERM'. Effectively, it is left +alone by the preprocessor whenever it's used in running text. You can +tell that it's a macro with `#ifdef'. You might do this if you want to +define numeric constants with an `enum', but have `#ifdef' be true for +each constant. + + If a macro `x' expands to use a macro `y', and the expansion of `y' +refers to the macro `x', that is an "indirect self-reference" of `x'. +`x' is not expanded in this case either. Thus, if we have + + #define x (4 + y) + #define y (2 * x) + +then `x' and `y' expand as follows: + + x ==> (4 + y) + ==> (4 + (2 * x)) + + y ==> (2 * x) + ==> (2 * (4 + y)) + +Each macro is expanded when it appears in the definition of the other +macro, but not when it indirectly appears in its own definition. + + +File: cpp.info, Node: Argument Prescan, Next: Newlines in Arguments, Prev: Self-Referential Macros, Up: Macro Pitfalls + +3.10.6 Argument Prescan +----------------------- + +Macro arguments are completely macro-expanded before they are +substituted into a macro body, unless they are stringified or pasted +with other tokens. After substitution, the entire macro body, including +the substituted arguments, is scanned again for macros to be expanded. +The result is that the arguments are scanned _twice_ to expand macro +calls in them. + + Most of the time, this has no effect. If the argument contained any +macro calls, they are expanded during the first scan. The result +therefore contains no macro calls, so the second scan does not change +it. If the argument were substituted as given, with no prescan, the +single remaining scan would find the same macro calls and produce the +same results. + + You might expect the double scan to change the results when a +self-referential macro is used in an argument of another macro (*note +Self-Referential Macros::): the self-referential macro would be +expanded once in the first scan, and a second time in the second scan. +However, this is not what happens. The self-references that do not +expand in the first scan are marked so that they will not expand in the +second scan either. + + You might wonder, "Why mention the prescan, if it makes no +difference? And why not skip it and make the preprocessor faster?" +The answer is that the prescan does make a difference in three special +cases: + + * Nested calls to a macro. + + We say that "nested" calls to a macro occur when a macro's argument + contains a call to that very macro. For example, if `f' is a macro + that expects one argument, `f (f (1))' is a nested pair of calls to + `f'. The desired expansion is made by expanding `f (1)' and + substituting that into the definition of `f'. The prescan causes + the expected result to happen. Without the prescan, `f (1)' itself + would be substituted as an argument, and the inner use of `f' would + appear during the main scan as an indirect self-reference and + would not be expanded. + + * Macros that call other macros that stringify or concatenate. + + If an argument is stringified or concatenated, the prescan does not + occur. If you _want_ to expand a macro, then stringify or + concatenate its expansion, you can do that by causing one macro to + call another macro that does the stringification or concatenation. + For instance, if you have + + #define AFTERX(x) X_ ## x + #define XAFTERX(x) AFTERX(x) + #define TABLESIZE 1024 + #define BUFSIZE TABLESIZE + + then `AFTERX(BUFSIZE)' expands to `X_BUFSIZE', and + `XAFTERX(BUFSIZE)' expands to `X_1024'. (Not to `X_TABLESIZE'. + Prescan always does a complete expansion.) + + * Macros used in arguments, whose expansions contain unshielded + commas. + + This can cause a macro expanded on the second scan to be called + with the wrong number of arguments. Here is an example: + + #define foo a,b + #define bar(x) lose(x) + #define lose(x) (1 + (x)) + + We would like `bar(foo)' to turn into `(1 + (foo))', which would + then turn into `(1 + (a,b))'. Instead, `bar(foo)' expands into + `lose(a,b)', and you get an error because `lose' requires a single + argument. In this case, the problem is easily solved by the same + parentheses that ought to be used to prevent misnesting of + arithmetic operations: + + #define foo (a,b) + or + #define bar(x) lose((x)) + + The extra pair of parentheses prevents the comma in `foo''s + definition from being interpreted as an argument separator. + + + +File: cpp.info, Node: Newlines in Arguments, Prev: Argument Prescan, Up: Macro Pitfalls + +3.10.7 Newlines in Arguments +---------------------------- + +The invocation of a function-like macro can extend over many logical +lines. However, in the present implementation, the entire expansion +comes out on one line. Thus line numbers emitted by the compiler or +debugger refer to the line the invocation started on, which might be +different to the line containing the argument causing the problem. + + Here is an example illustrating this: + + #define ignore_second_arg(a,b,c) a; c + + ignore_second_arg (foo (), + ignored (), + syntax error); + +The syntax error triggered by the tokens `syntax error' results in an +error message citing line three--the line of ignore_second_arg-- even +though the problematic code comes from line five. + + We consider this a bug, and intend to fix it in the near future. + + +File: cpp.info, Node: Conditionals, Next: Diagnostics, Prev: Macros, Up: Top + +4 Conditionals +************** + +A "conditional" is a directive that instructs the preprocessor to +select whether or not to include a chunk of code in the final token +stream passed to the compiler. Preprocessor conditionals can test +arithmetic expressions, or whether a name is defined as a macro, or both +simultaneously using the special `defined' operator. + + A conditional in the C preprocessor resembles in some ways an `if' +statement in C, but it is important to understand the difference between +them. The condition in an `if' statement is tested during the +execution of your program. Its purpose is to allow your program to +behave differently from run to run, depending on the data it is +operating on. The condition in a preprocessing conditional directive is +tested when your program is compiled. Its purpose is to allow different +code to be included in the program depending on the situation at the +time of compilation. + + However, the distinction is becoming less clear. Modern compilers +often do test `if' statements when a program is compiled, if their +conditions are known not to vary at run time, and eliminate code which +can never be executed. If you can count on your compiler to do this, +you may find that your program is more readable if you use `if' +statements with constant conditions (perhaps determined by macros). Of +course, you can only use this to exclude code, not type definitions or +other preprocessing directives, and you can only do it if the code +remains syntactically valid when it is not to be used. + + GCC version 3 eliminates this kind of never-executed code even when +not optimizing. Older versions did it only when optimizing. + +* Menu: + +* Conditional Uses:: +* Conditional Syntax:: +* Deleted Code:: + + +File: cpp.info, Node: Conditional Uses, Next: Conditional Syntax, Up: Conditionals + +4.1 Conditional Uses +==================== + +There are three general reasons to use a conditional. + + * A program may need to use different code depending on the machine + or operating system it is to run on. In some cases the code for + one operating system may be erroneous on another operating system; + for example, it might refer to data types or constants that do not + exist on the other system. When this happens, it is not enough to + avoid executing the invalid code. Its mere presence will cause + the compiler to reject the program. With a preprocessing + conditional, the offending code can be effectively excised from + the program when it is not valid. + + * You may want to be able to compile the same source file into two + different programs. One version might make frequent time-consuming + consistency checks on its intermediate data, or print the values of + those data for debugging, and the other not. + + * A conditional whose condition is always false is one way to + exclude code from the program but keep it as a sort of comment for + future reference. + + Simple programs that do not need system-specific logic or complex +debugging hooks generally will not need to use preprocessing +conditionals. + + +File: cpp.info, Node: Conditional Syntax, Next: Deleted Code, Prev: Conditional Uses, Up: Conditionals + +4.2 Conditional Syntax +====================== + +A conditional in the C preprocessor begins with a "conditional +directive": `#if', `#ifdef' or `#ifndef'. + +* Menu: + +* Ifdef:: +* If:: +* Defined:: +* Else:: +* Elif:: + + +File: cpp.info, Node: Ifdef, Next: If, Up: Conditional Syntax + +4.2.1 Ifdef +----------- + +The simplest sort of conditional is + + #ifdef MACRO + + CONTROLLED TEXT + + #endif /* MACRO */ + + This block is called a "conditional group". CONTROLLED TEXT will be +included in the output of the preprocessor if and only if MACRO is +defined. We say that the conditional "succeeds" if MACRO is defined, +"fails" if it is not. + + The CONTROLLED TEXT inside of a conditional can include +preprocessing directives. They are executed only if the conditional +succeeds. You can nest conditional groups inside other conditional +groups, but they must be completely nested. In other words, `#endif' +always matches the nearest `#ifdef' (or `#ifndef', or `#if'). Also, +you cannot start a conditional group in one file and end it in another. + + Even if a conditional fails, the CONTROLLED TEXT inside it is still +run through initial transformations and tokenization. Therefore, it +must all be lexically valid C. Normally the only way this matters is +that all comments and string literals inside a failing conditional group +must still be properly ended. + + The comment following the `#endif' is not required, but it is a good +practice if there is a lot of CONTROLLED TEXT, because it helps people +match the `#endif' to the corresponding `#ifdef'. Older programs +sometimes put MACRO directly after the `#endif' without enclosing it in +a comment. This is invalid code according to the C standard. CPP +accepts it with a warning. It never affects which `#ifndef' the +`#endif' matches. + + Sometimes you wish to use some code if a macro is _not_ defined. +You can do this by writing `#ifndef' instead of `#ifdef'. One common +use of `#ifndef' is to include code only the first time a header file +is included. *Note Once-Only Headers::. + + Macro definitions can vary between compilations for several reasons. +Here are some samples. + + * Some macros are predefined on each kind of machine (*note + System-specific Predefined Macros::). This allows you to provide + code specially tuned for a particular machine. + + * System header files define more macros, associated with the + features they implement. You can test these macros with + conditionals to avoid using a system feature on a machine where it + is not implemented. + + * Macros can be defined or undefined with the `-D' and `-U' command + line options when you compile the program. You can arrange to + compile the same source file into two different programs by + choosing a macro name to specify which program you want, writing + conditionals to test whether or how this macro is defined, and + then controlling the state of the macro with command line options, + perhaps set in the Makefile. *Note Invocation::. + + * Your program might have a special header file (often called + `config.h') that is adjusted when the program is compiled. It can + define or not define macros depending on the features of the + system and the desired capabilities of the program. The + adjustment can be automated by a tool such as `autoconf', or done + by hand. + + +File: cpp.info, Node: If, Next: Defined, Prev: Ifdef, Up: Conditional Syntax + +4.2.2 If +-------- + +The `#if' directive allows you to test the value of an arithmetic +expression, rather than the mere existence of one macro. Its syntax is + + #if EXPRESSION + + CONTROLLED TEXT + + #endif /* EXPRESSION */ + + EXPRESSION is a C expression of integer type, subject to stringent +restrictions. It may contain + + * Integer constants. + + * Character constants, which are interpreted as they would be in + normal code. + + * Arithmetic operators for addition, subtraction, multiplication, + division, bitwise operations, shifts, comparisons, and logical + operations (`&&' and `||'). The latter two obey the usual + short-circuiting rules of standard C. + + * Macros. All macros in the expression are expanded before actual + computation of the expression's value begins. + + * Uses of the `defined' operator, which lets you check whether macros + are defined in the middle of an `#if'. + + * Identifiers that are not macros, which are all considered to be the + number zero. This allows you to write `#if MACRO' instead of + `#ifdef MACRO', if you know that MACRO, when defined, will always + have a nonzero value. Function-like macros used without their + function call parentheses are also treated as zero. + + In some contexts this shortcut is undesirable. The `-Wundef' + option causes GCC to warn whenever it encounters an identifier + which is not a macro in an `#if'. + + The preprocessor does not know anything about types in the language. +Therefore, `sizeof' operators are not recognized in `#if', and neither +are `enum' constants. They will be taken as identifiers which are not +macros, and replaced by zero. In the case of `sizeof', this is likely +to cause the expression to be invalid. + + The preprocessor calculates the value of EXPRESSION. It carries out +all calculations in the widest integer type known to the compiler; on +most machines supported by GCC this is 64 bits. This is not the same +rule as the compiler uses to calculate the value of a constant +expression, and may give different results in some cases. If the value +comes out to be nonzero, the `#if' succeeds and the CONTROLLED TEXT is +included; otherwise it is skipped. + + +File: cpp.info, Node: Defined, Next: Else, Prev: If, Up: Conditional Syntax + +4.2.3 Defined +------------- + +The special operator `defined' is used in `#if' and `#elif' expressions +to test whether a certain name is defined as a macro. `defined NAME' +and `defined (NAME)' are both expressions whose value is 1 if NAME is +defined as a macro at the current point in the program, and 0 +otherwise. Thus, `#if defined MACRO' is precisely equivalent to +`#ifdef MACRO'. + + `defined' is useful when you wish to test more than one macro for +existence at once. For example, + + #if defined (__vax__) || defined (__ns16000__) + +would succeed if either of the names `__vax__' or `__ns16000__' is +defined as a macro. + + Conditionals written like this: + + #if defined BUFSIZE && BUFSIZE >= 1024 + +can generally be simplified to just `#if BUFSIZE >= 1024', since if +`BUFSIZE' is not defined, it will be interpreted as having the value +zero. + + If the `defined' operator appears as a result of a macro expansion, +the C standard says the behavior is undefined. GNU cpp treats it as a +genuine `defined' operator and evaluates it normally. It will warn +wherever your code uses this feature if you use the command-line option +`-pedantic', since other compilers may handle it differently. + + +File: cpp.info, Node: Else, Next: Elif, Prev: Defined, Up: Conditional Syntax + +4.2.4 Else +---------- + +The `#else' directive can be added to a conditional to provide +alternative text to be used if the condition fails. This is what it +looks like: + + #if EXPRESSION + TEXT-IF-TRUE + #else /* Not EXPRESSION */ + TEXT-IF-FALSE + #endif /* Not EXPRESSION */ + +If EXPRESSION is nonzero, the TEXT-IF-TRUE is included and the +TEXT-IF-FALSE is skipped. If EXPRESSION is zero, the opposite happens. + + You can use `#else' with `#ifdef' and `#ifndef', too. + + +File: cpp.info, Node: Elif, Prev: Else, Up: Conditional Syntax + +4.2.5 Elif +---------- + +One common case of nested conditionals is used to check for more than +two possible alternatives. For example, you might have + + #if X == 1 + ... + #else /* X != 1 */ + #if X == 2 + ... + #else /* X != 2 */ + ... + #endif /* X != 2 */ + #endif /* X != 1 */ + + Another conditional directive, `#elif', allows this to be +abbreviated as follows: + + #if X == 1 + ... + #elif X == 2 + ... + #else /* X != 2 and X != 1*/ + ... + #endif /* X != 2 and X != 1*/ + + `#elif' stands for "else if". Like `#else', it goes in the middle +of a conditional group and subdivides it; it does not require a +matching `#endif' of its own. Like `#if', the `#elif' directive +includes an expression to be tested. The text following the `#elif' is +processed only if the original `#if'-condition failed and the `#elif' +condition succeeds. + + More than one `#elif' can go in the same conditional group. Then +the text after each `#elif' is processed only if the `#elif' condition +succeeds after the original `#if' and all previous `#elif' directives +within it have failed. + + `#else' is allowed after any number of `#elif' directives, but +`#elif' may not follow `#else'. + + +File: cpp.info, Node: Deleted Code, Prev: Conditional Syntax, Up: Conditionals + +4.3 Deleted Code +================ + +If you replace or delete a part of the program but want to keep the old +code around for future reference, you often cannot simply comment it +out. Block comments do not nest, so the first comment inside the old +code will end the commenting-out. The probable result is a flood of +syntax errors. + + One way to avoid this problem is to use an always-false conditional +instead. For instance, put `#if 0' before the deleted code and +`#endif' after it. This works even if the code being turned off +contains conditionals, but they must be entire conditionals (balanced +`#if' and `#endif'). + + Some people use `#ifdef notdef' instead. This is risky, because +`notdef' might be accidentally defined as a macro, and then the +conditional would succeed. `#if 0' can be counted on to fail. + + Do not use `#if 0' for comments which are not C code. Use a real +comment, instead. The interior of `#if 0' must consist of complete +tokens; in particular, single-quote characters must balance. Comments +often contain unbalanced single-quote characters (known in English as +apostrophes). These confuse `#if 0'. They don't confuse `/*'. + + +File: cpp.info, Node: Diagnostics, Next: Line Control, Prev: Conditionals, Up: Top + +5 Diagnostics +************* + +The directive `#error' causes the preprocessor to report a fatal error. +The tokens forming the rest of the line following `#error' are used as +the error message. + + You would use `#error' inside of a conditional that detects a +combination of parameters which you know the program does not properly +support. For example, if you know that the program will not run +properly on a VAX, you might write + + #ifdef __vax__ + #error "Won't work on VAXen. See comments at get_last_object." + #endif + + If you have several configuration parameters that must be set up by +the installation in a consistent way, you can use conditionals to detect +an inconsistency and report it with `#error'. For example, + + #if !defined(UNALIGNED_INT_ASM_OP) && defined(DWARF2_DEBUGGING_INFO) + #error "DWARF2_DEBUGGING_INFO requires UNALIGNED_INT_ASM_OP." + #endif + + The directive `#warning' is like `#error', but causes the +preprocessor to issue a warning and continue preprocessing. The tokens +following `#warning' are used as the warning message. + + You might use `#warning' in obsolete header files, with a message +directing the user to the header file which should be used instead. + + Neither `#error' nor `#warning' macro-expands its argument. +Internal whitespace sequences are each replaced with a single space. +The line must consist of complete tokens. It is wisest to make the +argument of these directives be a single string constant; this avoids +problems with apostrophes and the like. + + +File: cpp.info, Node: Line Control, Next: Pragmas, Prev: Diagnostics, Up: Top + +6 Line Control +************** + +The C preprocessor informs the C compiler of the location in your source +code where each token came from. Presently, this is just the file name +and line number. All the tokens resulting from macro expansion are +reported as having appeared on the line of the source file where the +outermost macro was used. We intend to be more accurate in the future. + + If you write a program which generates source code, such as the +`bison' parser generator, you may want to adjust the preprocessor's +notion of the current file name and line number by hand. Parts of the +output from `bison' are generated from scratch, other parts come from a +standard parser file. The rest are copied verbatim from `bison''s +input. You would like compiler error messages and symbolic debuggers +to be able to refer to `bison''s input file. + + `bison' or any such program can arrange this by writing `#line' +directives into the output file. `#line' is a directive that specifies +the original line number and source file name for subsequent input in +the current preprocessor input file. `#line' has three variants: + +`#line LINENUM' + LINENUM is a non-negative decimal integer constant. It specifies + the line number which should be reported for the following line of + input. Subsequent lines are counted from LINENUM. + +`#line LINENUM FILENAME' + LINENUM is the same as for the first form, and has the same + effect. In addition, FILENAME is a string constant. The + following line and all subsequent lines are reported to come from + the file it specifies, until something else happens to change that. + FILENAME is interpreted according to the normal rules for a string + constant: backslash escapes are interpreted. This is different + from `#include'. + + Previous versions of CPP did not interpret escapes in `#line'; we + have changed it because the standard requires they be interpreted, + and most other compilers do. + +`#line ANYTHING ELSE' + ANYTHING ELSE is checked for macro calls, which are expanded. The + result should match one of the above two forms. + + `#line' directives alter the results of the `__FILE__' and +`__LINE__' predefined macros from that point on. *Note Standard +Predefined Macros::. They do not have any effect on `#include''s idea +of the directory containing the current file. This is a change from +GCC 2.95. Previously, a file reading + + #line 1 "../src/gram.y" + #include "gram.h" + + would search for `gram.h' in `../src', then the `-I' chain; the +directory containing the physical source file would not be searched. +In GCC 3.0 and later, the `#include' is not affected by the presence of +a `#line' referring to a different directory. + + We made this change because the old behavior caused problems when +generated source files were transported between machines. For instance, +it is common practice to ship generated parsers with a source release, +so that people building the distribution do not need to have yacc or +Bison installed. These files frequently have `#line' directives +referring to the directory tree of the system where the distribution was +created. If GCC tries to search for headers in those directories, the +build is likely to fail. + + The new behavior can cause failures too, if the generated file is not +in the same directory as its source and it attempts to include a header +which would be visible searching from the directory containing the +source file. However, this problem is easily solved with an additional +`-I' switch on the command line. The failures caused by the old +semantics could sometimes be corrected only by editing the generated +files, which is difficult and error-prone. + + +File: cpp.info, Node: Pragmas, Next: Other Directives, Prev: Line Control, Up: Top + +7 Pragmas +********* + +The `#pragma' directive is the method specified by the C standard for +providing additional information to the compiler, beyond what is +conveyed in the language itself. Three forms of this directive +(commonly known as "pragmas") are specified by the 1999 C standard. A +C compiler is free to attach any meaning it likes to other pragmas. + + GCC has historically preferred to use extensions to the syntax of the +language, such as `__attribute__', for this purpose. However, GCC does +define a few pragmas of its own. These mostly have effects on the +entire translation unit or source file. + + In GCC version 3, all GNU-defined, supported pragmas have been given +a `GCC' prefix. This is in line with the `STDC' prefix on all pragmas +defined by C99. For backward compatibility, pragmas which were +recognized by previous versions are still recognized without the `GCC' +prefix, but that usage is deprecated. Some older pragmas are +deprecated in their entirety. They are not recognized with the `GCC' +prefix. *Note Obsolete Features::. + + C99 introduces the `_Pragma' operator. This feature addresses a +major problem with `#pragma': being a directive, it cannot be produced +as the result of macro expansion. `_Pragma' is an operator, much like +`sizeof' or `defined', and can be embedded in a macro. + + Its syntax is `_Pragma (STRING-LITERAL)', where STRING-LITERAL can +be either a normal or wide-character string literal. It is +destringized, by replacing all `\\' with a single `\' and all `\"' with +a `"'. The result is then processed as if it had appeared as the right +hand side of a `#pragma' directive. For example, + + _Pragma ("GCC dependency \"parse.y\"") + +has the same effect as `#pragma GCC dependency "parse.y"'. The same +effect could be achieved using macros, for example + + #define DO_PRAGMA(x) _Pragma (#x) + DO_PRAGMA (GCC dependency "parse.y") + + The standard is unclear on where a `_Pragma' operator can appear. +The preprocessor does not accept it within a preprocessing conditional +directive like `#if'. To be safe, you are probably best keeping it out +of directives other than `#define', and putting it on a line of its own. + + This manual documents the pragmas which are meaningful to the +preprocessor itself. Other pragmas are meaningful to the C or C++ +compilers. They are documented in the GCC manual. + + GCC plugins may provide their own pragmas. + +`#pragma GCC dependency' + `#pragma GCC dependency' allows you to check the relative dates of + the current file and another file. If the other file is more + recent than the current file, a warning is issued. This is useful + if the current file is derived from the other file, and should be + regenerated. The other file is searched for using the normal + include search path. Optional trailing text can be used to give + more information in the warning message. + + #pragma GCC dependency "parse.y" + #pragma GCC dependency "/usr/include/time.h" rerun fixincludes + +`#pragma GCC poison' + Sometimes, there is an identifier that you want to remove + completely from your program, and make sure that it never creeps + back in. To enforce this, you can "poison" the identifier with + this pragma. `#pragma GCC poison' is followed by a list of + identifiers to poison. If any of those identifiers appears + anywhere in the source after the directive, it is a hard error. + For example, + + #pragma GCC poison printf sprintf fprintf + sprintf(some_string, "hello"); + + will produce an error. + + If a poisoned identifier appears as part of the expansion of a + macro which was defined before the identifier was poisoned, it + will _not_ cause an error. This lets you poison an identifier + without worrying about system headers defining macros that use it. + + For example, + + #define strrchr rindex + #pragma GCC poison rindex + strrchr(some_string, 'h'); + + will not produce an error. + +`#pragma GCC system_header' + This pragma takes no arguments. It causes the rest of the code in + the current file to be treated as if it came from a system header. + *Note System Headers::. + + + +File: cpp.info, Node: Other Directives, Next: Preprocessor Output, Prev: Pragmas, Up: Top + +8 Other Directives +****************** + +The `#ident' directive takes one argument, a string constant. On some +systems, that string constant is copied into a special segment of the +object file. On other systems, the directive is ignored. The `#sccs' +directive is a synonym for `#ident'. + + These directives are not part of the C standard, but they are not +official GNU extensions either. What historical information we have +been able to find, suggests they originated with System V. + + The "null directive" consists of a `#' followed by a newline, with +only whitespace (including comments) in between. A null directive is +understood as a preprocessing directive but has no effect on the +preprocessor output. The primary significance of the existence of the +null directive is that an input line consisting of just a `#' will +produce no output, rather than a line of output containing just a `#'. +Supposedly some old C programs contain such lines. + + +File: cpp.info, Node: Preprocessor Output, Next: Traditional Mode, Prev: Other Directives, Up: Top + +9 Preprocessor Output +********************* + +When the C preprocessor is used with the C, C++, or Objective-C +compilers, it is integrated into the compiler and communicates a stream +of binary tokens directly to the compiler's parser. However, it can +also be used in the more conventional standalone mode, where it produces +textual output. + + The output from the C preprocessor looks much like the input, except +that all preprocessing directive lines have been replaced with blank +lines and all comments with spaces. Long runs of blank lines are +discarded. + + The ISO standard specifies that it is implementation defined whether +a preprocessor preserves whitespace between tokens, or replaces it with +e.g. a single space. In GNU CPP, whitespace between tokens is collapsed +to become a single space, with the exception that the first token on a +non-directive line is preceded with sufficient spaces that it appears in +the same column in the preprocessed output that it appeared in the +original source file. This is so the output is easy to read. *Note +Differences from previous versions::. CPP does not insert any +whitespace where there was none in the original source, except where +necessary to prevent an accidental token paste. + + Source file name and line number information is conveyed by lines of +the form + + # LINENUM FILENAME FLAGS + +These are called "linemarkers". They are inserted as needed into the +output (but never within a string or character constant). They mean +that the following line originated in file FILENAME at line LINENUM. +FILENAME will never contain any non-printing characters; they are +replaced with octal escape sequences. + + After the file name comes zero or more flags, which are `1', `2', +`3', or `4'. If there are multiple flags, spaces separate them. Here +is what the flags mean: + +`1' + This indicates the start of a new file. + +`2' + This indicates returning to a file (after having included another + file). + +`3' + This indicates that the following text comes from a system header + file, so certain warnings should be suppressed. + +`4' + This indicates that the following text should be treated as being + wrapped in an implicit `extern "C"' block. + + As an extension, the preprocessor accepts linemarkers in +non-assembler input files. They are treated like the corresponding +`#line' directive, (*note Line Control::), except that trailing flags +are permitted, and are interpreted with the meanings described above. +If multiple flags are given, they must be in ascending order. + + Some directives may be duplicated in the output of the preprocessor. +These are `#ident' (always), `#pragma' (only if the preprocessor does +not handle the pragma itself), and `#define' and `#undef' (with certain +debugging options). If this happens, the `#' of the directive will +always be in the first column, and there will be no space between the +`#' and the directive name. If macro expansion happens to generate +tokens which might be mistaken for a duplicated directive, a space will +be inserted between the `#' and the directive name. + + +File: cpp.info, Node: Traditional Mode, Next: Implementation Details, Prev: Preprocessor Output, Up: Top + +10 Traditional Mode +******************* + +Traditional (pre-standard) C preprocessing is rather different from the +preprocessing specified by the standard. When GCC is given the +`-traditional-cpp' option, it attempts to emulate a traditional +preprocessor. + + GCC versions 3.2 and later only support traditional mode semantics in +the preprocessor, and not in the compiler front ends. This chapter +outlines the traditional preprocessor semantics we implemented. + + The implementation does not correspond precisely to the behavior of +earlier versions of GCC, nor to any true traditional preprocessor. +After all, inconsistencies among traditional implementations were a +major motivation for C standardization. However, we intend that it +should be compatible with true traditional preprocessors in all ways +that actually matter. + +* Menu: + +* Traditional lexical analysis:: +* Traditional macros:: +* Traditional miscellany:: +* Traditional warnings:: + + +File: cpp.info, Node: Traditional lexical analysis, Next: Traditional macros, Up: Traditional Mode + +10.1 Traditional lexical analysis +================================= + +The traditional preprocessor does not decompose its input into tokens +the same way a standards-conforming preprocessor does. The input is +simply treated as a stream of text with minimal internal form. + + This implementation does not treat trigraphs (*note trigraphs::) +specially since they were an invention of the standards committee. It +handles arbitrarily-positioned escaped newlines properly and splices +the lines as you would expect; many traditional preprocessors did not +do this. + + The form of horizontal whitespace in the input file is preserved in +the output. In particular, hard tabs remain hard tabs. This can be +useful if, for example, you are preprocessing a Makefile. + + Traditional CPP only recognizes C-style block comments, and treats +the `/*' sequence as introducing a comment only if it lies outside +quoted text. Quoted text is introduced by the usual single and double +quotes, and also by an initial `<' in a `#include' directive. + + Traditionally, comments are completely removed and are not replaced +with a space. Since a traditional compiler does its own tokenization +of the output of the preprocessor, this means that comments can +effectively be used as token paste operators. However, comments behave +like separators for text handled by the preprocessor itself, since it +doesn't re-lex its input. For example, in + + #if foo/**/bar + +`foo' and `bar' are distinct identifiers and expanded separately if +they happen to be macros. In other words, this directive is equivalent +to + + #if foo bar + +rather than + + #if foobar + + Generally speaking, in traditional mode an opening quote need not +have a matching closing quote. In particular, a macro may be defined +with replacement text that contains an unmatched quote. Of course, if +you attempt to compile preprocessed output containing an unmatched quote +you will get a syntax error. + + However, all preprocessing directives other than `#define' require +matching quotes. For example: + + #define m This macro's fine and has an unmatched quote + "/* This is not a comment. */ + /* This is a comment. The following #include directive + is ill-formed. */ + #include ++foo; + + Function-like macros are similar in form but quite different in +behavior to their ISO counterparts. Their arguments are contained +within parentheses, are comma-separated, and can cross physical lines. +Commas within nested parentheses are not treated as argument +separators. Similarly, a quote in an argument cannot be left unclosed; +a following comma or parenthesis that comes before the closing quote is +treated like any other character. There is no facility for handling +variadic macros. + + This implementation removes all comments from macro arguments, unless +the `-C' option is given. The form of all other horizontal whitespace +in arguments is preserved, including leading and trailing whitespace. +In particular + + f( ) + +is treated as an invocation of the macro `f' with a single argument +consisting of a single space. If you want to invoke a function-like +macro that takes no arguments, you must not leave any whitespace +between the parentheses. + + If a macro argument crosses a new line, the new line is replaced with +a space when forming the argument. If the previous line contained an +unterminated quote, the following line inherits the quoted state. + + Traditional preprocessors replace parameters in the replacement text +with their arguments regardless of whether the parameters are within +quotes or not. This provides a way to stringize arguments. For example + + #define str(x) "x" + str(/* A comment */some text ) + ==> "some text " + +Note that the comment is removed, but that the trailing space is +preserved. Here is an example of using a comment to effect token +pasting. + + #define suffix(x) foo_/**/x + suffix(bar) + ==> foo_bar + + +File: cpp.info, Node: Traditional miscellany, Next: Traditional warnings, Prev: Traditional macros, Up: Traditional Mode + +10.3 Traditional miscellany +=========================== + +Here are some things to be aware of when using the traditional +preprocessor. + + * Preprocessing directives are recognized only when their leading + `#' appears in the first column. There can be no whitespace + between the beginning of the line and the `#', but whitespace can + follow the `#'. + + * A true traditional C preprocessor does not recognize `#error' or + `#pragma', and may not recognize `#elif'. CPP supports all the + directives in traditional mode that it supports in ISO mode, + including extensions, with the exception that the effects of + `#pragma GCC poison' are undefined. + + * __STDC__ is not defined. + + * If you use digraphs the behavior is undefined. + + * If a line that looks like a directive appears within macro + arguments, the behavior is undefined. + + + +File: cpp.info, Node: Traditional warnings, Prev: Traditional miscellany, Up: Traditional Mode + +10.4 Traditional warnings +========================= + +You can request warnings about features that did not exist, or worked +differently, in traditional C with the `-Wtraditional' option. GCC +does not warn about features of ISO C which you must use when you are +using a conforming compiler, such as the `#' and `##' operators. + + Presently `-Wtraditional' warns about: + + * Macro parameters that appear within string literals in the macro + body. In traditional C macro replacement takes place within + string literals, but does not in ISO C. + + * In traditional C, some preprocessor directives did not exist. + Traditional preprocessors would only consider a line to be a + directive if the `#' appeared in column 1 on the line. Therefore + `-Wtraditional' warns about directives that traditional C + understands but would ignore because the `#' does not appear as the + first character on the line. It also suggests you hide directives + like `#pragma' not understood by traditional C by indenting them. + Some traditional implementations would not recognize `#elif', so it + suggests avoiding it altogether. + + * A function-like macro that appears without an argument list. In + some traditional preprocessors this was an error. In ISO C it + merely means that the macro is not expanded. + + * The unary plus operator. This did not exist in traditional C. + + * The `U' and `LL' integer constant suffixes, which were not + available in traditional C. (Traditional C does support the `L' + suffix for simple long integer constants.) You are not warned + about uses of these suffixes in macros defined in system headers. + For instance, `UINT_MAX' may well be defined as `4294967295U', but + you will not be warned if you use `UINT_MAX'. + + You can usually avoid the warning, and the related warning about + constants which are so large that they are unsigned, by writing the + integer constant in question in hexadecimal, with no U suffix. + Take care, though, because this gives the wrong result in exotic + cases. + + +File: cpp.info, Node: Implementation Details, Next: Invocation, Prev: Traditional Mode, Up: Top + +11 Implementation Details +************************* + +Here we document details of how the preprocessor's implementation +affects its user-visible behavior. You should try to avoid undue +reliance on behavior described here, as it is possible that it will +change subtly in future implementations. + + Also documented here are obsolete features and changes from previous +versions of CPP. + +* Menu: + +* Implementation-defined behavior:: +* Implementation limits:: +* Obsolete Features:: +* Differences from previous versions:: + + +File: cpp.info, Node: Implementation-defined behavior, Next: Implementation limits, Up: Implementation Details + +11.1 Implementation-defined behavior +==================================== + +This is how CPP behaves in all the cases which the C standard describes +as "implementation-defined". This term means that the implementation +is free to do what it likes, but must document its choice and stick to +it. + + * The mapping of physical source file multi-byte characters to the + execution character set. + + The input character set can be specified using the + `-finput-charset' option, while the execution character set may be + controlled using the `-fexec-charset' and `-fwide-exec-charset' + options. + + * Identifier characters. The C and C++ standards allow identifiers + to be composed of `_' and the alphanumeric characters. C++ and + C99 also allow universal character names, and C99 further permits + implementation-defined characters. GCC currently only permits + universal character names if `-fextended-identifiers' is used, + because the implementation of universal character names in + identifiers is experimental. + + GCC allows the `$' character in identifiers as an extension for + most targets. This is true regardless of the `std=' switch, since + this extension cannot conflict with standards-conforming programs. + When preprocessing assembler, however, dollars are not identifier + characters by default. + + Currently the targets that by default do not permit `$' are AVR, + IP2K, MMIX, MIPS Irix 3, ARM aout, and PowerPC targets for the AIX + operating system. + + You can override the default with `-fdollars-in-identifiers' or + `fno-dollars-in-identifiers'. *Note fdollars-in-identifiers::. + + * Non-empty sequences of whitespace characters. + + In textual output, each whitespace sequence is collapsed to a + single space. For aesthetic reasons, the first token on each + non-directive line of output is preceded with sufficient spaces + that it appears in the same column as it did in the original + source file. + + * The numeric value of character constants in preprocessor + expressions. + + The preprocessor and compiler interpret character constants in the + same way; i.e. escape sequences such as `\a' are given the values + they would have on the target machine. + + The compiler evaluates a multi-character character constant a + character at a time, shifting the previous value left by the + number of bits per target character, and then or-ing in the + bit-pattern of the new character truncated to the width of a + target character. The final bit-pattern is given type `int', and + is therefore signed, regardless of whether single characters are + signed or not (a slight change from versions 3.1 and earlier of + GCC). If there are more characters in the constant than would fit + in the target `int' the compiler issues a warning, and the excess + leading characters are ignored. + + For example, `'ab'' for a target with an 8-bit `char' would be + interpreted as + `(int) ((unsigned char) 'a' * 256 + (unsigned char) 'b')', and + `'\234a'' as + `(int) ((unsigned char) '\234' * 256 + (unsigned char) 'a')'. + + * Source file inclusion. + + For a discussion on how the preprocessor locates header files, + *note Include Operation::. + + * Interpretation of the filename resulting from a macro-expanded + `#include' directive. + + *Note Computed Includes::. + + * Treatment of a `#pragma' directive that after macro-expansion + results in a standard pragma. + + No macro expansion occurs on any `#pragma' directive line, so the + question does not arise. + + Note that GCC does not yet implement any of the standard pragmas. + + + +File: cpp.info, Node: Implementation limits, Next: Obsolete Features, Prev: Implementation-defined behavior, Up: Implementation Details + +11.2 Implementation limits +========================== + +CPP has a small number of internal limits. This section lists the +limits which the C standard requires to be no lower than some minimum, +and all the others known. It is intended that there should be as few +limits as possible. If you encounter an undocumented or inconvenient +limit, please report that as a bug. *Note Reporting Bugs: (gcc)Bugs. + + Where we say something is limited "only by available memory", that +means that internal data structures impose no intrinsic limit, and space +is allocated with `malloc' or equivalent. The actual limit will +therefore depend on many things, such as the size of other things +allocated by the compiler at the same time, the amount of memory +consumed by other processes on the same computer, etc. + + * Nesting levels of `#include' files. + + We impose an arbitrary limit of 200 levels, to avoid runaway + recursion. The standard requires at least 15 levels. + + * Nesting levels of conditional inclusion. + + The C standard mandates this be at least 63. CPP is limited only + by available memory. + + * Levels of parenthesized expressions within a full expression. + + The C standard requires this to be at least 63. In preprocessor + conditional expressions, it is limited only by available memory. + + * Significant initial characters in an identifier or macro name. + + The preprocessor treats all characters as significant. The C + standard requires only that the first 63 be significant. + + * Number of macros simultaneously defined in a single translation + unit. + + The standard requires at least 4095 be possible. CPP is limited + only by available memory. + + * Number of parameters in a macro definition and arguments in a + macro call. + + We allow `USHRT_MAX', which is no smaller than 65,535. The minimum + required by the standard is 127. + + * Number of characters on a logical source line. + + The C standard requires a minimum of 4096 be permitted. CPP places + no limits on this, but you may get incorrect column numbers + reported in diagnostics for lines longer than 65,535 characters. + + * Maximum size of a source file. + + The standard does not specify any lower limit on the maximum size + of a source file. GNU cpp maps files into memory, so it is + limited by the available address space. This is generally at + least two gigabytes. Depending on the operating system, the size + of physical memory may or may not be a limitation. + + + +File: cpp.info, Node: Obsolete Features, Next: Differences from previous versions, Prev: Implementation limits, Up: Implementation Details + +11.3 Obsolete Features +====================== + +CPP has some features which are present mainly for compatibility with +older programs. We discourage their use in new code. In some cases, +we plan to remove the feature in a future version of GCC. + +11.3.1 Assertions +----------------- + +"Assertions" are a deprecated alternative to macros in writing +conditionals to test what sort of computer or system the compiled +program will run on. Assertions are usually predefined, but you can +define them with preprocessing directives or command-line options. + + Assertions were intended to provide a more systematic way to describe +the compiler's target system and we added them for compatibility with +existing compilers. In practice they are just as unpredictable as the +system-specific predefined macros. In addition, they are not part of +any standard, and only a few compilers support them. Therefore, the +use of assertions is *less* portable than the use of system-specific +predefined macros. We recommend you do not use them at all. + + An assertion looks like this: + + #PREDICATE (ANSWER) + +PREDICATE must be a single identifier. ANSWER can be any sequence of +tokens; all characters are significant except for leading and trailing +whitespace, and differences in internal whitespace sequences are +ignored. (This is similar to the rules governing macro redefinition.) +Thus, `(x + y)' is different from `(x+y)' but equivalent to +`( x + y )'. Parentheses do not nest inside an answer. + + To test an assertion, you write it in an `#if'. For example, this +conditional succeeds if either `vax' or `ns16000' has been asserted as +an answer for `machine'. + + #if #machine (vax) || #machine (ns16000) + +You can test whether _any_ answer is asserted for a predicate by +omitting the answer in the conditional: + + #if #machine + + Assertions are made with the `#assert' directive. Its sole argument +is the assertion to make, without the leading `#' that identifies +assertions in conditionals. + + #assert PREDICATE (ANSWER) + +You may make several assertions with the same predicate and different +answers. Subsequent assertions do not override previous ones for the +same predicate. All the answers for any given predicate are +simultaneously true. + + Assertions can be canceled with the `#unassert' directive. It has +the same syntax as `#assert'. In that form it cancels only the answer +which was specified on the `#unassert' line; other answers for that +predicate remain true. You can cancel an entire predicate by leaving +out the answer: + + #unassert PREDICATE + +In either form, if no such assertion has been made, `#unassert' has no +effect. + + You can also make or cancel assertions using command line options. +*Note Invocation::. + + +File: cpp.info, Node: Differences from previous versions, Prev: Obsolete Features, Up: Implementation Details + +11.4 Differences from previous versions +======================================= + +This section details behavior which has changed from previous versions +of CPP. We do not plan to change it again in the near future, but we +do not promise not to, either. + + The "previous versions" discussed here are 2.95 and before. The +behavior of GCC 3.0 is mostly the same as the behavior of the widely +used 2.96 and 2.97 development snapshots. Where there are differences, +they generally represent bugs in the snapshots. + + * -I- deprecated + + This option has been deprecated in 4.0. `-iquote' is meant to + replace the need for this option. + + * Order of evaluation of `#' and `##' operators + + The standard does not specify the order of evaluation of a chain of + `##' operators, nor whether `#' is evaluated before, after, or at + the same time as `##'. You should therefore not write any code + which depends on any specific ordering. It is possible to + guarantee an ordering, if you need one, by suitable use of nested + macros. + + An example of where this might matter is pasting the arguments `1', + `e' and `-2'. This would be fine for left-to-right pasting, but + right-to-left pasting would produce an invalid token `e-2'. + + GCC 3.0 evaluates `#' and `##' at the same time and strictly left + to right. Older versions evaluated all `#' operators first, then + all `##' operators, in an unreliable order. + + * The form of whitespace between tokens in preprocessor output + + *Note Preprocessor Output::, for the current textual format. This + is also the format used by stringification. Normally, the + preprocessor communicates tokens directly to the compiler's + parser, and whitespace does not come up at all. + + Older versions of GCC preserved all whitespace provided by the + user and inserted lots more whitespace of their own, because they + could not accurately predict when extra spaces were needed to + prevent accidental token pasting. + + * Optional argument when invoking rest argument macros + + As an extension, GCC permits you to omit the variable arguments + entirely when you use a variable argument macro. This is + forbidden by the 1999 C standard, and will provoke a pedantic + warning with GCC 3.0. Previous versions accepted it silently. + + * `##' swallowing preceding text in rest argument macros + + Formerly, in a macro expansion, if `##' appeared before a variable + arguments parameter, and the set of tokens specified for that + argument in the macro invocation was empty, previous versions of + CPP would back up and remove the preceding sequence of + non-whitespace characters (*not* the preceding token). This + extension is in direct conflict with the 1999 C standard and has + been drastically pared back. + + In the current version of the preprocessor, if `##' appears between + a comma and a variable arguments parameter, and the variable + argument is omitted entirely, the comma will be removed from the + expansion. If the variable argument is empty, or the token before + `##' is not a comma, then `##' behaves as a normal token paste. + + * `#line' and `#include' + + The `#line' directive used to change GCC's notion of the + "directory containing the current file", used by `#include' with a + double-quoted header file name. In 3.0 and later, it does not. + *Note Line Control::, for further explanation. + + * Syntax of `#line' + + In GCC 2.95 and previous, the string constant argument to `#line' + was treated the same way as the argument to `#include': backslash + escapes were not honored, and the string ended at the second `"'. + This is not compliant with the C standard. In GCC 3.0, an attempt + was made to correct the behavior, so that the string was treated + as a real string constant, but it turned out to be buggy. In 3.1, + the bugs have been fixed. (We are not fixing the bugs in 3.0 + because they affect relatively few people and the fix is quite + invasive.) + + + +File: cpp.info, Node: Invocation, Next: Environment Variables, Prev: Implementation Details, Up: Top + +12 Invocation +************* + +Most often when you use the C preprocessor you will not have to invoke +it explicitly: the C compiler will do so automatically. However, the +preprocessor is sometimes useful on its own. All the options listed +here are also acceptable to the C compiler and have the same meaning, +except that the C compiler has different rules for specifying the output +file. + + _Note:_ Whether you use the preprocessor by way of `gcc' or `cpp', +the "compiler driver" is run first. This program's purpose is to +translate your command into invocations of the programs that do the +actual work. Their command line interfaces are similar but not +identical to the documented interface, and may change without notice. + + The C preprocessor expects two file names as arguments, INFILE and +OUTFILE. The preprocessor reads INFILE together with any other files +it specifies with `#include'. All the output generated by the combined +input files is written in OUTFILE. + + Either INFILE or OUTFILE may be `-', which as INFILE means to read +from standard input and as OUTFILE means to write to standard output. +Also, if either file is omitted, it means the same as if `-' had been +specified for that file. + + Unless otherwise noted, or the option ends in `=', all options which +take an argument may have that argument appear either immediately after +the option, or with a space between option and argument: `-Ifoo' and +`-I foo' have the same effect. + + Many options have multi-letter names; therefore multiple +single-letter options may _not_ be grouped: `-dM' is very different from +`-d -M'. + +`-D NAME' + Predefine NAME as a macro, with definition `1'. + +`-D NAME=DEFINITION' + The contents of DEFINITION are tokenized and processed as if they + appeared during translation phase three in a `#define' directive. + In particular, the definition will be truncated by embedded + newline characters. + + If you are invoking the preprocessor from a shell or shell-like + program you may need to use the shell's quoting syntax to protect + characters such as spaces that have a meaning in the shell syntax. + + If you wish to define a function-like macro on the command line, + write its argument list with surrounding parentheses before the + equals sign (if any). Parentheses are meaningful to most shells, + so you will need to quote the option. With `sh' and `csh', + `-D'NAME(ARGS...)=DEFINITION'' works. + + `-D' and `-U' options are processed in the order they are given on + the command line. All `-imacros FILE' and `-include FILE' options + are processed after all `-D' and `-U' options. + +`-U NAME' + Cancel any previous definition of NAME, either built in or + provided with a `-D' option. + +`-undef' + Do not predefine any system-specific or GCC-specific macros. The + standard predefined macros remain defined. *Note Standard + Predefined Macros::. + +`-I DIR' + Add the directory DIR to the list of directories to be searched + for header files. *Note Search Path::. Directories named by `-I' + are searched before the standard system include directories. If + the directory DIR is a standard system include directory, the + option is ignored to ensure that the default search order for + system directories and the special treatment of system headers are + not defeated (*note System Headers::) . If DIR begins with `=', + then the `=' will be replaced by the sysroot prefix; see + `--sysroot' and `-isysroot'. + +`-o FILE' + Write output to FILE. This is the same as specifying FILE as the + second non-option argument to `cpp'. `gcc' has a different + interpretation of a second non-option argument, so you must use + `-o' to specify the output file. + +`-Wall' + Turns on all optional warnings which are desirable for normal code. + At present this is `-Wcomment', `-Wtrigraphs', `-Wmultichar' and a + warning about integer promotion causing a change of sign in `#if' + expressions. Note that many of the preprocessor's warnings are on + by default and have no options to control them. + +`-Wcomment' +`-Wcomments' + Warn whenever a comment-start sequence `/*' appears in a `/*' + comment, or whenever a backslash-newline appears in a `//' comment. + (Both forms have the same effect.) + +`-Wtrigraphs' + Most trigraphs in comments cannot affect the meaning of the + program. However, a trigraph that would form an escaped newline + (`??/' at the end of a line) can, by changing where the comment + begins or ends. Therefore, only trigraphs that would form escaped + newlines produce warnings inside a comment. + + This option is implied by `-Wall'. If `-Wall' is not given, this + option is still enabled unless trigraphs are enabled. To get + trigraph conversion without warnings, but get the other `-Wall' + warnings, use `-trigraphs -Wall -Wno-trigraphs'. + +`-Wtraditional' + Warn about certain constructs that behave differently in + traditional and ISO C. Also warn about ISO C constructs that have + no traditional C equivalent, and problematic constructs which + should be avoided. *Note Traditional Mode::. + +`-Wundef' + Warn whenever an identifier which is not a macro is encountered in + an `#if' directive, outside of `defined'. Such identifiers are + replaced with zero. + +`-Wunused-macros' + Warn about macros defined in the main file that are unused. A + macro is "used" if it is expanded or tested for existence at least + once. The preprocessor will also warn if the macro has not been + used at the time it is redefined or undefined. + + Built-in macros, macros defined on the command line, and macros + defined in include files are not warned about. + + _Note:_ If a macro is actually used, but only used in skipped + conditional blocks, then CPP will report it as unused. To avoid + the warning in such a case, you might improve the scope of the + macro's definition by, for example, moving it into the first + skipped block. Alternatively, you could provide a dummy use with + something like: + + #if defined the_macro_causing_the_warning + #endif + +`-Wendif-labels' + Warn whenever an `#else' or an `#endif' are followed by text. + This usually happens in code of the form + + #if FOO + ... + #else FOO + ... + #endif FOO + + The second and third `FOO' should be in comments, but often are not + in older programs. This warning is on by default. + +`-Werror' + Make all warnings into hard errors. Source code which triggers + warnings will be rejected. + +`-Wsystem-headers' + Issue warnings for code in system headers. These are normally + unhelpful in finding bugs in your own code, therefore suppressed. + If you are responsible for the system library, you may want to see + them. + +`-w' + Suppress all warnings, including those which GNU CPP issues by + default. + +`-pedantic' + Issue all the mandatory diagnostics listed in the C standard. + Some of them are left out by default, since they trigger + frequently on harmless code. + +`-pedantic-errors' + Issue all the mandatory diagnostics, and make all mandatory + diagnostics into errors. This includes mandatory diagnostics that + GCC issues without `-pedantic' but treats as warnings. + +`-M' + Instead of outputting the result of preprocessing, output a rule + suitable for `make' describing the dependencies of the main source + file. The preprocessor outputs one `make' rule containing the + object file name for that source file, a colon, and the names of + all the included files, including those coming from `-include' or + `-imacros' command line options. + + Unless specified explicitly (with `-MT' or `-MQ'), the object file + name consists of the name of the source file with any suffix + replaced with object file suffix and with any leading directory + parts removed. If there are many included files then the rule is + split into several lines using `\'-newline. The rule has no + commands. + + This option does not suppress the preprocessor's debug output, + such as `-dM'. To avoid mixing such debug output with the + dependency rules you should explicitly specify the dependency + output file with `-MF', or use an environment variable like + `DEPENDENCIES_OUTPUT' (*note Environment Variables::). Debug + output will still be sent to the regular output stream as normal. + + Passing `-M' to the driver implies `-E', and suppresses warnings + with an implicit `-w'. + +`-MM' + Like `-M' but do not mention header files that are found in system + header directories, nor header files that are included, directly + or indirectly, from such a header. + + This implies that the choice of angle brackets or double quotes in + an `#include' directive does not in itself determine whether that + header will appear in `-MM' dependency output. This is a slight + change in semantics from GCC versions 3.0 and earlier. + +`-MF FILE' + When used with `-M' or `-MM', specifies a file to write the + dependencies to. If no `-MF' switch is given the preprocessor + sends the rules to the same place it would have sent preprocessed + output. + + When used with the driver options `-MD' or `-MMD', `-MF' overrides + the default dependency output file. + +`-MG' + In conjunction with an option such as `-M' requesting dependency + generation, `-MG' assumes missing header files are generated files + and adds them to the dependency list without raising an error. + The dependency filename is taken directly from the `#include' + directive without prepending any path. `-MG' also suppresses + preprocessed output, as a missing header file renders this useless. + + This feature is used in automatic updating of makefiles. + +`-MP' + This option instructs CPP to add a phony target for each dependency + other than the main file, causing each to depend on nothing. These + dummy rules work around errors `make' gives if you remove header + files without updating the `Makefile' to match. + + This is typical output: + + test.o: test.c test.h + + test.h: + +`-MT TARGET' + Change the target of the rule emitted by dependency generation. By + default CPP takes the name of the main input file, deletes any + directory components and any file suffix such as `.c', and appends + the platform's usual object suffix. The result is the target. + + An `-MT' option will set the target to be exactly the string you + specify. If you want multiple targets, you can specify them as a + single argument to `-MT', or use multiple `-MT' options. + + For example, `-MT '$(objpfx)foo.o'' might give + + $(objpfx)foo.o: foo.c + +`-MQ TARGET' + Same as `-MT', but it quotes any characters which are special to + Make. `-MQ '$(objpfx)foo.o'' gives + + $$(objpfx)foo.o: foo.c + + The default target is automatically quoted, as if it were given + with `-MQ'. + +`-MD' + `-MD' is equivalent to `-M -MF FILE', except that `-E' is not + implied. The driver determines FILE based on whether an `-o' + option is given. If it is, the driver uses its argument but with + a suffix of `.d', otherwise it takes the name of the input file, + removes any directory components and suffix, and applies a `.d' + suffix. + + If `-MD' is used in conjunction with `-E', any `-o' switch is + understood to specify the dependency output file (*note -MF: + dashMF.), but if used without `-E', each `-o' is understood to + specify a target object file. + + Since `-E' is not implied, `-MD' can be used to generate a + dependency output file as a side-effect of the compilation process. + +`-MMD' + Like `-MD' except mention only user header files, not system + header files. + +`-x c' +`-x c++' +`-x objective-c' +`-x assembler-with-cpp' + Specify the source language: C, C++, Objective-C, or assembly. + This has nothing to do with standards conformance or extensions; + it merely selects which base syntax to expect. If you give none + of these options, cpp will deduce the language from the extension + of the source file: `.c', `.cc', `.m', or `.S'. Some other common + extensions for C++ and assembly are also recognized. If cpp does + not recognize the extension, it will treat the file as C; this is + the most generic mode. + + _Note:_ Previous versions of cpp accepted a `-lang' option which + selected both the language and the standards conformance level. + This option has been removed, because it conflicts with the `-l' + option. + +`-std=STANDARD' +`-ansi' + Specify the standard to which the code should conform. Currently + CPP knows about C and C++ standards; others may be added in the + future. + + STANDARD may be one of: + `c90' + `c89' + `iso9899:1990' + The ISO C standard from 1990. `c90' is the customary + shorthand for this version of the standard. + + The `-ansi' option is equivalent to `-std=c90'. + + `iso9899:199409' + The 1990 C standard, as amended in 1994. + + `iso9899:1999' + `c99' + `iso9899:199x' + `c9x' + The revised ISO C standard, published in December 1999. + Before publication, this was known as C9X. + + `c1x' + The next version of the ISO C standard, still under + development. + + `gnu90' + `gnu89' + The 1990 C standard plus GNU extensions. This is the default. + + `gnu99' + `gnu9x' + The 1999 C standard plus GNU extensions. + + `gnu1x' + The next version of the ISO C standard, still under + development, plus GNU extensions. + + `c++98' + The 1998 ISO C++ standard plus amendments. + + `gnu++98' + The same as `-std=c++98' plus GNU extensions. This is the + default for C++ code. + +`-I-' + Split the include path. Any directories specified with `-I' + options before `-I-' are searched only for headers requested with + `#include "FILE"'; they are not searched for `#include '. + If additional directories are specified with `-I' options after + the `-I-', those directories are searched for all `#include' + directives. + + In addition, `-I-' inhibits the use of the directory of the current + file directory as the first search directory for `#include "FILE"'. + *Note Search Path::. This option has been deprecated. + +`-nostdinc' + Do not search the standard system directories for header files. + Only the directories you have specified with `-I' options (and the + directory of the current file, if appropriate) are searched. + +`-nostdinc++' + Do not search for header files in the C++-specific standard + directories, but do still search the other standard directories. + (This option is used when building the C++ library.) + +`-include FILE' + Process FILE as if `#include "file"' appeared as the first line of + the primary source file. However, the first directory searched + for FILE is the preprocessor's working directory _instead of_ the + directory containing the main source file. If not found there, it + is searched for in the remainder of the `#include "..."' search + chain as normal. + + If multiple `-include' options are given, the files are included + in the order they appear on the command line. + +`-imacros FILE' + Exactly like `-include', except that any output produced by + scanning FILE is thrown away. Macros it defines remain defined. + This allows you to acquire all the macros from a header without + also processing its declarations. + + All files specified by `-imacros' are processed before all files + specified by `-include'. + +`-idirafter DIR' + Search DIR for header files, but do it _after_ all directories + specified with `-I' and the standard system directories have been + exhausted. DIR is treated as a system include directory. If DIR + begins with `=', then the `=' will be replaced by the sysroot + prefix; see `--sysroot' and `-isysroot'. + +`-iprefix PREFIX' + Specify PREFIX as the prefix for subsequent `-iwithprefix' + options. If the prefix represents a directory, you should include + the final `/'. + +`-iwithprefix DIR' +`-iwithprefixbefore DIR' + Append DIR to the prefix specified previously with `-iprefix', and + add the resulting directory to the include search path. + `-iwithprefixbefore' puts it in the same place `-I' would; + `-iwithprefix' puts it where `-idirafter' would. + +`-isysroot DIR' + This option is like the `--sysroot' option, but applies only to + header files (except for Darwin targets, where it applies to both + header files and libraries). See the `--sysroot' option for more + information. + +`-imultilib DIR' + Use DIR as a subdirectory of the directory containing + target-specific C++ headers. + +`-isystem DIR' + Search DIR for header files, after all directories specified by + `-I' but before the standard system directories. Mark it as a + system directory, so that it gets the same special treatment as is + applied to the standard system directories. *Note System + Headers::. If DIR begins with `=', then the `=' will be replaced + by the sysroot prefix; see `--sysroot' and `-isysroot'. + +`-iquote DIR' + Search DIR only for header files requested with `#include "FILE"'; + they are not searched for `#include ', before all + directories specified by `-I' and before the standard system + directories. *Note Search Path::. If DIR begins with `=', then + the `=' will be replaced by the sysroot prefix; see `--sysroot' + and `-isysroot'. + +`-fdirectives-only' + When preprocessing, handle directives, but do not expand macros. + + The option's behavior depends on the `-E' and `-fpreprocessed' + options. + + With `-E', preprocessing is limited to the handling of directives + such as `#define', `#ifdef', and `#error'. Other preprocessor + operations, such as macro expansion and trigraph conversion are + not performed. In addition, the `-dD' option is implicitly + enabled. + + With `-fpreprocessed', predefinition of command line and most + builtin macros is disabled. Macros such as `__LINE__', which are + contextually dependent, are handled normally. This enables + compilation of files previously preprocessed with `-E + -fdirectives-only'. + + With both `-E' and `-fpreprocessed', the rules for + `-fpreprocessed' take precedence. This enables full preprocessing + of files previously preprocessed with `-E -fdirectives-only'. + +`-fdollars-in-identifiers' + Accept `$' in identifiers. *Note Identifier characters::. + +`-fextended-identifiers' + Accept universal character names in identifiers. This option is + experimental; in a future version of GCC, it will be enabled by + default for C99 and C++. + +`-fpreprocessed' + Indicate to the preprocessor that the input file has already been + preprocessed. This suppresses things like macro expansion, + trigraph conversion, escaped newline splicing, and processing of + most directives. The preprocessor still recognizes and removes + comments, so that you can pass a file preprocessed with `-C' to + the compiler without problems. In this mode the integrated + preprocessor is little more than a tokenizer for the front ends. + + `-fpreprocessed' is implicit if the input file has one of the + extensions `.i', `.ii' or `.mi'. These are the extensions that + GCC uses for preprocessed files created by `-save-temps'. + +`-ftabstop=WIDTH' + Set the distance between tab stops. This helps the preprocessor + report correct column numbers in warnings or errors, even if tabs + appear on the line. If the value is less than 1 or greater than + 100, the option is ignored. The default is 8. + +`-fexec-charset=CHARSET' + Set the execution character set, used for string and character + constants. The default is UTF-8. CHARSET can be any encoding + supported by the system's `iconv' library routine. + +`-fwide-exec-charset=CHARSET' + Set the wide execution character set, used for wide string and + character constants. The default is UTF-32 or UTF-16, whichever + corresponds to the width of `wchar_t'. As with `-fexec-charset', + CHARSET can be any encoding supported by the system's `iconv' + library routine; however, you will have problems with encodings + that do not fit exactly in `wchar_t'. + +`-finput-charset=CHARSET' + Set the input character set, used for translation from the + character set of the input file to the source character set used + by GCC. If the locale does not specify, or GCC cannot get this + information from the locale, the default is UTF-8. This can be + overridden by either the locale or this command line option. + Currently the command line option takes precedence if there's a + conflict. CHARSET can be any encoding supported by the system's + `iconv' library routine. + +`-fworking-directory' + Enable generation of linemarkers in the preprocessor output that + will let the compiler know the current working directory at the + time of preprocessing. When this option is enabled, the + preprocessor will emit, after the initial linemarker, a second + linemarker with the current working directory followed by two + slashes. GCC will use this directory, when it's present in the + preprocessed input, as the directory emitted as the current + working directory in some debugging information formats. This + option is implicitly enabled if debugging information is enabled, + but this can be inhibited with the negated form + `-fno-working-directory'. If the `-P' flag is present in the + command line, this option has no effect, since no `#line' + directives are emitted whatsoever. + +`-fno-show-column' + Do not print column numbers in diagnostics. This may be necessary + if diagnostics are being scanned by a program that does not + understand the column numbers, such as `dejagnu'. + +`-A PREDICATE=ANSWER' + Make an assertion with the predicate PREDICATE and answer ANSWER. + This form is preferred to the older form `-A PREDICATE(ANSWER)', + which is still supported, because it does not use shell special + characters. *Note Obsolete Features::. + +`-A -PREDICATE=ANSWER' + Cancel an assertion with the predicate PREDICATE and answer ANSWER. + +`-dCHARS' + CHARS is a sequence of one or more of the following characters, + and must not be preceded by a space. Other characters are + interpreted by the compiler proper, or reserved for future + versions of GCC, and so are silently ignored. If you specify + characters whose behavior conflicts, the result is undefined. + + `M' + Instead of the normal output, generate a list of `#define' + directives for all the macros defined during the execution of + the preprocessor, including predefined macros. This gives + you a way of finding out what is predefined in your version + of the preprocessor. Assuming you have no file `foo.h', the + command + + touch foo.h; cpp -dM foo.h + + will show all the predefined macros. + + If you use `-dM' without the `-E' option, `-dM' is + interpreted as a synonym for `-fdump-rtl-mach'. *Note + Debugging Options: (gcc)Debugging Options. + + `D' + Like `M' except in two respects: it does _not_ include the + predefined macros, and it outputs _both_ the `#define' + directives and the result of preprocessing. Both kinds of + output go to the standard output file. + + `N' + Like `D', but emit only the macro names, not their expansions. + + `I' + Output `#include' directives in addition to the result of + preprocessing. + + `U' + Like `D' except that only macros that are expanded, or whose + definedness is tested in preprocessor directives, are output; + the output is delayed until the use or test of the macro; and + `#undef' directives are also output for macros tested but + undefined at the time. + +`-P' + Inhibit generation of linemarkers in the output from the + preprocessor. This might be useful when running the preprocessor + on something that is not C code, and will be sent to a program + which might be confused by the linemarkers. *Note Preprocessor + Output::. + +`-C' + Do not discard comments. All comments are passed through to the + output file, except for comments in processed directives, which + are deleted along with the directive. + + You should be prepared for side effects when using `-C'; it causes + the preprocessor to treat comments as tokens in their own right. + For example, comments appearing at the start of what would be a + directive line have the effect of turning that line into an + ordinary source line, since the first token on the line is no + longer a `#'. + +`-CC' + Do not discard comments, including during macro expansion. This is + like `-C', except that comments contained within macros are also + passed through to the output file where the macro is expanded. + + In addition to the side-effects of the `-C' option, the `-CC' + option causes all C++-style comments inside a macro to be + converted to C-style comments. This is to prevent later use of + that macro from inadvertently commenting out the remainder of the + source line. + + The `-CC' option is generally used to support lint comments. + +`-traditional-cpp' + Try to imitate the behavior of old-fashioned C preprocessors, as + opposed to ISO C preprocessors. *Note Traditional Mode::. + +`-trigraphs' + Process trigraph sequences. *Note Initial processing::. + +`-remap' + Enable special code to work around file systems which only permit + very short file names, such as MS-DOS. + +`--help' +`--target-help' + Print text describing all the command line options instead of + preprocessing anything. + +`-v' + Verbose mode. Print out GNU CPP's version number at the beginning + of execution, and report the final form of the include path. + +`-H' + Print the name of each header file used, in addition to other + normal activities. Each name is indented to show how deep in the + `#include' stack it is. Precompiled header files are also + printed, even if they are found to be invalid; an invalid + precompiled header file is printed with `...x' and a valid one + with `...!' . + +`-version' +`--version' + Print out GNU CPP's version number. With one dash, proceed to + preprocess as normal. With two dashes, exit immediately. + + +File: cpp.info, Node: Environment Variables, Next: GNU Free Documentation License, Prev: Invocation, Up: Top + +13 Environment Variables +************************ + +This section describes the environment variables that affect how CPP +operates. You can use them to specify directories or prefixes to use +when searching for include files, or to control dependency output. + + Note that you can also specify places to search using options such as +`-I', and control dependency output with options like `-M' (*note +Invocation::). These take precedence over environment variables, which +in turn take precedence over the configuration of GCC. + +`CPATH' +`C_INCLUDE_PATH' +`CPLUS_INCLUDE_PATH' +`OBJC_INCLUDE_PATH' + Each variable's value is a list of directories separated by a + special character, much like `PATH', in which to look for header + files. The special character, `PATH_SEPARATOR', is + target-dependent and determined at GCC build time. For Microsoft + Windows-based targets it is a semicolon, and for almost all other + targets it is a colon. + + `CPATH' specifies a list of directories to be searched as if + specified with `-I', but after any paths given with `-I' options + on the command line. This environment variable is used regardless + of which language is being preprocessed. + + The remaining environment variables apply only when preprocessing + the particular language indicated. Each specifies a list of + directories to be searched as if specified with `-isystem', but + after any paths given with `-isystem' options on the command line. + + In all these variables, an empty element instructs the compiler to + search its current working directory. Empty elements can appear + at the beginning or end of a path. For instance, if the value of + `CPATH' is `:/special/include', that has the same effect as + `-I. -I/special/include'. + + See also *note Search Path::. + +`DEPENDENCIES_OUTPUT' + If this variable is set, its value specifies how to output + dependencies for Make based on the non-system header files + processed by the compiler. System header files are ignored in the + dependency output. + + The value of `DEPENDENCIES_OUTPUT' can be just a file name, in + which case the Make rules are written to that file, guessing the + target name from the source file name. Or the value can have the + form `FILE TARGET', in which case the rules are written to file + FILE using TARGET as the target name. + + In other words, this environment variable is equivalent to + combining the options `-MM' and `-MF' (*note Invocation::), with + an optional `-MT' switch too. + +`SUNPRO_DEPENDENCIES' + This variable is the same as `DEPENDENCIES_OUTPUT' (see above), + except that system header files are not ignored, so it implies + `-M' rather than `-MM'. However, the dependence on the main input + file is omitted. *Note Invocation::. + + +File: cpp.info, Node: GNU Free Documentation License, Next: Index of Directives, Prev: Environment Variables, Up: Top + +GNU Free Documentation License +****************************** + + Version 1.3, 3 November 2008 + + Copyright (C) 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc. + `http://fsf.org/' + + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + + 0. PREAMBLE + + The purpose of this License is to make a manual, textbook, or other + functional and useful document "free" in the sense of freedom: to + assure everyone the effective freedom to copy and redistribute it, + with or without modifying it, either commercially or + noncommercially. Secondarily, this License preserves for the + author and publisher a way to get credit for their work, while not + being considered responsible for modifications made by others. + + This License is a kind of "copyleft", which means that derivative + works of the document must themselves be free in the same sense. + It complements the GNU General Public License, which is a copyleft + license designed for free software. + + We have designed this License in order to use it for manuals for + free software, because free software needs free documentation: a + free program should come with manuals providing the same freedoms + that the software does. But this License is not limited to + software manuals; it can be used for any textual work, regardless + of subject matter or whether it is published as a printed book. + We recommend this License principally for works whose purpose is + instruction or reference. + + 1. APPLICABILITY AND DEFINITIONS + + This License applies to any manual or other work, in any medium, + that contains a notice placed by the copyright holder saying it + can be distributed under the terms of this License. Such a notice + grants a world-wide, royalty-free license, unlimited in duration, + to use that work under the conditions stated herein. The + "Document", below, refers to any such manual or work. Any member + of the public is a licensee, and is addressed as "you". You + accept the license if you copy, modify or distribute the work in a + way requiring permission under copyright law. + + A "Modified Version" of the Document means any work containing the + Document or a portion of it, either copied verbatim, or with + modifications and/or translated into another language. + + A "Secondary Section" is a named appendix or a front-matter section + of the Document that deals exclusively with the relationship of the + publishers or authors of the Document to the Document's overall + subject (or to related matters) and contains nothing that could + fall directly within that overall subject. (Thus, if the Document + is in part a textbook of mathematics, a Secondary Section may not + explain any mathematics.) The relationship could be a matter of + historical connection with the subject or with related matters, or + of legal, commercial, philosophical, ethical or political position + regarding them. + + The "Invariant Sections" are certain Secondary Sections whose + titles are designated, as being those of Invariant Sections, in + the notice that says that the Document is released under this + License. If a section does not fit the above definition of + Secondary then it is not allowed to be designated as Invariant. + The Document may contain zero Invariant Sections. If the Document + does not identify any Invariant Sections then there are none. + + The "Cover Texts" are certain short passages of text that are + listed, as Front-Cover Texts or Back-Cover Texts, in the notice + that says that the Document is released under this License. A + Front-Cover Text may be at most 5 words, and a Back-Cover Text may + be at most 25 words. + + A "Transparent" copy of the Document means a machine-readable copy, + represented in a format whose specification is available to the + general public, that is suitable for revising the document + straightforwardly with generic text editors or (for images + composed of pixels) generic paint programs or (for drawings) some + widely available drawing editor, and that is suitable for input to + text formatters or for automatic translation to a variety of + formats suitable for input to text formatters. A copy made in an + otherwise Transparent file format whose markup, or absence of + markup, has been arranged to thwart or discourage subsequent + modification by readers is not Transparent. An image format is + not Transparent if used for any substantial amount of text. A + copy that is not "Transparent" is called "Opaque". + + Examples of suitable formats for Transparent copies include plain + ASCII without markup, Texinfo input format, LaTeX input format, + SGML or XML using a publicly available DTD, and + standard-conforming simple HTML, PostScript or PDF designed for + human modification. Examples of transparent image formats include + PNG, XCF and JPG. Opaque formats include proprietary formats that + can be read and edited only by proprietary word processors, SGML or + XML for which the DTD and/or processing tools are not generally + available, and the machine-generated HTML, PostScript or PDF + produced by some word processors for output purposes only. + + The "Title Page" means, for a printed book, the title page itself, + plus such following pages as are needed to hold, legibly, the + material this License requires to appear in the title page. For + works in formats which do not have any title page as such, "Title + Page" means the text near the most prominent appearance of the + work's title, preceding the beginning of the body of the text. + + The "publisher" means any person or entity that distributes copies + of the Document to the public. + + A section "Entitled XYZ" means a named subunit of the Document + whose title either is precisely XYZ or contains XYZ in parentheses + following text that translates XYZ in another language. (Here XYZ + stands for a specific section name mentioned below, such as + "Acknowledgements", "Dedications", "Endorsements", or "History".) + To "Preserve the Title" of such a section when you modify the + Document means that it remains a section "Entitled XYZ" according + to this definition. + + The Document may include Warranty Disclaimers next to the notice + which states that this License applies to the Document. These + Warranty Disclaimers are considered to be included by reference in + this License, but only as regards disclaiming warranties: any other + implication that these Warranty Disclaimers may have is void and + has no effect on the meaning of this License. + + 2. VERBATIM COPYING + + You may copy and distribute the Document in any medium, either + commercially or noncommercially, provided that this License, the + copyright notices, and the license notice saying this License + applies to the Document are reproduced in all copies, and that you + add no other conditions whatsoever to those of this License. You + may not use technical measures to obstruct or control the reading + or further copying of the copies you make or distribute. However, + you may accept compensation in exchange for copies. If you + distribute a large enough number of copies you must also follow + the conditions in section 3. + + You may also lend copies, under the same conditions stated above, + and you may publicly display copies. + + 3. COPYING IN QUANTITY + + If you publish printed copies (or copies in media that commonly + have printed covers) of the Document, numbering more than 100, and + the Document's license notice requires Cover Texts, you must + enclose the copies in covers that carry, clearly and legibly, all + these Cover Texts: Front-Cover Texts on the front cover, and + Back-Cover Texts on the back cover. Both covers must also clearly + and legibly identify you as the publisher of these copies. The + front cover must present the full title with all words of the + title equally prominent and visible. You may add other material + on the covers in addition. Copying with changes limited to the + covers, as long as they preserve the title of the Document and + satisfy these conditions, can be treated as verbatim copying in + other respects. + + If the required texts for either cover are too voluminous to fit + legibly, you should put the first ones listed (as many as fit + reasonably) on the actual cover, and continue the rest onto + adjacent pages. + + If you publish or distribute Opaque copies of the Document + numbering more than 100, you must either include a + machine-readable Transparent copy along with each Opaque copy, or + state in or with each Opaque copy a computer-network location from + which the general network-using public has access to download + using public-standard network protocols a complete Transparent + copy of the Document, free of added material. If you use the + latter option, you must take reasonably prudent steps, when you + begin distribution of Opaque copies in quantity, to ensure that + this Transparent copy will remain thus accessible at the stated + location until at least one year after the last time you + distribute an Opaque copy (directly or through your agents or + retailers) of that edition to the public. + + It is requested, but not required, that you contact the authors of + the Document well before redistributing any large number of + copies, to give them a chance to provide you with an updated + version of the Document. + + 4. MODIFICATIONS + + You may copy and distribute a Modified Version of the Document + under the conditions of sections 2 and 3 above, provided that you + release the Modified Version under precisely this License, with + the Modified Version filling the role of the Document, thus + licensing distribution and modification of the Modified Version to + whoever possesses a copy of it. In addition, you must do these + things in the Modified Version: + + A. Use in the Title Page (and on the covers, if any) a title + distinct from that of the Document, and from those of + previous versions (which should, if there were any, be listed + in the History section of the Document). You may use the + same title as a previous version if the original publisher of + that version gives permission. + + B. List on the Title Page, as authors, one or more persons or + entities responsible for authorship of the modifications in + the Modified Version, together with at least five of the + principal authors of the Document (all of its principal + authors, if it has fewer than five), unless they release you + from this requirement. + + C. State on the Title page the name of the publisher of the + Modified Version, as the publisher. + + D. Preserve all the copyright notices of the Document. + + E. Add an appropriate copyright notice for your modifications + adjacent to the other copyright notices. + + F. Include, immediately after the copyright notices, a license + notice giving the public permission to use the Modified + Version under the terms of this License, in the form shown in + the Addendum below. + + G. Preserve in that license notice the full lists of Invariant + Sections and required Cover Texts given in the Document's + license notice. + + H. Include an unaltered copy of this License. + + I. Preserve the section Entitled "History", Preserve its Title, + and add to it an item stating at least the title, year, new + authors, and publisher of the Modified Version as given on + the Title Page. If there is no section Entitled "History" in + the Document, create one stating the title, year, authors, + and publisher of the Document as given on its Title Page, + then add an item describing the Modified Version as stated in + the previous sentence. + + J. Preserve the network location, if any, given in the Document + for public access to a Transparent copy of the Document, and + likewise the network locations given in the Document for + previous versions it was based on. These may be placed in + the "History" section. You may omit a network location for a + work that was published at least four years before the + Document itself, or if the original publisher of the version + it refers to gives permission. + + K. For any section Entitled "Acknowledgements" or "Dedications", + Preserve the Title of the section, and preserve in the + section all the substance and tone of each of the contributor + acknowledgements and/or dedications given therein. + + L. Preserve all the Invariant Sections of the Document, + unaltered in their text and in their titles. Section numbers + or the equivalent are not considered part of the section + titles. + + M. Delete any section Entitled "Endorsements". Such a section + may not be included in the Modified Version. + + N. Do not retitle any existing section to be Entitled + "Endorsements" or to conflict in title with any Invariant + Section. + + O. Preserve any Warranty Disclaimers. + + If the Modified Version includes new front-matter sections or + appendices that qualify as Secondary Sections and contain no + material copied from the Document, you may at your option + designate some or all of these sections as invariant. To do this, + add their titles to the list of Invariant Sections in the Modified + Version's license notice. These titles must be distinct from any + other section titles. + + You may add a section Entitled "Endorsements", provided it contains + nothing but endorsements of your Modified Version by various + parties--for example, statements of peer review or that the text + has been approved by an organization as the authoritative + definition of a standard. + + You may add a passage of up to five words as a Front-Cover Text, + and a passage of up to 25 words as a Back-Cover Text, to the end + of the list of Cover Texts in the Modified Version. Only one + passage of Front-Cover Text and one of Back-Cover Text may be + added by (or through arrangements made by) any one entity. If the + Document already includes a cover text for the same cover, + previously added by you or by arrangement made by the same entity + you are acting on behalf of, you may not add another; but you may + replace the old one, on explicit permission from the previous + publisher that added the old one. + + The author(s) and publisher(s) of the Document do not by this + License give permission to use their names for publicity for or to + assert or imply endorsement of any Modified Version. + + 5. COMBINING DOCUMENTS + + You may combine the Document with other documents released under + this License, under the terms defined in section 4 above for + modified versions, provided that you include in the combination + all of the Invariant Sections of all of the original documents, + unmodified, and list them all as Invariant Sections of your + combined work in its license notice, and that you preserve all + their Warranty Disclaimers. + + The combined work need only contain one copy of this License, and + multiple identical Invariant Sections may be replaced with a single + copy. If there are multiple Invariant Sections with the same name + but different contents, make the title of each such section unique + by adding at the end of it, in parentheses, the name of the + original author or publisher of that section if known, or else a + unique number. Make the same adjustment to the section titles in + the list of Invariant Sections in the license notice of the + combined work. + + In the combination, you must combine any sections Entitled + "History" in the various original documents, forming one section + Entitled "History"; likewise combine any sections Entitled + "Acknowledgements", and any sections Entitled "Dedications". You + must delete all sections Entitled "Endorsements." + + 6. COLLECTIONS OF DOCUMENTS + + You may make a collection consisting of the Document and other + documents released under this License, and replace the individual + copies of this License in the various documents with a single copy + that is included in the collection, provided that you follow the + rules of this License for verbatim copying of each of the + documents in all other respects. + + You may extract a single document from such a collection, and + distribute it individually under this License, provided you insert + a copy of this License into the extracted document, and follow + this License in all other respects regarding verbatim copying of + that document. + + 7. AGGREGATION WITH INDEPENDENT WORKS + + A compilation of the Document or its derivatives with other + separate and independent documents or works, in or on a volume of + a storage or distribution medium, is called an "aggregate" if the + copyright resulting from the compilation is not used to limit the + legal rights of the compilation's users beyond what the individual + works permit. When the Document is included in an aggregate, this + License does not apply to the other works in the aggregate which + are not themselves derivative works of the Document. + + If the Cover Text requirement of section 3 is applicable to these + copies of the Document, then if the Document is less than one half + of the entire aggregate, the Document's Cover Texts may be placed + on covers that bracket the Document within the aggregate, or the + electronic equivalent of covers if the Document is in electronic + form. Otherwise they must appear on printed covers that bracket + the whole aggregate. + + 8. TRANSLATION + + Translation is considered a kind of modification, so you may + distribute translations of the Document under the terms of section + 4. Replacing Invariant Sections with translations requires special + permission from their copyright holders, but you may include + translations of some or all Invariant Sections in addition to the + original versions of these Invariant Sections. You may include a + translation of this License, and all the license notices in the + Document, and any Warranty Disclaimers, provided that you also + include the original English version of this License and the + original versions of those notices and disclaimers. In case of a + disagreement between the translation and the original version of + this License or a notice or disclaimer, the original version will + prevail. + + If a section in the Document is Entitled "Acknowledgements", + "Dedications", or "History", the requirement (section 4) to + Preserve its Title (section 1) will typically require changing the + actual title. + + 9. TERMINATION + + You may not copy, modify, sublicense, or distribute the Document + except as expressly provided under this License. Any attempt + otherwise to copy, modify, sublicense, or distribute it is void, + and will automatically terminate your rights under this License. + + However, if you cease all violation of this License, then your + license from a particular copyright holder is reinstated (a) + provisionally, unless and until the copyright holder explicitly + and finally terminates your license, and (b) permanently, if the + copyright holder fails to notify you of the violation by some + reasonable means prior to 60 days after the cessation. + + Moreover, your license from a particular copyright holder is + reinstated permanently if the copyright holder notifies you of the + violation by some reasonable means, this is the first time you have + received notice of violation of this License (for any work) from + that copyright holder, and you cure the violation prior to 30 days + after your receipt of the notice. + + Termination of your rights under this section does not terminate + the licenses of parties who have received copies or rights from + you under this License. If your rights have been terminated and + not permanently reinstated, receipt of a copy of some or all of + the same material does not give you any rights to use it. + + 10. FUTURE REVISIONS OF THIS LICENSE + + The Free Software Foundation may publish new, revised versions of + the GNU Free Documentation License from time to time. Such new + versions will be similar in spirit to the present version, but may + differ in detail to address new problems or concerns. See + `http://www.gnu.org/copyleft/'. + + Each version of the License is given a distinguishing version + number. If the Document specifies that a particular numbered + version of this License "or any later version" applies to it, you + have the option of following the terms and conditions either of + that specified version or of any later version that has been + published (not as a draft) by the Free Software Foundation. If + the Document does not specify a version number of this License, + you may choose any version ever published (not as a draft) by the + Free Software Foundation. If the Document specifies that a proxy + can decide which future versions of this License can be used, that + proxy's public statement of acceptance of a version permanently + authorizes you to choose that version for the Document. + + 11. RELICENSING + + "Massive Multiauthor Collaboration Site" (or "MMC Site") means any + World Wide Web server that publishes copyrightable works and also + provides prominent facilities for anybody to edit those works. A + public wiki that anybody can edit is an example of such a server. + A "Massive Multiauthor Collaboration" (or "MMC") contained in the + site means any set of copyrightable works thus published on the MMC + site. + + "CC-BY-SA" means the Creative Commons Attribution-Share Alike 3.0 + license published by Creative Commons Corporation, a not-for-profit + corporation with a principal place of business in San Francisco, + California, as well as future copyleft versions of that license + published by that same organization. + + "Incorporate" means to publish or republish a Document, in whole or + in part, as part of another Document. + + An MMC is "eligible for relicensing" if it is licensed under this + License, and if all works that were first published under this + License somewhere other than this MMC, and subsequently + incorporated in whole or in part into the MMC, (1) had no cover + texts or invariant sections, and (2) were thus incorporated prior + to November 1, 2008. + + The operator of an MMC Site may republish an MMC contained in the + site under CC-BY-SA on the same site at any time before August 1, + 2009, provided the MMC is eligible for relicensing. + + +ADDENDUM: How to use this License for your documents +==================================================== + +To use this License in a document you have written, include a copy of +the License in the document and put the following copyright and license +notices just after the title page: + + Copyright (C) YEAR YOUR NAME. + Permission is granted to copy, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.3 + or any later version published by the Free Software Foundation; + with no Invariant Sections, no Front-Cover Texts, and no Back-Cover + Texts. A copy of the license is included in the section entitled ``GNU + Free Documentation License''. + + If you have Invariant Sections, Front-Cover Texts and Back-Cover +Texts, replace the "with...Texts." line with this: + + with the Invariant Sections being LIST THEIR TITLES, with + the Front-Cover Texts being LIST, and with the Back-Cover Texts + being LIST. + + If you have Invariant Sections without Cover Texts, or some other +combination of the three, merge those two alternatives to suit the +situation. + + If your document contains nontrivial examples of program code, we +recommend releasing these examples in parallel under your choice of +free software license, such as the GNU General Public License, to +permit their use in free software. + + +File: cpp.info, Node: Index of Directives, Next: Option Index, Prev: GNU Free Documentation License, Up: Top + +Index of Directives +******************* + +[index] +* Menu: + +* #assert: Obsolete Features. (line 48) +* #define: Object-like Macros. (line 11) +* #elif: Elif. (line 6) +* #else: Else. (line 6) +* #endif: Ifdef. (line 6) +* #error: Diagnostics. (line 6) +* #ident: Other Directives. (line 6) +* #if: Conditional Syntax. (line 6) +* #ifdef: Ifdef. (line 6) +* #ifndef: Ifdef. (line 40) +* #import: Alternatives to Wrapper #ifndef. + (line 11) +* #include: Include Syntax. (line 6) +* #include_next: Wrapper Headers. (line 6) +* #line: Line Control. (line 20) +* #pragma GCC dependency: Pragmas. (line 55) +* #pragma GCC poison: Pragmas. (line 67) +* #pragma GCC system_header <1>: Pragmas. (line 94) +* #pragma GCC system_header: System Headers. (line 31) +* #sccs: Other Directives. (line 6) +* #unassert: Obsolete Features. (line 59) +* #undef: Undefining and Redefining Macros. + (line 6) +* #warning: Diagnostics. (line 27) + + +File: cpp.info, Node: Option Index, Next: Concept Index, Prev: Index of Directives, Up: Top + +Option Index +************ + +CPP's command line options and environment variables are indexed here +without any initial `-' or `--'. + +[index] +* Menu: + +* A: Invocation. (line 534) +* ansi: Invocation. (line 308) +* C: Invocation. (line 593) +* C_INCLUDE_PATH: Environment Variables. + (line 16) +* CPATH: Environment Variables. + (line 15) +* CPLUS_INCLUDE_PATH: Environment Variables. + (line 17) +* D: Invocation. (line 39) +* dD: Invocation. (line 566) +* DEPENDENCIES_OUTPUT: Environment Variables. + (line 44) +* dI: Invocation. (line 575) +* dM: Invocation. (line 550) +* dN: Invocation. (line 572) +* dU: Invocation. (line 579) +* fdirectives-only: Invocation. (line 442) +* fdollars-in-identifiers: Invocation. (line 464) +* fexec-charset: Invocation. (line 491) +* fextended-identifiers: Invocation. (line 467) +* finput-charset: Invocation. (line 504) +* fno-show-column: Invocation. (line 529) +* fno-working-directory: Invocation. (line 514) +* fpreprocessed: Invocation. (line 472) +* ftabstop: Invocation. (line 485) +* fwide-exec-charset: Invocation. (line 496) +* fworking-directory: Invocation. (line 514) +* H: Invocation. (line 638) +* help: Invocation. (line 630) +* I: Invocation. (line 71) +* I-: Invocation. (line 355) +* idirafter: Invocation. (line 397) +* imacros: Invocation. (line 388) +* imultilib: Invocation. (line 422) +* include: Invocation. (line 377) +* iprefix: Invocation. (line 404) +* iquote: Invocation. (line 434) +* isysroot: Invocation. (line 416) +* isystem: Invocation. (line 426) +* iwithprefix: Invocation. (line 410) +* iwithprefixbefore: Invocation. (line 410) +* M: Invocation. (line 180) +* MD: Invocation. (line 269) +* MF: Invocation. (line 215) +* MG: Invocation. (line 224) +* MM: Invocation. (line 205) +* MMD: Invocation. (line 285) +* MP: Invocation. (line 234) +* MQ: Invocation. (line 260) +* MT: Invocation. (line 246) +* nostdinc: Invocation. (line 367) +* nostdinc++: Invocation. (line 372) +* o: Invocation. (line 82) +* OBJC_INCLUDE_PATH: Environment Variables. + (line 18) +* P: Invocation. (line 586) +* pedantic: Invocation. (line 170) +* pedantic-errors: Invocation. (line 175) +* remap: Invocation. (line 625) +* std=: Invocation. (line 308) +* SUNPRO_DEPENDENCIES: Environment Variables. + (line 60) +* target-help: Invocation. (line 630) +* traditional-cpp: Invocation. (line 618) +* trigraphs: Invocation. (line 622) +* U: Invocation. (line 62) +* undef: Invocation. (line 66) +* v: Invocation. (line 634) +* version: Invocation. (line 647) +* w: Invocation. (line 166) +* Wall: Invocation. (line 88) +* Wcomment: Invocation. (line 96) +* Wcomments: Invocation. (line 96) +* Wendif-labels: Invocation. (line 143) +* Werror: Invocation. (line 156) +* Wsystem-headers: Invocation. (line 160) +* Wtraditional: Invocation. (line 113) +* Wtrigraphs: Invocation. (line 101) +* Wundef: Invocation. (line 119) +* Wunused-macros: Invocation. (line 124) +* x: Invocation. (line 292) + + +File: cpp.info, Node: Concept Index, Prev: Option Index, Up: Top + +Concept Index +************* + +[index] +* Menu: + +* # operator: Stringification. (line 6) +* ## operator: Concatenation. (line 6) +* _Pragma: Pragmas. (line 25) +* alternative tokens: Tokenization. (line 106) +* arguments: Macro Arguments. (line 6) +* arguments in macro definitions: Macro Arguments. (line 6) +* assertions: Obsolete Features. (line 13) +* assertions, canceling: Obsolete Features. (line 59) +* backslash-newline: Initial processing. (line 61) +* block comments: Initial processing. (line 77) +* C++ named operators: C++ Named Operators. (line 6) +* character constants: Tokenization. (line 85) +* character set, execution: Invocation. (line 491) +* character set, input: Invocation. (line 504) +* character set, wide execution: Invocation. (line 496) +* command line: Invocation. (line 6) +* commenting out code: Deleted Code. (line 6) +* comments: Initial processing. (line 77) +* common predefined macros: Common Predefined Macros. + (line 6) +* computed includes: Computed Includes. (line 6) +* concatenation: Concatenation. (line 6) +* conditional group: Ifdef. (line 14) +* conditionals: Conditionals. (line 6) +* continued lines: Initial processing. (line 61) +* controlling macro: Once-Only Headers. (line 35) +* defined: Defined. (line 6) +* dependencies for make as output: Environment Variables. + (line 45) +* dependencies, make: Invocation. (line 180) +* diagnostic: Diagnostics. (line 6) +* differences from previous versions: Differences from previous versions. + (line 6) +* digraphs: Tokenization. (line 106) +* directive line: The preprocessing language. + (line 6) +* directive name: The preprocessing language. + (line 6) +* directives: The preprocessing language. + (line 6) +* empty macro arguments: Macro Arguments. (line 66) +* environment variables: Environment Variables. + (line 6) +* expansion of arguments: Argument Prescan. (line 6) +* FDL, GNU Free Documentation License: GNU Free Documentation License. + (line 6) +* function-like macros: Function-like Macros. + (line 6) +* grouping options: Invocation. (line 34) +* guard macro: Once-Only Headers. (line 35) +* header file: Header Files. (line 6) +* header file names: Tokenization. (line 85) +* identifiers: Tokenization. (line 34) +* implementation limits: Implementation limits. + (line 6) +* implementation-defined behavior: Implementation-defined behavior. + (line 6) +* including just once: Once-Only Headers. (line 6) +* invocation: Invocation. (line 6) +* iso646.h: C++ Named Operators. (line 6) +* line comments: Initial processing. (line 77) +* line control: Line Control. (line 6) +* line endings: Initial processing. (line 14) +* linemarkers: Preprocessor Output. (line 28) +* macro argument expansion: Argument Prescan. (line 6) +* macro arguments and directives: Directives Within Macro Arguments. + (line 6) +* macros in include: Computed Includes. (line 6) +* macros with arguments: Macro Arguments. (line 6) +* macros with variable arguments: Variadic Macros. (line 6) +* make: Invocation. (line 180) +* manifest constants: Object-like Macros. (line 6) +* named operators: C++ Named Operators. (line 6) +* newlines in macro arguments: Newlines in Arguments. + (line 6) +* null directive: Other Directives. (line 15) +* numbers: Tokenization. (line 61) +* object-like macro: Object-like Macros. (line 6) +* options: Invocation. (line 38) +* options, grouping: Invocation. (line 34) +* other tokens: Tokenization. (line 120) +* output format: Preprocessor Output. (line 12) +* overriding a header file: Wrapper Headers. (line 6) +* parentheses in macro bodies: Operator Precedence Problems. + (line 6) +* pitfalls of macros: Macro Pitfalls. (line 6) +* predefined macros: Predefined Macros. (line 6) +* predefined macros, system-specific: System-specific Predefined Macros. + (line 6) +* predicates: Obsolete Features. (line 26) +* preprocessing directives: The preprocessing language. + (line 6) +* preprocessing numbers: Tokenization. (line 61) +* preprocessing tokens: Tokenization. (line 6) +* prescan of macro arguments: Argument Prescan. (line 6) +* problems with macros: Macro Pitfalls. (line 6) +* punctuators: Tokenization. (line 106) +* redefining macros: Undefining and Redefining Macros. + (line 6) +* repeated inclusion: Once-Only Headers. (line 6) +* reporting errors: Diagnostics. (line 6) +* reporting warnings: Diagnostics. (line 6) +* reserved namespace: System-specific Predefined Macros. + (line 6) +* self-reference: Self-Referential Macros. + (line 6) +* semicolons (after macro calls): Swallowing the Semicolon. + (line 6) +* side effects (in macro arguments): Duplication of Side Effects. + (line 6) +* standard predefined macros.: Standard Predefined Macros. + (line 6) +* string constants: Tokenization. (line 85) +* string literals: Tokenization. (line 85) +* stringification: Stringification. (line 6) +* symbolic constants: Object-like Macros. (line 6) +* system header files <1>: System Headers. (line 6) +* system header files: Header Files. (line 13) +* system-specific predefined macros: System-specific Predefined Macros. + (line 6) +* testing predicates: Obsolete Features. (line 37) +* token concatenation: Concatenation. (line 6) +* token pasting: Concatenation. (line 6) +* tokens: Tokenization. (line 6) +* trigraphs: Initial processing. (line 32) +* undefining macros: Undefining and Redefining Macros. + (line 6) +* unsafe macros: Duplication of Side Effects. + (line 6) +* variable number of arguments: Variadic Macros. (line 6) +* variadic macros: Variadic Macros. (line 6) +* wrapper #ifndef: Once-Only Headers. (line 6) +* wrapper headers: Wrapper Headers. (line 6) + + + +Tag Table: +Node: Top1118 +Node: Overview3850 +Node: Character sets6683 +Ref: Character sets-Footnote-18866 +Node: Initial processing9047 +Ref: trigraphs10606 +Node: Tokenization14808 +Ref: Tokenization-Footnote-121944 +Node: The preprocessing language22055 +Node: Header Files24933 +Node: Include Syntax26849 +Node: Include Operation28486 +Node: Search Path30334 +Node: Once-Only Headers33524 +Node: Alternatives to Wrapper #ifndef35183 +Node: Computed Includes36926 +Node: Wrapper Headers40084 +Node: System Headers42510 +Node: Macros44560 +Node: Object-like Macros45701 +Node: Function-like Macros49291 +Node: Macro Arguments50907 +Node: Stringification55052 +Node: Concatenation58258 +Node: Variadic Macros61366 +Node: Predefined Macros66153 +Node: Standard Predefined Macros66741 +Node: Common Predefined Macros72678 +Node: System-specific Predefined Macros90181 +Node: C++ Named Operators92202 +Node: Undefining and Redefining Macros93166 +Node: Directives Within Macro Arguments95270 +Node: Macro Pitfalls96818 +Node: Misnesting97351 +Node: Operator Precedence Problems98463 +Node: Swallowing the Semicolon100329 +Node: Duplication of Side Effects102352 +Node: Self-Referential Macros104535 +Node: Argument Prescan106944 +Node: Newlines in Arguments110698 +Node: Conditionals111649 +Node: Conditional Uses113479 +Node: Conditional Syntax114837 +Node: Ifdef115157 +Node: If118318 +Node: Defined120622 +Node: Else121905 +Node: Elif122475 +Node: Deleted Code123764 +Node: Diagnostics125011 +Node: Line Control126628 +Node: Pragmas130432 +Node: Other Directives134749 +Node: Preprocessor Output135799 +Node: Traditional Mode139000 +Node: Traditional lexical analysis140058 +Node: Traditional macros142561 +Node: Traditional miscellany146363 +Node: Traditional warnings147360 +Node: Implementation Details149557 +Node: Implementation-defined behavior150178 +Ref: Identifier characters150930 +Node: Implementation limits154008 +Node: Obsolete Features156682 +Node: Differences from previous versions159570 +Node: Invocation163778 +Ref: Wtrigraphs168230 +Ref: dashMF173005 +Ref: fdollars-in-identifiers182716 +Node: Environment Variables190879 +Node: GNU Free Documentation License193845 +Node: Index of Directives219009 +Node: Option Index220943 +Node: Concept Index227127 + +End Tag Table diff --git a/gcc/doc/cpp.texi b/gcc/doc/cpp.texi new file mode 100644 index 000000000..03cd00fa1 --- /dev/null +++ b/gcc/doc/cpp.texi @@ -0,0 +1,4472 @@ +\input texinfo +@setfilename cpp.info +@settitle The C Preprocessor +@setchapternewpage off +@c @smallbook +@c @cropmarks +@c @finalout + +@include gcc-common.texi + +@copying +@c man begin COPYRIGHT +Copyright @copyright{} 1987, 1989, 1991, 1992, 1993, 1994, 1995, 1996, +1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, +2008, 2009, 2010, 2011 +Free Software Foundation, Inc. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation. A copy of +the license is included in the +@c man end +section entitled ``GNU Free Documentation License''. +@ignore +@c man begin COPYRIGHT +man page gfdl(7). +@c man end +@end ignore + +@c man begin COPYRIGHT +This manual contains no Invariant Sections. The Front-Cover Texts are +(a) (see below), and the Back-Cover Texts are (b) (see below). + +(a) The FSF's Front-Cover Text is: + + A GNU Manual + +(b) The FSF's Back-Cover Text is: + + You have freedom to copy and modify this GNU Manual, like GNU + software. Copies published by the Free Software Foundation raise + funds for GNU development. +@c man end +@end copying + +@c Create a separate index for command line options. +@defcodeindex op +@syncodeindex vr op + +@c Used in cppopts.texi and cppenv.texi. +@set cppmanual + +@ifinfo +@dircategory Software development +@direntry +* Cpp: (cpp). The GNU C preprocessor. +@end direntry +@end ifinfo + +@titlepage +@title The C Preprocessor +@versionsubtitle +@author Richard M. Stallman, Zachary Weinberg +@page +@c There is a fill at the bottom of the page, so we need a filll to +@c override it. +@vskip 0pt plus 1filll +@insertcopying +@end titlepage +@contents +@page + +@ifnottex +@node Top +@top +The C preprocessor implements the macro language used to transform C, +C++, and Objective-C programs before they are compiled. It can also be +useful on its own. + +@menu +* Overview:: +* Header Files:: +* Macros:: +* Conditionals:: +* Diagnostics:: +* Line Control:: +* Pragmas:: +* Other Directives:: +* Preprocessor Output:: +* Traditional Mode:: +* Implementation Details:: +* Invocation:: +* Environment Variables:: +* GNU Free Documentation License:: +* Index of Directives:: +* Option Index:: +* Concept Index:: + +@detailmenu + --- The Detailed Node Listing --- + +Overview + +* Character sets:: +* Initial processing:: +* Tokenization:: +* The preprocessing language:: + +Header Files + +* Include Syntax:: +* Include Operation:: +* Search Path:: +* Once-Only Headers:: +* Alternatives to Wrapper #ifndef:: +* Computed Includes:: +* Wrapper Headers:: +* System Headers:: + +Macros + +* Object-like Macros:: +* Function-like Macros:: +* Macro Arguments:: +* Stringification:: +* Concatenation:: +* Variadic Macros:: +* Predefined Macros:: +* Undefining and Redefining Macros:: +* Directives Within Macro Arguments:: +* Macro Pitfalls:: + +Predefined Macros + +* Standard Predefined Macros:: +* Common Predefined Macros:: +* System-specific Predefined Macros:: +* C++ Named Operators:: + +Macro Pitfalls + +* Misnesting:: +* Operator Precedence Problems:: +* Swallowing the Semicolon:: +* Duplication of Side Effects:: +* Self-Referential Macros:: +* Argument Prescan:: +* Newlines in Arguments:: + +Conditionals + +* Conditional Uses:: +* Conditional Syntax:: +* Deleted Code:: + +Conditional Syntax + +* Ifdef:: +* If:: +* Defined:: +* Else:: +* Elif:: + +Implementation Details + +* Implementation-defined behavior:: +* Implementation limits:: +* Obsolete Features:: +* Differences from previous versions:: + +Obsolete Features + +* Obsolete Features:: + +@end detailmenu +@end menu + +@insertcopying +@end ifnottex + +@node Overview +@chapter Overview +@c man begin DESCRIPTION +The C preprocessor, often known as @dfn{cpp}, is a @dfn{macro processor} +that is used automatically by the C compiler to transform your program +before compilation. It is called a macro processor because it allows +you to define @dfn{macros}, which are brief abbreviations for longer +constructs. + +The C preprocessor is intended to be used only with C, C++, and +Objective-C source code. In the past, it has been abused as a general +text processor. It will choke on input which does not obey C's lexical +rules. For example, apostrophes will be interpreted as the beginning of +character constants, and cause errors. Also, you cannot rely on it +preserving characteristics of the input which are not significant to +C-family languages. If a Makefile is preprocessed, all the hard tabs +will be removed, and the Makefile will not work. + +Having said that, you can often get away with using cpp on things which +are not C@. Other Algol-ish programming languages are often safe +(Pascal, Ada, etc.) So is assembly, with caution. @option{-traditional-cpp} +mode preserves more white space, and is otherwise more permissive. Many +of the problems can be avoided by writing C or C++ style comments +instead of native language comments, and keeping macros simple. + +Wherever possible, you should use a preprocessor geared to the language +you are writing in. Modern versions of the GNU assembler have macro +facilities. Most high level programming languages have their own +conditional compilation and inclusion mechanism. If all else fails, +try a true general text processor, such as GNU M4. + +C preprocessors vary in some details. This manual discusses the GNU C +preprocessor, which provides a small superset of the features of ISO +Standard C@. In its default mode, the GNU C preprocessor does not do a +few things required by the standard. These are features which are +rarely, if ever, used, and may cause surprising changes to the meaning +of a program which does not expect them. To get strict ISO Standard C, +you should use the @option{-std=c90}, @option{-std=c99} or +@option{-std=c1x} options, depending +on which version of the standard you want. To get all the mandatory +diagnostics, you must also use @option{-pedantic}. @xref{Invocation}. + +This manual describes the behavior of the ISO preprocessor. To +minimize gratuitous differences, where the ISO preprocessor's +behavior does not conflict with traditional semantics, the +traditional preprocessor should behave the same way. The various +differences that do exist are detailed in the section @ref{Traditional +Mode}. + +For clarity, unless noted otherwise, references to @samp{CPP} in this +manual refer to GNU CPP@. +@c man end + +@menu +* Character sets:: +* Initial processing:: +* Tokenization:: +* The preprocessing language:: +@end menu + +@node Character sets +@section Character sets + +Source code character set processing in C and related languages is +rather complicated. The C standard discusses two character sets, but +there are really at least four. + +The files input to CPP might be in any character set at all. CPP's +very first action, before it even looks for line boundaries, is to +convert the file into the character set it uses for internal +processing. That set is what the C standard calls the @dfn{source} +character set. It must be isomorphic with ISO 10646, also known as +Unicode. CPP uses the UTF-8 encoding of Unicode. + +The character sets of the input files are specified using the +@option{-finput-charset=} option. + +All preprocessing work (the subject of the rest of this manual) is +carried out in the source character set. If you request textual +output from the preprocessor with the @option{-E} option, it will be +in UTF-8. + +After preprocessing is complete, string and character constants are +converted again, into the @dfn{execution} character set. This +character set is under control of the user; the default is UTF-8, +matching the source character set. Wide string and character +constants have their own character set, which is not called out +specifically in the standard. Again, it is under control of the user. +The default is UTF-16 or UTF-32, whichever fits in the target's +@code{wchar_t} type, in the target machine's byte +order.@footnote{UTF-16 does not meet the requirements of the C +standard for a wide character set, but the choice of 16-bit +@code{wchar_t} is enshrined in some system ABIs so we cannot fix +this.} Octal and hexadecimal escape sequences do not undergo +conversion; @t{'\x12'} has the value 0x12 regardless of the currently +selected execution character set. All other escapes are replaced by +the character in the source character set that they represent, then +converted to the execution character set, just like unescaped +characters. + +Unless the experimental @option{-fextended-identifiers} option is used, +GCC does not permit the use of characters outside the ASCII range, nor +@samp{\u} and @samp{\U} escapes, in identifiers. Even with that +option, characters outside the ASCII range can only be specified with +the @samp{\u} and @samp{\U} escapes, not used directly in identifiers. + +@node Initial processing +@section Initial processing + +The preprocessor performs a series of textual transformations on its +input. These happen before all other processing. Conceptually, they +happen in a rigid order, and the entire file is run through each +transformation before the next one begins. CPP actually does them +all at once, for performance reasons. These transformations correspond +roughly to the first three ``phases of translation'' described in the C +standard. + +@enumerate +@item +@cindex line endings +The input file is read into memory and broken into lines. + +Different systems use different conventions to indicate the end of a +line. GCC accepts the ASCII control sequences @kbd{LF}, @kbd{@w{CR +LF}} and @kbd{CR} as end-of-line markers. These are the canonical +sequences used by Unix, DOS and VMS, and the classic Mac OS (before +OSX) respectively. You may therefore safely copy source code written +on any of those systems to a different one and use it without +conversion. (GCC may lose track of the current line number if a file +doesn't consistently use one convention, as sometimes happens when it +is edited on computers with different conventions that share a network +file system.) + +If the last line of any input file lacks an end-of-line marker, the end +of the file is considered to implicitly supply one. The C standard says +that this condition provokes undefined behavior, so GCC will emit a +warning message. + +@item +@cindex trigraphs +@anchor{trigraphs}If trigraphs are enabled, they are replaced by their +corresponding single characters. By default GCC ignores trigraphs, +but if you request a strictly conforming mode with the @option{-std} +option, or you specify the @option{-trigraphs} option, then it +converts them. + +These are nine three-character sequences, all starting with @samp{??}, +that are defined by ISO C to stand for single characters. They permit +obsolete systems that lack some of C's punctuation to use C@. For +example, @samp{??/} stands for @samp{\}, so @t{'??/n'} is a character +constant for a newline. + +Trigraphs are not popular and many compilers implement them +incorrectly. Portable code should not rely on trigraphs being either +converted or ignored. With @option{-Wtrigraphs} GCC will warn you +when a trigraph may change the meaning of your program if it were +converted. @xref{Wtrigraphs}. + +In a string constant, you can prevent a sequence of question marks +from being confused with a trigraph by inserting a backslash between +the question marks, or by separating the string literal at the +trigraph and making use of string literal concatenation. @t{"(??\?)"} +is the string @samp{(???)}, not @samp{(?]}. Traditional C compilers +do not recognize these idioms. + +The nine trigraphs and their replacements are + +@smallexample +Trigraph: ??( ??) ??< ??> ??= ??/ ??' ??! ??- +Replacement: [ ] @{ @} # \ ^ | ~ +@end smallexample + +@item +@cindex continued lines +@cindex backslash-newline +Continued lines are merged into one long line. + +A continued line is a line which ends with a backslash, @samp{\}. The +backslash is removed and the following line is joined with the current +one. No space is inserted, so you may split a line anywhere, even in +the middle of a word. (It is generally more readable to split lines +only at white space.) + +The trailing backslash on a continued line is commonly referred to as a +@dfn{backslash-newline}. + +If there is white space between a backslash and the end of a line, that +is still a continued line. However, as this is usually the result of an +editing mistake, and many compilers will not accept it as a continued +line, GCC will warn you about it. + +@item +@cindex comments +@cindex line comments +@cindex block comments +All comments are replaced with single spaces. + +There are two kinds of comments. @dfn{Block comments} begin with +@samp{/*} and continue until the next @samp{*/}. Block comments do not +nest: + +@smallexample +/* @r{this is} /* @r{one comment} */ @r{text outside comment} +@end smallexample + +@dfn{Line comments} begin with @samp{//} and continue to the end of the +current line. Line comments do not nest either, but it does not matter, +because they would end in the same place anyway. + +@smallexample +// @r{this is} // @r{one comment} +@r{text outside comment} +@end smallexample +@end enumerate + +It is safe to put line comments inside block comments, or vice versa. + +@smallexample +@group +/* @r{block comment} + // @r{contains line comment} + @r{yet more comment} + */ @r{outside comment} + +// @r{line comment} /* @r{contains block comment} */ +@end group +@end smallexample + +But beware of commenting out one end of a block comment with a line +comment. + +@smallexample +@group + // @r{l.c.} /* @r{block comment begins} + @r{oops! this isn't a comment anymore} */ +@end group +@end smallexample + +Comments are not recognized within string literals. +@t{@w{"/* blah */"}} is the string constant @samp{@w{/* blah */}}, not +an empty string. + +Line comments are not in the 1989 edition of the C standard, but they +are recognized by GCC as an extension. In C++ and in the 1999 edition +of the C standard, they are an official part of the language. + +Since these transformations happen before all other processing, you can +split a line mechanically with backslash-newline anywhere. You can +comment out the end of a line. You can continue a line comment onto the +next line with backslash-newline. You can even split @samp{/*}, +@samp{*/}, and @samp{//} onto multiple lines with backslash-newline. +For example: + +@smallexample +@group +/\ +* +*/ # /* +*/ defi\ +ne FO\ +O 10\ +20 +@end group +@end smallexample + +@noindent +is equivalent to @code{@w{#define FOO 1020}}. All these tricks are +extremely confusing and should not be used in code intended to be +readable. + +There is no way to prevent a backslash at the end of a line from being +interpreted as a backslash-newline. This cannot affect any correct +program, however. + +@node Tokenization +@section Tokenization + +@cindex tokens +@cindex preprocessing tokens +After the textual transformations are finished, the input file is +converted into a sequence of @dfn{preprocessing tokens}. These mostly +correspond to the syntactic tokens used by the C compiler, but there are +a few differences. White space separates tokens; it is not itself a +token of any kind. Tokens do not have to be separated by white space, +but it is often necessary to avoid ambiguities. + +When faced with a sequence of characters that has more than one possible +tokenization, the preprocessor is greedy. It always makes each token, +starting from the left, as big as possible before moving on to the next +token. For instance, @code{a+++++b} is interpreted as +@code{@w{a ++ ++ + b}}, not as @code{@w{a ++ + ++ b}}, even though the +latter tokenization could be part of a valid C program and the former +could not. + +Once the input file is broken into tokens, the token boundaries never +change, except when the @samp{##} preprocessing operator is used to paste +tokens together. @xref{Concatenation}. For example, + +@smallexample +@group +#define foo() bar +foo()baz + @expansion{} bar baz +@emph{not} + @expansion{} barbaz +@end group +@end smallexample + +The compiler does not re-tokenize the preprocessor's output. Each +preprocessing token becomes one compiler token. + +@cindex identifiers +Preprocessing tokens fall into five broad classes: identifiers, +preprocessing numbers, string literals, punctuators, and other. An +@dfn{identifier} is the same as an identifier in C: any sequence of +letters, digits, or underscores, which begins with a letter or +underscore. Keywords of C have no significance to the preprocessor; +they are ordinary identifiers. You can define a macro whose name is a +keyword, for instance. The only identifier which can be considered a +preprocessing keyword is @code{defined}. @xref{Defined}. + +This is mostly true of other languages which use the C preprocessor. +However, a few of the keywords of C++ are significant even in the +preprocessor. @xref{C++ Named Operators}. + +In the 1999 C standard, identifiers may contain letters which are not +part of the ``basic source character set'', at the implementation's +discretion (such as accented Latin letters, Greek letters, or Chinese +ideograms). This may be done with an extended character set, or the +@samp{\u} and @samp{\U} escape sequences. The implementation of this +feature in GCC is experimental; such characters are only accepted in +the @samp{\u} and @samp{\U} forms and only if +@option{-fextended-identifiers} is used. + +As an extension, GCC treats @samp{$} as a letter. This is for +compatibility with some systems, such as VMS, where @samp{$} is commonly +used in system-defined function and object names. @samp{$} is not a +letter in strictly conforming mode, or if you specify the @option{-$} +option. @xref{Invocation}. + +@cindex numbers +@cindex preprocessing numbers +A @dfn{preprocessing number} has a rather bizarre definition. The +category includes all the normal integer and floating point constants +one expects of C, but also a number of other things one might not +initially recognize as a number. Formally, preprocessing numbers begin +with an optional period, a required decimal digit, and then continue +with any sequence of letters, digits, underscores, periods, and +exponents. Exponents are the two-character sequences @samp{e+}, +@samp{e-}, @samp{E+}, @samp{E-}, @samp{p+}, @samp{p-}, @samp{P+}, and +@samp{P-}. (The exponents that begin with @samp{p} or @samp{P} are new +to C99. They are used for hexadecimal floating-point constants.) + +The purpose of this unusual definition is to isolate the preprocessor +from the full complexity of numeric constants. It does not have to +distinguish between lexically valid and invalid floating-point numbers, +which is complicated. The definition also permits you to split an +identifier at any position and get exactly two tokens, which can then be +pasted back together with the @samp{##} operator. + +It's possible for preprocessing numbers to cause programs to be +misinterpreted. For example, @code{0xE+12} is a preprocessing number +which does not translate to any valid numeric constant, therefore a +syntax error. It does not mean @code{@w{0xE + 12}}, which is what you +might have intended. + +@cindex string literals +@cindex string constants +@cindex character constants +@cindex header file names +@c the @: prevents makeinfo from turning '' into ". +@dfn{String literals} are string constants, character constants, and +header file names (the argument of @samp{#include}).@footnote{The C +standard uses the term @dfn{string literal} to refer only to what we are +calling @dfn{string constants}.} String constants and character +constants are straightforward: @t{"@dots{}"} or @t{'@dots{}'}. In +either case embedded quotes should be escaped with a backslash: +@t{'\'@:'} is the character constant for @samp{'}. There is no limit on +the length of a character constant, but the value of a character +constant that contains more than one character is +implementation-defined. @xref{Implementation Details}. + +Header file names either look like string constants, @t{"@dots{}"}, or are +written with angle brackets instead, @t{<@dots{}>}. In either case, +backslash is an ordinary character. There is no way to escape the +closing quote or angle bracket. The preprocessor looks for the header +file in different places depending on which form you use. @xref{Include +Operation}. + +No string literal may extend past the end of a line. Older versions +of GCC accepted multi-line string constants. You may use continued +lines instead, or string constant concatenation. @xref{Differences +from previous versions}. + +@cindex punctuators +@cindex digraphs +@cindex alternative tokens +@dfn{Punctuators} are all the usual bits of punctuation which are +meaningful to C and C++. All but three of the punctuation characters in +ASCII are C punctuators. The exceptions are @samp{@@}, @samp{$}, and +@samp{`}. In addition, all the two- and three-character operators are +punctuators. There are also six @dfn{digraphs}, which the C++ standard +calls @dfn{alternative tokens}, which are merely alternate ways to spell +other punctuators. This is a second attempt to work around missing +punctuation in obsolete systems. It has no negative side effects, +unlike trigraphs, but does not cover as much ground. The digraphs and +their corresponding normal punctuators are: + +@smallexample +Digraph: <% %> <: :> %: %:%: +Punctuator: @{ @} [ ] # ## +@end smallexample + +@cindex other tokens +Any other single character is considered ``other''. It is passed on to +the preprocessor's output unmolested. The C compiler will almost +certainly reject source code containing ``other'' tokens. In ASCII, the +only other characters are @samp{@@}, @samp{$}, @samp{`}, and control +characters other than NUL (all bits zero). (Note that @samp{$} is +normally considered a letter.) All characters with the high bit set +(numeric range 0x7F--0xFF) are also ``other'' in the present +implementation. This will change when proper support for international +character sets is added to GCC@. + +NUL is a special case because of the high probability that its +appearance is accidental, and because it may be invisible to the user +(many terminals do not display NUL at all). Within comments, NULs are +silently ignored, just as any other character would be. In running +text, NUL is considered white space. For example, these two directives +have the same meaning. + +@smallexample +#define X^@@1 +#define X 1 +@end smallexample + +@noindent +(where @samp{^@@} is ASCII NUL)@. Within string or character constants, +NULs are preserved. In the latter two cases the preprocessor emits a +warning message. + +@node The preprocessing language +@section The preprocessing language +@cindex directives +@cindex preprocessing directives +@cindex directive line +@cindex directive name + +After tokenization, the stream of tokens may simply be passed straight +to the compiler's parser. However, if it contains any operations in the +@dfn{preprocessing language}, it will be transformed first. This stage +corresponds roughly to the standard's ``translation phase 4'' and is +what most people think of as the preprocessor's job. + +The preprocessing language consists of @dfn{directives} to be executed +and @dfn{macros} to be expanded. Its primary capabilities are: + +@itemize @bullet +@item +Inclusion of header files. These are files of declarations that can be +substituted into your program. + +@item +Macro expansion. You can define @dfn{macros}, which are abbreviations +for arbitrary fragments of C code. The preprocessor will replace the +macros with their definitions throughout the program. Some macros are +automatically defined for you. + +@item +Conditional compilation. You can include or exclude parts of the +program according to various conditions. + +@item +Line control. If you use a program to combine or rearrange source files +into an intermediate file which is then compiled, you can use line +control to inform the compiler where each source line originally came +from. + +@item +Diagnostics. You can detect problems at compile time and issue errors +or warnings. +@end itemize + +There are a few more, less useful, features. + +Except for expansion of predefined macros, all these operations are +triggered with @dfn{preprocessing directives}. Preprocessing directives +are lines in your program that start with @samp{#}. Whitespace is +allowed before and after the @samp{#}. The @samp{#} is followed by an +identifier, the @dfn{directive name}. It specifies the operation to +perform. Directives are commonly referred to as @samp{#@var{name}} +where @var{name} is the directive name. For example, @samp{#define} is +the directive that defines a macro. + +The @samp{#} which begins a directive cannot come from a macro +expansion. Also, the directive name is not macro expanded. Thus, if +@code{foo} is defined as a macro expanding to @code{define}, that does +not make @samp{#foo} a valid preprocessing directive. + +The set of valid directive names is fixed. Programs cannot define new +preprocessing directives. + +Some directives require arguments; these make up the rest of the +directive line and must be separated from the directive name by +whitespace. For example, @samp{#define} must be followed by a macro +name and the intended expansion of the macro. + +A preprocessing directive cannot cover more than one line. The line +may, however, be continued with backslash-newline, or by a block comment +which extends past the end of the line. In either case, when the +directive is processed, the continuations have already been merged with +the first line to make one long line. + +@node Header Files +@chapter Header Files + +@cindex header file +A header file is a file containing C declarations and macro definitions +(@pxref{Macros}) to be shared between several source files. You request +the use of a header file in your program by @dfn{including} it, with the +C preprocessing directive @samp{#include}. + +Header files serve two purposes. + +@itemize @bullet +@item +@cindex system header files +System header files declare the interfaces to parts of the operating +system. You include them in your program to supply the definitions and +declarations you need to invoke system calls and libraries. + +@item +Your own header files contain declarations for interfaces between the +source files of your program. Each time you have a group of related +declarations and macro definitions all or most of which are needed in +several different source files, it is a good idea to create a header +file for them. +@end itemize + +Including a header file produces the same results as copying the header +file into each source file that needs it. Such copying would be +time-consuming and error-prone. With a header file, the related +declarations appear in only one place. If they need to be changed, they +can be changed in one place, and programs that include the header file +will automatically use the new version when next recompiled. The header +file eliminates the labor of finding and changing all the copies as well +as the risk that a failure to find one copy will result in +inconsistencies within a program. + +In C, the usual convention is to give header files names that end with +@file{.h}. It is most portable to use only letters, digits, dashes, and +underscores in header file names, and at most one dot. + +@menu +* Include Syntax:: +* Include Operation:: +* Search Path:: +* Once-Only Headers:: +* Alternatives to Wrapper #ifndef:: +* Computed Includes:: +* Wrapper Headers:: +* System Headers:: +@end menu + +@node Include Syntax +@section Include Syntax + +@findex #include +Both user and system header files are included using the preprocessing +directive @samp{#include}. It has two variants: + +@table @code +@item #include <@var{file}> +This variant is used for system header files. It searches for a file +named @var{file} in a standard list of system directories. You can prepend +directories to this list with the @option{-I} option (@pxref{Invocation}). + +@item #include "@var{file}" +This variant is used for header files of your own program. It +searches for a file named @var{file} first in the directory containing +the current file, then in the quote directories and then the same +directories used for @code{<@var{file}>}. You can prepend directories +to the list of quote directories with the @option{-iquote} option. +@end table + +The argument of @samp{#include}, whether delimited with quote marks or +angle brackets, behaves like a string constant in that comments are not +recognized, and macro names are not expanded. Thus, @code{@w{#include +}} specifies inclusion of a system header file named @file{x/*y}. + +However, if backslashes occur within @var{file}, they are considered +ordinary text characters, not escape characters. None of the character +escape sequences appropriate to string constants in C are processed. +Thus, @code{@w{#include "x\n\\y"}} specifies a filename containing three +backslashes. (Some systems interpret @samp{\} as a pathname separator. +All of these also interpret @samp{/} the same way. It is most portable +to use only @samp{/}.) + +It is an error if there is anything (other than comments) on the line +after the file name. + +@node Include Operation +@section Include Operation + +The @samp{#include} directive works by directing the C preprocessor to +scan the specified file as input before continuing with the rest of the +current file. The output from the preprocessor contains the output +already generated, followed by the output resulting from the included +file, followed by the output that comes from the text after the +@samp{#include} directive. For example, if you have a header file +@file{header.h} as follows, + +@smallexample +char *test (void); +@end smallexample + +@noindent +and a main program called @file{program.c} that uses the header file, +like this, + +@smallexample +int x; +#include "header.h" + +int +main (void) +@{ + puts (test ()); +@} +@end smallexample + +@noindent +the compiler will see the same token stream as it would if +@file{program.c} read + +@smallexample +int x; +char *test (void); + +int +main (void) +@{ + puts (test ()); +@} +@end smallexample + +Included files are not limited to declarations and macro definitions; +those are merely the typical uses. Any fragment of a C program can be +included from another file. The include file could even contain the +beginning of a statement that is concluded in the containing file, or +the end of a statement that was started in the including file. However, +an included file must consist of complete tokens. Comments and string +literals which have not been closed by the end of an included file are +invalid. For error recovery, they are considered to end at the end of +the file. + +To avoid confusion, it is best if header files contain only complete +syntactic units---function declarations or definitions, type +declarations, etc. + +The line following the @samp{#include} directive is always treated as a +separate line by the C preprocessor, even if the included file lacks a +final newline. + +@node Search Path +@section Search Path + +GCC looks in several different places for headers. On a normal Unix +system, if you do not instruct it otherwise, it will look for headers +requested with @code{@w{#include <@var{file}>}} in: + +@smallexample +/usr/local/include +@var{libdir}/gcc/@var{target}/@var{version}/include +/usr/@var{target}/include +/usr/include +@end smallexample + +For C++ programs, it will also look in @file{/usr/include/g++-v3}, +first. In the above, @var{target} is the canonical name of the system +GCC was configured to compile code for; often but not always the same as +the canonical name of the system it runs on. @var{version} is the +version of GCC in use. + +You can add to this list with the @option{-I@var{dir}} command line +option. All the directories named by @option{-I} are searched, in +left-to-right order, @emph{before} the default directories. The only +exception is when @file{dir} is already searched by default. In +this case, the option is ignored and the search order for system +directories remains unchanged. + +Duplicate directories are removed from the quote and bracket search +chains before the two chains are merged to make the final search chain. +Thus, it is possible for a directory to occur twice in the final search +chain if it was specified in both the quote and bracket chains. + +You can prevent GCC from searching any of the default directories with +the @option{-nostdinc} option. This is useful when you are compiling an +operating system kernel or some other program that does not use the +standard C library facilities, or the standard C library itself. +@option{-I} options are not ignored as described above when +@option{-nostdinc} is in effect. + +GCC looks for headers requested with @code{@w{#include "@var{file}"}} +first in the directory containing the current file, then in the +directories as specified by @option{-iquote} options, then in the same +places it would have looked for a header requested with angle +brackets. For example, if @file{/usr/include/sys/stat.h} contains +@code{@w{#include "types.h"}}, GCC looks for @file{types.h} first in +@file{/usr/include/sys}, then in its usual search path. + +@samp{#line} (@pxref{Line Control}) does not change GCC's idea of the +directory containing the current file. + +You may put @option{-I-} at any point in your list of @option{-I} options. +This has two effects. First, directories appearing before the +@option{-I-} in the list are searched only for headers requested with +quote marks. Directories after @option{-I-} are searched for all +headers. Second, the directory containing the current file is not +searched for anything, unless it happens to be one of the directories +named by an @option{-I} switch. @option{-I-} is deprecated, @option{-iquote} +should be used instead. + +@option{-I. -I-} is not the same as no @option{-I} options at all, and does +not cause the same behavior for @samp{<>} includes that @samp{""} +includes get with no special options. @option{-I.} searches the +compiler's current working directory for header files. That may or may +not be the same as the directory containing the current file. + +If you need to look for headers in a directory named @file{-}, write +@option{-I./-}. + +There are several more ways to adjust the header search path. They are +generally less useful. @xref{Invocation}. + +@node Once-Only Headers +@section Once-Only Headers +@cindex repeated inclusion +@cindex including just once +@cindex wrapper @code{#ifndef} + +If a header file happens to be included twice, the compiler will process +its contents twice. This is very likely to cause an error, e.g.@: when the +compiler sees the same structure definition twice. Even if it does not, +it will certainly waste time. + +The standard way to prevent this is to enclose the entire real contents +of the file in a conditional, like this: + +@smallexample +@group +/* File foo. */ +#ifndef FILE_FOO_SEEN +#define FILE_FOO_SEEN + +@var{the entire file} + +#endif /* !FILE_FOO_SEEN */ +@end group +@end smallexample + +This construct is commonly known as a @dfn{wrapper #ifndef}. +When the header is included again, the conditional will be false, +because @code{FILE_FOO_SEEN} is defined. The preprocessor will skip +over the entire contents of the file, and the compiler will not see it +twice. + +CPP optimizes even further. It remembers when a header file has a +wrapper @samp{#ifndef}. If a subsequent @samp{#include} specifies that +header, and the macro in the @samp{#ifndef} is still defined, it does +not bother to rescan the file at all. + +You can put comments outside the wrapper. They will not interfere with +this optimization. + +@cindex controlling macro +@cindex guard macro +The macro @code{FILE_FOO_SEEN} is called the @dfn{controlling macro} or +@dfn{guard macro}. In a user header file, the macro name should not +begin with @samp{_}. In a system header file, it should begin with +@samp{__} to avoid conflicts with user programs. In any kind of header +file, the macro name should contain the name of the file and some +additional text, to avoid conflicts with other header files. + +@node Alternatives to Wrapper #ifndef +@section Alternatives to Wrapper #ifndef + +CPP supports two more ways of indicating that a header file should be +read only once. Neither one is as portable as a wrapper @samp{#ifndef} +and we recommend you do not use them in new programs, with the caveat +that @samp{#import} is standard practice in Objective-C. + +@findex #import +CPP supports a variant of @samp{#include} called @samp{#import} which +includes a file, but does so at most once. If you use @samp{#import} +instead of @samp{#include}, then you don't need the conditionals +inside the header file to prevent multiple inclusion of the contents. +@samp{#import} is standard in Objective-C, but is considered a +deprecated extension in C and C++. + +@samp{#import} is not a well designed feature. It requires the users of +a header file to know that it should only be included once. It is much +better for the header file's implementor to write the file so that users +don't need to know this. Using a wrapper @samp{#ifndef} accomplishes +this goal. + +In the present implementation, a single use of @samp{#import} will +prevent the file from ever being read again, by either @samp{#import} or +@samp{#include}. You should not rely on this; do not use both +@samp{#import} and @samp{#include} to refer to the same header file. + +Another way to prevent a header file from being included more than once +is with the @samp{#pragma once} directive. If @samp{#pragma once} is +seen when scanning a header file, that file will never be read again, no +matter what. + +@samp{#pragma once} does not have the problems that @samp{#import} does, +but it is not recognized by all preprocessors, so you cannot rely on it +in a portable program. + +@node Computed Includes +@section Computed Includes +@cindex computed includes +@cindex macros in include + +Sometimes it is necessary to select one of several different header +files to be included into your program. They might specify +configuration parameters to be used on different sorts of operating +systems, for instance. You could do this with a series of conditionals, + +@smallexample +#if SYSTEM_1 +# include "system_1.h" +#elif SYSTEM_2 +# include "system_2.h" +#elif SYSTEM_3 +@dots{} +#endif +@end smallexample + +That rapidly becomes tedious. Instead, the preprocessor offers the +ability to use a macro for the header name. This is called a +@dfn{computed include}. Instead of writing a header name as the direct +argument of @samp{#include}, you simply put a macro name there instead: + +@smallexample +#define SYSTEM_H "system_1.h" +@dots{} +#include SYSTEM_H +@end smallexample + +@noindent +@code{SYSTEM_H} will be expanded, and the preprocessor will look for +@file{system_1.h} as if the @samp{#include} had been written that way +originally. @code{SYSTEM_H} could be defined by your Makefile with a +@option{-D} option. + +You must be careful when you define the macro. @samp{#define} saves +tokens, not text. The preprocessor has no way of knowing that the macro +will be used as the argument of @samp{#include}, so it generates +ordinary tokens, not a header name. This is unlikely to cause problems +if you use double-quote includes, which are close enough to string +constants. If you use angle brackets, however, you may have trouble. + +The syntax of a computed include is actually a bit more general than the +above. If the first non-whitespace character after @samp{#include} is +not @samp{"} or @samp{<}, then the entire line is macro-expanded +like running text would be. + +If the line expands to a single string constant, the contents of that +string constant are the file to be included. CPP does not re-examine the +string for embedded quotes, but neither does it process backslash +escapes in the string. Therefore + +@smallexample +#define HEADER "a\"b" +#include HEADER +@end smallexample + +@noindent +looks for a file named @file{a\"b}. CPP searches for the file according +to the rules for double-quoted includes. + +If the line expands to a token stream beginning with a @samp{<} token +and including a @samp{>} token, then the tokens between the @samp{<} and +the first @samp{>} are combined to form the filename to be included. +Any whitespace between tokens is reduced to a single space; then any +space after the initial @samp{<} is retained, but a trailing space +before the closing @samp{>} is ignored. CPP searches for the file +according to the rules for angle-bracket includes. + +In either case, if there are any tokens on the line after the file name, +an error occurs and the directive is not processed. It is also an error +if the result of expansion does not match either of the two expected +forms. + +These rules are implementation-defined behavior according to the C +standard. To minimize the risk of different compilers interpreting your +computed includes differently, we recommend you use only a single +object-like macro which expands to a string constant. This will also +minimize confusion for people reading your program. + +@node Wrapper Headers +@section Wrapper Headers +@cindex wrapper headers +@cindex overriding a header file +@findex #include_next + +Sometimes it is necessary to adjust the contents of a system-provided +header file without editing it directly. GCC's @command{fixincludes} +operation does this, for example. One way to do that would be to create +a new header file with the same name and insert it in the search path +before the original header. That works fine as long as you're willing +to replace the old header entirely. But what if you want to refer to +the old header from the new one? + +You cannot simply include the old header with @samp{#include}. That +will start from the beginning, and find your new header again. If your +header is not protected from multiple inclusion (@pxref{Once-Only +Headers}), it will recurse infinitely and cause a fatal error. + +You could include the old header with an absolute pathname: +@smallexample +#include "/usr/include/old-header.h" +@end smallexample +@noindent +This works, but is not clean; should the system headers ever move, you +would have to edit the new headers to match. + +There is no way to solve this problem within the C standard, but you can +use the GNU extension @samp{#include_next}. It means, ``Include the +@emph{next} file with this name''. This directive works like +@samp{#include} except in searching for the specified file: it starts +searching the list of header file directories @emph{after} the directory +in which the current file was found. + +Suppose you specify @option{-I /usr/local/include}, and the list of +directories to search also includes @file{/usr/include}; and suppose +both directories contain @file{signal.h}. Ordinary @code{@w{#include +}} finds the file under @file{/usr/local/include}. If that +file contains @code{@w{#include_next }}, it starts searching +after that directory, and finds the file in @file{/usr/include}. + +@samp{#include_next} does not distinguish between @code{<@var{file}>} +and @code{"@var{file}"} inclusion, nor does it check that the file you +specify has the same name as the current file. It simply looks for the +file named, starting with the directory in the search path after the one +where the current file was found. + +The use of @samp{#include_next} can lead to great confusion. We +recommend it be used only when there is no other alternative. In +particular, it should not be used in the headers belonging to a specific +program; it should be used only to make global corrections along the +lines of @command{fixincludes}. + +@node System Headers +@section System Headers +@cindex system header files + +The header files declaring interfaces to the operating system and +runtime libraries often cannot be written in strictly conforming C@. +Therefore, GCC gives code found in @dfn{system headers} special +treatment. All warnings, other than those generated by @samp{#warning} +(@pxref{Diagnostics}), are suppressed while GCC is processing a system +header. Macros defined in a system header are immune to a few warnings +wherever they are expanded. This immunity is granted on an ad-hoc +basis, when we find that a warning generates lots of false positives +because of code in macros defined in system headers. + +Normally, only the headers found in specific directories are considered +system headers. These directories are determined when GCC is compiled. +There are, however, two ways to make normal headers into system headers. + +The @option{-isystem} command line option adds its argument to the list of +directories to search for headers, just like @option{-I}. Any headers +found in that directory will be considered system headers. + +All directories named by @option{-isystem} are searched @emph{after} all +directories named by @option{-I}, no matter what their order was on the +command line. If the same directory is named by both @option{-I} and +@option{-isystem}, the @option{-I} option is ignored. GCC provides an +informative message when this occurs if @option{-v} is used. + +@findex #pragma GCC system_header +There is also a directive, @code{@w{#pragma GCC system_header}}, which +tells GCC to consider the rest of the current include file a system +header, no matter where it was found. Code that comes before the +@samp{#pragma} in the file will not be affected. @code{@w{#pragma GCC +system_header}} has no effect in the primary source file. + +On very old systems, some of the pre-defined system header directories +get even more special treatment. GNU C++ considers code in headers +found in those directories to be surrounded by an @code{@w{extern "C"}} +block. There is no way to request this behavior with a @samp{#pragma}, +or from the command line. + +@node Macros +@chapter Macros + +A @dfn{macro} is a fragment of code which has been given a name. +Whenever the name is used, it is replaced by the contents of the macro. +There are two kinds of macros. They differ mostly in what they look +like when they are used. @dfn{Object-like} macros resemble data objects +when used, @dfn{function-like} macros resemble function calls. + +You may define any valid identifier as a macro, even if it is a C +keyword. The preprocessor does not know anything about keywords. This +can be useful if you wish to hide a keyword such as @code{const} from an +older compiler that does not understand it. However, the preprocessor +operator @code{defined} (@pxref{Defined}) can never be defined as a +macro, and C++'s named operators (@pxref{C++ Named Operators}) cannot be +macros when you are compiling C++. + +@menu +* Object-like Macros:: +* Function-like Macros:: +* Macro Arguments:: +* Stringification:: +* Concatenation:: +* Variadic Macros:: +* Predefined Macros:: +* Undefining and Redefining Macros:: +* Directives Within Macro Arguments:: +* Macro Pitfalls:: +@end menu + +@node Object-like Macros +@section Object-like Macros +@cindex object-like macro +@cindex symbolic constants +@cindex manifest constants + +An @dfn{object-like macro} is a simple identifier which will be replaced +by a code fragment. It is called object-like because it looks like a +data object in code that uses it. They are most commonly used to give +symbolic names to numeric constants. + +@findex #define +You create macros with the @samp{#define} directive. @samp{#define} is +followed by the name of the macro and then the token sequence it should +be an abbreviation for, which is variously referred to as the macro's +@dfn{body}, @dfn{expansion} or @dfn{replacement list}. For example, + +@smallexample +#define BUFFER_SIZE 1024 +@end smallexample + +@noindent +defines a macro named @code{BUFFER_SIZE} as an abbreviation for the +token @code{1024}. If somewhere after this @samp{#define} directive +there comes a C statement of the form + +@smallexample +foo = (char *) malloc (BUFFER_SIZE); +@end smallexample + +@noindent +then the C preprocessor will recognize and @dfn{expand} the macro +@code{BUFFER_SIZE}. The C compiler will see the same tokens as it would +if you had written + +@smallexample +foo = (char *) malloc (1024); +@end smallexample + +By convention, macro names are written in uppercase. Programs are +easier to read when it is possible to tell at a glance which names are +macros. + +The macro's body ends at the end of the @samp{#define} line. You may +continue the definition onto multiple lines, if necessary, using +backslash-newline. When the macro is expanded, however, it will all +come out on one line. For example, + +@smallexample +#define NUMBERS 1, \ + 2, \ + 3 +int x[] = @{ NUMBERS @}; + @expansion{} int x[] = @{ 1, 2, 3 @}; +@end smallexample + +@noindent +The most common visible consequence of this is surprising line numbers +in error messages. + +There is no restriction on what can go in a macro body provided it +decomposes into valid preprocessing tokens. Parentheses need not +balance, and the body need not resemble valid C code. (If it does not, +you may get error messages from the C compiler when you use the macro.) + +The C preprocessor scans your program sequentially. Macro definitions +take effect at the place you write them. Therefore, the following input +to the C preprocessor + +@smallexample +foo = X; +#define X 4 +bar = X; +@end smallexample + +@noindent +produces + +@smallexample +foo = X; +bar = 4; +@end smallexample + +When the preprocessor expands a macro name, the macro's expansion +replaces the macro invocation, then the expansion is examined for more +macros to expand. For example, + +@smallexample +@group +#define TABLESIZE BUFSIZE +#define BUFSIZE 1024 +TABLESIZE + @expansion{} BUFSIZE + @expansion{} 1024 +@end group +@end smallexample + +@noindent +@code{TABLESIZE} is expanded first to produce @code{BUFSIZE}, then that +macro is expanded to produce the final result, @code{1024}. + +Notice that @code{BUFSIZE} was not defined when @code{TABLESIZE} was +defined. The @samp{#define} for @code{TABLESIZE} uses exactly the +expansion you specify---in this case, @code{BUFSIZE}---and does not +check to see whether it too contains macro names. Only when you +@emph{use} @code{TABLESIZE} is the result of its expansion scanned for +more macro names. + +This makes a difference if you change the definition of @code{BUFSIZE} +at some point in the source file. @code{TABLESIZE}, defined as shown, +will always expand using the definition of @code{BUFSIZE} that is +currently in effect: + +@smallexample +#define BUFSIZE 1020 +#define TABLESIZE BUFSIZE +#undef BUFSIZE +#define BUFSIZE 37 +@end smallexample + +@noindent +Now @code{TABLESIZE} expands (in two stages) to @code{37}. + +If the expansion of a macro contains its own name, either directly or +via intermediate macros, it is not expanded again when the expansion is +examined for more macros. This prevents infinite recursion. +@xref{Self-Referential Macros}, for the precise details. + +@node Function-like Macros +@section Function-like Macros +@cindex function-like macros + +You can also define macros whose use looks like a function call. These +are called @dfn{function-like macros}. To define a function-like macro, +you use the same @samp{#define} directive, but you put a pair of +parentheses immediately after the macro name. For example, + +@smallexample +#define lang_init() c_init() +lang_init() + @expansion{} c_init() +@end smallexample + +A function-like macro is only expanded if its name appears with a pair +of parentheses after it. If you write just the name, it is left alone. +This can be useful when you have a function and a macro of the same +name, and you wish to use the function sometimes. + +@smallexample +extern void foo(void); +#define foo() /* @r{optimized inline version} */ +@dots{} + foo(); + funcptr = foo; +@end smallexample + +Here the call to @code{foo()} will use the macro, but the function +pointer will get the address of the real function. If the macro were to +be expanded, it would cause a syntax error. + +If you put spaces between the macro name and the parentheses in the +macro definition, that does not define a function-like macro, it defines +an object-like macro whose expansion happens to begin with a pair of +parentheses. + +@smallexample +#define lang_init () c_init() +lang_init() + @expansion{} () c_init()() +@end smallexample + +The first two pairs of parentheses in this expansion come from the +macro. The third is the pair that was originally after the macro +invocation. Since @code{lang_init} is an object-like macro, it does not +consume those parentheses. + +@node Macro Arguments +@section Macro Arguments +@cindex arguments +@cindex macros with arguments +@cindex arguments in macro definitions + +Function-like macros can take @dfn{arguments}, just like true functions. +To define a macro that uses arguments, you insert @dfn{parameters} +between the pair of parentheses in the macro definition that make the +macro function-like. The parameters must be valid C identifiers, +separated by commas and optionally whitespace. + +To invoke a macro that takes arguments, you write the name of the macro +followed by a list of @dfn{actual arguments} in parentheses, separated +by commas. The invocation of the macro need not be restricted to a +single logical line---it can cross as many lines in the source file as +you wish. The number of arguments you give must match the number of +parameters in the macro definition. When the macro is expanded, each +use of a parameter in its body is replaced by the tokens of the +corresponding argument. (You need not use all of the parameters in the +macro body.) + +As an example, here is a macro that computes the minimum of two numeric +values, as it is defined in many C programs, and some uses. + +@smallexample +#define min(X, Y) ((X) < (Y) ? (X) : (Y)) + x = min(a, b); @expansion{} x = ((a) < (b) ? (a) : (b)); + y = min(1, 2); @expansion{} y = ((1) < (2) ? (1) : (2)); + z = min(a + 28, *p); @expansion{} z = ((a + 28) < (*p) ? (a + 28) : (*p)); +@end smallexample + +@noindent +(In this small example you can already see several of the dangers of +macro arguments. @xref{Macro Pitfalls}, for detailed explanations.) + +Leading and trailing whitespace in each argument is dropped, and all +whitespace between the tokens of an argument is reduced to a single +space. Parentheses within each argument must balance; a comma within +such parentheses does not end the argument. However, there is no +requirement for square brackets or braces to balance, and they do not +prevent a comma from separating arguments. Thus, + +@smallexample +macro (array[x = y, x + 1]) +@end smallexample + +@noindent +passes two arguments to @code{macro}: @code{array[x = y} and @code{x + +1]}. If you want to supply @code{array[x = y, x + 1]} as an argument, +you can write it as @code{array[(x = y, x + 1)]}, which is equivalent C +code. + +All arguments to a macro are completely macro-expanded before they are +substituted into the macro body. After substitution, the complete text +is scanned again for macros to expand, including the arguments. This rule +may seem strange, but it is carefully designed so you need not worry +about whether any function call is actually a macro invocation. You can +run into trouble if you try to be too clever, though. @xref{Argument +Prescan}, for detailed discussion. + +For example, @code{min (min (a, b), c)} is first expanded to + +@smallexample + min (((a) < (b) ? (a) : (b)), (c)) +@end smallexample + +@noindent +and then to + +@smallexample +@group +((((a) < (b) ? (a) : (b))) < (c) + ? (((a) < (b) ? (a) : (b))) + : (c)) +@end group +@end smallexample + +@noindent +(Line breaks shown here for clarity would not actually be generated.) + +@cindex empty macro arguments +You can leave macro arguments empty; this is not an error to the +preprocessor (but many macros will then expand to invalid code). +You cannot leave out arguments entirely; if a macro takes two arguments, +there must be exactly one comma at the top level of its argument list. +Here are some silly examples using @code{min}: + +@smallexample +min(, b) @expansion{} (( ) < (b) ? ( ) : (b)) +min(a, ) @expansion{} ((a ) < ( ) ? (a ) : ( )) +min(,) @expansion{} (( ) < ( ) ? ( ) : ( )) +min((,),) @expansion{} (((,)) < ( ) ? ((,)) : ( )) + +min() @error{} macro "min" requires 2 arguments, but only 1 given +min(,,) @error{} macro "min" passed 3 arguments, but takes just 2 +@end smallexample + +Whitespace is not a preprocessing token, so if a macro @code{foo} takes +one argument, @code{@w{foo ()}} and @code{@w{foo ( )}} both supply it an +empty argument. Previous GNU preprocessor implementations and +documentation were incorrect on this point, insisting that a +function-like macro that takes a single argument be passed a space if an +empty argument was required. + +Macro parameters appearing inside string literals are not replaced by +their corresponding actual arguments. + +@smallexample +#define foo(x) x, "x" +foo(bar) @expansion{} bar, "x" +@end smallexample + +@node Stringification +@section Stringification +@cindex stringification +@cindex @samp{#} operator + +Sometimes you may want to convert a macro argument into a string +constant. Parameters are not replaced inside string constants, but you +can use the @samp{#} preprocessing operator instead. When a macro +parameter is used with a leading @samp{#}, the preprocessor replaces it +with the literal text of the actual argument, converted to a string +constant. Unlike normal parameter replacement, the argument is not +macro-expanded first. This is called @dfn{stringification}. + +There is no way to combine an argument with surrounding text and +stringify it all together. Instead, you can write a series of adjacent +string constants and stringified arguments. The preprocessor will +replace the stringified arguments with string constants. The C +compiler will then combine all the adjacent string constants into one +long string. + +Here is an example of a macro definition that uses stringification: + +@smallexample +@group +#define WARN_IF(EXP) \ +do @{ if (EXP) \ + fprintf (stderr, "Warning: " #EXP "\n"); @} \ +while (0) +WARN_IF (x == 0); + @expansion{} do @{ if (x == 0) + fprintf (stderr, "Warning: " "x == 0" "\n"); @} while (0); +@end group +@end smallexample + +@noindent +The argument for @code{EXP} is substituted once, as-is, into the +@code{if} statement, and once, stringified, into the argument to +@code{fprintf}. If @code{x} were a macro, it would be expanded in the +@code{if} statement, but not in the string. + +The @code{do} and @code{while (0)} are a kludge to make it possible to +write @code{WARN_IF (@var{arg});}, which the resemblance of +@code{WARN_IF} to a function would make C programmers want to do; see +@ref{Swallowing the Semicolon}. + +Stringification in C involves more than putting double-quote characters +around the fragment. The preprocessor backslash-escapes the quotes +surrounding embedded string constants, and all backslashes within string and +character constants, in order to get a valid C string constant with the +proper contents. Thus, stringifying @code{@w{p = "foo\n";}} results in +@t{@w{"p = \"foo\\n\";"}}. However, backslashes that are not inside string +or character constants are not duplicated: @samp{\n} by itself +stringifies to @t{"\n"}. + +All leading and trailing whitespace in text being stringified is +ignored. Any sequence of whitespace in the middle of the text is +converted to a single space in the stringified result. Comments are +replaced by whitespace long before stringification happens, so they +never appear in stringified text. + +There is no way to convert a macro argument into a character constant. + +If you want to stringify the result of expansion of a macro argument, +you have to use two levels of macros. + +@smallexample +#define xstr(s) str(s) +#define str(s) #s +#define foo 4 +str (foo) + @expansion{} "foo" +xstr (foo) + @expansion{} xstr (4) + @expansion{} str (4) + @expansion{} "4" +@end smallexample + +@code{s} is stringified when it is used in @code{str}, so it is not +macro-expanded first. But @code{s} is an ordinary argument to +@code{xstr}, so it is completely macro-expanded before @code{xstr} +itself is expanded (@pxref{Argument Prescan}). Therefore, by the time +@code{str} gets to its argument, it has already been macro-expanded. + +@node Concatenation +@section Concatenation +@cindex concatenation +@cindex token pasting +@cindex token concatenation +@cindex @samp{##} operator + +It is often useful to merge two tokens into one while expanding macros. +This is called @dfn{token pasting} or @dfn{token concatenation}. The +@samp{##} preprocessing operator performs token pasting. When a macro +is expanded, the two tokens on either side of each @samp{##} operator +are combined into a single token, which then replaces the @samp{##} and +the two original tokens in the macro expansion. Usually both will be +identifiers, or one will be an identifier and the other a preprocessing +number. When pasted, they make a longer identifier. This isn't the +only valid case. It is also possible to concatenate two numbers (or a +number and a name, such as @code{1.5} and @code{e3}) into a number. +Also, multi-character operators such as @code{+=} can be formed by +token pasting. + +However, two tokens that don't together form a valid token cannot be +pasted together. For example, you cannot concatenate @code{x} with +@code{+} in either order. If you try, the preprocessor issues a warning +and emits the two tokens. Whether it puts white space between the +tokens is undefined. It is common to find unnecessary uses of @samp{##} +in complex macros. If you get this warning, it is likely that you can +simply remove the @samp{##}. + +Both the tokens combined by @samp{##} could come from the macro body, +but you could just as well write them as one token in the first place. +Token pasting is most useful when one or both of the tokens comes from a +macro argument. If either of the tokens next to an @samp{##} is a +parameter name, it is replaced by its actual argument before @samp{##} +executes. As with stringification, the actual argument is not +macro-expanded first. If the argument is empty, that @samp{##} has no +effect. + +Keep in mind that the C preprocessor converts comments to whitespace +before macros are even considered. Therefore, you cannot create a +comment by concatenating @samp{/} and @samp{*}. You can put as much +whitespace between @samp{##} and its operands as you like, including +comments, and you can put comments in arguments that will be +concatenated. However, it is an error if @samp{##} appears at either +end of a macro body. + +Consider a C program that interprets named commands. There probably +needs to be a table of commands, perhaps an array of structures declared +as follows: + +@smallexample +@group +struct command +@{ + char *name; + void (*function) (void); +@}; +@end group + +@group +struct command commands[] = +@{ + @{ "quit", quit_command @}, + @{ "help", help_command @}, + @dots{} +@}; +@end group +@end smallexample + +It would be cleaner not to have to give each command name twice, once in +the string constant and once in the function name. A macro which takes the +name of a command as an argument can make this unnecessary. The string +constant can be created with stringification, and the function name by +concatenating the argument with @samp{_command}. Here is how it is done: + +@smallexample +#define COMMAND(NAME) @{ #NAME, NAME ## _command @} + +struct command commands[] = +@{ + COMMAND (quit), + COMMAND (help), + @dots{} +@}; +@end smallexample + +@node Variadic Macros +@section Variadic Macros +@cindex variable number of arguments +@cindex macros with variable arguments +@cindex variadic macros + +A macro can be declared to accept a variable number of arguments much as +a function can. The syntax for defining the macro is similar to that of +a function. Here is an example: + +@smallexample +#define eprintf(@dots{}) fprintf (stderr, __VA_ARGS__) +@end smallexample + +This kind of macro is called @dfn{variadic}. When the macro is invoked, +all the tokens in its argument list after the last named argument (this +macro has none), including any commas, become the @dfn{variable +argument}. This sequence of tokens replaces the identifier +@code{@w{__VA_ARGS__}} in the macro body wherever it appears. Thus, we +have this expansion: + +@smallexample +eprintf ("%s:%d: ", input_file, lineno) + @expansion{} fprintf (stderr, "%s:%d: ", input_file, lineno) +@end smallexample + +The variable argument is completely macro-expanded before it is inserted +into the macro expansion, just like an ordinary argument. You may use +the @samp{#} and @samp{##} operators to stringify the variable argument +or to paste its leading or trailing token with another token. (But see +below for an important special case for @samp{##}.) + +If your macro is complicated, you may want a more descriptive name for +the variable argument than @code{@w{__VA_ARGS__}}. CPP permits +this, as an extension. You may write an argument name immediately +before the @samp{@dots{}}; that name is used for the variable argument. +The @code{eprintf} macro above could be written + +@smallexample +#define eprintf(args@dots{}) fprintf (stderr, args) +@end smallexample + +@noindent +using this extension. You cannot use @code{@w{__VA_ARGS__}} and this +extension in the same macro. + +You can have named arguments as well as variable arguments in a variadic +macro. We could define @code{eprintf} like this, instead: + +@smallexample +#define eprintf(format, @dots{}) fprintf (stderr, format, __VA_ARGS__) +@end smallexample + +@noindent +This formulation looks more descriptive, but unfortunately it is less +flexible: you must now supply at least one argument after the format +string. In standard C, you cannot omit the comma separating the named +argument from the variable arguments. Furthermore, if you leave the +variable argument empty, you will get a syntax error, because +there will be an extra comma after the format string. + +@smallexample +eprintf("success!\n", ); + @expansion{} fprintf(stderr, "success!\n", ); +@end smallexample + +GNU CPP has a pair of extensions which deal with this problem. First, +you are allowed to leave the variable argument out entirely: + +@smallexample +eprintf ("success!\n") + @expansion{} fprintf(stderr, "success!\n", ); +@end smallexample + +@noindent +Second, the @samp{##} token paste operator has a special meaning when +placed between a comma and a variable argument. If you write + +@smallexample +#define eprintf(format, @dots{}) fprintf (stderr, format, ##__VA_ARGS__) +@end smallexample + +@noindent +and the variable argument is left out when the @code{eprintf} macro is +used, then the comma before the @samp{##} will be deleted. This does +@emph{not} happen if you pass an empty argument, nor does it happen if +the token preceding @samp{##} is anything other than a comma. + +@smallexample +eprintf ("success!\n") + @expansion{} fprintf(stderr, "success!\n"); +@end smallexample + +@noindent +The above explanation is ambiguous about the case where the only macro +parameter is a variable arguments parameter, as it is meaningless to +try to distinguish whether no argument at all is an empty argument or +a missing argument. In this case the C99 standard is clear that the +comma must remain, however the existing GCC extension used to swallow +the comma. So CPP retains the comma when conforming to a specific C +standard, and drops it otherwise. + +C99 mandates that the only place the identifier @code{@w{__VA_ARGS__}} +can appear is in the replacement list of a variadic macro. It may not +be used as a macro name, macro argument name, or within a different type +of macro. It may also be forbidden in open text; the standard is +ambiguous. We recommend you avoid using it except for its defined +purpose. + +Variadic macros are a new feature in C99. GNU CPP has supported them +for a long time, but only with a named variable argument +(@samp{args@dots{}}, not @samp{@dots{}} and @code{@w{__VA_ARGS__}}). If you are +concerned with portability to previous versions of GCC, you should use +only named variable arguments. On the other hand, if you are concerned +with portability to other conforming implementations of C99, you should +use only @code{@w{__VA_ARGS__}}. + +Previous versions of CPP implemented the comma-deletion extension +much more generally. We have restricted it in this release to minimize +the differences from C99. To get the same effect with both this and +previous versions of GCC, the token preceding the special @samp{##} must +be a comma, and there must be white space between that comma and +whatever comes immediately before it: + +@smallexample +#define eprintf(format, args@dots{}) fprintf (stderr, format , ##args) +@end smallexample + +@noindent +@xref{Differences from previous versions}, for the gory details. + +@node Predefined Macros +@section Predefined Macros + +@cindex predefined macros +Several object-like macros are predefined; you use them without +supplying their definitions. They fall into three classes: standard, +common, and system-specific. + +In C++, there is a fourth category, the named operators. They act like +predefined macros, but you cannot undefine them. + +@menu +* Standard Predefined Macros:: +* Common Predefined Macros:: +* System-specific Predefined Macros:: +* C++ Named Operators:: +@end menu + +@node Standard Predefined Macros +@subsection Standard Predefined Macros +@cindex standard predefined macros. + +The standard predefined macros are specified by the relevant +language standards, so they are available with all compilers that +implement those standards. Older compilers may not provide all of +them. Their names all start with double underscores. + +@table @code +@item __FILE__ +This macro expands to the name of the current input file, in the form of +a C string constant. This is the path by which the preprocessor opened +the file, not the short name specified in @samp{#include} or as the +input file name argument. For example, +@code{"/usr/local/include/myheader.h"} is a possible expansion of this +macro. + +@item __LINE__ +This macro expands to the current input line number, in the form of a +decimal integer constant. While we call it a predefined macro, it's +a pretty strange macro, since its ``definition'' changes with each +new line of source code. +@end table + +@code{__FILE__} and @code{__LINE__} are useful in generating an error +message to report an inconsistency detected by the program; the message +can state the source line at which the inconsistency was detected. For +example, + +@smallexample +fprintf (stderr, "Internal error: " + "negative string length " + "%d at %s, line %d.", + length, __FILE__, __LINE__); +@end smallexample + +An @samp{#include} directive changes the expansions of @code{__FILE__} +and @code{__LINE__} to correspond to the included file. At the end of +that file, when processing resumes on the input file that contained +the @samp{#include} directive, the expansions of @code{__FILE__} and +@code{__LINE__} revert to the values they had before the +@samp{#include} (but @code{__LINE__} is then incremented by one as +processing moves to the line after the @samp{#include}). + +A @samp{#line} directive changes @code{__LINE__}, and may change +@code{__FILE__} as well. @xref{Line Control}. + +C99 introduces @code{__func__}, and GCC has provided @code{__FUNCTION__} +for a long time. Both of these are strings containing the name of the +current function (there are slight semantic differences; see the GCC +manual). Neither of them is a macro; the preprocessor does not know the +name of the current function. They tend to be useful in conjunction +with @code{__FILE__} and @code{__LINE__}, though. + +@table @code + +@item __DATE__ +This macro expands to a string constant that describes the date on which +the preprocessor is being run. The string constant contains eleven +characters and looks like @code{@w{"Feb 12 1996"}}. If the day of the +month is less than 10, it is padded with a space on the left. + +If GCC cannot determine the current date, it will emit a warning message +(once per compilation) and @code{__DATE__} will expand to +@code{@w{"??? ?? ????"}}. + +@item __TIME__ +This macro expands to a string constant that describes the time at +which the preprocessor is being run. The string constant contains +eight characters and looks like @code{"23:59:01"}. + +If GCC cannot determine the current time, it will emit a warning message +(once per compilation) and @code{__TIME__} will expand to +@code{"??:??:??"}. + +@item __STDC__ +In normal operation, this macro expands to the constant 1, to signify +that this compiler conforms to ISO Standard C@. If GNU CPP is used with +a compiler other than GCC, this is not necessarily true; however, the +preprocessor always conforms to the standard unless the +@option{-traditional-cpp} option is used. + +This macro is not defined if the @option{-traditional-cpp} option is used. + +On some hosts, the system compiler uses a different convention, where +@code{__STDC__} is normally 0, but is 1 if the user specifies strict +conformance to the C Standard. CPP follows the host convention when +processing system header files, but when processing user files +@code{__STDC__} is always 1. This has been reported to cause problems; +for instance, some versions of Solaris provide X Windows headers that +expect @code{__STDC__} to be either undefined or 1. @xref{Invocation}. + +@item __STDC_VERSION__ +This macro expands to the C Standard's version number, a long integer +constant of the form @code{@var{yyyy}@var{mm}L} where @var{yyyy} and +@var{mm} are the year and month of the Standard version. This signifies +which version of the C Standard the compiler conforms to. Like +@code{__STDC__}, this is not necessarily accurate for the entire +implementation, unless GNU CPP is being used with GCC@. + +The value @code{199409L} signifies the 1989 C standard as amended in +1994, which is the current default; the value @code{199901L} signifies +the 1999 revision of the C standard. Support for the 1999 revision is +not yet complete. + +This macro is not defined if the @option{-traditional-cpp} option is +used, nor when compiling C++ or Objective-C@. + +@item __STDC_HOSTED__ +This macro is defined, with value 1, if the compiler's target is a +@dfn{hosted environment}. A hosted environment has the complete +facilities of the standard C library available. + +@item __cplusplus +This macro is defined when the C++ compiler is in use. You can use +@code{__cplusplus} to test whether a header is compiled by a C compiler +or a C++ compiler. This macro is similar to @code{__STDC_VERSION__}, in +that it expands to a version number. A fully conforming implementation +of the 1998 C++ standard will define this macro to @code{199711L}. The +GNU C++ compiler is not yet fully conforming, so it uses @code{1} +instead. It is hoped to complete the implementation of standard C++ +in the near future. + +@item __OBJC__ +This macro is defined, with value 1, when the Objective-C compiler is in +use. You can use @code{__OBJC__} to test whether a header is compiled +by a C compiler or an Objective-C compiler. + +@item __ASSEMBLER__ +This macro is defined with value 1 when preprocessing assembly +language. + +@end table + +@node Common Predefined Macros +@subsection Common Predefined Macros +@cindex common predefined macros + +The common predefined macros are GNU C extensions. They are available +with the same meanings regardless of the machine or operating system on +which you are using GNU C or GNU Fortran. Their names all start with +double underscores. + +@table @code + +@item __COUNTER__ +This macro expands to sequential integral values starting from 0. In +conjunction with the @code{##} operator, this provides a convenient means to +generate unique identifiers. Care must be taken to ensure that +@code{__COUNTER__} is not expanded prior to inclusion of precompiled headers +which use it. Otherwise, the precompiled headers will not be used. + +@item __GFORTRAN__ +The GNU Fortran compiler defines this. + +@item __GNUC__ +@itemx __GNUC_MINOR__ +@itemx __GNUC_PATCHLEVEL__ +These macros are defined by all GNU compilers that use the C +preprocessor: C, C++, Objective-C and Fortran. Their values are the major +version, minor version, and patch level of the compiler, as integer +constants. For example, GCC 3.2.1 will define @code{__GNUC__} to 3, +@code{__GNUC_MINOR__} to 2, and @code{__GNUC_PATCHLEVEL__} to 1. These +macros are also defined if you invoke the preprocessor directly. + +@code{__GNUC_PATCHLEVEL__} is new to GCC 3.0; it is also present in the +widely-used development snapshots leading up to 3.0 (which identify +themselves as GCC 2.96 or 2.97, depending on which snapshot you have). + +If all you need to know is whether or not your program is being compiled +by GCC, or a non-GCC compiler that claims to accept the GNU C dialects, +you can simply test @code{__GNUC__}. If you need to write code +which depends on a specific version, you must be more careful. Each +time the minor version is increased, the patch level is reset to zero; +each time the major version is increased (which happens rarely), the +minor version and patch level are reset. If you wish to use the +predefined macros directly in the conditional, you will need to write it +like this: + +@smallexample +/* @r{Test for GCC > 3.2.0} */ +#if __GNUC__ > 3 || \ + (__GNUC__ == 3 && (__GNUC_MINOR__ > 2 || \ + (__GNUC_MINOR__ == 2 && \ + __GNUC_PATCHLEVEL__ > 0)) +@end smallexample + +@noindent +Another approach is to use the predefined macros to +calculate a single number, then compare that against a threshold: + +@smallexample +#define GCC_VERSION (__GNUC__ * 10000 \ + + __GNUC_MINOR__ * 100 \ + + __GNUC_PATCHLEVEL__) +@dots{} +/* @r{Test for GCC > 3.2.0} */ +#if GCC_VERSION > 30200 +@end smallexample + +@noindent +Many people find this form easier to understand. + +@item __GNUG__ +The GNU C++ compiler defines this. Testing it is equivalent to +testing @code{@w{(__GNUC__ && __cplusplus)}}. + +@item __STRICT_ANSI__ +GCC defines this macro if and only if the @option{-ansi} switch, or a +@option{-std} switch specifying strict conformance to some version of ISO C, +was specified when GCC was invoked. It is defined to @samp{1}. +This macro exists primarily to direct GNU libc's header files to +restrict their definitions to the minimal set found in the 1989 C +standard. + +@item __BASE_FILE__ +This macro expands to the name of the main input file, in the form +of a C string constant. This is the source file that was specified +on the command line of the preprocessor or C compiler. + +@item __INCLUDE_LEVEL__ +This macro expands to a decimal integer constant that represents the +depth of nesting in include files. The value of this macro is +incremented on every @samp{#include} directive and decremented at the +end of every included file. It starts out at 0, its value within the +base file specified on the command line. + +@item __ELF__ +This macro is defined if the target uses the ELF object format. + +@item __VERSION__ +This macro expands to a string constant which describes the version of +the compiler in use. You should not rely on its contents having any +particular form, but it can be counted on to contain at least the +release number. + +@item __OPTIMIZE__ +@itemx __OPTIMIZE_SIZE__ +@itemx __NO_INLINE__ +These macros describe the compilation mode. @code{__OPTIMIZE__} is +defined in all optimizing compilations. @code{__OPTIMIZE_SIZE__} is +defined if the compiler is optimizing for size, not speed. +@code{__NO_INLINE__} is defined if no functions will be inlined into +their callers (when not optimizing, or when inlining has been +specifically disabled by @option{-fno-inline}). + +These macros cause certain GNU header files to provide optimized +definitions, using macros or inline functions, of system library +functions. You should not use these macros in any way unless you make +sure that programs will execute with the same effect whether or not they +are defined. If they are defined, their value is 1. + +@item __GNUC_GNU_INLINE__ +GCC defines this macro if functions declared @code{inline} will be +handled in GCC's traditional gnu90 mode. Object files will contain +externally visible definitions of all functions declared @code{inline} +without @code{extern} or @code{static}. They will not contain any +definitions of any functions declared @code{extern inline}. + +@item __GNUC_STDC_INLINE__ +GCC defines this macro if functions declared @code{inline} will be +handled according to the ISO C99 standard. Object files will contain +externally visible definitions of all functions declared @code{extern +inline}. They will not contain definitions of any functions declared +@code{inline} without @code{extern}. + +If this macro is defined, GCC supports the @code{gnu_inline} function +attribute as a way to always get the gnu90 behavior. Support for +this and @code{__GNUC_GNU_INLINE__} was added in GCC 4.1.3. If +neither macro is defined, an older version of GCC is being used: +@code{inline} functions will be compiled in gnu90 mode, and the +@code{gnu_inline} function attribute will not be recognized. + +@item __CHAR_UNSIGNED__ +GCC defines this macro if and only if the data type @code{char} is +unsigned on the target machine. It exists to cause the standard header +file @file{limits.h} to work correctly. You should not use this macro +yourself; instead, refer to the standard macros defined in @file{limits.h}. + +@item __WCHAR_UNSIGNED__ +Like @code{__CHAR_UNSIGNED__}, this macro is defined if and only if the +data type @code{wchar_t} is unsigned and the front-end is in C++ mode. + +@item __REGISTER_PREFIX__ +This macro expands to a single token (not a string constant) which is +the prefix applied to CPU register names in assembly language for this +target. You can use it to write assembly that is usable in multiple +environments. For example, in the @code{m68k-aout} environment it +expands to nothing, but in the @code{m68k-coff} environment it expands +to a single @samp{%}. + +@item __USER_LABEL_PREFIX__ +This macro expands to a single token which is the prefix applied to +user labels (symbols visible to C code) in assembly. For example, in +the @code{m68k-aout} environment it expands to an @samp{_}, but in the +@code{m68k-coff} environment it expands to nothing. + +This macro will have the correct definition even if +@option{-f(no-)underscores} is in use, but it will not be correct if +target-specific options that adjust this prefix are used (e.g.@: the +OSF/rose @option{-mno-underscores} option). + +@item __SIZE_TYPE__ +@itemx __PTRDIFF_TYPE__ +@itemx __WCHAR_TYPE__ +@itemx __WINT_TYPE__ +@itemx __INTMAX_TYPE__ +@itemx __UINTMAX_TYPE__ +@itemx __SIG_ATOMIC_TYPE__ +@itemx __INT8_TYPE__ +@itemx __INT16_TYPE__ +@itemx __INT32_TYPE__ +@itemx __INT64_TYPE__ +@itemx __UINT8_TYPE__ +@itemx __UINT16_TYPE__ +@itemx __UINT32_TYPE__ +@itemx __UINT64_TYPE__ +@itemx __INT_LEAST8_TYPE__ +@itemx __INT_LEAST16_TYPE__ +@itemx __INT_LEAST32_TYPE__ +@itemx __INT_LEAST64_TYPE__ +@itemx __UINT_LEAST8_TYPE__ +@itemx __UINT_LEAST16_TYPE__ +@itemx __UINT_LEAST32_TYPE__ +@itemx __UINT_LEAST64_TYPE__ +@itemx __INT_FAST8_TYPE__ +@itemx __INT_FAST16_TYPE__ +@itemx __INT_FAST32_TYPE__ +@itemx __INT_FAST64_TYPE__ +@itemx __UINT_FAST8_TYPE__ +@itemx __UINT_FAST16_TYPE__ +@itemx __UINT_FAST32_TYPE__ +@itemx __UINT_FAST64_TYPE__ +@itemx __INTPTR_TYPE__ +@itemx __UINTPTR_TYPE__ +These macros are defined to the correct underlying types for the +@code{size_t}, @code{ptrdiff_t}, @code{wchar_t}, @code{wint_t}, +@code{intmax_t}, @code{uintmax_t}, @code{sig_atomic_t}, @code{int8_t}, +@code{int16_t}, @code{int32_t}, @code{int64_t}, @code{uint8_t}, +@code{uint16_t}, @code{uint32_t}, @code{uint64_t}, +@code{int_least8_t}, @code{int_least16_t}, @code{int_least32_t}, +@code{int_least64_t}, @code{uint_least8_t}, @code{uint_least16_t}, +@code{uint_least32_t}, @code{uint_least64_t}, @code{int_fast8_t}, +@code{int_fast16_t}, @code{int_fast32_t}, @code{int_fast64_t}, +@code{uint_fast8_t}, @code{uint_fast16_t}, @code{uint_fast32_t}, +@code{uint_fast64_t}, @code{intptr_t}, and @code{uintptr_t} typedefs, +respectively. They exist to make the standard header files +@file{stddef.h}, @file{stdint.h}, and @file{wchar.h} work correctly. +You should not use these macros directly; instead, include the +appropriate headers and use the typedefs. Some of these macros may +not be defined on particular systems if GCC does not provide a +@file{stdint.h} header on those systems. + +@item __CHAR_BIT__ +Defined to the number of bits used in the representation of the +@code{char} data type. It exists to make the standard header given +numerical limits work correctly. You should not use +this macro directly; instead, include the appropriate headers. + +@item __SCHAR_MAX__ +@itemx __WCHAR_MAX__ +@itemx __SHRT_MAX__ +@itemx __INT_MAX__ +@itemx __LONG_MAX__ +@itemx __LONG_LONG_MAX__ +@itemx __WINT_MAX__ +@itemx __SIZE_MAX__ +@itemx __PTRDIFF_MAX__ +@itemx __INTMAX_MAX__ +@itemx __UINTMAX_MAX__ +@itemx __SIG_ATOMIC_MAX__ +@itemx __INT8_MAX__ +@itemx __INT16_MAX__ +@itemx __INT32_MAX__ +@itemx __INT64_MAX__ +@itemx __UINT8_MAX__ +@itemx __UINT16_MAX__ +@itemx __UINT32_MAX__ +@itemx __UINT64_MAX__ +@itemx __INT_LEAST8_MAX__ +@itemx __INT_LEAST16_MAX__ +@itemx __INT_LEAST32_MAX__ +@itemx __INT_LEAST64_MAX__ +@itemx __UINT_LEAST8_MAX__ +@itemx __UINT_LEAST16_MAX__ +@itemx __UINT_LEAST32_MAX__ +@itemx __UINT_LEAST64_MAX__ +@itemx __INT_FAST8_MAX__ +@itemx __INT_FAST16_MAX__ +@itemx __INT_FAST32_MAX__ +@itemx __INT_FAST64_MAX__ +@itemx __UINT_FAST8_MAX__ +@itemx __UINT_FAST16_MAX__ +@itemx __UINT_FAST32_MAX__ +@itemx __UINT_FAST64_MAX__ +@itemx __INTPTR_MAX__ +@itemx __UINTPTR_MAX__ +@itemx __WCHAR_MIN__ +@itemx __WINT_MIN__ +@itemx __SIG_ATOMIC_MIN__ +Defined to the maximum value of the @code{signed char}, @code{wchar_t}, +@code{signed short}, +@code{signed int}, @code{signed long}, @code{signed long long}, +@code{wint_t}, @code{size_t}, @code{ptrdiff_t}, +@code{intmax_t}, @code{uintmax_t}, @code{sig_atomic_t}, @code{int8_t}, +@code{int16_t}, @code{int32_t}, @code{int64_t}, @code{uint8_t}, +@code{uint16_t}, @code{uint32_t}, @code{uint64_t}, +@code{int_least8_t}, @code{int_least16_t}, @code{int_least32_t}, +@code{int_least64_t}, @code{uint_least8_t}, @code{uint_least16_t}, +@code{uint_least32_t}, @code{uint_least64_t}, @code{int_fast8_t}, +@code{int_fast16_t}, @code{int_fast32_t}, @code{int_fast64_t}, +@code{uint_fast8_t}, @code{uint_fast16_t}, @code{uint_fast32_t}, +@code{uint_fast64_t}, @code{intptr_t}, and @code{uintptr_t} types and +to the minimum value of the @code{wchar_t}, @code{wint_t}, and +@code{sig_atomic_t} types respectively. They exist to make the +standard header given numerical limits work correctly. You should not +use these macros directly; instead, include the appropriate headers. +Some of these macros may not be defined on particular systems if GCC +does not provide a @file{stdint.h} header on those systems. + +@item __INT8_C +@itemx __INT16_C +@itemx __INT32_C +@itemx __INT64_C +@itemx __UINT8_C +@itemx __UINT16_C +@itemx __UINT32_C +@itemx __UINT64_C +@itemx __INTMAX_C +@itemx __UINTMAX_C +Defined to implementations of the standard @file{stdint.h} macros with +the same names without the leading @code{__}. They exist the make the +implementation of that header work correctly. You should not use +these macros directly; instead, include the appropriate headers. Some +of these macros may not be defined on particular systems if GCC does +not provide a @file{stdint.h} header on those systems. + +@item __SIZEOF_INT__ +@itemx __SIZEOF_LONG__ +@itemx __SIZEOF_LONG_LONG__ +@itemx __SIZEOF_SHORT__ +@itemx __SIZEOF_POINTER__ +@itemx __SIZEOF_FLOAT__ +@itemx __SIZEOF_DOUBLE__ +@itemx __SIZEOF_LONG_DOUBLE__ +@itemx __SIZEOF_SIZE_T__ +@itemx __SIZEOF_WCHAR_T__ +@itemx __SIZEOF_WINT_T__ +@itemx __SIZEOF_PTRDIFF_T__ +Defined to the number of bytes of the C standard data types: @code{int}, +@code{long}, @code{long long}, @code{short}, @code{void *}, @code{float}, +@code{double}, @code{long double}, @code{size_t}, @code{wchar_t}, @code{wint_t} +and @code{ptrdiff_t}. + +@item __BYTE_ORDER__ +@itemx __ORDER_LITTLE_ENDIAN__ +@itemx __ORDER_BIG_ENDIAN__ +@itemx __ORDER_PDP_ENDIAN__ +@code{__BYTE_ORDER__} is defined to one of the values +@code{__ORDER_LITTLE_ENDIAN__}, @code{__ORDER_BIG_ENDIAN__}, or +@code{__ORDER_PDP_ENDIAN__} to reflect the layout of multi-byte and +multi-word quantities in memory. If @code{__BYTE_ORDER__} is equal to +@code{__ORDER_LITTLE_ENDIAN__} or @code{__ORDER_BIG_ENDIAN__}, then +multi-byte and multi-word quantities are laid out identically: the +byte (word) at the lowest address is the least significant or most +significant byte (word) of the quantity, respectively. If +@code{__BYTE_ORDER__} is equal to @code{__ORDER_PDP_ENDIAN__}, then +bytes in 16-bit words are laid out in a little-endian fashion, whereas +the 16-bit subwords of a 32-bit quantity are laid out in big-endian +fashion. + +You should use these macros for testing like this: + +@smallexample +/* @r{Test for a little-endian machine} */ +#if __BYTE_ORDER__ == __ORDER_LITTLE_ENDIAN__ +@end smallexample + +@item __FLOAT_WORD_ORDER__ +@code{__FLOAT_WORD_ORDER__} is defined to one of the values +@code{__ORDER_LITTLE_ENDIAN__} or @code{__ORDER_BIG_ENDIAN__} to reflect +the layout of the words of multi-word floating-point quantities. + +@item __DEPRECATED +This macro is defined, with value 1, when compiling a C++ source file +with warnings about deprecated constructs enabled. These warnings are +enabled by default, but can be disabled with @option{-Wno-deprecated}. + +@item __EXCEPTIONS +This macro is defined, with value 1, when compiling a C++ source file +with exceptions enabled. If @option{-fno-exceptions} is used when +compiling the file, then this macro is not defined. + +@item __GXX_RTTI +This macro is defined, with value 1, when compiling a C++ source file +with runtime type identification enabled. If @option{-fno-rtti} is +used when compiling the file, then this macro is not defined. + +@item __USING_SJLJ_EXCEPTIONS__ +This macro is defined, with value 1, if the compiler uses the old +mechanism based on @code{setjmp} and @code{longjmp} for exception +handling. + +@item __GXX_EXPERIMENTAL_CXX0X__ +This macro is defined when compiling a C++ source file with the option +@option{-std=c++0x} or @option{-std=gnu++0x}. It indicates that some +features likely to be included in C++0x are available. Note that these +features are experimental, and may change or be removed in future +versions of GCC. + +@item __GXX_WEAK__ +This macro is defined when compiling a C++ source file. It has the +value 1 if the compiler will use weak symbols, COMDAT sections, or +other similar techniques to collapse symbols with ``vague linkage'' +that are defined in multiple translation units. If the compiler will +not collapse such symbols, this macro is defined with value 0. In +general, user code should not need to make use of this macro; the +purpose of this macro is to ease implementation of the C++ runtime +library provided with G++. + +@item __NEXT_RUNTIME__ +This macro is defined, with value 1, if (and only if) the NeXT runtime +(as in @option{-fnext-runtime}) is in use for Objective-C@. If the GNU +runtime is used, this macro is not defined, so that you can use this +macro to determine which runtime (NeXT or GNU) is being used. + +@item __LP64__ +@itemx _LP64 +These macros are defined, with value 1, if (and only if) the compilation +is for a target where @code{long int} and pointer both use 64-bits and +@code{int} uses 32-bit. + +@item __SSP__ +This macro is defined, with value 1, when @option{-fstack-protector} is in +use. + +@item __SSP_ALL__ +This macro is defined, with value 2, when @option{-fstack-protector-all} is +in use. + +@item __TIMESTAMP__ +This macro expands to a string constant that describes the date and time +of the last modification of the current source file. The string constant +contains abbreviated day of the week, month, day of the month, time in +hh:mm:ss form, year and looks like @code{@w{"Sun Sep 16 01:03:52 1973"}}. +If the day of the month is less than 10, it is padded with a space on the left. + +If GCC cannot determine the current date, it will emit a warning message +(once per compilation) and @code{__TIMESTAMP__} will expand to +@code{@w{"??? ??? ?? ??:??:?? ????"}}. + +@item __GCC_HAVE_SYNC_COMPARE_AND_SWAP_1 +@itemx __GCC_HAVE_SYNC_COMPARE_AND_SWAP_2 +@itemx __GCC_HAVE_SYNC_COMPARE_AND_SWAP_4 +@itemx __GCC_HAVE_SYNC_COMPARE_AND_SWAP_8 +@itemx __GCC_HAVE_SYNC_COMPARE_AND_SWAP_16 +These macros are defined when the target processor supports atomic compare +and swap operations on operands 1, 2, 4, 8 or 16 bytes in length, respectively. + +@item __GCC_HAVE_DWARF2_CFI_ASM +This macro is defined when the compiler is emitting Dwarf2 CFI directives +to the assembler. When this is defined, it is possible to emit those same +directives in inline assembly. + +@item __FP_FAST_FMA +@itemx __FP_FAST_FMAF +@itemx __FP_FAST_FMAL +These macros are defined with value 1 if the backend supports the +@code{fma}, @code{fmaf}, and @code{fmal} builtin functions, so that +the include file @file{math.h} can define the macros +@code{FP_FAST_FMA}, @code{FP_FAST_FMAF}, and @code{FP_FAST_FMAL} +for compatibility with the 1999 C standard. +@end table + +@node System-specific Predefined Macros +@subsection System-specific Predefined Macros + +@cindex system-specific predefined macros +@cindex predefined macros, system-specific +@cindex reserved namespace + +The C preprocessor normally predefines several macros that indicate what +type of system and machine is in use. They are obviously different on +each target supported by GCC@. This manual, being for all systems and +machines, cannot tell you what their names are, but you can use +@command{cpp -dM} to see them all. @xref{Invocation}. All system-specific +predefined macros expand to the constant 1, so you can test them with +either @samp{#ifdef} or @samp{#if}. + +The C standard requires that all system-specific macros be part of the +@dfn{reserved namespace}. All names which begin with two underscores, +or an underscore and a capital letter, are reserved for the compiler and +library to use as they wish. However, historically system-specific +macros have had names with no special prefix; for instance, it is common +to find @code{unix} defined on Unix systems. For all such macros, GCC +provides a parallel macro with two underscores added at the beginning +and the end. If @code{unix} is defined, @code{__unix__} will be defined +too. There will never be more than two underscores; the parallel of +@code{_mips} is @code{__mips__}. + +When the @option{-ansi} option, or any @option{-std} option that +requests strict conformance, is given to the compiler, all the +system-specific predefined macros outside the reserved namespace are +suppressed. The parallel macros, inside the reserved namespace, remain +defined. + +We are slowly phasing out all predefined macros which are outside the +reserved namespace. You should never use them in new programs, and we +encourage you to correct older code to use the parallel macros whenever +you find it. We don't recommend you use the system-specific macros that +are in the reserved namespace, either. It is better in the long run to +check specifically for features you need, using a tool such as +@command{autoconf}. + +@node C++ Named Operators +@subsection C++ Named Operators +@cindex named operators +@cindex C++ named operators +@cindex @file{iso646.h} + +In C++, there are eleven keywords which are simply alternate spellings +of operators normally written with punctuation. These keywords are +treated as such even in the preprocessor. They function as operators in +@samp{#if}, and they cannot be defined as macros or poisoned. In C, you +can request that those keywords take their C++ meaning by including +@file{iso646.h}. That header defines each one as a normal object-like +macro expanding to the appropriate punctuator. + +These are the named operators and their corresponding punctuators: + +@multitable {Named Operator} {Punctuator} +@item Named Operator @tab Punctuator +@item @code{and} @tab @code{&&} +@item @code{and_eq} @tab @code{&=} +@item @code{bitand} @tab @code{&} +@item @code{bitor} @tab @code{|} +@item @code{compl} @tab @code{~} +@item @code{not} @tab @code{!} +@item @code{not_eq} @tab @code{!=} +@item @code{or} @tab @code{||} +@item @code{or_eq} @tab @code{|=} +@item @code{xor} @tab @code{^} +@item @code{xor_eq} @tab @code{^=} +@end multitable + +@node Undefining and Redefining Macros +@section Undefining and Redefining Macros +@cindex undefining macros +@cindex redefining macros +@findex #undef + +If a macro ceases to be useful, it may be @dfn{undefined} with the +@samp{#undef} directive. @samp{#undef} takes a single argument, the +name of the macro to undefine. You use the bare macro name, even if the +macro is function-like. It is an error if anything appears on the line +after the macro name. @samp{#undef} has no effect if the name is not a +macro. + +@smallexample +#define FOO 4 +x = FOO; @expansion{} x = 4; +#undef FOO +x = FOO; @expansion{} x = FOO; +@end smallexample + +Once a macro has been undefined, that identifier may be @dfn{redefined} +as a macro by a subsequent @samp{#define} directive. The new definition +need not have any resemblance to the old definition. + +However, if an identifier which is currently a macro is redefined, then +the new definition must be @dfn{effectively the same} as the old one. +Two macro definitions are effectively the same if: +@itemize @bullet +@item Both are the same type of macro (object- or function-like). +@item All the tokens of the replacement list are the same. +@item If there are any parameters, they are the same. +@item Whitespace appears in the same places in both. It need not be +exactly the same amount of whitespace, though. Remember that comments +count as whitespace. +@end itemize + +@noindent +These definitions are effectively the same: +@smallexample +#define FOUR (2 + 2) +#define FOUR (2 + 2) +#define FOUR (2 /* @r{two} */ + 2) +@end smallexample +@noindent +but these are not: +@smallexample +#define FOUR (2 + 2) +#define FOUR ( 2+2 ) +#define FOUR (2 * 2) +#define FOUR(score,and,seven,years,ago) (2 + 2) +@end smallexample + +If a macro is redefined with a definition that is not effectively the +same as the old one, the preprocessor issues a warning and changes the +macro to use the new definition. If the new definition is effectively +the same, the redefinition is silently ignored. This allows, for +instance, two different headers to define a common macro. The +preprocessor will only complain if the definitions do not match. + +@node Directives Within Macro Arguments +@section Directives Within Macro Arguments +@cindex macro arguments and directives + +Occasionally it is convenient to use preprocessor directives within +the arguments of a macro. The C and C++ standards declare that +behavior in these cases is undefined. + +Versions of CPP prior to 3.2 would reject such constructs with an +error message. This was the only syntactic difference between normal +functions and function-like macros, so it seemed attractive to remove +this limitation, and people would often be surprised that they could +not use macros in this way. Moreover, sometimes people would use +conditional compilation in the argument list to a normal library +function like @samp{printf}, only to find that after a library upgrade +@samp{printf} had changed to be a function-like macro, and their code +would no longer compile. So from version 3.2 we changed CPP to +successfully process arbitrary directives within macro arguments in +exactly the same way as it would have processed the directive were the +function-like macro invocation not present. + +If, within a macro invocation, that macro is redefined, then the new +definition takes effect in time for argument pre-expansion, but the +original definition is still used for argument replacement. Here is a +pathological example: + +@smallexample +#define f(x) x x +f (1 +#undef f +#define f 2 +f) +@end smallexample + +@noindent +which expands to + +@smallexample +1 2 1 2 +@end smallexample + +@noindent +with the semantics described above. + +@node Macro Pitfalls +@section Macro Pitfalls +@cindex problems with macros +@cindex pitfalls of macros + +In this section we describe some special rules that apply to macros and +macro expansion, and point out certain cases in which the rules have +counter-intuitive consequences that you must watch out for. + +@menu +* Misnesting:: +* Operator Precedence Problems:: +* Swallowing the Semicolon:: +* Duplication of Side Effects:: +* Self-Referential Macros:: +* Argument Prescan:: +* Newlines in Arguments:: +@end menu + +@node Misnesting +@subsection Misnesting + +When a macro is called with arguments, the arguments are substituted +into the macro body and the result is checked, together with the rest of +the input file, for more macro calls. It is possible to piece together +a macro call coming partially from the macro body and partially from the +arguments. For example, + +@smallexample +#define twice(x) (2*(x)) +#define call_with_1(x) x(1) +call_with_1 (twice) + @expansion{} twice(1) + @expansion{} (2*(1)) +@end smallexample + +Macro definitions do not have to have balanced parentheses. By writing +an unbalanced open parenthesis in a macro body, it is possible to create +a macro call that begins inside the macro body but ends outside of it. +For example, + +@smallexample +#define strange(file) fprintf (file, "%s %d", +@dots{} +strange(stderr) p, 35) + @expansion{} fprintf (stderr, "%s %d", p, 35) +@end smallexample + +The ability to piece together a macro call can be useful, but the use of +unbalanced open parentheses in a macro body is just confusing, and +should be avoided. + +@node Operator Precedence Problems +@subsection Operator Precedence Problems +@cindex parentheses in macro bodies + +You may have noticed that in most of the macro definition examples shown +above, each occurrence of a macro argument name had parentheses around +it. In addition, another pair of parentheses usually surround the +entire macro definition. Here is why it is best to write macros that +way. + +Suppose you define a macro as follows, + +@smallexample +#define ceil_div(x, y) (x + y - 1) / y +@end smallexample + +@noindent +whose purpose is to divide, rounding up. (One use for this operation is +to compute how many @code{int} objects are needed to hold a certain +number of @code{char} objects.) Then suppose it is used as follows: + +@smallexample +a = ceil_div (b & c, sizeof (int)); + @expansion{} a = (b & c + sizeof (int) - 1) / sizeof (int); +@end smallexample + +@noindent +This does not do what is intended. The operator-precedence rules of +C make it equivalent to this: + +@smallexample +a = (b & (c + sizeof (int) - 1)) / sizeof (int); +@end smallexample + +@noindent +What we want is this: + +@smallexample +a = ((b & c) + sizeof (int) - 1)) / sizeof (int); +@end smallexample + +@noindent +Defining the macro as + +@smallexample +#define ceil_div(x, y) ((x) + (y) - 1) / (y) +@end smallexample + +@noindent +provides the desired result. + +Unintended grouping can result in another way. Consider @code{sizeof +ceil_div(1, 2)}. That has the appearance of a C expression that would +compute the size of the type of @code{ceil_div (1, 2)}, but in fact it +means something very different. Here is what it expands to: + +@smallexample +sizeof ((1) + (2) - 1) / (2) +@end smallexample + +@noindent +This would take the size of an integer and divide it by two. The +precedence rules have put the division outside the @code{sizeof} when it +was intended to be inside. + +Parentheses around the entire macro definition prevent such problems. +Here, then, is the recommended way to define @code{ceil_div}: + +@smallexample +#define ceil_div(x, y) (((x) + (y) - 1) / (y)) +@end smallexample + +@node Swallowing the Semicolon +@subsection Swallowing the Semicolon +@cindex semicolons (after macro calls) + +Often it is desirable to define a macro that expands into a compound +statement. Consider, for example, the following macro, that advances a +pointer (the argument @code{p} says where to find it) across whitespace +characters: + +@smallexample +#define SKIP_SPACES(p, limit) \ +@{ char *lim = (limit); \ + while (p < lim) @{ \ + if (*p++ != ' ') @{ \ + p--; break; @}@}@} +@end smallexample + +@noindent +Here backslash-newline is used to split the macro definition, which must +be a single logical line, so that it resembles the way such code would +be laid out if not part of a macro definition. + +A call to this macro might be @code{SKIP_SPACES (p, lim)}. Strictly +speaking, the call expands to a compound statement, which is a complete +statement with no need for a semicolon to end it. However, since it +looks like a function call, it minimizes confusion if you can use it +like a function call, writing a semicolon afterward, as in +@code{SKIP_SPACES (p, lim);} + +This can cause trouble before @code{else} statements, because the +semicolon is actually a null statement. Suppose you write + +@smallexample +if (*p != 0) + SKIP_SPACES (p, lim); +else @dots{} +@end smallexample + +@noindent +The presence of two statements---the compound statement and a null +statement---in between the @code{if} condition and the @code{else} +makes invalid C code. + +The definition of the macro @code{SKIP_SPACES} can be altered to solve +this problem, using a @code{do @dots{} while} statement. Here is how: + +@smallexample +#define SKIP_SPACES(p, limit) \ +do @{ char *lim = (limit); \ + while (p < lim) @{ \ + if (*p++ != ' ') @{ \ + p--; break; @}@}@} \ +while (0) +@end smallexample + +Now @code{SKIP_SPACES (p, lim);} expands into + +@smallexample +do @{@dots{}@} while (0); +@end smallexample + +@noindent +which is one statement. The loop executes exactly once; most compilers +generate no extra code for it. + +@node Duplication of Side Effects +@subsection Duplication of Side Effects + +@cindex side effects (in macro arguments) +@cindex unsafe macros +Many C programs define a macro @code{min}, for ``minimum'', like this: + +@smallexample +#define min(X, Y) ((X) < (Y) ? (X) : (Y)) +@end smallexample + +When you use this macro with an argument containing a side effect, +as shown here, + +@smallexample +next = min (x + y, foo (z)); +@end smallexample + +@noindent +it expands as follows: + +@smallexample +next = ((x + y) < (foo (z)) ? (x + y) : (foo (z))); +@end smallexample + +@noindent +where @code{x + y} has been substituted for @code{X} and @code{foo (z)} +for @code{Y}. + +The function @code{foo} is used only once in the statement as it appears +in the program, but the expression @code{foo (z)} has been substituted +twice into the macro expansion. As a result, @code{foo} might be called +two times when the statement is executed. If it has side effects or if +it takes a long time to compute, the results might not be what you +intended. We say that @code{min} is an @dfn{unsafe} macro. + +The best solution to this problem is to define @code{min} in a way that +computes the value of @code{foo (z)} only once. The C language offers +no standard way to do this, but it can be done with GNU extensions as +follows: + +@smallexample +#define min(X, Y) \ +(@{ typeof (X) x_ = (X); \ + typeof (Y) y_ = (Y); \ + (x_ < y_) ? x_ : y_; @}) +@end smallexample + +The @samp{(@{ @dots{} @})} notation produces a compound statement that +acts as an expression. Its value is the value of its last statement. +This permits us to define local variables and assign each argument to +one. The local variables have underscores after their names to reduce +the risk of conflict with an identifier of wider scope (it is impossible +to avoid this entirely). Now each argument is evaluated exactly once. + +If you do not wish to use GNU C extensions, the only solution is to be +careful when @emph{using} the macro @code{min}. For example, you can +calculate the value of @code{foo (z)}, save it in a variable, and use +that variable in @code{min}: + +@smallexample +@group +#define min(X, Y) ((X) < (Y) ? (X) : (Y)) +@dots{} +@{ + int tem = foo (z); + next = min (x + y, tem); +@} +@end group +@end smallexample + +@noindent +(where we assume that @code{foo} returns type @code{int}). + +@node Self-Referential Macros +@subsection Self-Referential Macros +@cindex self-reference + +A @dfn{self-referential} macro is one whose name appears in its +definition. Recall that all macro definitions are rescanned for more +macros to replace. If the self-reference were considered a use of the +macro, it would produce an infinitely large expansion. To prevent this, +the self-reference is not considered a macro call. It is passed into +the preprocessor output unchanged. Consider an example: + +@smallexample +#define foo (4 + foo) +@end smallexample + +@noindent +where @code{foo} is also a variable in your program. + +Following the ordinary rules, each reference to @code{foo} will expand +into @code{(4 + foo)}; then this will be rescanned and will expand into +@code{(4 + (4 + foo))}; and so on until the computer runs out of memory. + +The self-reference rule cuts this process short after one step, at +@code{(4 + foo)}. Therefore, this macro definition has the possibly +useful effect of causing the program to add 4 to the value of @code{foo} +wherever @code{foo} is referred to. + +In most cases, it is a bad idea to take advantage of this feature. A +person reading the program who sees that @code{foo} is a variable will +not expect that it is a macro as well. The reader will come across the +identifier @code{foo} in the program and think its value should be that +of the variable @code{foo}, whereas in fact the value is four greater. + +One common, useful use of self-reference is to create a macro which +expands to itself. If you write + +@smallexample +#define EPERM EPERM +@end smallexample + +@noindent +then the macro @code{EPERM} expands to @code{EPERM}. Effectively, it is +left alone by the preprocessor whenever it's used in running text. You +can tell that it's a macro with @samp{#ifdef}. You might do this if you +want to define numeric constants with an @code{enum}, but have +@samp{#ifdef} be true for each constant. + +If a macro @code{x} expands to use a macro @code{y}, and the expansion of +@code{y} refers to the macro @code{x}, that is an @dfn{indirect +self-reference} of @code{x}. @code{x} is not expanded in this case +either. Thus, if we have + +@smallexample +#define x (4 + y) +#define y (2 * x) +@end smallexample + +@noindent +then @code{x} and @code{y} expand as follows: + +@smallexample +@group +x @expansion{} (4 + y) + @expansion{} (4 + (2 * x)) + +y @expansion{} (2 * x) + @expansion{} (2 * (4 + y)) +@end group +@end smallexample + +@noindent +Each macro is expanded when it appears in the definition of the other +macro, but not when it indirectly appears in its own definition. + +@node Argument Prescan +@subsection Argument Prescan +@cindex expansion of arguments +@cindex macro argument expansion +@cindex prescan of macro arguments + +Macro arguments are completely macro-expanded before they are +substituted into a macro body, unless they are stringified or pasted +with other tokens. After substitution, the entire macro body, including +the substituted arguments, is scanned again for macros to be expanded. +The result is that the arguments are scanned @emph{twice} to expand +macro calls in them. + +Most of the time, this has no effect. If the argument contained any +macro calls, they are expanded during the first scan. The result +therefore contains no macro calls, so the second scan does not change +it. If the argument were substituted as given, with no prescan, the +single remaining scan would find the same macro calls and produce the +same results. + +You might expect the double scan to change the results when a +self-referential macro is used in an argument of another macro +(@pxref{Self-Referential Macros}): the self-referential macro would be +expanded once in the first scan, and a second time in the second scan. +However, this is not what happens. The self-references that do not +expand in the first scan are marked so that they will not expand in the +second scan either. + +You might wonder, ``Why mention the prescan, if it makes no difference? +And why not skip it and make the preprocessor faster?'' The answer is +that the prescan does make a difference in three special cases: + +@itemize @bullet +@item +Nested calls to a macro. + +We say that @dfn{nested} calls to a macro occur when a macro's argument +contains a call to that very macro. For example, if @code{f} is a macro +that expects one argument, @code{f (f (1))} is a nested pair of calls to +@code{f}. The desired expansion is made by expanding @code{f (1)} and +substituting that into the definition of @code{f}. The prescan causes +the expected result to happen. Without the prescan, @code{f (1)} itself +would be substituted as an argument, and the inner use of @code{f} would +appear during the main scan as an indirect self-reference and would not +be expanded. + +@item +Macros that call other macros that stringify or concatenate. + +If an argument is stringified or concatenated, the prescan does not +occur. If you @emph{want} to expand a macro, then stringify or +concatenate its expansion, you can do that by causing one macro to call +another macro that does the stringification or concatenation. For +instance, if you have + +@smallexample +#define AFTERX(x) X_ ## x +#define XAFTERX(x) AFTERX(x) +#define TABLESIZE 1024 +#define BUFSIZE TABLESIZE +@end smallexample + +then @code{AFTERX(BUFSIZE)} expands to @code{X_BUFSIZE}, and +@code{XAFTERX(BUFSIZE)} expands to @code{X_1024}. (Not to +@code{X_TABLESIZE}. Prescan always does a complete expansion.) + +@item +Macros used in arguments, whose expansions contain unshielded commas. + +This can cause a macro expanded on the second scan to be called with the +wrong number of arguments. Here is an example: + +@smallexample +#define foo a,b +#define bar(x) lose(x) +#define lose(x) (1 + (x)) +@end smallexample + +We would like @code{bar(foo)} to turn into @code{(1 + (foo))}, which +would then turn into @code{(1 + (a,b))}. Instead, @code{bar(foo)} +expands into @code{lose(a,b)}, and you get an error because @code{lose} +requires a single argument. In this case, the problem is easily solved +by the same parentheses that ought to be used to prevent misnesting of +arithmetic operations: + +@smallexample +#define foo (a,b) +@exdent or +#define bar(x) lose((x)) +@end smallexample + +The extra pair of parentheses prevents the comma in @code{foo}'s +definition from being interpreted as an argument separator. + +@end itemize + +@node Newlines in Arguments +@subsection Newlines in Arguments +@cindex newlines in macro arguments + +The invocation of a function-like macro can extend over many logical +lines. However, in the present implementation, the entire expansion +comes out on one line. Thus line numbers emitted by the compiler or +debugger refer to the line the invocation started on, which might be +different to the line containing the argument causing the problem. + +Here is an example illustrating this: + +@smallexample +#define ignore_second_arg(a,b,c) a; c + +ignore_second_arg (foo (), + ignored (), + syntax error); +@end smallexample + +@noindent +The syntax error triggered by the tokens @code{syntax error} results in +an error message citing line three---the line of ignore_second_arg--- +even though the problematic code comes from line five. + +We consider this a bug, and intend to fix it in the near future. + +@node Conditionals +@chapter Conditionals +@cindex conditionals + +A @dfn{conditional} is a directive that instructs the preprocessor to +select whether or not to include a chunk of code in the final token +stream passed to the compiler. Preprocessor conditionals can test +arithmetic expressions, or whether a name is defined as a macro, or both +simultaneously using the special @code{defined} operator. + +A conditional in the C preprocessor resembles in some ways an @code{if} +statement in C, but it is important to understand the difference between +them. The condition in an @code{if} statement is tested during the +execution of your program. Its purpose is to allow your program to +behave differently from run to run, depending on the data it is +operating on. The condition in a preprocessing conditional directive is +tested when your program is compiled. Its purpose is to allow different +code to be included in the program depending on the situation at the +time of compilation. + +However, the distinction is becoming less clear. Modern compilers often +do test @code{if} statements when a program is compiled, if their +conditions are known not to vary at run time, and eliminate code which +can never be executed. If you can count on your compiler to do this, +you may find that your program is more readable if you use @code{if} +statements with constant conditions (perhaps determined by macros). Of +course, you can only use this to exclude code, not type definitions or +other preprocessing directives, and you can only do it if the code +remains syntactically valid when it is not to be used. + +GCC version 3 eliminates this kind of never-executed code even when +not optimizing. Older versions did it only when optimizing. + +@menu +* Conditional Uses:: +* Conditional Syntax:: +* Deleted Code:: +@end menu + +@node Conditional Uses +@section Conditional Uses + +There are three general reasons to use a conditional. + +@itemize @bullet +@item +A program may need to use different code depending on the machine or +operating system it is to run on. In some cases the code for one +operating system may be erroneous on another operating system; for +example, it might refer to data types or constants that do not exist on +the other system. When this happens, it is not enough to avoid +executing the invalid code. Its mere presence will cause the compiler +to reject the program. With a preprocessing conditional, the offending +code can be effectively excised from the program when it is not valid. + +@item +You may want to be able to compile the same source file into two +different programs. One version might make frequent time-consuming +consistency checks on its intermediate data, or print the values of +those data for debugging, and the other not. + +@item +A conditional whose condition is always false is one way to exclude code +from the program but keep it as a sort of comment for future reference. +@end itemize + +Simple programs that do not need system-specific logic or complex +debugging hooks generally will not need to use preprocessing +conditionals. + +@node Conditional Syntax +@section Conditional Syntax + +@findex #if +A conditional in the C preprocessor begins with a @dfn{conditional +directive}: @samp{#if}, @samp{#ifdef} or @samp{#ifndef}. + +@menu +* Ifdef:: +* If:: +* Defined:: +* Else:: +* Elif:: +@end menu + +@node Ifdef +@subsection Ifdef +@findex #ifdef +@findex #endif + +The simplest sort of conditional is + +@smallexample +@group +#ifdef @var{MACRO} + +@var{controlled text} + +#endif /* @var{MACRO} */ +@end group +@end smallexample + +@cindex conditional group +This block is called a @dfn{conditional group}. @var{controlled text} +will be included in the output of the preprocessor if and only if +@var{MACRO} is defined. We say that the conditional @dfn{succeeds} if +@var{MACRO} is defined, @dfn{fails} if it is not. + +The @var{controlled text} inside of a conditional can include +preprocessing directives. They are executed only if the conditional +succeeds. You can nest conditional groups inside other conditional +groups, but they must be completely nested. In other words, +@samp{#endif} always matches the nearest @samp{#ifdef} (or +@samp{#ifndef}, or @samp{#if}). Also, you cannot start a conditional +group in one file and end it in another. + +Even if a conditional fails, the @var{controlled text} inside it is +still run through initial transformations and tokenization. Therefore, +it must all be lexically valid C@. Normally the only way this matters is +that all comments and string literals inside a failing conditional group +must still be properly ended. + +The comment following the @samp{#endif} is not required, but it is a +good practice if there is a lot of @var{controlled text}, because it +helps people match the @samp{#endif} to the corresponding @samp{#ifdef}. +Older programs sometimes put @var{MACRO} directly after the +@samp{#endif} without enclosing it in a comment. This is invalid code +according to the C standard. CPP accepts it with a warning. It +never affects which @samp{#ifndef} the @samp{#endif} matches. + +@findex #ifndef +Sometimes you wish to use some code if a macro is @emph{not} defined. +You can do this by writing @samp{#ifndef} instead of @samp{#ifdef}. +One common use of @samp{#ifndef} is to include code only the first +time a header file is included. @xref{Once-Only Headers}. + +Macro definitions can vary between compilations for several reasons. +Here are some samples. + +@itemize @bullet +@item +Some macros are predefined on each kind of machine +(@pxref{System-specific Predefined Macros}). This allows you to provide +code specially tuned for a particular machine. + +@item +System header files define more macros, associated with the features +they implement. You can test these macros with conditionals to avoid +using a system feature on a machine where it is not implemented. + +@item +Macros can be defined or undefined with the @option{-D} and @option{-U} +command line options when you compile the program. You can arrange to +compile the same source file into two different programs by choosing a +macro name to specify which program you want, writing conditionals to +test whether or how this macro is defined, and then controlling the +state of the macro with command line options, perhaps set in the +Makefile. @xref{Invocation}. + +@item +Your program might have a special header file (often called +@file{config.h}) that is adjusted when the program is compiled. It can +define or not define macros depending on the features of the system and +the desired capabilities of the program. The adjustment can be +automated by a tool such as @command{autoconf}, or done by hand. +@end itemize + +@node If +@subsection If + +The @samp{#if} directive allows you to test the value of an arithmetic +expression, rather than the mere existence of one macro. Its syntax is + +@smallexample +@group +#if @var{expression} + +@var{controlled text} + +#endif /* @var{expression} */ +@end group +@end smallexample + +@var{expression} is a C expression of integer type, subject to stringent +restrictions. It may contain + +@itemize @bullet +@item +Integer constants. + +@item +Character constants, which are interpreted as they would be in normal +code. + +@item +Arithmetic operators for addition, subtraction, multiplication, +division, bitwise operations, shifts, comparisons, and logical +operations (@code{&&} and @code{||}). The latter two obey the usual +short-circuiting rules of standard C@. + +@item +Macros. All macros in the expression are expanded before actual +computation of the expression's value begins. + +@item +Uses of the @code{defined} operator, which lets you check whether macros +are defined in the middle of an @samp{#if}. + +@item +Identifiers that are not macros, which are all considered to be the +number zero. This allows you to write @code{@w{#if MACRO}} instead of +@code{@w{#ifdef MACRO}}, if you know that MACRO, when defined, will +always have a nonzero value. Function-like macros used without their +function call parentheses are also treated as zero. + +In some contexts this shortcut is undesirable. The @option{-Wundef} +option causes GCC to warn whenever it encounters an identifier which is +not a macro in an @samp{#if}. +@end itemize + +The preprocessor does not know anything about types in the language. +Therefore, @code{sizeof} operators are not recognized in @samp{#if}, and +neither are @code{enum} constants. They will be taken as identifiers +which are not macros, and replaced by zero. In the case of +@code{sizeof}, this is likely to cause the expression to be invalid. + +The preprocessor calculates the value of @var{expression}. It carries +out all calculations in the widest integer type known to the compiler; +on most machines supported by GCC this is 64 bits. This is not the same +rule as the compiler uses to calculate the value of a constant +expression, and may give different results in some cases. If the value +comes out to be nonzero, the @samp{#if} succeeds and the @var{controlled +text} is included; otherwise it is skipped. + +@node Defined +@subsection Defined + +@cindex @code{defined} +The special operator @code{defined} is used in @samp{#if} and +@samp{#elif} expressions to test whether a certain name is defined as a +macro. @code{defined @var{name}} and @code{defined (@var{name})} are +both expressions whose value is 1 if @var{name} is defined as a macro at +the current point in the program, and 0 otherwise. Thus, @code{@w{#if +defined MACRO}} is precisely equivalent to @code{@w{#ifdef MACRO}}. + +@code{defined} is useful when you wish to test more than one macro for +existence at once. For example, + +@smallexample +#if defined (__vax__) || defined (__ns16000__) +@end smallexample + +@noindent +would succeed if either of the names @code{__vax__} or +@code{__ns16000__} is defined as a macro. + +Conditionals written like this: + +@smallexample +#if defined BUFSIZE && BUFSIZE >= 1024 +@end smallexample + +@noindent +can generally be simplified to just @code{@w{#if BUFSIZE >= 1024}}, +since if @code{BUFSIZE} is not defined, it will be interpreted as having +the value zero. + +If the @code{defined} operator appears as a result of a macro expansion, +the C standard says the behavior is undefined. GNU cpp treats it as a +genuine @code{defined} operator and evaluates it normally. It will warn +wherever your code uses this feature if you use the command-line option +@option{-pedantic}, since other compilers may handle it differently. + +@node Else +@subsection Else + +@findex #else +The @samp{#else} directive can be added to a conditional to provide +alternative text to be used if the condition fails. This is what it +looks like: + +@smallexample +@group +#if @var{expression} +@var{text-if-true} +#else /* Not @var{expression} */ +@var{text-if-false} +#endif /* Not @var{expression} */ +@end group +@end smallexample + +@noindent +If @var{expression} is nonzero, the @var{text-if-true} is included and +the @var{text-if-false} is skipped. If @var{expression} is zero, the +opposite happens. + +You can use @samp{#else} with @samp{#ifdef} and @samp{#ifndef}, too. + +@node Elif +@subsection Elif + +@findex #elif +One common case of nested conditionals is used to check for more than two +possible alternatives. For example, you might have + +@smallexample +#if X == 1 +@dots{} +#else /* X != 1 */ +#if X == 2 +@dots{} +#else /* X != 2 */ +@dots{} +#endif /* X != 2 */ +#endif /* X != 1 */ +@end smallexample + +Another conditional directive, @samp{#elif}, allows this to be +abbreviated as follows: + +@smallexample +#if X == 1 +@dots{} +#elif X == 2 +@dots{} +#else /* X != 2 and X != 1*/ +@dots{} +#endif /* X != 2 and X != 1*/ +@end smallexample + +@samp{#elif} stands for ``else if''. Like @samp{#else}, it goes in the +middle of a conditional group and subdivides it; it does not require a +matching @samp{#endif} of its own. Like @samp{#if}, the @samp{#elif} +directive includes an expression to be tested. The text following the +@samp{#elif} is processed only if the original @samp{#if}-condition +failed and the @samp{#elif} condition succeeds. + +More than one @samp{#elif} can go in the same conditional group. Then +the text after each @samp{#elif} is processed only if the @samp{#elif} +condition succeeds after the original @samp{#if} and all previous +@samp{#elif} directives within it have failed. + +@samp{#else} is allowed after any number of @samp{#elif} directives, but +@samp{#elif} may not follow @samp{#else}. + +@node Deleted Code +@section Deleted Code +@cindex commenting out code + +If you replace or delete a part of the program but want to keep the old +code around for future reference, you often cannot simply comment it +out. Block comments do not nest, so the first comment inside the old +code will end the commenting-out. The probable result is a flood of +syntax errors. + +One way to avoid this problem is to use an always-false conditional +instead. For instance, put @code{#if 0} before the deleted code and +@code{#endif} after it. This works even if the code being turned +off contains conditionals, but they must be entire conditionals +(balanced @samp{#if} and @samp{#endif}). + +Some people use @code{#ifdef notdef} instead. This is risky, because +@code{notdef} might be accidentally defined as a macro, and then the +conditional would succeed. @code{#if 0} can be counted on to fail. + +Do not use @code{#if 0} for comments which are not C code. Use a real +comment, instead. The interior of @code{#if 0} must consist of complete +tokens; in particular, single-quote characters must balance. Comments +often contain unbalanced single-quote characters (known in English as +apostrophes). These confuse @code{#if 0}. They don't confuse +@samp{/*}. + +@node Diagnostics +@chapter Diagnostics +@cindex diagnostic +@cindex reporting errors +@cindex reporting warnings + +@findex #error +The directive @samp{#error} causes the preprocessor to report a fatal +error. The tokens forming the rest of the line following @samp{#error} +are used as the error message. + +You would use @samp{#error} inside of a conditional that detects a +combination of parameters which you know the program does not properly +support. For example, if you know that the program will not run +properly on a VAX, you might write + +@smallexample +@group +#ifdef __vax__ +#error "Won't work on VAXen. See comments at get_last_object." +#endif +@end group +@end smallexample + +If you have several configuration parameters that must be set up by +the installation in a consistent way, you can use conditionals to detect +an inconsistency and report it with @samp{#error}. For example, + +@smallexample +#if !defined(UNALIGNED_INT_ASM_OP) && defined(DWARF2_DEBUGGING_INFO) +#error "DWARF2_DEBUGGING_INFO requires UNALIGNED_INT_ASM_OP." +#endif +@end smallexample + +@findex #warning +The directive @samp{#warning} is like @samp{#error}, but causes the +preprocessor to issue a warning and continue preprocessing. The tokens +following @samp{#warning} are used as the warning message. + +You might use @samp{#warning} in obsolete header files, with a message +directing the user to the header file which should be used instead. + +Neither @samp{#error} nor @samp{#warning} macro-expands its argument. +Internal whitespace sequences are each replaced with a single space. +The line must consist of complete tokens. It is wisest to make the +argument of these directives be a single string constant; this avoids +problems with apostrophes and the like. + +@node Line Control +@chapter Line Control +@cindex line control + +The C preprocessor informs the C compiler of the location in your source +code where each token came from. Presently, this is just the file name +and line number. All the tokens resulting from macro expansion are +reported as having appeared on the line of the source file where the +outermost macro was used. We intend to be more accurate in the future. + +If you write a program which generates source code, such as the +@command{bison} parser generator, you may want to adjust the preprocessor's +notion of the current file name and line number by hand. Parts of the +output from @command{bison} are generated from scratch, other parts come +from a standard parser file. The rest are copied verbatim from +@command{bison}'s input. You would like compiler error messages and +symbolic debuggers to be able to refer to @code{bison}'s input file. + +@findex #line +@command{bison} or any such program can arrange this by writing +@samp{#line} directives into the output file. @samp{#line} is a +directive that specifies the original line number and source file name +for subsequent input in the current preprocessor input file. +@samp{#line} has three variants: + +@table @code +@item #line @var{linenum} +@var{linenum} is a non-negative decimal integer constant. It specifies +the line number which should be reported for the following line of +input. Subsequent lines are counted from @var{linenum}. + +@item #line @var{linenum} @var{filename} +@var{linenum} is the same as for the first form, and has the same +effect. In addition, @var{filename} is a string constant. The +following line and all subsequent lines are reported to come from the +file it specifies, until something else happens to change that. +@var{filename} is interpreted according to the normal rules for a string +constant: backslash escapes are interpreted. This is different from +@samp{#include}. + +Previous versions of CPP did not interpret escapes in @samp{#line}; +we have changed it because the standard requires they be interpreted, +and most other compilers do. + +@item #line @var{anything else} +@var{anything else} is checked for macro calls, which are expanded. +The result should match one of the above two forms. +@end table + +@samp{#line} directives alter the results of the @code{__FILE__} and +@code{__LINE__} predefined macros from that point on. @xref{Standard +Predefined Macros}. They do not have any effect on @samp{#include}'s +idea of the directory containing the current file. This is a change +from GCC 2.95. Previously, a file reading + +@smallexample +#line 1 "../src/gram.y" +#include "gram.h" +@end smallexample + +would search for @file{gram.h} in @file{../src}, then the @option{-I} +chain; the directory containing the physical source file would not be +searched. In GCC 3.0 and later, the @samp{#include} is not affected by +the presence of a @samp{#line} referring to a different directory. + +We made this change because the old behavior caused problems when +generated source files were transported between machines. For instance, +it is common practice to ship generated parsers with a source release, +so that people building the distribution do not need to have yacc or +Bison installed. These files frequently have @samp{#line} directives +referring to the directory tree of the system where the distribution was +created. If GCC tries to search for headers in those directories, the +build is likely to fail. + +The new behavior can cause failures too, if the generated file is not +in the same directory as its source and it attempts to include a header +which would be visible searching from the directory containing the +source file. However, this problem is easily solved with an additional +@option{-I} switch on the command line. The failures caused by the old +semantics could sometimes be corrected only by editing the generated +files, which is difficult and error-prone. + +@node Pragmas +@chapter Pragmas + +The @samp{#pragma} directive is the method specified by the C standard +for providing additional information to the compiler, beyond what is +conveyed in the language itself. Three forms of this directive +(commonly known as @dfn{pragmas}) are specified by the 1999 C standard. +A C compiler is free to attach any meaning it likes to other pragmas. + +GCC has historically preferred to use extensions to the syntax of the +language, such as @code{__attribute__}, for this purpose. However, GCC +does define a few pragmas of its own. These mostly have effects on the +entire translation unit or source file. + +In GCC version 3, all GNU-defined, supported pragmas have been given a +@code{GCC} prefix. This is in line with the @code{STDC} prefix on all +pragmas defined by C99. For backward compatibility, pragmas which were +recognized by previous versions are still recognized without the +@code{GCC} prefix, but that usage is deprecated. Some older pragmas are +deprecated in their entirety. They are not recognized with the +@code{GCC} prefix. @xref{Obsolete Features}. + +@cindex @code{_Pragma} +C99 introduces the @code{@w{_Pragma}} operator. This feature addresses a +major problem with @samp{#pragma}: being a directive, it cannot be +produced as the result of macro expansion. @code{@w{_Pragma}} is an +operator, much like @code{sizeof} or @code{defined}, and can be embedded +in a macro. + +Its syntax is @code{@w{_Pragma (@var{string-literal})}}, where +@var{string-literal} can be either a normal or wide-character string +literal. It is destringized, by replacing all @samp{\\} with a single +@samp{\} and all @samp{\"} with a @samp{"}. The result is then +processed as if it had appeared as the right hand side of a +@samp{#pragma} directive. For example, + +@smallexample +_Pragma ("GCC dependency \"parse.y\"") +@end smallexample + +@noindent +has the same effect as @code{#pragma GCC dependency "parse.y"}. The +same effect could be achieved using macros, for example + +@smallexample +#define DO_PRAGMA(x) _Pragma (#x) +DO_PRAGMA (GCC dependency "parse.y") +@end smallexample + +The standard is unclear on where a @code{_Pragma} operator can appear. +The preprocessor does not accept it within a preprocessing conditional +directive like @samp{#if}. To be safe, you are probably best keeping it +out of directives other than @samp{#define}, and putting it on a line of +its own. + +This manual documents the pragmas which are meaningful to the +preprocessor itself. Other pragmas are meaningful to the C or C++ +compilers. They are documented in the GCC manual. + +GCC plugins may provide their own pragmas. + +@ftable @code +@item #pragma GCC dependency +@code{#pragma GCC dependency} allows you to check the relative dates of +the current file and another file. If the other file is more recent than +the current file, a warning is issued. This is useful if the current +file is derived from the other file, and should be regenerated. The +other file is searched for using the normal include search path. +Optional trailing text can be used to give more information in the +warning message. + +@smallexample +#pragma GCC dependency "parse.y" +#pragma GCC dependency "/usr/include/time.h" rerun fixincludes +@end smallexample + +@item #pragma GCC poison +Sometimes, there is an identifier that you want to remove completely +from your program, and make sure that it never creeps back in. To +enforce this, you can @dfn{poison} the identifier with this pragma. +@code{#pragma GCC poison} is followed by a list of identifiers to +poison. If any of those identifiers appears anywhere in the source +after the directive, it is a hard error. For example, + +@smallexample +#pragma GCC poison printf sprintf fprintf +sprintf(some_string, "hello"); +@end smallexample + +@noindent +will produce an error. + +If a poisoned identifier appears as part of the expansion of a macro +which was defined before the identifier was poisoned, it will @emph{not} +cause an error. This lets you poison an identifier without worrying +about system headers defining macros that use it. + +For example, + +@smallexample +#define strrchr rindex +#pragma GCC poison rindex +strrchr(some_string, 'h'); +@end smallexample + +@noindent +will not produce an error. + +@item #pragma GCC system_header +This pragma takes no arguments. It causes the rest of the code in the +current file to be treated as if it came from a system header. +@xref{System Headers}. + +@end ftable + +@node Other Directives +@chapter Other Directives + +@findex #ident +@findex #sccs +The @samp{#ident} directive takes one argument, a string constant. On +some systems, that string constant is copied into a special segment of +the object file. On other systems, the directive is ignored. The +@samp{#sccs} directive is a synonym for @samp{#ident}. + +These directives are not part of the C standard, but they are not +official GNU extensions either. What historical information we have +been able to find, suggests they originated with System V@. + +@cindex null directive +The @dfn{null directive} consists of a @samp{#} followed by a newline, +with only whitespace (including comments) in between. A null directive +is understood as a preprocessing directive but has no effect on the +preprocessor output. The primary significance of the existence of the +null directive is that an input line consisting of just a @samp{#} will +produce no output, rather than a line of output containing just a +@samp{#}. Supposedly some old C programs contain such lines. + +@node Preprocessor Output +@chapter Preprocessor Output + +When the C preprocessor is used with the C, C++, or Objective-C +compilers, it is integrated into the compiler and communicates a stream +of binary tokens directly to the compiler's parser. However, it can +also be used in the more conventional standalone mode, where it produces +textual output. +@c FIXME: Document the library interface. + +@cindex output format +The output from the C preprocessor looks much like the input, except +that all preprocessing directive lines have been replaced with blank +lines and all comments with spaces. Long runs of blank lines are +discarded. + +The ISO standard specifies that it is implementation defined whether a +preprocessor preserves whitespace between tokens, or replaces it with +e.g.@: a single space. In GNU CPP, whitespace between tokens is collapsed +to become a single space, with the exception that the first token on a +non-directive line is preceded with sufficient spaces that it appears in +the same column in the preprocessed output that it appeared in the +original source file. This is so the output is easy to read. +@xref{Differences from previous versions}. CPP does not insert any +whitespace where there was none in the original source, except where +necessary to prevent an accidental token paste. + +@cindex linemarkers +Source file name and line number information is conveyed by lines +of the form + +@smallexample +# @var{linenum} @var{filename} @var{flags} +@end smallexample + +@noindent +These are called @dfn{linemarkers}. They are inserted as needed into +the output (but never within a string or character constant). They mean +that the following line originated in file @var{filename} at line +@var{linenum}. @var{filename} will never contain any non-printing +characters; they are replaced with octal escape sequences. + +After the file name comes zero or more flags, which are @samp{1}, +@samp{2}, @samp{3}, or @samp{4}. If there are multiple flags, spaces +separate them. Here is what the flags mean: + +@table @samp +@item 1 +This indicates the start of a new file. +@item 2 +This indicates returning to a file (after having included another file). +@item 3 +This indicates that the following text comes from a system header file, +so certain warnings should be suppressed. +@item 4 +This indicates that the following text should be treated as being +wrapped in an implicit @code{extern "C"} block. +@c maybe cross reference NO_IMPLICIT_EXTERN_C +@end table + +As an extension, the preprocessor accepts linemarkers in non-assembler +input files. They are treated like the corresponding @samp{#line} +directive, (@pxref{Line Control}), except that trailing flags are +permitted, and are interpreted with the meanings described above. If +multiple flags are given, they must be in ascending order. + +Some directives may be duplicated in the output of the preprocessor. +These are @samp{#ident} (always), @samp{#pragma} (only if the +preprocessor does not handle the pragma itself), and @samp{#define} and +@samp{#undef} (with certain debugging options). If this happens, the +@samp{#} of the directive will always be in the first column, and there +will be no space between the @samp{#} and the directive name. If macro +expansion happens to generate tokens which might be mistaken for a +duplicated directive, a space will be inserted between the @samp{#} and +the directive name. + +@node Traditional Mode +@chapter Traditional Mode + +Traditional (pre-standard) C preprocessing is rather different from +the preprocessing specified by the standard. When GCC is given the +@option{-traditional-cpp} option, it attempts to emulate a traditional +preprocessor. + +GCC versions 3.2 and later only support traditional mode semantics in +the preprocessor, and not in the compiler front ends. This chapter +outlines the traditional preprocessor semantics we implemented. + +The implementation does not correspond precisely to the behavior of +earlier versions of GCC, nor to any true traditional preprocessor. +After all, inconsistencies among traditional implementations were a +major motivation for C standardization. However, we intend that it +should be compatible with true traditional preprocessors in all ways +that actually matter. + +@menu +* Traditional lexical analysis:: +* Traditional macros:: +* Traditional miscellany:: +* Traditional warnings:: +@end menu + +@node Traditional lexical analysis +@section Traditional lexical analysis + +The traditional preprocessor does not decompose its input into tokens +the same way a standards-conforming preprocessor does. The input is +simply treated as a stream of text with minimal internal form. + +This implementation does not treat trigraphs (@pxref{trigraphs}) +specially since they were an invention of the standards committee. It +handles arbitrarily-positioned escaped newlines properly and splices +the lines as you would expect; many traditional preprocessors did not +do this. + +The form of horizontal whitespace in the input file is preserved in +the output. In particular, hard tabs remain hard tabs. This can be +useful if, for example, you are preprocessing a Makefile. + +Traditional CPP only recognizes C-style block comments, and treats the +@samp{/*} sequence as introducing a comment only if it lies outside +quoted text. Quoted text is introduced by the usual single and double +quotes, and also by an initial @samp{<} in a @code{#include} +directive. + +Traditionally, comments are completely removed and are not replaced +with a space. Since a traditional compiler does its own tokenization +of the output of the preprocessor, this means that comments can +effectively be used as token paste operators. However, comments +behave like separators for text handled by the preprocessor itself, +since it doesn't re-lex its input. For example, in + +@smallexample +#if foo/**/bar +@end smallexample + +@noindent +@samp{foo} and @samp{bar} are distinct identifiers and expanded +separately if they happen to be macros. In other words, this +directive is equivalent to + +@smallexample +#if foo bar +@end smallexample + +@noindent +rather than + +@smallexample +#if foobar +@end smallexample + +Generally speaking, in traditional mode an opening quote need not have +a matching closing quote. In particular, a macro may be defined with +replacement text that contains an unmatched quote. Of course, if you +attempt to compile preprocessed output containing an unmatched quote +you will get a syntax error. + +However, all preprocessing directives other than @code{#define} +require matching quotes. For example: + +@smallexample +#define m This macro's fine and has an unmatched quote +"/* This is not a comment. */ +/* @r{This is a comment. The following #include directive + is ill-formed.} */ +#include ' character. Note that we don't allow +the terminators of header names to be escaped; the first `"' or `>' +terminates the header name. + + Interpretation of some character sequences depends upon whether we +are lexing C, C++ or Objective-C, and on the revision of the standard in +force. For example, `::' is a single token in C++, but in C it is two +separate `:' tokens and almost certainly a syntax error. Such cases +are handled by `_cpp_lex_direct' based upon command-line flags stored +in the `cpp_options' structure. + + Once a token has been lexed, it leads an independent existence. The +spelling of numbers, identifiers and strings is copied to permanent +storage from the original input buffer, so a token remains valid and +correct even if its source buffer is freed with `_cpp_pop_buffer'. The +storage holding the spellings of such tokens remains until the client +program calls cpp_destroy, probably at the end of the translation unit. + +Lexing a line +============= + +When the preprocessor was changed to return pointers to tokens, one +feature I wanted was some sort of guarantee regarding how long a +returned pointer remains valid. This is important to the stand-alone +preprocessor, the future direction of the C family front ends, and even +to cpplib itself internally. + + Occasionally the preprocessor wants to be able to peek ahead in the +token stream. For example, after the name of a function-like macro, it +wants to check the next token to see if it is an opening parenthesis. +Another example is that, after reading the first few tokens of a +`#pragma' directive and not recognizing it as a registered pragma, it +wants to backtrack and allow the user-defined handler for unknown +pragmas to access the full `#pragma' token stream. The stand-alone +preprocessor wants to be able to test the current token with the +previous one to see if a space needs to be inserted to preserve their +separate tokenization upon re-lexing (paste avoidance), so it needs to +be sure the pointer to the previous token is still valid. The +recursive-descent C++ parser wants to be able to perform tentative +parsing arbitrarily far ahead in the token stream, and then to be able +to jump back to a prior position in that stream if necessary. + + The rule I chose, which is fairly natural, is to arrange that the +preprocessor lex all tokens on a line consecutively into a token buffer, +which I call a "token run", and when meeting an unescaped new line +(newlines within comments do not count either), to start lexing back at +the beginning of the run. Note that we do _not_ lex a line of tokens +at once; if we did that `parse_identifier' would not have state flags +available to warn about invalid identifiers (*note Invalid +identifiers::). + + In other words, accessing tokens that appeared earlier in the current +line is valid, but since each logical line overwrites the tokens of the +previous line, tokens from prior lines are unavailable. In particular, +since a directive only occupies a single logical line, this means that +the directive handlers like the `#pragma' handler can jump around in +the directive's tokens if necessary. + + Two issues remain: what about tokens that arise from macro +expansions, and what happens when we have a long line that overflows +the token run? + + Since we promise clients that we preserve the validity of pointers +that we have already returned for tokens that appeared earlier in the +line, we cannot reallocate the run. Instead, on overflow it is +expanded by chaining a new token run on to the end of the existing one. + + The tokens forming a macro's replacement list are collected by the +`#define' handler, and placed in storage that is only freed by +`cpp_destroy'. So if a macro is expanded in the line of tokens, the +pointers to the tokens of its expansion that are returned will always +remain valid. However, macros are a little trickier than that, since +they give rise to three sources of fresh tokens. They are the built-in +macros like `__LINE__', and the `#' and `##' operators for +stringification and token pasting. I handled this by allocating space +for these tokens from the lexer's token run chain. This means they +automatically receive the same lifetime guarantees as lexed tokens, and +we don't need to concern ourselves with freeing them. + + Lexing into a line of tokens solves some of the token memory +management issues, but not all. The opening parenthesis after a +function-like macro name might lie on a different line, and the front +ends definitely want the ability to look ahead past the end of the +current line. So cpplib only moves back to the start of the token run +at the end of a line if the variable `keep_tokens' is zero. +Line-buffering is quite natural for the preprocessor, and as a result +the only time cpplib needs to increment this variable is whilst looking +for the opening parenthesis to, and reading the arguments of, a +function-like macro. In the near future cpplib will export an +interface to increment and decrement this variable, so that clients can +share full control over the lifetime of token pointers too. + + The routine `_cpp_lex_token' handles moving to new token runs, +calling `_cpp_lex_direct' to lex new tokens, or returning +previously-lexed tokens if we stepped back in the token stream. It also +checks each token for the `BOL' flag, which might indicate a directive +that needs to be handled, or require a start-of-line call-back to be +made. `_cpp_lex_token' also handles skipping over tokens in failed +conditional blocks, and invalidates the control macro of the +multiple-include optimization if a token was successfully lexed outside +a directive. In other words, its callers do not need to concern +themselves with such issues. + + +File: cppinternals.info, Node: Hash Nodes, Next: Macro Expansion, Prev: Lexer, Up: Top + +Hash Nodes +********** + +When cpplib encounters an "identifier", it generates a hash code for it +and stores it in the hash table. By "identifier" we mean tokens with +type `CPP_NAME'; this includes identifiers in the usual C sense, as +well as keywords, directive names, macro names and so on. For example, +all of `pragma', `int', `foo' and `__GNUC__' are identifiers and hashed +when lexed. + + Each node in the hash table contain various information about the +identifier it represents. For example, its length and type. At any one +time, each identifier falls into exactly one of three categories: + + * Macros + + These have been declared to be macros, either on the command line + or with `#define'. A few, such as `__TIME__' are built-ins + entered in the hash table during initialization. The hash node + for a normal macro points to a structure with more information + about the macro, such as whether it is function-like, how many + arguments it takes, and its expansion. Built-in macros are + flagged as special, and instead contain an enum indicating which + of the various built-in macros it is. + + * Assertions + + Assertions are in a separate namespace to macros. To enforce + this, cpp actually prepends a `#' character before hashing and + entering it in the hash table. An assertion's node points to a + chain of answers to that assertion. + + * Void + + Everything else falls into this category--an identifier that is not + currently a macro, or a macro that has since been undefined with + `#undef'. + + When preprocessing C++, this category also includes the named + operators, such as `xor'. In expressions these behave like the + operators they represent, but in contexts where the spelling of a + token matters they are spelt differently. This spelling + distinction is relevant when they are operands of the stringizing + and pasting macro operators `#' and `##'. Named operator hash + nodes are flagged, both to catch the spelling distinction and to + prevent them from being defined as macros. + + The same identifiers share the same hash node. Since each identifier +token, after lexing, contains a pointer to its hash node, this is used +to provide rapid lookup of various information. For example, when +parsing a `#define' statement, CPP flags each argument's identifier +hash node with the index of that argument. This makes duplicated +argument checking an O(1) operation for each argument. Similarly, for +each identifier in the macro's expansion, lookup to see if it is an +argument, and which argument it is, is also an O(1) operation. Further, +each directive name, such as `endif', has an associated directive enum +stored in its hash node, so that directive lookup is also O(1). + + +File: cppinternals.info, Node: Macro Expansion, Next: Token Spacing, Prev: Hash Nodes, Up: Top + +Macro Expansion Algorithm +************************* + +Macro expansion is a tricky operation, fraught with nasty corner cases +and situations that render what you thought was a nifty way to optimize +the preprocessor's expansion algorithm wrong in quite subtle ways. + + I strongly recommend you have a good grasp of how the C and C++ +standards require macros to be expanded before diving into this +section, let alone the code!. If you don't have a clear mental picture +of how things like nested macro expansion, stringification and token +pasting are supposed to work, damage to your sanity can quickly result. + +Internal representation of macros +================================= + +The preprocessor stores macro expansions in tokenized form. This saves +repeated lexing passes during expansion, at the cost of a small +increase in memory consumption on average. The tokens are stored +contiguously in memory, so a pointer to the first one and a token count +is all you need to get the replacement list of a macro. + + If the macro is a function-like macro the preprocessor also stores +its parameters, in the form of an ordered list of pointers to the hash +table entry of each parameter's identifier. Further, in the macro's +stored expansion each occurrence of a parameter is replaced with a +special token of type `CPP_MACRO_ARG'. Each such token holds the index +of the parameter it represents in the parameter list, which allows +rapid replacement of parameters with their arguments during expansion. +Despite this optimization it is still necessary to store the original +parameters to the macro, both for dumping with e.g., `-dD', and to warn +about non-trivial macro redefinitions when the parameter names have +changed. + +Macro expansion overview +======================== + +The preprocessor maintains a "context stack", implemented as a linked +list of `cpp_context' structures, which together represent the macro +expansion state at any one time. The `struct cpp_reader' member +variable `context' points to the current top of this stack. The top +normally holds the unexpanded replacement list of the innermost macro +under expansion, except when cpplib is about to pre-expand an argument, +in which case it holds that argument's unexpanded tokens. + + When there are no macros under expansion, cpplib is in "base +context". All contexts other than the base context contain a +contiguous list of tokens delimited by a starting and ending token. +When not in base context, cpplib obtains the next token from the list +of the top context. If there are no tokens left in the list, it pops +that context off the stack, and subsequent ones if necessary, until an +unexhausted context is found or it returns to base context. In base +context, cpplib reads tokens directly from the lexer. + + If it encounters an identifier that is both a macro and enabled for +expansion, cpplib prepares to push a new context for that macro on the +stack by calling the routine `enter_macro_context'. When this routine +returns, the new context will contain the unexpanded tokens of the +replacement list of that macro. In the case of function-like macros, +`enter_macro_context' also replaces any parameters in the replacement +list, stored as `CPP_MACRO_ARG' tokens, with the appropriate macro +argument. If the standard requires that the parameter be replaced with +its expanded argument, the argument will have been fully macro expanded +first. + + `enter_macro_context' also handles special macros like `__LINE__'. +Although these macros expand to a single token which cannot contain any +further macros, for reasons of token spacing (*note Token Spacing::) +and simplicity of implementation, cpplib handles these special macros +by pushing a context containing just that one token. + + The final thing that `enter_macro_context' does before returning is +to mark the macro disabled for expansion (except for special macros +like `__TIME__'). The macro is re-enabled when its context is later +popped from the context stack, as described above. This strict +ordering ensures that a macro is disabled whilst its expansion is being +scanned, but that it is _not_ disabled whilst any arguments to it are +being expanded. + +Scanning the replacement list for macros to expand +================================================== + +The C standard states that, after any parameters have been replaced +with their possibly-expanded arguments, the replacement list is scanned +for nested macros. Further, any identifiers in the replacement list +that are not expanded during this scan are never again eligible for +expansion in the future, if the reason they were not expanded is that +the macro in question was disabled. + + Clearly this latter condition can only apply to tokens resulting from +argument pre-expansion. Other tokens never have an opportunity to be +re-tested for expansion. It is possible for identifiers that are +function-like macros to not expand initially but to expand during a +later scan. This occurs when the identifier is the last token of an +argument (and therefore originally followed by a comma or a closing +parenthesis in its macro's argument list), and when it replaces its +parameter in the macro's replacement list, the subsequent token happens +to be an opening parenthesis (itself possibly the first token of an +argument). + + It is important to note that when cpplib reads the last token of a +given context, that context still remains on the stack. Only when +looking for the _next_ token do we pop it off the stack and drop to a +lower context. This makes backing up by one token easy, but more +importantly ensures that the macro corresponding to the current context +is still disabled when we are considering the last token of its +replacement list for expansion (or indeed expanding it). As an +example, which illustrates many of the points above, consider + + #define foo(x) bar x + foo(foo) (2) + +which fully expands to `bar foo (2)'. During pre-expansion of the +argument, `foo' does not expand even though the macro is enabled, since +it has no following parenthesis [pre-expansion of an argument only uses +tokens from that argument; it cannot take tokens from whatever follows +the macro invocation]. This still leaves the argument token `foo' +eligible for future expansion. Then, when re-scanning after argument +replacement, the token `foo' is rejected for expansion, and marked +ineligible for future expansion, since the macro is now disabled. It +is disabled because the replacement list `bar foo' of the macro is +still on the context stack. + + If instead the algorithm looked for an opening parenthesis first and +then tested whether the macro were disabled it would be subtly wrong. +In the example above, the replacement list of `foo' would be popped in +the process of finding the parenthesis, re-enabling `foo' and expanding +it a second time. + +Looking for a function-like macro's opening parenthesis +======================================================= + +Function-like macros only expand when immediately followed by a +parenthesis. To do this cpplib needs to temporarily disable macros and +read the next token. Unfortunately, because of spacing issues (*note +Token Spacing::), there can be fake padding tokens in-between, and if +the next real token is not a parenthesis cpplib needs to be able to +back up that one token as well as retain the information in any +intervening padding tokens. + + Backing up more than one token when macros are involved is not +permitted by cpplib, because in general it might involve issues like +restoring popped contexts onto the context stack, which are too hard. +Instead, searching for the parenthesis is handled by a special +function, `funlike_invocation_p', which remembers padding information +as it reads tokens. If the next real token is not an opening +parenthesis, it backs up that one token, and then pushes an extra +context just containing the padding information if necessary. + +Marking tokens ineligible for future expansion +============================================== + +As discussed above, cpplib needs a way of marking tokens as +unexpandable. Since the tokens cpplib handles are read-only once they +have been lexed, it instead makes a copy of the token and adds the flag +`NO_EXPAND' to the copy. + + For efficiency and to simplify memory management by avoiding having +to remember to free these tokens, they are allocated as temporary tokens +from the lexer's current token run (*note Lexing a line::) using the +function `_cpp_temp_token'. The tokens are then re-used once the +current line of tokens has been read in. + + This might sound unsafe. However, tokens runs are not re-used at the +end of a line if it happens to be in the middle of a macro argument +list, and cpplib only wants to back-up more than one lexer token in +situations where no macro expansion is involved, so the optimization is +safe. + + +File: cppinternals.info, Node: Token Spacing, Next: Line Numbering, Prev: Macro Expansion, Up: Top + +Token Spacing +************* + +First, consider an issue that only concerns the stand-alone +preprocessor: there needs to be a guarantee that re-reading its +preprocessed output results in an identical token stream. Without +taking special measures, this might not be the case because of macro +substitution. For example: + + #define PLUS + + #define EMPTY + #define f(x) =x= + +PLUS -EMPTY- PLUS+ f(=) + ==> + + - - + + = = = + _not_ + ==> ++ -- ++ === + + One solution would be to simply insert a space between all adjacent +tokens. However, we would like to keep space insertion to a minimum, +both for aesthetic reasons and because it causes problems for people who +still try to abuse the preprocessor for things like Fortran source and +Makefiles. + + For now, just notice that when tokens are added (or removed, as +shown by the `EMPTY' example) from the original lexed token stream, we +need to check for accidental token pasting. We call this "paste +avoidance". Token addition and removal can only occur because of macro +expansion, but accidental pasting can occur in many places: both before +and after each macro replacement, each argument replacement, and +additionally each token created by the `#' and `##' operators. + + Look at how the preprocessor gets whitespace output correct +normally. The `cpp_token' structure contains a flags byte, and one of +those flags is `PREV_WHITE'. This is flagged by the lexer, and +indicates that the token was preceded by whitespace of some form other +than a new line. The stand-alone preprocessor can use this flag to +decide whether to insert a space between tokens in the output. + + Now consider the result of the following macro expansion: + + #define add(x, y, z) x + y +z; + sum = add (1,2, 3); + ==> sum = 1 + 2 +3; + + The interesting thing here is that the tokens `1' and `2' are output +with a preceding space, and `3' is output without a preceding space, +but when lexed none of these tokens had that property. Careful +consideration reveals that `1' gets its preceding whitespace from the +space preceding `add' in the macro invocation, _not_ replacement list. +`2' gets its whitespace from the space preceding the parameter `y' in +the macro replacement list, and `3' has no preceding space because +parameter `z' has none in the replacement list. + + Once lexed, tokens are effectively fixed and cannot be altered, since +pointers to them might be held in many places, in particular by +in-progress macro expansions. So instead of modifying the two tokens +above, the preprocessor inserts a special token, which I call a +"padding token", into the token stream to indicate that spacing of the +subsequent token is special. The preprocessor inserts padding tokens +in front of every macro expansion and expanded macro argument. These +point to a "source token" from which the subsequent real token should +inherit its spacing. In the above example, the source tokens are `add' +in the macro invocation, and `y' and `z' in the macro replacement list, +respectively. + + It is quite easy to get multiple padding tokens in a row, for +example if a macro's first replacement token expands straight into +another macro. + + #define foo bar + #define bar baz + [foo] + ==> [baz] + + Here, two padding tokens are generated with sources the `foo' token +between the brackets, and the `bar' token from foo's replacement list, +respectively. Clearly the first padding token is the one to use, so +the output code should contain a rule that the first padding token in a +sequence is the one that matters. + + But what if a macro expansion is left? Adjusting the above example +slightly: + + #define foo bar + #define bar EMPTY baz + #define EMPTY + [foo] EMPTY; + ==> [ baz] ; + + As shown, now there should be a space before `baz' and the semicolon +in the output. + + The rules we decided above fail for `baz': we generate three padding +tokens, one per macro invocation, before the token `baz'. We would +then have it take its spacing from the first of these, which carries +source token `foo' with no leading space. + + It is vital that cpplib get spacing correct in these examples since +any of these macro expansions could be stringified, where spacing +matters. + + So, this demonstrates that not just entering macro and argument +expansions, but leaving them requires special handling too. I made +cpplib insert a padding token with a `NULL' source token when leaving +macro expansions, as well as after each replaced argument in a macro's +replacement list. It also inserts appropriate padding tokens on either +side of tokens created by the `#' and `##' operators. I expanded the +rule so that, if we see a padding token with a `NULL' source token, +_and_ that source token has no leading space, then we behave as if we +have seen no padding tokens at all. A quick check shows this rule will +then get the above example correct as well. + + Now a relationship with paste avoidance is apparent: we have to be +careful about paste avoidance in exactly the same locations we have +padding tokens in order to get white space correct. This makes +implementation of paste avoidance easy: wherever the stand-alone +preprocessor is fixing up spacing because of padding tokens, and it +turns out that no space is needed, it has to take the extra step to +check that a space is not needed after all to avoid an accidental paste. +The function `cpp_avoid_paste' advises whether a space is required +between two consecutive tokens. To avoid excessive spacing, it tries +hard to only require a space if one is likely to be necessary, but for +reasons of efficiency it is slightly conservative and might recommend a +space where one is not strictly needed. + + +File: cppinternals.info, Node: Line Numbering, Next: Guard Macros, Prev: Token Spacing, Up: Top + +Line numbering +************** + +Just which line number anyway? +============================== + +There are three reasonable requirements a cpplib client might have for +the line number of a token passed to it: + + * The source line it was lexed on. + + * The line it is output on. This can be different to the line it was + lexed on if, for example, there are intervening escaped newlines or + C-style comments. For example: + + foo /* A long + comment */ bar \ + baz + => + foo bar baz + + * If the token results from a macro expansion, the line of the macro + name, or possibly the line of the closing parenthesis in the case + of function-like macro expansion. + + The `cpp_token' structure contains `line' and `col' members. The +lexer fills these in with the line and column of the first character of +the token. Consequently, but maybe unexpectedly, a token from the +replacement list of a macro expansion carries the location of the token +within the `#define' directive, because cpplib expands a macro by +returning pointers to the tokens in its replacement list. The current +implementation of cpplib assigns tokens created from built-in macros +and the `#' and `##' operators the location of the most recently lexed +token. This is a because they are allocated from the lexer's token +runs, and because of the way the diagnostic routines infer the +appropriate location to report. + + The diagnostic routines in cpplib display the location of the most +recently _lexed_ token, unless they are passed a specific line and +column to report. For diagnostics regarding tokens that arise from +macro expansions, it might also be helpful for the user to see the +original location in the macro definition that the token came from. +Since that is exactly the information each token carries, such an +enhancement could be made relatively easily in future. + + The stand-alone preprocessor faces a similar problem when determining +the correct line to output the token on: the position attached to a +token is fairly useless if the token came from a macro expansion. All +tokens on a logical line should be output on its first physical line, so +the token's reported location is also wrong if it is part of a physical +line other than the first. + + To solve these issues, cpplib provides a callback that is generated +whenever it lexes a preprocessing token that starts a new logical line +other than a directive. It passes this token (which may be a `CPP_EOF' +token indicating the end of the translation unit) to the callback +routine, which can then use the line and column of this token to +produce correct output. + +Representation of line numbers +============================== + +As mentioned above, cpplib stores with each token the line number that +it was lexed on. In fact, this number is not the number of the line in +the source file, but instead bears more resemblance to the number of the +line in the translation unit. + + The preprocessor maintains a monotonic increasing line count, which +is incremented at every new line character (and also at the end of any +buffer that does not end in a new line). Since a line number of zero is +useful to indicate certain special states and conditions, this variable +starts counting from one. + + This variable therefore uniquely enumerates each line in the +translation unit. With some simple infrastructure, it is straight +forward to map from this to the original source file and line number +pair, saving space whenever line number information needs to be saved. +The code the implements this mapping lies in the files `line-map.c' and +`line-map.h'. + + Command-line macros and assertions are implemented by pushing a +buffer containing the right hand side of an equivalent `#define' or +`#assert' directive. Some built-in macros are handled similarly. +Since these are all processed before the first line of the main input +file, it will typically have an assigned line closer to twenty than to +one. + + +File: cppinternals.info, Node: Guard Macros, Next: Files, Prev: Line Numbering, Up: Top + +The Multiple-Include Optimization +********************************* + +Header files are often of the form + + #ifndef FOO + #define FOO + ... + #endif + +to prevent the compiler from processing them more than once. The +preprocessor notices such header files, so that if the header file +appears in a subsequent `#include' directive and `FOO' is defined, then +it is ignored and it doesn't preprocess or even re-open the file a +second time. This is referred to as the "multiple include +optimization". + + Under what circumstances is such an optimization valid? If the file +were included a second time, it can only be optimized away if that +inclusion would result in no tokens to return, and no relevant +directives to process. Therefore the current implementation imposes +requirements and makes some allowances as follows: + + 1. There must be no tokens outside the controlling `#if'-`#endif' + pair, but whitespace and comments are permitted. + + 2. There must be no directives outside the controlling directive + pair, but the "null directive" (a line containing nothing other + than a single `#' and possibly whitespace) is permitted. + + 3. The opening directive must be of the form + + #ifndef FOO + + or + + #if !defined FOO [equivalently, #if !defined(FOO)] + + 4. In the second form above, the tokens forming the `#if' expression + must have come directly from the source file--no macro expansion + must have been involved. This is because macro definitions can + change, and tracking whether or not a relevant change has been + made is not worth the implementation cost. + + 5. There can be no `#else' or `#elif' directives at the outer + conditional block level, because they would probably contain + something of interest to a subsequent pass. + + First, when pushing a new file on the buffer stack, +`_stack_include_file' sets the controlling macro `mi_cmacro' to `NULL', +and sets `mi_valid' to `true'. This indicates that the preprocessor +has not yet encountered anything that would invalidate the +multiple-include optimization. As described in the next few +paragraphs, these two variables having these values effectively +indicates top-of-file. + + When about to return a token that is not part of a directive, +`_cpp_lex_token' sets `mi_valid' to `false'. This enforces the +constraint that tokens outside the controlling conditional block +invalidate the optimization. + + The `do_if', when appropriate, and `do_ifndef' directive handlers +pass the controlling macro to the function `push_conditional'. cpplib +maintains a stack of nested conditional blocks, and after processing +every opening conditional this function pushes an `if_stack' structure +onto the stack. In this structure it records the controlling macro for +the block, provided there is one and we're at top-of-file (as described +above). If an `#elif' or `#else' directive is encountered, the +controlling macro for that block is cleared to `NULL'. Otherwise, it +survives until the `#endif' closing the block, upon which `do_endif' +sets `mi_valid' to true and stores the controlling macro in `mi_cmacro'. + + `_cpp_handle_directive' clears `mi_valid' when processing any +directive other than an opening conditional and the null directive. +With this, and requiring top-of-file to record a controlling macro, and +no `#else' or `#elif' for it to survive and be copied to `mi_cmacro' by +`do_endif', we have enforced the absence of directives outside the main +conditional block for the optimization to be on. + + Note that whilst we are inside the conditional block, `mi_valid' is +likely to be reset to `false', but this does not matter since the +closing `#endif' restores it to `true' if appropriate. + + Finally, since `_cpp_lex_direct' pops the file off the buffer stack +at `EOF' without returning a token, if the `#endif' directive was not +followed by any tokens, `mi_valid' is `true' and `_cpp_pop_file_buffer' +remembers the controlling macro associated with the file. Subsequent +calls to `stack_include_file' result in no buffer being pushed if the +controlling macro is defined, effecting the optimization. + + A quick word on how we handle the + + #if !defined FOO + +case. `_cpp_parse_expr' and `parse_defined' take steps to see whether +the three stages `!', `defined-expression' and `end-of-directive' occur +in order in a `#if' expression. If so, they return the guard macro to +`do_if' in the variable `mi_ind_cmacro', and otherwise set it to `NULL'. +`enter_macro_context' sets `mi_valid' to false, so if a macro was +expanded whilst parsing any part of the expression, then the +top-of-file test in `push_conditional' fails and the optimization is +turned off. + + +File: cppinternals.info, Node: Files, Next: Concept Index, Prev: Guard Macros, Up: Top + +File Handling +************* + +Fairly obviously, the file handling code of cpplib resides in the file +`files.c'. It takes care of the details of file searching, opening, +reading and caching, for both the main source file and all the headers +it recursively includes. + + The basic strategy is to minimize the number of system calls. On +many systems, the basic `open ()' and `fstat ()' system calls can be +quite expensive. For every `#include'-d file, we need to try all the +directories in the search path until we find a match. Some projects, +such as glibc, pass twenty or thirty include paths on the command line, +so this can rapidly become time consuming. + + For a header file we have not encountered before we have little +choice but to do this. However, it is often the case that the same +headers are repeatedly included, and in these cases we try to avoid +repeating the filesystem queries whilst searching for the correct file. + + For each file we try to open, we store the constructed path in a +splay tree. This path first undergoes simplification by the function +`_cpp_simplify_pathname'. For example, `/usr/include/bits/../foo.h' is +simplified to `/usr/include/foo.h' before we enter it in the splay tree +and try to `open ()' the file. CPP will then find subsequent uses of +`foo.h', even as `/usr/include/foo.h', in the splay tree and save +system calls. + + Further, it is likely the file contents have also been cached, +saving a `read ()' system call. We don't bother caching the contents of +header files that are re-inclusion protected, and whose re-inclusion +macro is defined when we leave the header file for the first time. If +the host supports it, we try to map suitably large files into memory, +rather than reading them in directly. + + The include paths are internally stored on a null-terminated +singly-linked list, starting with the `"header.h"' directory search +chain, which then links into the `' directory chain. + + Files included with the `' syntax start the lookup directly +in the second half of this chain. However, files included with the +`"foo.h"' syntax start at the beginning of the chain, but with one +extra directory prepended. This is the directory of the current file; +the one containing the `#include' directive. Prepending this directory +on a per-file basis is handled by the function `search_from'. + + Note that a header included with a directory component, such as +`#include "mydir/foo.h"' and opened as +`/usr/local/include/mydir/foo.h', will have the complete path minus the +basename `foo.h' as the current directory. + + Enough information is stored in the splay tree that CPP can +immediately tell whether it can skip the header file because of the +multiple include optimization, whether the file didn't exist or +couldn't be opened for some reason, or whether the header was flagged +not to be re-used, as it is with the obsolete `#import' directive. + + For the benefit of MS-DOS filesystems with an 8.3 filename +limitation, CPP offers the ability to treat various include file names +as aliases for the real header files with shorter names. The map from +one to the other is found in a special file called `header.gcc', stored +in the command line (or system) include directories to which the mapping +applies. This may be higher up the directory tree than the full path to +the file minus the base name. + + +File: cppinternals.info, Node: Concept Index, Prev: Files, Up: Top + +Concept Index +************* + +[index] +* Menu: + +* assertions: Hash Nodes. (line 6) +* controlling macros: Guard Macros. (line 6) +* escaped newlines: Lexer. (line 6) +* files: Files. (line 6) +* guard macros: Guard Macros. (line 6) +* hash table: Hash Nodes. (line 6) +* header files: Conventions. (line 6) +* identifiers: Hash Nodes. (line 6) +* interface: Conventions. (line 6) +* lexer: Lexer. (line 6) +* line numbers: Line Numbering. (line 6) +* macro expansion: Macro Expansion. (line 6) +* macro representation (internal): Macro Expansion. (line 19) +* macros: Hash Nodes. (line 6) +* multiple-include optimization: Guard Macros. (line 6) +* named operators: Hash Nodes. (line 6) +* newlines: Lexer. (line 6) +* paste avoidance: Token Spacing. (line 6) +* spacing: Token Spacing. (line 6) +* token run: Lexer. (line 192) +* token spacing: Token Spacing. (line 6) + + + +Tag Table: +Node: Top980 +Node: Conventions2665 +Node: Lexer3607 +Ref: Invalid identifiers11520 +Ref: Lexing a line13469 +Node: Hash Nodes18242 +Node: Macro Expansion21121 +Node: Token Spacing30068 +Node: Line Numbering35928 +Node: Guard Macros40013 +Node: Files44804 +Node: Concept Index48270 + +End Tag Table diff --git a/gcc/doc/cppinternals.texi b/gcc/doc/cppinternals.texi new file mode 100644 index 000000000..a22ef0d42 --- /dev/null +++ b/gcc/doc/cppinternals.texi @@ -0,0 +1,1068 @@ +\input texinfo +@setfilename cppinternals.info +@settitle The GNU C Preprocessor Internals + +@include gcc-common.texi + +@ifinfo +@dircategory Software development +@direntry +* Cpplib: (cppinternals). Cpplib internals. +@end direntry +@end ifinfo + +@c @smallbook +@c @cropmarks +@c @finalout +@setchapternewpage odd +@ifinfo +This file documents the internals of the GNU C Preprocessor. + +Copyright 2000, 2001, 2002, 2004, 2005, 2006, 2007 Free Software +Foundation, Inc. + +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. + +@ignore +Permission is granted to process this file through Tex and print the +results, provided the printed document carries copying permission +notice identical to this one except for the removal of this paragraph +(this paragraph not being relevant to the printed manual). + +@end ignore +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided also that +the entire resulting derived work is distributed under the terms of a +permission notice identical to this one. + +Permission is granted to copy and distribute translations of this manual +into another language, under the above conditions for modified versions. +@end ifinfo + +@titlepage +@title Cpplib Internals +@versionsubtitle +@author Neil Booth +@page +@vskip 0pt plus 1filll +@c man begin COPYRIGHT +Copyright @copyright{} 2000, 2001, 2002, 2004, 2005 +Free Software Foundation, Inc. + +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 also that +the entire resulting derived work is distributed under the terms of a +permission notice identical to this one. + +Permission is granted to copy and distribute translations of this manual +into another language, under the above conditions for modified versions. +@c man end +@end titlepage +@contents +@page + +@ifnottex +@node Top +@top +@chapter Cpplib---the GNU C Preprocessor + +The GNU C preprocessor is +implemented as a library, @dfn{cpplib}, so it can be easily shared between +a stand-alone preprocessor, and a preprocessor integrated with the C, +C++ and Objective-C front ends. It is also available for use by other +programs, though this is not recommended as its exposed interface has +not yet reached a point of reasonable stability. + +The library has been written to be re-entrant, so that it can be used +to preprocess many files simultaneously if necessary. It has also been +written with the preprocessing token as the fundamental unit; the +preprocessor in previous versions of GCC would operate on text strings +as the fundamental unit. + +This brief manual documents the internals of cpplib, and explains some +of the tricky issues. It is intended that, along with the comments in +the source code, a reasonably competent C programmer should be able to +figure out what the code is doing, and why things have been implemented +the way they have. + +@menu +* Conventions:: Conventions used in the code. +* Lexer:: The combined C, C++ and Objective-C Lexer. +* Hash Nodes:: All identifiers are entered into a hash table. +* Macro Expansion:: Macro expansion algorithm. +* Token Spacing:: Spacing and paste avoidance issues. +* Line Numbering:: Tracking location within files. +* Guard Macros:: Optimizing header files with guard macros. +* Files:: File handling. +* Concept Index:: Index. +@end menu +@end ifnottex + +@node Conventions +@unnumbered Conventions +@cindex interface +@cindex header files + +cpplib has two interfaces---one is exposed internally only, and the +other is for both internal and external use. + +The convention is that functions and types that are exposed to multiple +files internally are prefixed with @samp{_cpp_}, and are to be found in +the file @file{internal.h}. Functions and types exposed to external +clients are in @file{cpplib.h}, and prefixed with @samp{cpp_}. For +historical reasons this is no longer quite true, but we should strive to +stick to it. + +We are striving to reduce the information exposed in @file{cpplib.h} to the +bare minimum necessary, and then to keep it there. This makes clear +exactly what external clients are entitled to assume, and allows us to +change internals in the future without worrying whether library clients +are perhaps relying on some kind of undocumented implementation-specific +behavior. + +@node Lexer +@unnumbered The Lexer +@cindex lexer +@cindex newlines +@cindex escaped newlines + +@section Overview +The lexer is contained in the file @file{lex.c}. It is a hand-coded +lexer, and not implemented as a state machine. It can understand C, C++ +and Objective-C source code, and has been extended to allow reasonably +successful preprocessing of assembly language. The lexer does not make +an initial pass to strip out trigraphs and escaped newlines, but handles +them as they are encountered in a single pass of the input file. It +returns preprocessing tokens individually, not a line at a time. + +It is mostly transparent to users of the library, since the library's +interface for obtaining the next token, @code{cpp_get_token}, takes care +of lexing new tokens, handling directives, and expanding macros as +necessary. However, the lexer does expose some functionality so that +clients of the library can easily spell a given token, such as +@code{cpp_spell_token} and @code{cpp_token_len}. These functions are +useful when generating diagnostics, and for emitting the preprocessed +output. + +@section Lexing a token +Lexing of an individual token is handled by @code{_cpp_lex_direct} and +its subroutines. In its current form the code is quite complicated, +with read ahead characters and such-like, since it strives to not step +back in the character stream in preparation for handling non-ASCII file +encodings. The current plan is to convert any such files to UTF-8 +before processing them. This complexity is therefore unnecessary and +will be removed, so I'll not discuss it further here. + +The job of @code{_cpp_lex_direct} is simply to lex a token. It is not +responsible for issues like directive handling, returning lookahead +tokens directly, multiple-include optimization, or conditional block +skipping. It necessarily has a minor r@^ole to play in memory +management of lexed lines. I discuss these issues in a separate section +(@pxref{Lexing a line}). + +The lexer places the token it lexes into storage pointed to by the +variable @code{cur_token}, and then increments it. This variable is +important for correct diagnostic positioning. Unless a specific line +and column are passed to the diagnostic routines, they will examine the +@code{line} and @code{col} values of the token just before the location +that @code{cur_token} points to, and use that location to report the +diagnostic. + +The lexer does not consider whitespace to be a token in its own right. +If whitespace (other than a new line) precedes a token, it sets the +@code{PREV_WHITE} bit in the token's flags. Each token has its +@code{line} and @code{col} variables set to the line and column of the +first character of the token. This line number is the line number in +the translation unit, and can be converted to a source (file, line) pair +using the line map code. + +The first token on a logical, i.e.@: unescaped, line has the flag +@code{BOL} set for beginning-of-line. This flag is intended for +internal use, both to distinguish a @samp{#} that begins a directive +from one that doesn't, and to generate a call-back to clients that want +to be notified about the start of every non-directive line with tokens +on it. Clients cannot reliably determine this for themselves: the first +token might be a macro, and the tokens of a macro expansion do not have +the @code{BOL} flag set. The macro expansion may even be empty, and the +next token on the line certainly won't have the @code{BOL} flag set. + +New lines are treated specially; exactly how the lexer handles them is +context-dependent. The C standard mandates that directives are +terminated by the first unescaped newline character, even if it appears +in the middle of a macro expansion. Therefore, if the state variable +@code{in_directive} is set, the lexer returns a @code{CPP_EOF} token, +which is normally used to indicate end-of-file, to indicate +end-of-directive. In a directive a @code{CPP_EOF} token never means +end-of-file. Conveniently, if the caller was @code{collect_args}, it +already handles @code{CPP_EOF} as if it were end-of-file, and reports an +error about an unterminated macro argument list. + +The C standard also specifies that a new line in the middle of the +arguments to a macro is treated as whitespace. This white space is +important in case the macro argument is stringified. The state variable +@code{parsing_args} is nonzero when the preprocessor is collecting the +arguments to a macro call. It is set to 1 when looking for the opening +parenthesis to a function-like macro, and 2 when collecting the actual +arguments up to the closing parenthesis, since these two cases need to +be distinguished sometimes. One such time is here: the lexer sets the +@code{PREV_WHITE} flag of a token if it meets a new line when +@code{parsing_args} is set to 2. It doesn't set it if it meets a new +line when @code{parsing_args} is 1, since then code like + +@smallexample +#define foo() bar +foo +baz +@end smallexample + +@noindent would be output with an erroneous space before @samp{baz}: + +@smallexample +foo + baz +@end smallexample + +This is a good example of the subtlety of getting token spacing correct +in the preprocessor; there are plenty of tests in the testsuite for +corner cases like this. + +The lexer is written to treat each of @samp{\r}, @samp{\n}, @samp{\r\n} +and @samp{\n\r} as a single new line indicator. This allows it to +transparently preprocess MS-DOS, Macintosh and Unix files without their +needing to pass through a special filter beforehand. + +We also decided to treat a backslash, either @samp{\} or the trigraph +@samp{??/}, separated from one of the above newline indicators by +non-comment whitespace only, as intending to escape the newline. It +tends to be a typing mistake, and cannot reasonably be mistaken for +anything else in any of the C-family grammars. Since handling it this +way is not strictly conforming to the ISO standard, the library issues a +warning wherever it encounters it. + +Handling newlines like this is made simpler by doing it in one place +only. The function @code{handle_newline} takes care of all newline +characters, and @code{skip_escaped_newlines} takes care of arbitrarily +long sequences of escaped newlines, deferring to @code{handle_newline} +to handle the newlines themselves. + +The most painful aspect of lexing ISO-standard C and C++ is handling +trigraphs and backlash-escaped newlines. Trigraphs are processed before +any interpretation of the meaning of a character is made, and unfortunately +there is a trigraph representation for a backslash, so it is possible for +the trigraph @samp{??/} to introduce an escaped newline. + +Escaped newlines are tedious because theoretically they can occur +anywhere---between the @samp{+} and @samp{=} of the @samp{+=} token, +within the characters of an identifier, and even between the @samp{*} +and @samp{/} that terminates a comment. Moreover, you cannot be sure +there is just one---there might be an arbitrarily long sequence of them. + +So, for example, the routine that lexes a number, @code{parse_number}, +cannot assume that it can scan forwards until the first non-number +character and be done with it, because this could be the @samp{\} +introducing an escaped newline, or the @samp{?} introducing the trigraph +sequence that represents the @samp{\} of an escaped newline. If it +encounters a @samp{?} or @samp{\}, it calls @code{skip_escaped_newlines} +to skip over any potential escaped newlines before checking whether the +number has been finished. + +Similarly code in the main body of @code{_cpp_lex_direct} cannot simply +check for a @samp{=} after a @samp{+} character to determine whether it +has a @samp{+=} token; it needs to be prepared for an escaped newline of +some sort. Such cases use the function @code{get_effective_char}, which +returns the first character after any intervening escaped newlines. + +The lexer needs to keep track of the correct column position, including +counting tabs as specified by the @option{-ftabstop=} option. This +should be done even within C-style comments; they can appear in the +middle of a line, and we want to report diagnostics in the correct +position for text appearing after the end of the comment. + +@anchor{Invalid identifiers} +Some identifiers, such as @code{__VA_ARGS__} and poisoned identifiers, +may be invalid and require a diagnostic. However, if they appear in a +macro expansion we don't want to complain with each use of the macro. +It is therefore best to catch them during the lexing stage, in +@code{parse_identifier}. In both cases, whether a diagnostic is needed +or not is dependent upon the lexer's state. For example, we don't want +to issue a diagnostic for re-poisoning a poisoned identifier, or for +using @code{__VA_ARGS__} in the expansion of a variable-argument macro. +Therefore @code{parse_identifier} makes use of state flags to determine +whether a diagnostic is appropriate. Since we change state on a +per-token basis, and don't lex whole lines at a time, this is not a +problem. + +Another place where state flags are used to change behavior is whilst +lexing header names. Normally, a @samp{<} would be lexed as a single +token. After a @code{#include} directive, though, it should be lexed as +a single token as far as the nearest @samp{>} character. Note that we +don't allow the terminators of header names to be escaped; the first +@samp{"} or @samp{>} terminates the header name. + +Interpretation of some character sequences depends upon whether we are +lexing C, C++ or Objective-C, and on the revision of the standard in +force. For example, @samp{::} is a single token in C++, but in C it is +two separate @samp{:} tokens and almost certainly a syntax error. Such +cases are handled by @code{_cpp_lex_direct} based upon command-line +flags stored in the @code{cpp_options} structure. + +Once a token has been lexed, it leads an independent existence. The +spelling of numbers, identifiers and strings is copied to permanent +storage from the original input buffer, so a token remains valid and +correct even if its source buffer is freed with @code{_cpp_pop_buffer}. +The storage holding the spellings of such tokens remains until the +client program calls cpp_destroy, probably at the end of the translation +unit. + +@anchor{Lexing a line} +@section Lexing a line +@cindex token run + +When the preprocessor was changed to return pointers to tokens, one +feature I wanted was some sort of guarantee regarding how long a +returned pointer remains valid. This is important to the stand-alone +preprocessor, the future direction of the C family front ends, and even +to cpplib itself internally. + +Occasionally the preprocessor wants to be able to peek ahead in the +token stream. For example, after the name of a function-like macro, it +wants to check the next token to see if it is an opening parenthesis. +Another example is that, after reading the first few tokens of a +@code{#pragma} directive and not recognizing it as a registered pragma, +it wants to backtrack and allow the user-defined handler for unknown +pragmas to access the full @code{#pragma} token stream. The stand-alone +preprocessor wants to be able to test the current token with the +previous one to see if a space needs to be inserted to preserve their +separate tokenization upon re-lexing (paste avoidance), so it needs to +be sure the pointer to the previous token is still valid. The +recursive-descent C++ parser wants to be able to perform tentative +parsing arbitrarily far ahead in the token stream, and then to be able +to jump back to a prior position in that stream if necessary. + +The rule I chose, which is fairly natural, is to arrange that the +preprocessor lex all tokens on a line consecutively into a token buffer, +which I call a @dfn{token run}, and when meeting an unescaped new line +(newlines within comments do not count either), to start lexing back at +the beginning of the run. Note that we do @emph{not} lex a line of +tokens at once; if we did that @code{parse_identifier} would not have +state flags available to warn about invalid identifiers (@pxref{Invalid +identifiers}). + +In other words, accessing tokens that appeared earlier in the current +line is valid, but since each logical line overwrites the tokens of the +previous line, tokens from prior lines are unavailable. In particular, +since a directive only occupies a single logical line, this means that +the directive handlers like the @code{#pragma} handler can jump around +in the directive's tokens if necessary. + +Two issues remain: what about tokens that arise from macro expansions, +and what happens when we have a long line that overflows the token run? + +Since we promise clients that we preserve the validity of pointers that +we have already returned for tokens that appeared earlier in the line, +we cannot reallocate the run. Instead, on overflow it is expanded by +chaining a new token run on to the end of the existing one. + +The tokens forming a macro's replacement list are collected by the +@code{#define} handler, and placed in storage that is only freed by +@code{cpp_destroy}. So if a macro is expanded in the line of tokens, +the pointers to the tokens of its expansion that are returned will always +remain valid. However, macros are a little trickier than that, since +they give rise to three sources of fresh tokens. They are the built-in +macros like @code{__LINE__}, and the @samp{#} and @samp{##} operators +for stringification and token pasting. I handled this by allocating +space for these tokens from the lexer's token run chain. This means +they automatically receive the same lifetime guarantees as lexed tokens, +and we don't need to concern ourselves with freeing them. + +Lexing into a line of tokens solves some of the token memory management +issues, but not all. The opening parenthesis after a function-like +macro name might lie on a different line, and the front ends definitely +want the ability to look ahead past the end of the current line. So +cpplib only moves back to the start of the token run at the end of a +line if the variable @code{keep_tokens} is zero. Line-buffering is +quite natural for the preprocessor, and as a result the only time cpplib +needs to increment this variable is whilst looking for the opening +parenthesis to, and reading the arguments of, a function-like macro. In +the near future cpplib will export an interface to increment and +decrement this variable, so that clients can share full control over the +lifetime of token pointers too. + +The routine @code{_cpp_lex_token} handles moving to new token runs, +calling @code{_cpp_lex_direct} to lex new tokens, or returning +previously-lexed tokens if we stepped back in the token stream. It also +checks each token for the @code{BOL} flag, which might indicate a +directive that needs to be handled, or require a start-of-line call-back +to be made. @code{_cpp_lex_token} also handles skipping over tokens in +failed conditional blocks, and invalidates the control macro of the +multiple-include optimization if a token was successfully lexed outside +a directive. In other words, its callers do not need to concern +themselves with such issues. + +@node Hash Nodes +@unnumbered Hash Nodes +@cindex hash table +@cindex identifiers +@cindex macros +@cindex assertions +@cindex named operators + +When cpplib encounters an ``identifier'', it generates a hash code for +it and stores it in the hash table. By ``identifier'' we mean tokens +with type @code{CPP_NAME}; this includes identifiers in the usual C +sense, as well as keywords, directive names, macro names and so on. For +example, all of @code{pragma}, @code{int}, @code{foo} and +@code{__GNUC__} are identifiers and hashed when lexed. + +Each node in the hash table contain various information about the +identifier it represents. For example, its length and type. At any one +time, each identifier falls into exactly one of three categories: + +@itemize @bullet +@item Macros + +These have been declared to be macros, either on the command line or +with @code{#define}. A few, such as @code{__TIME__} are built-ins +entered in the hash table during initialization. The hash node for a +normal macro points to a structure with more information about the +macro, such as whether it is function-like, how many arguments it takes, +and its expansion. Built-in macros are flagged as special, and instead +contain an enum indicating which of the various built-in macros it is. + +@item Assertions + +Assertions are in a separate namespace to macros. To enforce this, cpp +actually prepends a @code{#} character before hashing and entering it in +the hash table. An assertion's node points to a chain of answers to +that assertion. + +@item Void + +Everything else falls into this category---an identifier that is not +currently a macro, or a macro that has since been undefined with +@code{#undef}. + +When preprocessing C++, this category also includes the named operators, +such as @code{xor}. In expressions these behave like the operators they +represent, but in contexts where the spelling of a token matters they +are spelt differently. This spelling distinction is relevant when they +are operands of the stringizing and pasting macro operators @code{#} and +@code{##}. Named operator hash nodes are flagged, both to catch the +spelling distinction and to prevent them from being defined as macros. +@end itemize + +The same identifiers share the same hash node. Since each identifier +token, after lexing, contains a pointer to its hash node, this is used +to provide rapid lookup of various information. For example, when +parsing a @code{#define} statement, CPP flags each argument's identifier +hash node with the index of that argument. This makes duplicated +argument checking an O(1) operation for each argument. Similarly, for +each identifier in the macro's expansion, lookup to see if it is an +argument, and which argument it is, is also an O(1) operation. Further, +each directive name, such as @code{endif}, has an associated directive +enum stored in its hash node, so that directive lookup is also O(1). + +@node Macro Expansion +@unnumbered Macro Expansion Algorithm +@cindex macro expansion + +Macro expansion is a tricky operation, fraught with nasty corner cases +and situations that render what you thought was a nifty way to +optimize the preprocessor's expansion algorithm wrong in quite subtle +ways. + +I strongly recommend you have a good grasp of how the C and C++ +standards require macros to be expanded before diving into this +section, let alone the code!. If you don't have a clear mental +picture of how things like nested macro expansion, stringification and +token pasting are supposed to work, damage to your sanity can quickly +result. + +@section Internal representation of macros +@cindex macro representation (internal) + +The preprocessor stores macro expansions in tokenized form. This +saves repeated lexing passes during expansion, at the cost of a small +increase in memory consumption on average. The tokens are stored +contiguously in memory, so a pointer to the first one and a token +count is all you need to get the replacement list of a macro. + +If the macro is a function-like macro the preprocessor also stores its +parameters, in the form of an ordered list of pointers to the hash +table entry of each parameter's identifier. Further, in the macro's +stored expansion each occurrence of a parameter is replaced with a +special token of type @code{CPP_MACRO_ARG}. Each such token holds the +index of the parameter it represents in the parameter list, which +allows rapid replacement of parameters with their arguments during +expansion. Despite this optimization it is still necessary to store +the original parameters to the macro, both for dumping with e.g., +@option{-dD}, and to warn about non-trivial macro redefinitions when +the parameter names have changed. + +@section Macro expansion overview +The preprocessor maintains a @dfn{context stack}, implemented as a +linked list of @code{cpp_context} structures, which together represent +the macro expansion state at any one time. The @code{struct +cpp_reader} member variable @code{context} points to the current top +of this stack. The top normally holds the unexpanded replacement list +of the innermost macro under expansion, except when cpplib is about to +pre-expand an argument, in which case it holds that argument's +unexpanded tokens. + +When there are no macros under expansion, cpplib is in @dfn{base +context}. All contexts other than the base context contain a +contiguous list of tokens delimited by a starting and ending token. +When not in base context, cpplib obtains the next token from the list +of the top context. If there are no tokens left in the list, it pops +that context off the stack, and subsequent ones if necessary, until an +unexhausted context is found or it returns to base context. In base +context, cpplib reads tokens directly from the lexer. + +If it encounters an identifier that is both a macro and enabled for +expansion, cpplib prepares to push a new context for that macro on the +stack by calling the routine @code{enter_macro_context}. When this +routine returns, the new context will contain the unexpanded tokens of +the replacement list of that macro. In the case of function-like +macros, @code{enter_macro_context} also replaces any parameters in the +replacement list, stored as @code{CPP_MACRO_ARG} tokens, with the +appropriate macro argument. If the standard requires that the +parameter be replaced with its expanded argument, the argument will +have been fully macro expanded first. + +@code{enter_macro_context} also handles special macros like +@code{__LINE__}. Although these macros expand to a single token which +cannot contain any further macros, for reasons of token spacing +(@pxref{Token Spacing}) and simplicity of implementation, cpplib +handles these special macros by pushing a context containing just that +one token. + +The final thing that @code{enter_macro_context} does before returning +is to mark the macro disabled for expansion (except for special macros +like @code{__TIME__}). The macro is re-enabled when its context is +later popped from the context stack, as described above. This strict +ordering ensures that a macro is disabled whilst its expansion is +being scanned, but that it is @emph{not} disabled whilst any arguments +to it are being expanded. + +@section Scanning the replacement list for macros to expand +The C standard states that, after any parameters have been replaced +with their possibly-expanded arguments, the replacement list is +scanned for nested macros. Further, any identifiers in the +replacement list that are not expanded during this scan are never +again eligible for expansion in the future, if the reason they were +not expanded is that the macro in question was disabled. + +Clearly this latter condition can only apply to tokens resulting from +argument pre-expansion. Other tokens never have an opportunity to be +re-tested for expansion. It is possible for identifiers that are +function-like macros to not expand initially but to expand during a +later scan. This occurs when the identifier is the last token of an +argument (and therefore originally followed by a comma or a closing +parenthesis in its macro's argument list), and when it replaces its +parameter in the macro's replacement list, the subsequent token +happens to be an opening parenthesis (itself possibly the first token +of an argument). + +It is important to note that when cpplib reads the last token of a +given context, that context still remains on the stack. Only when +looking for the @emph{next} token do we pop it off the stack and drop +to a lower context. This makes backing up by one token easy, but more +importantly ensures that the macro corresponding to the current +context is still disabled when we are considering the last token of +its replacement list for expansion (or indeed expanding it). As an +example, which illustrates many of the points above, consider + +@smallexample +#define foo(x) bar x +foo(foo) (2) +@end smallexample + +@noindent which fully expands to @samp{bar foo (2)}. During pre-expansion +of the argument, @samp{foo} does not expand even though the macro is +enabled, since it has no following parenthesis [pre-expansion of an +argument only uses tokens from that argument; it cannot take tokens +from whatever follows the macro invocation]. This still leaves the +argument token @samp{foo} eligible for future expansion. Then, when +re-scanning after argument replacement, the token @samp{foo} is +rejected for expansion, and marked ineligible for future expansion, +since the macro is now disabled. It is disabled because the +replacement list @samp{bar foo} of the macro is still on the context +stack. + +If instead the algorithm looked for an opening parenthesis first and +then tested whether the macro were disabled it would be subtly wrong. +In the example above, the replacement list of @samp{foo} would be +popped in the process of finding the parenthesis, re-enabling +@samp{foo} and expanding it a second time. + +@section Looking for a function-like macro's opening parenthesis +Function-like macros only expand when immediately followed by a +parenthesis. To do this cpplib needs to temporarily disable macros +and read the next token. Unfortunately, because of spacing issues +(@pxref{Token Spacing}), there can be fake padding tokens in-between, +and if the next real token is not a parenthesis cpplib needs to be +able to back up that one token as well as retain the information in +any intervening padding tokens. + +Backing up more than one token when macros are involved is not +permitted by cpplib, because in general it might involve issues like +restoring popped contexts onto the context stack, which are too hard. +Instead, searching for the parenthesis is handled by a special +function, @code{funlike_invocation_p}, which remembers padding +information as it reads tokens. If the next real token is not an +opening parenthesis, it backs up that one token, and then pushes an +extra context just containing the padding information if necessary. + +@section Marking tokens ineligible for future expansion +As discussed above, cpplib needs a way of marking tokens as +unexpandable. Since the tokens cpplib handles are read-only once they +have been lexed, it instead makes a copy of the token and adds the +flag @code{NO_EXPAND} to the copy. + +For efficiency and to simplify memory management by avoiding having to +remember to free these tokens, they are allocated as temporary tokens +from the lexer's current token run (@pxref{Lexing a line}) using the +function @code{_cpp_temp_token}. The tokens are then re-used once the +current line of tokens has been read in. + +This might sound unsafe. However, tokens runs are not re-used at the +end of a line if it happens to be in the middle of a macro argument +list, and cpplib only wants to back-up more than one lexer token in +situations where no macro expansion is involved, so the optimization +is safe. + +@node Token Spacing +@unnumbered Token Spacing +@cindex paste avoidance +@cindex spacing +@cindex token spacing + +First, consider an issue that only concerns the stand-alone +preprocessor: there needs to be a guarantee that re-reading its preprocessed +output results in an identical token stream. Without taking special +measures, this might not be the case because of macro substitution. +For example: + +@smallexample +#define PLUS + +#define EMPTY +#define f(x) =x= ++PLUS -EMPTY- PLUS+ f(=) + @expansion{} + + - - + + = = = +@emph{not} + @expansion{} ++ -- ++ === +@end smallexample + +One solution would be to simply insert a space between all adjacent +tokens. However, we would like to keep space insertion to a minimum, +both for aesthetic reasons and because it causes problems for people who +still try to abuse the preprocessor for things like Fortran source and +Makefiles. + +For now, just notice that when tokens are added (or removed, as shown by +the @code{EMPTY} example) from the original lexed token stream, we need +to check for accidental token pasting. We call this @dfn{paste +avoidance}. Token addition and removal can only occur because of macro +expansion, but accidental pasting can occur in many places: both before +and after each macro replacement, each argument replacement, and +additionally each token created by the @samp{#} and @samp{##} operators. + +Look at how the preprocessor gets whitespace output correct +normally. The @code{cpp_token} structure contains a flags byte, and one +of those flags is @code{PREV_WHITE}. This is flagged by the lexer, and +indicates that the token was preceded by whitespace of some form other +than a new line. The stand-alone preprocessor can use this flag to +decide whether to insert a space between tokens in the output. + +Now consider the result of the following macro expansion: + +@smallexample +#define add(x, y, z) x + y +z; +sum = add (1,2, 3); + @expansion{} sum = 1 + 2 +3; +@end smallexample + +The interesting thing here is that the tokens @samp{1} and @samp{2} are +output with a preceding space, and @samp{3} is output without a +preceding space, but when lexed none of these tokens had that property. +Careful consideration reveals that @samp{1} gets its preceding +whitespace from the space preceding @samp{add} in the macro invocation, +@emph{not} replacement list. @samp{2} gets its whitespace from the +space preceding the parameter @samp{y} in the macro replacement list, +and @samp{3} has no preceding space because parameter @samp{z} has none +in the replacement list. + +Once lexed, tokens are effectively fixed and cannot be altered, since +pointers to them might be held in many places, in particular by +in-progress macro expansions. So instead of modifying the two tokens +above, the preprocessor inserts a special token, which I call a +@dfn{padding token}, into the token stream to indicate that spacing of +the subsequent token is special. The preprocessor inserts padding +tokens in front of every macro expansion and expanded macro argument. +These point to a @dfn{source token} from which the subsequent real token +should inherit its spacing. In the above example, the source tokens are +@samp{add} in the macro invocation, and @samp{y} and @samp{z} in the +macro replacement list, respectively. + +It is quite easy to get multiple padding tokens in a row, for example if +a macro's first replacement token expands straight into another macro. + +@smallexample +#define foo bar +#define bar baz +[foo] + @expansion{} [baz] +@end smallexample + +Here, two padding tokens are generated with sources the @samp{foo} token +between the brackets, and the @samp{bar} token from foo's replacement +list, respectively. Clearly the first padding token is the one to +use, so the output code should contain a rule that the first +padding token in a sequence is the one that matters. + +But what if a macro expansion is left? Adjusting the above +example slightly: + +@smallexample +#define foo bar +#define bar EMPTY baz +#define EMPTY +[foo] EMPTY; + @expansion{} [ baz] ; +@end smallexample + +As shown, now there should be a space before @samp{baz} and the +semicolon in the output. + +The rules we decided above fail for @samp{baz}: we generate three +padding tokens, one per macro invocation, before the token @samp{baz}. +We would then have it take its spacing from the first of these, which +carries source token @samp{foo} with no leading space. + +It is vital that cpplib get spacing correct in these examples since any +of these macro expansions could be stringified, where spacing matters. + +So, this demonstrates that not just entering macro and argument +expansions, but leaving them requires special handling too. I made +cpplib insert a padding token with a @code{NULL} source token when +leaving macro expansions, as well as after each replaced argument in a +macro's replacement list. It also inserts appropriate padding tokens on +either side of tokens created by the @samp{#} and @samp{##} operators. +I expanded the rule so that, if we see a padding token with a +@code{NULL} source token, @emph{and} that source token has no leading +space, then we behave as if we have seen no padding tokens at all. A +quick check shows this rule will then get the above example correct as +well. + +Now a relationship with paste avoidance is apparent: we have to be +careful about paste avoidance in exactly the same locations we have +padding tokens in order to get white space correct. This makes +implementation of paste avoidance easy: wherever the stand-alone +preprocessor is fixing up spacing because of padding tokens, and it +turns out that no space is needed, it has to take the extra step to +check that a space is not needed after all to avoid an accidental paste. +The function @code{cpp_avoid_paste} advises whether a space is required +between two consecutive tokens. To avoid excessive spacing, it tries +hard to only require a space if one is likely to be necessary, but for +reasons of efficiency it is slightly conservative and might recommend a +space where one is not strictly needed. + +@node Line Numbering +@unnumbered Line numbering +@cindex line numbers + +@section Just which line number anyway? + +There are three reasonable requirements a cpplib client might have for +the line number of a token passed to it: + +@itemize @bullet +@item +The source line it was lexed on. +@item +The line it is output on. This can be different to the line it was +lexed on if, for example, there are intervening escaped newlines or +C-style comments. For example: + +@smallexample +foo /* @r{A long +comment} */ bar \ +baz +@result{} +foo bar baz +@end smallexample + +@item +If the token results from a macro expansion, the line of the macro name, +or possibly the line of the closing parenthesis in the case of +function-like macro expansion. +@end itemize + +The @code{cpp_token} structure contains @code{line} and @code{col} +members. The lexer fills these in with the line and column of the first +character of the token. Consequently, but maybe unexpectedly, a token +from the replacement list of a macro expansion carries the location of +the token within the @code{#define} directive, because cpplib expands a +macro by returning pointers to the tokens in its replacement list. The +current implementation of cpplib assigns tokens created from built-in +macros and the @samp{#} and @samp{##} operators the location of the most +recently lexed token. This is a because they are allocated from the +lexer's token runs, and because of the way the diagnostic routines infer +the appropriate location to report. + +The diagnostic routines in cpplib display the location of the most +recently @emph{lexed} token, unless they are passed a specific line and +column to report. For diagnostics regarding tokens that arise from +macro expansions, it might also be helpful for the user to see the +original location in the macro definition that the token came from. +Since that is exactly the information each token carries, such an +enhancement could be made relatively easily in future. + +The stand-alone preprocessor faces a similar problem when determining +the correct line to output the token on: the position attached to a +token is fairly useless if the token came from a macro expansion. All +tokens on a logical line should be output on its first physical line, so +the token's reported location is also wrong if it is part of a physical +line other than the first. + +To solve these issues, cpplib provides a callback that is generated +whenever it lexes a preprocessing token that starts a new logical line +other than a directive. It passes this token (which may be a +@code{CPP_EOF} token indicating the end of the translation unit) to the +callback routine, which can then use the line and column of this token +to produce correct output. + +@section Representation of line numbers + +As mentioned above, cpplib stores with each token the line number that +it was lexed on. In fact, this number is not the number of the line in +the source file, but instead bears more resemblance to the number of the +line in the translation unit. + +The preprocessor maintains a monotonic increasing line count, which is +incremented at every new line character (and also at the end of any +buffer that does not end in a new line). Since a line number of zero is +useful to indicate certain special states and conditions, this variable +starts counting from one. + +This variable therefore uniquely enumerates each line in the translation +unit. With some simple infrastructure, it is straight forward to map +from this to the original source file and line number pair, saving space +whenever line number information needs to be saved. The code the +implements this mapping lies in the files @file{line-map.c} and +@file{line-map.h}. + +Command-line macros and assertions are implemented by pushing a buffer +containing the right hand side of an equivalent @code{#define} or +@code{#assert} directive. Some built-in macros are handled similarly. +Since these are all processed before the first line of the main input +file, it will typically have an assigned line closer to twenty than to +one. + +@node Guard Macros +@unnumbered The Multiple-Include Optimization +@cindex guard macros +@cindex controlling macros +@cindex multiple-include optimization + +Header files are often of the form + +@smallexample +#ifndef FOO +#define FOO +@dots{} +#endif +@end smallexample + +@noindent +to prevent the compiler from processing them more than once. The +preprocessor notices such header files, so that if the header file +appears in a subsequent @code{#include} directive and @code{FOO} is +defined, then it is ignored and it doesn't preprocess or even re-open +the file a second time. This is referred to as the @dfn{multiple +include optimization}. + +Under what circumstances is such an optimization valid? If the file +were included a second time, it can only be optimized away if that +inclusion would result in no tokens to return, and no relevant +directives to process. Therefore the current implementation imposes +requirements and makes some allowances as follows: + +@enumerate +@item +There must be no tokens outside the controlling @code{#if}-@code{#endif} +pair, but whitespace and comments are permitted. + +@item +There must be no directives outside the controlling directive pair, but +the @dfn{null directive} (a line containing nothing other than a single +@samp{#} and possibly whitespace) is permitted. + +@item +The opening directive must be of the form + +@smallexample +#ifndef FOO +@end smallexample + +or + +@smallexample +#if !defined FOO [equivalently, #if !defined(FOO)] +@end smallexample + +@item +In the second form above, the tokens forming the @code{#if} expression +must have come directly from the source file---no macro expansion must +have been involved. This is because macro definitions can change, and +tracking whether or not a relevant change has been made is not worth the +implementation cost. + +@item +There can be no @code{#else} or @code{#elif} directives at the outer +conditional block level, because they would probably contain something +of interest to a subsequent pass. +@end enumerate + +First, when pushing a new file on the buffer stack, +@code{_stack_include_file} sets the controlling macro @code{mi_cmacro} to +@code{NULL}, and sets @code{mi_valid} to @code{true}. This indicates +that the preprocessor has not yet encountered anything that would +invalidate the multiple-include optimization. As described in the next +few paragraphs, these two variables having these values effectively +indicates top-of-file. + +When about to return a token that is not part of a directive, +@code{_cpp_lex_token} sets @code{mi_valid} to @code{false}. This +enforces the constraint that tokens outside the controlling conditional +block invalidate the optimization. + +The @code{do_if}, when appropriate, and @code{do_ifndef} directive +handlers pass the controlling macro to the function +@code{push_conditional}. cpplib maintains a stack of nested conditional +blocks, and after processing every opening conditional this function +pushes an @code{if_stack} structure onto the stack. In this structure +it records the controlling macro for the block, provided there is one +and we're at top-of-file (as described above). If an @code{#elif} or +@code{#else} directive is encountered, the controlling macro for that +block is cleared to @code{NULL}. Otherwise, it survives until the +@code{#endif} closing the block, upon which @code{do_endif} sets +@code{mi_valid} to true and stores the controlling macro in +@code{mi_cmacro}. + +@code{_cpp_handle_directive} clears @code{mi_valid} when processing any +directive other than an opening conditional and the null directive. +With this, and requiring top-of-file to record a controlling macro, and +no @code{#else} or @code{#elif} for it to survive and be copied to +@code{mi_cmacro} by @code{do_endif}, we have enforced the absence of +directives outside the main conditional block for the optimization to be +on. + +Note that whilst we are inside the conditional block, @code{mi_valid} is +likely to be reset to @code{false}, but this does not matter since +the closing @code{#endif} restores it to @code{true} if appropriate. + +Finally, since @code{_cpp_lex_direct} pops the file off the buffer stack +at @code{EOF} without returning a token, if the @code{#endif} directive +was not followed by any tokens, @code{mi_valid} is @code{true} and +@code{_cpp_pop_file_buffer} remembers the controlling macro associated +with the file. Subsequent calls to @code{stack_include_file} result in +no buffer being pushed if the controlling macro is defined, effecting +the optimization. + +A quick word on how we handle the + +@smallexample +#if !defined FOO +@end smallexample + +@noindent +case. @code{_cpp_parse_expr} and @code{parse_defined} take steps to see +whether the three stages @samp{!}, @samp{defined-expression} and +@samp{end-of-directive} occur in order in a @code{#if} expression. If +so, they return the guard macro to @code{do_if} in the variable +@code{mi_ind_cmacro}, and otherwise set it to @code{NULL}. +@code{enter_macro_context} sets @code{mi_valid} to false, so if a macro +was expanded whilst parsing any part of the expression, then the +top-of-file test in @code{push_conditional} fails and the optimization +is turned off. + +@node Files +@unnumbered File Handling +@cindex files + +Fairly obviously, the file handling code of cpplib resides in the file +@file{files.c}. It takes care of the details of file searching, +opening, reading and caching, for both the main source file and all the +headers it recursively includes. + +The basic strategy is to minimize the number of system calls. On many +systems, the basic @code{open ()} and @code{fstat ()} system calls can +be quite expensive. For every @code{#include}-d file, we need to try +all the directories in the search path until we find a match. Some +projects, such as glibc, pass twenty or thirty include paths on the +command line, so this can rapidly become time consuming. + +For a header file we have not encountered before we have little choice +but to do this. However, it is often the case that the same headers are +repeatedly included, and in these cases we try to avoid repeating the +filesystem queries whilst searching for the correct file. + +For each file we try to open, we store the constructed path in a splay +tree. This path first undergoes simplification by the function +@code{_cpp_simplify_pathname}. For example, +@file{/usr/include/bits/../foo.h} is simplified to +@file{/usr/include/foo.h} before we enter it in the splay tree and try +to @code{open ()} the file. CPP will then find subsequent uses of +@file{foo.h}, even as @file{/usr/include/foo.h}, in the splay tree and +save system calls. + +Further, it is likely the file contents have also been cached, saving a +@code{read ()} system call. We don't bother caching the contents of +header files that are re-inclusion protected, and whose re-inclusion +macro is defined when we leave the header file for the first time. If +the host supports it, we try to map suitably large files into memory, +rather than reading them in directly. + +The include paths are internally stored on a null-terminated +singly-linked list, starting with the @code{"header.h"} directory search +chain, which then links into the @code{} directory chain. + +Files included with the @code{} syntax start the lookup directly +in the second half of this chain. However, files included with the +@code{"foo.h"} syntax start at the beginning of the chain, but with one +extra directory prepended. This is the directory of the current file; +the one containing the @code{#include} directive. Prepending this +directory on a per-file basis is handled by the function +@code{search_from}. + +Note that a header included with a directory component, such as +@code{#include "mydir/foo.h"} and opened as +@file{/usr/local/include/mydir/foo.h}, will have the complete path minus +the basename @samp{foo.h} as the current directory. + +Enough information is stored in the splay tree that CPP can immediately +tell whether it can skip the header file because of the multiple include +optimization, whether the file didn't exist or couldn't be opened for +some reason, or whether the header was flagged not to be re-used, as it +is with the obsolete @code{#import} directive. + +For the benefit of MS-DOS filesystems with an 8.3 filename limitation, +CPP offers the ability to treat various include file names as aliases +for the real header files with shorter names. The map from one to the +other is found in a special file called @samp{header.gcc}, stored in the +command line (or system) include directories to which the mapping +applies. This may be higher up the directory tree than the full path to +the file minus the base name. + +@node Concept Index +@unnumbered Concept Index +@printindex cp + +@bye diff --git a/gcc/doc/cppopts.texi b/gcc/doc/cppopts.texi new file mode 100644 index 000000000..52d59973a --- /dev/null +++ b/gcc/doc/cppopts.texi @@ -0,0 +1,797 @@ +@c Copyright (c) 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, +@c 2010, Free Software Foundation, Inc. +@c This is part of the CPP and GCC manuals. +@c For copying conditions, see the file gcc.texi. + +@c --------------------------------------------------------------------- +@c Options affecting the preprocessor +@c --------------------------------------------------------------------- + +@c If this file is included with the flag ``cppmanual'' set, it is +@c formatted for inclusion in the CPP manual; otherwise the main GCC manual. + +@table @gcctabopt +@item -D @var{name} +@opindex D +Predefine @var{name} as a macro, with definition @code{1}. + +@item -D @var{name}=@var{definition} +The contents of @var{definition} are tokenized and processed as if +they appeared during translation phase three in a @samp{#define} +directive. In particular, the definition will be truncated by +embedded newline characters. + +If you are invoking the preprocessor from a shell or shell-like +program you may need to use the shell's quoting syntax to protect +characters such as spaces that have a meaning in the shell syntax. + +If you wish to define a function-like macro on the command line, write +its argument list with surrounding parentheses before the equals sign +(if any). Parentheses are meaningful to most shells, so you will need +to quote the option. With @command{sh} and @command{csh}, +@option{-D'@var{name}(@var{args@dots{}})=@var{definition}'} works. + +@option{-D} and @option{-U} options are processed in the order they +are given on the command line. All @option{-imacros @var{file}} and +@option{-include @var{file}} options are processed after all +@option{-D} and @option{-U} options. + +@item -U @var{name} +@opindex U +Cancel any previous definition of @var{name}, either built in or +provided with a @option{-D} option. + +@item -undef +@opindex undef +Do not predefine any system-specific or GCC-specific macros. The +standard predefined macros remain defined. +@ifset cppmanual +@xref{Standard Predefined Macros}. +@end ifset + +@item -I @var{dir} +@opindex I +Add the directory @var{dir} to the list of directories to be searched +for header files. +@ifset cppmanual +@xref{Search Path}. +@end ifset +Directories named by @option{-I} are searched before the standard +system include directories. If the directory @var{dir} is a standard +system include directory, the option is ignored to ensure that the +default search order for system directories and the special treatment +of system headers are not defeated +@ifset cppmanual +(@pxref{System Headers}) +@end ifset +. +If @var{dir} begins with @code{=}, then the @code{=} will be replaced +by the sysroot prefix; see @option{--sysroot} and @option{-isysroot}. + +@item -o @var{file} +@opindex o +Write output to @var{file}. This is the same as specifying @var{file} +as the second non-option argument to @command{cpp}. @command{gcc} has a +different interpretation of a second non-option argument, so you must +use @option{-o} to specify the output file. + +@item -Wall +@opindex Wall +Turns on all optional warnings which are desirable for normal code. +At present this is @option{-Wcomment}, @option{-Wtrigraphs}, +@option{-Wmultichar} and a warning about integer promotion causing a +change of sign in @code{#if} expressions. Note that many of the +preprocessor's warnings are on by default and have no options to +control them. + +@item -Wcomment +@itemx -Wcomments +@opindex Wcomment +@opindex Wcomments +Warn whenever a comment-start sequence @samp{/*} appears in a @samp{/*} +comment, or whenever a backslash-newline appears in a @samp{//} comment. +(Both forms have the same effect.) + +@item -Wtrigraphs +@opindex Wtrigraphs +@anchor{Wtrigraphs} +Most trigraphs in comments cannot affect the meaning of the program. +However, a trigraph that would form an escaped newline (@samp{??/} at +the end of a line) can, by changing where the comment begins or ends. +Therefore, only trigraphs that would form escaped newlines produce +warnings inside a comment. + +This option is implied by @option{-Wall}. If @option{-Wall} is not +given, this option is still enabled unless trigraphs are enabled. To +get trigraph conversion without warnings, but get the other +@option{-Wall} warnings, use @samp{-trigraphs -Wall -Wno-trigraphs}. + +@item -Wtraditional +@opindex Wtraditional +Warn about certain constructs that behave differently in traditional and +ISO C@. Also warn about ISO C constructs that have no traditional C +equivalent, and problematic constructs which should be avoided. +@ifset cppmanual +@xref{Traditional Mode}. +@end ifset + +@item -Wundef +@opindex Wundef +Warn whenever an identifier which is not a macro is encountered in an +@samp{#if} directive, outside of @samp{defined}. Such identifiers are +replaced with zero. + +@item -Wunused-macros +@opindex Wunused-macros +Warn about macros defined in the main file that are unused. A macro +is @dfn{used} if it is expanded or tested for existence at least once. +The preprocessor will also warn if the macro has not been used at the +time it is redefined or undefined. + +Built-in macros, macros defined on the command line, and macros +defined in include files are not warned about. + +@emph{Note:} If a macro is actually used, but only used in skipped +conditional blocks, then CPP will report it as unused. To avoid the +warning in such a case, you might improve the scope of the macro's +definition by, for example, moving it into the first skipped block. +Alternatively, you could provide a dummy use with something like: + +@smallexample +#if defined the_macro_causing_the_warning +#endif +@end smallexample + +@item -Wendif-labels +@opindex Wendif-labels +Warn whenever an @samp{#else} or an @samp{#endif} are followed by text. +This usually happens in code of the form + +@smallexample +#if FOO +@dots{} +#else FOO +@dots{} +#endif FOO +@end smallexample + +@noindent +The second and third @code{FOO} should be in comments, but often are not +in older programs. This warning is on by default. + +@item -Werror +@opindex Werror +Make all warnings into hard errors. Source code which triggers warnings +will be rejected. + +@item -Wsystem-headers +@opindex Wsystem-headers +Issue warnings for code in system headers. These are normally unhelpful +in finding bugs in your own code, therefore suppressed. If you are +responsible for the system library, you may want to see them. + +@item -w +@opindex w +Suppress all warnings, including those which GNU CPP issues by default. + +@item -pedantic +@opindex pedantic +Issue all the mandatory diagnostics listed in the C standard. Some of +them are left out by default, since they trigger frequently on harmless +code. + +@item -pedantic-errors +@opindex pedantic-errors +Issue all the mandatory diagnostics, and make all mandatory diagnostics +into errors. This includes mandatory diagnostics that GCC issues +without @samp{-pedantic} but treats as warnings. + +@item -M +@opindex M +@cindex @command{make} +@cindex dependencies, @command{make} +Instead of outputting the result of preprocessing, output a rule +suitable for @command{make} describing the dependencies of the main +source file. The preprocessor outputs one @command{make} rule containing +the object file name for that source file, a colon, and the names of all +the included files, including those coming from @option{-include} or +@option{-imacros} command line options. + +Unless specified explicitly (with @option{-MT} or @option{-MQ}), the +object file name consists of the name of the source file with any +suffix replaced with object file suffix and with any leading directory +parts removed. If there are many included files then the rule is +split into several lines using @samp{\}-newline. The rule has no +commands. + +This option does not suppress the preprocessor's debug output, such as +@option{-dM}. To avoid mixing such debug output with the dependency +rules you should explicitly specify the dependency output file with +@option{-MF}, or use an environment variable like +@env{DEPENDENCIES_OUTPUT} (@pxref{Environment Variables}). Debug output +will still be sent to the regular output stream as normal. + +Passing @option{-M} to the driver implies @option{-E}, and suppresses +warnings with an implicit @option{-w}. + +@item -MM +@opindex MM +Like @option{-M} but do not mention header files that are found in +system header directories, nor header files that are included, +directly or indirectly, from such a header. + +This implies that the choice of angle brackets or double quotes in an +@samp{#include} directive does not in itself determine whether that +header will appear in @option{-MM} dependency output. This is a +slight change in semantics from GCC versions 3.0 and earlier. + +@anchor{dashMF} +@item -MF @var{file} +@opindex MF +When used with @option{-M} or @option{-MM}, specifies a +file to write the dependencies to. If no @option{-MF} switch is given +the preprocessor sends the rules to the same place it would have sent +preprocessed output. + +When used with the driver options @option{-MD} or @option{-MMD}, +@option{-MF} overrides the default dependency output file. + +@item -MG +@opindex MG +In conjunction with an option such as @option{-M} requesting +dependency generation, @option{-MG} assumes missing header files are +generated files and adds them to the dependency list without raising +an error. The dependency filename is taken directly from the +@code{#include} directive without prepending any path. @option{-MG} +also suppresses preprocessed output, as a missing header file renders +this useless. + +This feature is used in automatic updating of makefiles. + +@item -MP +@opindex MP +This option instructs CPP to add a phony target for each dependency +other than the main file, causing each to depend on nothing. These +dummy rules work around errors @command{make} gives if you remove header +files without updating the @file{Makefile} to match. + +This is typical output: + +@smallexample +test.o: test.c test.h + +test.h: +@end smallexample + +@item -MT @var{target} +@opindex MT + +Change the target of the rule emitted by dependency generation. By +default CPP takes the name of the main input file, deletes any +directory components and any file suffix such as @samp{.c}, and +appends the platform's usual object suffix. The result is the target. + +An @option{-MT} option will set the target to be exactly the string you +specify. If you want multiple targets, you can specify them as a single +argument to @option{-MT}, or use multiple @option{-MT} options. + +For example, @option{@w{-MT '$(objpfx)foo.o'}} might give + +@smallexample +$(objpfx)foo.o: foo.c +@end smallexample + +@item -MQ @var{target} +@opindex MQ + +Same as @option{-MT}, but it quotes any characters which are special to +Make. @option{@w{-MQ '$(objpfx)foo.o'}} gives + +@smallexample +$$(objpfx)foo.o: foo.c +@end smallexample + +The default target is automatically quoted, as if it were given with +@option{-MQ}. + +@item -MD +@opindex MD +@option{-MD} is equivalent to @option{-M -MF @var{file}}, except that +@option{-E} is not implied. The driver determines @var{file} based on +whether an @option{-o} option is given. If it is, the driver uses its +argument but with a suffix of @file{.d}, otherwise it takes the name +of the input file, removes any directory components and suffix, and +applies a @file{.d} suffix. + +If @option{-MD} is used in conjunction with @option{-E}, any +@option{-o} switch is understood to specify the dependency output file +(@pxref{dashMF,,-MF}), but if used without @option{-E}, each @option{-o} +is understood to specify a target object file. + +Since @option{-E} is not implied, @option{-MD} can be used to generate +a dependency output file as a side-effect of the compilation process. + +@item -MMD +@opindex MMD +Like @option{-MD} except mention only user header files, not system +header files. + +@ifclear cppmanual +@item -fpch-deps +@opindex fpch-deps +When using precompiled headers (@pxref{Precompiled Headers}), this flag +will cause the dependency-output flags to also list the files from the +precompiled header's dependencies. If not specified only the +precompiled header would be listed and not the files that were used to +create it because those files are not consulted when a precompiled +header is used. + +@item -fpch-preprocess +@opindex fpch-preprocess +This option allows use of a precompiled header (@pxref{Precompiled +Headers}) together with @option{-E}. It inserts a special @code{#pragma}, +@code{#pragma GCC pch_preprocess "@var{filename}"} in the output to mark +the place where the precompiled header was found, and its @var{filename}. +When @option{-fpreprocessed} is in use, GCC recognizes this @code{#pragma} +and loads the PCH@. + +This option is off by default, because the resulting preprocessed output +is only really suitable as input to GCC@. It is switched on by +@option{-save-temps}. + +You should not write this @code{#pragma} in your own code, but it is +safe to edit the filename if the PCH file is available in a different +location. The filename may be absolute or it may be relative to GCC's +current directory. + +@end ifclear +@item -x c +@itemx -x c++ +@itemx -x objective-c +@itemx -x assembler-with-cpp +@opindex x +Specify the source language: C, C++, Objective-C, or assembly. This has +nothing to do with standards conformance or extensions; it merely +selects which base syntax to expect. If you give none of these options, +cpp will deduce the language from the extension of the source file: +@samp{.c}, @samp{.cc}, @samp{.m}, or @samp{.S}. Some other common +extensions for C++ and assembly are also recognized. If cpp does not +recognize the extension, it will treat the file as C; this is the most +generic mode. + +@emph{Note:} Previous versions of cpp accepted a @option{-lang} option +which selected both the language and the standards conformance level. +This option has been removed, because it conflicts with the @option{-l} +option. + +@item -std=@var{standard} +@itemx -ansi +@opindex ansi +@opindex std= +Specify the standard to which the code should conform. Currently CPP +knows about C and C++ standards; others may be added in the future. + +@var{standard} +may be one of: +@table @code +@item c90 +@itemx c89 +@itemx iso9899:1990 +The ISO C standard from 1990. @samp{c90} is the customary shorthand for +this version of the standard. + +The @option{-ansi} option is equivalent to @option{-std=c90}. + +@item iso9899:199409 +The 1990 C standard, as amended in 1994. + +@item iso9899:1999 +@itemx c99 +@itemx iso9899:199x +@itemx c9x +The revised ISO C standard, published in December 1999. Before +publication, this was known as C9X@. + +@item c1x +The next version of the ISO C standard, still under development. + +@item gnu90 +@itemx gnu89 +The 1990 C standard plus GNU extensions. This is the default. + +@item gnu99 +@itemx gnu9x +The 1999 C standard plus GNU extensions. + +@item gnu1x +The next version of the ISO C standard, still under development, plus +GNU extensions. + +@item c++98 +The 1998 ISO C++ standard plus amendments. + +@item gnu++98 +The same as @option{-std=c++98} plus GNU extensions. This is the +default for C++ code. +@end table + +@item -I- +@opindex I- +Split the include path. Any directories specified with @option{-I} +options before @option{-I-} are searched only for headers requested with +@code{@w{#include "@var{file}"}}; they are not searched for +@code{@w{#include <@var{file}>}}. If additional directories are +specified with @option{-I} options after the @option{-I-}, those +directories are searched for all @samp{#include} directives. + +In addition, @option{-I-} inhibits the use of the directory of the current +file directory as the first search directory for @code{@w{#include +"@var{file}"}}. +@ifset cppmanual +@xref{Search Path}. +@end ifset +This option has been deprecated. + +@item -nostdinc +@opindex nostdinc +Do not search the standard system directories for header files. +Only the directories you have specified with @option{-I} options +(and the directory of the current file, if appropriate) are searched. + +@item -nostdinc++ +@opindex nostdinc++ +Do not search for header files in the C++-specific standard directories, +but do still search the other standard directories. (This option is +used when building the C++ library.) + +@item -include @var{file} +@opindex include +Process @var{file} as if @code{#include "file"} appeared as the first +line of the primary source file. However, the first directory searched +for @var{file} is the preprocessor's working directory @emph{instead of} +the directory containing the main source file. If not found there, it +is searched for in the remainder of the @code{#include "@dots{}"} search +chain as normal. + +If multiple @option{-include} options are given, the files are included +in the order they appear on the command line. + +@item -imacros @var{file} +@opindex imacros +Exactly like @option{-include}, except that any output produced by +scanning @var{file} is thrown away. Macros it defines remain defined. +This allows you to acquire all the macros from a header without also +processing its declarations. + +All files specified by @option{-imacros} are processed before all files +specified by @option{-include}. + +@item -idirafter @var{dir} +@opindex idirafter +Search @var{dir} for header files, but do it @emph{after} all +directories specified with @option{-I} and the standard system directories +have been exhausted. @var{dir} is treated as a system include directory. +If @var{dir} begins with @code{=}, then the @code{=} will be replaced +by the sysroot prefix; see @option{--sysroot} and @option{-isysroot}. + +@item -iprefix @var{prefix} +@opindex iprefix +Specify @var{prefix} as the prefix for subsequent @option{-iwithprefix} +options. If the prefix represents a directory, you should include the +final @samp{/}. + +@item -iwithprefix @var{dir} +@itemx -iwithprefixbefore @var{dir} +@opindex iwithprefix +@opindex iwithprefixbefore +Append @var{dir} to the prefix specified previously with +@option{-iprefix}, and add the resulting directory to the include search +path. @option{-iwithprefixbefore} puts it in the same place @option{-I} +would; @option{-iwithprefix} puts it where @option{-idirafter} would. + +@item -isysroot @var{dir} +@opindex isysroot +This option is like the @option{--sysroot} option, but applies only to +header files (except for Darwin targets, where it applies to both header +files and libraries). See the @option{--sysroot} option for more +information. + +@item -imultilib @var{dir} +@opindex imultilib +Use @var{dir} as a subdirectory of the directory containing +target-specific C++ headers. + +@item -isystem @var{dir} +@opindex isystem +Search @var{dir} for header files, after all directories specified by +@option{-I} but before the standard system directories. Mark it +as a system directory, so that it gets the same special treatment as +is applied to the standard system directories. +@ifset cppmanual +@xref{System Headers}. +@end ifset +If @var{dir} begins with @code{=}, then the @code{=} will be replaced +by the sysroot prefix; see @option{--sysroot} and @option{-isysroot}. + +@item -iquote @var{dir} +@opindex iquote +Search @var{dir} only for header files requested with +@code{@w{#include "@var{file}"}}; they are not searched for +@code{@w{#include <@var{file}>}}, before all directories specified by +@option{-I} and before the standard system directories. +@ifset cppmanual +@xref{Search Path}. +@end ifset +If @var{dir} begins with @code{=}, then the @code{=} will be replaced +by the sysroot prefix; see @option{--sysroot} and @option{-isysroot}. + +@item -fdirectives-only +@opindex fdirectives-only +When preprocessing, handle directives, but do not expand macros. + +The option's behavior depends on the @option{-E} and @option{-fpreprocessed} +options. + +With @option{-E}, preprocessing is limited to the handling of directives +such as @code{#define}, @code{#ifdef}, and @code{#error}. Other +preprocessor operations, such as macro expansion and trigraph +conversion are not performed. In addition, the @option{-dD} option is +implicitly enabled. + +With @option{-fpreprocessed}, predefinition of command line and most +builtin macros is disabled. Macros such as @code{__LINE__}, which are +contextually dependent, are handled normally. This enables compilation of +files previously preprocessed with @code{-E -fdirectives-only}. + +With both @option{-E} and @option{-fpreprocessed}, the rules for +@option{-fpreprocessed} take precedence. This enables full preprocessing of +files previously preprocessed with @code{-E -fdirectives-only}. + +@item -fdollars-in-identifiers +@opindex fdollars-in-identifiers +@anchor{fdollars-in-identifiers} +Accept @samp{$} in identifiers. +@ifset cppmanual +@xref{Identifier characters}. +@end ifset + +@item -fextended-identifiers +@opindex fextended-identifiers +Accept universal character names in identifiers. This option is +experimental; in a future version of GCC, it will be enabled by +default for C99 and C++. + +@item -fpreprocessed +@opindex fpreprocessed +Indicate to the preprocessor that the input file has already been +preprocessed. This suppresses things like macro expansion, trigraph +conversion, escaped newline splicing, and processing of most directives. +The preprocessor still recognizes and removes comments, so that you can +pass a file preprocessed with @option{-C} to the compiler without +problems. In this mode the integrated preprocessor is little more than +a tokenizer for the front ends. + +@option{-fpreprocessed} is implicit if the input file has one of the +extensions @samp{.i}, @samp{.ii} or @samp{.mi}. These are the +extensions that GCC uses for preprocessed files created by +@option{-save-temps}. + +@item -ftabstop=@var{width} +@opindex ftabstop +Set the distance between tab stops. This helps the preprocessor report +correct column numbers in warnings or errors, even if tabs appear on the +line. If the value is less than 1 or greater than 100, the option is +ignored. The default is 8. + +@item -fexec-charset=@var{charset} +@opindex fexec-charset +@cindex character set, execution +Set the execution character set, used for string and character +constants. The default is UTF-8. @var{charset} can be any encoding +supported by the system's @code{iconv} library routine. + +@item -fwide-exec-charset=@var{charset} +@opindex fwide-exec-charset +@cindex character set, wide execution +Set the wide execution character set, used for wide string and +character constants. The default is UTF-32 or UTF-16, whichever +corresponds to the width of @code{wchar_t}. As with +@option{-fexec-charset}, @var{charset} can be any encoding supported +by the system's @code{iconv} library routine; however, you will have +problems with encodings that do not fit exactly in @code{wchar_t}. + +@item -finput-charset=@var{charset} +@opindex finput-charset +@cindex character set, input +Set the input character set, used for translation from the character +set of the input file to the source character set used by GCC@. If the +locale does not specify, or GCC cannot get this information from the +locale, the default is UTF-8. This can be overridden by either the locale +or this command line option. Currently the command line option takes +precedence if there's a conflict. @var{charset} can be any encoding +supported by the system's @code{iconv} library routine. + +@item -fworking-directory +@opindex fworking-directory +@opindex fno-working-directory +Enable generation of linemarkers in the preprocessor output that will +let the compiler know the current working directory at the time of +preprocessing. When this option is enabled, the preprocessor will +emit, after the initial linemarker, a second linemarker with the +current working directory followed by two slashes. GCC will use this +directory, when it's present in the preprocessed input, as the +directory emitted as the current working directory in some debugging +information formats. This option is implicitly enabled if debugging +information is enabled, but this can be inhibited with the negated +form @option{-fno-working-directory}. If the @option{-P} flag is +present in the command line, this option has no effect, since no +@code{#line} directives are emitted whatsoever. + +@item -fno-show-column +@opindex fno-show-column +Do not print column numbers in diagnostics. This may be necessary if +diagnostics are being scanned by a program that does not understand the +column numbers, such as @command{dejagnu}. + +@item -A @var{predicate}=@var{answer} +@opindex A +Make an assertion with the predicate @var{predicate} and answer +@var{answer}. This form is preferred to the older form @option{-A +@var{predicate}(@var{answer})}, which is still supported, because +it does not use shell special characters. +@ifset cppmanual +@xref{Obsolete Features}. +@end ifset + +@item -A -@var{predicate}=@var{answer} +Cancel an assertion with the predicate @var{predicate} and answer +@var{answer}. + +@item -dCHARS +@var{CHARS} is a sequence of one or more of the following characters, +and must not be preceded by a space. Other characters are interpreted +by the compiler proper, or reserved for future versions of GCC, and so +are silently ignored. If you specify characters whose behavior +conflicts, the result is undefined. + +@table @samp +@item M +@opindex dM +Instead of the normal output, generate a list of @samp{#define} +directives for all the macros defined during the execution of the +preprocessor, including predefined macros. This gives you a way of +finding out what is predefined in your version of the preprocessor. +Assuming you have no file @file{foo.h}, the command + +@smallexample +touch foo.h; cpp -dM foo.h +@end smallexample + +@noindent +will show all the predefined macros. + +If you use @option{-dM} without the @option{-E} option, @option{-dM} is +interpreted as a synonym for @option{-fdump-rtl-mach}. +@xref{Debugging Options, , ,gcc}. + +@item D +@opindex dD +Like @samp{M} except in two respects: it does @emph{not} include the +predefined macros, and it outputs @emph{both} the @samp{#define} +directives and the result of preprocessing. Both kinds of output go to +the standard output file. + +@item N +@opindex dN +Like @samp{D}, but emit only the macro names, not their expansions. + +@item I +@opindex dI +Output @samp{#include} directives in addition to the result of +preprocessing. + +@item U +@opindex dU +Like @samp{D} except that only macros that are expanded, or whose +definedness is tested in preprocessor directives, are output; the +output is delayed until the use or test of the macro; and +@samp{#undef} directives are also output for macros tested but +undefined at the time. +@end table + +@item -P +@opindex P +Inhibit generation of linemarkers in the output from the preprocessor. +This might be useful when running the preprocessor on something that is +not C code, and will be sent to a program which might be confused by the +linemarkers. +@ifset cppmanual +@xref{Preprocessor Output}. +@end ifset + +@item -C +@opindex C +Do not discard comments. All comments are passed through to the output +file, except for comments in processed directives, which are deleted +along with the directive. + +You should be prepared for side effects when using @option{-C}; it +causes the preprocessor to treat comments as tokens in their own right. +For example, comments appearing at the start of what would be a +directive line have the effect of turning that line into an ordinary +source line, since the first token on the line is no longer a @samp{#}. + +@item -CC +Do not discard comments, including during macro expansion. This is +like @option{-C}, except that comments contained within macros are +also passed through to the output file where the macro is expanded. + +In addition to the side-effects of the @option{-C} option, the +@option{-CC} option causes all C++-style comments inside a macro +to be converted to C-style comments. This is to prevent later use +of that macro from inadvertently commenting out the remainder of +the source line. + +The @option{-CC} option is generally used to support lint comments. + +@item -traditional-cpp +@opindex traditional-cpp +Try to imitate the behavior of old-fashioned C preprocessors, as +opposed to ISO C preprocessors. +@ifset cppmanual +@xref{Traditional Mode}. +@end ifset + +@item -trigraphs +@opindex trigraphs +Process trigraph sequences. +@ifset cppmanual +@xref{Initial processing}. +@end ifset +@ifclear cppmanual +These are three-character sequences, all starting with @samp{??}, that +are defined by ISO C to stand for single characters. For example, +@samp{??/} stands for @samp{\}, so @samp{'??/n'} is a character +constant for a newline. By default, GCC ignores trigraphs, but in +standard-conforming modes it converts them. See the @option{-std} and +@option{-ansi} options. + +The nine trigraphs and their replacements are + +@smallexample +Trigraph: ??( ??) ??< ??> ??= ??/ ??' ??! ??- +Replacement: [ ] @{ @} # \ ^ | ~ +@end smallexample +@end ifclear + +@item -remap +@opindex remap +Enable special code to work around file systems which only permit very +short file names, such as MS-DOS@. + +@item --help +@itemx --target-help +@opindex help +@opindex target-help +Print text describing all the command line options instead of +preprocessing anything. + +@item -v +@opindex v +Verbose mode. Print out GNU CPP's version number at the beginning of +execution, and report the final form of the include path. + +@item -H +@opindex H +Print the name of each header file used, in addition to other normal +activities. Each name is indented to show how deep in the +@samp{#include} stack it is. Precompiled header files are also +printed, even if they are found to be invalid; an invalid precompiled +header file is printed with @samp{...x} and a valid one with @samp{...!} . + +@item -version +@itemx --version +@opindex version +Print out GNU CPP's version number. With one dash, proceed to +preprocess as normal. With two dashes, exit immediately. +@end table diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi new file mode 100644 index 000000000..be1c32cc1 --- /dev/null +++ b/gcc/doc/extend.texi @@ -0,0 +1,14546 @@ +@c Copyright (C) 1988, 1989, 1992, 1993, 1994, 1996, 1998, 1999, 2000, 2001, +@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 +@c Free Software Foundation, Inc. + +@c This is part of the GCC manual. +@c For copying conditions, see the file gcc.texi. + +@node C Extensions +@chapter Extensions to the C Language Family +@cindex extensions, C language +@cindex C language extensions + +@opindex pedantic +GNU C provides several language features not found in ISO standard C@. +(The @option{-pedantic} option directs GCC to print a warning message if +any of these features is used.) To test for the availability of these +features in conditional compilation, check for a predefined macro +@code{__GNUC__}, which is always defined under GCC@. + +These extensions are available in C and Objective-C@. Most of them are +also available in C++. @xref{C++ Extensions,,Extensions to the +C++ Language}, for extensions that apply @emph{only} to C++. + +Some features that are in ISO C99 but not C90 or C++ are also, as +extensions, accepted by GCC in C90 mode and in C++. + +@menu +* Statement Exprs:: Putting statements and declarations inside expressions. +* Local Labels:: Labels local to a block. +* Labels as Values:: Getting pointers to labels, and computed gotos. +* Nested Functions:: As in Algol and Pascal, lexical scoping of functions. +* Constructing Calls:: Dispatching a call to another function. +* Typeof:: @code{typeof}: referring to the type of an expression. +* Conditionals:: Omitting the middle operand of a @samp{?:} expression. +* Long Long:: Double-word integers---@code{long long int}. +* __int128:: 128-bit integers---@code{__int128}. +* Complex:: Data types for complex numbers. +* Floating Types:: Additional Floating Types. +* Half-Precision:: Half-Precision Floating Point. +* Decimal Float:: Decimal Floating Types. +* Hex Floats:: Hexadecimal floating-point constants. +* Fixed-Point:: Fixed-Point Types. +* Named Address Spaces::Named address spaces. +* Zero Length:: Zero-length arrays. +* Variable Length:: Arrays whose length is computed at run time. +* Empty Structures:: Structures with no members. +* Variadic Macros:: Macros with a variable number of arguments. +* Escaped Newlines:: Slightly looser rules for escaped newlines. +* Subscripting:: Any array can be subscripted, even if not an lvalue. +* Pointer Arith:: Arithmetic on @code{void}-pointers and function pointers. +* Initializers:: Non-constant initializers. +* Compound Literals:: Compound literals give structures, unions + or arrays as values. +* Designated Inits:: Labeling elements of initializers. +* Cast to Union:: Casting to union type from any member of the union. +* Case Ranges:: `case 1 ... 9' and such. +* Mixed Declarations:: Mixing declarations and code. +* Function Attributes:: Declaring that functions have no side effects, + or that they can never return. +* Attribute Syntax:: Formal syntax for attributes. +* Function Prototypes:: Prototype declarations and old-style definitions. +* C++ Comments:: C++ comments are recognized. +* Dollar Signs:: Dollar sign is allowed in identifiers. +* Character Escapes:: @samp{\e} stands for the character @key{ESC}. +* Variable Attributes:: Specifying attributes of variables. +* Type Attributes:: Specifying attributes of types. +* Alignment:: Inquiring about the alignment of a type or variable. +* Inline:: Defining inline functions (as fast as macros). +* Volatiles:: What constitutes an access to a volatile object. +* Extended Asm:: Assembler instructions with C expressions as operands. + (With them you can define ``built-in'' functions.) +* Constraints:: Constraints for asm operands +* Asm Labels:: Specifying the assembler name to use for a C symbol. +* Explicit Reg Vars:: Defining variables residing in specified registers. +* Alternate Keywords:: @code{__const__}, @code{__asm__}, etc., for header files. +* Incomplete Enums:: @code{enum foo;}, with details to follow. +* Function Names:: Printable strings which are the name of the current + function. +* Return Address:: Getting the return or frame address of a function. +* Vector Extensions:: Using vector instructions through built-in functions. +* Offsetof:: Special syntax for implementing @code{offsetof}. +* Atomic Builtins:: Built-in functions for atomic memory access. +* Object Size Checking:: Built-in functions for limited buffer overflow + checking. +* Other Builtins:: Other built-in functions. +* Target Builtins:: Built-in functions specific to particular targets. +* Target Format Checks:: Format checks specific to particular targets. +* Pragmas:: Pragmas accepted by GCC. +* Unnamed Fields:: Unnamed struct/union fields within structs/unions. +* Thread-Local:: Per-thread variables. +* Binary constants:: Binary constants using the @samp{0b} prefix. +@end menu + +@node Statement Exprs +@section Statements and Declarations in Expressions +@cindex statements inside expressions +@cindex declarations inside expressions +@cindex expressions containing statements +@cindex macros, statements in expressions + +@c the above section title wrapped and causes an underfull hbox.. i +@c changed it from "within" to "in". --mew 4feb93 +A compound statement enclosed in parentheses may appear as an expression +in GNU C@. This allows you to use loops, switches, and local variables +within an expression. + +Recall that a compound statement is a sequence of statements surrounded +by braces; in this construct, parentheses go around the braces. For +example: + +@smallexample +(@{ int y = foo (); int z; + if (y > 0) z = y; + else z = - y; + z; @}) +@end smallexample + +@noindent +is a valid (though slightly more complex than necessary) expression +for the absolute value of @code{foo ()}. + +The last thing in the compound statement should be an expression +followed by a semicolon; the value of this subexpression serves as the +value of the entire construct. (If you use some other kind of statement +last within the braces, the construct has type @code{void}, and thus +effectively no value.) + +This feature is especially useful in making macro definitions ``safe'' (so +that they evaluate each operand exactly once). For example, the +``maximum'' function is commonly defined as a macro in standard C as +follows: + +@smallexample +#define max(a,b) ((a) > (b) ? (a) : (b)) +@end smallexample + +@noindent +@cindex side effects, macro argument +But this definition computes either @var{a} or @var{b} twice, with bad +results if the operand has side effects. In GNU C, if you know the +type of the operands (here taken as @code{int}), you can define +the macro safely as follows: + +@smallexample +#define maxint(a,b) \ + (@{int _a = (a), _b = (b); _a > _b ? _a : _b; @}) +@end smallexample + +Embedded statements are not allowed in constant expressions, such as +the value of an enumeration constant, the width of a bit-field, or +the initial value of a static variable. + +If you don't know the type of the operand, you can still do this, but you +must use @code{typeof} (@pxref{Typeof}). + +In G++, the result value of a statement expression undergoes array and +function pointer decay, and is returned by value to the enclosing +expression. For instance, if @code{A} is a class, then + +@smallexample + A a; + + (@{a;@}).Foo () +@end smallexample + +@noindent +will construct a temporary @code{A} object to hold the result of the +statement expression, and that will be used to invoke @code{Foo}. +Therefore the @code{this} pointer observed by @code{Foo} will not be the +address of @code{a}. + +Any temporaries created within a statement within a statement expression +will be destroyed at the statement's end. This makes statement +expressions inside macros slightly different from function calls. In +the latter case temporaries introduced during argument evaluation will +be destroyed at the end of the statement that includes the function +call. In the statement expression case they will be destroyed during +the statement expression. For instance, + +@smallexample +#define macro(a) (@{__typeof__(a) b = (a); b + 3; @}) +template T function(T a) @{ T b = a; return b + 3; @} + +void foo () +@{ + macro (X ()); + function (X ()); +@} +@end smallexample + +@noindent +will have different places where temporaries are destroyed. For the +@code{macro} case, the temporary @code{X} will be destroyed just after +the initialization of @code{b}. In the @code{function} case that +temporary will be destroyed when the function returns. + +These considerations mean that it is probably a bad idea to use +statement-expressions of this form in header files that are designed to +work with C++. (Note that some versions of the GNU C Library contained +header files using statement-expression that lead to precisely this +bug.) + +Jumping into a statement expression with @code{goto} or using a +@code{switch} statement outside the statement expression with a +@code{case} or @code{default} label inside the statement expression is +not permitted. Jumping into a statement expression with a computed +@code{goto} (@pxref{Labels as Values}) yields undefined behavior. +Jumping out of a statement expression is permitted, but if the +statement expression is part of a larger expression then it is +unspecified which other subexpressions of that expression have been +evaluated except where the language definition requires certain +subexpressions to be evaluated before or after the statement +expression. In any case, as with a function call the evaluation of a +statement expression is not interleaved with the evaluation of other +parts of the containing expression. For example, + +@smallexample + foo (), ((@{ bar1 (); goto a; 0; @}) + bar2 ()), baz(); +@end smallexample + +@noindent +will call @code{foo} and @code{bar1} and will not call @code{baz} but +may or may not call @code{bar2}. If @code{bar2} is called, it will be +called after @code{foo} and before @code{bar1} + +@node Local Labels +@section Locally Declared Labels +@cindex local labels +@cindex macros, local labels + +GCC allows you to declare @dfn{local labels} in any nested block +scope. A local label is just like an ordinary label, but you can +only reference it (with a @code{goto} statement, or by taking its +address) within the block in which it was declared. + +A local label declaration looks like this: + +@smallexample +__label__ @var{label}; +@end smallexample + +@noindent +or + +@smallexample +__label__ @var{label1}, @var{label2}, /* @r{@dots{}} */; +@end smallexample + +Local label declarations must come at the beginning of the block, +before any ordinary declarations or statements. + +The label declaration defines the label @emph{name}, but does not define +the label itself. You must do this in the usual way, with +@code{@var{label}:}, within the statements of the statement expression. + +The local label feature is useful for complex macros. If a macro +contains nested loops, a @code{goto} can be useful for breaking out of +them. However, an ordinary label whose scope is the whole function +cannot be used: if the macro can be expanded several times in one +function, the label will be multiply defined in that function. A +local label avoids this problem. For example: + +@smallexample +#define SEARCH(value, array, target) \ +do @{ \ + __label__ found; \ + typeof (target) _SEARCH_target = (target); \ + typeof (*(array)) *_SEARCH_array = (array); \ + int i, j; \ + int value; \ + for (i = 0; i < max; i++) \ + for (j = 0; j < max; j++) \ + if (_SEARCH_array[i][j] == _SEARCH_target) \ + @{ (value) = i; goto found; @} \ + (value) = -1; \ + found:; \ +@} while (0) +@end smallexample + +This could also be written using a statement-expression: + +@smallexample +#define SEARCH(array, target) \ +(@{ \ + __label__ found; \ + typeof (target) _SEARCH_target = (target); \ + typeof (*(array)) *_SEARCH_array = (array); \ + int i, j; \ + int value; \ + for (i = 0; i < max; i++) \ + for (j = 0; j < max; j++) \ + if (_SEARCH_array[i][j] == _SEARCH_target) \ + @{ value = i; goto found; @} \ + value = -1; \ + found: \ + value; \ +@}) +@end smallexample + +Local label declarations also make the labels they declare visible to +nested functions, if there are any. @xref{Nested Functions}, for details. + +@node Labels as Values +@section Labels as Values +@cindex labels as values +@cindex computed gotos +@cindex goto with computed label +@cindex address of a label + +You can get the address of a label defined in the current function +(or a containing function) with the unary operator @samp{&&}. The +value has type @code{void *}. This value is a constant and can be used +wherever a constant of that type is valid. For example: + +@smallexample +void *ptr; +/* @r{@dots{}} */ +ptr = &&foo; +@end smallexample + +To use these values, you need to be able to jump to one. This is done +with the computed goto statement@footnote{The analogous feature in +Fortran is called an assigned goto, but that name seems inappropriate in +C, where one can do more than simply store label addresses in label +variables.}, @code{goto *@var{exp};}. For example, + +@smallexample +goto *ptr; +@end smallexample + +@noindent +Any expression of type @code{void *} is allowed. + +One way of using these constants is in initializing a static array that +will serve as a jump table: + +@smallexample +static void *array[] = @{ &&foo, &&bar, &&hack @}; +@end smallexample + +Then you can select a label with indexing, like this: + +@smallexample +goto *array[i]; +@end smallexample + +@noindent +Note that this does not check whether the subscript is in bounds---array +indexing in C never does that. + +Such an array of label values serves a purpose much like that of the +@code{switch} statement. The @code{switch} statement is cleaner, so +use that rather than an array unless the problem does not fit a +@code{switch} statement very well. + +Another use of label values is in an interpreter for threaded code. +The labels within the interpreter function can be stored in the +threaded code for super-fast dispatching. + +You may not use this mechanism to jump to code in a different function. +If you do that, totally unpredictable things will happen. The best way to +avoid this is to store the label address only in automatic variables and +never pass it as an argument. + +An alternate way to write the above example is + +@smallexample +static const int array[] = @{ &&foo - &&foo, &&bar - &&foo, + &&hack - &&foo @}; +goto *(&&foo + array[i]); +@end smallexample + +@noindent +This is more friendly to code living in shared libraries, as it reduces +the number of dynamic relocations that are needed, and by consequence, +allows the data to be read-only. + +The @code{&&foo} expressions for the same label might have different +values if the containing function is inlined or cloned. If a program +relies on them being always the same, +@code{__attribute__((__noinline__,__noclone__))} should be used to +prevent inlining and cloning. If @code{&&foo} is used in a static +variable initializer, inlining and cloning is forbidden. + +@node Nested Functions +@section Nested Functions +@cindex nested functions +@cindex downward funargs +@cindex thunks + +A @dfn{nested function} is a function defined inside another function. +(Nested functions are not supported for GNU C++.) The nested function's +name is local to the block where it is defined. For example, here we +define a nested function named @code{square}, and call it twice: + +@smallexample +@group +foo (double a, double b) +@{ + double square (double z) @{ return z * z; @} + + return square (a) + square (b); +@} +@end group +@end smallexample + +The nested function can access all the variables of the containing +function that are visible at the point of its definition. This is +called @dfn{lexical scoping}. For example, here we show a nested +function which uses an inherited variable named @code{offset}: + +@smallexample +@group +bar (int *array, int offset, int size) +@{ + int access (int *array, int index) + @{ return array[index + offset]; @} + int i; + /* @r{@dots{}} */ + for (i = 0; i < size; i++) + /* @r{@dots{}} */ access (array, i) /* @r{@dots{}} */ +@} +@end group +@end smallexample + +Nested function definitions are permitted within functions in the places +where variable definitions are allowed; that is, in any block, mixed +with the other declarations and statements in the block. + +It is possible to call the nested function from outside the scope of its +name by storing its address or passing the address to another function: + +@smallexample +hack (int *array, int size) +@{ + void store (int index, int value) + @{ array[index] = value; @} + + intermediate (store, size); +@} +@end smallexample + +Here, the function @code{intermediate} receives the address of +@code{store} as an argument. If @code{intermediate} calls @code{store}, +the arguments given to @code{store} are used to store into @code{array}. +But this technique works only so long as the containing function +(@code{hack}, in this example) does not exit. + +If you try to call the nested function through its address after the +containing function has exited, all hell will break loose. If you try +to call it after a containing scope level has exited, and if it refers +to some of the variables that are no longer in scope, you may be lucky, +but it's not wise to take the risk. If, however, the nested function +does not refer to anything that has gone out of scope, you should be +safe. + +GCC implements taking the address of a nested function using a technique +called @dfn{trampolines}. This technique was described in +@cite{Lexical Closures for C++} (Thomas M. Breuel, USENIX +C++ Conference Proceedings, October 17-21, 1988). + +A nested function can jump to a label inherited from a containing +function, provided the label was explicitly declared in the containing +function (@pxref{Local Labels}). Such a jump returns instantly to the +containing function, exiting the nested function which did the +@code{goto} and any intermediate functions as well. Here is an example: + +@smallexample +@group +bar (int *array, int offset, int size) +@{ + __label__ failure; + int access (int *array, int index) + @{ + if (index > size) + goto failure; + return array[index + offset]; + @} + int i; + /* @r{@dots{}} */ + for (i = 0; i < size; i++) + /* @r{@dots{}} */ access (array, i) /* @r{@dots{}} */ + /* @r{@dots{}} */ + return 0; + + /* @r{Control comes here from @code{access} + if it detects an error.} */ + failure: + return -1; +@} +@end group +@end smallexample + +A nested function always has no linkage. Declaring one with +@code{extern} or @code{static} is erroneous. If you need to declare the nested function +before its definition, use @code{auto} (which is otherwise meaningless +for function declarations). + +@smallexample +bar (int *array, int offset, int size) +@{ + __label__ failure; + auto int access (int *, int); + /* @r{@dots{}} */ + int access (int *array, int index) + @{ + if (index > size) + goto failure; + return array[index + offset]; + @} + /* @r{@dots{}} */ +@} +@end smallexample + +@node Constructing Calls +@section Constructing Function Calls +@cindex constructing calls +@cindex forwarding calls + +Using the built-in functions described below, you can record +the arguments a function received, and call another function +with the same arguments, without knowing the number or types +of the arguments. + +You can also record the return value of that function call, +and later return that value, without knowing what data type +the function tried to return (as long as your caller expects +that data type). + +However, these built-in functions may interact badly with some +sophisticated features or other extensions of the language. It +is, therefore, not recommended to use them outside very simple +functions acting as mere forwarders for their arguments. + +@deftypefn {Built-in Function} {void *} __builtin_apply_args () +This built-in function returns a pointer to data +describing how to perform a call with the same arguments as were passed +to the current function. + +The function saves the arg pointer register, structure value address, +and all registers that might be used to pass arguments to a function +into a block of memory allocated on the stack. Then it returns the +address of that block. +@end deftypefn + +@deftypefn {Built-in Function} {void *} __builtin_apply (void (*@var{function})(), void *@var{arguments}, size_t @var{size}) +This built-in function invokes @var{function} +with a copy of the parameters described by @var{arguments} +and @var{size}. + +The value of @var{arguments} should be the value returned by +@code{__builtin_apply_args}. The argument @var{size} specifies the size +of the stack argument data, in bytes. + +This function returns a pointer to data describing +how to return whatever value was returned by @var{function}. The data +is saved in a block of memory allocated on the stack. + +It is not always simple to compute the proper value for @var{size}. The +value is used by @code{__builtin_apply} to compute the amount of data +that should be pushed on the stack and copied from the incoming argument +area. +@end deftypefn + +@deftypefn {Built-in Function} {void} __builtin_return (void *@var{result}) +This built-in function returns the value described by @var{result} from +the containing function. You should specify, for @var{result}, a value +returned by @code{__builtin_apply}. +@end deftypefn + +@deftypefn {Built-in Function} {} __builtin_va_arg_pack () +This built-in function represents all anonymous arguments of an inline +function. It can be used only in inline functions which will be always +inlined, never compiled as a separate function, such as those using +@code{__attribute__ ((__always_inline__))} or +@code{__attribute__ ((__gnu_inline__))} extern inline functions. +It must be only passed as last argument to some other function +with variable arguments. This is useful for writing small wrapper +inlines for variable argument functions, when using preprocessor +macros is undesirable. For example: +@smallexample +extern int myprintf (FILE *f, const char *format, ...); +extern inline __attribute__ ((__gnu_inline__)) int +myprintf (FILE *f, const char *format, ...) +@{ + int r = fprintf (f, "myprintf: "); + if (r < 0) + return r; + int s = fprintf (f, format, __builtin_va_arg_pack ()); + if (s < 0) + return s; + return r + s; +@} +@end smallexample +@end deftypefn + +@deftypefn {Built-in Function} {size_t} __builtin_va_arg_pack_len () +This built-in function returns the number of anonymous arguments of +an inline function. It can be used only in inline functions which +will be always inlined, never compiled as a separate function, such +as those using @code{__attribute__ ((__always_inline__))} or +@code{__attribute__ ((__gnu_inline__))} extern inline functions. +For example following will do link or runtime checking of open +arguments for optimized code: +@smallexample +#ifdef __OPTIMIZE__ +extern inline __attribute__((__gnu_inline__)) int +myopen (const char *path, int oflag, ...) +@{ + if (__builtin_va_arg_pack_len () > 1) + warn_open_too_many_arguments (); + + if (__builtin_constant_p (oflag)) + @{ + if ((oflag & O_CREAT) != 0 && __builtin_va_arg_pack_len () < 1) + @{ + warn_open_missing_mode (); + return __open_2 (path, oflag); + @} + return open (path, oflag, __builtin_va_arg_pack ()); + @} + + if (__builtin_va_arg_pack_len () < 1) + return __open_2 (path, oflag); + + return open (path, oflag, __builtin_va_arg_pack ()); +@} +#endif +@end smallexample +@end deftypefn + +@node Typeof +@section Referring to a Type with @code{typeof} +@findex typeof +@findex sizeof +@cindex macros, types of arguments + +Another way to refer to the type of an expression is with @code{typeof}. +The syntax of using of this keyword looks like @code{sizeof}, but the +construct acts semantically like a type name defined with @code{typedef}. + +There are two ways of writing the argument to @code{typeof}: with an +expression or with a type. Here is an example with an expression: + +@smallexample +typeof (x[0](1)) +@end smallexample + +@noindent +This assumes that @code{x} is an array of pointers to functions; +the type described is that of the values of the functions. + +Here is an example with a typename as the argument: + +@smallexample +typeof (int *) +@end smallexample + +@noindent +Here the type described is that of pointers to @code{int}. + +If you are writing a header file that must work when included in ISO C +programs, write @code{__typeof__} instead of @code{typeof}. +@xref{Alternate Keywords}. + +A @code{typeof}-construct can be used anywhere a typedef name could be +used. For example, you can use it in a declaration, in a cast, or inside +of @code{sizeof} or @code{typeof}. + +The operand of @code{typeof} is evaluated for its side effects if and +only if it is an expression of variably modified type or the name of +such a type. + +@code{typeof} is often useful in conjunction with the +statements-within-expressions feature. Here is how the two together can +be used to define a safe ``maximum'' macro that operates on any +arithmetic type and evaluates each of its arguments exactly once: + +@smallexample +#define max(a,b) \ + (@{ typeof (a) _a = (a); \ + typeof (b) _b = (b); \ + _a > _b ? _a : _b; @}) +@end smallexample + +@cindex underscores in variables in macros +@cindex @samp{_} in variables in macros +@cindex local variables in macros +@cindex variables, local, in macros +@cindex macros, local variables in + +The reason for using names that start with underscores for the local +variables is to avoid conflicts with variable names that occur within the +expressions that are substituted for @code{a} and @code{b}. Eventually we +hope to design a new form of declaration syntax that allows you to declare +variables whose scopes start only after their initializers; this will be a +more reliable way to prevent such conflicts. + +@noindent +Some more examples of the use of @code{typeof}: + +@itemize @bullet +@item +This declares @code{y} with the type of what @code{x} points to. + +@smallexample +typeof (*x) y; +@end smallexample + +@item +This declares @code{y} as an array of such values. + +@smallexample +typeof (*x) y[4]; +@end smallexample + +@item +This declares @code{y} as an array of pointers to characters: + +@smallexample +typeof (typeof (char *)[4]) y; +@end smallexample + +@noindent +It is equivalent to the following traditional C declaration: + +@smallexample +char *y[4]; +@end smallexample + +To see the meaning of the declaration using @code{typeof}, and why it +might be a useful way to write, rewrite it with these macros: + +@smallexample +#define pointer(T) typeof(T *) +#define array(T, N) typeof(T [N]) +@end smallexample + +@noindent +Now the declaration can be rewritten this way: + +@smallexample +array (pointer (char), 4) y; +@end smallexample + +@noindent +Thus, @code{array (pointer (char), 4)} is the type of arrays of 4 +pointers to @code{char}. +@end itemize + +@emph{Compatibility Note:} In addition to @code{typeof}, GCC 2 supported +a more limited extension which permitted one to write + +@smallexample +typedef @var{T} = @var{expr}; +@end smallexample + +@noindent +with the effect of declaring @var{T} to have the type of the expression +@var{expr}. This extension does not work with GCC 3 (versions between +3.0 and 3.2 will crash; 3.2.1 and later give an error). Code which +relies on it should be rewritten to use @code{typeof}: + +@smallexample +typedef typeof(@var{expr}) @var{T}; +@end smallexample + +@noindent +This will work with all versions of GCC@. + +@node Conditionals +@section Conditionals with Omitted Operands +@cindex conditional expressions, extensions +@cindex omitted middle-operands +@cindex middle-operands, omitted +@cindex extensions, @code{?:} +@cindex @code{?:} extensions + +The middle operand in a conditional expression may be omitted. Then +if the first operand is nonzero, its value is the value of the conditional +expression. + +Therefore, the expression + +@smallexample +x ? : y +@end smallexample + +@noindent +has the value of @code{x} if that is nonzero; otherwise, the value of +@code{y}. + +This example is perfectly equivalent to + +@smallexample +x ? x : y +@end smallexample + +@cindex side effect in @code{?:} +@cindex @code{?:} side effect +@noindent +In this simple case, the ability to omit the middle operand is not +especially useful. When it becomes useful is when the first operand does, +or may (if it is a macro argument), contain a side effect. Then repeating +the operand in the middle would perform the side effect twice. Omitting +the middle operand uses the value already computed without the undesirable +effects of recomputing it. + +@node __int128 +@section 128-bits integers +@cindex @code{__int128} data types + +As an extension the integer scalar type @code{__int128} is supported for +targets having an integer mode wide enough to hold 128-bit. +Simply write @code{__int128} for a signed 128-bit integer, or +@code{unsigned __int128} for an unsigned 128-bit integer. There is no +support in GCC to express an integer constant of type @code{__int128} +for targets having @code{long long} integer with less then 128 bit width. + +@node Long Long +@section Double-Word Integers +@cindex @code{long long} data types +@cindex double-word arithmetic +@cindex multiprecision arithmetic +@cindex @code{LL} integer suffix +@cindex @code{ULL} integer suffix + +ISO C99 supports data types for integers that are at least 64 bits wide, +and as an extension GCC supports them in C90 mode and in C++. +Simply write @code{long long int} for a signed integer, or +@code{unsigned long long int} for an unsigned integer. To make an +integer constant of type @code{long long int}, add the suffix @samp{LL} +to the integer. To make an integer constant of type @code{unsigned long +long int}, add the suffix @samp{ULL} to the integer. + +You can use these types in arithmetic like any other integer types. +Addition, subtraction, and bitwise boolean operations on these types +are open-coded on all types of machines. Multiplication is open-coded +if the machine supports fullword-to-doubleword a widening multiply +instruction. Division and shifts are open-coded only on machines that +provide special support. The operations that are not open-coded use +special library routines that come with GCC@. + +There may be pitfalls when you use @code{long long} types for function +arguments, unless you declare function prototypes. If a function +expects type @code{int} for its argument, and you pass a value of type +@code{long long int}, confusion will result because the caller and the +subroutine will disagree about the number of bytes for the argument. +Likewise, if the function expects @code{long long int} and you pass +@code{int}. The best way to avoid such problems is to use prototypes. + +@node Complex +@section Complex Numbers +@cindex complex numbers +@cindex @code{_Complex} keyword +@cindex @code{__complex__} keyword + +ISO C99 supports complex floating data types, and as an extension GCC +supports them in C90 mode and in C++, and supports complex integer data +types which are not part of ISO C99. You can declare complex types +using the keyword @code{_Complex}. As an extension, the older GNU +keyword @code{__complex__} is also supported. + +For example, @samp{_Complex double x;} declares @code{x} as a +variable whose real part and imaginary part are both of type +@code{double}. @samp{_Complex short int y;} declares @code{y} to +have real and imaginary parts of type @code{short int}; this is not +likely to be useful, but it shows that the set of complex types is +complete. + +To write a constant with a complex data type, use the suffix @samp{i} or +@samp{j} (either one; they are equivalent). For example, @code{2.5fi} +has type @code{_Complex float} and @code{3i} has type +@code{_Complex int}. Such a constant always has a pure imaginary +value, but you can form any complex value you like by adding one to a +real constant. This is a GNU extension; if you have an ISO C99 +conforming C library (such as GNU libc), and want to construct complex +constants of floating type, you should include @code{} and +use the macros @code{I} or @code{_Complex_I} instead. + +@cindex @code{__real__} keyword +@cindex @code{__imag__} keyword +To extract the real part of a complex-valued expression @var{exp}, write +@code{__real__ @var{exp}}. Likewise, use @code{__imag__} to +extract the imaginary part. This is a GNU extension; for values of +floating type, you should use the ISO C99 functions @code{crealf}, +@code{creal}, @code{creall}, @code{cimagf}, @code{cimag} and +@code{cimagl}, declared in @code{} and also provided as +built-in functions by GCC@. + +@cindex complex conjugation +The operator @samp{~} performs complex conjugation when used on a value +with a complex type. This is a GNU extension; for values of +floating type, you should use the ISO C99 functions @code{conjf}, +@code{conj} and @code{conjl}, declared in @code{} and also +provided as built-in functions by GCC@. + +GCC can allocate complex automatic variables in a noncontiguous +fashion; it's even possible for the real part to be in a register while +the imaginary part is on the stack (or vice-versa). Only the DWARF2 +debug info format can represent this, so use of DWARF2 is recommended. +If you are using the stabs debug info format, GCC describes a noncontiguous +complex variable as if it were two separate variables of noncomplex type. +If the variable's actual name is @code{foo}, the two fictitious +variables are named @code{foo$real} and @code{foo$imag}. You can +examine and set these two fictitious variables with your debugger. + +@node Floating Types +@section Additional Floating Types +@cindex additional floating types +@cindex @code{__float80} data type +@cindex @code{__float128} data type +@cindex @code{w} floating point suffix +@cindex @code{q} floating point suffix +@cindex @code{W} floating point suffix +@cindex @code{Q} floating point suffix + +As an extension, the GNU C compiler supports additional floating +types, @code{__float80} and @code{__float128} to support 80bit +(@code{XFmode}) and 128 bit (@code{TFmode}) floating types. +Support for additional types includes the arithmetic operators: +add, subtract, multiply, divide; unary arithmetic operators; +relational operators; equality operators; and conversions to and from +integer and other floating types. Use a suffix @samp{w} or @samp{W} +in a literal constant of type @code{__float80} and @samp{q} or @samp{Q} +for @code{_float128}. You can declare complex types using the +corresponding internal complex type, @code{XCmode} for @code{__float80} +type and @code{TCmode} for @code{__float128} type: + +@smallexample +typedef _Complex float __attribute__((mode(TC))) _Complex128; +typedef _Complex float __attribute__((mode(XC))) _Complex80; +@end smallexample + +Not all targets support additional floating point types. @code{__float80} +and @code{__float128} types are supported on i386, x86_64 and ia64 targets. +The @code{__float128} type is supported on hppa HP-UX targets. + +@node Half-Precision +@section Half-Precision Floating Point +@cindex half-precision floating point +@cindex @code{__fp16} data type + +On ARM targets, GCC supports half-precision (16-bit) floating point via +the @code{__fp16} type. You must enable this type explicitly +with the @option{-mfp16-format} command-line option in order to use it. + +ARM supports two incompatible representations for half-precision +floating-point values. You must choose one of the representations and +use it consistently in your program. + +Specifying @option{-mfp16-format=ieee} selects the IEEE 754-2008 format. +This format can represent normalized values in the range of @math{2^{-14}} to 65504. +There are 11 bits of significand precision, approximately 3 +decimal digits. + +Specifying @option{-mfp16-format=alternative} selects the ARM +alternative format. This representation is similar to the IEEE +format, but does not support infinities or NaNs. Instead, the range +of exponents is extended, so that this format can represent normalized +values in the range of @math{2^{-14}} to 131008. + +The @code{__fp16} type is a storage format only. For purposes +of arithmetic and other operations, @code{__fp16} values in C or C++ +expressions are automatically promoted to @code{float}. In addition, +you cannot declare a function with a return value or parameters +of type @code{__fp16}. + +Note that conversions from @code{double} to @code{__fp16} +involve an intermediate conversion to @code{float}. Because +of rounding, this can sometimes produce a different result than a +direct conversion. + +ARM provides hardware support for conversions between +@code{__fp16} and @code{float} values +as an extension to VFP and NEON (Advanced SIMD). GCC generates +code using these hardware instructions if you compile with +options to select an FPU that provides them; +for example, @option{-mfpu=neon-fp16 -mfloat-abi=softfp}, +in addition to the @option{-mfp16-format} option to select +a half-precision format. + +Language-level support for the @code{__fp16} data type is +independent of whether GCC generates code using hardware floating-point +instructions. In cases where hardware support is not specified, GCC +implements conversions between @code{__fp16} and @code{float} values +as library calls. + +@node Decimal Float +@section Decimal Floating Types +@cindex decimal floating types +@cindex @code{_Decimal32} data type +@cindex @code{_Decimal64} data type +@cindex @code{_Decimal128} data type +@cindex @code{df} integer suffix +@cindex @code{dd} integer suffix +@cindex @code{dl} integer suffix +@cindex @code{DF} integer suffix +@cindex @code{DD} integer suffix +@cindex @code{DL} integer suffix + +As an extension, the GNU C compiler supports decimal floating types as +defined in the N1312 draft of ISO/IEC WDTR24732. Support for decimal +floating types in GCC will evolve as the draft technical report changes. +Calling conventions for any target might also change. Not all targets +support decimal floating types. + +The decimal floating types are @code{_Decimal32}, @code{_Decimal64}, and +@code{_Decimal128}. They use a radix of ten, unlike the floating types +@code{float}, @code{double}, and @code{long double} whose radix is not +specified by the C standard but is usually two. + +Support for decimal floating types includes the arithmetic operators +add, subtract, multiply, divide; unary arithmetic operators; +relational operators; equality operators; and conversions to and from +integer and other floating types. Use a suffix @samp{df} or +@samp{DF} in a literal constant of type @code{_Decimal32}, @samp{dd} +or @samp{DD} for @code{_Decimal64}, and @samp{dl} or @samp{DL} for +@code{_Decimal128}. + +GCC support of decimal float as specified by the draft technical report +is incomplete: + +@itemize @bullet +@item +When the value of a decimal floating type cannot be represented in the +integer type to which it is being converted, the result is undefined +rather than the result value specified by the draft technical report. + +@item +GCC does not provide the C library functionality associated with +@file{math.h}, @file{fenv.h}, @file{stdio.h}, @file{stdlib.h}, and +@file{wchar.h}, which must come from a separate C library implementation. +Because of this the GNU C compiler does not define macro +@code{__STDC_DEC_FP__} to indicate that the implementation conforms to +the technical report. +@end itemize + +Types @code{_Decimal32}, @code{_Decimal64}, and @code{_Decimal128} +are supported by the DWARF2 debug information format. + +@node Hex Floats +@section Hex Floats +@cindex hex floats + +ISO C99 supports floating-point numbers written not only in the usual +decimal notation, such as @code{1.55e1}, but also numbers such as +@code{0x1.fp3} written in hexadecimal format. As a GNU extension, GCC +supports this in C90 mode (except in some cases when strictly +conforming) and in C++. In that format the +@samp{0x} hex introducer and the @samp{p} or @samp{P} exponent field are +mandatory. The exponent is a decimal number that indicates the power of +2 by which the significant part will be multiplied. Thus @samp{0x1.f} is +@tex +$1 {15\over16}$, +@end tex +@ifnottex +1 15/16, +@end ifnottex +@samp{p3} multiplies it by 8, and the value of @code{0x1.fp3} +is the same as @code{1.55e1}. + +Unlike for floating-point numbers in the decimal notation the exponent +is always required in the hexadecimal notation. Otherwise the compiler +would not be able to resolve the ambiguity of, e.g., @code{0x1.f}. This +could mean @code{1.0f} or @code{1.9375} since @samp{f} is also the +extension for floating-point constants of type @code{float}. + +@node Fixed-Point +@section Fixed-Point Types +@cindex fixed-point types +@cindex @code{_Fract} data type +@cindex @code{_Accum} data type +@cindex @code{_Sat} data type +@cindex @code{hr} fixed-suffix +@cindex @code{r} fixed-suffix +@cindex @code{lr} fixed-suffix +@cindex @code{llr} fixed-suffix +@cindex @code{uhr} fixed-suffix +@cindex @code{ur} fixed-suffix +@cindex @code{ulr} fixed-suffix +@cindex @code{ullr} fixed-suffix +@cindex @code{hk} fixed-suffix +@cindex @code{k} fixed-suffix +@cindex @code{lk} fixed-suffix +@cindex @code{llk} fixed-suffix +@cindex @code{uhk} fixed-suffix +@cindex @code{uk} fixed-suffix +@cindex @code{ulk} fixed-suffix +@cindex @code{ullk} fixed-suffix +@cindex @code{HR} fixed-suffix +@cindex @code{R} fixed-suffix +@cindex @code{LR} fixed-suffix +@cindex @code{LLR} fixed-suffix +@cindex @code{UHR} fixed-suffix +@cindex @code{UR} fixed-suffix +@cindex @code{ULR} fixed-suffix +@cindex @code{ULLR} fixed-suffix +@cindex @code{HK} fixed-suffix +@cindex @code{K} fixed-suffix +@cindex @code{LK} fixed-suffix +@cindex @code{LLK} fixed-suffix +@cindex @code{UHK} fixed-suffix +@cindex @code{UK} fixed-suffix +@cindex @code{ULK} fixed-suffix +@cindex @code{ULLK} fixed-suffix + +As an extension, the GNU C compiler supports fixed-point types as +defined in the N1169 draft of ISO/IEC DTR 18037. Support for fixed-point +types in GCC will evolve as the draft technical report changes. +Calling conventions for any target might also change. Not all targets +support fixed-point types. + +The fixed-point types are +@code{short _Fract}, +@code{_Fract}, +@code{long _Fract}, +@code{long long _Fract}, +@code{unsigned short _Fract}, +@code{unsigned _Fract}, +@code{unsigned long _Fract}, +@code{unsigned long long _Fract}, +@code{_Sat short _Fract}, +@code{_Sat _Fract}, +@code{_Sat long _Fract}, +@code{_Sat long long _Fract}, +@code{_Sat unsigned short _Fract}, +@code{_Sat unsigned _Fract}, +@code{_Sat unsigned long _Fract}, +@code{_Sat unsigned long long _Fract}, +@code{short _Accum}, +@code{_Accum}, +@code{long _Accum}, +@code{long long _Accum}, +@code{unsigned short _Accum}, +@code{unsigned _Accum}, +@code{unsigned long _Accum}, +@code{unsigned long long _Accum}, +@code{_Sat short _Accum}, +@code{_Sat _Accum}, +@code{_Sat long _Accum}, +@code{_Sat long long _Accum}, +@code{_Sat unsigned short _Accum}, +@code{_Sat unsigned _Accum}, +@code{_Sat unsigned long _Accum}, +@code{_Sat unsigned long long _Accum}. + +Fixed-point data values contain fractional and optional integral parts. +The format of fixed-point data varies and depends on the target machine. + +Support for fixed-point types includes: +@itemize @bullet +@item +prefix and postfix increment and decrement operators (@code{++}, @code{--}) +@item +unary arithmetic operators (@code{+}, @code{-}, @code{!}) +@item +binary arithmetic operators (@code{+}, @code{-}, @code{*}, @code{/}) +@item +binary shift operators (@code{<<}, @code{>>}) +@item +relational operators (@code{<}, @code{<=}, @code{>=}, @code{>}) +@item +equality operators (@code{==}, @code{!=}) +@item +assignment operators (@code{+=}, @code{-=}, @code{*=}, @code{/=}, +@code{<<=}, @code{>>=}) +@item +conversions to and from integer, floating-point, or fixed-point types +@end itemize + +Use a suffix in a fixed-point literal constant: +@itemize +@item @samp{hr} or @samp{HR} for @code{short _Fract} and +@code{_Sat short _Fract} +@item @samp{r} or @samp{R} for @code{_Fract} and @code{_Sat _Fract} +@item @samp{lr} or @samp{LR} for @code{long _Fract} and +@code{_Sat long _Fract} +@item @samp{llr} or @samp{LLR} for @code{long long _Fract} and +@code{_Sat long long _Fract} +@item @samp{uhr} or @samp{UHR} for @code{unsigned short _Fract} and +@code{_Sat unsigned short _Fract} +@item @samp{ur} or @samp{UR} for @code{unsigned _Fract} and +@code{_Sat unsigned _Fract} +@item @samp{ulr} or @samp{ULR} for @code{unsigned long _Fract} and +@code{_Sat unsigned long _Fract} +@item @samp{ullr} or @samp{ULLR} for @code{unsigned long long _Fract} +and @code{_Sat unsigned long long _Fract} +@item @samp{hk} or @samp{HK} for @code{short _Accum} and +@code{_Sat short _Accum} +@item @samp{k} or @samp{K} for @code{_Accum} and @code{_Sat _Accum} +@item @samp{lk} or @samp{LK} for @code{long _Accum} and +@code{_Sat long _Accum} +@item @samp{llk} or @samp{LLK} for @code{long long _Accum} and +@code{_Sat long long _Accum} +@item @samp{uhk} or @samp{UHK} for @code{unsigned short _Accum} and +@code{_Sat unsigned short _Accum} +@item @samp{uk} or @samp{UK} for @code{unsigned _Accum} and +@code{_Sat unsigned _Accum} +@item @samp{ulk} or @samp{ULK} for @code{unsigned long _Accum} and +@code{_Sat unsigned long _Accum} +@item @samp{ullk} or @samp{ULLK} for @code{unsigned long long _Accum} +and @code{_Sat unsigned long long _Accum} +@end itemize + +GCC support of fixed-point types as specified by the draft technical report +is incomplete: + +@itemize @bullet +@item +Pragmas to control overflow and rounding behaviors are not implemented. +@end itemize + +Fixed-point types are supported by the DWARF2 debug information format. + +@node Named Address Spaces +@section Named address spaces +@cindex named address spaces + +As an extension, the GNU C compiler supports named address spaces as +defined in the N1275 draft of ISO/IEC DTR 18037. Support for named +address spaces in GCC will evolve as the draft technical report changes. +Calling conventions for any target might also change. At present, only +the SPU and M32C targets support other address spaces. On the SPU target, for +example, variables may be declared as belonging to another address space +by qualifying the type with the @code{__ea} address space identifier: + +@smallexample +extern int __ea i; +@end smallexample + +When the variable @code{i} is accessed, the compiler will generate +special code to access this variable. It may use runtime library +support, or generate special machine instructions to access that address +space. + +The @code{__ea} identifier may be used exactly like any other C type +qualifier (e.g., @code{const} or @code{volatile}). See the N1275 +document for more details. + +On the M32C target, with the R8C and M16C cpu variants, variables +qualified with @code{__far} are accessed using 32-bit addresses in +order to access memory beyond the first 64k bytes. If @code{__far} is +used with the M32CM or M32C cpu variants, it has no effect. + +@node Zero Length +@section Arrays of Length Zero +@cindex arrays of length zero +@cindex zero-length arrays +@cindex length-zero arrays +@cindex flexible array members + +Zero-length arrays are allowed in GNU C@. They are very useful as the +last element of a structure which is really a header for a variable-length +object: + +@smallexample +struct line @{ + int length; + char contents[0]; +@}; + +struct line *thisline = (struct line *) + malloc (sizeof (struct line) + this_length); +thisline->length = this_length; +@end smallexample + +In ISO C90, you would have to give @code{contents} a length of 1, which +means either you waste space or complicate the argument to @code{malloc}. + +In ISO C99, you would use a @dfn{flexible array member}, which is +slightly different in syntax and semantics: + +@itemize @bullet +@item +Flexible array members are written as @code{contents[]} without +the @code{0}. + +@item +Flexible array members have incomplete type, and so the @code{sizeof} +operator may not be applied. As a quirk of the original implementation +of zero-length arrays, @code{sizeof} evaluates to zero. + +@item +Flexible array members may only appear as the last member of a +@code{struct} that is otherwise non-empty. + +@item +A structure containing a flexible array member, or a union containing +such a structure (possibly recursively), may not be a member of a +structure or an element of an array. (However, these uses are +permitted by GCC as extensions.) +@end itemize + +GCC versions before 3.0 allowed zero-length arrays to be statically +initialized, as if they were flexible arrays. In addition to those +cases that were useful, it also allowed initializations in situations +that would corrupt later data. Non-empty initialization of zero-length +arrays is now treated like any case where there are more initializer +elements than the array holds, in that a suitable warning about "excess +elements in array" is given, and the excess elements (all of them, in +this case) are ignored. + +Instead GCC allows static initialization of flexible array members. +This is equivalent to defining a new structure containing the original +structure followed by an array of sufficient size to contain the data. +I.e.@: in the following, @code{f1} is constructed as if it were declared +like @code{f2}. + +@smallexample +struct f1 @{ + int x; int y[]; +@} f1 = @{ 1, @{ 2, 3, 4 @} @}; + +struct f2 @{ + struct f1 f1; int data[3]; +@} f2 = @{ @{ 1 @}, @{ 2, 3, 4 @} @}; +@end smallexample + +@noindent +The convenience of this extension is that @code{f1} has the desired +type, eliminating the need to consistently refer to @code{f2.f1}. + +This has symmetry with normal static arrays, in that an array of +unknown size is also written with @code{[]}. + +Of course, this extension only makes sense if the extra data comes at +the end of a top-level object, as otherwise we would be overwriting +data at subsequent offsets. To avoid undue complication and confusion +with initialization of deeply nested arrays, we simply disallow any +non-empty initialization except when the structure is the top-level +object. For example: + +@smallexample +struct foo @{ int x; int y[]; @}; +struct bar @{ struct foo z; @}; + +struct foo a = @{ 1, @{ 2, 3, 4 @} @}; // @r{Valid.} +struct bar b = @{ @{ 1, @{ 2, 3, 4 @} @} @}; // @r{Invalid.} +struct bar c = @{ @{ 1, @{ @} @} @}; // @r{Valid.} +struct foo d[1] = @{ @{ 1 @{ 2, 3, 4 @} @} @}; // @r{Invalid.} +@end smallexample + +@node Empty Structures +@section Structures With No Members +@cindex empty structures +@cindex zero-size structures + +GCC permits a C structure to have no members: + +@smallexample +struct empty @{ +@}; +@end smallexample + +The structure will have size zero. In C++, empty structures are part +of the language. G++ treats empty structures as if they had a single +member of type @code{char}. + +@node Variable Length +@section Arrays of Variable Length +@cindex variable-length arrays +@cindex arrays of variable length +@cindex VLAs + +Variable-length automatic arrays are allowed in ISO C99, and as an +extension GCC accepts them in C90 mode and in C++. These arrays are +declared like any other automatic arrays, but with a length that is not +a constant expression. The storage is allocated at the point of +declaration and deallocated when the brace-level is exited. For +example: + +@smallexample +FILE * +concat_fopen (char *s1, char *s2, char *mode) +@{ + char str[strlen (s1) + strlen (s2) + 1]; + strcpy (str, s1); + strcat (str, s2); + return fopen (str, mode); +@} +@end smallexample + +@cindex scope of a variable length array +@cindex variable-length array scope +@cindex deallocating variable length arrays +Jumping or breaking out of the scope of the array name deallocates the +storage. Jumping into the scope is not allowed; you get an error +message for it. + +@cindex @code{alloca} vs variable-length arrays +You can use the function @code{alloca} to get an effect much like +variable-length arrays. The function @code{alloca} is available in +many other C implementations (but not in all). On the other hand, +variable-length arrays are more elegant. + +There are other differences between these two methods. Space allocated +with @code{alloca} exists until the containing @emph{function} returns. +The space for a variable-length array is deallocated as soon as the array +name's scope ends. (If you use both variable-length arrays and +@code{alloca} in the same function, deallocation of a variable-length array +will also deallocate anything more recently allocated with @code{alloca}.) + +You can also use variable-length arrays as arguments to functions: + +@smallexample +struct entry +tester (int len, char data[len][len]) +@{ + /* @r{@dots{}} */ +@} +@end smallexample + +The length of an array is computed once when the storage is allocated +and is remembered for the scope of the array in case you access it with +@code{sizeof}. + +If you want to pass the array first and the length afterward, you can +use a forward declaration in the parameter list---another GNU extension. + +@smallexample +struct entry +tester (int len; char data[len][len], int len) +@{ + /* @r{@dots{}} */ +@} +@end smallexample + +@cindex parameter forward declaration +The @samp{int len} before the semicolon is a @dfn{parameter forward +declaration}, and it serves the purpose of making the name @code{len} +known when the declaration of @code{data} is parsed. + +You can write any number of such parameter forward declarations in the +parameter list. They can be separated by commas or semicolons, but the +last one must end with a semicolon, which is followed by the ``real'' +parameter declarations. Each forward declaration must match a ``real'' +declaration in parameter name and data type. ISO C99 does not support +parameter forward declarations. + +@node Variadic Macros +@section Macros with a Variable Number of Arguments. +@cindex variable number of arguments +@cindex macro with variable arguments +@cindex rest argument (in macro) +@cindex variadic macros + +In the ISO C standard of 1999, a macro can be declared to accept a +variable number of arguments much as a function can. The syntax for +defining the macro is similar to that of a function. Here is an +example: + +@smallexample +#define debug(format, ...) fprintf (stderr, format, __VA_ARGS__) +@end smallexample + +Here @samp{@dots{}} is a @dfn{variable argument}. In the invocation of +such a macro, it represents the zero or more tokens until the closing +parenthesis that ends the invocation, including any commas. This set of +tokens replaces the identifier @code{__VA_ARGS__} in the macro body +wherever it appears. See the CPP manual for more information. + +GCC has long supported variadic macros, and used a different syntax that +allowed you to give a name to the variable arguments just like any other +argument. Here is an example: + +@smallexample +#define debug(format, args...) fprintf (stderr, format, args) +@end smallexample + +This is in all ways equivalent to the ISO C example above, but arguably +more readable and descriptive. + +GNU CPP has two further variadic macro extensions, and permits them to +be used with either of the above forms of macro definition. + +In standard C, you are not allowed to leave the variable argument out +entirely; but you are allowed to pass an empty argument. For example, +this invocation is invalid in ISO C, because there is no comma after +the string: + +@smallexample +debug ("A message") +@end smallexample + +GNU CPP permits you to completely omit the variable arguments in this +way. In the above examples, the compiler would complain, though since +the expansion of the macro still has the extra comma after the format +string. + +To help solve this problem, CPP behaves specially for variable arguments +used with the token paste operator, @samp{##}. If instead you write + +@smallexample +#define debug(format, ...) fprintf (stderr, format, ## __VA_ARGS__) +@end smallexample + +and if the variable arguments are omitted or empty, the @samp{##} +operator causes the preprocessor to remove the comma before it. If you +do provide some variable arguments in your macro invocation, GNU CPP +does not complain about the paste operation and instead places the +variable arguments after the comma. Just like any other pasted macro +argument, these arguments are not macro expanded. + +@node Escaped Newlines +@section Slightly Looser Rules for Escaped Newlines +@cindex escaped newlines +@cindex newlines (escaped) + +Recently, the preprocessor has relaxed its treatment of escaped +newlines. Previously, the newline had to immediately follow a +backslash. The current implementation allows whitespace in the form +of spaces, horizontal and vertical tabs, and form feeds between the +backslash and the subsequent newline. The preprocessor issues a +warning, but treats it as a valid escaped newline and combines the two +lines to form a single logical line. This works within comments and +tokens, as well as between tokens. Comments are @emph{not} treated as +whitespace for the purposes of this relaxation, since they have not +yet been replaced with spaces. + +@node Subscripting +@section Non-Lvalue Arrays May Have Subscripts +@cindex subscripting +@cindex arrays, non-lvalue + +@cindex subscripting and function values +In ISO C99, arrays that are not lvalues still decay to pointers, and +may be subscripted, although they may not be modified or used after +the next sequence point and the unary @samp{&} operator may not be +applied to them. As an extension, GCC allows such arrays to be +subscripted in C90 mode, though otherwise they do not decay to +pointers outside C99 mode. For example, +this is valid in GNU C though not valid in C90: + +@smallexample +@group +struct foo @{int a[4];@}; + +struct foo f(); + +bar (int index) +@{ + return f().a[index]; +@} +@end group +@end smallexample + +@node Pointer Arith +@section Arithmetic on @code{void}- and Function-Pointers +@cindex void pointers, arithmetic +@cindex void, size of pointer to +@cindex function pointers, arithmetic +@cindex function, size of pointer to + +In GNU C, addition and subtraction operations are supported on pointers to +@code{void} and on pointers to functions. This is done by treating the +size of a @code{void} or of a function as 1. + +A consequence of this is that @code{sizeof} is also allowed on @code{void} +and on function types, and returns 1. + +@opindex Wpointer-arith +The option @option{-Wpointer-arith} requests a warning if these extensions +are used. + +@node Initializers +@section Non-Constant Initializers +@cindex initializers, non-constant +@cindex non-constant initializers + +As in standard C++ and ISO C99, the elements of an aggregate initializer for an +automatic variable are not required to be constant expressions in GNU C@. +Here is an example of an initializer with run-time varying elements: + +@smallexample +foo (float f, float g) +@{ + float beat_freqs[2] = @{ f-g, f+g @}; + /* @r{@dots{}} */ +@} +@end smallexample + +@node Compound Literals +@section Compound Literals +@cindex constructor expressions +@cindex initializations in expressions +@cindex structures, constructor expression +@cindex expressions, constructor +@cindex compound literals +@c The GNU C name for what C99 calls compound literals was "constructor expressions". + +ISO C99 supports compound literals. A compound literal looks like +a cast containing an initializer. Its value is an object of the +type specified in the cast, containing the elements specified in +the initializer; it is an lvalue. As an extension, GCC supports +compound literals in C90 mode and in C++. + +Usually, the specified type is a structure. Assume that +@code{struct foo} and @code{structure} are declared as shown: + +@smallexample +struct foo @{int a; char b[2];@} structure; +@end smallexample + +@noindent +Here is an example of constructing a @code{struct foo} with a compound literal: + +@smallexample +structure = ((struct foo) @{x + y, 'a', 0@}); +@end smallexample + +@noindent +This is equivalent to writing the following: + +@smallexample +@{ + struct foo temp = @{x + y, 'a', 0@}; + structure = temp; +@} +@end smallexample + +You can also construct an array. If all the elements of the compound literal +are (made up of) simple constant expressions, suitable for use in +initializers of objects of static storage duration, then the compound +literal can be coerced to a pointer to its first element and used in +such an initializer, as shown here: + +@smallexample +char **foo = (char *[]) @{ "x", "y", "z" @}; +@end smallexample + +Compound literals for scalar types and union types are is +also allowed, but then the compound literal is equivalent +to a cast. + +As a GNU extension, GCC allows initialization of objects with static storage +duration by compound literals (which is not possible in ISO C99, because +the initializer is not a constant). +It is handled as if the object was initialized only with the bracket +enclosed list if the types of the compound literal and the object match. +The initializer list of the compound literal must be constant. +If the object being initialized has array type of unknown size, the size is +determined by compound literal size. + +@smallexample +static struct foo x = (struct foo) @{1, 'a', 'b'@}; +static int y[] = (int []) @{1, 2, 3@}; +static int z[] = (int [3]) @{1@}; +@end smallexample + +@noindent +The above lines are equivalent to the following: +@smallexample +static struct foo x = @{1, 'a', 'b'@}; +static int y[] = @{1, 2, 3@}; +static int z[] = @{1, 0, 0@}; +@end smallexample + +@node Designated Inits +@section Designated Initializers +@cindex initializers with labeled elements +@cindex labeled elements in initializers +@cindex case labels in initializers +@cindex designated initializers + +Standard C90 requires the elements of an initializer to appear in a fixed +order, the same as the order of the elements in the array or structure +being initialized. + +In ISO C99 you can give the elements in any order, specifying the array +indices or structure field names they apply to, and GNU C allows this as +an extension in C90 mode as well. This extension is not +implemented in GNU C++. + +To specify an array index, write +@samp{[@var{index}] =} before the element value. For example, + +@smallexample +int a[6] = @{ [4] = 29, [2] = 15 @}; +@end smallexample + +@noindent +is equivalent to + +@smallexample +int a[6] = @{ 0, 0, 15, 0, 29, 0 @}; +@end smallexample + +@noindent +The index values must be constant expressions, even if the array being +initialized is automatic. + +An alternative syntax for this which has been obsolete since GCC 2.5 but +GCC still accepts is to write @samp{[@var{index}]} before the element +value, with no @samp{=}. + +To initialize a range of elements to the same value, write +@samp{[@var{first} ... @var{last}] = @var{value}}. This is a GNU +extension. For example, + +@smallexample +int widths[] = @{ [0 ... 9] = 1, [10 ... 99] = 2, [100] = 3 @}; +@end smallexample + +@noindent +If the value in it has side-effects, the side-effects will happen only once, +not for each initialized field by the range initializer. + +@noindent +Note that the length of the array is the highest value specified +plus one. + +In a structure initializer, specify the name of a field to initialize +with @samp{.@var{fieldname} =} before the element value. For example, +given the following structure, + +@smallexample +struct point @{ int x, y; @}; +@end smallexample + +@noindent +the following initialization + +@smallexample +struct point p = @{ .y = yvalue, .x = xvalue @}; +@end smallexample + +@noindent +is equivalent to + +@smallexample +struct point p = @{ xvalue, yvalue @}; +@end smallexample + +Another syntax which has the same meaning, obsolete since GCC 2.5, is +@samp{@var{fieldname}:}, as shown here: + +@smallexample +struct point p = @{ y: yvalue, x: xvalue @}; +@end smallexample + +@cindex designators +The @samp{[@var{index}]} or @samp{.@var{fieldname}} is known as a +@dfn{designator}. You can also use a designator (or the obsolete colon +syntax) when initializing a union, to specify which element of the union +should be used. For example, + +@smallexample +union foo @{ int i; double d; @}; + +union foo f = @{ .d = 4 @}; +@end smallexample + +@noindent +will convert 4 to a @code{double} to store it in the union using +the second element. By contrast, casting 4 to type @code{union foo} +would store it into the union as the integer @code{i}, since it is +an integer. (@xref{Cast to Union}.) + +You can combine this technique of naming elements with ordinary C +initialization of successive elements. Each initializer element that +does not have a designator applies to the next consecutive element of the +array or structure. For example, + +@smallexample +int a[6] = @{ [1] = v1, v2, [4] = v4 @}; +@end smallexample + +@noindent +is equivalent to + +@smallexample +int a[6] = @{ 0, v1, v2, 0, v4, 0 @}; +@end smallexample + +Labeling the elements of an array initializer is especially useful +when the indices are characters or belong to an @code{enum} type. +For example: + +@smallexample +int whitespace[256] + = @{ [' '] = 1, ['\t'] = 1, ['\h'] = 1, + ['\f'] = 1, ['\n'] = 1, ['\r'] = 1 @}; +@end smallexample + +@cindex designator lists +You can also write a series of @samp{.@var{fieldname}} and +@samp{[@var{index}]} designators before an @samp{=} to specify a +nested subobject to initialize; the list is taken relative to the +subobject corresponding to the closest surrounding brace pair. For +example, with the @samp{struct point} declaration above: + +@smallexample +struct point ptarray[10] = @{ [2].y = yv2, [2].x = xv2, [0].x = xv0 @}; +@end smallexample + +@noindent +If the same field is initialized multiple times, it will have value from +the last initialization. If any such overridden initialization has +side-effect, it is unspecified whether the side-effect happens or not. +Currently, GCC will discard them and issue a warning. + +@node Case Ranges +@section Case Ranges +@cindex case ranges +@cindex ranges in case statements + +You can specify a range of consecutive values in a single @code{case} label, +like this: + +@smallexample +case @var{low} ... @var{high}: +@end smallexample + +@noindent +This has the same effect as the proper number of individual @code{case} +labels, one for each integer value from @var{low} to @var{high}, inclusive. + +This feature is especially useful for ranges of ASCII character codes: + +@smallexample +case 'A' ... 'Z': +@end smallexample + +@strong{Be careful:} Write spaces around the @code{...}, for otherwise +it may be parsed wrong when you use it with integer values. For example, +write this: + +@smallexample +case 1 ... 5: +@end smallexample + +@noindent +rather than this: + +@smallexample +case 1...5: +@end smallexample + +@node Cast to Union +@section Cast to a Union Type +@cindex cast to a union +@cindex union, casting to a + +A cast to union type is similar to other casts, except that the type +specified is a union type. You can specify the type either with +@code{union @var{tag}} or with a typedef name. A cast to union is actually +a constructor though, not a cast, and hence does not yield an lvalue like +normal casts. (@xref{Compound Literals}.) + +The types that may be cast to the union type are those of the members +of the union. Thus, given the following union and variables: + +@smallexample +union foo @{ int i; double d; @}; +int x; +double y; +@end smallexample + +@noindent +both @code{x} and @code{y} can be cast to type @code{union foo}. + +Using the cast as the right-hand side of an assignment to a variable of +union type is equivalent to storing in a member of the union: + +@smallexample +union foo u; +/* @r{@dots{}} */ +u = (union foo) x @equiv{} u.i = x +u = (union foo) y @equiv{} u.d = y +@end smallexample + +You can also use the union cast as a function argument: + +@smallexample +void hack (union foo); +/* @r{@dots{}} */ +hack ((union foo) x); +@end smallexample + +@node Mixed Declarations +@section Mixed Declarations and Code +@cindex mixed declarations and code +@cindex declarations, mixed with code +@cindex code, mixed with declarations + +ISO C99 and ISO C++ allow declarations and code to be freely mixed +within compound statements. As an extension, GCC also allows this in +C90 mode. For example, you could do: + +@smallexample +int i; +/* @r{@dots{}} */ +i++; +int j = i + 2; +@end smallexample + +Each identifier is visible from where it is declared until the end of +the enclosing block. + +@node Function Attributes +@section Declaring Attributes of Functions +@cindex function attributes +@cindex declaring attributes of functions +@cindex functions that never return +@cindex functions that return more than once +@cindex functions that have no side effects +@cindex functions in arbitrary sections +@cindex functions that behave like malloc +@cindex @code{volatile} applied to function +@cindex @code{const} applied to function +@cindex functions with @code{printf}, @code{scanf}, @code{strftime} or @code{strfmon} style arguments +@cindex functions with non-null pointer arguments +@cindex functions that are passed arguments in registers on the 386 +@cindex functions that pop the argument stack on the 386 +@cindex functions that do not pop the argument stack on the 386 +@cindex functions that have different compilation options on the 386 +@cindex functions that have different optimization options +@cindex functions that are dynamically resolved + +In GNU C, you declare certain things about functions called in your program +which help the compiler optimize function calls and check your code more +carefully. + +The keyword @code{__attribute__} allows you to specify special +attributes when making a declaration. This keyword is followed by an +attribute specification inside double parentheses. The following +attributes are currently defined for functions on all targets: +@code{aligned}, @code{alloc_size}, @code{noreturn}, +@code{returns_twice}, @code{noinline}, @code{noclone}, +@code{always_inline}, @code{flatten}, @code{pure}, @code{const}, +@code{nothrow}, @code{sentinel}, @code{format}, @code{format_arg}, +@code{no_instrument_function}, @code{no_split_stack}, +@code{section}, @code{constructor}, +@code{destructor}, @code{used}, @code{unused}, @code{deprecated}, +@code{weak}, @code{malloc}, @code{alias}, @code{ifunc}, +@code{warn_unused_result}, @code{nonnull}, @code{gnu_inline}, +@code{externally_visible}, @code{hot}, @code{cold}, @code{artificial}, +@code{error} and @code{warning}. Several other attributes are defined +for functions on particular target systems. Other attributes, +including @code{section} are supported for variables declarations +(@pxref{Variable Attributes}) and for types (@pxref{Type Attributes}). + +GCC plugins may provide their own attributes. + +You may also specify attributes with @samp{__} preceding and following +each keyword. This allows you to use them in header files without +being concerned about a possible macro of the same name. For example, +you may use @code{__noreturn__} instead of @code{noreturn}. + +@xref{Attribute Syntax}, for details of the exact syntax for using +attributes. + +@table @code +@c Keep this table alphabetized by attribute name. Treat _ as space. + +@item alias ("@var{target}") +@cindex @code{alias} attribute +The @code{alias} attribute causes the declaration to be emitted as an +alias for another symbol, which must be specified. For instance, + +@smallexample +void __f () @{ /* @r{Do something.} */; @} +void f () __attribute__ ((weak, alias ("__f"))); +@end smallexample + +defines @samp{f} to be a weak alias for @samp{__f}. In C++, the +mangled name for the target must be used. It is an error if @samp{__f} +is not defined in the same translation unit. + +Not all target machines support this attribute. + +@item aligned (@var{alignment}) +@cindex @code{aligned} attribute +This attribute specifies a minimum alignment for the function, +measured in bytes. + +You cannot use this attribute to decrease the alignment of a function, +only to increase it. However, when you explicitly specify a function +alignment this will override the effect of the +@option{-falign-functions} (@pxref{Optimize Options}) option for this +function. + +Note that the effectiveness of @code{aligned} attributes may be +limited by inherent limitations in your linker. On many systems, the +linker is only able to arrange for functions to be aligned up to a +certain maximum alignment. (For some linkers, the maximum supported +alignment may be very very small.) See your linker documentation for +further information. + +The @code{aligned} attribute can also be used for variables and fields +(@pxref{Variable Attributes}.) + +@item alloc_size +@cindex @code{alloc_size} attribute +The @code{alloc_size} attribute is used to tell the compiler that the +function return value points to memory, where the size is given by +one or two of the functions parameters. GCC uses this +information to improve the correctness of @code{__builtin_object_size}. + +The function parameter(s) denoting the allocated size are specified by +one or two integer arguments supplied to the attribute. The allocated size +is either the value of the single function argument specified or the product +of the two function arguments specified. Argument numbering starts at +one. + +For instance, + +@smallexample +void* my_calloc(size_t, size_t) __attribute__((alloc_size(1,2))) +void my_realloc(void*, size_t) __attribute__((alloc_size(2))) +@end smallexample + +declares that my_calloc will return memory of the size given by +the product of parameter 1 and 2 and that my_realloc will return memory +of the size given by parameter 2. + +@item always_inline +@cindex @code{always_inline} function attribute +Generally, functions are not inlined unless optimization is specified. +For functions declared inline, this attribute inlines the function even +if no optimization level was specified. + +@item gnu_inline +@cindex @code{gnu_inline} function attribute +This attribute should be used with a function which is also declared +with the @code{inline} keyword. It directs GCC to treat the function +as if it were defined in gnu90 mode even when compiling in C99 or +gnu99 mode. + +If the function is declared @code{extern}, then this definition of the +function is used only for inlining. In no case is the function +compiled as a standalone function, not even if you take its address +explicitly. Such an address becomes an external reference, as if you +had only declared the function, and had not defined it. This has +almost the effect of a macro. The way to use this is to put a +function definition in a header file with this attribute, and put +another copy of the function, without @code{extern}, in a library +file. The definition in the header file will cause most calls to the +function to be inlined. If any uses of the function remain, they will +refer to the single copy in the library. Note that the two +definitions of the functions need not be precisely the same, although +if they do not have the same effect your program may behave oddly. + +In C, if the function is neither @code{extern} nor @code{static}, then +the function is compiled as a standalone function, as well as being +inlined where possible. + +This is how GCC traditionally handled functions declared +@code{inline}. Since ISO C99 specifies a different semantics for +@code{inline}, this function attribute is provided as a transition +measure and as a useful feature in its own right. This attribute is +available in GCC 4.1.3 and later. It is available if either of the +preprocessor macros @code{__GNUC_GNU_INLINE__} or +@code{__GNUC_STDC_INLINE__} are defined. @xref{Inline,,An Inline +Function is As Fast As a Macro}. + +In C++, this attribute does not depend on @code{extern} in any way, +but it still requires the @code{inline} keyword to enable its special +behavior. + +@item artificial +@cindex @code{artificial} function attribute +This attribute is useful for small inline wrappers which if possible +should appear during debugging as a unit, depending on the debug +info format it will either mean marking the function as artificial +or using the caller location for all instructions within the inlined +body. + +@item bank_switch +@cindex interrupt handler functions +When added to an interrupt handler with the M32C port, causes the +prologue and epilogue to use bank switching to preserve the registers +rather than saving them on the stack. + +@item flatten +@cindex @code{flatten} function attribute +Generally, inlining into a function is limited. For a function marked with +this attribute, every call inside this function will be inlined, if possible. +Whether the function itself is considered for inlining depends on its size and +the current inlining parameters. + +@item error ("@var{message}") +@cindex @code{error} function attribute +If this attribute is used on a function declaration and a call to such a function +is not eliminated through dead code elimination or other optimizations, an error +which will include @var{message} will be diagnosed. This is useful +for compile time checking, especially together with @code{__builtin_constant_p} +and inline functions where checking the inline function arguments is not +possible through @code{extern char [(condition) ? 1 : -1];} tricks. +While it is possible to leave the function undefined and thus invoke +a link failure, when using this attribute the problem will be diagnosed +earlier and with exact location of the call even in presence of inline +functions or when not emitting debugging information. + +@item warning ("@var{message}") +@cindex @code{warning} function attribute +If this attribute is used on a function declaration and a call to such a function +is not eliminated through dead code elimination or other optimizations, a warning +which will include @var{message} will be diagnosed. This is useful +for compile time checking, especially together with @code{__builtin_constant_p} +and inline functions. While it is possible to define the function with +a message in @code{.gnu.warning*} section, when using this attribute the problem +will be diagnosed earlier and with exact location of the call even in presence +of inline functions or when not emitting debugging information. + +@item cdecl +@cindex functions that do pop the argument stack on the 386 +@opindex mrtd +On the Intel 386, the @code{cdecl} attribute causes the compiler to +assume that the calling function will pop off the stack space used to +pass arguments. This is +useful to override the effects of the @option{-mrtd} switch. + +@item const +@cindex @code{const} function attribute +Many functions do not examine any values except their arguments, and +have no effects except the return value. Basically this is just slightly +more strict class than the @code{pure} attribute below, since function is not +allowed to read global memory. + +@cindex pointer arguments +Note that a function that has pointer arguments and examines the data +pointed to must @emph{not} be declared @code{const}. Likewise, a +function that calls a non-@code{const} function usually must not be +@code{const}. It does not make sense for a @code{const} function to +return @code{void}. + +The attribute @code{const} is not implemented in GCC versions earlier +than 2.5. An alternative way to declare that a function has no side +effects, which works in the current version and in some older versions, +is as follows: + +@smallexample +typedef int intfn (); + +extern const intfn square; +@end smallexample + +This approach does not work in GNU C++ from 2.6.0 on, since the language +specifies that the @samp{const} must be attached to the return value. + +@item constructor +@itemx destructor +@itemx constructor (@var{priority}) +@itemx destructor (@var{priority}) +@cindex @code{constructor} function attribute +@cindex @code{destructor} function attribute +The @code{constructor} attribute causes the function to be called +automatically before execution enters @code{main ()}. Similarly, the +@code{destructor} attribute causes the function to be called +automatically after @code{main ()} has completed or @code{exit ()} has +been called. Functions with these attributes are useful for +initializing data that will be used implicitly during the execution of +the program. + +You may provide an optional integer priority to control the order in +which constructor and destructor functions are run. A constructor +with a smaller priority number runs before a constructor with a larger +priority number; the opposite relationship holds for destructors. So, +if you have a constructor that allocates a resource and a destructor +that deallocates the same resource, both functions typically have the +same priority. The priorities for constructor and destructor +functions are the same as those specified for namespace-scope C++ +objects (@pxref{C++ Attributes}). + +These attributes are not currently implemented for Objective-C@. + +@item deprecated +@itemx deprecated (@var{msg}) +@cindex @code{deprecated} attribute. +The @code{deprecated} attribute results in a warning if the function +is used anywhere in the source file. This is useful when identifying +functions that are expected to be removed in a future version of a +program. The warning also includes the location of the declaration +of the deprecated function, to enable users to easily find further +information about why the function is deprecated, or what they should +do instead. Note that the warnings only occurs for uses: + +@smallexample +int old_fn () __attribute__ ((deprecated)); +int old_fn (); +int (*fn_ptr)() = old_fn; +@end smallexample + +results in a warning on line 3 but not line 2. The optional msg +argument, which must be a string, will be printed in the warning if +present. + +The @code{deprecated} attribute can also be used for variables and +types (@pxref{Variable Attributes}, @pxref{Type Attributes}.) + +@item disinterrupt +@cindex @code{disinterrupt} attribute +On MeP targets, this attribute causes the compiler to emit +instructions to disable interrupts for the duration of the given +function. + +@item dllexport +@cindex @code{__declspec(dllexport)} +On Microsoft Windows targets and Symbian OS targets the +@code{dllexport} attribute causes the compiler to provide a global +pointer to a pointer in a DLL, so that it can be referenced with the +@code{dllimport} attribute. On Microsoft Windows targets, the pointer +name is formed by combining @code{_imp__} and the function or variable +name. + +You can use @code{__declspec(dllexport)} as a synonym for +@code{__attribute__ ((dllexport))} for compatibility with other +compilers. + +On systems that support the @code{visibility} attribute, this +attribute also implies ``default'' visibility. It is an error to +explicitly specify any other visibility. + +In previous versions of GCC, the @code{dllexport} attribute was ignored +for inlined functions, unless the @option{-fkeep-inline-functions} flag +had been used. The default behaviour now is to emit all dllexported +inline functions; however, this can cause object file-size bloat, in +which case the old behaviour can be restored by using +@option{-fno-keep-inline-dllexport}. + +The attribute is also ignored for undefined symbols. + +When applied to C++ classes, the attribute marks defined non-inlined +member functions and static data members as exports. Static consts +initialized in-class are not marked unless they are also defined +out-of-class. + +For Microsoft Windows targets there are alternative methods for +including the symbol in the DLL's export table such as using a +@file{.def} file with an @code{EXPORTS} section or, with GNU ld, using +the @option{--export-all} linker flag. + +@item dllimport +@cindex @code{__declspec(dllimport)} +On Microsoft Windows and Symbian OS targets, the @code{dllimport} +attribute causes the compiler to reference a function or variable via +a global pointer to a pointer that is set up by the DLL exporting the +symbol. The attribute implies @code{extern}. On Microsoft Windows +targets, the pointer name is formed by combining @code{_imp__} and the +function or variable name. + +You can use @code{__declspec(dllimport)} as a synonym for +@code{__attribute__ ((dllimport))} for compatibility with other +compilers. + +On systems that support the @code{visibility} attribute, this +attribute also implies ``default'' visibility. It is an error to +explicitly specify any other visibility. + +Currently, the attribute is ignored for inlined functions. If the +attribute is applied to a symbol @emph{definition}, an error is reported. +If a symbol previously declared @code{dllimport} is later defined, the +attribute is ignored in subsequent references, and a warning is emitted. +The attribute is also overridden by a subsequent declaration as +@code{dllexport}. + +When applied to C++ classes, the attribute marks non-inlined +member functions and static data members as imports. However, the +attribute is ignored for virtual methods to allow creation of vtables +using thunks. + +On the SH Symbian OS target the @code{dllimport} attribute also has +another affect---it can cause the vtable and run-time type information +for a class to be exported. This happens when the class has a +dllimport'ed constructor or a non-inline, non-pure virtual function +and, for either of those two conditions, the class also has an inline +constructor or destructor and has a key function that is defined in +the current translation unit. + +For Microsoft Windows based targets the use of the @code{dllimport} +attribute on functions is not necessary, but provides a small +performance benefit by eliminating a thunk in the DLL@. The use of the +@code{dllimport} attribute on imported variables was required on older +versions of the GNU linker, but can now be avoided by passing the +@option{--enable-auto-import} switch to the GNU linker. As with +functions, using the attribute for a variable eliminates a thunk in +the DLL@. + +One drawback to using this attribute is that a pointer to a +@emph{variable} marked as @code{dllimport} cannot be used as a constant +address. However, a pointer to a @emph{function} with the +@code{dllimport} attribute can be used as a constant initializer; in +this case, the address of a stub function in the import lib is +referenced. On Microsoft Windows targets, the attribute can be disabled +for functions by setting the @option{-mnop-fun-dllimport} flag. + +@item eightbit_data +@cindex eight bit data on the H8/300, H8/300H, and H8S +Use this attribute on the H8/300, H8/300H, and H8S to indicate that the specified +variable should be placed into the eight bit data section. +The compiler will generate more efficient code for certain operations +on data in the eight bit data area. Note the eight bit data area is limited to +256 bytes of data. + +You must use GAS and GLD from GNU binutils version 2.7 or later for +this attribute to work correctly. + +@item exception_handler +@cindex exception handler functions on the Blackfin processor +Use this attribute on the Blackfin to indicate that the specified function +is an exception handler. The compiler will generate function entry and +exit sequences suitable for use in an exception handler when this +attribute is present. + +@item externally_visible +@cindex @code{externally_visible} attribute. +This attribute, attached to a global variable or function, nullifies +the effect of the @option{-fwhole-program} command-line option, so the +object remains visible outside the current compilation unit. If @option{-fwhole-program} is used together with @option{-flto} and @command{gold} is used as the linker plugin, @code{externally_visible} attributes are automatically added to functions (not variable yet due to a current @command{gold} issue) that are accessed outside of LTO objects according to resolution file produced by @command{gold}. For other linkers that cannot generate resolution file, explicit @code{externally_visible} attributes are still necessary. + +@item far +@cindex functions which handle memory bank switching +On 68HC11 and 68HC12 the @code{far} attribute causes the compiler to +use a calling convention that takes care of switching memory banks when +entering and leaving a function. This calling convention is also the +default when using the @option{-mlong-calls} option. + +On 68HC12 the compiler will use the @code{call} and @code{rtc} instructions +to call and return from a function. + +On 68HC11 the compiler will generate a sequence of instructions +to invoke a board-specific routine to switch the memory bank and call the +real function. The board-specific routine simulates a @code{call}. +At the end of a function, it will jump to a board-specific routine +instead of using @code{rts}. The board-specific return routine simulates +the @code{rtc}. + +On MeP targets this causes the compiler to use a calling convention +which assumes the called function is too far away for the built-in +addressing modes. + +@item fast_interrupt +@cindex interrupt handler functions +Use this attribute on the M32C and RX ports to indicate that the specified +function is a fast interrupt handler. This is just like the +@code{interrupt} attribute, except that @code{freit} is used to return +instead of @code{reit}. + +@item fastcall +@cindex functions that pop the argument stack on the 386 +On the Intel 386, the @code{fastcall} attribute causes the compiler to +pass the first argument (if of integral type) in the register ECX and +the second argument (if of integral type) in the register EDX@. Subsequent +and other typed arguments are passed on the stack. The called function will +pop the arguments off the stack. If the number of arguments is variable all +arguments are pushed on the stack. + +@item thiscall +@cindex functions that pop the argument stack on the 386 +On the Intel 386, the @code{thiscall} attribute causes the compiler to +pass the first argument (if of integral type) in the register ECX. +Subsequent and other typed arguments are passed on the stack. The called +function will pop the arguments off the stack. +If the number of arguments is variable all arguments are pushed on the +stack. +The @code{thiscall} attribute is intended for C++ non-static member functions. +As gcc extension this calling convention can be used for C-functions +and for static member methods. + +@item format (@var{archetype}, @var{string-index}, @var{first-to-check}) +@cindex @code{format} function attribute +@opindex Wformat +The @code{format} attribute specifies that a function takes @code{printf}, +@code{scanf}, @code{strftime} or @code{strfmon} style arguments which +should be type-checked against a format string. For example, the +declaration: + +@smallexample +extern int +my_printf (void *my_object, const char *my_format, ...) + __attribute__ ((format (printf, 2, 3))); +@end smallexample + +@noindent +causes the compiler to check the arguments in calls to @code{my_printf} +for consistency with the @code{printf} style format string argument +@code{my_format}. + +The parameter @var{archetype} determines how the format string is +interpreted, and should be @code{printf}, @code{scanf}, @code{strftime}, +@code{gnu_printf}, @code{gnu_scanf}, @code{gnu_strftime} or +@code{strfmon}. (You can also use @code{__printf__}, +@code{__scanf__}, @code{__strftime__} or @code{__strfmon__}.) On +MinGW targets, @code{ms_printf}, @code{ms_scanf}, and +@code{ms_strftime} are also present. +@var{archtype} values such as @code{printf} refer to the formats accepted +by the system's C run-time library, while @code{gnu_} values always refer +to the formats accepted by the GNU C Library. On Microsoft Windows +targets, @code{ms_} values refer to the formats accepted by the +@file{msvcrt.dll} library. +The parameter @var{string-index} +specifies which argument is the format string argument (starting +from 1), while @var{first-to-check} is the number of the first +argument to check against the format string. For functions +where the arguments are not available to be checked (such as +@code{vprintf}), specify the third parameter as zero. In this case the +compiler only checks the format string for consistency. For +@code{strftime} formats, the third parameter is required to be zero. +Since non-static C++ methods have an implicit @code{this} argument, the +arguments of such methods should be counted from two, not one, when +giving values for @var{string-index} and @var{first-to-check}. + +In the example above, the format string (@code{my_format}) is the second +argument of the function @code{my_print}, and the arguments to check +start with the third argument, so the correct parameters for the format +attribute are 2 and 3. + +@opindex ffreestanding +@opindex fno-builtin +The @code{format} attribute allows you to identify your own functions +which take format strings as arguments, so that GCC can check the +calls to these functions for errors. The compiler always (unless +@option{-ffreestanding} or @option{-fno-builtin} is used) checks formats +for the standard library functions @code{printf}, @code{fprintf}, +@code{sprintf}, @code{scanf}, @code{fscanf}, @code{sscanf}, @code{strftime}, +@code{vprintf}, @code{vfprintf} and @code{vsprintf} whenever such +warnings are requested (using @option{-Wformat}), so there is no need to +modify the header file @file{stdio.h}. In C99 mode, the functions +@code{snprintf}, @code{vsnprintf}, @code{vscanf}, @code{vfscanf} and +@code{vsscanf} are also checked. Except in strictly conforming C +standard modes, the X/Open function @code{strfmon} is also checked as +are @code{printf_unlocked} and @code{fprintf_unlocked}. +@xref{C Dialect Options,,Options Controlling C Dialect}. + +For Objective-C dialects, @code{NSString} (or @code{__NSString__}) is +recognized in the same context. Declarations including these format attributes +will be parsed for correct syntax, however the result of checking of such format +strings is not yet defined, and will not be carried out by this version of the +compiler. + +The target may also provide additional types of format checks. +@xref{Target Format Checks,,Format Checks Specific to Particular +Target Machines}. + +@item format_arg (@var{string-index}) +@cindex @code{format_arg} function attribute +@opindex Wformat-nonliteral +The @code{format_arg} attribute specifies that a function takes a format +string for a @code{printf}, @code{scanf}, @code{strftime} or +@code{strfmon} style function and modifies it (for example, to translate +it into another language), so the result can be passed to a +@code{printf}, @code{scanf}, @code{strftime} or @code{strfmon} style +function (with the remaining arguments to the format function the same +as they would have been for the unmodified string). For example, the +declaration: + +@smallexample +extern char * +my_dgettext (char *my_domain, const char *my_format) + __attribute__ ((format_arg (2))); +@end smallexample + +@noindent +causes the compiler to check the arguments in calls to a @code{printf}, +@code{scanf}, @code{strftime} or @code{strfmon} type function, whose +format string argument is a call to the @code{my_dgettext} function, for +consistency with the format string argument @code{my_format}. If the +@code{format_arg} attribute had not been specified, all the compiler +could tell in such calls to format functions would be that the format +string argument is not constant; this would generate a warning when +@option{-Wformat-nonliteral} is used, but the calls could not be checked +without the attribute. + +The parameter @var{string-index} specifies which argument is the format +string argument (starting from one). Since non-static C++ methods have +an implicit @code{this} argument, the arguments of such methods should +be counted from two. + +The @code{format-arg} attribute allows you to identify your own +functions which modify format strings, so that GCC can check the +calls to @code{printf}, @code{scanf}, @code{strftime} or @code{strfmon} +type function whose operands are a call to one of your own function. +The compiler always treats @code{gettext}, @code{dgettext}, and +@code{dcgettext} in this manner except when strict ISO C support is +requested by @option{-ansi} or an appropriate @option{-std} option, or +@option{-ffreestanding} or @option{-fno-builtin} +is used. @xref{C Dialect Options,,Options +Controlling C Dialect}. + +For Objective-C dialects, the @code{format-arg} attribute may refer to an +@code{NSString} reference for compatibility with the @code{format} attribute +above. + +The target may also allow additional types in @code{format-arg} attributes. +@xref{Target Format Checks,,Format Checks Specific to Particular +Target Machines}. + +@item function_vector +@cindex calling functions through the function vector on H8/300, M16C, M32C and SH2A processors +Use this attribute on the H8/300, H8/300H, and H8S to indicate that the specified +function should be called through the function vector. Calling a +function through the function vector will reduce code size, however; +the function vector has a limited size (maximum 128 entries on the H8/300 +and 64 entries on the H8/300H and H8S) and shares space with the interrupt vector. + +In SH2A target, this attribute declares a function to be called using the +TBR relative addressing mode. The argument to this attribute is the entry +number of the same function in a vector table containing all the TBR +relative addressable functions. For the successful jump, register TBR +should contain the start address of this TBR relative vector table. +In the startup routine of the user application, user needs to care of this +TBR register initialization. The TBR relative vector table can have at +max 256 function entries. The jumps to these functions will be generated +using a SH2A specific, non delayed branch instruction JSR/N @@(disp8,TBR). +You must use GAS and GLD from GNU binutils version 2.7 or later for +this attribute to work correctly. + +Please refer the example of M16C target, to see the use of this +attribute while declaring a function, + +In an application, for a function being called once, this attribute will +save at least 8 bytes of code; and if other successive calls are being +made to the same function, it will save 2 bytes of code per each of these +calls. + +On M16C/M32C targets, the @code{function_vector} attribute declares a +special page subroutine call function. Use of this attribute reduces +the code size by 2 bytes for each call generated to the +subroutine. The argument to the attribute is the vector number entry +from the special page vector table which contains the 16 low-order +bits of the subroutine's entry address. Each vector table has special +page number (18 to 255) which are used in @code{jsrs} instruction. +Jump addresses of the routines are generated by adding 0x0F0000 (in +case of M16C targets) or 0xFF0000 (in case of M32C targets), to the 2 +byte addresses set in the vector table. Therefore you need to ensure +that all the special page vector routines should get mapped within the +address range 0x0F0000 to 0x0FFFFF (for M16C) and 0xFF0000 to 0xFFFFFF +(for M32C). + +In the following example 2 bytes will be saved for each call to +function @code{foo}. + +@smallexample +void foo (void) __attribute__((function_vector(0x18))); +void foo (void) +@{ +@} + +void bar (void) +@{ + foo(); +@} +@end smallexample + +If functions are defined in one file and are called in another file, +then be sure to write this declaration in both files. + +This attribute is ignored for R8C target. + +@item interrupt +@cindex interrupt handler functions +Use this attribute on the ARM, AVR, CRX, M32C, M32R/D, m68k, MeP, MIPS, +RX and Xstormy16 ports to indicate that the specified function is an +interrupt handler. The compiler will generate function entry and exit +sequences suitable for use in an interrupt handler when this attribute +is present. + +Note, interrupt handlers for the Blackfin, H8/300, H8/300H, H8S, MicroBlaze, +and SH processors can be specified via the @code{interrupt_handler} attribute. + +Note, on the AVR, interrupts will be enabled inside the function. + +Note, for the ARM, you can specify the kind of interrupt to be handled by +adding an optional parameter to the interrupt attribute like this: + +@smallexample +void f () __attribute__ ((interrupt ("IRQ"))); +@end smallexample + +Permissible values for this parameter are: IRQ, FIQ, SWI, ABORT and UNDEF@. + +On ARMv7-M the interrupt type is ignored, and the attribute means the function +may be called with a word aligned stack pointer. + +On MIPS targets, you can use the following attributes to modify the behavior +of an interrupt handler: +@table @code +@item use_shadow_register_set +@cindex @code{use_shadow_register_set} attribute +Assume that the handler uses a shadow register set, instead of +the main general-purpose registers. + +@item keep_interrupts_masked +@cindex @code{keep_interrupts_masked} attribute +Keep interrupts masked for the whole function. Without this attribute, +GCC tries to reenable interrupts for as much of the function as it can. + +@item use_debug_exception_return +@cindex @code{use_debug_exception_return} attribute +Return using the @code{deret} instruction. Interrupt handlers that don't +have this attribute return using @code{eret} instead. +@end table + +You can use any combination of these attributes, as shown below: +@smallexample +void __attribute__ ((interrupt)) v0 (); +void __attribute__ ((interrupt, use_shadow_register_set)) v1 (); +void __attribute__ ((interrupt, keep_interrupts_masked)) v2 (); +void __attribute__ ((interrupt, use_debug_exception_return)) v3 (); +void __attribute__ ((interrupt, use_shadow_register_set, + keep_interrupts_masked)) v4 (); +void __attribute__ ((interrupt, use_shadow_register_set, + use_debug_exception_return)) v5 (); +void __attribute__ ((interrupt, keep_interrupts_masked, + use_debug_exception_return)) v6 (); +void __attribute__ ((interrupt, use_shadow_register_set, + keep_interrupts_masked, + use_debug_exception_return)) v7 (); +@end smallexample + +@item ifunc ("@var{resolver}") +@cindex @code{ifunc} attribute +The @code{ifunc} attribute is used to mark a function as an indirect +function using the STT_GNU_IFUNC symbol type extension to the ELF +standard. This allows the resolution of the symbol value to be +determined dynamically at load time, and an optimized version of the +routine can be selected for the particular processor or other system +characteristics determined then. To use this attribute, first define +the implementation functions available, and a resolver function that +returns a pointer to the selected implementation function. The +implementation functions' declarations must match the API of the +function being implemented, the resolver's declaration is be a +function returning pointer to void function returning void: + +@smallexample +void *my_memcpy (void *dst, const void *src, size_t len) +@{ + @dots{} +@} + +static void (*resolve_memcpy (void)) (void) +@{ + return my_memcpy; // we'll just always select this routine +@} +@end smallexample + +The exported header file declaring the function the user calls would +contain: + +@smallexample +extern void *memcpy (void *, const void *, size_t); +@end smallexample + +allowing the user to call this as a regular function, unaware of the +implementation. Finally, the indirect function needs to be defined in +the same translation unit as the resolver function: + +@smallexample +void *memcpy (void *, const void *, size_t) + __attribute__ ((ifunc ("resolve_memcpy"))); +@end smallexample + +Indirect functions cannot be weak, and require a recent binutils (at +least version 2.20.1), and GNU C library (at least version 2.11.1). + +@item interrupt_handler +@cindex interrupt handler functions on the Blackfin, m68k, H8/300 and SH processors +Use this attribute on the Blackfin, m68k, H8/300, H8/300H, H8S, and SH to +indicate that the specified function is an interrupt handler. The compiler +will generate function entry and exit sequences suitable for use in an +interrupt handler when this attribute is present. + +@item interrupt_thread +@cindex interrupt thread functions on fido +Use this attribute on fido, a subarchitecture of the m68k, to indicate +that the specified function is an interrupt handler that is designed +to run as a thread. The compiler omits generate prologue/epilogue +sequences and replaces the return instruction with a @code{sleep} +instruction. This attribute is available only on fido. + +@item isr +@cindex interrupt service routines on ARM +Use this attribute on ARM to write Interrupt Service Routines. This is an +alias to the @code{interrupt} attribute above. + +@item kspisusp +@cindex User stack pointer in interrupts on the Blackfin +When used together with @code{interrupt_handler}, @code{exception_handler} +or @code{nmi_handler}, code will be generated to load the stack pointer +from the USP register in the function prologue. + +@item l1_text +@cindex @code{l1_text} function attribute +This attribute specifies a function to be placed into L1 Instruction +SRAM@. The function will be put into a specific section named @code{.l1.text}. +With @option{-mfdpic}, function calls with a such function as the callee +or caller will use inlined PLT. + +@item l2 +@cindex @code{l2} function attribute +On the Blackfin, this attribute specifies a function to be placed into L2 +SRAM. The function will be put into a specific section named +@code{.l1.text}. With @option{-mfdpic}, callers of such functions will use +an inlined PLT. + +@item leaf +@cindex @code{leaf} function attribute +Calls to external functions with this attribute must return to the current +compilation unit only by return or by exception handling. In particular, leaf +functions are not allowed to call callback function passed to it from the current +compilation unit or directly call functions exported by the unit or longjmp +into the unit. Leaf function might still call functions from other compilation +units and thus they are not necessarily leaf in the sense that they contain no +function calls at all. + +The attribute is intended for library functions to improve dataflow analysis. +The compiler takes the hint that any data not escaping the current compilation unit can +not be used or modified by the leaf function. For example, the @code{sin} function +is a leaf function, but @code{qsort} is not. + +Note that leaf functions might invoke signals and signal handlers might be +defined in the current compilation unit and use static variables. The only +compliant way to write such a signal handler is to declare such variables +@code{volatile}. + +The attribute has no effect on functions defined within the current compilation +unit. This is to allow easy merging of multiple compilation units into one, +for example, by using the link time optimization. For this reason the +attribute is not allowed on types to annotate indirect calls. + +@item long_call/short_call +@cindex indirect calls on ARM +This attribute specifies how a particular function is called on +ARM@. Both attributes override the @option{-mlong-calls} (@pxref{ARM Options}) +command-line switch and @code{#pragma long_calls} settings. The +@code{long_call} attribute indicates that the function might be far +away from the call site and require a different (more expensive) +calling sequence. The @code{short_call} attribute always places +the offset to the function from the call site into the @samp{BL} +instruction directly. + +@item longcall/shortcall +@cindex functions called via pointer on the RS/6000 and PowerPC +On the Blackfin, RS/6000 and PowerPC, the @code{longcall} attribute +indicates that the function might be far away from the call site and +require a different (more expensive) calling sequence. The +@code{shortcall} attribute indicates that the function is always close +enough for the shorter calling sequence to be used. These attributes +override both the @option{-mlongcall} switch and, on the RS/6000 and +PowerPC, the @code{#pragma longcall} setting. + +@xref{RS/6000 and PowerPC Options}, for more information on whether long +calls are necessary. + +@item long_call/near/far +@cindex indirect calls on MIPS +These attributes specify how a particular function is called on MIPS@. +The attributes override the @option{-mlong-calls} (@pxref{MIPS Options}) +command-line switch. The @code{long_call} and @code{far} attributes are +synonyms, and cause the compiler to always call +the function by first loading its address into a register, and then using +the contents of that register. The @code{near} attribute has the opposite +effect; it specifies that non-PIC calls should be made using the more +efficient @code{jal} instruction. + +@item malloc +@cindex @code{malloc} attribute +The @code{malloc} attribute is used to tell the compiler that a function +may be treated as if any non-@code{NULL} pointer it returns cannot +alias any other pointer valid when the function returns. +This will often improve optimization. +Standard functions with this property include @code{malloc} and +@code{calloc}. @code{realloc}-like functions have this property as +long as the old pointer is never referred to (including comparing it +to the new pointer) after the function returns a non-@code{NULL} +value. + +@item mips16/nomips16 +@cindex @code{mips16} attribute +@cindex @code{nomips16} attribute + +On MIPS targets, you can use the @code{mips16} and @code{nomips16} +function attributes to locally select or turn off MIPS16 code generation. +A function with the @code{mips16} attribute is emitted as MIPS16 code, +while MIPS16 code generation is disabled for functions with the +@code{nomips16} attribute. These attributes override the +@option{-mips16} and @option{-mno-mips16} options on the command line +(@pxref{MIPS Options}). + +When compiling files containing mixed MIPS16 and non-MIPS16 code, the +preprocessor symbol @code{__mips16} reflects the setting on the command line, +not that within individual functions. Mixed MIPS16 and non-MIPS16 code +may interact badly with some GCC extensions such as @code{__builtin_apply} +(@pxref{Constructing Calls}). + +@item model (@var{model-name}) +@cindex function addressability on the M32R/D +@cindex variable addressability on the IA-64 + +On the M32R/D, use this attribute to set the addressability of an +object, and of the code generated for a function. The identifier +@var{model-name} is one of @code{small}, @code{medium}, or +@code{large}, representing each of the code models. + +Small model objects live in the lower 16MB of memory (so that their +addresses can be loaded with the @code{ld24} instruction), and are +callable with the @code{bl} instruction. + +Medium model objects may live anywhere in the 32-bit address space (the +compiler will generate @code{seth/add3} instructions to load their addresses), +and are callable with the @code{bl} instruction. + +Large model objects may live anywhere in the 32-bit address space (the +compiler will generate @code{seth/add3} instructions to load their addresses), +and may not be reachable with the @code{bl} instruction (the compiler will +generate the much slower @code{seth/add3/jl} instruction sequence). + +On IA-64, use this attribute to set the addressability of an object. +At present, the only supported identifier for @var{model-name} is +@code{small}, indicating addressability via ``small'' (22-bit) +addresses (so that their addresses can be loaded with the @code{addl} +instruction). Caveat: such addressing is by definition not position +independent and hence this attribute must not be used for objects +defined by shared libraries. + +@item ms_abi/sysv_abi +@cindex @code{ms_abi} attribute +@cindex @code{sysv_abi} attribute + +On 64-bit x86_64-*-* targets, you can use an ABI attribute to indicate +which calling convention should be used for a function. The @code{ms_abi} +attribute tells the compiler to use the Microsoft ABI, while the +@code{sysv_abi} attribute tells the compiler to use the ABI used on +GNU/Linux and other systems. The default is to use the Microsoft ABI +when targeting Windows. On all other systems, the default is the AMD ABI. + +Note, the @code{ms_abi} attribute for Windows targets currently requires +the @option{-maccumulate-outgoing-args} option. + +@item callee_pop_aggregate_return (@var{number}) +@cindex @code{callee_pop_aggregate_return} attribute + +On 32-bit i?86-*-* targets, you can control by those attribute for +aggregate return in memory, if the caller is responsible to pop the hidden +pointer together with the rest of the arguments - @var{number} equal to +zero -, or if the callee is responsible to pop hidden pointer - @var{number} +equal to one. + +For i?86-netware, the caller pops the stack for the hidden arguments pointing +to aggregate return value. This differs from the default i386 ABI which assumes +that the callee pops the stack for hidden pointer. + +@item ms_hook_prologue +@cindex @code{ms_hook_prologue} attribute + +On 32 bit i[34567]86-*-* targets and 64 bit x86_64-*-* targets, you can use +this function attribute to make gcc generate the "hot-patching" function +prologue used in Win32 API functions in Microsoft Windows XP Service Pack 2 +and newer. + +@item naked +@cindex function without a prologue/epilogue code +Use this attribute on the ARM, AVR, MCORE, RX and SPU ports to indicate that +the specified function does not need prologue/epilogue sequences generated by +the compiler. It is up to the programmer to provide these sequences. The +only statements that can be safely included in naked functions are +@code{asm} statements that do not have operands. All other statements, +including declarations of local variables, @code{if} statements, and so +forth, should be avoided. Naked functions should be used to implement the +body of an assembly function, while allowing the compiler to construct +the requisite function declaration for the assembler. + +@item near +@cindex functions which do not handle memory bank switching on 68HC11/68HC12 +On 68HC11 and 68HC12 the @code{near} attribute causes the compiler to +use the normal calling convention based on @code{jsr} and @code{rts}. +This attribute can be used to cancel the effect of the @option{-mlong-calls} +option. + +On MeP targets this attribute causes the compiler to assume the called +function is close enough to use the normal calling convention, +overriding the @code{-mtf} command line option. + +@item nesting +@cindex Allow nesting in an interrupt handler on the Blackfin processor. +Use this attribute together with @code{interrupt_handler}, +@code{exception_handler} or @code{nmi_handler} to indicate that the function +entry code should enable nested interrupts or exceptions. + +@item nmi_handler +@cindex NMI handler functions on the Blackfin processor +Use this attribute on the Blackfin to indicate that the specified function +is an NMI handler. The compiler will generate function entry and +exit sequences suitable for use in an NMI handler when this +attribute is present. + +@item no_instrument_function +@cindex @code{no_instrument_function} function attribute +@opindex finstrument-functions +If @option{-finstrument-functions} is given, profiling function calls will +be generated at entry and exit of most user-compiled functions. +Functions with this attribute will not be so instrumented. + +@item no_split_stack +@cindex @code{no_split_stack} function attribute +@opindex fsplit-stack +If @option{-fsplit-stack} is given, functions will have a small +prologue which decides whether to split the stack. Functions with the +@code{no_split_stack} attribute will not have that prologue, and thus +may run with only a small amount of stack space available. + +@item noinline +@cindex @code{noinline} function attribute +This function attribute prevents a function from being considered for +inlining. +@c Don't enumerate the optimizations by name here; we try to be +@c future-compatible with this mechanism. +If the function does not have side-effects, there are optimizations +other than inlining that causes function calls to be optimized away, +although the function call is live. To keep such calls from being +optimized away, put +@smallexample +asm (""); +@end smallexample +(@pxref{Extended Asm}) in the called function, to serve as a special +side-effect. + +@item noclone +@cindex @code{noclone} function attribute +This function attribute prevents a function from being considered for +cloning - a mechanism which produces specialized copies of functions +and which is (currently) performed by interprocedural constant +propagation. + +@item nonnull (@var{arg-index}, @dots{}) +@cindex @code{nonnull} function attribute +The @code{nonnull} attribute specifies that some function parameters should +be non-null pointers. For instance, the declaration: + +@smallexample +extern void * +my_memcpy (void *dest, const void *src, size_t len) + __attribute__((nonnull (1, 2))); +@end smallexample + +@noindent +causes the compiler to check that, in calls to @code{my_memcpy}, +arguments @var{dest} and @var{src} are non-null. If the compiler +determines that a null pointer is passed in an argument slot marked +as non-null, and the @option{-Wnonnull} option is enabled, a warning +is issued. The compiler may also choose to make optimizations based +on the knowledge that certain function arguments will not be null. + +If no argument index list is given to the @code{nonnull} attribute, +all pointer arguments are marked as non-null. To illustrate, the +following declaration is equivalent to the previous example: + +@smallexample +extern void * +my_memcpy (void *dest, const void *src, size_t len) + __attribute__((nonnull)); +@end smallexample + +@item noreturn +@cindex @code{noreturn} function attribute +A few standard library functions, such as @code{abort} and @code{exit}, +cannot return. GCC knows this automatically. Some programs define +their own functions that never return. You can declare them +@code{noreturn} to tell the compiler this fact. For example, + +@smallexample +@group +void fatal () __attribute__ ((noreturn)); + +void +fatal (/* @r{@dots{}} */) +@{ + /* @r{@dots{}} */ /* @r{Print error message.} */ /* @r{@dots{}} */ + exit (1); +@} +@end group +@end smallexample + +The @code{noreturn} keyword tells the compiler to assume that +@code{fatal} cannot return. It can then optimize without regard to what +would happen if @code{fatal} ever did return. This makes slightly +better code. More importantly, it helps avoid spurious warnings of +uninitialized variables. + +The @code{noreturn} keyword does not affect the exceptional path when that +applies: a @code{noreturn}-marked function may still return to the caller +by throwing an exception or calling @code{longjmp}. + +Do not assume that registers saved by the calling function are +restored before calling the @code{noreturn} function. + +It does not make sense for a @code{noreturn} function to have a return +type other than @code{void}. + +The attribute @code{noreturn} is not implemented in GCC versions +earlier than 2.5. An alternative way to declare that a function does +not return, which works in the current version and in some older +versions, is as follows: + +@smallexample +typedef void voidfn (); + +volatile voidfn fatal; +@end smallexample + +This approach does not work in GNU C++. + +@item nothrow +@cindex @code{nothrow} function attribute +The @code{nothrow} attribute is used to inform the compiler that a +function cannot throw an exception. For example, most functions in +the standard C library can be guaranteed not to throw an exception +with the notable exceptions of @code{qsort} and @code{bsearch} that +take function pointer arguments. The @code{nothrow} attribute is not +implemented in GCC versions earlier than 3.3. + +@item optimize +@cindex @code{optimize} function attribute +The @code{optimize} attribute is used to specify that a function is to +be compiled with different optimization options than specified on the +command line. Arguments can either be numbers or strings. Numbers +are assumed to be an optimization level. Strings that begin with +@code{O} are assumed to be an optimization option, while other options +are assumed to be used with a @code{-f} prefix. You can also use the +@samp{#pragma GCC optimize} pragma to set the optimization options +that affect more than one function. +@xref{Function Specific Option Pragmas}, for details about the +@samp{#pragma GCC optimize} pragma. + +This can be used for instance to have frequently executed functions +compiled with more aggressive optimization options that produce faster +and larger code, while other functions can be called with less +aggressive options. + +@item OS_main/OS_task +@cindex @code{OS_main} AVR function attribute +@cindex @code{OS_task} AVR function attribute +On AVR, functions with the @code{OS_main} or @code{OS_task} attribute +do not save/restore any call-saved register in their prologue/epilogue. + +The @code{OS_main} attribute can be used when there @emph{is +guarantee} that interrupts are disabled at the time when the function +is entered. This will save resources when the stack pointer has to be +changed to set up a frame for local variables. + +The @code{OS_task} attribute can be used when there is @emph{no +guarantee} that interrupts are disabled at that time when the function +is entered like for, e@.g@. task functions in a multi-threading operating +system. In that case, changing the stack pointer register will be +guarded by save/clear/restore of the global interrupt enable flag. + +The differences to the @code{naked} function attrubute are: +@itemize @bullet +@item @code{naked} functions do not have a return instruction whereas +@code{OS_main} and @code{OS_task} functions will have a @code{RET} or +@code{RETI} return instruction. +@item @code{naked} functions do not set up a frame for local variables +or a frame pointer whereas @code{OS_main} and @code{OS_task} do this +as needed. +@end itemize + +@item pcs +@cindex @code{pcs} function attribute + +The @code{pcs} attribute can be used to control the calling convention +used for a function on ARM. The attribute takes an argument that specifies +the calling convention to use. + +When compiling using the AAPCS ABI (or a variant of that) then valid +values for the argument are @code{"aapcs"} and @code{"aapcs-vfp"}. In +order to use a variant other than @code{"aapcs"} then the compiler must +be permitted to use the appropriate co-processor registers (i.e., the +VFP registers must be available in order to use @code{"aapcs-vfp"}). +For example, + +@smallexample +/* Argument passed in r0, and result returned in r0+r1. */ +double f2d (float) __attribute__((pcs("aapcs"))); +@end smallexample + +Variadic functions always use the @code{"aapcs"} calling convention and +the compiler will reject attempts to specify an alternative. + +@item pure +@cindex @code{pure} function attribute +Many functions have no effects except the return value and their +return value depends only on the parameters and/or global variables. +Such a function can be subject +to common subexpression elimination and loop optimization just as an +arithmetic operator would be. These functions should be declared +with the attribute @code{pure}. For example, + +@smallexample +int square (int) __attribute__ ((pure)); +@end smallexample + +@noindent +says that the hypothetical function @code{square} is safe to call +fewer times than the program says. + +Some of common examples of pure functions are @code{strlen} or @code{memcmp}. +Interesting non-pure functions are functions with infinite loops or those +depending on volatile memory or other system resource, that may change between +two consecutive calls (such as @code{feof} in a multithreading environment). + +The attribute @code{pure} is not implemented in GCC versions earlier +than 2.96. + +@item hot +@cindex @code{hot} function attribute +The @code{hot} attribute is used to inform the compiler that a function is a +hot spot of the compiled program. The function is optimized more aggressively +and on many target it is placed into special subsection of the text section so +all hot functions appears close together improving locality. + +When profile feedback is available, via @option{-fprofile-use}, hot functions +are automatically detected and this attribute is ignored. + +The @code{hot} attribute is not implemented in GCC versions earlier +than 4.3. + +@item cold +@cindex @code{cold} function attribute +The @code{cold} attribute is used to inform the compiler that a function is +unlikely executed. The function is optimized for size rather than speed and on +many targets it is placed into special subsection of the text section so all +cold functions appears close together improving code locality of non-cold parts +of program. The paths leading to call of cold functions within code are marked +as unlikely by the branch prediction mechanism. It is thus useful to mark +functions used to handle unlikely conditions, such as @code{perror}, as cold to +improve optimization of hot functions that do call marked functions in rare +occasions. + +When profile feedback is available, via @option{-fprofile-use}, hot functions +are automatically detected and this attribute is ignored. + +The @code{cold} attribute is not implemented in GCC versions earlier than 4.3. + +@item regparm (@var{number}) +@cindex @code{regparm} attribute +@cindex functions that are passed arguments in registers on the 386 +On the Intel 386, the @code{regparm} attribute causes the compiler to +pass arguments number one to @var{number} if they are of integral type +in registers EAX, EDX, and ECX instead of on the stack. Functions that +take a variable number of arguments will continue to be passed all of their +arguments on the stack. + +Beware that on some ELF systems this attribute is unsuitable for +global functions in shared libraries with lazy binding (which is the +default). Lazy binding will send the first call via resolving code in +the loader, which might assume EAX, EDX and ECX can be clobbered, as +per the standard calling conventions. Solaris 8 is affected by this. +GNU systems with GLIBC 2.1 or higher, and FreeBSD, are believed to be +safe since the loaders there save EAX, EDX and ECX. (Lazy binding can be +disabled with the linker or the loader if desired, to avoid the +problem.) + +@item sseregparm +@cindex @code{sseregparm} attribute +On the Intel 386 with SSE support, the @code{sseregparm} attribute +causes the compiler to pass up to 3 floating point arguments in +SSE registers instead of on the stack. Functions that take a +variable number of arguments will continue to pass all of their +floating point arguments on the stack. + +@item force_align_arg_pointer +@cindex @code{force_align_arg_pointer} attribute +On the Intel x86, the @code{force_align_arg_pointer} attribute may be +applied to individual function definitions, generating an alternate +prologue and epilogue that realigns the runtime stack if necessary. +This supports mixing legacy codes that run with a 4-byte aligned stack +with modern codes that keep a 16-byte stack for SSE compatibility. + +@item resbank +@cindex @code{resbank} attribute +On the SH2A target, this attribute enables the high-speed register +saving and restoration using a register bank for @code{interrupt_handler} +routines. Saving to the bank is performed automatically after the CPU +accepts an interrupt that uses a register bank. + +The nineteen 32-bit registers comprising general register R0 to R14, +control register GBR, and system registers MACH, MACL, and PR and the +vector table address offset are saved into a register bank. Register +banks are stacked in first-in last-out (FILO) sequence. Restoration +from the bank is executed by issuing a RESBANK instruction. + +@item returns_twice +@cindex @code{returns_twice} attribute +The @code{returns_twice} attribute tells the compiler that a function may +return more than one time. The compiler will ensure that all registers +are dead before calling such a function and will emit a warning about +the variables that may be clobbered after the second return from the +function. Examples of such functions are @code{setjmp} and @code{vfork}. +The @code{longjmp}-like counterpart of such function, if any, might need +to be marked with the @code{noreturn} attribute. + +@item saveall +@cindex save all registers on the Blackfin, H8/300, H8/300H, and H8S +Use this attribute on the Blackfin, H8/300, H8/300H, and H8S to indicate that +all registers except the stack pointer should be saved in the prologue +regardless of whether they are used or not. + +@item save_volatiles +@cindex save volatile registers on the MicroBlaze +Use this attribute on the MicroBlaze to indicate that the function is +an interrupt handler. All volatile registers (in addition to non-volatile +registers) will be saved in the function prologue. If the function is a leaf +function, only volatiles used by the function are saved. A normal function +return is generated instead of a return from interrupt. + +@item section ("@var{section-name}") +@cindex @code{section} function attribute +Normally, the compiler places the code it generates in the @code{text} section. +Sometimes, however, you need additional sections, or you need certain +particular functions to appear in special sections. The @code{section} +attribute specifies that a function lives in a particular section. +For example, the declaration: + +@smallexample +extern void foobar (void) __attribute__ ((section ("bar"))); +@end smallexample + +@noindent +puts the function @code{foobar} in the @code{bar} section. + +Some file formats do not support arbitrary sections so the @code{section} +attribute is not available on all platforms. +If you need to map the entire contents of a module to a particular +section, consider using the facilities of the linker instead. + +@item sentinel +@cindex @code{sentinel} function attribute +This function attribute ensures that a parameter in a function call is +an explicit @code{NULL}. The attribute is only valid on variadic +functions. By default, the sentinel is located at position zero, the +last parameter of the function call. If an optional integer position +argument P is supplied to the attribute, the sentinel must be located at +position P counting backwards from the end of the argument list. + +@smallexample +__attribute__ ((sentinel)) +is equivalent to +__attribute__ ((sentinel(0))) +@end smallexample + +The attribute is automatically set with a position of 0 for the built-in +functions @code{execl} and @code{execlp}. The built-in function +@code{execle} has the attribute set with a position of 1. + +A valid @code{NULL} in this context is defined as zero with any pointer +type. If your system defines the @code{NULL} macro with an integer type +then you need to add an explicit cast. GCC replaces @code{stddef.h} +with a copy that redefines NULL appropriately. + +The warnings for missing or incorrect sentinels are enabled with +@option{-Wformat}. + +@item short_call +See long_call/short_call. + +@item shortcall +See longcall/shortcall. + +@item signal +@cindex signal handler functions on the AVR processors +Use this attribute on the AVR to indicate that the specified +function is a signal handler. The compiler will generate function +entry and exit sequences suitable for use in a signal handler when this +attribute is present. Interrupts will be disabled inside the function. + +@item sp_switch +Use this attribute on the SH to indicate an @code{interrupt_handler} +function should switch to an alternate stack. It expects a string +argument that names a global variable holding the address of the +alternate stack. + +@smallexample +void *alt_stack; +void f () __attribute__ ((interrupt_handler, + sp_switch ("alt_stack"))); +@end smallexample + +@item stdcall +@cindex functions that pop the argument stack on the 386 +On the Intel 386, the @code{stdcall} attribute causes the compiler to +assume that the called function will pop off the stack space used to +pass arguments, unless it takes a variable number of arguments. + +@item syscall_linkage +@cindex @code{syscall_linkage} attribute +This attribute is used to modify the IA64 calling convention by marking +all input registers as live at all function exits. This makes it possible +to restart a system call after an interrupt without having to save/restore +the input registers. This also prevents kernel data from leaking into +application code. + +@item target +@cindex @code{target} function attribute +The @code{target} attribute is used to specify that a function is to +be compiled with different target options than specified on the +command line. This can be used for instance to have functions +compiled with a different ISA (instruction set architecture) than the +default. You can also use the @samp{#pragma GCC target} pragma to set +more than one function to be compiled with specific target options. +@xref{Function Specific Option Pragmas}, for details about the +@samp{#pragma GCC target} pragma. + +For instance on a 386, you could compile one function with +@code{target("sse4.1,arch=core2")} and another with +@code{target("sse4a,arch=amdfam10")} that would be equivalent to +compiling the first function with @option{-msse4.1} and +@option{-march=core2} options, and the second function with +@option{-msse4a} and @option{-march=amdfam10} options. It is up to the +user to make sure that a function is only invoked on a machine that +supports the particular ISA it was compiled for (for example by using +@code{cpuid} on 386 to determine what feature bits and architecture +family are used). + +@smallexample +int core2_func (void) __attribute__ ((__target__ ("arch=core2"))); +int sse3_func (void) __attribute__ ((__target__ ("sse3"))); +@end smallexample + +On the 386, the following options are allowed: + +@table @samp +@item abm +@itemx no-abm +@cindex @code{target("abm")} attribute +Enable/disable the generation of the advanced bit instructions. + +@item aes +@itemx no-aes +@cindex @code{target("aes")} attribute +Enable/disable the generation of the AES instructions. + +@item mmx +@itemx no-mmx +@cindex @code{target("mmx")} attribute +Enable/disable the generation of the MMX instructions. + +@item pclmul +@itemx no-pclmul +@cindex @code{target("pclmul")} attribute +Enable/disable the generation of the PCLMUL instructions. + +@item popcnt +@itemx no-popcnt +@cindex @code{target("popcnt")} attribute +Enable/disable the generation of the POPCNT instruction. + +@item sse +@itemx no-sse +@cindex @code{target("sse")} attribute +Enable/disable the generation of the SSE instructions. + +@item sse2 +@itemx no-sse2 +@cindex @code{target("sse2")} attribute +Enable/disable the generation of the SSE2 instructions. + +@item sse3 +@itemx no-sse3 +@cindex @code{target("sse3")} attribute +Enable/disable the generation of the SSE3 instructions. + +@item sse4 +@itemx no-sse4 +@cindex @code{target("sse4")} attribute +Enable/disable the generation of the SSE4 instructions (both SSE4.1 +and SSE4.2). + +@item sse4.1 +@itemx no-sse4.1 +@cindex @code{target("sse4.1")} attribute +Enable/disable the generation of the sse4.1 instructions. + +@item sse4.2 +@itemx no-sse4.2 +@cindex @code{target("sse4.2")} attribute +Enable/disable the generation of the sse4.2 instructions. + +@item sse4a +@itemx no-sse4a +@cindex @code{target("sse4a")} attribute +Enable/disable the generation of the SSE4A instructions. + +@item fma4 +@itemx no-fma4 +@cindex @code{target("fma4")} attribute +Enable/disable the generation of the FMA4 instructions. + +@item xop +@itemx no-xop +@cindex @code{target("xop")} attribute +Enable/disable the generation of the XOP instructions. + +@item lwp +@itemx no-lwp +@cindex @code{target("lwp")} attribute +Enable/disable the generation of the LWP instructions. + +@item ssse3 +@itemx no-ssse3 +@cindex @code{target("ssse3")} attribute +Enable/disable the generation of the SSSE3 instructions. + +@item cld +@itemx no-cld +@cindex @code{target("cld")} attribute +Enable/disable the generation of the CLD before string moves. + +@item fancy-math-387 +@itemx no-fancy-math-387 +@cindex @code{target("fancy-math-387")} attribute +Enable/disable the generation of the @code{sin}, @code{cos}, and +@code{sqrt} instructions on the 387 floating point unit. + +@item fused-madd +@itemx no-fused-madd +@cindex @code{target("fused-madd")} attribute +Enable/disable the generation of the fused multiply/add instructions. + +@item ieee-fp +@itemx no-ieee-fp +@cindex @code{target("ieee-fp")} attribute +Enable/disable the generation of floating point that depends on IEEE arithmetic. + +@item inline-all-stringops +@itemx no-inline-all-stringops +@cindex @code{target("inline-all-stringops")} attribute +Enable/disable inlining of string operations. + +@item inline-stringops-dynamically +@itemx no-inline-stringops-dynamically +@cindex @code{target("inline-stringops-dynamically")} attribute +Enable/disable the generation of the inline code to do small string +operations and calling the library routines for large operations. + +@item align-stringops +@itemx no-align-stringops +@cindex @code{target("align-stringops")} attribute +Do/do not align destination of inlined string operations. + +@item recip +@itemx no-recip +@cindex @code{target("recip")} attribute +Enable/disable the generation of RCPSS, RCPPS, RSQRTSS and RSQRTPS +instructions followed an additional Newton-Raphson step instead of +doing a floating point division. + +@item arch=@var{ARCH} +@cindex @code{target("arch=@var{ARCH}")} attribute +Specify the architecture to generate code for in compiling the function. + +@item tune=@var{TUNE} +@cindex @code{target("tune=@var{TUNE}")} attribute +Specify the architecture to tune for in compiling the function. + +@item fpmath=@var{FPMATH} +@cindex @code{target("fpmath=@var{FPMATH}")} attribute +Specify which floating point unit to use. The +@code{target("fpmath=sse,387")} option must be specified as +@code{target("fpmath=sse+387")} because the comma would separate +different options. +@end table + +On the PowerPC, the following options are allowed: + +@table @samp +@item altivec +@itemx no-altivec +@cindex @code{target("altivec")} attribute +Generate code that uses (does not use) AltiVec instructions. In +32-bit code, you cannot enable Altivec instructions unless +@option{-mabi=altivec} was used on the command line. + +@item cmpb +@itemx no-cmpb +@cindex @code{target("cmpb")} attribute +Generate code that uses (does not use) the compare bytes instruction +implemented on the POWER6 processor and other processors that support +the PowerPC V2.05 architecture. + +@item dlmzb +@itemx no-dlmzb +@cindex @code{target("dlmzb")} attribute +Generate code that uses (does not use) the string-search @samp{dlmzb} +instruction on the IBM 405, 440, 464 and 476 processors. This instruction is +generated by default when targetting those processors. + +@item fprnd +@itemx no-fprnd +@cindex @code{target("fprnd")} attribute +Generate code that uses (does not use) the FP round to integer +instructions implemented on the POWER5+ processor and other processors +that support the PowerPC V2.03 architecture. + +@item hard-dfp +@itemx no-hard-dfp +@cindex @code{target("hard-dfp")} attribute +Generate code that uses (does not use) the decimal floating point +instructions implemented on some POWER processors. + +@item isel +@itemx no-isel +@cindex @code{target("isel")} attribute +Generate code that uses (does not use) ISEL instruction. + +@item mfcrf +@itemx no-mfcrf +@cindex @code{target("mfcrf")} attribute +Generate code that uses (does not use) the move from condition +register field instruction implemented on the POWER4 processor and +other processors that support the PowerPC V2.01 architecture. + +@item mfpgpr +@itemx no-mfpgpr +@cindex @code{target("mfpgpr")} attribute +Generate code that uses (does not use) the FP move to/from general +purpose register instructions implemented on the POWER6X processor and +other processors that support the extended PowerPC V2.05 architecture. + +@item mulhw +@itemx no-mulhw +@cindex @code{target("mulhw")} attribute +Generate code that uses (does not use) the half-word multiply and +multiply-accumulate instructions on the IBM 405, 440, 464 and 476 processors. +These instructions are generated by default when targetting those +processors. + +@item multiple +@itemx no-multiple +@cindex @code{target("multiple")} attribute +Generate code that uses (does not use) the load multiple word +instructions and the store multiple word instructions. + +@item update +@itemx no-update +@cindex @code{target("update")} attribute +Generate code that uses (does not use) the load or store instructions +that update the base register to the address of the calculated memory +location. + +@item popcntb +@itemx no-popcntb +@cindex @code{target("popcntb")} attribute +Generate code that uses (does not use) the popcount and double +precision FP reciprocal estimate instruction implemented on the POWER5 +processor and other processors that support the PowerPC V2.02 +architecture. + +@item popcntd +@itemx no-popcntd +@cindex @code{target("popcntd")} attribute +Generate code that uses (does not use) the popcount instruction +implemented on the POWER7 processor and other processors that support +the PowerPC V2.06 architecture. + +@item powerpc-gfxopt +@itemx no-powerpc-gfxopt +@cindex @code{target("powerpc-gfxopt")} attribute +Generate code that uses (does not use) the optional PowerPC +architecture instructions in the Graphics group, including +floating-point select. + +@item powerpc-gpopt +@itemx no-powerpc-gpopt +@cindex @code{target("powerpc-gpopt")} attribute +Generate code that uses (does not use) the optional PowerPC +architecture instructions in the General Purpose group, including +floating-point square root. + +@item recip-precision +@itemx no-recip-precision +@cindex @code{target("recip-precision")} attribute +Assume (do not assume) that the reciprocal estimate instructions +provide higher precision estimates than is mandated by the powerpc +ABI. + +@item string +@itemx no-string +@cindex @code{target("string")} attribute +Generate code that uses (does not use) the load string instructions +and the store string word instructions to save multiple registers and +do small block moves. + +@item vsx +@itemx no-vsx +@cindex @code{target("vsx")} attribute +Generate code that uses (does not use) vector/scalar (VSX) +instructions, and also enable the use of built-in functions that allow +more direct access to the VSX instruction set. In 32-bit code, you +cannot enable VSX or Altivec instructions unless +@option{-mabi=altivec} was used on the command line. + +@item friz +@itemx no-friz +@cindex @code{target("friz")} attribute +Generate (do not generate) the @code{friz} instruction when the +@option{-funsafe-math-optimizations} option is used to optimize +rounding a floating point value to 64-bit integer and back to floating +point. The @code{friz} instruction does not return the same value if +the floating point number is too large to fit in an integer. + +@item avoid-indexed-addresses +@itemx no-avoid-indexed-addresses +@cindex @code{target("avoid-indexed-addresses")} attribute +Generate code that tries to avoid (not avoid) the use of indexed load +or store instructions. + +@item paired +@itemx no-paired +@cindex @code{target("paired")} attribute +Generate code that uses (does not use) the generation of PAIRED simd +instructions. + +@item longcall +@itemx no-longcall +@cindex @code{target("longcall")} attribute +Generate code that assumes (does not assume) that all calls are far +away so that a longer more expensive calling sequence is required. + +@item cpu=@var{CPU} +@cindex @code{target("cpu=@var{CPU}")} attribute +Specify the architecture to generate code for when compiling the +function. If you select the @code{"target("cpu=power7)"} attribute when +generating 32-bit code, VSX and Altivec instructions are not generated +unless you use the @option{-mabi=altivec} option on the command line. + +@item tune=@var{TUNE} +@cindex @code{target("tune=@var{TUNE}")} attribute +Specify the architecture to tune for when compiling the function. If +you do not specify the @code{target("tune=@var{TUNE}")} attribute and +you do specify the @code{target("cpu=@var{CPU}")} attribute, +compilation will tune for the @var{CPU} architecture, and not the +default tuning specified on the command line. +@end table + +On the 386/x86_64 and PowerPC backends, you can use either multiple +strings to specify multiple options, or you can separate the option +with a comma (@code{,}). + +On the 386/x86_64 and PowerPC backends, the inliner will not inline a +function that has different target options than the caller, unless the +callee has a subset of the target options of the caller. For example +a function declared with @code{target("sse3")} can inline a function +with @code{target("sse2")}, since @code{-msse3} implies @code{-msse2}. + +The @code{target} attribute is not implemented in GCC versions earlier +than 4.4 for the i386/x86_64 and 4.6 for the PowerPC backends. It is +not currently implemented for other backends. + +@item tiny_data +@cindex tiny data section on the H8/300H and H8S +Use this attribute on the H8/300H and H8S to indicate that the specified +variable should be placed into the tiny data section. +The compiler will generate more efficient code for loads and stores +on data in the tiny data section. Note the tiny data area is limited to +slightly under 32kbytes of data. + +@item trap_exit +Use this attribute on the SH for an @code{interrupt_handler} to return using +@code{trapa} instead of @code{rte}. This attribute expects an integer +argument specifying the trap number to be used. + +@item unused +@cindex @code{unused} attribute. +This attribute, attached to a function, means that the function is meant +to be possibly unused. GCC will not produce a warning for this +function. + +@item used +@cindex @code{used} attribute. +This attribute, attached to a function, means that code must be emitted +for the function even if it appears that the function is not referenced. +This is useful, for example, when the function is referenced only in +inline assembly. + +@item version_id +@cindex @code{version_id} attribute +This IA64 HP-UX attribute, attached to a global variable or function, renames a +symbol to contain a version string, thus allowing for function level +versioning. HP-UX system header files may use version level functioning +for some system calls. + +@smallexample +extern int foo () __attribute__((version_id ("20040821"))); +@end smallexample + +Calls to @var{foo} will be mapped to calls to @var{foo@{20040821@}}. + +@item visibility ("@var{visibility_type}") +@cindex @code{visibility} attribute +This attribute affects the linkage of the declaration to which it is attached. +There are four supported @var{visibility_type} values: default, +hidden, protected or internal visibility. + +@smallexample +void __attribute__ ((visibility ("protected"))) +f () @{ /* @r{Do something.} */; @} +int i __attribute__ ((visibility ("hidden"))); +@end smallexample + +The possible values of @var{visibility_type} correspond to the +visibility settings in the ELF gABI. + +@table @dfn +@c keep this list of visibilities in alphabetical order. + +@item default +Default visibility is the normal case for the object file format. +This value is available for the visibility attribute to override other +options that may change the assumed visibility of entities. + +On ELF, default visibility means that the declaration is visible to other +modules and, in shared libraries, means that the declared entity may be +overridden. + +On Darwin, default visibility means that the declaration is visible to +other modules. + +Default visibility corresponds to ``external linkage'' in the language. + +@item hidden +Hidden visibility indicates that the entity declared will have a new +form of linkage, which we'll call ``hidden linkage''. Two +declarations of an object with hidden linkage refer to the same object +if they are in the same shared object. + +@item internal +Internal visibility is like hidden visibility, but with additional +processor specific semantics. Unless otherwise specified by the +psABI, GCC defines internal visibility to mean that a function is +@emph{never} called from another module. Compare this with hidden +functions which, while they cannot be referenced directly by other +modules, can be referenced indirectly via function pointers. By +indicating that a function cannot be called from outside the module, +GCC may for instance omit the load of a PIC register since it is known +that the calling function loaded the correct value. + +@item protected +Protected visibility is like default visibility except that it +indicates that references within the defining module will bind to the +definition in that module. That is, the declared entity cannot be +overridden by another module. + +@end table + +All visibilities are supported on many, but not all, ELF targets +(supported when the assembler supports the @samp{.visibility} +pseudo-op). Default visibility is supported everywhere. Hidden +visibility is supported on Darwin targets. + +The visibility attribute should be applied only to declarations which +would otherwise have external linkage. The attribute should be applied +consistently, so that the same entity should not be declared with +different settings of the attribute. + +In C++, the visibility attribute applies to types as well as functions +and objects, because in C++ types have linkage. A class must not have +greater visibility than its non-static data member types and bases, +and class members default to the visibility of their class. Also, a +declaration without explicit visibility is limited to the visibility +of its type. + +In C++, you can mark member functions and static member variables of a +class with the visibility attribute. This is useful if you know a +particular method or static member variable should only be used from +one shared object; then you can mark it hidden while the rest of the +class has default visibility. Care must be taken to avoid breaking +the One Definition Rule; for example, it is usually not useful to mark +an inline method as hidden without marking the whole class as hidden. + +A C++ namespace declaration can also have the visibility attribute. +This attribute applies only to the particular namespace body, not to +other definitions of the same namespace; it is equivalent to using +@samp{#pragma GCC visibility} before and after the namespace +definition (@pxref{Visibility Pragmas}). + +In C++, if a template argument has limited visibility, this +restriction is implicitly propagated to the template instantiation. +Otherwise, template instantiations and specializations default to the +visibility of their template. + +If both the template and enclosing class have explicit visibility, the +visibility from the template is used. + +@item vliw +@cindex @code{vliw} attribute +On MeP, the @code{vliw} attribute tells the compiler to emit +instructions in VLIW mode instead of core mode. Note that this +attribute is not allowed unless a VLIW coprocessor has been configured +and enabled through command line options. + +@item warn_unused_result +@cindex @code{warn_unused_result} attribute +The @code{warn_unused_result} attribute causes a warning to be emitted +if a caller of the function with this attribute does not use its +return value. This is useful for functions where not checking +the result is either a security problem or always a bug, such as +@code{realloc}. + +@smallexample +int fn () __attribute__ ((warn_unused_result)); +int foo () +@{ + if (fn () < 0) return -1; + fn (); + return 0; +@} +@end smallexample + +results in warning on line 5. + +@item weak +@cindex @code{weak} attribute +The @code{weak} attribute causes the declaration to be emitted as a weak +symbol rather than a global. This is primarily useful in defining +library functions which can be overridden in user code, though it can +also be used with non-function declarations. Weak symbols are supported +for ELF targets, and also for a.out targets when using the GNU assembler +and linker. + +@item weakref +@itemx weakref ("@var{target}") +@cindex @code{weakref} attribute +The @code{weakref} attribute marks a declaration as a weak reference. +Without arguments, it should be accompanied by an @code{alias} attribute +naming the target symbol. Optionally, the @var{target} may be given as +an argument to @code{weakref} itself. In either case, @code{weakref} +implicitly marks the declaration as @code{weak}. Without a +@var{target}, given as an argument to @code{weakref} or to @code{alias}, +@code{weakref} is equivalent to @code{weak}. + +@smallexample +static int x() __attribute__ ((weakref ("y"))); +/* is equivalent to... */ +static int x() __attribute__ ((weak, weakref, alias ("y"))); +/* and to... */ +static int x() __attribute__ ((weakref)); +static int x() __attribute__ ((alias ("y"))); +@end smallexample + +A weak reference is an alias that does not by itself require a +definition to be given for the target symbol. If the target symbol is +only referenced through weak references, then it becomes a @code{weak} +undefined symbol. If it is directly referenced, however, then such +strong references prevail, and a definition will be required for the +symbol, not necessarily in the same translation unit. + +The effect is equivalent to moving all references to the alias to a +separate translation unit, renaming the alias to the aliased symbol, +declaring it as weak, compiling the two separate translation units and +performing a reloadable link on them. + +At present, a declaration to which @code{weakref} is attached can +only be @code{static}. + +@end table + +You can specify multiple attributes in a declaration by separating them +by commas within the double parentheses or by immediately following an +attribute declaration with another attribute declaration. + +@cindex @code{#pragma}, reason for not using +@cindex pragma, reason for not using +Some people object to the @code{__attribute__} feature, suggesting that +ISO C's @code{#pragma} should be used instead. At the time +@code{__attribute__} was designed, there were two reasons for not doing +this. + +@enumerate +@item +It is impossible to generate @code{#pragma} commands from a macro. + +@item +There is no telling what the same @code{#pragma} might mean in another +compiler. +@end enumerate + +These two reasons applied to almost any application that might have been +proposed for @code{#pragma}. It was basically a mistake to use +@code{#pragma} for @emph{anything}. + +The ISO C99 standard includes @code{_Pragma}, which now allows pragmas +to be generated from macros. In addition, a @code{#pragma GCC} +namespace is now in use for GCC-specific pragmas. However, it has been +found convenient to use @code{__attribute__} to achieve a natural +attachment of attributes to their corresponding declarations, whereas +@code{#pragma GCC} is of use for constructs that do not naturally form +part of the grammar. @xref{Other Directives,,Miscellaneous +Preprocessing Directives, cpp, The GNU C Preprocessor}. + +@node Attribute Syntax +@section Attribute Syntax +@cindex attribute syntax + +This section describes the syntax with which @code{__attribute__} may be +used, and the constructs to which attribute specifiers bind, for the C +language. Some details may vary for C++ and Objective-C@. Because of +infelicities in the grammar for attributes, some forms described here +may not be successfully parsed in all cases. + +There are some problems with the semantics of attributes in C++. For +example, there are no manglings for attributes, although they may affect +code generation, so problems may arise when attributed types are used in +conjunction with templates or overloading. Similarly, @code{typeid} +does not distinguish between types with different attributes. Support +for attributes in C++ may be restricted in future to attributes on +declarations only, but not on nested declarators. + +@xref{Function Attributes}, for details of the semantics of attributes +applying to functions. @xref{Variable Attributes}, for details of the +semantics of attributes applying to variables. @xref{Type Attributes}, +for details of the semantics of attributes applying to structure, union +and enumerated types. + +An @dfn{attribute specifier} is of the form +@code{__attribute__ ((@var{attribute-list}))}. An @dfn{attribute list} +is a possibly empty comma-separated sequence of @dfn{attributes}, where +each attribute is one of the following: + +@itemize @bullet +@item +Empty. Empty attributes are ignored. + +@item +A word (which may be an identifier such as @code{unused}, or a reserved +word such as @code{const}). + +@item +A word, followed by, in parentheses, parameters for the attribute. +These parameters take one of the following forms: + +@itemize @bullet +@item +An identifier. For example, @code{mode} attributes use this form. + +@item +An identifier followed by a comma and a non-empty comma-separated list +of expressions. For example, @code{format} attributes use this form. + +@item +A possibly empty comma-separated list of expressions. For example, +@code{format_arg} attributes use this form with the list being a single +integer constant expression, and @code{alias} attributes use this form +with the list being a single string constant. +@end itemize +@end itemize + +An @dfn{attribute specifier list} is a sequence of one or more attribute +specifiers, not separated by any other tokens. + +In GNU C, an attribute specifier list may appear after the colon following a +label, other than a @code{case} or @code{default} label. The only +attribute it makes sense to use after a label is @code{unused}. This +feature is intended for code generated by programs which contains labels +that may be unused but which is compiled with @option{-Wall}. It would +not normally be appropriate to use in it human-written code, though it +could be useful in cases where the code that jumps to the label is +contained within an @code{#ifdef} conditional. GNU C++ only permits +attributes on labels if the attribute specifier is immediately +followed by a semicolon (i.e., the label applies to an empty +statement). If the semicolon is missing, C++ label attributes are +ambiguous, as it is permissible for a declaration, which could begin +with an attribute list, to be labelled in C++. Declarations cannot be +labelled in C90 or C99, so the ambiguity does not arise there. + +An attribute specifier list may appear as part of a @code{struct}, +@code{union} or @code{enum} specifier. It may go either immediately +after the @code{struct}, @code{union} or @code{enum} keyword, or after +the closing brace. The former syntax is preferred. +Where attribute specifiers follow the closing brace, they are considered +to relate to the structure, union or enumerated type defined, not to any +enclosing declaration the type specifier appears in, and the type +defined is not complete until after the attribute specifiers. +@c Otherwise, there would be the following problems: a shift/reduce +@c conflict between attributes binding the struct/union/enum and +@c binding to the list of specifiers/qualifiers; and "aligned" +@c attributes could use sizeof for the structure, but the size could be +@c changed later by "packed" attributes. + +Otherwise, an attribute specifier appears as part of a declaration, +counting declarations of unnamed parameters and type names, and relates +to that declaration (which may be nested in another declaration, for +example in the case of a parameter declaration), or to a particular declarator +within a declaration. Where an +attribute specifier is applied to a parameter declared as a function or +an array, it should apply to the function or array rather than the +pointer to which the parameter is implicitly converted, but this is not +yet correctly implemented. + +Any list of specifiers and qualifiers at the start of a declaration may +contain attribute specifiers, whether or not such a list may in that +context contain storage class specifiers. (Some attributes, however, +are essentially in the nature of storage class specifiers, and only make +sense where storage class specifiers may be used; for example, +@code{section}.) There is one necessary limitation to this syntax: the +first old-style parameter declaration in a function definition cannot +begin with an attribute specifier, because such an attribute applies to +the function instead by syntax described below (which, however, is not +yet implemented in this case). In some other cases, attribute +specifiers are permitted by this grammar but not yet supported by the +compiler. All attribute specifiers in this place relate to the +declaration as a whole. In the obsolescent usage where a type of +@code{int} is implied by the absence of type specifiers, such a list of +specifiers and qualifiers may be an attribute specifier list with no +other specifiers or qualifiers. + +At present, the first parameter in a function prototype must have some +type specifier which is not an attribute specifier; this resolves an +ambiguity in the interpretation of @code{void f(int +(__attribute__((foo)) x))}, but is subject to change. At present, if +the parentheses of a function declarator contain only attributes then +those attributes are ignored, rather than yielding an error or warning +or implying a single parameter of type int, but this is subject to +change. + +An attribute specifier list may appear immediately before a declarator +(other than the first) in a comma-separated list of declarators in a +declaration of more than one identifier using a single list of +specifiers and qualifiers. Such attribute specifiers apply +only to the identifier before whose declarator they appear. For +example, in + +@smallexample +__attribute__((noreturn)) void d0 (void), + __attribute__((format(printf, 1, 2))) d1 (const char *, ...), + d2 (void) +@end smallexample + +@noindent +the @code{noreturn} attribute applies to all the functions +declared; the @code{format} attribute only applies to @code{d1}. + +An attribute specifier list may appear immediately before the comma, +@code{=} or semicolon terminating the declaration of an identifier other +than a function definition. Such attribute specifiers apply +to the declared object or function. Where an +assembler name for an object or function is specified (@pxref{Asm +Labels}), the attribute must follow the @code{asm} +specification. + +An attribute specifier list may, in future, be permitted to appear after +the declarator in a function definition (before any old-style parameter +declarations or the function body). + +Attribute specifiers may be mixed with type qualifiers appearing inside +the @code{[]} of a parameter array declarator, in the C99 construct by +which such qualifiers are applied to the pointer to which the array is +implicitly converted. Such attribute specifiers apply to the pointer, +not to the array, but at present this is not implemented and they are +ignored. + +An attribute specifier list may appear at the start of a nested +declarator. At present, there are some limitations in this usage: the +attributes correctly apply to the declarator, but for most individual +attributes the semantics this implies are not implemented. +When attribute specifiers follow the @code{*} of a pointer +declarator, they may be mixed with any type qualifiers present. +The following describes the formal semantics of this syntax. It will make the +most sense if you are familiar with the formal specification of +declarators in the ISO C standard. + +Consider (as in C99 subclause 6.7.5 paragraph 4) a declaration @code{T +D1}, where @code{T} contains declaration specifiers that specify a type +@var{Type} (such as @code{int}) and @code{D1} is a declarator that +contains an identifier @var{ident}. The type specified for @var{ident} +for derived declarators whose type does not include an attribute +specifier is as in the ISO C standard. + +If @code{D1} has the form @code{( @var{attribute-specifier-list} D )}, +and the declaration @code{T D} specifies the type +``@var{derived-declarator-type-list} @var{Type}'' for @var{ident}, then +@code{T D1} specifies the type ``@var{derived-declarator-type-list} +@var{attribute-specifier-list} @var{Type}'' for @var{ident}. + +If @code{D1} has the form @code{* +@var{type-qualifier-and-attribute-specifier-list} D}, and the +declaration @code{T D} specifies the type +``@var{derived-declarator-type-list} @var{Type}'' for @var{ident}, then +@code{T D1} specifies the type ``@var{derived-declarator-type-list} +@var{type-qualifier-and-attribute-specifier-list} pointer to @var{Type}'' for +@var{ident}. + +For example, + +@smallexample +void (__attribute__((noreturn)) ****f) (void); +@end smallexample + +@noindent +specifies the type ``pointer to pointer to pointer to pointer to +non-returning function returning @code{void}''. As another example, + +@smallexample +char *__attribute__((aligned(8))) *f; +@end smallexample + +@noindent +specifies the type ``pointer to 8-byte-aligned pointer to @code{char}''. +Note again that this does not work with most attributes; for example, +the usage of @samp{aligned} and @samp{noreturn} attributes given above +is not yet supported. + +For compatibility with existing code written for compiler versions that +did not implement attributes on nested declarators, some laxity is +allowed in the placing of attributes. If an attribute that only applies +to types is applied to a declaration, it will be treated as applying to +the type of that declaration. If an attribute that only applies to +declarations is applied to the type of a declaration, it will be treated +as applying to that declaration; and, for compatibility with code +placing the attributes immediately before the identifier declared, such +an attribute applied to a function return type will be treated as +applying to the function type, and such an attribute applied to an array +element type will be treated as applying to the array type. If an +attribute that only applies to function types is applied to a +pointer-to-function type, it will be treated as applying to the pointer +target type; if such an attribute is applied to a function return type +that is not a pointer-to-function type, it will be treated as applying +to the function type. + +@node Function Prototypes +@section Prototypes and Old-Style Function Definitions +@cindex function prototype declarations +@cindex old-style function definitions +@cindex promotion of formal parameters + +GNU C extends ISO C to allow a function prototype to override a later +old-style non-prototype definition. Consider the following example: + +@smallexample +/* @r{Use prototypes unless the compiler is old-fashioned.} */ +#ifdef __STDC__ +#define P(x) x +#else +#define P(x) () +#endif + +/* @r{Prototype function declaration.} */ +int isroot P((uid_t)); + +/* @r{Old-style function definition.} */ +int +isroot (x) /* @r{??? lossage here ???} */ + uid_t x; +@{ + return x == 0; +@} +@end smallexample + +Suppose the type @code{uid_t} happens to be @code{short}. ISO C does +not allow this example, because subword arguments in old-style +non-prototype definitions are promoted. Therefore in this example the +function definition's argument is really an @code{int}, which does not +match the prototype argument type of @code{short}. + +This restriction of ISO C makes it hard to write code that is portable +to traditional C compilers, because the programmer does not know +whether the @code{uid_t} type is @code{short}, @code{int}, or +@code{long}. Therefore, in cases like these GNU C allows a prototype +to override a later old-style definition. More precisely, in GNU C, a +function prototype argument type overrides the argument type specified +by a later old-style definition if the former type is the same as the +latter type before promotion. Thus in GNU C the above example is +equivalent to the following: + +@smallexample +int isroot (uid_t); + +int +isroot (uid_t x) +@{ + return x == 0; +@} +@end smallexample + +@noindent +GNU C++ does not support old-style function definitions, so this +extension is irrelevant. + +@node C++ Comments +@section C++ Style Comments +@cindex @code{//} +@cindex C++ comments +@cindex comments, C++ style + +In GNU C, you may use C++ style comments, which start with @samp{//} and +continue until the end of the line. Many other C implementations allow +such comments, and they are included in the 1999 C standard. However, +C++ style comments are not recognized if you specify an @option{-std} +option specifying a version of ISO C before C99, or @option{-ansi} +(equivalent to @option{-std=c90}). + +@node Dollar Signs +@section Dollar Signs in Identifier Names +@cindex $ +@cindex dollar signs in identifier names +@cindex identifier names, dollar signs in + +In GNU C, you may normally use dollar signs in identifier names. +This is because many traditional C implementations allow such identifiers. +However, dollar signs in identifiers are not supported on a few target +machines, typically because the target assembler does not allow them. + +@node Character Escapes +@section The Character @key{ESC} in Constants + +You can use the sequence @samp{\e} in a string or character constant to +stand for the ASCII character @key{ESC}. + +@node Variable Attributes +@section Specifying Attributes of Variables +@cindex attribute of variables +@cindex variable attributes + +The keyword @code{__attribute__} allows you to specify special +attributes of variables or structure fields. This keyword is followed +by an attribute specification inside double parentheses. Some +attributes are currently defined generically for variables. +Other attributes are defined for variables on particular target +systems. Other attributes are available for functions +(@pxref{Function Attributes}) and for types (@pxref{Type Attributes}). +Other front ends might define more attributes +(@pxref{C++ Extensions,,Extensions to the C++ Language}). + +You may also specify attributes with @samp{__} preceding and following +each keyword. This allows you to use them in header files without +being concerned about a possible macro of the same name. For example, +you may use @code{__aligned__} instead of @code{aligned}. + +@xref{Attribute Syntax}, for details of the exact syntax for using +attributes. + +@table @code +@cindex @code{aligned} attribute +@item aligned (@var{alignment}) +This attribute specifies a minimum alignment for the variable or +structure field, measured in bytes. For example, the declaration: + +@smallexample +int x __attribute__ ((aligned (16))) = 0; +@end smallexample + +@noindent +causes the compiler to allocate the global variable @code{x} on a +16-byte boundary. On a 68040, this could be used in conjunction with +an @code{asm} expression to access the @code{move16} instruction which +requires 16-byte aligned operands. + +You can also specify the alignment of structure fields. For example, to +create a double-word aligned @code{int} pair, you could write: + +@smallexample +struct foo @{ int x[2] __attribute__ ((aligned (8))); @}; +@end smallexample + +@noindent +This is an alternative to creating a union with a @code{double} member +that forces the union to be double-word aligned. + +As in the preceding examples, you can explicitly specify the alignment +(in bytes) that you wish the compiler to use for a given variable or +structure field. Alternatively, you can leave out the alignment factor +and just ask the compiler to align a variable or field to the +default alignment for the target architecture you are compiling for. +The default alignment is sufficient for all scalar types, but may not be +enough for all vector types on a target which supports vector operations. +The default alignment is fixed for a particular target ABI. + +Gcc also provides a target specific macro @code{__BIGGEST_ALIGNMENT__}, +which is the largest alignment ever used for any data type on the +target machine you are compiling for. For example, you could write: + +@smallexample +short array[3] __attribute__ ((aligned (__BIGGEST_ALIGNMENT__))); +@end smallexample + +The compiler automatically sets the alignment for the declared +variable or field to @code{__BIGGEST_ALIGNMENT__}. Doing this can +often make copy operations more efficient, because the compiler can +use whatever instructions copy the biggest chunks of memory when +performing copies to or from the variables or fields that you have +aligned this way. Note that the value of @code{__BIGGEST_ALIGNMENT__} +may change depending on command line options. + +When used on a struct, or struct member, the @code{aligned} attribute can +only increase the alignment; in order to decrease it, the @code{packed} +attribute must be specified as well. When used as part of a typedef, the +@code{aligned} attribute can both increase and decrease alignment, and +specifying the @code{packed} attribute will generate a warning. + +Note that the effectiveness of @code{aligned} attributes may be limited +by inherent limitations in your linker. On many systems, the linker is +only able to arrange for variables to be aligned up to a certain maximum +alignment. (For some linkers, the maximum supported alignment may +be very very small.) If your linker is only able to align variables +up to a maximum of 8 byte alignment, then specifying @code{aligned(16)} +in an @code{__attribute__} will still only provide you with 8 byte +alignment. See your linker documentation for further information. + +The @code{aligned} attribute can also be used for functions +(@pxref{Function Attributes}.) + +@item cleanup (@var{cleanup_function}) +@cindex @code{cleanup} attribute +The @code{cleanup} attribute runs a function when the variable goes +out of scope. This attribute can only be applied to auto function +scope variables; it may not be applied to parameters or variables +with static storage duration. The function must take one parameter, +a pointer to a type compatible with the variable. The return value +of the function (if any) is ignored. + +If @option{-fexceptions} is enabled, then @var{cleanup_function} +will be run during the stack unwinding that happens during the +processing of the exception. Note that the @code{cleanup} attribute +does not allow the exception to be caught, only to perform an action. +It is undefined what happens if @var{cleanup_function} does not +return normally. + +@item common +@itemx nocommon +@cindex @code{common} attribute +@cindex @code{nocommon} attribute +@opindex fcommon +@opindex fno-common +The @code{common} attribute requests GCC to place a variable in +``common'' storage. The @code{nocommon} attribute requests the +opposite---to allocate space for it directly. + +These attributes override the default chosen by the +@option{-fno-common} and @option{-fcommon} flags respectively. + +@item deprecated +@itemx deprecated (@var{msg}) +@cindex @code{deprecated} attribute +The @code{deprecated} attribute results in a warning if the variable +is used anywhere in the source file. This is useful when identifying +variables that are expected to be removed in a future version of a +program. The warning also includes the location of the declaration +of the deprecated variable, to enable users to easily find further +information about why the variable is deprecated, or what they should +do instead. Note that the warning only occurs for uses: + +@smallexample +extern int old_var __attribute__ ((deprecated)); +extern int old_var; +int new_fn () @{ return old_var; @} +@end smallexample + +results in a warning on line 3 but not line 2. The optional msg +argument, which must be a string, will be printed in the warning if +present. + +The @code{deprecated} attribute can also be used for functions and +types (@pxref{Function Attributes}, @pxref{Type Attributes}.) + +@item mode (@var{mode}) +@cindex @code{mode} attribute +This attribute specifies the data type for the declaration---whichever +type corresponds to the mode @var{mode}. This in effect lets you +request an integer or floating point type according to its width. + +You may also specify a mode of @samp{byte} or @samp{__byte__} to +indicate the mode corresponding to a one-byte integer, @samp{word} or +@samp{__word__} for the mode of a one-word integer, and @samp{pointer} +or @samp{__pointer__} for the mode used to represent pointers. + +@item packed +@cindex @code{packed} attribute +The @code{packed} attribute specifies that a variable or structure field +should have the smallest possible alignment---one byte for a variable, +and one bit for a field, unless you specify a larger value with the +@code{aligned} attribute. + +Here is a structure in which the field @code{x} is packed, so that it +immediately follows @code{a}: + +@smallexample +struct foo +@{ + char a; + int x[2] __attribute__ ((packed)); +@}; +@end smallexample + +@emph{Note:} The 4.1, 4.2 and 4.3 series of GCC ignore the +@code{packed} attribute on bit-fields of type @code{char}. This has +been fixed in GCC 4.4 but the change can lead to differences in the +structure layout. See the documentation of +@option{-Wpacked-bitfield-compat} for more information. + +@item section ("@var{section-name}") +@cindex @code{section} variable attribute +Normally, the compiler places the objects it generates in sections like +@code{data} and @code{bss}. Sometimes, however, you need additional sections, +or you need certain particular variables to appear in special sections, +for example to map to special hardware. The @code{section} +attribute specifies that a variable (or function) lives in a particular +section. For example, this small program uses several specific section names: + +@smallexample +struct duart a __attribute__ ((section ("DUART_A"))) = @{ 0 @}; +struct duart b __attribute__ ((section ("DUART_B"))) = @{ 0 @}; +char stack[10000] __attribute__ ((section ("STACK"))) = @{ 0 @}; +int init_data __attribute__ ((section ("INITDATA"))); + +main() +@{ + /* @r{Initialize stack pointer} */ + init_sp (stack + sizeof (stack)); + + /* @r{Initialize initialized data} */ + memcpy (&init_data, &data, &edata - &data); + + /* @r{Turn on the serial ports} */ + init_duart (&a); + init_duart (&b); +@} +@end smallexample + +@noindent +Use the @code{section} attribute with +@emph{global} variables and not @emph{local} variables, +as shown in the example. + +You may use the @code{section} attribute with initialized or +uninitialized global variables but the linker requires +each object be defined once, with the exception that uninitialized +variables tentatively go in the @code{common} (or @code{bss}) section +and can be multiply ``defined''. Using the @code{section} attribute +will change what section the variable goes into and may cause the +linker to issue an error if an uninitialized variable has multiple +definitions. You can force a variable to be initialized with the +@option{-fno-common} flag or the @code{nocommon} attribute. + +Some file formats do not support arbitrary sections so the @code{section} +attribute is not available on all platforms. +If you need to map the entire contents of a module to a particular +section, consider using the facilities of the linker instead. + +@item shared +@cindex @code{shared} variable attribute +On Microsoft Windows, in addition to putting variable definitions in a named +section, the section can also be shared among all running copies of an +executable or DLL@. For example, this small program defines shared data +by putting it in a named section @code{shared} and marking the section +shareable: + +@smallexample +int foo __attribute__((section ("shared"), shared)) = 0; + +int +main() +@{ + /* @r{Read and write foo. All running + copies see the same value.} */ + return 0; +@} +@end smallexample + +@noindent +You may only use the @code{shared} attribute along with @code{section} +attribute with a fully initialized global definition because of the way +linkers work. See @code{section} attribute for more information. + +The @code{shared} attribute is only available on Microsoft Windows@. + +@item tls_model ("@var{tls_model}") +@cindex @code{tls_model} attribute +The @code{tls_model} attribute sets thread-local storage model +(@pxref{Thread-Local}) of a particular @code{__thread} variable, +overriding @option{-ftls-model=} command-line switch on a per-variable +basis. +The @var{tls_model} argument should be one of @code{global-dynamic}, +@code{local-dynamic}, @code{initial-exec} or @code{local-exec}. + +Not all targets support this attribute. + +@item unused +This attribute, attached to a variable, means that the variable is meant +to be possibly unused. GCC will not produce a warning for this +variable. + +@item used +This attribute, attached to a variable, means that the variable must be +emitted even if it appears that the variable is not referenced. + +@item vector_size (@var{bytes}) +This attribute specifies the vector size for the variable, measured in +bytes. For example, the declaration: + +@smallexample +int foo __attribute__ ((vector_size (16))); +@end smallexample + +@noindent +causes the compiler to set the mode for @code{foo}, to be 16 bytes, +divided into @code{int} sized units. Assuming a 32-bit int (a vector of +4 units of 4 bytes), the corresponding mode of @code{foo} will be V4SI@. + +This attribute is only applicable to integral and float scalars, +although arrays, pointers, and function return values are allowed in +conjunction with this construct. + +Aggregates with this attribute are invalid, even if they are of the same +size as a corresponding scalar. For example, the declaration: + +@smallexample +struct S @{ int a; @}; +struct S __attribute__ ((vector_size (16))) foo; +@end smallexample + +@noindent +is invalid even if the size of the structure is the same as the size of +the @code{int}. + +@item selectany +The @code{selectany} attribute causes an initialized global variable to +have link-once semantics. When multiple definitions of the variable are +encountered by the linker, the first is selected and the remainder are +discarded. Following usage by the Microsoft compiler, the linker is told +@emph{not} to warn about size or content differences of the multiple +definitions. + +Although the primary usage of this attribute is for POD types, the +attribute can also be applied to global C++ objects that are initialized +by a constructor. In this case, the static initialization and destruction +code for the object is emitted in each translation defining the object, +but the calls to the constructor and destructor are protected by a +link-once guard variable. + +The @code{selectany} attribute is only available on Microsoft Windows +targets. You can use @code{__declspec (selectany)} as a synonym for +@code{__attribute__ ((selectany))} for compatibility with other +compilers. + +@item weak +The @code{weak} attribute is described in @ref{Function Attributes}. + +@item dllimport +The @code{dllimport} attribute is described in @ref{Function Attributes}. + +@item dllexport +The @code{dllexport} attribute is described in @ref{Function Attributes}. + +@end table + +@subsection AVR Variable Attributes + +@table @code +@item progmem +@cindex @code{progmem} AVR variable attribute +The @code{progmem} attribute is used on the AVR to place data in the program +memory address space (flash). This is accomplished by putting +respective variables into a section whose name starts with @code{.progmem}. + +AVR is a Harvard architecture processor and data and reas only data +normally resides in the data memory address space (RAM). +@end table + +@subsection Blackfin Variable Attributes + +Three attributes are currently defined for the Blackfin. + +@table @code +@item l1_data +@itemx l1_data_A +@itemx l1_data_B +@cindex @code{l1_data} variable attribute +@cindex @code{l1_data_A} variable attribute +@cindex @code{l1_data_B} variable attribute +Use these attributes on the Blackfin to place the variable into L1 Data SRAM. +Variables with @code{l1_data} attribute will be put into the specific section +named @code{.l1.data}. Those with @code{l1_data_A} attribute will be put into +the specific section named @code{.l1.data.A}. Those with @code{l1_data_B} +attribute will be put into the specific section named @code{.l1.data.B}. + +@item l2 +@cindex @code{l2} variable attribute +Use this attribute on the Blackfin to place the variable into L2 SRAM. +Variables with @code{l2} attribute will be put into the specific section +named @code{.l2.data}. +@end table + +@subsection M32R/D Variable Attributes + +One attribute is currently defined for the M32R/D@. + +@table @code +@item model (@var{model-name}) +@cindex variable addressability on the M32R/D +Use this attribute on the M32R/D to set the addressability of an object. +The identifier @var{model-name} is one of @code{small}, @code{medium}, +or @code{large}, representing each of the code models. + +Small model objects live in the lower 16MB of memory (so that their +addresses can be loaded with the @code{ld24} instruction). + +Medium and large model objects may live anywhere in the 32-bit address space +(the compiler will generate @code{seth/add3} instructions to load their +addresses). +@end table + +@anchor{MeP Variable Attributes} +@subsection MeP Variable Attributes + +The MeP target has a number of addressing modes and busses. The +@code{near} space spans the standard memory space's first 16 megabytes +(24 bits). The @code{far} space spans the entire 32-bit memory space. +The @code{based} space is a 128 byte region in the memory space which +is addressed relative to the @code{$tp} register. The @code{tiny} +space is a 65536 byte region relative to the @code{$gp} register. In +addition to these memory regions, the MeP target has a separate 16-bit +control bus which is specified with @code{cb} attributes. + +@table @code + +@item based +Any variable with the @code{based} attribute will be assigned to the +@code{.based} section, and will be accessed with relative to the +@code{$tp} register. + +@item tiny +Likewise, the @code{tiny} attribute assigned variables to the +@code{.tiny} section, relative to the @code{$gp} register. + +@item near +Variables with the @code{near} attribute are assumed to have addresses +that fit in a 24-bit addressing mode. This is the default for large +variables (@code{-mtiny=4} is the default) but this attribute can +override @code{-mtiny=} for small variables, or override @code{-ml}. + +@item far +Variables with the @code{far} attribute are addressed using a full +32-bit address. Since this covers the entire memory space, this +allows modules to make no assumptions about where variables might be +stored. + +@item io +@itemx io (@var{addr}) +Variables with the @code{io} attribute are used to address +memory-mapped peripherals. If an address is specified, the variable +is assigned that address, else it is not assigned an address (it is +assumed some other module will assign an address). Example: + +@example +int timer_count __attribute__((io(0x123))); +@end example + +@item cb +@itemx cb (@var{addr}) +Variables with the @code{cb} attribute are used to access the control +bus, using special instructions. @code{addr} indicates the control bus +address. Example: + +@example +int cpu_clock __attribute__((cb(0x123))); +@end example + +@end table + +@anchor{i386 Variable Attributes} +@subsection i386 Variable Attributes + +Two attributes are currently defined for i386 configurations: +@code{ms_struct} and @code{gcc_struct} + +@table @code +@item ms_struct +@itemx gcc_struct +@cindex @code{ms_struct} attribute +@cindex @code{gcc_struct} attribute + +If @code{packed} is used on a structure, or if bit-fields are used +it may be that the Microsoft ABI packs them differently +than GCC would normally pack them. Particularly when moving packed +data between functions compiled with GCC and the native Microsoft compiler +(either via function call or as data in a file), it may be necessary to access +either format. + +Currently @option{-m[no-]ms-bitfields} is provided for the Microsoft Windows X86 +compilers to match the native Microsoft compiler. + +The Microsoft structure layout algorithm is fairly simple with the exception +of the bitfield packing: + +The padding and alignment of members of structures and whether a bit field +can straddle a storage-unit boundary + +@enumerate +@item Structure members are stored sequentially in the order in which they are +declared: the first member has the lowest memory address and the last member +the highest. + +@item Every data object has an alignment-requirement. The alignment-requirement +for all data except structures, unions, and arrays is either the size of the +object or the current packing size (specified with either the aligned attribute +or the pack pragma), whichever is less. For structures, unions, and arrays, +the alignment-requirement is the largest alignment-requirement of its members. +Every object is allocated an offset so that: + +offset % alignment-requirement == 0 + +@item Adjacent bit fields are packed into the same 1-, 2-, or 4-byte allocation +unit if the integral types are the same size and if the next bit field fits +into the current allocation unit without crossing the boundary imposed by the +common alignment requirements of the bit fields. +@end enumerate + +Handling of zero-length bitfields: + +MSVC interprets zero-length bitfields in the following ways: + +@enumerate +@item If a zero-length bitfield is inserted between two bitfields that would +normally be coalesced, the bitfields will not be coalesced. + +For example: + +@smallexample +struct + @{ + unsigned long bf_1 : 12; + unsigned long : 0; + unsigned long bf_2 : 12; + @} t1; +@end smallexample + +The size of @code{t1} would be 8 bytes with the zero-length bitfield. If the +zero-length bitfield were removed, @code{t1}'s size would be 4 bytes. + +@item If a zero-length bitfield is inserted after a bitfield, @code{foo}, and the +alignment of the zero-length bitfield is greater than the member that follows it, +@code{bar}, @code{bar} will be aligned as the type of the zero-length bitfield. + +For example: + +@smallexample +struct + @{ + char foo : 4; + short : 0; + char bar; + @} t2; + +struct + @{ + char foo : 4; + short : 0; + double bar; + @} t3; +@end smallexample + +For @code{t2}, @code{bar} will be placed at offset 2, rather than offset 1. +Accordingly, the size of @code{t2} will be 4. For @code{t3}, the zero-length +bitfield will not affect the alignment of @code{bar} or, as a result, the size +of the structure. + +Taking this into account, it is important to note the following: + +@enumerate +@item If a zero-length bitfield follows a normal bitfield, the type of the +zero-length bitfield may affect the alignment of the structure as whole. For +example, @code{t2} has a size of 4 bytes, since the zero-length bitfield follows a +normal bitfield, and is of type short. + +@item Even if a zero-length bitfield is not followed by a normal bitfield, it may +still affect the alignment of the structure: + +@smallexample +struct + @{ + char foo : 6; + long : 0; + @} t4; +@end smallexample + +Here, @code{t4} will take up 4 bytes. +@end enumerate + +@item Zero-length bitfields following non-bitfield members are ignored: + +@smallexample +struct + @{ + char foo; + long : 0; + char bar; + @} t5; +@end smallexample + +Here, @code{t5} will take up 2 bytes. +@end enumerate +@end table + +@subsection PowerPC Variable Attributes + +Three attributes currently are defined for PowerPC configurations: +@code{altivec}, @code{ms_struct} and @code{gcc_struct}. + +For full documentation of the struct attributes please see the +documentation in @ref{i386 Variable Attributes}. + +For documentation of @code{altivec} attribute please see the +documentation in @ref{PowerPC Type Attributes}. + +@subsection SPU Variable Attributes + +The SPU supports the @code{spu_vector} attribute for variables. For +documentation of this attribute please see the documentation in +@ref{SPU Type Attributes}. + +@subsection Xstormy16 Variable Attributes + +One attribute is currently defined for xstormy16 configurations: +@code{below100}. + +@table @code +@item below100 +@cindex @code{below100} attribute + +If a variable has the @code{below100} attribute (@code{BELOW100} is +allowed also), GCC will place the variable in the first 0x100 bytes of +memory and use special opcodes to access it. Such variables will be +placed in either the @code{.bss_below100} section or the +@code{.data_below100} section. + +@end table + +@node Type Attributes +@section Specifying Attributes of Types +@cindex attribute of types +@cindex type attributes + +The keyword @code{__attribute__} allows you to specify special +attributes of @code{struct} and @code{union} types when you define +such types. This keyword is followed by an attribute specification +inside double parentheses. Seven attributes are currently defined for +types: @code{aligned}, @code{packed}, @code{transparent_union}, +@code{unused}, @code{deprecated}, @code{visibility}, and +@code{may_alias}. Other attributes are defined for functions +(@pxref{Function Attributes}) and for variables (@pxref{Variable +Attributes}). + +You may also specify any one of these attributes with @samp{__} +preceding and following its keyword. This allows you to use these +attributes in header files without being concerned about a possible +macro of the same name. For example, you may use @code{__aligned__} +instead of @code{aligned}. + +You may specify type attributes in an enum, struct or union type +declaration or definition, or for other types in a @code{typedef} +declaration. + +For an enum, struct or union type, you may specify attributes either +between the enum, struct or union tag and the name of the type, or +just past the closing curly brace of the @emph{definition}. The +former syntax is preferred. + +@xref{Attribute Syntax}, for details of the exact syntax for using +attributes. + +@table @code +@cindex @code{aligned} attribute +@item aligned (@var{alignment}) +This attribute specifies a minimum alignment (in bytes) for variables +of the specified type. For example, the declarations: + +@smallexample +struct S @{ short f[3]; @} __attribute__ ((aligned (8))); +typedef int more_aligned_int __attribute__ ((aligned (8))); +@end smallexample + +@noindent +force the compiler to insure (as far as it can) that each variable whose +type is @code{struct S} or @code{more_aligned_int} will be allocated and +aligned @emph{at least} on a 8-byte boundary. On a SPARC, having all +variables of type @code{struct S} aligned to 8-byte boundaries allows +the compiler to use the @code{ldd} and @code{std} (doubleword load and +store) instructions when copying one variable of type @code{struct S} to +another, thus improving run-time efficiency. + +Note that the alignment of any given @code{struct} or @code{union} type +is required by the ISO C standard to be at least a perfect multiple of +the lowest common multiple of the alignments of all of the members of +the @code{struct} or @code{union} in question. This means that you @emph{can} +effectively adjust the alignment of a @code{struct} or @code{union} +type by attaching an @code{aligned} attribute to any one of the members +of such a type, but the notation illustrated in the example above is a +more obvious, intuitive, and readable way to request the compiler to +adjust the alignment of an entire @code{struct} or @code{union} type. + +As in the preceding example, you can explicitly specify the alignment +(in bytes) that you wish the compiler to use for a given @code{struct} +or @code{union} type. Alternatively, you can leave out the alignment factor +and just ask the compiler to align a type to the maximum +useful alignment for the target machine you are compiling for. For +example, you could write: + +@smallexample +struct S @{ short f[3]; @} __attribute__ ((aligned)); +@end smallexample + +Whenever you leave out the alignment factor in an @code{aligned} +attribute specification, the compiler automatically sets the alignment +for the type to the largest alignment which is ever used for any data +type on the target machine you are compiling for. Doing this can often +make copy operations more efficient, because the compiler can use +whatever instructions copy the biggest chunks of memory when performing +copies to or from the variables which have types that you have aligned +this way. + +In the example above, if the size of each @code{short} is 2 bytes, then +the size of the entire @code{struct S} type is 6 bytes. The smallest +power of two which is greater than or equal to that is 8, so the +compiler sets the alignment for the entire @code{struct S} type to 8 +bytes. + +Note that although you can ask the compiler to select a time-efficient +alignment for a given type and then declare only individual stand-alone +objects of that type, the compiler's ability to select a time-efficient +alignment is primarily useful only when you plan to create arrays of +variables having the relevant (efficiently aligned) type. If you +declare or use arrays of variables of an efficiently-aligned type, then +it is likely that your program will also be doing pointer arithmetic (or +subscripting, which amounts to the same thing) on pointers to the +relevant type, and the code that the compiler generates for these +pointer arithmetic operations will often be more efficient for +efficiently-aligned types than for other types. + +The @code{aligned} attribute can only increase the alignment; but you +can decrease it by specifying @code{packed} as well. See below. + +Note that the effectiveness of @code{aligned} attributes may be limited +by inherent limitations in your linker. On many systems, the linker is +only able to arrange for variables to be aligned up to a certain maximum +alignment. (For some linkers, the maximum supported alignment may +be very very small.) If your linker is only able to align variables +up to a maximum of 8 byte alignment, then specifying @code{aligned(16)} +in an @code{__attribute__} will still only provide you with 8 byte +alignment. See your linker documentation for further information. + +@item packed +This attribute, attached to @code{struct} or @code{union} type +definition, specifies that each member (other than zero-width bitfields) +of the structure or union is placed to minimize the memory required. When +attached to an @code{enum} definition, it indicates that the smallest +integral type should be used. + +@opindex fshort-enums +Specifying this attribute for @code{struct} and @code{union} types is +equivalent to specifying the @code{packed} attribute on each of the +structure or union members. Specifying the @option{-fshort-enums} +flag on the line is equivalent to specifying the @code{packed} +attribute on all @code{enum} definitions. + +In the following example @code{struct my_packed_struct}'s members are +packed closely together, but the internal layout of its @code{s} member +is not packed---to do that, @code{struct my_unpacked_struct} would need to +be packed too. + +@smallexample +struct my_unpacked_struct + @{ + char c; + int i; + @}; + +struct __attribute__ ((__packed__)) my_packed_struct + @{ + char c; + int i; + struct my_unpacked_struct s; + @}; +@end smallexample + +You may only specify this attribute on the definition of an @code{enum}, +@code{struct} or @code{union}, not on a @code{typedef} which does not +also define the enumerated type, structure or union. + +@item transparent_union +This attribute, attached to a @code{union} type definition, indicates +that any function parameter having that union type causes calls to that +function to be treated in a special way. + +First, the argument corresponding to a transparent union type can be of +any type in the union; no cast is required. Also, if the union contains +a pointer type, the corresponding argument can be a null pointer +constant or a void pointer expression; and if the union contains a void +pointer type, the corresponding argument can be any pointer expression. +If the union member type is a pointer, qualifiers like @code{const} on +the referenced type must be respected, just as with normal pointer +conversions. + +Second, the argument is passed to the function using the calling +conventions of the first member of the transparent union, not the calling +conventions of the union itself. All members of the union must have the +same machine representation; this is necessary for this argument passing +to work properly. + +Transparent unions are designed for library functions that have multiple +interfaces for compatibility reasons. For example, suppose the +@code{wait} function must accept either a value of type @code{int *} to +comply with Posix, or a value of type @code{union wait *} to comply with +the 4.1BSD interface. If @code{wait}'s parameter were @code{void *}, +@code{wait} would accept both kinds of arguments, but it would also +accept any other pointer type and this would make argument type checking +less useful. Instead, @code{} might define the interface +as follows: + +@smallexample +typedef union __attribute__ ((__transparent_union__)) + @{ + int *__ip; + union wait *__up; + @} wait_status_ptr_t; + +pid_t wait (wait_status_ptr_t); +@end smallexample + +This interface allows either @code{int *} or @code{union wait *} +arguments to be passed, using the @code{int *} calling convention. +The program can call @code{wait} with arguments of either type: + +@smallexample +int w1 () @{ int w; return wait (&w); @} +int w2 () @{ union wait w; return wait (&w); @} +@end smallexample + +With this interface, @code{wait}'s implementation might look like this: + +@smallexample +pid_t wait (wait_status_ptr_t p) +@{ + return waitpid (-1, p.__ip, 0); +@} +@end smallexample + +@item unused +When attached to a type (including a @code{union} or a @code{struct}), +this attribute means that variables of that type are meant to appear +possibly unused. GCC will not produce a warning for any variables of +that type, even if the variable appears to do nothing. This is often +the case with lock or thread classes, which are usually defined and then +not referenced, but contain constructors and destructors that have +nontrivial bookkeeping functions. + +@item deprecated +@itemx deprecated (@var{msg}) +The @code{deprecated} attribute results in a warning if the type +is used anywhere in the source file. This is useful when identifying +types that are expected to be removed in a future version of a program. +If possible, the warning also includes the location of the declaration +of the deprecated type, to enable users to easily find further +information about why the type is deprecated, or what they should do +instead. Note that the warnings only occur for uses and then only +if the type is being applied to an identifier that itself is not being +declared as deprecated. + +@smallexample +typedef int T1 __attribute__ ((deprecated)); +T1 x; +typedef T1 T2; +T2 y; +typedef T1 T3 __attribute__ ((deprecated)); +T3 z __attribute__ ((deprecated)); +@end smallexample + +results in a warning on line 2 and 3 but not lines 4, 5, or 6. No +warning is issued for line 4 because T2 is not explicitly +deprecated. Line 5 has no warning because T3 is explicitly +deprecated. Similarly for line 6. The optional msg +argument, which must be a string, will be printed in the warning if +present. + +The @code{deprecated} attribute can also be used for functions and +variables (@pxref{Function Attributes}, @pxref{Variable Attributes}.) + +@item may_alias +Accesses through pointers to types with this attribute are not subject +to type-based alias analysis, but are instead assumed to be able to alias +any other type of objects. In the context of 6.5/7 an lvalue expression +dereferencing such a pointer is treated like having a character type. +See @option{-fstrict-aliasing} for more information on aliasing issues. +This extension exists to support some vector APIs, in which pointers to +one vector type are permitted to alias pointers to a different vector type. + +Note that an object of a type with this attribute does not have any +special semantics. + +Example of use: + +@smallexample +typedef short __attribute__((__may_alias__)) short_a; + +int +main (void) +@{ + int a = 0x12345678; + short_a *b = (short_a *) &a; + + b[1] = 0; + + if (a == 0x12345678) + abort(); + + exit(0); +@} +@end smallexample + +If you replaced @code{short_a} with @code{short} in the variable +declaration, the above program would abort when compiled with +@option{-fstrict-aliasing}, which is on by default at @option{-O2} or +above in recent GCC versions. + +@item visibility +In C++, attribute visibility (@pxref{Function Attributes}) can also be +applied to class, struct, union and enum types. Unlike other type +attributes, the attribute must appear between the initial keyword and +the name of the type; it cannot appear after the body of the type. + +Note that the type visibility is applied to vague linkage entities +associated with the class (vtable, typeinfo node, etc.). In +particular, if a class is thrown as an exception in one shared object +and caught in another, the class must have default visibility. +Otherwise the two shared objects will be unable to use the same +typeinfo node and exception handling will break. + +@end table + +@subsection ARM Type Attributes + +On those ARM targets that support @code{dllimport} (such as Symbian +OS), you can use the @code{notshared} attribute to indicate that the +virtual table and other similar data for a class should not be +exported from a DLL@. For example: + +@smallexample +class __declspec(notshared) C @{ +public: + __declspec(dllimport) C(); + virtual void f(); +@} + +__declspec(dllexport) +C::C() @{@} +@end smallexample + +In this code, @code{C::C} is exported from the current DLL, but the +virtual table for @code{C} is not exported. (You can use +@code{__attribute__} instead of @code{__declspec} if you prefer, but +most Symbian OS code uses @code{__declspec}.) + +@anchor{MeP Type Attributes} +@subsection MeP Type Attributes + +Many of the MeP variable attributes may be applied to types as well. +Specifically, the @code{based}, @code{tiny}, @code{near}, and +@code{far} attributes may be applied to either. The @code{io} and +@code{cb} attributes may not be applied to types. + +@anchor{i386 Type Attributes} +@subsection i386 Type Attributes + +Two attributes are currently defined for i386 configurations: +@code{ms_struct} and @code{gcc_struct}. + +@table @code + +@item ms_struct +@itemx gcc_struct +@cindex @code{ms_struct} +@cindex @code{gcc_struct} + +If @code{packed} is used on a structure, or if bit-fields are used +it may be that the Microsoft ABI packs them differently +than GCC would normally pack them. Particularly when moving packed +data between functions compiled with GCC and the native Microsoft compiler +(either via function call or as data in a file), it may be necessary to access +either format. + +Currently @option{-m[no-]ms-bitfields} is provided for the Microsoft Windows X86 +compilers to match the native Microsoft compiler. +@end table + +To specify multiple attributes, separate them by commas within the +double parentheses: for example, @samp{__attribute__ ((aligned (16), +packed))}. + +@anchor{PowerPC Type Attributes} +@subsection PowerPC Type Attributes + +Three attributes currently are defined for PowerPC configurations: +@code{altivec}, @code{ms_struct} and @code{gcc_struct}. + +For full documentation of the @code{ms_struct} and @code{gcc_struct} +attributes please see the documentation in @ref{i386 Type Attributes}. + +The @code{altivec} attribute allows one to declare AltiVec vector data +types supported by the AltiVec Programming Interface Manual. The +attribute requires an argument to specify one of three vector types: +@code{vector__}, @code{pixel__} (always followed by unsigned short), +and @code{bool__} (always followed by unsigned). + +@smallexample +__attribute__((altivec(vector__))) +__attribute__((altivec(pixel__))) unsigned short +__attribute__((altivec(bool__))) unsigned +@end smallexample + +These attributes mainly are intended to support the @code{__vector}, +@code{__pixel}, and @code{__bool} AltiVec keywords. + +@anchor{SPU Type Attributes} +@subsection SPU Type Attributes + +The SPU supports the @code{spu_vector} attribute for types. This attribute +allows one to declare vector data types supported by the Sony/Toshiba/IBM SPU +Language Extensions Specification. It is intended to support the +@code{__vector} keyword. + +@node Alignment +@section Inquiring on Alignment of Types or Variables +@cindex alignment +@cindex type alignment +@cindex variable alignment + +The keyword @code{__alignof__} allows you to inquire about how an object +is aligned, or the minimum alignment usually required by a type. Its +syntax is just like @code{sizeof}. + +For example, if the target machine requires a @code{double} value to be +aligned on an 8-byte boundary, then @code{__alignof__ (double)} is 8. +This is true on many RISC machines. On more traditional machine +designs, @code{__alignof__ (double)} is 4 or even 2. + +Some machines never actually require alignment; they allow reference to any +data type even at an odd address. For these machines, @code{__alignof__} +reports the smallest alignment that GCC will give the data type, usually as +mandated by the target ABI. + +If the operand of @code{__alignof__} is an lvalue rather than a type, +its value is the required alignment for its type, taking into account +any minimum alignment specified with GCC's @code{__attribute__} +extension (@pxref{Variable Attributes}). For example, after this +declaration: + +@smallexample +struct foo @{ int x; char y; @} foo1; +@end smallexample + +@noindent +the value of @code{__alignof__ (foo1.y)} is 1, even though its actual +alignment is probably 2 or 4, the same as @code{__alignof__ (int)}. + +It is an error to ask for the alignment of an incomplete type. + + +@node Inline +@section An Inline Function is As Fast As a Macro +@cindex inline functions +@cindex integrating function code +@cindex open coding +@cindex macros, inline alternative + +By declaring a function inline, you can direct GCC to make +calls to that function faster. One way GCC can achieve this is to +integrate that function's code into the code for its callers. This +makes execution faster by eliminating the function-call overhead; in +addition, if any of the actual argument values are constant, their +known values may permit simplifications at compile time so that not +all of the inline function's code needs to be included. The effect on +code size is less predictable; object code may be larger or smaller +with function inlining, depending on the particular case. You can +also direct GCC to try to integrate all ``simple enough'' functions +into their callers with the option @option{-finline-functions}. + +GCC implements three different semantics of declaring a function +inline. One is available with @option{-std=gnu89} or +@option{-fgnu89-inline} or when @code{gnu_inline} attribute is present +on all inline declarations, another when +@option{-std=c99}, @option{-std=c1x}, +@option{-std=gnu99} or @option{-std=gnu1x} +(without @option{-fgnu89-inline}), and the third +is used when compiling C++. + +To declare a function inline, use the @code{inline} keyword in its +declaration, like this: + +@smallexample +static inline int +inc (int *a) +@{ + return (*a)++; +@} +@end smallexample + +If you are writing a header file to be included in ISO C90 programs, write +@code{__inline__} instead of @code{inline}. @xref{Alternate Keywords}. + +The three types of inlining behave similarly in two important cases: +when the @code{inline} keyword is used on a @code{static} function, +like the example above, and when a function is first declared without +using the @code{inline} keyword and then is defined with +@code{inline}, like this: + +@smallexample +extern int inc (int *a); +inline int +inc (int *a) +@{ + return (*a)++; +@} +@end smallexample + +In both of these common cases, the program behaves the same as if you +had not used the @code{inline} keyword, except for its speed. + +@cindex inline functions, omission of +@opindex fkeep-inline-functions +When a function is both inline and @code{static}, if all calls to the +function are integrated into the caller, and the function's address is +never used, then the function's own assembler code is never referenced. +In this case, GCC does not actually output assembler code for the +function, unless you specify the option @option{-fkeep-inline-functions}. +Some calls cannot be integrated for various reasons (in particular, +calls that precede the function's definition cannot be integrated, and +neither can recursive calls within the definition). If there is a +nonintegrated call, then the function is compiled to assembler code as +usual. The function must also be compiled as usual if the program +refers to its address, because that can't be inlined. + +@opindex Winline +Note that certain usages in a function definition can make it unsuitable +for inline substitution. Among these usages are: use of varargs, use of +alloca, use of variable sized data types (@pxref{Variable Length}), +use of computed goto (@pxref{Labels as Values}), use of nonlocal goto, +and nested functions (@pxref{Nested Functions}). Using @option{-Winline} +will warn when a function marked @code{inline} could not be substituted, +and will give the reason for the failure. + +@cindex automatic @code{inline} for C++ member fns +@cindex @code{inline} automatic for C++ member fns +@cindex member fns, automatically @code{inline} +@cindex C++ member fns, automatically @code{inline} +@opindex fno-default-inline +As required by ISO C++, GCC considers member functions defined within +the body of a class to be marked inline even if they are +not explicitly declared with the @code{inline} keyword. You can +override this with @option{-fno-default-inline}; @pxref{C++ Dialect +Options,,Options Controlling C++ Dialect}. + +GCC does not inline any functions when not optimizing unless you specify +the @samp{always_inline} attribute for the function, like this: + +@smallexample +/* @r{Prototype.} */ +inline void foo (const char) __attribute__((always_inline)); +@end smallexample + +The remainder of this section is specific to GNU C90 inlining. + +@cindex non-static inline function +When an inline function is not @code{static}, then the compiler must assume +that there may be calls from other source files; since a global symbol can +be defined only once in any program, the function must not be defined in +the other source files, so the calls therein cannot be integrated. +Therefore, a non-@code{static} inline function is always compiled on its +own in the usual fashion. + +If you specify both @code{inline} and @code{extern} in the function +definition, then the definition is used only for inlining. In no case +is the function compiled on its own, not even if you refer to its +address explicitly. Such an address becomes an external reference, as +if you had only declared the function, and had not defined it. + +This combination of @code{inline} and @code{extern} has almost the +effect of a macro. The way to use it is to put a function definition in +a header file with these keywords, and put another copy of the +definition (lacking @code{inline} and @code{extern}) in a library file. +The definition in the header file will cause most calls to the function +to be inlined. If any uses of the function remain, they will refer to +the single copy in the library. + +@node Volatiles +@section When is a Volatile Object Accessed? +@cindex accessing volatiles +@cindex volatile read +@cindex volatile write +@cindex volatile access + +C has the concept of volatile objects. These are normally accessed by +pointers and used for accessing hardware or inter-thread +communication. The standard encourages compilers to refrain from +optimizations concerning accesses to volatile objects, but leaves it +implementation defined as to what constitutes a volatile access. The +minimum requirement is that at a sequence point all previous accesses +to volatile objects have stabilized and no subsequent accesses have +occurred. Thus an implementation is free to reorder and combine +volatile accesses which occur between sequence points, but cannot do +so for accesses across a sequence point. The use of volatile does +not allow you to violate the restriction on updating objects multiple +times between two sequence points. + +Accesses to non-volatile objects are not ordered with respect to +volatile accesses. You cannot use a volatile object as a memory +barrier to order a sequence of writes to non-volatile memory. For +instance: + +@smallexample +int *ptr = @var{something}; +volatile int vobj; +*ptr = @var{something}; +vobj = 1; +@end smallexample + +Unless @var{*ptr} and @var{vobj} can be aliased, it is not guaranteed +that the write to @var{*ptr} will have occurred by the time the update +of @var{vobj} has happened. If you need this guarantee, you must use +a stronger memory barrier such as: + +@smallexample +int *ptr = @var{something}; +volatile int vobj; +*ptr = @var{something}; +asm volatile ("" : : : "memory"); +vobj = 1; +@end smallexample + +A scalar volatile object is read when it is accessed in a void context: + +@smallexample +volatile int *src = @var{somevalue}; +*src; +@end smallexample + +Such expressions are rvalues, and GCC implements this as a +read of the volatile object being pointed to. + +Assignments are also expressions and have an rvalue. However when +assigning to a scalar volatile, the volatile object is not reread, +regardless of whether the assignment expression's rvalue is used or +not. If the assignment's rvalue is used, the value is that assigned +to the volatile object. For instance, there is no read of @var{vobj} +in all the following cases: + +@smallexample +int obj; +volatile int vobj; +vobj = @var{something}; +obj = vobj = @var{something}; +obj ? vobj = @var{onething} : vobj = @var{anotherthing}; +obj = (@var{something}, vobj = @var{anotherthing}); +@end smallexample + +If you need to read the volatile object after an assignment has +occurred, you must use a separate expression with an intervening +sequence point. + +As bitfields are not individually addressable, volatile bitfields may +be implicitly read when written to, or when adjacent bitfields are +accessed. Bitfield operations may be optimized such that adjacent +bitfields are only partially accessed, if they straddle a storage unit +boundary. For these reasons it is unwise to use volatile bitfields to +access hardware. + +@node Extended Asm +@section Assembler Instructions with C Expression Operands +@cindex extended @code{asm} +@cindex @code{asm} expressions +@cindex assembler instructions +@cindex registers + +In an assembler instruction using @code{asm}, you can specify the +operands of the instruction using C expressions. This means you need not +guess which registers or memory locations will contain the data you want +to use. + +You must specify an assembler instruction template much like what +appears in a machine description, plus an operand constraint string for +each operand. + +For example, here is how to use the 68881's @code{fsinx} instruction: + +@smallexample +asm ("fsinx %1,%0" : "=f" (result) : "f" (angle)); +@end smallexample + +@noindent +Here @code{angle} is the C expression for the input operand while +@code{result} is that of the output operand. Each has @samp{"f"} as its +operand constraint, saying that a floating point register is required. +The @samp{=} in @samp{=f} indicates that the operand is an output; all +output operands' constraints must use @samp{=}. The constraints use the +same language used in the machine description (@pxref{Constraints}). + +Each operand is described by an operand-constraint string followed by +the C expression in parentheses. A colon separates the assembler +template from the first output operand and another separates the last +output operand from the first input, if any. Commas separate the +operands within each group. The total number of operands is currently +limited to 30; this limitation may be lifted in some future version of +GCC@. + +If there are no output operands but there are input operands, you must +place two consecutive colons surrounding the place where the output +operands would go. + +As of GCC version 3.1, it is also possible to specify input and output +operands using symbolic names which can be referenced within the +assembler code. These names are specified inside square brackets +preceding the constraint string, and can be referenced inside the +assembler code using @code{%[@var{name}]} instead of a percentage sign +followed by the operand number. Using named operands the above example +could look like: + +@smallexample +asm ("fsinx %[angle],%[output]" + : [output] "=f" (result) + : [angle] "f" (angle)); +@end smallexample + +@noindent +Note that the symbolic operand names have no relation whatsoever to +other C identifiers. You may use any name you like, even those of +existing C symbols, but you must ensure that no two operands within the same +assembler construct use the same symbolic name. + +Output operand expressions must be lvalues; the compiler can check this. +The input operands need not be lvalues. The compiler cannot check +whether the operands have data types that are reasonable for the +instruction being executed. It does not parse the assembler instruction +template and does not know what it means or even whether it is valid +assembler input. The extended @code{asm} feature is most often used for +machine instructions the compiler itself does not know exist. If +the output expression cannot be directly addressed (for example, it is a +bit-field), your constraint must allow a register. In that case, GCC +will use the register as the output of the @code{asm}, and then store +that register into the output. + +The ordinary output operands must be write-only; GCC will assume that +the values in these operands before the instruction are dead and need +not be generated. Extended asm supports input-output or read-write +operands. Use the constraint character @samp{+} to indicate such an +operand and list it with the output operands. You should only use +read-write operands when the constraints for the operand (or the +operand in which only some of the bits are to be changed) allow a +register. + +You may, as an alternative, logically split its function into two +separate operands, one input operand and one write-only output +operand. The connection between them is expressed by constraints +which say they need to be in the same location when the instruction +executes. You can use the same C expression for both operands, or +different expressions. For example, here we write the (fictitious) +@samp{combine} instruction with @code{bar} as its read-only source +operand and @code{foo} as its read-write destination: + +@smallexample +asm ("combine %2,%0" : "=r" (foo) : "0" (foo), "g" (bar)); +@end smallexample + +@noindent +The constraint @samp{"0"} for operand 1 says that it must occupy the +same location as operand 0. A number in constraint is allowed only in +an input operand and it must refer to an output operand. + +Only a number in the constraint can guarantee that one operand will be in +the same place as another. The mere fact that @code{foo} is the value +of both operands is not enough to guarantee that they will be in the +same place in the generated assembler code. The following would not +work reliably: + +@smallexample +asm ("combine %2,%0" : "=r" (foo) : "r" (foo), "g" (bar)); +@end smallexample + +Various optimizations or reloading could cause operands 0 and 1 to be in +different registers; GCC knows no reason not to do so. For example, the +compiler might find a copy of the value of @code{foo} in one register and +use it for operand 1, but generate the output operand 0 in a different +register (copying it afterward to @code{foo}'s own address). Of course, +since the register for operand 1 is not even mentioned in the assembler +code, the result will not work, but GCC can't tell that. + +As of GCC version 3.1, one may write @code{[@var{name}]} instead of +the operand number for a matching constraint. For example: + +@smallexample +asm ("cmoveq %1,%2,%[result]" + : [result] "=r"(result) + : "r" (test), "r"(new), "[result]"(old)); +@end smallexample + +Sometimes you need to make an @code{asm} operand be a specific register, +but there's no matching constraint letter for that register @emph{by +itself}. To force the operand into that register, use a local variable +for the operand and specify the register in the variable declaration. +@xref{Explicit Reg Vars}. Then for the @code{asm} operand, use any +register constraint letter that matches the register: + +@smallexample +register int *p1 asm ("r0") = @dots{}; +register int *p2 asm ("r1") = @dots{}; +register int *result asm ("r0"); +asm ("sysint" : "=r" (result) : "0" (p1), "r" (p2)); +@end smallexample + +@anchor{Example of asm with clobbered asm reg} +In the above example, beware that a register that is call-clobbered by +the target ABI will be overwritten by any function call in the +assignment, including library calls for arithmetic operators. +Also a register may be clobbered when generating some operations, +like variable shift, memory copy or memory move on x86. +Assuming it is a call-clobbered register, this may happen to @code{r0} +above by the assignment to @code{p2}. If you have to use such a +register, use temporary variables for expressions between the register +assignment and use: + +@smallexample +int t1 = @dots{}; +register int *p1 asm ("r0") = @dots{}; +register int *p2 asm ("r1") = t1; +register int *result asm ("r0"); +asm ("sysint" : "=r" (result) : "0" (p1), "r" (p2)); +@end smallexample + +Some instructions clobber specific hard registers. To describe this, +write a third colon after the input operands, followed by the names of +the clobbered hard registers (given as strings). Here is a realistic +example for the VAX: + +@smallexample +asm volatile ("movc3 %0,%1,%2" + : /* @r{no outputs} */ + : "g" (from), "g" (to), "g" (count) + : "r0", "r1", "r2", "r3", "r4", "r5"); +@end smallexample + +You may not write a clobber description in a way that overlaps with an +input or output operand. For example, you may not have an operand +describing a register class with one member if you mention that register +in the clobber list. Variables declared to live in specific registers +(@pxref{Explicit Reg Vars}), and used as asm input or output operands must +have no part mentioned in the clobber description. +There is no way for you to specify that an input +operand is modified without also specifying it as an output +operand. Note that if all the output operands you specify are for this +purpose (and hence unused), you will then also need to specify +@code{volatile} for the @code{asm} construct, as described below, to +prevent GCC from deleting the @code{asm} statement as unused. + +If you refer to a particular hardware register from the assembler code, +you will probably have to list the register after the third colon to +tell the compiler the register's value is modified. In some assemblers, +the register names begin with @samp{%}; to produce one @samp{%} in the +assembler code, you must write @samp{%%} in the input. + +If your assembler instruction can alter the condition code register, add +@samp{cc} to the list of clobbered registers. GCC on some machines +represents the condition codes as a specific hardware register; +@samp{cc} serves to name this register. On other machines, the +condition code is handled differently, and specifying @samp{cc} has no +effect. But it is valid no matter what the machine. + +If your assembler instructions access memory in an unpredictable +fashion, add @samp{memory} to the list of clobbered registers. This +will cause GCC to not keep memory values cached in registers across the +assembler instruction and not optimize stores or loads to that memory. +You will also want to add the @code{volatile} keyword if the memory +affected is not listed in the inputs or outputs of the @code{asm}, as +the @samp{memory} clobber does not count as a side-effect of the +@code{asm}. If you know how large the accessed memory is, you can add +it as input or output but if this is not known, you should add +@samp{memory}. As an example, if you access ten bytes of a string, you +can use a memory input like: + +@smallexample +@{"m"( (@{ struct @{ char x[10]; @} *p = (void *)ptr ; *p; @}) )@}. +@end smallexample + +Note that in the following example the memory input is necessary, +otherwise GCC might optimize the store to @code{x} away: +@smallexample +int foo () +@{ + int x = 42; + int *y = &x; + int result; + asm ("magic stuff accessing an 'int' pointed to by '%1'" + "=&d" (r) : "a" (y), "m" (*y)); + return result; +@} +@end smallexample + +You can put multiple assembler instructions together in a single +@code{asm} template, separated by the characters normally used in assembly +code for the system. A combination that works in most places is a newline +to break the line, plus a tab character to move to the instruction field +(written as @samp{\n\t}). Sometimes semicolons can be used, if the +assembler allows semicolons as a line-breaking character. Note that some +assembler dialects use semicolons to start a comment. +The input operands are guaranteed not to use any of the clobbered +registers, and neither will the output operands' addresses, so you can +read and write the clobbered registers as many times as you like. Here +is an example of multiple instructions in a template; it assumes the +subroutine @code{_foo} accepts arguments in registers 9 and 10: + +@smallexample +asm ("movl %0,r9\n\tmovl %1,r10\n\tcall _foo" + : /* no outputs */ + : "g" (from), "g" (to) + : "r9", "r10"); +@end smallexample + +Unless an output operand has the @samp{&} constraint modifier, GCC +may allocate it in the same register as an unrelated input operand, on +the assumption the inputs are consumed before the outputs are produced. +This assumption may be false if the assembler code actually consists of +more than one instruction. In such a case, use @samp{&} for each output +operand that may not overlap an input. @xref{Modifiers}. + +If you want to test the condition code produced by an assembler +instruction, you must include a branch and a label in the @code{asm} +construct, as follows: + +@smallexample +asm ("clr %0\n\tfrob %1\n\tbeq 0f\n\tmov #1,%0\n0:" + : "g" (result) + : "g" (input)); +@end smallexample + +@noindent +This assumes your assembler supports local labels, as the GNU assembler +and most Unix assemblers do. + +Speaking of labels, jumps from one @code{asm} to another are not +supported. The compiler's optimizers do not know about these jumps, and +therefore they cannot take account of them when deciding how to +optimize. @xref{Extended asm with goto}. + +@cindex macros containing @code{asm} +Usually the most convenient way to use these @code{asm} instructions is to +encapsulate them in macros that look like functions. For example, + +@smallexample +#define sin(x) \ +(@{ double __value, __arg = (x); \ + asm ("fsinx %1,%0": "=f" (__value): "f" (__arg)); \ + __value; @}) +@end smallexample + +@noindent +Here the variable @code{__arg} is used to make sure that the instruction +operates on a proper @code{double} value, and to accept only those +arguments @code{x} which can convert automatically to a @code{double}. + +Another way to make sure the instruction operates on the correct data +type is to use a cast in the @code{asm}. This is different from using a +variable @code{__arg} in that it converts more different types. For +example, if the desired type were @code{int}, casting the argument to +@code{int} would accept a pointer with no complaint, while assigning the +argument to an @code{int} variable named @code{__arg} would warn about +using a pointer unless the caller explicitly casts it. + +If an @code{asm} has output operands, GCC assumes for optimization +purposes the instruction has no side effects except to change the output +operands. This does not mean instructions with a side effect cannot be +used, but you must be careful, because the compiler may eliminate them +if the output operands aren't used, or move them out of loops, or +replace two with one if they constitute a common subexpression. Also, +if your instruction does have a side effect on a variable that otherwise +appears not to change, the old value of the variable may be reused later +if it happens to be found in a register. + +You can prevent an @code{asm} instruction from being deleted +by writing the keyword @code{volatile} after +the @code{asm}. For example: + +@smallexample +#define get_and_set_priority(new) \ +(@{ int __old; \ + asm volatile ("get_and_set_priority %0, %1" \ + : "=g" (__old) : "g" (new)); \ + __old; @}) +@end smallexample + +@noindent +The @code{volatile} keyword indicates that the instruction has +important side-effects. GCC will not delete a volatile @code{asm} if +it is reachable. (The instruction can still be deleted if GCC can +prove that control-flow will never reach the location of the +instruction.) Note that even a volatile @code{asm} instruction +can be moved relative to other code, including across jump +instructions. For example, on many targets there is a system +register which can be set to control the rounding mode of +floating point operations. You might try +setting it with a volatile @code{asm}, like this PowerPC example: + +@smallexample + asm volatile("mtfsf 255,%0" : : "f" (fpenv)); + sum = x + y; +@end smallexample + +@noindent +This will not work reliably, as the compiler may move the addition back +before the volatile @code{asm}. To make it work you need to add an +artificial dependency to the @code{asm} referencing a variable in the code +you don't want moved, for example: + +@smallexample + asm volatile ("mtfsf 255,%1" : "=X"(sum): "f"(fpenv)); + sum = x + y; +@end smallexample + +Similarly, you can't expect a +sequence of volatile @code{asm} instructions to remain perfectly +consecutive. If you want consecutive output, use a single @code{asm}. +Also, GCC will perform some optimizations across a volatile @code{asm} +instruction; GCC does not ``forget everything'' when it encounters +a volatile @code{asm} instruction the way some other compilers do. + +An @code{asm} instruction without any output operands will be treated +identically to a volatile @code{asm} instruction. + +It is a natural idea to look for a way to give access to the condition +code left by the assembler instruction. However, when we attempted to +implement this, we found no way to make it work reliably. The problem +is that output operands might need reloading, which would result in +additional following ``store'' instructions. On most machines, these +instructions would alter the condition code before there was time to +test it. This problem doesn't arise for ordinary ``test'' and +``compare'' instructions because they don't have any output operands. + +For reasons similar to those described above, it is not possible to give +an assembler instruction access to the condition code left by previous +instructions. + +@anchor{Extended asm with goto} +As of GCC version 4.5, @code{asm goto} may be used to have the assembly +jump to one or more C labels. In this form, a fifth section after the +clobber list contains a list of all C labels to which the assembly may jump. +Each label operand is implicitly self-named. The @code{asm} is also assumed +to fall through to the next statement. + +This form of @code{asm} is restricted to not have outputs. This is due +to a internal restriction in the compiler that control transfer instructions +cannot have outputs. This restriction on @code{asm goto} may be lifted +in some future version of the compiler. In the mean time, @code{asm goto} +may include a memory clobber, and so leave outputs in memory. + +@smallexample +int frob(int x) +@{ + int y; + asm goto ("frob %%r5, %1; jc %l[error]; mov (%2), %%r5" + : : "r"(x), "r"(&y) : "r5", "memory" : error); + return y; + error: + return -1; +@} +@end smallexample + +In this (inefficient) example, the @code{frob} instruction sets the +carry bit to indicate an error. The @code{jc} instruction detects +this and branches to the @code{error} label. Finally, the output +of the @code{frob} instruction (@code{%r5}) is stored into the memory +for variable @code{y}, which is later read by the @code{return} statement. + +@smallexample +void doit(void) +@{ + int i = 0; + asm goto ("mfsr %%r1, 123; jmp %%r1;" + ".pushsection doit_table;" + ".long %l0, %l1, %l2, %l3;" + ".popsection" + : : : "r1" : label1, label2, label3, label4); + __builtin_unreachable (); + + label1: + f1(); + return; + label2: + f2(); + return; + label3: + i = 1; + label4: + f3(i); +@} +@end smallexample + +In this (also inefficient) example, the @code{mfsr} instruction reads +an address from some out-of-band machine register, and the following +@code{jmp} instruction branches to that address. The address read by +the @code{mfsr} instruction is assumed to have been previously set via +some application-specific mechanism to be one of the four values stored +in the @code{doit_table} section. Finally, the @code{asm} is followed +by a call to @code{__builtin_unreachable} to indicate that the @code{asm} +does not in fact fall through. + +@smallexample +#define TRACE1(NUM) \ + do @{ \ + asm goto ("0: nop;" \ + ".pushsection trace_table;" \ + ".long 0b, %l0;" \ + ".popsection" \ + : : : : trace#NUM); \ + if (0) @{ trace#NUM: trace(); @} \ + @} while (0) +#define TRACE TRACE1(__COUNTER__) +@end smallexample + +In this example (which in fact inspired the @code{asm goto} feature) +we want on rare occasions to call the @code{trace} function; on other +occasions we'd like to keep the overhead to the absolute minimum. +The normal code path consists of a single @code{nop} instruction. +However, we record the address of this @code{nop} together with the +address of a label that calls the @code{trace} function. This allows +the @code{nop} instruction to be patched at runtime to be an +unconditional branch to the stored label. It is assumed that an +optimizing compiler will move the labeled block out of line, to +optimize the fall through path from the @code{asm}. + +If you are writing a header file that should be includable in ISO C +programs, write @code{__asm__} instead of @code{asm}. @xref{Alternate +Keywords}. + +@subsection Size of an @code{asm} + +Some targets require that GCC track the size of each instruction used in +order to generate correct code. Because the final length of an +@code{asm} is only known by the assembler, GCC must make an estimate as +to how big it will be. The estimate is formed by counting the number of +statements in the pattern of the @code{asm} and multiplying that by the +length of the longest instruction on that processor. Statements in the +@code{asm} are identified by newline characters and whatever statement +separator characters are supported by the assembler; on most processors +this is the `@code{;}' character. + +Normally, GCC's estimate is perfectly adequate to ensure that correct +code is generated, but it is possible to confuse the compiler if you use +pseudo instructions or assembler macros that expand into multiple real +instructions or if you use assembler directives that expand to more +space in the object file than would be needed for a single instruction. +If this happens then the assembler will produce a diagnostic saying that +a label is unreachable. + +@subsection i386 floating point asm operands + +There are several rules on the usage of stack-like regs in +asm_operands insns. These rules apply only to the operands that are +stack-like regs: + +@enumerate +@item +Given a set of input regs that die in an asm_operands, it is +necessary to know which are implicitly popped by the asm, and +which must be explicitly popped by gcc. + +An input reg that is implicitly popped by the asm must be +explicitly clobbered, unless it is constrained to match an +output operand. + +@item +For any input reg that is implicitly popped by an asm, it is +necessary to know how to adjust the stack to compensate for the pop. +If any non-popped input is closer to the top of the reg-stack than +the implicitly popped reg, it would not be possible to know what the +stack looked like---it's not clear how the rest of the stack ``slides +up''. + +All implicitly popped input regs must be closer to the top of +the reg-stack than any input that is not implicitly popped. + +It is possible that if an input dies in an insn, reload might +use the input reg for an output reload. Consider this example: + +@smallexample +asm ("foo" : "=t" (a) : "f" (b)); +@end smallexample + +This asm says that input B is not popped by the asm, and that +the asm pushes a result onto the reg-stack, i.e., the stack is one +deeper after the asm than it was before. But, it is possible that +reload will think that it can use the same reg for both the input and +the output, if input B dies in this insn. + +If any input operand uses the @code{f} constraint, all output reg +constraints must use the @code{&} earlyclobber. + +The asm above would be written as + +@smallexample +asm ("foo" : "=&t" (a) : "f" (b)); +@end smallexample + +@item +Some operands need to be in particular places on the stack. All +output operands fall in this category---there is no other way to +know which regs the outputs appear in unless the user indicates +this in the constraints. + +Output operands must specifically indicate which reg an output +appears in after an asm. @code{=f} is not allowed: the operand +constraints must select a class with a single reg. + +@item +Output operands may not be ``inserted'' between existing stack regs. +Since no 387 opcode uses a read/write operand, all output operands +are dead before the asm_operands, and are pushed by the asm_operands. +It makes no sense to push anywhere but the top of the reg-stack. + +Output operands must start at the top of the reg-stack: output +operands may not ``skip'' a reg. + +@item +Some asm statements may need extra stack space for internal +calculations. This can be guaranteed by clobbering stack registers +unrelated to the inputs and outputs. + +@end enumerate + +Here are a couple of reasonable asms to want to write. This asm +takes one input, which is internally popped, and produces two outputs. + +@smallexample +asm ("fsincos" : "=t" (cos), "=u" (sin) : "0" (inp)); +@end smallexample + +This asm takes two inputs, which are popped by the @code{fyl2xp1} opcode, +and replaces them with one output. The user must code the @code{st(1)} +clobber for reg-stack.c to know that @code{fyl2xp1} pops both inputs. + +@smallexample +asm ("fyl2xp1" : "=t" (result) : "0" (x), "u" (y) : "st(1)"); +@end smallexample + +@include md.texi + +@node Asm Labels +@section Controlling Names Used in Assembler Code +@cindex assembler names for identifiers +@cindex names used in assembler code +@cindex identifiers, names in assembler code + +You can specify the name to be used in the assembler code for a C +function or variable by writing the @code{asm} (or @code{__asm__}) +keyword after the declarator as follows: + +@smallexample +int foo asm ("myfoo") = 2; +@end smallexample + +@noindent +This specifies that the name to be used for the variable @code{foo} in +the assembler code should be @samp{myfoo} rather than the usual +@samp{_foo}. + +On systems where an underscore is normally prepended to the name of a C +function or variable, this feature allows you to define names for the +linker that do not start with an underscore. + +It does not make sense to use this feature with a non-static local +variable since such variables do not have assembler names. If you are +trying to put the variable in a particular register, see @ref{Explicit +Reg Vars}. GCC presently accepts such code with a warning, but will +probably be changed to issue an error, rather than a warning, in the +future. + +You cannot use @code{asm} in this way in a function @emph{definition}; but +you can get the same effect by writing a declaration for the function +before its definition and putting @code{asm} there, like this: + +@smallexample +extern func () asm ("FUNC"); + +func (x, y) + int x, y; +/* @r{@dots{}} */ +@end smallexample + +It is up to you to make sure that the assembler names you choose do not +conflict with any other assembler symbols. Also, you must not use a +register name; that would produce completely invalid assembler code. GCC +does not as yet have the ability to store static variables in registers. +Perhaps that will be added. + +@node Explicit Reg Vars +@section Variables in Specified Registers +@cindex explicit register variables +@cindex variables in specified registers +@cindex specified registers +@cindex registers, global allocation + +GNU C allows you to put a few global variables into specified hardware +registers. You can also specify the register in which an ordinary +register variable should be allocated. + +@itemize @bullet +@item +Global register variables reserve registers throughout the program. +This may be useful in programs such as programming language +interpreters which have a couple of global variables that are accessed +very often. + +@item +Local register variables in specific registers do not reserve the +registers, except at the point where they are used as input or output +operands in an @code{asm} statement and the @code{asm} statement itself is +not deleted. The compiler's data flow analysis is capable of determining +where the specified registers contain live values, and where they are +available for other uses. Stores into local register variables may be deleted +when they appear to be dead according to dataflow analysis. References +to local register variables may be deleted or moved or simplified. + +These local variables are sometimes convenient for use with the extended +@code{asm} feature (@pxref{Extended Asm}), if you want to write one +output of the assembler instruction directly into a particular register. +(This will work provided the register you specify fits the constraints +specified for that operand in the @code{asm}.) +@end itemize + +@menu +* Global Reg Vars:: +* Local Reg Vars:: +@end menu + +@node Global Reg Vars +@subsection Defining Global Register Variables +@cindex global register variables +@cindex registers, global variables in + +You can define a global register variable in GNU C like this: + +@smallexample +register int *foo asm ("a5"); +@end smallexample + +@noindent +Here @code{a5} is the name of the register which should be used. Choose a +register which is normally saved and restored by function calls on your +machine, so that library routines will not clobber it. + +Naturally the register name is cpu-dependent, so you would need to +conditionalize your program according to cpu type. The register +@code{a5} would be a good choice on a 68000 for a variable of pointer +type. On machines with register windows, be sure to choose a ``global'' +register that is not affected magically by the function call mechanism. + +In addition, operating systems on one type of cpu may differ in how they +name the registers; then you would need additional conditionals. For +example, some 68000 operating systems call this register @code{%a5}. + +Eventually there may be a way of asking the compiler to choose a register +automatically, but first we need to figure out how it should choose and +how to enable you to guide the choice. No solution is evident. + +Defining a global register variable in a certain register reserves that +register entirely for this use, at least within the current compilation. +The register will not be allocated for any other purpose in the functions +in the current compilation. The register will not be saved and restored by +these functions. Stores into this register are never deleted even if they +would appear to be dead, but references may be deleted or moved or +simplified. + +It is not safe to access the global register variables from signal +handlers, or from more than one thread of control, because the system +library routines may temporarily use the register for other things (unless +you recompile them specially for the task at hand). + +@cindex @code{qsort}, and global register variables +It is not safe for one function that uses a global register variable to +call another such function @code{foo} by way of a third function +@code{lose} that was compiled without knowledge of this variable (i.e.@: in a +different source file in which the variable wasn't declared). This is +because @code{lose} might save the register and put some other value there. +For example, you can't expect a global register variable to be available in +the comparison-function that you pass to @code{qsort}, since @code{qsort} +might have put something else in that register. (If you are prepared to +recompile @code{qsort} with the same global register variable, you can +solve this problem.) + +If you want to recompile @code{qsort} or other source files which do not +actually use your global register variable, so that they will not use that +register for any other purpose, then it suffices to specify the compiler +option @option{-ffixed-@var{reg}}. You need not actually add a global +register declaration to their source code. + +A function which can alter the value of a global register variable cannot +safely be called from a function compiled without this variable, because it +could clobber the value the caller expects to find there on return. +Therefore, the function which is the entry point into the part of the +program that uses the global register variable must explicitly save and +restore the value which belongs to its caller. + +@cindex register variable after @code{longjmp} +@cindex global register after @code{longjmp} +@cindex value after @code{longjmp} +@findex longjmp +@findex setjmp +On most machines, @code{longjmp} will restore to each global register +variable the value it had at the time of the @code{setjmp}. On some +machines, however, @code{longjmp} will not change the value of global +register variables. To be portable, the function that called @code{setjmp} +should make other arrangements to save the values of the global register +variables, and to restore them in a @code{longjmp}. This way, the same +thing will happen regardless of what @code{longjmp} does. + +All global register variable declarations must precede all function +definitions. If such a declaration could appear after function +definitions, the declaration would be too late to prevent the register from +being used for other purposes in the preceding functions. + +Global register variables may not have initial values, because an +executable file has no means to supply initial contents for a register. + +On the SPARC, there are reports that g3 @dots{} g7 are suitable +registers, but certain library functions, such as @code{getwd}, as well +as the subroutines for division and remainder, modify g3 and g4. g1 and +g2 are local temporaries. + +On the 68000, a2 @dots{} a5 should be suitable, as should d2 @dots{} d7. +Of course, it will not do to use more than a few of those. + +@node Local Reg Vars +@subsection Specifying Registers for Local Variables +@cindex local variables, specifying registers +@cindex specifying registers for local variables +@cindex registers for local variables + +You can define a local register variable with a specified register +like this: + +@smallexample +register int *foo asm ("a5"); +@end smallexample + +@noindent +Here @code{a5} is the name of the register which should be used. Note +that this is the same syntax used for defining global register +variables, but for a local variable it would appear within a function. + +Naturally the register name is cpu-dependent, but this is not a +problem, since specific registers are most often useful with explicit +assembler instructions (@pxref{Extended Asm}). Both of these things +generally require that you conditionalize your program according to +cpu type. + +In addition, operating systems on one type of cpu may differ in how they +name the registers; then you would need additional conditionals. For +example, some 68000 operating systems call this register @code{%a5}. + +Defining such a register variable does not reserve the register; it +remains available for other uses in places where flow control determines +the variable's value is not live. + +This option does not guarantee that GCC will generate code that has +this variable in the register you specify at all times. You may not +code an explicit reference to this register in the @emph{assembler +instruction template} part of an @code{asm} statement and assume it will +always refer to this variable. However, using the variable as an +@code{asm} @emph{operand} guarantees that the specified register is used +for the operand. + +Stores into local register variables may be deleted when they appear to be dead +according to dataflow analysis. References to local register variables may +be deleted or moved or simplified. + +As for global register variables, it's recommended that you choose a +register which is normally saved and restored by function calls on +your machine, so that library routines will not clobber it. A common +pitfall is to initialize multiple call-clobbered registers with +arbitrary expressions, where a function call or library call for an +arithmetic operator will overwrite a register value from a previous +assignment, for example @code{r0} below: +@smallexample +register int *p1 asm ("r0") = @dots{}; +register int *p2 asm ("r1") = @dots{}; +@end smallexample +In those cases, a solution is to use a temporary variable for +each arbitrary expression. @xref{Example of asm with clobbered asm reg}. + +@node Alternate Keywords +@section Alternate Keywords +@cindex alternate keywords +@cindex keywords, alternate + +@option{-ansi} and the various @option{-std} options disable certain +keywords. This causes trouble when you want to use GNU C extensions, or +a general-purpose header file that should be usable by all programs, +including ISO C programs. The keywords @code{asm}, @code{typeof} and +@code{inline} are not available in programs compiled with +@option{-ansi} or @option{-std} (although @code{inline} can be used in a +program compiled with @option{-std=c99} or @option{-std=c1x}). The +ISO C99 keyword +@code{restrict} is only available when @option{-std=gnu99} (which will +eventually be the default) or @option{-std=c99} (or the equivalent +@option{-std=iso9899:1999}), or an option for a later standard +version, is used. + +The way to solve these problems is to put @samp{__} at the beginning and +end of each problematical keyword. For example, use @code{__asm__} +instead of @code{asm}, and @code{__inline__} instead of @code{inline}. + +Other C compilers won't accept these alternative keywords; if you want to +compile with another compiler, you can define the alternate keywords as +macros to replace them with the customary keywords. It looks like this: + +@smallexample +#ifndef __GNUC__ +#define __asm__ asm +#endif +@end smallexample + +@findex __extension__ +@opindex pedantic +@option{-pedantic} and other options cause warnings for many GNU C extensions. +You can +prevent such warnings within one expression by writing +@code{__extension__} before the expression. @code{__extension__} has no +effect aside from this. + +@node Incomplete Enums +@section Incomplete @code{enum} Types + +You can define an @code{enum} tag without specifying its possible values. +This results in an incomplete type, much like what you get if you write +@code{struct foo} without describing the elements. A later declaration +which does specify the possible values completes the type. + +You can't allocate variables or storage using the type while it is +incomplete. However, you can work with pointers to that type. + +This extension may not be very useful, but it makes the handling of +@code{enum} more consistent with the way @code{struct} and @code{union} +are handled. + +This extension is not supported by GNU C++. + +@node Function Names +@section Function Names as Strings +@cindex @code{__func__} identifier +@cindex @code{__FUNCTION__} identifier +@cindex @code{__PRETTY_FUNCTION__} identifier + +GCC provides three magic variables which hold the name of the current +function, as a string. The first of these is @code{__func__}, which +is part of the C99 standard: + +The identifier @code{__func__} is implicitly declared by the translator +as if, immediately following the opening brace of each function +definition, the declaration + +@smallexample +static const char __func__[] = "function-name"; +@end smallexample + +@noindent +appeared, where function-name is the name of the lexically-enclosing +function. This name is the unadorned name of the function. + +@code{__FUNCTION__} is another name for @code{__func__}. Older +versions of GCC recognize only this name. However, it is not +standardized. For maximum portability, we recommend you use +@code{__func__}, but provide a fallback definition with the +preprocessor: + +@smallexample +#if __STDC_VERSION__ < 199901L +# if __GNUC__ >= 2 +# define __func__ __FUNCTION__ +# else +# define __func__ "" +# endif +#endif +@end smallexample + +In C, @code{__PRETTY_FUNCTION__} is yet another name for +@code{__func__}. However, in C++, @code{__PRETTY_FUNCTION__} contains +the type signature of the function as well as its bare name. For +example, this program: + +@smallexample +extern "C" @{ +extern int printf (char *, ...); +@} + +class a @{ + public: + void sub (int i) + @{ + printf ("__FUNCTION__ = %s\n", __FUNCTION__); + printf ("__PRETTY_FUNCTION__ = %s\n", __PRETTY_FUNCTION__); + @} +@}; + +int +main (void) +@{ + a ax; + ax.sub (0); + return 0; +@} +@end smallexample + +@noindent +gives this output: + +@smallexample +__FUNCTION__ = sub +__PRETTY_FUNCTION__ = void a::sub(int) +@end smallexample + +These identifiers are not preprocessor macros. In GCC 3.3 and +earlier, in C only, @code{__FUNCTION__} and @code{__PRETTY_FUNCTION__} +were treated as string literals; they could be used to initialize +@code{char} arrays, and they could be concatenated with other string +literals. GCC 3.4 and later treat them as variables, like +@code{__func__}. In C++, @code{__FUNCTION__} and +@code{__PRETTY_FUNCTION__} have always been variables. + +@node Return Address +@section Getting the Return or Frame Address of a Function + +These functions may be used to get information about the callers of a +function. + +@deftypefn {Built-in Function} {void *} __builtin_return_address (unsigned int @var{level}) +This function returns the return address of the current function, or of +one of its callers. The @var{level} argument is number of frames to +scan up the call stack. A value of @code{0} yields the return address +of the current function, a value of @code{1} yields the return address +of the caller of the current function, and so forth. When inlining +the expected behavior is that the function will return the address of +the function that will be returned to. To work around this behavior use +the @code{noinline} function attribute. + +The @var{level} argument must be a constant integer. + +On some machines it may be impossible to determine the return address of +any function other than the current one; in such cases, or when the top +of the stack has been reached, this function will return @code{0} or a +random value. In addition, @code{__builtin_frame_address} may be used +to determine if the top of the stack has been reached. + +Additional post-processing of the returned value may be needed, see +@code{__builtin_extract_return_address}. + +This function should only be used with a nonzero argument for debugging +purposes. +@end deftypefn + +@deftypefn {Built-in Function} {void *} __builtin_extract_return_address (void *@var{addr}) +The address as returned by @code{__builtin_return_address} may have to be fed +through this function to get the actual encoded address. For example, on the +31-bit S/390 platform the highest bit has to be masked out, or on SPARC +platforms an offset has to be added for the true next instruction to be +executed. + +If no fixup is needed, this function simply passes through @var{addr}. +@end deftypefn + +@deftypefn {Built-in Function} {void *} __builtin_frob_return_address (void *@var{addr}) +This function does the reverse of @code{__builtin_extract_return_address}. +@end deftypefn + +@deftypefn {Built-in Function} {void *} __builtin_frame_address (unsigned int @var{level}) +This function is similar to @code{__builtin_return_address}, but it +returns the address of the function frame rather than the return address +of the function. Calling @code{__builtin_frame_address} with a value of +@code{0} yields the frame address of the current function, a value of +@code{1} yields the frame address of the caller of the current function, +and so forth. + +The frame is the area on the stack which holds local variables and saved +registers. The frame address is normally the address of the first word +pushed on to the stack by the function. However, the exact definition +depends upon the processor and the calling convention. If the processor +has a dedicated frame pointer register, and the function has a frame, +then @code{__builtin_frame_address} will return the value of the frame +pointer register. + +On some machines it may be impossible to determine the frame address of +any function other than the current one; in such cases, or when the top +of the stack has been reached, this function will return @code{0} if +the first frame pointer is properly initialized by the startup code. + +This function should only be used with a nonzero argument for debugging +purposes. +@end deftypefn + +@node Vector Extensions +@section Using vector instructions through built-in functions + +On some targets, the instruction set contains SIMD vector instructions that +operate on multiple values contained in one large register at the same time. +For example, on the i386 the MMX, 3DNow!@: and SSE extensions can be used +this way. + +The first step in using these extensions is to provide the necessary data +types. This should be done using an appropriate @code{typedef}: + +@smallexample +typedef int v4si __attribute__ ((vector_size (16))); +@end smallexample + +The @code{int} type specifies the base type, while the attribute specifies +the vector size for the variable, measured in bytes. For example, the +declaration above causes the compiler to set the mode for the @code{v4si} +type to be 16 bytes wide and divided into @code{int} sized units. For +a 32-bit @code{int} this means a vector of 4 units of 4 bytes, and the +corresponding mode of @code{foo} will be @acronym{V4SI}. + +The @code{vector_size} attribute is only applicable to integral and +float scalars, although arrays, pointers, and function return values +are allowed in conjunction with this construct. + +All the basic integer types can be used as base types, both as signed +and as unsigned: @code{char}, @code{short}, @code{int}, @code{long}, +@code{long long}. In addition, @code{float} and @code{double} can be +used to build floating-point vector types. + +Specifying a combination that is not valid for the current architecture +will cause GCC to synthesize the instructions using a narrower mode. +For example, if you specify a variable of type @code{V4SI} and your +architecture does not allow for this specific SIMD type, GCC will +produce code that uses 4 @code{SIs}. + +The types defined in this manner can be used with a subset of normal C +operations. Currently, GCC will allow using the following operators +on these types: @code{+, -, *, /, unary minus, ^, |, &, ~, %}@. + +The operations behave like C++ @code{valarrays}. Addition is defined as +the addition of the corresponding elements of the operands. For +example, in the code below, each of the 4 elements in @var{a} will be +added to the corresponding 4 elements in @var{b} and the resulting +vector will be stored in @var{c}. + +@smallexample +typedef int v4si __attribute__ ((vector_size (16))); + +v4si a, b, c; + +c = a + b; +@end smallexample + +Subtraction, multiplication, division, and the logical operations +operate in a similar manner. Likewise, the result of using the unary +minus or complement operators on a vector type is a vector whose +elements are the negative or complemented values of the corresponding +elements in the operand. + +In C it is possible to use shifting operators @code{<<}, @code{>>} on +integer-type vectors. The operation is defined as following: @code{@{a0, +a1, @dots{}, an@} >> @{b0, b1, @dots{}, bn@} == @{a0 >> b0, a1 >> b1, +@dots{}, an >> bn@}}@. Vector operands must have the same number of +elements. Additionally second operands can be a scalar integer in which +case the scalar is converted to the type used by the vector operand (with +possible truncation) and each element of this new vector is the scalar's +value. +Consider the following code. + +@smallexample +typedef int v4si __attribute__ ((vector_size (16))); + +v4si a, b; + +b = a >> 1; /* b = a >> @{1,1,1,1@}; */ +@end smallexample + +In C vectors can be subscripted as if the vector were an array with +the same number of elements and base type. Out of bound accesses +invoke undefined behavior at runtime. Warnings for out of bound +accesses for vector subscription can be enabled with +@option{-Warray-bounds}. + +You can declare variables and use them in function calls and returns, as +well as in assignments and some casts. You can specify a vector type as +a return type for a function. Vector types can also be used as function +arguments. It is possible to cast from one vector type to another, +provided they are of the same size (in fact, you can also cast vectors +to and from other datatypes of the same size). + +You cannot operate between vectors of different lengths or different +signedness without a cast. + +A port that supports hardware vector operations, usually provides a set +of built-in functions that can be used to operate on vectors. For +example, a function to add two vectors and multiply the result by a +third could look like this: + +@smallexample +v4si f (v4si a, v4si b, v4si c) +@{ + v4si tmp = __builtin_addv4si (a, b); + return __builtin_mulv4si (tmp, c); +@} + +@end smallexample + +@node Offsetof +@section Offsetof +@findex __builtin_offsetof + +GCC implements for both C and C++ a syntactic extension to implement +the @code{offsetof} macro. + +@smallexample +primary: + "__builtin_offsetof" "(" @code{typename} "," offsetof_member_designator ")" + +offsetof_member_designator: + @code{identifier} + | offsetof_member_designator "." @code{identifier} + | offsetof_member_designator "[" @code{expr} "]" +@end smallexample + +This extension is sufficient such that + +@smallexample +#define offsetof(@var{type}, @var{member}) __builtin_offsetof (@var{type}, @var{member}) +@end smallexample + +is a suitable definition of the @code{offsetof} macro. In C++, @var{type} +may be dependent. In either case, @var{member} may consist of a single +identifier, or a sequence of member accesses and array references. + +@node Atomic Builtins +@section Built-in functions for atomic memory access + +The following builtins are intended to be compatible with those described +in the @cite{Intel Itanium Processor-specific Application Binary Interface}, +section 7.4. As such, they depart from the normal GCC practice of using +the ``__builtin_'' prefix, and further that they are overloaded such that +they work on multiple types. + +The definition given in the Intel documentation allows only for the use of +the types @code{int}, @code{long}, @code{long long} as well as their unsigned +counterparts. GCC will allow any integral scalar or pointer type that is +1, 2, 4 or 8 bytes in length. + +Not all operations are supported by all target processors. If a particular +operation cannot be implemented on the target processor, a warning will be +generated and a call an external function will be generated. The external +function will carry the same name as the builtin, with an additional suffix +@samp{_@var{n}} where @var{n} is the size of the data type. + +@c ??? Should we have a mechanism to suppress this warning? This is almost +@c useful for implementing the operation under the control of an external +@c mutex. + +In most cases, these builtins are considered a @dfn{full barrier}. That is, +no memory operand will be moved across the operation, either forward or +backward. Further, instructions will be issued as necessary to prevent the +processor from speculating loads across the operation and from queuing stores +after the operation. + +All of the routines are described in the Intel documentation to take +``an optional list of variables protected by the memory barrier''. It's +not clear what is meant by that; it could mean that @emph{only} the +following variables are protected, or it could mean that these variables +should in addition be protected. At present GCC ignores this list and +protects all variables which are globally accessible. If in the future +we make some use of this list, an empty list will continue to mean all +globally accessible variables. + +@table @code +@item @var{type} __sync_fetch_and_add (@var{type} *ptr, @var{type} value, ...) +@itemx @var{type} __sync_fetch_and_sub (@var{type} *ptr, @var{type} value, ...) +@itemx @var{type} __sync_fetch_and_or (@var{type} *ptr, @var{type} value, ...) +@itemx @var{type} __sync_fetch_and_and (@var{type} *ptr, @var{type} value, ...) +@itemx @var{type} __sync_fetch_and_xor (@var{type} *ptr, @var{type} value, ...) +@itemx @var{type} __sync_fetch_and_nand (@var{type} *ptr, @var{type} value, ...) +@findex __sync_fetch_and_add +@findex __sync_fetch_and_sub +@findex __sync_fetch_and_or +@findex __sync_fetch_and_and +@findex __sync_fetch_and_xor +@findex __sync_fetch_and_nand +These builtins perform the operation suggested by the name, and +returns the value that had previously been in memory. That is, + +@smallexample +@{ tmp = *ptr; *ptr @var{op}= value; return tmp; @} +@{ tmp = *ptr; *ptr = ~(tmp & value); return tmp; @} // nand +@end smallexample + +@emph{Note:} GCC 4.4 and later implement @code{__sync_fetch_and_nand} +builtin as @code{*ptr = ~(tmp & value)} instead of @code{*ptr = ~tmp & value}. + +@item @var{type} __sync_add_and_fetch (@var{type} *ptr, @var{type} value, ...) +@itemx @var{type} __sync_sub_and_fetch (@var{type} *ptr, @var{type} value, ...) +@itemx @var{type} __sync_or_and_fetch (@var{type} *ptr, @var{type} value, ...) +@itemx @var{type} __sync_and_and_fetch (@var{type} *ptr, @var{type} value, ...) +@itemx @var{type} __sync_xor_and_fetch (@var{type} *ptr, @var{type} value, ...) +@itemx @var{type} __sync_nand_and_fetch (@var{type} *ptr, @var{type} value, ...) +@findex __sync_add_and_fetch +@findex __sync_sub_and_fetch +@findex __sync_or_and_fetch +@findex __sync_and_and_fetch +@findex __sync_xor_and_fetch +@findex __sync_nand_and_fetch +These builtins perform the operation suggested by the name, and +return the new value. That is, + +@smallexample +@{ *ptr @var{op}= value; return *ptr; @} +@{ *ptr = ~(*ptr & value); return *ptr; @} // nand +@end smallexample + +@emph{Note:} GCC 4.4 and later implement @code{__sync_nand_and_fetch} +builtin as @code{*ptr = ~(*ptr & value)} instead of +@code{*ptr = ~*ptr & value}. + +@item bool __sync_bool_compare_and_swap (@var{type} *ptr, @var{type} oldval @var{type} newval, ...) +@itemx @var{type} __sync_val_compare_and_swap (@var{type} *ptr, @var{type} oldval @var{type} newval, ...) +@findex __sync_bool_compare_and_swap +@findex __sync_val_compare_and_swap +These builtins perform an atomic compare and swap. That is, if the current +value of @code{*@var{ptr}} is @var{oldval}, then write @var{newval} into +@code{*@var{ptr}}. + +The ``bool'' version returns true if the comparison is successful and +@var{newval} was written. The ``val'' version returns the contents +of @code{*@var{ptr}} before the operation. + +@item __sync_synchronize (...) +@findex __sync_synchronize +This builtin issues a full memory barrier. + +@item @var{type} __sync_lock_test_and_set (@var{type} *ptr, @var{type} value, ...) +@findex __sync_lock_test_and_set +This builtin, as described by Intel, is not a traditional test-and-set +operation, but rather an atomic exchange operation. It writes @var{value} +into @code{*@var{ptr}}, and returns the previous contents of +@code{*@var{ptr}}. + +Many targets have only minimal support for such locks, and do not support +a full exchange operation. In this case, a target may support reduced +functionality here by which the @emph{only} valid value to store is the +immediate constant 1. The exact value actually stored in @code{*@var{ptr}} +is implementation defined. + +This builtin is not a full barrier, but rather an @dfn{acquire barrier}. +This means that references after the builtin cannot move to (or be +speculated to) before the builtin, but previous memory stores may not +be globally visible yet, and previous memory loads may not yet be +satisfied. + +@item void __sync_lock_release (@var{type} *ptr, ...) +@findex __sync_lock_release +This builtin releases the lock acquired by @code{__sync_lock_test_and_set}. +Normally this means writing the constant 0 to @code{*@var{ptr}}. + +This builtin is not a full barrier, but rather a @dfn{release barrier}. +This means that all previous memory stores are globally visible, and all +previous memory loads have been satisfied, but following memory reads +are not prevented from being speculated to before the barrier. +@end table + +@node Object Size Checking +@section Object Size Checking Builtins +@findex __builtin_object_size +@findex __builtin___memcpy_chk +@findex __builtin___mempcpy_chk +@findex __builtin___memmove_chk +@findex __builtin___memset_chk +@findex __builtin___strcpy_chk +@findex __builtin___stpcpy_chk +@findex __builtin___strncpy_chk +@findex __builtin___strcat_chk +@findex __builtin___strncat_chk +@findex __builtin___sprintf_chk +@findex __builtin___snprintf_chk +@findex __builtin___vsprintf_chk +@findex __builtin___vsnprintf_chk +@findex __builtin___printf_chk +@findex __builtin___vprintf_chk +@findex __builtin___fprintf_chk +@findex __builtin___vfprintf_chk + +GCC implements a limited buffer overflow protection mechanism +that can prevent some buffer overflow attacks. + +@deftypefn {Built-in Function} {size_t} __builtin_object_size (void * @var{ptr}, int @var{type}) +is a built-in construct that returns a constant number of bytes from +@var{ptr} to the end of the object @var{ptr} pointer points to +(if known at compile time). @code{__builtin_object_size} never evaluates +its arguments for side-effects. If there are any side-effects in them, it +returns @code{(size_t) -1} for @var{type} 0 or 1 and @code{(size_t) 0} +for @var{type} 2 or 3. If there are multiple objects @var{ptr} can +point to and all of them are known at compile time, the returned number +is the maximum of remaining byte counts in those objects if @var{type} & 2 is +0 and minimum if nonzero. If it is not possible to determine which objects +@var{ptr} points to at compile time, @code{__builtin_object_size} should +return @code{(size_t) -1} for @var{type} 0 or 1 and @code{(size_t) 0} +for @var{type} 2 or 3. + +@var{type} is an integer constant from 0 to 3. If the least significant +bit is clear, objects are whole variables, if it is set, a closest +surrounding subobject is considered the object a pointer points to. +The second bit determines if maximum or minimum of remaining bytes +is computed. + +@smallexample +struct V @{ char buf1[10]; int b; char buf2[10]; @} var; +char *p = &var.buf1[1], *q = &var.b; + +/* Here the object p points to is var. */ +assert (__builtin_object_size (p, 0) == sizeof (var) - 1); +/* The subobject p points to is var.buf1. */ +assert (__builtin_object_size (p, 1) == sizeof (var.buf1) - 1); +/* The object q points to is var. */ +assert (__builtin_object_size (q, 0) + == (char *) (&var + 1) - (char *) &var.b); +/* The subobject q points to is var.b. */ +assert (__builtin_object_size (q, 1) == sizeof (var.b)); +@end smallexample +@end deftypefn + +There are built-in functions added for many common string operation +functions, e.g., for @code{memcpy} @code{__builtin___memcpy_chk} +built-in is provided. This built-in has an additional last argument, +which is the number of bytes remaining in object the @var{dest} +argument points to or @code{(size_t) -1} if the size is not known. + +The built-in functions are optimized into the normal string functions +like @code{memcpy} if the last argument is @code{(size_t) -1} or if +it is known at compile time that the destination object will not +be overflown. If the compiler can determine at compile time the +object will be always overflown, it issues a warning. + +The intended use can be e.g. + +@smallexample +#undef memcpy +#define bos0(dest) __builtin_object_size (dest, 0) +#define memcpy(dest, src, n) \ + __builtin___memcpy_chk (dest, src, n, bos0 (dest)) + +char *volatile p; +char buf[10]; +/* It is unknown what object p points to, so this is optimized + into plain memcpy - no checking is possible. */ +memcpy (p, "abcde", n); +/* Destination is known and length too. It is known at compile + time there will be no overflow. */ +memcpy (&buf[5], "abcde", 5); +/* Destination is known, but the length is not known at compile time. + This will result in __memcpy_chk call that can check for overflow + at runtime. */ +memcpy (&buf[5], "abcde", n); +/* Destination is known and it is known at compile time there will + be overflow. There will be a warning and __memcpy_chk call that + will abort the program at runtime. */ +memcpy (&buf[6], "abcde", 5); +@end smallexample + +Such built-in functions are provided for @code{memcpy}, @code{mempcpy}, +@code{memmove}, @code{memset}, @code{strcpy}, @code{stpcpy}, @code{strncpy}, +@code{strcat} and @code{strncat}. + +There are also checking built-in functions for formatted output functions. +@smallexample +int __builtin___sprintf_chk (char *s, int flag, size_t os, const char *fmt, ...); +int __builtin___snprintf_chk (char *s, size_t maxlen, int flag, size_t os, + const char *fmt, ...); +int __builtin___vsprintf_chk (char *s, int flag, size_t os, const char *fmt, + va_list ap); +int __builtin___vsnprintf_chk (char *s, size_t maxlen, int flag, size_t os, + const char *fmt, va_list ap); +@end smallexample + +The added @var{flag} argument is passed unchanged to @code{__sprintf_chk} +etc.@: functions and can contain implementation specific flags on what +additional security measures the checking function might take, such as +handling @code{%n} differently. + +The @var{os} argument is the object size @var{s} points to, like in the +other built-in functions. There is a small difference in the behavior +though, if @var{os} is @code{(size_t) -1}, the built-in functions are +optimized into the non-checking functions only if @var{flag} is 0, otherwise +the checking function is called with @var{os} argument set to +@code{(size_t) -1}. + +In addition to this, there are checking built-in functions +@code{__builtin___printf_chk}, @code{__builtin___vprintf_chk}, +@code{__builtin___fprintf_chk} and @code{__builtin___vfprintf_chk}. +These have just one additional argument, @var{flag}, right before +format string @var{fmt}. If the compiler is able to optimize them to +@code{fputc} etc.@: functions, it will, otherwise the checking function +should be called and the @var{flag} argument passed to it. + +@node Other Builtins +@section Other built-in functions provided by GCC +@cindex built-in functions +@findex __builtin_fpclassify +@findex __builtin_isfinite +@findex __builtin_isnormal +@findex __builtin_isgreater +@findex __builtin_isgreaterequal +@findex __builtin_isinf_sign +@findex __builtin_isless +@findex __builtin_islessequal +@findex __builtin_islessgreater +@findex __builtin_isunordered +@findex __builtin_powi +@findex __builtin_powif +@findex __builtin_powil +@findex _Exit +@findex _exit +@findex abort +@findex abs +@findex acos +@findex acosf +@findex acosh +@findex acoshf +@findex acoshl +@findex acosl +@findex alloca +@findex asin +@findex asinf +@findex asinh +@findex asinhf +@findex asinhl +@findex asinl +@findex atan +@findex atan2 +@findex atan2f +@findex atan2l +@findex atanf +@findex atanh +@findex atanhf +@findex atanhl +@findex atanl +@findex bcmp +@findex bzero +@findex cabs +@findex cabsf +@findex cabsl +@findex cacos +@findex cacosf +@findex cacosh +@findex cacoshf +@findex cacoshl +@findex cacosl +@findex calloc +@findex carg +@findex cargf +@findex cargl +@findex casin +@findex casinf +@findex casinh +@findex casinhf +@findex casinhl +@findex casinl +@findex catan +@findex catanf +@findex catanh +@findex catanhf +@findex catanhl +@findex catanl +@findex cbrt +@findex cbrtf +@findex cbrtl +@findex ccos +@findex ccosf +@findex ccosh +@findex ccoshf +@findex ccoshl +@findex ccosl +@findex ceil +@findex ceilf +@findex ceill +@findex cexp +@findex cexpf +@findex cexpl +@findex cimag +@findex cimagf +@findex cimagl +@findex clog +@findex clogf +@findex clogl +@findex conj +@findex conjf +@findex conjl +@findex copysign +@findex copysignf +@findex copysignl +@findex cos +@findex cosf +@findex cosh +@findex coshf +@findex coshl +@findex cosl +@findex cpow +@findex cpowf +@findex cpowl +@findex cproj +@findex cprojf +@findex cprojl +@findex creal +@findex crealf +@findex creall +@findex csin +@findex csinf +@findex csinh +@findex csinhf +@findex csinhl +@findex csinl +@findex csqrt +@findex csqrtf +@findex csqrtl +@findex ctan +@findex ctanf +@findex ctanh +@findex ctanhf +@findex ctanhl +@findex ctanl +@findex dcgettext +@findex dgettext +@findex drem +@findex dremf +@findex dreml +@findex erf +@findex erfc +@findex erfcf +@findex erfcl +@findex erff +@findex erfl +@findex exit +@findex exp +@findex exp10 +@findex exp10f +@findex exp10l +@findex exp2 +@findex exp2f +@findex exp2l +@findex expf +@findex expl +@findex expm1 +@findex expm1f +@findex expm1l +@findex fabs +@findex fabsf +@findex fabsl +@findex fdim +@findex fdimf +@findex fdiml +@findex ffs +@findex floor +@findex floorf +@findex floorl +@findex fma +@findex fmaf +@findex fmal +@findex fmax +@findex fmaxf +@findex fmaxl +@findex fmin +@findex fminf +@findex fminl +@findex fmod +@findex fmodf +@findex fmodl +@findex fprintf +@findex fprintf_unlocked +@findex fputs +@findex fputs_unlocked +@findex frexp +@findex frexpf +@findex frexpl +@findex fscanf +@findex gamma +@findex gammaf +@findex gammal +@findex gamma_r +@findex gammaf_r +@findex gammal_r +@findex gettext +@findex hypot +@findex hypotf +@findex hypotl +@findex ilogb +@findex ilogbf +@findex ilogbl +@findex imaxabs +@findex index +@findex isalnum +@findex isalpha +@findex isascii +@findex isblank +@findex iscntrl +@findex isdigit +@findex isgraph +@findex islower +@findex isprint +@findex ispunct +@findex isspace +@findex isupper +@findex iswalnum +@findex iswalpha +@findex iswblank +@findex iswcntrl +@findex iswdigit +@findex iswgraph +@findex iswlower +@findex iswprint +@findex iswpunct +@findex iswspace +@findex iswupper +@findex iswxdigit +@findex isxdigit +@findex j0 +@findex j0f +@findex j0l +@findex j1 +@findex j1f +@findex j1l +@findex jn +@findex jnf +@findex jnl +@findex labs +@findex ldexp +@findex ldexpf +@findex ldexpl +@findex lgamma +@findex lgammaf +@findex lgammal +@findex lgamma_r +@findex lgammaf_r +@findex lgammal_r +@findex llabs +@findex llrint +@findex llrintf +@findex llrintl +@findex llround +@findex llroundf +@findex llroundl +@findex log +@findex log10 +@findex log10f +@findex log10l +@findex log1p +@findex log1pf +@findex log1pl +@findex log2 +@findex log2f +@findex log2l +@findex logb +@findex logbf +@findex logbl +@findex logf +@findex logl +@findex lrint +@findex lrintf +@findex lrintl +@findex lround +@findex lroundf +@findex lroundl +@findex malloc +@findex memchr +@findex memcmp +@findex memcpy +@findex mempcpy +@findex memset +@findex modf +@findex modff +@findex modfl +@findex nearbyint +@findex nearbyintf +@findex nearbyintl +@findex nextafter +@findex nextafterf +@findex nextafterl +@findex nexttoward +@findex nexttowardf +@findex nexttowardl +@findex pow +@findex pow10 +@findex pow10f +@findex pow10l +@findex powf +@findex powl +@findex printf +@findex printf_unlocked +@findex putchar +@findex puts +@findex remainder +@findex remainderf +@findex remainderl +@findex remquo +@findex remquof +@findex remquol +@findex rindex +@findex rint +@findex rintf +@findex rintl +@findex round +@findex roundf +@findex roundl +@findex scalb +@findex scalbf +@findex scalbl +@findex scalbln +@findex scalblnf +@findex scalblnf +@findex scalbn +@findex scalbnf +@findex scanfnl +@findex signbit +@findex signbitf +@findex signbitl +@findex signbitd32 +@findex signbitd64 +@findex signbitd128 +@findex significand +@findex significandf +@findex significandl +@findex sin +@findex sincos +@findex sincosf +@findex sincosl +@findex sinf +@findex sinh +@findex sinhf +@findex sinhl +@findex sinl +@findex snprintf +@findex sprintf +@findex sqrt +@findex sqrtf +@findex sqrtl +@findex sscanf +@findex stpcpy +@findex stpncpy +@findex strcasecmp +@findex strcat +@findex strchr +@findex strcmp +@findex strcpy +@findex strcspn +@findex strdup +@findex strfmon +@findex strftime +@findex strlen +@findex strncasecmp +@findex strncat +@findex strncmp +@findex strncpy +@findex strndup +@findex strpbrk +@findex strrchr +@findex strspn +@findex strstr +@findex tan +@findex tanf +@findex tanh +@findex tanhf +@findex tanhl +@findex tanl +@findex tgamma +@findex tgammaf +@findex tgammal +@findex toascii +@findex tolower +@findex toupper +@findex towlower +@findex towupper +@findex trunc +@findex truncf +@findex truncl +@findex vfprintf +@findex vfscanf +@findex vprintf +@findex vscanf +@findex vsnprintf +@findex vsprintf +@findex vsscanf +@findex y0 +@findex y0f +@findex y0l +@findex y1 +@findex y1f +@findex y1l +@findex yn +@findex ynf +@findex ynl + +GCC provides a large number of built-in functions other than the ones +mentioned above. Some of these are for internal use in the processing +of exceptions or variable-length argument lists and will not be +documented here because they may change from time to time; we do not +recommend general use of these functions. + +The remaining functions are provided for optimization purposes. + +@opindex fno-builtin +GCC includes built-in versions of many of the functions in the standard +C library. The versions prefixed with @code{__builtin_} will always be +treated as having the same meaning as the C library function even if you +specify the @option{-fno-builtin} option. (@pxref{C Dialect Options}) +Many of these functions are only optimized in certain cases; if they are +not optimized in a particular case, a call to the library function will +be emitted. + +@opindex ansi +@opindex std +Outside strict ISO C mode (@option{-ansi}, @option{-std=c90}, +@option{-std=c99} or @option{-std=c1x}), the functions +@code{_exit}, @code{alloca}, @code{bcmp}, @code{bzero}, +@code{dcgettext}, @code{dgettext}, @code{dremf}, @code{dreml}, +@code{drem}, @code{exp10f}, @code{exp10l}, @code{exp10}, @code{ffsll}, +@code{ffsl}, @code{ffs}, @code{fprintf_unlocked}, +@code{fputs_unlocked}, @code{gammaf}, @code{gammal}, @code{gamma}, +@code{gammaf_r}, @code{gammal_r}, @code{gamma_r}, @code{gettext}, +@code{index}, @code{isascii}, @code{j0f}, @code{j0l}, @code{j0}, +@code{j1f}, @code{j1l}, @code{j1}, @code{jnf}, @code{jnl}, @code{jn}, +@code{lgammaf_r}, @code{lgammal_r}, @code{lgamma_r}, @code{mempcpy}, +@code{pow10f}, @code{pow10l}, @code{pow10}, @code{printf_unlocked}, +@code{rindex}, @code{scalbf}, @code{scalbl}, @code{scalb}, +@code{signbit}, @code{signbitf}, @code{signbitl}, @code{signbitd32}, +@code{signbitd64}, @code{signbitd128}, @code{significandf}, +@code{significandl}, @code{significand}, @code{sincosf}, +@code{sincosl}, @code{sincos}, @code{stpcpy}, @code{stpncpy}, +@code{strcasecmp}, @code{strdup}, @code{strfmon}, @code{strncasecmp}, +@code{strndup}, @code{toascii}, @code{y0f}, @code{y0l}, @code{y0}, +@code{y1f}, @code{y1l}, @code{y1}, @code{ynf}, @code{ynl} and +@code{yn} +may be handled as built-in functions. +All these functions have corresponding versions +prefixed with @code{__builtin_}, which may be used even in strict C90 +mode. + +The ISO C99 functions +@code{_Exit}, @code{acoshf}, @code{acoshl}, @code{acosh}, @code{asinhf}, +@code{asinhl}, @code{asinh}, @code{atanhf}, @code{atanhl}, @code{atanh}, +@code{cabsf}, @code{cabsl}, @code{cabs}, @code{cacosf}, @code{cacoshf}, +@code{cacoshl}, @code{cacosh}, @code{cacosl}, @code{cacos}, +@code{cargf}, @code{cargl}, @code{carg}, @code{casinf}, @code{casinhf}, +@code{casinhl}, @code{casinh}, @code{casinl}, @code{casin}, +@code{catanf}, @code{catanhf}, @code{catanhl}, @code{catanh}, +@code{catanl}, @code{catan}, @code{cbrtf}, @code{cbrtl}, @code{cbrt}, +@code{ccosf}, @code{ccoshf}, @code{ccoshl}, @code{ccosh}, @code{ccosl}, +@code{ccos}, @code{cexpf}, @code{cexpl}, @code{cexp}, @code{cimagf}, +@code{cimagl}, @code{cimag}, @code{clogf}, @code{clogl}, @code{clog}, +@code{conjf}, @code{conjl}, @code{conj}, @code{copysignf}, @code{copysignl}, +@code{copysign}, @code{cpowf}, @code{cpowl}, @code{cpow}, @code{cprojf}, +@code{cprojl}, @code{cproj}, @code{crealf}, @code{creall}, @code{creal}, +@code{csinf}, @code{csinhf}, @code{csinhl}, @code{csinh}, @code{csinl}, +@code{csin}, @code{csqrtf}, @code{csqrtl}, @code{csqrt}, @code{ctanf}, +@code{ctanhf}, @code{ctanhl}, @code{ctanh}, @code{ctanl}, @code{ctan}, +@code{erfcf}, @code{erfcl}, @code{erfc}, @code{erff}, @code{erfl}, +@code{erf}, @code{exp2f}, @code{exp2l}, @code{exp2}, @code{expm1f}, +@code{expm1l}, @code{expm1}, @code{fdimf}, @code{fdiml}, @code{fdim}, +@code{fmaf}, @code{fmal}, @code{fmaxf}, @code{fmaxl}, @code{fmax}, +@code{fma}, @code{fminf}, @code{fminl}, @code{fmin}, @code{hypotf}, +@code{hypotl}, @code{hypot}, @code{ilogbf}, @code{ilogbl}, @code{ilogb}, +@code{imaxabs}, @code{isblank}, @code{iswblank}, @code{lgammaf}, +@code{lgammal}, @code{lgamma}, @code{llabs}, @code{llrintf}, @code{llrintl}, +@code{llrint}, @code{llroundf}, @code{llroundl}, @code{llround}, +@code{log1pf}, @code{log1pl}, @code{log1p}, @code{log2f}, @code{log2l}, +@code{log2}, @code{logbf}, @code{logbl}, @code{logb}, @code{lrintf}, +@code{lrintl}, @code{lrint}, @code{lroundf}, @code{lroundl}, +@code{lround}, @code{nearbyintf}, @code{nearbyintl}, @code{nearbyint}, +@code{nextafterf}, @code{nextafterl}, @code{nextafter}, +@code{nexttowardf}, @code{nexttowardl}, @code{nexttoward}, +@code{remainderf}, @code{remainderl}, @code{remainder}, @code{remquof}, +@code{remquol}, @code{remquo}, @code{rintf}, @code{rintl}, @code{rint}, +@code{roundf}, @code{roundl}, @code{round}, @code{scalblnf}, +@code{scalblnl}, @code{scalbln}, @code{scalbnf}, @code{scalbnl}, +@code{scalbn}, @code{snprintf}, @code{tgammaf}, @code{tgammal}, +@code{tgamma}, @code{truncf}, @code{truncl}, @code{trunc}, +@code{vfscanf}, @code{vscanf}, @code{vsnprintf} and @code{vsscanf} +are handled as built-in functions +except in strict ISO C90 mode (@option{-ansi} or @option{-std=c90}). + +There are also built-in versions of the ISO C99 functions +@code{acosf}, @code{acosl}, @code{asinf}, @code{asinl}, @code{atan2f}, +@code{atan2l}, @code{atanf}, @code{atanl}, @code{ceilf}, @code{ceill}, +@code{cosf}, @code{coshf}, @code{coshl}, @code{cosl}, @code{expf}, +@code{expl}, @code{fabsf}, @code{fabsl}, @code{floorf}, @code{floorl}, +@code{fmodf}, @code{fmodl}, @code{frexpf}, @code{frexpl}, @code{ldexpf}, +@code{ldexpl}, @code{log10f}, @code{log10l}, @code{logf}, @code{logl}, +@code{modfl}, @code{modf}, @code{powf}, @code{powl}, @code{sinf}, +@code{sinhf}, @code{sinhl}, @code{sinl}, @code{sqrtf}, @code{sqrtl}, +@code{tanf}, @code{tanhf}, @code{tanhl} and @code{tanl} +that are recognized in any mode since ISO C90 reserves these names for +the purpose to which ISO C99 puts them. All these functions have +corresponding versions prefixed with @code{__builtin_}. + +The ISO C94 functions +@code{iswalnum}, @code{iswalpha}, @code{iswcntrl}, @code{iswdigit}, +@code{iswgraph}, @code{iswlower}, @code{iswprint}, @code{iswpunct}, +@code{iswspace}, @code{iswupper}, @code{iswxdigit}, @code{towlower} and +@code{towupper} +are handled as built-in functions +except in strict ISO C90 mode (@option{-ansi} or @option{-std=c90}). + +The ISO C90 functions +@code{abort}, @code{abs}, @code{acos}, @code{asin}, @code{atan2}, +@code{atan}, @code{calloc}, @code{ceil}, @code{cosh}, @code{cos}, +@code{exit}, @code{exp}, @code{fabs}, @code{floor}, @code{fmod}, +@code{fprintf}, @code{fputs}, @code{frexp}, @code{fscanf}, +@code{isalnum}, @code{isalpha}, @code{iscntrl}, @code{isdigit}, +@code{isgraph}, @code{islower}, @code{isprint}, @code{ispunct}, +@code{isspace}, @code{isupper}, @code{isxdigit}, @code{tolower}, +@code{toupper}, @code{labs}, @code{ldexp}, @code{log10}, @code{log}, +@code{malloc}, @code{memchr}, @code{memcmp}, @code{memcpy}, +@code{memset}, @code{modf}, @code{pow}, @code{printf}, @code{putchar}, +@code{puts}, @code{scanf}, @code{sinh}, @code{sin}, @code{snprintf}, +@code{sprintf}, @code{sqrt}, @code{sscanf}, @code{strcat}, +@code{strchr}, @code{strcmp}, @code{strcpy}, @code{strcspn}, +@code{strlen}, @code{strncat}, @code{strncmp}, @code{strncpy}, +@code{strpbrk}, @code{strrchr}, @code{strspn}, @code{strstr}, +@code{tanh}, @code{tan}, @code{vfprintf}, @code{vprintf} and @code{vsprintf} +are all recognized as built-in functions unless +@option{-fno-builtin} is specified (or @option{-fno-builtin-@var{function}} +is specified for an individual function). All of these functions have +corresponding versions prefixed with @code{__builtin_}. + +GCC provides built-in versions of the ISO C99 floating point comparison +macros that avoid raising exceptions for unordered operands. They have +the same names as the standard macros ( @code{isgreater}, +@code{isgreaterequal}, @code{isless}, @code{islessequal}, +@code{islessgreater}, and @code{isunordered}) , with @code{__builtin_} +prefixed. We intend for a library implementor to be able to simply +@code{#define} each standard macro to its built-in equivalent. +In the same fashion, GCC provides @code{fpclassify}, @code{isfinite}, +@code{isinf_sign} and @code{isnormal} built-ins used with +@code{__builtin_} prefixed. The @code{isinf} and @code{isnan} +builtins appear both with and without the @code{__builtin_} prefix. + +@deftypefn {Built-in Function} int __builtin_types_compatible_p (@var{type1}, @var{type2}) + +You can use the built-in function @code{__builtin_types_compatible_p} to +determine whether two types are the same. + +This built-in function returns 1 if the unqualified versions of the +types @var{type1} and @var{type2} (which are types, not expressions) are +compatible, 0 otherwise. The result of this built-in function can be +used in integer constant expressions. + +This built-in function ignores top level qualifiers (e.g., @code{const}, +@code{volatile}). For example, @code{int} is equivalent to @code{const +int}. + +The type @code{int[]} and @code{int[5]} are compatible. On the other +hand, @code{int} and @code{char *} are not compatible, even if the size +of their types, on the particular architecture are the same. Also, the +amount of pointer indirection is taken into account when determining +similarity. Consequently, @code{short *} is not similar to +@code{short **}. Furthermore, two types that are typedefed are +considered compatible if their underlying types are compatible. + +An @code{enum} type is not considered to be compatible with another +@code{enum} type even if both are compatible with the same integer +type; this is what the C standard specifies. +For example, @code{enum @{foo, bar@}} is not similar to +@code{enum @{hot, dog@}}. + +You would typically use this function in code whose execution varies +depending on the arguments' types. For example: + +@smallexample +#define foo(x) \ + (@{ \ + typeof (x) tmp = (x); \ + if (__builtin_types_compatible_p (typeof (x), long double)) \ + tmp = foo_long_double (tmp); \ + else if (__builtin_types_compatible_p (typeof (x), double)) \ + tmp = foo_double (tmp); \ + else if (__builtin_types_compatible_p (typeof (x), float)) \ + tmp = foo_float (tmp); \ + else \ + abort (); \ + tmp; \ + @}) +@end smallexample + +@emph{Note:} This construct is only available for C@. + +@end deftypefn + +@deftypefn {Built-in Function} @var{type} __builtin_choose_expr (@var{const_exp}, @var{exp1}, @var{exp2}) + +You can use the built-in function @code{__builtin_choose_expr} to +evaluate code depending on the value of a constant expression. This +built-in function returns @var{exp1} if @var{const_exp}, which is an +integer constant expression, is nonzero. Otherwise it returns @var{exp2}. + +This built-in function is analogous to the @samp{? :} operator in C, +except that the expression returned has its type unaltered by promotion +rules. Also, the built-in function does not evaluate the expression +that was not chosen. For example, if @var{const_exp} evaluates to true, +@var{exp2} is not evaluated even if it has side-effects. + +This built-in function can return an lvalue if the chosen argument is an +lvalue. + +If @var{exp1} is returned, the return type is the same as @var{exp1}'s +type. Similarly, if @var{exp2} is returned, its return type is the same +as @var{exp2}. + +Example: + +@smallexample +#define foo(x) \ + __builtin_choose_expr ( \ + __builtin_types_compatible_p (typeof (x), double), \ + foo_double (x), \ + __builtin_choose_expr ( \ + __builtin_types_compatible_p (typeof (x), float), \ + foo_float (x), \ + /* @r{The void expression results in a compile-time error} \ + @r{when assigning the result to something.} */ \ + (void)0)) +@end smallexample + +@emph{Note:} This construct is only available for C@. Furthermore, the +unused expression (@var{exp1} or @var{exp2} depending on the value of +@var{const_exp}) may still generate syntax errors. This may change in +future revisions. + +@end deftypefn + +@deftypefn {Built-in Function} int __builtin_constant_p (@var{exp}) +You can use the built-in function @code{__builtin_constant_p} to +determine if a value is known to be constant at compile-time and hence +that GCC can perform constant-folding on expressions involving that +value. The argument of the function is the value to test. The function +returns the integer 1 if the argument is known to be a compile-time +constant and 0 if it is not known to be a compile-time constant. A +return of 0 does not indicate that the value is @emph{not} a constant, +but merely that GCC cannot prove it is a constant with the specified +value of the @option{-O} option. + +You would typically use this function in an embedded application where +memory was a critical resource. If you have some complex calculation, +you may want it to be folded if it involves constants, but need to call +a function if it does not. For example: + +@smallexample +#define Scale_Value(X) \ + (__builtin_constant_p (X) \ + ? ((X) * SCALE + OFFSET) : Scale (X)) +@end smallexample + +You may use this built-in function in either a macro or an inline +function. However, if you use it in an inlined function and pass an +argument of the function as the argument to the built-in, GCC will +never return 1 when you call the inline function with a string constant +or compound literal (@pxref{Compound Literals}) and will not return 1 +when you pass a constant numeric value to the inline function unless you +specify the @option{-O} option. + +You may also use @code{__builtin_constant_p} in initializers for static +data. For instance, you can write + +@smallexample +static const int table[] = @{ + __builtin_constant_p (EXPRESSION) ? (EXPRESSION) : -1, + /* @r{@dots{}} */ +@}; +@end smallexample + +@noindent +This is an acceptable initializer even if @var{EXPRESSION} is not a +constant expression, including the case where +@code{__builtin_constant_p} returns 1 because @var{EXPRESSION} can be +folded to a constant but @var{EXPRESSION} contains operands that would +not otherwise be permitted in a static initializer (for example, +@code{0 && foo ()}). GCC must be more conservative about evaluating the +built-in in this case, because it has no opportunity to perform +optimization. + +Previous versions of GCC did not accept this built-in in data +initializers. The earliest version where it is completely safe is +3.0.1. +@end deftypefn + +@deftypefn {Built-in Function} long __builtin_expect (long @var{exp}, long @var{c}) +@opindex fprofile-arcs +You may use @code{__builtin_expect} to provide the compiler with +branch prediction information. In general, you should prefer to +use actual profile feedback for this (@option{-fprofile-arcs}), as +programmers are notoriously bad at predicting how their programs +actually perform. However, there are applications in which this +data is hard to collect. + +The return value is the value of @var{exp}, which should be an integral +expression. The semantics of the built-in are that it is expected that +@var{exp} == @var{c}. For example: + +@smallexample +if (__builtin_expect (x, 0)) + foo (); +@end smallexample + +@noindent +would indicate that we do not expect to call @code{foo}, since +we expect @code{x} to be zero. Since you are limited to integral +expressions for @var{exp}, you should use constructions such as + +@smallexample +if (__builtin_expect (ptr != NULL, 1)) + error (); +@end smallexample + +@noindent +when testing pointer or floating-point values. +@end deftypefn + +@deftypefn {Built-in Function} void __builtin_trap (void) +This function causes the program to exit abnormally. GCC implements +this function by using a target-dependent mechanism (such as +intentionally executing an illegal instruction) or by calling +@code{abort}. The mechanism used may vary from release to release so +you should not rely on any particular implementation. +@end deftypefn + +@deftypefn {Built-in Function} void __builtin_unreachable (void) +If control flow reaches the point of the @code{__builtin_unreachable}, +the program is undefined. It is useful in situations where the +compiler cannot deduce the unreachability of the code. + +One such case is immediately following an @code{asm} statement that +will either never terminate, or one that transfers control elsewhere +and never returns. In this example, without the +@code{__builtin_unreachable}, GCC would issue a warning that control +reaches the end of a non-void function. It would also generate code +to return after the @code{asm}. + +@smallexample +int f (int c, int v) +@{ + if (c) + @{ + return v; + @} + else + @{ + asm("jmp error_handler"); + __builtin_unreachable (); + @} +@} +@end smallexample + +Because the @code{asm} statement unconditionally transfers control out +of the function, control will never reach the end of the function +body. The @code{__builtin_unreachable} is in fact unreachable and +communicates this fact to the compiler. + +Another use for @code{__builtin_unreachable} is following a call a +function that never returns but that is not declared +@code{__attribute__((noreturn))}, as in this example: + +@smallexample +void function_that_never_returns (void); + +int g (int c) +@{ + if (c) + @{ + return 1; + @} + else + @{ + function_that_never_returns (); + __builtin_unreachable (); + @} +@} +@end smallexample + +@end deftypefn + +@deftypefn {Built-in Function} void __builtin___clear_cache (char *@var{begin}, char *@var{end}) +This function is used to flush the processor's instruction cache for +the region of memory between @var{begin} inclusive and @var{end} +exclusive. Some targets require that the instruction cache be +flushed, after modifying memory containing code, in order to obtain +deterministic behavior. + +If the target does not require instruction cache flushes, +@code{__builtin___clear_cache} has no effect. Otherwise either +instructions are emitted in-line to clear the instruction cache or a +call to the @code{__clear_cache} function in libgcc is made. +@end deftypefn + +@deftypefn {Built-in Function} void __builtin_prefetch (const void *@var{addr}, ...) +This function is used to minimize cache-miss latency by moving data into +a cache before it is accessed. +You can insert calls to @code{__builtin_prefetch} into code for which +you know addresses of data in memory that is likely to be accessed soon. +If the target supports them, data prefetch instructions will be generated. +If the prefetch is done early enough before the access then the data will +be in the cache by the time it is accessed. + +The value of @var{addr} is the address of the memory to prefetch. +There are two optional arguments, @var{rw} and @var{locality}. +The value of @var{rw} is a compile-time constant one or zero; one +means that the prefetch is preparing for a write to the memory address +and zero, the default, means that the prefetch is preparing for a read. +The value @var{locality} must be a compile-time constant integer between +zero and three. A value of zero means that the data has no temporal +locality, so it need not be left in the cache after the access. A value +of three means that the data has a high degree of temporal locality and +should be left in all levels of cache possible. Values of one and two +mean, respectively, a low or moderate degree of temporal locality. The +default is three. + +@smallexample +for (i = 0; i < n; i++) + @{ + a[i] = a[i] + b[i]; + __builtin_prefetch (&a[i+j], 1, 1); + __builtin_prefetch (&b[i+j], 0, 1); + /* @r{@dots{}} */ + @} +@end smallexample + +Data prefetch does not generate faults if @var{addr} is invalid, but +the address expression itself must be valid. For example, a prefetch +of @code{p->next} will not fault if @code{p->next} is not a valid +address, but evaluation will fault if @code{p} is not a valid address. + +If the target does not support data prefetch, the address expression +is evaluated if it includes side effects but no other code is generated +and GCC does not issue a warning. +@end deftypefn + +@deftypefn {Built-in Function} double __builtin_huge_val (void) +Returns a positive infinity, if supported by the floating-point format, +else @code{DBL_MAX}. This function is suitable for implementing the +ISO C macro @code{HUGE_VAL}. +@end deftypefn + +@deftypefn {Built-in Function} float __builtin_huge_valf (void) +Similar to @code{__builtin_huge_val}, except the return type is @code{float}. +@end deftypefn + +@deftypefn {Built-in Function} {long double} __builtin_huge_vall (void) +Similar to @code{__builtin_huge_val}, except the return +type is @code{long double}. +@end deftypefn + +@deftypefn {Built-in Function} int __builtin_fpclassify (int, int, int, int, int, ...) +This built-in implements the C99 fpclassify functionality. The first +five int arguments should be the target library's notion of the +possible FP classes and are used for return values. They must be +constant values and they must appear in this order: @code{FP_NAN}, +@code{FP_INFINITE}, @code{FP_NORMAL}, @code{FP_SUBNORMAL} and +@code{FP_ZERO}. The ellipsis is for exactly one floating point value +to classify. GCC treats the last argument as type-generic, which +means it does not do default promotion from float to double. +@end deftypefn + +@deftypefn {Built-in Function} double __builtin_inf (void) +Similar to @code{__builtin_huge_val}, except a warning is generated +if the target floating-point format does not support infinities. +@end deftypefn + +@deftypefn {Built-in Function} _Decimal32 __builtin_infd32 (void) +Similar to @code{__builtin_inf}, except the return type is @code{_Decimal32}. +@end deftypefn + +@deftypefn {Built-in Function} _Decimal64 __builtin_infd64 (void) +Similar to @code{__builtin_inf}, except the return type is @code{_Decimal64}. +@end deftypefn + +@deftypefn {Built-in Function} _Decimal128 __builtin_infd128 (void) +Similar to @code{__builtin_inf}, except the return type is @code{_Decimal128}. +@end deftypefn + +@deftypefn {Built-in Function} float __builtin_inff (void) +Similar to @code{__builtin_inf}, except the return type is @code{float}. +This function is suitable for implementing the ISO C99 macro @code{INFINITY}. +@end deftypefn + +@deftypefn {Built-in Function} {long double} __builtin_infl (void) +Similar to @code{__builtin_inf}, except the return +type is @code{long double}. +@end deftypefn + +@deftypefn {Built-in Function} int __builtin_isinf_sign (...) +Similar to @code{isinf}, except the return value will be negative for +an argument of @code{-Inf}. Note while the parameter list is an +ellipsis, this function only accepts exactly one floating point +argument. GCC treats this parameter as type-generic, which means it +does not do default promotion from float to double. +@end deftypefn + +@deftypefn {Built-in Function} double __builtin_nan (const char *str) +This is an implementation of the ISO C99 function @code{nan}. + +Since ISO C99 defines this function in terms of @code{strtod}, which we +do not implement, a description of the parsing is in order. The string +is parsed as by @code{strtol}; that is, the base is recognized by +leading @samp{0} or @samp{0x} prefixes. The number parsed is placed +in the significand such that the least significant bit of the number +is at the least significant bit of the significand. The number is +truncated to fit the significand field provided. The significand is +forced to be a quiet NaN@. + +This function, if given a string literal all of which would have been +consumed by strtol, is evaluated early enough that it is considered a +compile-time constant. +@end deftypefn + +@deftypefn {Built-in Function} _Decimal32 __builtin_nand32 (const char *str) +Similar to @code{__builtin_nan}, except the return type is @code{_Decimal32}. +@end deftypefn + +@deftypefn {Built-in Function} _Decimal64 __builtin_nand64 (const char *str) +Similar to @code{__builtin_nan}, except the return type is @code{_Decimal64}. +@end deftypefn + +@deftypefn {Built-in Function} _Decimal128 __builtin_nand128 (const char *str) +Similar to @code{__builtin_nan}, except the return type is @code{_Decimal128}. +@end deftypefn + +@deftypefn {Built-in Function} float __builtin_nanf (const char *str) +Similar to @code{__builtin_nan}, except the return type is @code{float}. +@end deftypefn + +@deftypefn {Built-in Function} {long double} __builtin_nanl (const char *str) +Similar to @code{__builtin_nan}, except the return type is @code{long double}. +@end deftypefn + +@deftypefn {Built-in Function} double __builtin_nans (const char *str) +Similar to @code{__builtin_nan}, except the significand is forced +to be a signaling NaN@. The @code{nans} function is proposed by +@uref{http://www.open-std.org/jtc1/sc22/wg14/www/docs/n965.htm,,WG14 N965}. +@end deftypefn + +@deftypefn {Built-in Function} float __builtin_nansf (const char *str) +Similar to @code{__builtin_nans}, except the return type is @code{float}. +@end deftypefn + +@deftypefn {Built-in Function} {long double} __builtin_nansl (const char *str) +Similar to @code{__builtin_nans}, except the return type is @code{long double}. +@end deftypefn + +@deftypefn {Built-in Function} int __builtin_ffs (unsigned int x) +Returns one plus the index of the least significant 1-bit of @var{x}, or +if @var{x} is zero, returns zero. +@end deftypefn + +@deftypefn {Built-in Function} int __builtin_clz (unsigned int x) +Returns the number of leading 0-bits in @var{x}, starting at the most +significant bit position. If @var{x} is 0, the result is undefined. +@end deftypefn + +@deftypefn {Built-in Function} int __builtin_ctz (unsigned int x) +Returns the number of trailing 0-bits in @var{x}, starting at the least +significant bit position. If @var{x} is 0, the result is undefined. +@end deftypefn + +@deftypefn {Built-in Function} int __builtin_popcount (unsigned int x) +Returns the number of 1-bits in @var{x}. +@end deftypefn + +@deftypefn {Built-in Function} int __builtin_parity (unsigned int x) +Returns the parity of @var{x}, i.e.@: the number of 1-bits in @var{x} +modulo 2. +@end deftypefn + +@deftypefn {Built-in Function} int __builtin_ffsl (unsigned long) +Similar to @code{__builtin_ffs}, except the argument type is +@code{unsigned long}. +@end deftypefn + +@deftypefn {Built-in Function} int __builtin_clzl (unsigned long) +Similar to @code{__builtin_clz}, except the argument type is +@code{unsigned long}. +@end deftypefn + +@deftypefn {Built-in Function} int __builtin_ctzl (unsigned long) +Similar to @code{__builtin_ctz}, except the argument type is +@code{unsigned long}. +@end deftypefn + +@deftypefn {Built-in Function} int __builtin_popcountl (unsigned long) +Similar to @code{__builtin_popcount}, except the argument type is +@code{unsigned long}. +@end deftypefn + +@deftypefn {Built-in Function} int __builtin_parityl (unsigned long) +Similar to @code{__builtin_parity}, except the argument type is +@code{unsigned long}. +@end deftypefn + +@deftypefn {Built-in Function} int __builtin_ffsll (unsigned long long) +Similar to @code{__builtin_ffs}, except the argument type is +@code{unsigned long long}. +@end deftypefn + +@deftypefn {Built-in Function} int __builtin_clzll (unsigned long long) +Similar to @code{__builtin_clz}, except the argument type is +@code{unsigned long long}. +@end deftypefn + +@deftypefn {Built-in Function} int __builtin_ctzll (unsigned long long) +Similar to @code{__builtin_ctz}, except the argument type is +@code{unsigned long long}. +@end deftypefn + +@deftypefn {Built-in Function} int __builtin_popcountll (unsigned long long) +Similar to @code{__builtin_popcount}, except the argument type is +@code{unsigned long long}. +@end deftypefn + +@deftypefn {Built-in Function} int __builtin_parityll (unsigned long long) +Similar to @code{__builtin_parity}, except the argument type is +@code{unsigned long long}. +@end deftypefn + +@deftypefn {Built-in Function} double __builtin_powi (double, int) +Returns the first argument raised to the power of the second. Unlike the +@code{pow} function no guarantees about precision and rounding are made. +@end deftypefn + +@deftypefn {Built-in Function} float __builtin_powif (float, int) +Similar to @code{__builtin_powi}, except the argument and return types +are @code{float}. +@end deftypefn + +@deftypefn {Built-in Function} {long double} __builtin_powil (long double, int) +Similar to @code{__builtin_powi}, except the argument and return types +are @code{long double}. +@end deftypefn + +@deftypefn {Built-in Function} int32_t __builtin_bswap32 (int32_t x) +Returns @var{x} with the order of the bytes reversed; for example, +@code{0xaabbccdd} becomes @code{0xddccbbaa}. Byte here always means +exactly 8 bits. +@end deftypefn + +@deftypefn {Built-in Function} int64_t __builtin_bswap64 (int64_t x) +Similar to @code{__builtin_bswap32}, except the argument and return types +are 64-bit. +@end deftypefn + +@node Target Builtins +@section Built-in Functions Specific to Particular Target Machines + +On some target machines, GCC supports many built-in functions specific +to those machines. Generally these generate calls to specific machine +instructions, but allow the compiler to schedule those calls. + +@menu +* Alpha Built-in Functions:: +* ARM iWMMXt Built-in Functions:: +* ARM NEON Intrinsics:: +* Blackfin Built-in Functions:: +* FR-V Built-in Functions:: +* X86 Built-in Functions:: +* MIPS DSP Built-in Functions:: +* MIPS Paired-Single Support:: +* MIPS Loongson Built-in Functions:: +* Other MIPS Built-in Functions:: +* picoChip Built-in Functions:: +* PowerPC AltiVec/VSX Built-in Functions:: +* RX Built-in Functions:: +* SPARC VIS Built-in Functions:: +* SPU Built-in Functions:: +@end menu + +@node Alpha Built-in Functions +@subsection Alpha Built-in Functions + +These built-in functions are available for the Alpha family of +processors, depending on the command-line switches used. + +The following built-in functions are always available. They +all generate the machine instruction that is part of the name. + +@smallexample +long __builtin_alpha_implver (void) +long __builtin_alpha_rpcc (void) +long __builtin_alpha_amask (long) +long __builtin_alpha_cmpbge (long, long) +long __builtin_alpha_extbl (long, long) +long __builtin_alpha_extwl (long, long) +long __builtin_alpha_extll (long, long) +long __builtin_alpha_extql (long, long) +long __builtin_alpha_extwh (long, long) +long __builtin_alpha_extlh (long, long) +long __builtin_alpha_extqh (long, long) +long __builtin_alpha_insbl (long, long) +long __builtin_alpha_inswl (long, long) +long __builtin_alpha_insll (long, long) +long __builtin_alpha_insql (long, long) +long __builtin_alpha_inswh (long, long) +long __builtin_alpha_inslh (long, long) +long __builtin_alpha_insqh (long, long) +long __builtin_alpha_mskbl (long, long) +long __builtin_alpha_mskwl (long, long) +long __builtin_alpha_mskll (long, long) +long __builtin_alpha_mskql (long, long) +long __builtin_alpha_mskwh (long, long) +long __builtin_alpha_msklh (long, long) +long __builtin_alpha_mskqh (long, long) +long __builtin_alpha_umulh (long, long) +long __builtin_alpha_zap (long, long) +long __builtin_alpha_zapnot (long, long) +@end smallexample + +The following built-in functions are always with @option{-mmax} +or @option{-mcpu=@var{cpu}} where @var{cpu} is @code{pca56} or +later. They all generate the machine instruction that is part +of the name. + +@smallexample +long __builtin_alpha_pklb (long) +long __builtin_alpha_pkwb (long) +long __builtin_alpha_unpkbl (long) +long __builtin_alpha_unpkbw (long) +long __builtin_alpha_minub8 (long, long) +long __builtin_alpha_minsb8 (long, long) +long __builtin_alpha_minuw4 (long, long) +long __builtin_alpha_minsw4 (long, long) +long __builtin_alpha_maxub8 (long, long) +long __builtin_alpha_maxsb8 (long, long) +long __builtin_alpha_maxuw4 (long, long) +long __builtin_alpha_maxsw4 (long, long) +long __builtin_alpha_perr (long, long) +@end smallexample + +The following built-in functions are always with @option{-mcix} +or @option{-mcpu=@var{cpu}} where @var{cpu} is @code{ev67} or +later. They all generate the machine instruction that is part +of the name. + +@smallexample +long __builtin_alpha_cttz (long) +long __builtin_alpha_ctlz (long) +long __builtin_alpha_ctpop (long) +@end smallexample + +The following builtins are available on systems that use the OSF/1 +PALcode. Normally they invoke the @code{rduniq} and @code{wruniq} +PAL calls, but when invoked with @option{-mtls-kernel}, they invoke +@code{rdval} and @code{wrval}. + +@smallexample +void *__builtin_thread_pointer (void) +void __builtin_set_thread_pointer (void *) +@end smallexample + +@node ARM iWMMXt Built-in Functions +@subsection ARM iWMMXt Built-in Functions + +These built-in functions are available for the ARM family of +processors when the @option{-mcpu=iwmmxt} switch is used: + +@smallexample +typedef int v2si __attribute__ ((vector_size (8))); +typedef short v4hi __attribute__ ((vector_size (8))); +typedef char v8qi __attribute__ ((vector_size (8))); + +int __builtin_arm_getwcx (int) +void __builtin_arm_setwcx (int, int) +int __builtin_arm_textrmsb (v8qi, int) +int __builtin_arm_textrmsh (v4hi, int) +int __builtin_arm_textrmsw (v2si, int) +int __builtin_arm_textrmub (v8qi, int) +int __builtin_arm_textrmuh (v4hi, int) +int __builtin_arm_textrmuw (v2si, int) +v8qi __builtin_arm_tinsrb (v8qi, int) +v4hi __builtin_arm_tinsrh (v4hi, int) +v2si __builtin_arm_tinsrw (v2si, int) +long long __builtin_arm_tmia (long long, int, int) +long long __builtin_arm_tmiabb (long long, int, int) +long long __builtin_arm_tmiabt (long long, int, int) +long long __builtin_arm_tmiaph (long long, int, int) +long long __builtin_arm_tmiatb (long long, int, int) +long long __builtin_arm_tmiatt (long long, int, int) +int __builtin_arm_tmovmskb (v8qi) +int __builtin_arm_tmovmskh (v4hi) +int __builtin_arm_tmovmskw (v2si) +long long __builtin_arm_waccb (v8qi) +long long __builtin_arm_wacch (v4hi) +long long __builtin_arm_waccw (v2si) +v8qi __builtin_arm_waddb (v8qi, v8qi) +v8qi __builtin_arm_waddbss (v8qi, v8qi) +v8qi __builtin_arm_waddbus (v8qi, v8qi) +v4hi __builtin_arm_waddh (v4hi, v4hi) +v4hi __builtin_arm_waddhss (v4hi, v4hi) +v4hi __builtin_arm_waddhus (v4hi, v4hi) +v2si __builtin_arm_waddw (v2si, v2si) +v2si __builtin_arm_waddwss (v2si, v2si) +v2si __builtin_arm_waddwus (v2si, v2si) +v8qi __builtin_arm_walign (v8qi, v8qi, int) +long long __builtin_arm_wand(long long, long long) +long long __builtin_arm_wandn (long long, long long) +v8qi __builtin_arm_wavg2b (v8qi, v8qi) +v8qi __builtin_arm_wavg2br (v8qi, v8qi) +v4hi __builtin_arm_wavg2h (v4hi, v4hi) +v4hi __builtin_arm_wavg2hr (v4hi, v4hi) +v8qi __builtin_arm_wcmpeqb (v8qi, v8qi) +v4hi __builtin_arm_wcmpeqh (v4hi, v4hi) +v2si __builtin_arm_wcmpeqw (v2si, v2si) +v8qi __builtin_arm_wcmpgtsb (v8qi, v8qi) +v4hi __builtin_arm_wcmpgtsh (v4hi, v4hi) +v2si __builtin_arm_wcmpgtsw (v2si, v2si) +v8qi __builtin_arm_wcmpgtub (v8qi, v8qi) +v4hi __builtin_arm_wcmpgtuh (v4hi, v4hi) +v2si __builtin_arm_wcmpgtuw (v2si, v2si) +long long __builtin_arm_wmacs (long long, v4hi, v4hi) +long long __builtin_arm_wmacsz (v4hi, v4hi) +long long __builtin_arm_wmacu (long long, v4hi, v4hi) +long long __builtin_arm_wmacuz (v4hi, v4hi) +v4hi __builtin_arm_wmadds (v4hi, v4hi) +v4hi __builtin_arm_wmaddu (v4hi, v4hi) +v8qi __builtin_arm_wmaxsb (v8qi, v8qi) +v4hi __builtin_arm_wmaxsh (v4hi, v4hi) +v2si __builtin_arm_wmaxsw (v2si, v2si) +v8qi __builtin_arm_wmaxub (v8qi, v8qi) +v4hi __builtin_arm_wmaxuh (v4hi, v4hi) +v2si __builtin_arm_wmaxuw (v2si, v2si) +v8qi __builtin_arm_wminsb (v8qi, v8qi) +v4hi __builtin_arm_wminsh (v4hi, v4hi) +v2si __builtin_arm_wminsw (v2si, v2si) +v8qi __builtin_arm_wminub (v8qi, v8qi) +v4hi __builtin_arm_wminuh (v4hi, v4hi) +v2si __builtin_arm_wminuw (v2si, v2si) +v4hi __builtin_arm_wmulsm (v4hi, v4hi) +v4hi __builtin_arm_wmulul (v4hi, v4hi) +v4hi __builtin_arm_wmulum (v4hi, v4hi) +long long __builtin_arm_wor (long long, long long) +v2si __builtin_arm_wpackdss (long long, long long) +v2si __builtin_arm_wpackdus (long long, long long) +v8qi __builtin_arm_wpackhss (v4hi, v4hi) +v8qi __builtin_arm_wpackhus (v4hi, v4hi) +v4hi __builtin_arm_wpackwss (v2si, v2si) +v4hi __builtin_arm_wpackwus (v2si, v2si) +long long __builtin_arm_wrord (long long, long long) +long long __builtin_arm_wrordi (long long, int) +v4hi __builtin_arm_wrorh (v4hi, long long) +v4hi __builtin_arm_wrorhi (v4hi, int) +v2si __builtin_arm_wrorw (v2si, long long) +v2si __builtin_arm_wrorwi (v2si, int) +v2si __builtin_arm_wsadb (v8qi, v8qi) +v2si __builtin_arm_wsadbz (v8qi, v8qi) +v2si __builtin_arm_wsadh (v4hi, v4hi) +v2si __builtin_arm_wsadhz (v4hi, v4hi) +v4hi __builtin_arm_wshufh (v4hi, int) +long long __builtin_arm_wslld (long long, long long) +long long __builtin_arm_wslldi (long long, int) +v4hi __builtin_arm_wsllh (v4hi, long long) +v4hi __builtin_arm_wsllhi (v4hi, int) +v2si __builtin_arm_wsllw (v2si, long long) +v2si __builtin_arm_wsllwi (v2si, int) +long long __builtin_arm_wsrad (long long, long long) +long long __builtin_arm_wsradi (long long, int) +v4hi __builtin_arm_wsrah (v4hi, long long) +v4hi __builtin_arm_wsrahi (v4hi, int) +v2si __builtin_arm_wsraw (v2si, long long) +v2si __builtin_arm_wsrawi (v2si, int) +long long __builtin_arm_wsrld (long long, long long) +long long __builtin_arm_wsrldi (long long, int) +v4hi __builtin_arm_wsrlh (v4hi, long long) +v4hi __builtin_arm_wsrlhi (v4hi, int) +v2si __builtin_arm_wsrlw (v2si, long long) +v2si __builtin_arm_wsrlwi (v2si, int) +v8qi __builtin_arm_wsubb (v8qi, v8qi) +v8qi __builtin_arm_wsubbss (v8qi, v8qi) +v8qi __builtin_arm_wsubbus (v8qi, v8qi) +v4hi __builtin_arm_wsubh (v4hi, v4hi) +v4hi __builtin_arm_wsubhss (v4hi, v4hi) +v4hi __builtin_arm_wsubhus (v4hi, v4hi) +v2si __builtin_arm_wsubw (v2si, v2si) +v2si __builtin_arm_wsubwss (v2si, v2si) +v2si __builtin_arm_wsubwus (v2si, v2si) +v4hi __builtin_arm_wunpckehsb (v8qi) +v2si __builtin_arm_wunpckehsh (v4hi) +long long __builtin_arm_wunpckehsw (v2si) +v4hi __builtin_arm_wunpckehub (v8qi) +v2si __builtin_arm_wunpckehuh (v4hi) +long long __builtin_arm_wunpckehuw (v2si) +v4hi __builtin_arm_wunpckelsb (v8qi) +v2si __builtin_arm_wunpckelsh (v4hi) +long long __builtin_arm_wunpckelsw (v2si) +v4hi __builtin_arm_wunpckelub (v8qi) +v2si __builtin_arm_wunpckeluh (v4hi) +long long __builtin_arm_wunpckeluw (v2si) +v8qi __builtin_arm_wunpckihb (v8qi, v8qi) +v4hi __builtin_arm_wunpckihh (v4hi, v4hi) +v2si __builtin_arm_wunpckihw (v2si, v2si) +v8qi __builtin_arm_wunpckilb (v8qi, v8qi) +v4hi __builtin_arm_wunpckilh (v4hi, v4hi) +v2si __builtin_arm_wunpckilw (v2si, v2si) +long long __builtin_arm_wxor (long long, long long) +long long __builtin_arm_wzero () +@end smallexample + +@node ARM NEON Intrinsics +@subsection ARM NEON Intrinsics + +These built-in intrinsics for the ARM Advanced SIMD extension are available +when the @option{-mfpu=neon} switch is used: + +@include arm-neon-intrinsics.texi + +@node Blackfin Built-in Functions +@subsection Blackfin Built-in Functions + +Currently, there are two Blackfin-specific built-in functions. These are +used for generating @code{CSYNC} and @code{SSYNC} machine insns without +using inline assembly; by using these built-in functions the compiler can +automatically add workarounds for hardware errata involving these +instructions. These functions are named as follows: + +@smallexample +void __builtin_bfin_csync (void) +void __builtin_bfin_ssync (void) +@end smallexample + +@node FR-V Built-in Functions +@subsection FR-V Built-in Functions + +GCC provides many FR-V-specific built-in functions. In general, +these functions are intended to be compatible with those described +by @cite{FR-V Family, Softune C/C++ Compiler Manual (V6), Fujitsu +Semiconductor}. The two exceptions are @code{__MDUNPACKH} and +@code{__MBTOHE}, the gcc forms of which pass 128-bit values by +pointer rather than by value. + +Most of the functions are named after specific FR-V instructions. +Such functions are said to be ``directly mapped'' and are summarized +here in tabular form. + +@menu +* Argument Types:: +* Directly-mapped Integer Functions:: +* Directly-mapped Media Functions:: +* Raw read/write Functions:: +* Other Built-in Functions:: +@end menu + +@node Argument Types +@subsubsection Argument Types + +The arguments to the built-in functions can be divided into three groups: +register numbers, compile-time constants and run-time values. In order +to make this classification clear at a glance, the arguments and return +values are given the following pseudo types: + +@multitable @columnfractions .20 .30 .15 .35 +@item Pseudo type @tab Real C type @tab Constant? @tab Description +@item @code{uh} @tab @code{unsigned short} @tab No @tab an unsigned halfword +@item @code{uw1} @tab @code{unsigned int} @tab No @tab an unsigned word +@item @code{sw1} @tab @code{int} @tab No @tab a signed word +@item @code{uw2} @tab @code{unsigned long long} @tab No +@tab an unsigned doubleword +@item @code{sw2} @tab @code{long long} @tab No @tab a signed doubleword +@item @code{const} @tab @code{int} @tab Yes @tab an integer constant +@item @code{acc} @tab @code{int} @tab Yes @tab an ACC register number +@item @code{iacc} @tab @code{int} @tab Yes @tab an IACC register number +@end multitable + +These pseudo types are not defined by GCC, they are simply a notational +convenience used in this manual. + +Arguments of type @code{uh}, @code{uw1}, @code{sw1}, @code{uw2} +and @code{sw2} are evaluated at run time. They correspond to +register operands in the underlying FR-V instructions. + +@code{const} arguments represent immediate operands in the underlying +FR-V instructions. They must be compile-time constants. + +@code{acc} arguments are evaluated at compile time and specify the number +of an accumulator register. For example, an @code{acc} argument of 2 +will select the ACC2 register. + +@code{iacc} arguments are similar to @code{acc} arguments but specify the +number of an IACC register. See @pxref{Other Built-in Functions} +for more details. + +@node Directly-mapped Integer Functions +@subsubsection Directly-mapped Integer Functions + +The functions listed below map directly to FR-V I-type instructions. + +@multitable @columnfractions .45 .32 .23 +@item Function prototype @tab Example usage @tab Assembly output +@item @code{sw1 __ADDSS (sw1, sw1)} +@tab @code{@var{c} = __ADDSS (@var{a}, @var{b})} +@tab @code{ADDSS @var{a},@var{b},@var{c}} +@item @code{sw1 __SCAN (sw1, sw1)} +@tab @code{@var{c} = __SCAN (@var{a}, @var{b})} +@tab @code{SCAN @var{a},@var{b},@var{c}} +@item @code{sw1 __SCUTSS (sw1)} +@tab @code{@var{b} = __SCUTSS (@var{a})} +@tab @code{SCUTSS @var{a},@var{b}} +@item @code{sw1 __SLASS (sw1, sw1)} +@tab @code{@var{c} = __SLASS (@var{a}, @var{b})} +@tab @code{SLASS @var{a},@var{b},@var{c}} +@item @code{void __SMASS (sw1, sw1)} +@tab @code{__SMASS (@var{a}, @var{b})} +@tab @code{SMASS @var{a},@var{b}} +@item @code{void __SMSSS (sw1, sw1)} +@tab @code{__SMSSS (@var{a}, @var{b})} +@tab @code{SMSSS @var{a},@var{b}} +@item @code{void __SMU (sw1, sw1)} +@tab @code{__SMU (@var{a}, @var{b})} +@tab @code{SMU @var{a},@var{b}} +@item @code{sw2 __SMUL (sw1, sw1)} +@tab @code{@var{c} = __SMUL (@var{a}, @var{b})} +@tab @code{SMUL @var{a},@var{b},@var{c}} +@item @code{sw1 __SUBSS (sw1, sw1)} +@tab @code{@var{c} = __SUBSS (@var{a}, @var{b})} +@tab @code{SUBSS @var{a},@var{b},@var{c}} +@item @code{uw2 __UMUL (uw1, uw1)} +@tab @code{@var{c} = __UMUL (@var{a}, @var{b})} +@tab @code{UMUL @var{a},@var{b},@var{c}} +@end multitable + +@node Directly-mapped Media Functions +@subsubsection Directly-mapped Media Functions + +The functions listed below map directly to FR-V M-type instructions. + +@multitable @columnfractions .45 .32 .23 +@item Function prototype @tab Example usage @tab Assembly output +@item @code{uw1 __MABSHS (sw1)} +@tab @code{@var{b} = __MABSHS (@var{a})} +@tab @code{MABSHS @var{a},@var{b}} +@item @code{void __MADDACCS (acc, acc)} +@tab @code{__MADDACCS (@var{b}, @var{a})} +@tab @code{MADDACCS @var{a},@var{b}} +@item @code{sw1 __MADDHSS (sw1, sw1)} +@tab @code{@var{c} = __MADDHSS (@var{a}, @var{b})} +@tab @code{MADDHSS @var{a},@var{b},@var{c}} +@item @code{uw1 __MADDHUS (uw1, uw1)} +@tab @code{@var{c} = __MADDHUS (@var{a}, @var{b})} +@tab @code{MADDHUS @var{a},@var{b},@var{c}} +@item @code{uw1 __MAND (uw1, uw1)} +@tab @code{@var{c} = __MAND (@var{a}, @var{b})} +@tab @code{MAND @var{a},@var{b},@var{c}} +@item @code{void __MASACCS (acc, acc)} +@tab @code{__MASACCS (@var{b}, @var{a})} +@tab @code{MASACCS @var{a},@var{b}} +@item @code{uw1 __MAVEH (uw1, uw1)} +@tab @code{@var{c} = __MAVEH (@var{a}, @var{b})} +@tab @code{MAVEH @var{a},@var{b},@var{c}} +@item @code{uw2 __MBTOH (uw1)} +@tab @code{@var{b} = __MBTOH (@var{a})} +@tab @code{MBTOH @var{a},@var{b}} +@item @code{void __MBTOHE (uw1 *, uw1)} +@tab @code{__MBTOHE (&@var{b}, @var{a})} +@tab @code{MBTOHE @var{a},@var{b}} +@item @code{void __MCLRACC (acc)} +@tab @code{__MCLRACC (@var{a})} +@tab @code{MCLRACC @var{a}} +@item @code{void __MCLRACCA (void)} +@tab @code{__MCLRACCA ()} +@tab @code{MCLRACCA} +@item @code{uw1 __Mcop1 (uw1, uw1)} +@tab @code{@var{c} = __Mcop1 (@var{a}, @var{b})} +@tab @code{Mcop1 @var{a},@var{b},@var{c}} +@item @code{uw1 __Mcop2 (uw1, uw1)} +@tab @code{@var{c} = __Mcop2 (@var{a}, @var{b})} +@tab @code{Mcop2 @var{a},@var{b},@var{c}} +@item @code{uw1 __MCPLHI (uw2, const)} +@tab @code{@var{c} = __MCPLHI (@var{a}, @var{b})} +@tab @code{MCPLHI @var{a},#@var{b},@var{c}} +@item @code{uw1 __MCPLI (uw2, const)} +@tab @code{@var{c} = __MCPLI (@var{a}, @var{b})} +@tab @code{MCPLI @var{a},#@var{b},@var{c}} +@item @code{void __MCPXIS (acc, sw1, sw1)} +@tab @code{__MCPXIS (@var{c}, @var{a}, @var{b})} +@tab @code{MCPXIS @var{a},@var{b},@var{c}} +@item @code{void __MCPXIU (acc, uw1, uw1)} +@tab @code{__MCPXIU (@var{c}, @var{a}, @var{b})} +@tab @code{MCPXIU @var{a},@var{b},@var{c}} +@item @code{void __MCPXRS (acc, sw1, sw1)} +@tab @code{__MCPXRS (@var{c}, @var{a}, @var{b})} +@tab @code{MCPXRS @var{a},@var{b},@var{c}} +@item @code{void __MCPXRU (acc, uw1, uw1)} +@tab @code{__MCPXRU (@var{c}, @var{a}, @var{b})} +@tab @code{MCPXRU @var{a},@var{b},@var{c}} +@item @code{uw1 __MCUT (acc, uw1)} +@tab @code{@var{c} = __MCUT (@var{a}, @var{b})} +@tab @code{MCUT @var{a},@var{b},@var{c}} +@item @code{uw1 __MCUTSS (acc, sw1)} +@tab @code{@var{c} = __MCUTSS (@var{a}, @var{b})} +@tab @code{MCUTSS @var{a},@var{b},@var{c}} +@item @code{void __MDADDACCS (acc, acc)} +@tab @code{__MDADDACCS (@var{b}, @var{a})} +@tab @code{MDADDACCS @var{a},@var{b}} +@item @code{void __MDASACCS (acc, acc)} +@tab @code{__MDASACCS (@var{b}, @var{a})} +@tab @code{MDASACCS @var{a},@var{b}} +@item @code{uw2 __MDCUTSSI (acc, const)} +@tab @code{@var{c} = __MDCUTSSI (@var{a}, @var{b})} +@tab @code{MDCUTSSI @var{a},#@var{b},@var{c}} +@item @code{uw2 __MDPACKH (uw2, uw2)} +@tab @code{@var{c} = __MDPACKH (@var{a}, @var{b})} +@tab @code{MDPACKH @var{a},@var{b},@var{c}} +@item @code{uw2 __MDROTLI (uw2, const)} +@tab @code{@var{c} = __MDROTLI (@var{a}, @var{b})} +@tab @code{MDROTLI @var{a},#@var{b},@var{c}} +@item @code{void __MDSUBACCS (acc, acc)} +@tab @code{__MDSUBACCS (@var{b}, @var{a})} +@tab @code{MDSUBACCS @var{a},@var{b}} +@item @code{void __MDUNPACKH (uw1 *, uw2)} +@tab @code{__MDUNPACKH (&@var{b}, @var{a})} +@tab @code{MDUNPACKH @var{a},@var{b}} +@item @code{uw2 __MEXPDHD (uw1, const)} +@tab @code{@var{c} = __MEXPDHD (@var{a}, @var{b})} +@tab @code{MEXPDHD @var{a},#@var{b},@var{c}} +@item @code{uw1 __MEXPDHW (uw1, const)} +@tab @code{@var{c} = __MEXPDHW (@var{a}, @var{b})} +@tab @code{MEXPDHW @var{a},#@var{b},@var{c}} +@item @code{uw1 __MHDSETH (uw1, const)} +@tab @code{@var{c} = __MHDSETH (@var{a}, @var{b})} +@tab @code{MHDSETH @var{a},#@var{b},@var{c}} +@item @code{sw1 __MHDSETS (const)} +@tab @code{@var{b} = __MHDSETS (@var{a})} +@tab @code{MHDSETS #@var{a},@var{b}} +@item @code{uw1 __MHSETHIH (uw1, const)} +@tab @code{@var{b} = __MHSETHIH (@var{b}, @var{a})} +@tab @code{MHSETHIH #@var{a},@var{b}} +@item @code{sw1 __MHSETHIS (sw1, const)} +@tab @code{@var{b} = __MHSETHIS (@var{b}, @var{a})} +@tab @code{MHSETHIS #@var{a},@var{b}} +@item @code{uw1 __MHSETLOH (uw1, const)} +@tab @code{@var{b} = __MHSETLOH (@var{b}, @var{a})} +@tab @code{MHSETLOH #@var{a},@var{b}} +@item @code{sw1 __MHSETLOS (sw1, const)} +@tab @code{@var{b} = __MHSETLOS (@var{b}, @var{a})} +@tab @code{MHSETLOS #@var{a},@var{b}} +@item @code{uw1 __MHTOB (uw2)} +@tab @code{@var{b} = __MHTOB (@var{a})} +@tab @code{MHTOB @var{a},@var{b}} +@item @code{void __MMACHS (acc, sw1, sw1)} +@tab @code{__MMACHS (@var{c}, @var{a}, @var{b})} +@tab @code{MMACHS @var{a},@var{b},@var{c}} +@item @code{void __MMACHU (acc, uw1, uw1)} +@tab @code{__MMACHU (@var{c}, @var{a}, @var{b})} +@tab @code{MMACHU @var{a},@var{b},@var{c}} +@item @code{void __MMRDHS (acc, sw1, sw1)} +@tab @code{__MMRDHS (@var{c}, @var{a}, @var{b})} +@tab @code{MMRDHS @var{a},@var{b},@var{c}} +@item @code{void __MMRDHU (acc, uw1, uw1)} +@tab @code{__MMRDHU (@var{c}, @var{a}, @var{b})} +@tab @code{MMRDHU @var{a},@var{b},@var{c}} +@item @code{void __MMULHS (acc, sw1, sw1)} +@tab @code{__MMULHS (@var{c}, @var{a}, @var{b})} +@tab @code{MMULHS @var{a},@var{b},@var{c}} +@item @code{void __MMULHU (acc, uw1, uw1)} +@tab @code{__MMULHU (@var{c}, @var{a}, @var{b})} +@tab @code{MMULHU @var{a},@var{b},@var{c}} +@item @code{void __MMULXHS (acc, sw1, sw1)} +@tab @code{__MMULXHS (@var{c}, @var{a}, @var{b})} +@tab @code{MMULXHS @var{a},@var{b},@var{c}} +@item @code{void __MMULXHU (acc, uw1, uw1)} +@tab @code{__MMULXHU (@var{c}, @var{a}, @var{b})} +@tab @code{MMULXHU @var{a},@var{b},@var{c}} +@item @code{uw1 __MNOT (uw1)} +@tab @code{@var{b} = __MNOT (@var{a})} +@tab @code{MNOT @var{a},@var{b}} +@item @code{uw1 __MOR (uw1, uw1)} +@tab @code{@var{c} = __MOR (@var{a}, @var{b})} +@tab @code{MOR @var{a},@var{b},@var{c}} +@item @code{uw1 __MPACKH (uh, uh)} +@tab @code{@var{c} = __MPACKH (@var{a}, @var{b})} +@tab @code{MPACKH @var{a},@var{b},@var{c}} +@item @code{sw2 __MQADDHSS (sw2, sw2)} +@tab @code{@var{c} = __MQADDHSS (@var{a}, @var{b})} +@tab @code{MQADDHSS @var{a},@var{b},@var{c}} +@item @code{uw2 __MQADDHUS (uw2, uw2)} +@tab @code{@var{c} = __MQADDHUS (@var{a}, @var{b})} +@tab @code{MQADDHUS @var{a},@var{b},@var{c}} +@item @code{void __MQCPXIS (acc, sw2, sw2)} +@tab @code{__MQCPXIS (@var{c}, @var{a}, @var{b})} +@tab @code{MQCPXIS @var{a},@var{b},@var{c}} +@item @code{void __MQCPXIU (acc, uw2, uw2)} +@tab @code{__MQCPXIU (@var{c}, @var{a}, @var{b})} +@tab @code{MQCPXIU @var{a},@var{b},@var{c}} +@item @code{void __MQCPXRS (acc, sw2, sw2)} +@tab @code{__MQCPXRS (@var{c}, @var{a}, @var{b})} +@tab @code{MQCPXRS @var{a},@var{b},@var{c}} +@item @code{void __MQCPXRU (acc, uw2, uw2)} +@tab @code{__MQCPXRU (@var{c}, @var{a}, @var{b})} +@tab @code{MQCPXRU @var{a},@var{b},@var{c}} +@item @code{sw2 __MQLCLRHS (sw2, sw2)} +@tab @code{@var{c} = __MQLCLRHS (@var{a}, @var{b})} +@tab @code{MQLCLRHS @var{a},@var{b},@var{c}} +@item @code{sw2 __MQLMTHS (sw2, sw2)} +@tab @code{@var{c} = __MQLMTHS (@var{a}, @var{b})} +@tab @code{MQLMTHS @var{a},@var{b},@var{c}} +@item @code{void __MQMACHS (acc, sw2, sw2)} +@tab @code{__MQMACHS (@var{c}, @var{a}, @var{b})} +@tab @code{MQMACHS @var{a},@var{b},@var{c}} +@item @code{void __MQMACHU (acc, uw2, uw2)} +@tab @code{__MQMACHU (@var{c}, @var{a}, @var{b})} +@tab @code{MQMACHU @var{a},@var{b},@var{c}} +@item @code{void __MQMACXHS (acc, sw2, sw2)} +@tab @code{__MQMACXHS (@var{c}, @var{a}, @var{b})} +@tab @code{MQMACXHS @var{a},@var{b},@var{c}} +@item @code{void __MQMULHS (acc, sw2, sw2)} +@tab @code{__MQMULHS (@var{c}, @var{a}, @var{b})} +@tab @code{MQMULHS @var{a},@var{b},@var{c}} +@item @code{void __MQMULHU (acc, uw2, uw2)} +@tab @code{__MQMULHU (@var{c}, @var{a}, @var{b})} +@tab @code{MQMULHU @var{a},@var{b},@var{c}} +@item @code{void __MQMULXHS (acc, sw2, sw2)} +@tab @code{__MQMULXHS (@var{c}, @var{a}, @var{b})} +@tab @code{MQMULXHS @var{a},@var{b},@var{c}} +@item @code{void __MQMULXHU (acc, uw2, uw2)} +@tab @code{__MQMULXHU (@var{c}, @var{a}, @var{b})} +@tab @code{MQMULXHU @var{a},@var{b},@var{c}} +@item @code{sw2 __MQSATHS (sw2, sw2)} +@tab @code{@var{c} = __MQSATHS (@var{a}, @var{b})} +@tab @code{MQSATHS @var{a},@var{b},@var{c}} +@item @code{uw2 __MQSLLHI (uw2, int)} +@tab @code{@var{c} = __MQSLLHI (@var{a}, @var{b})} +@tab @code{MQSLLHI @var{a},@var{b},@var{c}} +@item @code{sw2 __MQSRAHI (sw2, int)} +@tab @code{@var{c} = __MQSRAHI (@var{a}, @var{b})} +@tab @code{MQSRAHI @var{a},@var{b},@var{c}} +@item @code{sw2 __MQSUBHSS (sw2, sw2)} +@tab @code{@var{c} = __MQSUBHSS (@var{a}, @var{b})} +@tab @code{MQSUBHSS @var{a},@var{b},@var{c}} +@item @code{uw2 __MQSUBHUS (uw2, uw2)} +@tab @code{@var{c} = __MQSUBHUS (@var{a}, @var{b})} +@tab @code{MQSUBHUS @var{a},@var{b},@var{c}} +@item @code{void __MQXMACHS (acc, sw2, sw2)} +@tab @code{__MQXMACHS (@var{c}, @var{a}, @var{b})} +@tab @code{MQXMACHS @var{a},@var{b},@var{c}} +@item @code{void __MQXMACXHS (acc, sw2, sw2)} +@tab @code{__MQXMACXHS (@var{c}, @var{a}, @var{b})} +@tab @code{MQXMACXHS @var{a},@var{b},@var{c}} +@item @code{uw1 __MRDACC (acc)} +@tab @code{@var{b} = __MRDACC (@var{a})} +@tab @code{MRDACC @var{a},@var{b}} +@item @code{uw1 __MRDACCG (acc)} +@tab @code{@var{b} = __MRDACCG (@var{a})} +@tab @code{MRDACCG @var{a},@var{b}} +@item @code{uw1 __MROTLI (uw1, const)} +@tab @code{@var{c} = __MROTLI (@var{a}, @var{b})} +@tab @code{MROTLI @var{a},#@var{b},@var{c}} +@item @code{uw1 __MROTRI (uw1, const)} +@tab @code{@var{c} = __MROTRI (@var{a}, @var{b})} +@tab @code{MROTRI @var{a},#@var{b},@var{c}} +@item @code{sw1 __MSATHS (sw1, sw1)} +@tab @code{@var{c} = __MSATHS (@var{a}, @var{b})} +@tab @code{MSATHS @var{a},@var{b},@var{c}} +@item @code{uw1 __MSATHU (uw1, uw1)} +@tab @code{@var{c} = __MSATHU (@var{a}, @var{b})} +@tab @code{MSATHU @var{a},@var{b},@var{c}} +@item @code{uw1 __MSLLHI (uw1, const)} +@tab @code{@var{c} = __MSLLHI (@var{a}, @var{b})} +@tab @code{MSLLHI @var{a},#@var{b},@var{c}} +@item @code{sw1 __MSRAHI (sw1, const)} +@tab @code{@var{c} = __MSRAHI (@var{a}, @var{b})} +@tab @code{MSRAHI @var{a},#@var{b},@var{c}} +@item @code{uw1 __MSRLHI (uw1, const)} +@tab @code{@var{c} = __MSRLHI (@var{a}, @var{b})} +@tab @code{MSRLHI @var{a},#@var{b},@var{c}} +@item @code{void __MSUBACCS (acc, acc)} +@tab @code{__MSUBACCS (@var{b}, @var{a})} +@tab @code{MSUBACCS @var{a},@var{b}} +@item @code{sw1 __MSUBHSS (sw1, sw1)} +@tab @code{@var{c} = __MSUBHSS (@var{a}, @var{b})} +@tab @code{MSUBHSS @var{a},@var{b},@var{c}} +@item @code{uw1 __MSUBHUS (uw1, uw1)} +@tab @code{@var{c} = __MSUBHUS (@var{a}, @var{b})} +@tab @code{MSUBHUS @var{a},@var{b},@var{c}} +@item @code{void __MTRAP (void)} +@tab @code{__MTRAP ()} +@tab @code{MTRAP} +@item @code{uw2 __MUNPACKH (uw1)} +@tab @code{@var{b} = __MUNPACKH (@var{a})} +@tab @code{MUNPACKH @var{a},@var{b}} +@item @code{uw1 __MWCUT (uw2, uw1)} +@tab @code{@var{c} = __MWCUT (@var{a}, @var{b})} +@tab @code{MWCUT @var{a},@var{b},@var{c}} +@item @code{void __MWTACC (acc, uw1)} +@tab @code{__MWTACC (@var{b}, @var{a})} +@tab @code{MWTACC @var{a},@var{b}} +@item @code{void __MWTACCG (acc, uw1)} +@tab @code{__MWTACCG (@var{b}, @var{a})} +@tab @code{MWTACCG @var{a},@var{b}} +@item @code{uw1 __MXOR (uw1, uw1)} +@tab @code{@var{c} = __MXOR (@var{a}, @var{b})} +@tab @code{MXOR @var{a},@var{b},@var{c}} +@end multitable + +@node Raw read/write Functions +@subsubsection Raw read/write Functions + +This sections describes built-in functions related to read and write +instructions to access memory. These functions generate +@code{membar} instructions to flush the I/O load and stores where +appropriate, as described in Fujitsu's manual described above. + +@table @code + +@item unsigned char __builtin_read8 (void *@var{data}) +@item unsigned short __builtin_read16 (void *@var{data}) +@item unsigned long __builtin_read32 (void *@var{data}) +@item unsigned long long __builtin_read64 (void *@var{data}) + +@item void __builtin_write8 (void *@var{data}, unsigned char @var{datum}) +@item void __builtin_write16 (void *@var{data}, unsigned short @var{datum}) +@item void __builtin_write32 (void *@var{data}, unsigned long @var{datum}) +@item void __builtin_write64 (void *@var{data}, unsigned long long @var{datum}) +@end table + +@node Other Built-in Functions +@subsubsection Other Built-in Functions + +This section describes built-in functions that are not named after +a specific FR-V instruction. + +@table @code +@item sw2 __IACCreadll (iacc @var{reg}) +Return the full 64-bit value of IACC0@. The @var{reg} argument is reserved +for future expansion and must be 0. + +@item sw1 __IACCreadl (iacc @var{reg}) +Return the value of IACC0H if @var{reg} is 0 and IACC0L if @var{reg} is 1. +Other values of @var{reg} are rejected as invalid. + +@item void __IACCsetll (iacc @var{reg}, sw2 @var{x}) +Set the full 64-bit value of IACC0 to @var{x}. The @var{reg} argument +is reserved for future expansion and must be 0. + +@item void __IACCsetl (iacc @var{reg}, sw1 @var{x}) +Set IACC0H to @var{x} if @var{reg} is 0 and IACC0L to @var{x} if @var{reg} +is 1. Other values of @var{reg} are rejected as invalid. + +@item void __data_prefetch0 (const void *@var{x}) +Use the @code{dcpl} instruction to load the contents of address @var{x} +into the data cache. + +@item void __data_prefetch (const void *@var{x}) +Use the @code{nldub} instruction to load the contents of address @var{x} +into the data cache. The instruction will be issued in slot I1@. +@end table + +@node X86 Built-in Functions +@subsection X86 Built-in Functions + +These built-in functions are available for the i386 and x86-64 family +of computers, depending on the command-line switches used. + +Note that, if you specify command-line switches such as @option{-msse}, +the compiler could use the extended instruction sets even if the built-ins +are not used explicitly in the program. For this reason, applications +which perform runtime CPU detection must compile separate files for each +supported architecture, using the appropriate flags. In particular, +the file containing the CPU detection code should be compiled without +these options. + +The following machine modes are available for use with MMX built-in functions +(@pxref{Vector Extensions}): @code{V2SI} for a vector of two 32-bit integers, +@code{V4HI} for a vector of four 16-bit integers, and @code{V8QI} for a +vector of eight 8-bit integers. Some of the built-in functions operate on +MMX registers as a whole 64-bit entity, these use @code{V1DI} as their mode. + +If 3DNow!@: extensions are enabled, @code{V2SF} is used as a mode for a vector +of two 32-bit floating point values. + +If SSE extensions are enabled, @code{V4SF} is used for a vector of four 32-bit +floating point values. Some instructions use a vector of four 32-bit +integers, these use @code{V4SI}. Finally, some instructions operate on an +entire vector register, interpreting it as a 128-bit integer, these use mode +@code{TI}. + +In 64-bit mode, the x86-64 family of processors uses additional built-in +functions for efficient use of @code{TF} (@code{__float128}) 128-bit +floating point and @code{TC} 128-bit complex floating point values. + +The following floating point built-in functions are available in 64-bit +mode. All of them implement the function that is part of the name. + +@smallexample +__float128 __builtin_fabsq (__float128) +__float128 __builtin_copysignq (__float128, __float128) +@end smallexample + +The following floating point built-in functions are made available in the +64-bit mode. + +@table @code +@item __float128 __builtin_infq (void) +Similar to @code{__builtin_inf}, except the return type is @code{__float128}. +@findex __builtin_infq + +@item __float128 __builtin_huge_valq (void) +Similar to @code{__builtin_huge_val}, except the return type is @code{__float128}. +@findex __builtin_huge_valq +@end table + +The following built-in functions are made available by @option{-mmmx}. +All of them generate the machine instruction that is part of the name. + +@smallexample +v8qi __builtin_ia32_paddb (v8qi, v8qi) +v4hi __builtin_ia32_paddw (v4hi, v4hi) +v2si __builtin_ia32_paddd (v2si, v2si) +v8qi __builtin_ia32_psubb (v8qi, v8qi) +v4hi __builtin_ia32_psubw (v4hi, v4hi) +v2si __builtin_ia32_psubd (v2si, v2si) +v8qi __builtin_ia32_paddsb (v8qi, v8qi) +v4hi __builtin_ia32_paddsw (v4hi, v4hi) +v8qi __builtin_ia32_psubsb (v8qi, v8qi) +v4hi __builtin_ia32_psubsw (v4hi, v4hi) +v8qi __builtin_ia32_paddusb (v8qi, v8qi) +v4hi __builtin_ia32_paddusw (v4hi, v4hi) +v8qi __builtin_ia32_psubusb (v8qi, v8qi) +v4hi __builtin_ia32_psubusw (v4hi, v4hi) +v4hi __builtin_ia32_pmullw (v4hi, v4hi) +v4hi __builtin_ia32_pmulhw (v4hi, v4hi) +di __builtin_ia32_pand (di, di) +di __builtin_ia32_pandn (di,di) +di __builtin_ia32_por (di, di) +di __builtin_ia32_pxor (di, di) +v8qi __builtin_ia32_pcmpeqb (v8qi, v8qi) +v4hi __builtin_ia32_pcmpeqw (v4hi, v4hi) +v2si __builtin_ia32_pcmpeqd (v2si, v2si) +v8qi __builtin_ia32_pcmpgtb (v8qi, v8qi) +v4hi __builtin_ia32_pcmpgtw (v4hi, v4hi) +v2si __builtin_ia32_pcmpgtd (v2si, v2si) +v8qi __builtin_ia32_punpckhbw (v8qi, v8qi) +v4hi __builtin_ia32_punpckhwd (v4hi, v4hi) +v2si __builtin_ia32_punpckhdq (v2si, v2si) +v8qi __builtin_ia32_punpcklbw (v8qi, v8qi) +v4hi __builtin_ia32_punpcklwd (v4hi, v4hi) +v2si __builtin_ia32_punpckldq (v2si, v2si) +v8qi __builtin_ia32_packsswb (v4hi, v4hi) +v4hi __builtin_ia32_packssdw (v2si, v2si) +v8qi __builtin_ia32_packuswb (v4hi, v4hi) + +v4hi __builtin_ia32_psllw (v4hi, v4hi) +v2si __builtin_ia32_pslld (v2si, v2si) +v1di __builtin_ia32_psllq (v1di, v1di) +v4hi __builtin_ia32_psrlw (v4hi, v4hi) +v2si __builtin_ia32_psrld (v2si, v2si) +v1di __builtin_ia32_psrlq (v1di, v1di) +v4hi __builtin_ia32_psraw (v4hi, v4hi) +v2si __builtin_ia32_psrad (v2si, v2si) +v4hi __builtin_ia32_psllwi (v4hi, int) +v2si __builtin_ia32_pslldi (v2si, int) +v1di __builtin_ia32_psllqi (v1di, int) +v4hi __builtin_ia32_psrlwi (v4hi, int) +v2si __builtin_ia32_psrldi (v2si, int) +v1di __builtin_ia32_psrlqi (v1di, int) +v4hi __builtin_ia32_psrawi (v4hi, int) +v2si __builtin_ia32_psradi (v2si, int) + +@end smallexample + +The following built-in functions are made available either with +@option{-msse}, or with a combination of @option{-m3dnow} and +@option{-march=athlon}. All of them generate the machine +instruction that is part of the name. + +@smallexample +v4hi __builtin_ia32_pmulhuw (v4hi, v4hi) +v8qi __builtin_ia32_pavgb (v8qi, v8qi) +v4hi __builtin_ia32_pavgw (v4hi, v4hi) +v1di __builtin_ia32_psadbw (v8qi, v8qi) +v8qi __builtin_ia32_pmaxub (v8qi, v8qi) +v4hi __builtin_ia32_pmaxsw (v4hi, v4hi) +v8qi __builtin_ia32_pminub (v8qi, v8qi) +v4hi __builtin_ia32_pminsw (v4hi, v4hi) +int __builtin_ia32_pextrw (v4hi, int) +v4hi __builtin_ia32_pinsrw (v4hi, int, int) +int __builtin_ia32_pmovmskb (v8qi) +void __builtin_ia32_maskmovq (v8qi, v8qi, char *) +void __builtin_ia32_movntq (di *, di) +void __builtin_ia32_sfence (void) +@end smallexample + +The following built-in functions are available when @option{-msse} is used. +All of them generate the machine instruction that is part of the name. + +@smallexample +int __builtin_ia32_comieq (v4sf, v4sf) +int __builtin_ia32_comineq (v4sf, v4sf) +int __builtin_ia32_comilt (v4sf, v4sf) +int __builtin_ia32_comile (v4sf, v4sf) +int __builtin_ia32_comigt (v4sf, v4sf) +int __builtin_ia32_comige (v4sf, v4sf) +int __builtin_ia32_ucomieq (v4sf, v4sf) +int __builtin_ia32_ucomineq (v4sf, v4sf) +int __builtin_ia32_ucomilt (v4sf, v4sf) +int __builtin_ia32_ucomile (v4sf, v4sf) +int __builtin_ia32_ucomigt (v4sf, v4sf) +int __builtin_ia32_ucomige (v4sf, v4sf) +v4sf __builtin_ia32_addps (v4sf, v4sf) +v4sf __builtin_ia32_subps (v4sf, v4sf) +v4sf __builtin_ia32_mulps (v4sf, v4sf) +v4sf __builtin_ia32_divps (v4sf, v4sf) +v4sf __builtin_ia32_addss (v4sf, v4sf) +v4sf __builtin_ia32_subss (v4sf, v4sf) +v4sf __builtin_ia32_mulss (v4sf, v4sf) +v4sf __builtin_ia32_divss (v4sf, v4sf) +v4si __builtin_ia32_cmpeqps (v4sf, v4sf) +v4si __builtin_ia32_cmpltps (v4sf, v4sf) +v4si __builtin_ia32_cmpleps (v4sf, v4sf) +v4si __builtin_ia32_cmpgtps (v4sf, v4sf) +v4si __builtin_ia32_cmpgeps (v4sf, v4sf) +v4si __builtin_ia32_cmpunordps (v4sf, v4sf) +v4si __builtin_ia32_cmpneqps (v4sf, v4sf) +v4si __builtin_ia32_cmpnltps (v4sf, v4sf) +v4si __builtin_ia32_cmpnleps (v4sf, v4sf) +v4si __builtin_ia32_cmpngtps (v4sf, v4sf) +v4si __builtin_ia32_cmpngeps (v4sf, v4sf) +v4si __builtin_ia32_cmpordps (v4sf, v4sf) +v4si __builtin_ia32_cmpeqss (v4sf, v4sf) +v4si __builtin_ia32_cmpltss (v4sf, v4sf) +v4si __builtin_ia32_cmpless (v4sf, v4sf) +v4si __builtin_ia32_cmpunordss (v4sf, v4sf) +v4si __builtin_ia32_cmpneqss (v4sf, v4sf) +v4si __builtin_ia32_cmpnlts (v4sf, v4sf) +v4si __builtin_ia32_cmpnless (v4sf, v4sf) +v4si __builtin_ia32_cmpordss (v4sf, v4sf) +v4sf __builtin_ia32_maxps (v4sf, v4sf) +v4sf __builtin_ia32_maxss (v4sf, v4sf) +v4sf __builtin_ia32_minps (v4sf, v4sf) +v4sf __builtin_ia32_minss (v4sf, v4sf) +v4sf __builtin_ia32_andps (v4sf, v4sf) +v4sf __builtin_ia32_andnps (v4sf, v4sf) +v4sf __builtin_ia32_orps (v4sf, v4sf) +v4sf __builtin_ia32_xorps (v4sf, v4sf) +v4sf __builtin_ia32_movss (v4sf, v4sf) +v4sf __builtin_ia32_movhlps (v4sf, v4sf) +v4sf __builtin_ia32_movlhps (v4sf, v4sf) +v4sf __builtin_ia32_unpckhps (v4sf, v4sf) +v4sf __builtin_ia32_unpcklps (v4sf, v4sf) +v4sf __builtin_ia32_cvtpi2ps (v4sf, v2si) +v4sf __builtin_ia32_cvtsi2ss (v4sf, int) +v2si __builtin_ia32_cvtps2pi (v4sf) +int __builtin_ia32_cvtss2si (v4sf) +v2si __builtin_ia32_cvttps2pi (v4sf) +int __builtin_ia32_cvttss2si (v4sf) +v4sf __builtin_ia32_rcpps (v4sf) +v4sf __builtin_ia32_rsqrtps (v4sf) +v4sf __builtin_ia32_sqrtps (v4sf) +v4sf __builtin_ia32_rcpss (v4sf) +v4sf __builtin_ia32_rsqrtss (v4sf) +v4sf __builtin_ia32_sqrtss (v4sf) +v4sf __builtin_ia32_shufps (v4sf, v4sf, int) +void __builtin_ia32_movntps (float *, v4sf) +int __builtin_ia32_movmskps (v4sf) +@end smallexample + +The following built-in functions are available when @option{-msse} is used. + +@table @code +@item v4sf __builtin_ia32_loadaps (float *) +Generates the @code{movaps} machine instruction as a load from memory. +@item void __builtin_ia32_storeaps (float *, v4sf) +Generates the @code{movaps} machine instruction as a store to memory. +@item v4sf __builtin_ia32_loadups (float *) +Generates the @code{movups} machine instruction as a load from memory. +@item void __builtin_ia32_storeups (float *, v4sf) +Generates the @code{movups} machine instruction as a store to memory. +@item v4sf __builtin_ia32_loadsss (float *) +Generates the @code{movss} machine instruction as a load from memory. +@item void __builtin_ia32_storess (float *, v4sf) +Generates the @code{movss} machine instruction as a store to memory. +@item v4sf __builtin_ia32_loadhps (v4sf, const v2sf *) +Generates the @code{movhps} machine instruction as a load from memory. +@item v4sf __builtin_ia32_loadlps (v4sf, const v2sf *) +Generates the @code{movlps} machine instruction as a load from memory +@item void __builtin_ia32_storehps (v2sf *, v4sf) +Generates the @code{movhps} machine instruction as a store to memory. +@item void __builtin_ia32_storelps (v2sf *, v4sf) +Generates the @code{movlps} machine instruction as a store to memory. +@end table + +The following built-in functions are available when @option{-msse2} is used. +All of them generate the machine instruction that is part of the name. + +@smallexample +int __builtin_ia32_comisdeq (v2df, v2df) +int __builtin_ia32_comisdlt (v2df, v2df) +int __builtin_ia32_comisdle (v2df, v2df) +int __builtin_ia32_comisdgt (v2df, v2df) +int __builtin_ia32_comisdge (v2df, v2df) +int __builtin_ia32_comisdneq (v2df, v2df) +int __builtin_ia32_ucomisdeq (v2df, v2df) +int __builtin_ia32_ucomisdlt (v2df, v2df) +int __builtin_ia32_ucomisdle (v2df, v2df) +int __builtin_ia32_ucomisdgt (v2df, v2df) +int __builtin_ia32_ucomisdge (v2df, v2df) +int __builtin_ia32_ucomisdneq (v2df, v2df) +v2df __builtin_ia32_cmpeqpd (v2df, v2df) +v2df __builtin_ia32_cmpltpd (v2df, v2df) +v2df __builtin_ia32_cmplepd (v2df, v2df) +v2df __builtin_ia32_cmpgtpd (v2df, v2df) +v2df __builtin_ia32_cmpgepd (v2df, v2df) +v2df __builtin_ia32_cmpunordpd (v2df, v2df) +v2df __builtin_ia32_cmpneqpd (v2df, v2df) +v2df __builtin_ia32_cmpnltpd (v2df, v2df) +v2df __builtin_ia32_cmpnlepd (v2df, v2df) +v2df __builtin_ia32_cmpngtpd (v2df, v2df) +v2df __builtin_ia32_cmpngepd (v2df, v2df) +v2df __builtin_ia32_cmpordpd (v2df, v2df) +v2df __builtin_ia32_cmpeqsd (v2df, v2df) +v2df __builtin_ia32_cmpltsd (v2df, v2df) +v2df __builtin_ia32_cmplesd (v2df, v2df) +v2df __builtin_ia32_cmpunordsd (v2df, v2df) +v2df __builtin_ia32_cmpneqsd (v2df, v2df) +v2df __builtin_ia32_cmpnltsd (v2df, v2df) +v2df __builtin_ia32_cmpnlesd (v2df, v2df) +v2df __builtin_ia32_cmpordsd (v2df, v2df) +v2di __builtin_ia32_paddq (v2di, v2di) +v2di __builtin_ia32_psubq (v2di, v2di) +v2df __builtin_ia32_addpd (v2df, v2df) +v2df __builtin_ia32_subpd (v2df, v2df) +v2df __builtin_ia32_mulpd (v2df, v2df) +v2df __builtin_ia32_divpd (v2df, v2df) +v2df __builtin_ia32_addsd (v2df, v2df) +v2df __builtin_ia32_subsd (v2df, v2df) +v2df __builtin_ia32_mulsd (v2df, v2df) +v2df __builtin_ia32_divsd (v2df, v2df) +v2df __builtin_ia32_minpd (v2df, v2df) +v2df __builtin_ia32_maxpd (v2df, v2df) +v2df __builtin_ia32_minsd (v2df, v2df) +v2df __builtin_ia32_maxsd (v2df, v2df) +v2df __builtin_ia32_andpd (v2df, v2df) +v2df __builtin_ia32_andnpd (v2df, v2df) +v2df __builtin_ia32_orpd (v2df, v2df) +v2df __builtin_ia32_xorpd (v2df, v2df) +v2df __builtin_ia32_movsd (v2df, v2df) +v2df __builtin_ia32_unpckhpd (v2df, v2df) +v2df __builtin_ia32_unpcklpd (v2df, v2df) +v16qi __builtin_ia32_paddb128 (v16qi, v16qi) +v8hi __builtin_ia32_paddw128 (v8hi, v8hi) +v4si __builtin_ia32_paddd128 (v4si, v4si) +v2di __builtin_ia32_paddq128 (v2di, v2di) +v16qi __builtin_ia32_psubb128 (v16qi, v16qi) +v8hi __builtin_ia32_psubw128 (v8hi, v8hi) +v4si __builtin_ia32_psubd128 (v4si, v4si) +v2di __builtin_ia32_psubq128 (v2di, v2di) +v8hi __builtin_ia32_pmullw128 (v8hi, v8hi) +v8hi __builtin_ia32_pmulhw128 (v8hi, v8hi) +v2di __builtin_ia32_pand128 (v2di, v2di) +v2di __builtin_ia32_pandn128 (v2di, v2di) +v2di __builtin_ia32_por128 (v2di, v2di) +v2di __builtin_ia32_pxor128 (v2di, v2di) +v16qi __builtin_ia32_pavgb128 (v16qi, v16qi) +v8hi __builtin_ia32_pavgw128 (v8hi, v8hi) +v16qi __builtin_ia32_pcmpeqb128 (v16qi, v16qi) +v8hi __builtin_ia32_pcmpeqw128 (v8hi, v8hi) +v4si __builtin_ia32_pcmpeqd128 (v4si, v4si) +v16qi __builtin_ia32_pcmpgtb128 (v16qi, v16qi) +v8hi __builtin_ia32_pcmpgtw128 (v8hi, v8hi) +v4si __builtin_ia32_pcmpgtd128 (v4si, v4si) +v16qi __builtin_ia32_pmaxub128 (v16qi, v16qi) +v8hi __builtin_ia32_pmaxsw128 (v8hi, v8hi) +v16qi __builtin_ia32_pminub128 (v16qi, v16qi) +v8hi __builtin_ia32_pminsw128 (v8hi, v8hi) +v16qi __builtin_ia32_punpckhbw128 (v16qi, v16qi) +v8hi __builtin_ia32_punpckhwd128 (v8hi, v8hi) +v4si __builtin_ia32_punpckhdq128 (v4si, v4si) +v2di __builtin_ia32_punpckhqdq128 (v2di, v2di) +v16qi __builtin_ia32_punpcklbw128 (v16qi, v16qi) +v8hi __builtin_ia32_punpcklwd128 (v8hi, v8hi) +v4si __builtin_ia32_punpckldq128 (v4si, v4si) +v2di __builtin_ia32_punpcklqdq128 (v2di, v2di) +v16qi __builtin_ia32_packsswb128 (v8hi, v8hi) +v8hi __builtin_ia32_packssdw128 (v4si, v4si) +v16qi __builtin_ia32_packuswb128 (v8hi, v8hi) +v8hi __builtin_ia32_pmulhuw128 (v8hi, v8hi) +void __builtin_ia32_maskmovdqu (v16qi, v16qi) +v2df __builtin_ia32_loadupd (double *) +void __builtin_ia32_storeupd (double *, v2df) +v2df __builtin_ia32_loadhpd (v2df, double const *) +v2df __builtin_ia32_loadlpd (v2df, double const *) +int __builtin_ia32_movmskpd (v2df) +int __builtin_ia32_pmovmskb128 (v16qi) +void __builtin_ia32_movnti (int *, int) +void __builtin_ia32_movntpd (double *, v2df) +void __builtin_ia32_movntdq (v2df *, v2df) +v4si __builtin_ia32_pshufd (v4si, int) +v8hi __builtin_ia32_pshuflw (v8hi, int) +v8hi __builtin_ia32_pshufhw (v8hi, int) +v2di __builtin_ia32_psadbw128 (v16qi, v16qi) +v2df __builtin_ia32_sqrtpd (v2df) +v2df __builtin_ia32_sqrtsd (v2df) +v2df __builtin_ia32_shufpd (v2df, v2df, int) +v2df __builtin_ia32_cvtdq2pd (v4si) +v4sf __builtin_ia32_cvtdq2ps (v4si) +v4si __builtin_ia32_cvtpd2dq (v2df) +v2si __builtin_ia32_cvtpd2pi (v2df) +v4sf __builtin_ia32_cvtpd2ps (v2df) +v4si __builtin_ia32_cvttpd2dq (v2df) +v2si __builtin_ia32_cvttpd2pi (v2df) +v2df __builtin_ia32_cvtpi2pd (v2si) +int __builtin_ia32_cvtsd2si (v2df) +int __builtin_ia32_cvttsd2si (v2df) +long long __builtin_ia32_cvtsd2si64 (v2df) +long long __builtin_ia32_cvttsd2si64 (v2df) +v4si __builtin_ia32_cvtps2dq (v4sf) +v2df __builtin_ia32_cvtps2pd (v4sf) +v4si __builtin_ia32_cvttps2dq (v4sf) +v2df __builtin_ia32_cvtsi2sd (v2df, int) +v2df __builtin_ia32_cvtsi642sd (v2df, long long) +v4sf __builtin_ia32_cvtsd2ss (v4sf, v2df) +v2df __builtin_ia32_cvtss2sd (v2df, v4sf) +void __builtin_ia32_clflush (const void *) +void __builtin_ia32_lfence (void) +void __builtin_ia32_mfence (void) +v16qi __builtin_ia32_loaddqu (const char *) +void __builtin_ia32_storedqu (char *, v16qi) +v1di __builtin_ia32_pmuludq (v2si, v2si) +v2di __builtin_ia32_pmuludq128 (v4si, v4si) +v8hi __builtin_ia32_psllw128 (v8hi, v8hi) +v4si __builtin_ia32_pslld128 (v4si, v4si) +v2di __builtin_ia32_psllq128 (v2di, v2di) +v8hi __builtin_ia32_psrlw128 (v8hi, v8hi) +v4si __builtin_ia32_psrld128 (v4si, v4si) +v2di __builtin_ia32_psrlq128 (v2di, v2di) +v8hi __builtin_ia32_psraw128 (v8hi, v8hi) +v4si __builtin_ia32_psrad128 (v4si, v4si) +v2di __builtin_ia32_pslldqi128 (v2di, int) +v8hi __builtin_ia32_psllwi128 (v8hi, int) +v4si __builtin_ia32_pslldi128 (v4si, int) +v2di __builtin_ia32_psllqi128 (v2di, int) +v2di __builtin_ia32_psrldqi128 (v2di, int) +v8hi __builtin_ia32_psrlwi128 (v8hi, int) +v4si __builtin_ia32_psrldi128 (v4si, int) +v2di __builtin_ia32_psrlqi128 (v2di, int) +v8hi __builtin_ia32_psrawi128 (v8hi, int) +v4si __builtin_ia32_psradi128 (v4si, int) +v4si __builtin_ia32_pmaddwd128 (v8hi, v8hi) +v2di __builtin_ia32_movq128 (v2di) +@end smallexample + +The following built-in functions are available when @option{-msse3} is used. +All of them generate the machine instruction that is part of the name. + +@smallexample +v2df __builtin_ia32_addsubpd (v2df, v2df) +v4sf __builtin_ia32_addsubps (v4sf, v4sf) +v2df __builtin_ia32_haddpd (v2df, v2df) +v4sf __builtin_ia32_haddps (v4sf, v4sf) +v2df __builtin_ia32_hsubpd (v2df, v2df) +v4sf __builtin_ia32_hsubps (v4sf, v4sf) +v16qi __builtin_ia32_lddqu (char const *) +void __builtin_ia32_monitor (void *, unsigned int, unsigned int) +v2df __builtin_ia32_movddup (v2df) +v4sf __builtin_ia32_movshdup (v4sf) +v4sf __builtin_ia32_movsldup (v4sf) +void __builtin_ia32_mwait (unsigned int, unsigned int) +@end smallexample + +The following built-in functions are available when @option{-msse3} is used. + +@table @code +@item v2df __builtin_ia32_loadddup (double const *) +Generates the @code{movddup} machine instruction as a load from memory. +@end table + +The following built-in functions are available when @option{-mssse3} is used. +All of them generate the machine instruction that is part of the name +with MMX registers. + +@smallexample +v2si __builtin_ia32_phaddd (v2si, v2si) +v4hi __builtin_ia32_phaddw (v4hi, v4hi) +v4hi __builtin_ia32_phaddsw (v4hi, v4hi) +v2si __builtin_ia32_phsubd (v2si, v2si) +v4hi __builtin_ia32_phsubw (v4hi, v4hi) +v4hi __builtin_ia32_phsubsw (v4hi, v4hi) +v4hi __builtin_ia32_pmaddubsw (v8qi, v8qi) +v4hi __builtin_ia32_pmulhrsw (v4hi, v4hi) +v8qi __builtin_ia32_pshufb (v8qi, v8qi) +v8qi __builtin_ia32_psignb (v8qi, v8qi) +v2si __builtin_ia32_psignd (v2si, v2si) +v4hi __builtin_ia32_psignw (v4hi, v4hi) +v1di __builtin_ia32_palignr (v1di, v1di, int) +v8qi __builtin_ia32_pabsb (v8qi) +v2si __builtin_ia32_pabsd (v2si) +v4hi __builtin_ia32_pabsw (v4hi) +@end smallexample + +The following built-in functions are available when @option{-mssse3} is used. +All of them generate the machine instruction that is part of the name +with SSE registers. + +@smallexample +v4si __builtin_ia32_phaddd128 (v4si, v4si) +v8hi __builtin_ia32_phaddw128 (v8hi, v8hi) +v8hi __builtin_ia32_phaddsw128 (v8hi, v8hi) +v4si __builtin_ia32_phsubd128 (v4si, v4si) +v8hi __builtin_ia32_phsubw128 (v8hi, v8hi) +v8hi __builtin_ia32_phsubsw128 (v8hi, v8hi) +v8hi __builtin_ia32_pmaddubsw128 (v16qi, v16qi) +v8hi __builtin_ia32_pmulhrsw128 (v8hi, v8hi) +v16qi __builtin_ia32_pshufb128 (v16qi, v16qi) +v16qi __builtin_ia32_psignb128 (v16qi, v16qi) +v4si __builtin_ia32_psignd128 (v4si, v4si) +v8hi __builtin_ia32_psignw128 (v8hi, v8hi) +v2di __builtin_ia32_palignr128 (v2di, v2di, int) +v16qi __builtin_ia32_pabsb128 (v16qi) +v4si __builtin_ia32_pabsd128 (v4si) +v8hi __builtin_ia32_pabsw128 (v8hi) +@end smallexample + +The following built-in functions are available when @option{-msse4.1} is +used. All of them generate the machine instruction that is part of the +name. + +@smallexample +v2df __builtin_ia32_blendpd (v2df, v2df, const int) +v4sf __builtin_ia32_blendps (v4sf, v4sf, const int) +v2df __builtin_ia32_blendvpd (v2df, v2df, v2df) +v4sf __builtin_ia32_blendvps (v4sf, v4sf, v4sf) +v2df __builtin_ia32_dppd (v2df, v2df, const int) +v4sf __builtin_ia32_dpps (v4sf, v4sf, const int) +v4sf __builtin_ia32_insertps128 (v4sf, v4sf, const int) +v2di __builtin_ia32_movntdqa (v2di *); +v16qi __builtin_ia32_mpsadbw128 (v16qi, v16qi, const int) +v8hi __builtin_ia32_packusdw128 (v4si, v4si) +v16qi __builtin_ia32_pblendvb128 (v16qi, v16qi, v16qi) +v8hi __builtin_ia32_pblendw128 (v8hi, v8hi, const int) +v2di __builtin_ia32_pcmpeqq (v2di, v2di) +v8hi __builtin_ia32_phminposuw128 (v8hi) +v16qi __builtin_ia32_pmaxsb128 (v16qi, v16qi) +v4si __builtin_ia32_pmaxsd128 (v4si, v4si) +v4si __builtin_ia32_pmaxud128 (v4si, v4si) +v8hi __builtin_ia32_pmaxuw128 (v8hi, v8hi) +v16qi __builtin_ia32_pminsb128 (v16qi, v16qi) +v4si __builtin_ia32_pminsd128 (v4si, v4si) +v4si __builtin_ia32_pminud128 (v4si, v4si) +v8hi __builtin_ia32_pminuw128 (v8hi, v8hi) +v4si __builtin_ia32_pmovsxbd128 (v16qi) +v2di __builtin_ia32_pmovsxbq128 (v16qi) +v8hi __builtin_ia32_pmovsxbw128 (v16qi) +v2di __builtin_ia32_pmovsxdq128 (v4si) +v4si __builtin_ia32_pmovsxwd128 (v8hi) +v2di __builtin_ia32_pmovsxwq128 (v8hi) +v4si __builtin_ia32_pmovzxbd128 (v16qi) +v2di __builtin_ia32_pmovzxbq128 (v16qi) +v8hi __builtin_ia32_pmovzxbw128 (v16qi) +v2di __builtin_ia32_pmovzxdq128 (v4si) +v4si __builtin_ia32_pmovzxwd128 (v8hi) +v2di __builtin_ia32_pmovzxwq128 (v8hi) +v2di __builtin_ia32_pmuldq128 (v4si, v4si) +v4si __builtin_ia32_pmulld128 (v4si, v4si) +int __builtin_ia32_ptestc128 (v2di, v2di) +int __builtin_ia32_ptestnzc128 (v2di, v2di) +int __builtin_ia32_ptestz128 (v2di, v2di) +v2df __builtin_ia32_roundpd (v2df, const int) +v4sf __builtin_ia32_roundps (v4sf, const int) +v2df __builtin_ia32_roundsd (v2df, v2df, const int) +v4sf __builtin_ia32_roundss (v4sf, v4sf, const int) +@end smallexample + +The following built-in functions are available when @option{-msse4.1} is +used. + +@table @code +@item v4sf __builtin_ia32_vec_set_v4sf (v4sf, float, const int) +Generates the @code{insertps} machine instruction. +@item int __builtin_ia32_vec_ext_v16qi (v16qi, const int) +Generates the @code{pextrb} machine instruction. +@item v16qi __builtin_ia32_vec_set_v16qi (v16qi, int, const int) +Generates the @code{pinsrb} machine instruction. +@item v4si __builtin_ia32_vec_set_v4si (v4si, int, const int) +Generates the @code{pinsrd} machine instruction. +@item v2di __builtin_ia32_vec_set_v2di (v2di, long long, const int) +Generates the @code{pinsrq} machine instruction in 64bit mode. +@end table + +The following built-in functions are changed to generate new SSE4.1 +instructions when @option{-msse4.1} is used. + +@table @code +@item float __builtin_ia32_vec_ext_v4sf (v4sf, const int) +Generates the @code{extractps} machine instruction. +@item int __builtin_ia32_vec_ext_v4si (v4si, const int) +Generates the @code{pextrd} machine instruction. +@item long long __builtin_ia32_vec_ext_v2di (v2di, const int) +Generates the @code{pextrq} machine instruction in 64bit mode. +@end table + +The following built-in functions are available when @option{-msse4.2} is +used. All of them generate the machine instruction that is part of the +name. + +@smallexample +v16qi __builtin_ia32_pcmpestrm128 (v16qi, int, v16qi, int, const int) +int __builtin_ia32_pcmpestri128 (v16qi, int, v16qi, int, const int) +int __builtin_ia32_pcmpestria128 (v16qi, int, v16qi, int, const int) +int __builtin_ia32_pcmpestric128 (v16qi, int, v16qi, int, const int) +int __builtin_ia32_pcmpestrio128 (v16qi, int, v16qi, int, const int) +int __builtin_ia32_pcmpestris128 (v16qi, int, v16qi, int, const int) +int __builtin_ia32_pcmpestriz128 (v16qi, int, v16qi, int, const int) +v16qi __builtin_ia32_pcmpistrm128 (v16qi, v16qi, const int) +int __builtin_ia32_pcmpistri128 (v16qi, v16qi, const int) +int __builtin_ia32_pcmpistria128 (v16qi, v16qi, const int) +int __builtin_ia32_pcmpistric128 (v16qi, v16qi, const int) +int __builtin_ia32_pcmpistrio128 (v16qi, v16qi, const int) +int __builtin_ia32_pcmpistris128 (v16qi, v16qi, const int) +int __builtin_ia32_pcmpistriz128 (v16qi, v16qi, const int) +v2di __builtin_ia32_pcmpgtq (v2di, v2di) +@end smallexample + +The following built-in functions are available when @option{-msse4.2} is +used. + +@table @code +@item unsigned int __builtin_ia32_crc32qi (unsigned int, unsigned char) +Generates the @code{crc32b} machine instruction. +@item unsigned int __builtin_ia32_crc32hi (unsigned int, unsigned short) +Generates the @code{crc32w} machine instruction. +@item unsigned int __builtin_ia32_crc32si (unsigned int, unsigned int) +Generates the @code{crc32l} machine instruction. +@item unsigned long long __builtin_ia32_crc32di (unsigned long long, unsigned long long) +Generates the @code{crc32q} machine instruction. +@end table + +The following built-in functions are changed to generate new SSE4.2 +instructions when @option{-msse4.2} is used. + +@table @code +@item int __builtin_popcount (unsigned int) +Generates the @code{popcntl} machine instruction. +@item int __builtin_popcountl (unsigned long) +Generates the @code{popcntl} or @code{popcntq} machine instruction, +depending on the size of @code{unsigned long}. +@item int __builtin_popcountll (unsigned long long) +Generates the @code{popcntq} machine instruction. +@end table + +The following built-in functions are available when @option{-mavx} is +used. All of them generate the machine instruction that is part of the +name. + +@smallexample +v4df __builtin_ia32_addpd256 (v4df,v4df) +v8sf __builtin_ia32_addps256 (v8sf,v8sf) +v4df __builtin_ia32_addsubpd256 (v4df,v4df) +v8sf __builtin_ia32_addsubps256 (v8sf,v8sf) +v4df __builtin_ia32_andnpd256 (v4df,v4df) +v8sf __builtin_ia32_andnps256 (v8sf,v8sf) +v4df __builtin_ia32_andpd256 (v4df,v4df) +v8sf __builtin_ia32_andps256 (v8sf,v8sf) +v4df __builtin_ia32_blendpd256 (v4df,v4df,int) +v8sf __builtin_ia32_blendps256 (v8sf,v8sf,int) +v4df __builtin_ia32_blendvpd256 (v4df,v4df,v4df) +v8sf __builtin_ia32_blendvps256 (v8sf,v8sf,v8sf) +v2df __builtin_ia32_cmppd (v2df,v2df,int) +v4df __builtin_ia32_cmppd256 (v4df,v4df,int) +v4sf __builtin_ia32_cmpps (v4sf,v4sf,int) +v8sf __builtin_ia32_cmpps256 (v8sf,v8sf,int) +v2df __builtin_ia32_cmpsd (v2df,v2df,int) +v4sf __builtin_ia32_cmpss (v4sf,v4sf,int) +v4df __builtin_ia32_cvtdq2pd256 (v4si) +v8sf __builtin_ia32_cvtdq2ps256 (v8si) +v4si __builtin_ia32_cvtpd2dq256 (v4df) +v4sf __builtin_ia32_cvtpd2ps256 (v4df) +v8si __builtin_ia32_cvtps2dq256 (v8sf) +v4df __builtin_ia32_cvtps2pd256 (v4sf) +v4si __builtin_ia32_cvttpd2dq256 (v4df) +v8si __builtin_ia32_cvttps2dq256 (v8sf) +v4df __builtin_ia32_divpd256 (v4df,v4df) +v8sf __builtin_ia32_divps256 (v8sf,v8sf) +v8sf __builtin_ia32_dpps256 (v8sf,v8sf,int) +v4df __builtin_ia32_haddpd256 (v4df,v4df) +v8sf __builtin_ia32_haddps256 (v8sf,v8sf) +v4df __builtin_ia32_hsubpd256 (v4df,v4df) +v8sf __builtin_ia32_hsubps256 (v8sf,v8sf) +v32qi __builtin_ia32_lddqu256 (pcchar) +v32qi __builtin_ia32_loaddqu256 (pcchar) +v4df __builtin_ia32_loadupd256 (pcdouble) +v8sf __builtin_ia32_loadups256 (pcfloat) +v2df __builtin_ia32_maskloadpd (pcv2df,v2df) +v4df __builtin_ia32_maskloadpd256 (pcv4df,v4df) +v4sf __builtin_ia32_maskloadps (pcv4sf,v4sf) +v8sf __builtin_ia32_maskloadps256 (pcv8sf,v8sf) +void __builtin_ia32_maskstorepd (pv2df,v2df,v2df) +void __builtin_ia32_maskstorepd256 (pv4df,v4df,v4df) +void __builtin_ia32_maskstoreps (pv4sf,v4sf,v4sf) +void __builtin_ia32_maskstoreps256 (pv8sf,v8sf,v8sf) +v4df __builtin_ia32_maxpd256 (v4df,v4df) +v8sf __builtin_ia32_maxps256 (v8sf,v8sf) +v4df __builtin_ia32_minpd256 (v4df,v4df) +v8sf __builtin_ia32_minps256 (v8sf,v8sf) +v4df __builtin_ia32_movddup256 (v4df) +int __builtin_ia32_movmskpd256 (v4df) +int __builtin_ia32_movmskps256 (v8sf) +v8sf __builtin_ia32_movshdup256 (v8sf) +v8sf __builtin_ia32_movsldup256 (v8sf) +v4df __builtin_ia32_mulpd256 (v4df,v4df) +v8sf __builtin_ia32_mulps256 (v8sf,v8sf) +v4df __builtin_ia32_orpd256 (v4df,v4df) +v8sf __builtin_ia32_orps256 (v8sf,v8sf) +v2df __builtin_ia32_pd_pd256 (v4df) +v4df __builtin_ia32_pd256_pd (v2df) +v4sf __builtin_ia32_ps_ps256 (v8sf) +v8sf __builtin_ia32_ps256_ps (v4sf) +int __builtin_ia32_ptestc256 (v4di,v4di,ptest) +int __builtin_ia32_ptestnzc256 (v4di,v4di,ptest) +int __builtin_ia32_ptestz256 (v4di,v4di,ptest) +v8sf __builtin_ia32_rcpps256 (v8sf) +v4df __builtin_ia32_roundpd256 (v4df,int) +v8sf __builtin_ia32_roundps256 (v8sf,int) +v8sf __builtin_ia32_rsqrtps_nr256 (v8sf) +v8sf __builtin_ia32_rsqrtps256 (v8sf) +v4df __builtin_ia32_shufpd256 (v4df,v4df,int) +v8sf __builtin_ia32_shufps256 (v8sf,v8sf,int) +v4si __builtin_ia32_si_si256 (v8si) +v8si __builtin_ia32_si256_si (v4si) +v4df __builtin_ia32_sqrtpd256 (v4df) +v8sf __builtin_ia32_sqrtps_nr256 (v8sf) +v8sf __builtin_ia32_sqrtps256 (v8sf) +void __builtin_ia32_storedqu256 (pchar,v32qi) +void __builtin_ia32_storeupd256 (pdouble,v4df) +void __builtin_ia32_storeups256 (pfloat,v8sf) +v4df __builtin_ia32_subpd256 (v4df,v4df) +v8sf __builtin_ia32_subps256 (v8sf,v8sf) +v4df __builtin_ia32_unpckhpd256 (v4df,v4df) +v8sf __builtin_ia32_unpckhps256 (v8sf,v8sf) +v4df __builtin_ia32_unpcklpd256 (v4df,v4df) +v8sf __builtin_ia32_unpcklps256 (v8sf,v8sf) +v4df __builtin_ia32_vbroadcastf128_pd256 (pcv2df) +v8sf __builtin_ia32_vbroadcastf128_ps256 (pcv4sf) +v4df __builtin_ia32_vbroadcastsd256 (pcdouble) +v4sf __builtin_ia32_vbroadcastss (pcfloat) +v8sf __builtin_ia32_vbroadcastss256 (pcfloat) +v2df __builtin_ia32_vextractf128_pd256 (v4df,int) +v4sf __builtin_ia32_vextractf128_ps256 (v8sf,int) +v4si __builtin_ia32_vextractf128_si256 (v8si,int) +v4df __builtin_ia32_vinsertf128_pd256 (v4df,v2df,int) +v8sf __builtin_ia32_vinsertf128_ps256 (v8sf,v4sf,int) +v8si __builtin_ia32_vinsertf128_si256 (v8si,v4si,int) +v4df __builtin_ia32_vperm2f128_pd256 (v4df,v4df,int) +v8sf __builtin_ia32_vperm2f128_ps256 (v8sf,v8sf,int) +v8si __builtin_ia32_vperm2f128_si256 (v8si,v8si,int) +v2df __builtin_ia32_vpermil2pd (v2df,v2df,v2di,int) +v4df __builtin_ia32_vpermil2pd256 (v4df,v4df,v4di,int) +v4sf __builtin_ia32_vpermil2ps (v4sf,v4sf,v4si,int) +v8sf __builtin_ia32_vpermil2ps256 (v8sf,v8sf,v8si,int) +v2df __builtin_ia32_vpermilpd (v2df,int) +v4df __builtin_ia32_vpermilpd256 (v4df,int) +v4sf __builtin_ia32_vpermilps (v4sf,int) +v8sf __builtin_ia32_vpermilps256 (v8sf,int) +v2df __builtin_ia32_vpermilvarpd (v2df,v2di) +v4df __builtin_ia32_vpermilvarpd256 (v4df,v4di) +v4sf __builtin_ia32_vpermilvarps (v4sf,v4si) +v8sf __builtin_ia32_vpermilvarps256 (v8sf,v8si) +int __builtin_ia32_vtestcpd (v2df,v2df,ptest) +int __builtin_ia32_vtestcpd256 (v4df,v4df,ptest) +int __builtin_ia32_vtestcps (v4sf,v4sf,ptest) +int __builtin_ia32_vtestcps256 (v8sf,v8sf,ptest) +int __builtin_ia32_vtestnzcpd (v2df,v2df,ptest) +int __builtin_ia32_vtestnzcpd256 (v4df,v4df,ptest) +int __builtin_ia32_vtestnzcps (v4sf,v4sf,ptest) +int __builtin_ia32_vtestnzcps256 (v8sf,v8sf,ptest) +int __builtin_ia32_vtestzpd (v2df,v2df,ptest) +int __builtin_ia32_vtestzpd256 (v4df,v4df,ptest) +int __builtin_ia32_vtestzps (v4sf,v4sf,ptest) +int __builtin_ia32_vtestzps256 (v8sf,v8sf,ptest) +void __builtin_ia32_vzeroall (void) +void __builtin_ia32_vzeroupper (void) +v4df __builtin_ia32_xorpd256 (v4df,v4df) +v8sf __builtin_ia32_xorps256 (v8sf,v8sf) +@end smallexample + +The following built-in functions are available when @option{-maes} is +used. All of them generate the machine instruction that is part of the +name. + +@smallexample +v2di __builtin_ia32_aesenc128 (v2di, v2di) +v2di __builtin_ia32_aesenclast128 (v2di, v2di) +v2di __builtin_ia32_aesdec128 (v2di, v2di) +v2di __builtin_ia32_aesdeclast128 (v2di, v2di) +v2di __builtin_ia32_aeskeygenassist128 (v2di, const int) +v2di __builtin_ia32_aesimc128 (v2di) +@end smallexample + +The following built-in function is available when @option{-mpclmul} is +used. + +@table @code +@item v2di __builtin_ia32_pclmulqdq128 (v2di, v2di, const int) +Generates the @code{pclmulqdq} machine instruction. +@end table + +The following built-in function is available when @option{-mfsgsbase} is +used. All of them generate the machine instruction that is part of the +name. + +@smallexample +unsigned int __builtin_ia32_rdfsbase32 (void) +unsigned long long __builtin_ia32_rdfsbase64 (void) +unsigned int __builtin_ia32_rdgsbase32 (void) +unsigned long long __builtin_ia32_rdgsbase64 (void) +void _writefsbase_u32 (unsigned int) +void _writefsbase_u64 (unsigned long long) +void _writegsbase_u32 (unsigned int) +void _writegsbase_u64 (unsigned long long) +@end smallexample + +The following built-in function is available when @option{-mrdrnd} is +used. All of them generate the machine instruction that is part of the +name. + +@smallexample +unsigned int __builtin_ia32_rdrand16_step (unsigned short *) +unsigned int __builtin_ia32_rdrand32_step (unsigned int *) +unsigned int __builtin_ia32_rdrand64_step (unsigned long long *) +@end smallexample + +The following built-in functions are available when @option{-msse4a} is used. +All of them generate the machine instruction that is part of the name. + +@smallexample +void __builtin_ia32_movntsd (double *, v2df) +void __builtin_ia32_movntss (float *, v4sf) +v2di __builtin_ia32_extrq (v2di, v16qi) +v2di __builtin_ia32_extrqi (v2di, const unsigned int, const unsigned int) +v2di __builtin_ia32_insertq (v2di, v2di) +v2di __builtin_ia32_insertqi (v2di, v2di, const unsigned int, const unsigned int) +@end smallexample + +The following built-in functions are available when @option{-mxop} is used. +@smallexample +v2df __builtin_ia32_vfrczpd (v2df) +v4sf __builtin_ia32_vfrczps (v4sf) +v2df __builtin_ia32_vfrczsd (v2df, v2df) +v4sf __builtin_ia32_vfrczss (v4sf, v4sf) +v4df __builtin_ia32_vfrczpd256 (v4df) +v8sf __builtin_ia32_vfrczps256 (v8sf) +v2di __builtin_ia32_vpcmov (v2di, v2di, v2di) +v2di __builtin_ia32_vpcmov_v2di (v2di, v2di, v2di) +v4si __builtin_ia32_vpcmov_v4si (v4si, v4si, v4si) +v8hi __builtin_ia32_vpcmov_v8hi (v8hi, v8hi, v8hi) +v16qi __builtin_ia32_vpcmov_v16qi (v16qi, v16qi, v16qi) +v2df __builtin_ia32_vpcmov_v2df (v2df, v2df, v2df) +v4sf __builtin_ia32_vpcmov_v4sf (v4sf, v4sf, v4sf) +v4di __builtin_ia32_vpcmov_v4di256 (v4di, v4di, v4di) +v8si __builtin_ia32_vpcmov_v8si256 (v8si, v8si, v8si) +v16hi __builtin_ia32_vpcmov_v16hi256 (v16hi, v16hi, v16hi) +v32qi __builtin_ia32_vpcmov_v32qi256 (v32qi, v32qi, v32qi) +v4df __builtin_ia32_vpcmov_v4df256 (v4df, v4df, v4df) +v8sf __builtin_ia32_vpcmov_v8sf256 (v8sf, v8sf, v8sf) +v16qi __builtin_ia32_vpcomeqb (v16qi, v16qi) +v8hi __builtin_ia32_vpcomeqw (v8hi, v8hi) +v4si __builtin_ia32_vpcomeqd (v4si, v4si) +v2di __builtin_ia32_vpcomeqq (v2di, v2di) +v16qi __builtin_ia32_vpcomequb (v16qi, v16qi) +v4si __builtin_ia32_vpcomequd (v4si, v4si) +v2di __builtin_ia32_vpcomequq (v2di, v2di) +v8hi __builtin_ia32_vpcomequw (v8hi, v8hi) +v8hi __builtin_ia32_vpcomeqw (v8hi, v8hi) +v16qi __builtin_ia32_vpcomfalseb (v16qi, v16qi) +v4si __builtin_ia32_vpcomfalsed (v4si, v4si) +v2di __builtin_ia32_vpcomfalseq (v2di, v2di) +v16qi __builtin_ia32_vpcomfalseub (v16qi, v16qi) +v4si __builtin_ia32_vpcomfalseud (v4si, v4si) +v2di __builtin_ia32_vpcomfalseuq (v2di, v2di) +v8hi __builtin_ia32_vpcomfalseuw (v8hi, v8hi) +v8hi __builtin_ia32_vpcomfalsew (v8hi, v8hi) +v16qi __builtin_ia32_vpcomgeb (v16qi, v16qi) +v4si __builtin_ia32_vpcomged (v4si, v4si) +v2di __builtin_ia32_vpcomgeq (v2di, v2di) +v16qi __builtin_ia32_vpcomgeub (v16qi, v16qi) +v4si __builtin_ia32_vpcomgeud (v4si, v4si) +v2di __builtin_ia32_vpcomgeuq (v2di, v2di) +v8hi __builtin_ia32_vpcomgeuw (v8hi, v8hi) +v8hi __builtin_ia32_vpcomgew (v8hi, v8hi) +v16qi __builtin_ia32_vpcomgtb (v16qi, v16qi) +v4si __builtin_ia32_vpcomgtd (v4si, v4si) +v2di __builtin_ia32_vpcomgtq (v2di, v2di) +v16qi __builtin_ia32_vpcomgtub (v16qi, v16qi) +v4si __builtin_ia32_vpcomgtud (v4si, v4si) +v2di __builtin_ia32_vpcomgtuq (v2di, v2di) +v8hi __builtin_ia32_vpcomgtuw (v8hi, v8hi) +v8hi __builtin_ia32_vpcomgtw (v8hi, v8hi) +v16qi __builtin_ia32_vpcomleb (v16qi, v16qi) +v4si __builtin_ia32_vpcomled (v4si, v4si) +v2di __builtin_ia32_vpcomleq (v2di, v2di) +v16qi __builtin_ia32_vpcomleub (v16qi, v16qi) +v4si __builtin_ia32_vpcomleud (v4si, v4si) +v2di __builtin_ia32_vpcomleuq (v2di, v2di) +v8hi __builtin_ia32_vpcomleuw (v8hi, v8hi) +v8hi __builtin_ia32_vpcomlew (v8hi, v8hi) +v16qi __builtin_ia32_vpcomltb (v16qi, v16qi) +v4si __builtin_ia32_vpcomltd (v4si, v4si) +v2di __builtin_ia32_vpcomltq (v2di, v2di) +v16qi __builtin_ia32_vpcomltub (v16qi, v16qi) +v4si __builtin_ia32_vpcomltud (v4si, v4si) +v2di __builtin_ia32_vpcomltuq (v2di, v2di) +v8hi __builtin_ia32_vpcomltuw (v8hi, v8hi) +v8hi __builtin_ia32_vpcomltw (v8hi, v8hi) +v16qi __builtin_ia32_vpcomneb (v16qi, v16qi) +v4si __builtin_ia32_vpcomned (v4si, v4si) +v2di __builtin_ia32_vpcomneq (v2di, v2di) +v16qi __builtin_ia32_vpcomneub (v16qi, v16qi) +v4si __builtin_ia32_vpcomneud (v4si, v4si) +v2di __builtin_ia32_vpcomneuq (v2di, v2di) +v8hi __builtin_ia32_vpcomneuw (v8hi, v8hi) +v8hi __builtin_ia32_vpcomnew (v8hi, v8hi) +v16qi __builtin_ia32_vpcomtrueb (v16qi, v16qi) +v4si __builtin_ia32_vpcomtrued (v4si, v4si) +v2di __builtin_ia32_vpcomtrueq (v2di, v2di) +v16qi __builtin_ia32_vpcomtrueub (v16qi, v16qi) +v4si __builtin_ia32_vpcomtrueud (v4si, v4si) +v2di __builtin_ia32_vpcomtrueuq (v2di, v2di) +v8hi __builtin_ia32_vpcomtrueuw (v8hi, v8hi) +v8hi __builtin_ia32_vpcomtruew (v8hi, v8hi) +v4si __builtin_ia32_vphaddbd (v16qi) +v2di __builtin_ia32_vphaddbq (v16qi) +v8hi __builtin_ia32_vphaddbw (v16qi) +v2di __builtin_ia32_vphadddq (v4si) +v4si __builtin_ia32_vphaddubd (v16qi) +v2di __builtin_ia32_vphaddubq (v16qi) +v8hi __builtin_ia32_vphaddubw (v16qi) +v2di __builtin_ia32_vphaddudq (v4si) +v4si __builtin_ia32_vphadduwd (v8hi) +v2di __builtin_ia32_vphadduwq (v8hi) +v4si __builtin_ia32_vphaddwd (v8hi) +v2di __builtin_ia32_vphaddwq (v8hi) +v8hi __builtin_ia32_vphsubbw (v16qi) +v2di __builtin_ia32_vphsubdq (v4si) +v4si __builtin_ia32_vphsubwd (v8hi) +v4si __builtin_ia32_vpmacsdd (v4si, v4si, v4si) +v2di __builtin_ia32_vpmacsdqh (v4si, v4si, v2di) +v2di __builtin_ia32_vpmacsdql (v4si, v4si, v2di) +v4si __builtin_ia32_vpmacssdd (v4si, v4si, v4si) +v2di __builtin_ia32_vpmacssdqh (v4si, v4si, v2di) +v2di __builtin_ia32_vpmacssdql (v4si, v4si, v2di) +v4si __builtin_ia32_vpmacsswd (v8hi, v8hi, v4si) +v8hi __builtin_ia32_vpmacssww (v8hi, v8hi, v8hi) +v4si __builtin_ia32_vpmacswd (v8hi, v8hi, v4si) +v8hi __builtin_ia32_vpmacsww (v8hi, v8hi, v8hi) +v4si __builtin_ia32_vpmadcsswd (v8hi, v8hi, v4si) +v4si __builtin_ia32_vpmadcswd (v8hi, v8hi, v4si) +v16qi __builtin_ia32_vpperm (v16qi, v16qi, v16qi) +v16qi __builtin_ia32_vprotb (v16qi, v16qi) +v4si __builtin_ia32_vprotd (v4si, v4si) +v2di __builtin_ia32_vprotq (v2di, v2di) +v8hi __builtin_ia32_vprotw (v8hi, v8hi) +v16qi __builtin_ia32_vpshab (v16qi, v16qi) +v4si __builtin_ia32_vpshad (v4si, v4si) +v2di __builtin_ia32_vpshaq (v2di, v2di) +v8hi __builtin_ia32_vpshaw (v8hi, v8hi) +v16qi __builtin_ia32_vpshlb (v16qi, v16qi) +v4si __builtin_ia32_vpshld (v4si, v4si) +v2di __builtin_ia32_vpshlq (v2di, v2di) +v8hi __builtin_ia32_vpshlw (v8hi, v8hi) +@end smallexample + +The following built-in functions are available when @option{-mfma4} is used. +All of them generate the machine instruction that is part of the name +with MMX registers. + +@smallexample +v2df __builtin_ia32_fmaddpd (v2df, v2df, v2df) +v4sf __builtin_ia32_fmaddps (v4sf, v4sf, v4sf) +v2df __builtin_ia32_fmaddsd (v2df, v2df, v2df) +v4sf __builtin_ia32_fmaddss (v4sf, v4sf, v4sf) +v2df __builtin_ia32_fmsubpd (v2df, v2df, v2df) +v4sf __builtin_ia32_fmsubps (v4sf, v4sf, v4sf) +v2df __builtin_ia32_fmsubsd (v2df, v2df, v2df) +v4sf __builtin_ia32_fmsubss (v4sf, v4sf, v4sf) +v2df __builtin_ia32_fnmaddpd (v2df, v2df, v2df) +v4sf __builtin_ia32_fnmaddps (v4sf, v4sf, v4sf) +v2df __builtin_ia32_fnmaddsd (v2df, v2df, v2df) +v4sf __builtin_ia32_fnmaddss (v4sf, v4sf, v4sf) +v2df __builtin_ia32_fnmsubpd (v2df, v2df, v2df) +v4sf __builtin_ia32_fnmsubps (v4sf, v4sf, v4sf) +v2df __builtin_ia32_fnmsubsd (v2df, v2df, v2df) +v4sf __builtin_ia32_fnmsubss (v4sf, v4sf, v4sf) +v2df __builtin_ia32_fmaddsubpd (v2df, v2df, v2df) +v4sf __builtin_ia32_fmaddsubps (v4sf, v4sf, v4sf) +v2df __builtin_ia32_fmsubaddpd (v2df, v2df, v2df) +v4sf __builtin_ia32_fmsubaddps (v4sf, v4sf, v4sf) +v4df __builtin_ia32_fmaddpd256 (v4df, v4df, v4df) +v8sf __builtin_ia32_fmaddps256 (v8sf, v8sf, v8sf) +v4df __builtin_ia32_fmsubpd256 (v4df, v4df, v4df) +v8sf __builtin_ia32_fmsubps256 (v8sf, v8sf, v8sf) +v4df __builtin_ia32_fnmaddpd256 (v4df, v4df, v4df) +v8sf __builtin_ia32_fnmaddps256 (v8sf, v8sf, v8sf) +v4df __builtin_ia32_fnmsubpd256 (v4df, v4df, v4df) +v8sf __builtin_ia32_fnmsubps256 (v8sf, v8sf, v8sf) +v4df __builtin_ia32_fmaddsubpd256 (v4df, v4df, v4df) +v8sf __builtin_ia32_fmaddsubps256 (v8sf, v8sf, v8sf) +v4df __builtin_ia32_fmsubaddpd256 (v4df, v4df, v4df) +v8sf __builtin_ia32_fmsubaddps256 (v8sf, v8sf, v8sf) + +@end smallexample + +The following built-in functions are available when @option{-mlwp} is used. + +@smallexample +void __builtin_ia32_llwpcb16 (void *); +void __builtin_ia32_llwpcb32 (void *); +void __builtin_ia32_llwpcb64 (void *); +void * __builtin_ia32_llwpcb16 (void); +void * __builtin_ia32_llwpcb32 (void); +void * __builtin_ia32_llwpcb64 (void); +void __builtin_ia32_lwpval16 (unsigned short, unsigned int, unsigned short) +void __builtin_ia32_lwpval32 (unsigned int, unsigned int, unsigned int) +void __builtin_ia32_lwpval64 (unsigned __int64, unsigned int, unsigned int) +unsigned char __builtin_ia32_lwpins16 (unsigned short, unsigned int, unsigned short) +unsigned char __builtin_ia32_lwpins32 (unsigned int, unsigned int, unsigned int) +unsigned char __builtin_ia32_lwpins64 (unsigned __int64, unsigned int, unsigned int) +@end smallexample + +The following built-in functions are available when @option{-mbmi} is used. +All of them generate the machine instruction that is part of the name. +@smallexample +unsigned int __builtin_ia32_bextr_u32(unsigned int, unsigned int); +unsigned long long __builtin_ia32_bextr_u64 (unsigned long long, unsigned long long); +unsigned short __builtin_ia32_lzcnt_16(unsigned short); +unsigned int __builtin_ia32_lzcnt_u32(unsigned int); +unsigned long long __builtin_ia32_lzcnt_u64 (unsigned long long); +@end smallexample + +The following built-in functions are available when @option{-mtbm} is used. +Both of them generate the immediate form of the bextr machine instruction. +@smallexample +unsigned int __builtin_ia32_bextri_u32 (unsigned int, const unsigned int); +unsigned long long __builtin_ia32_bextri_u64 (unsigned long long, const unsigned long long); +@end smallexample + + +The following built-in functions are available when @option{-m3dnow} is used. +All of them generate the machine instruction that is part of the name. + +@smallexample +void __builtin_ia32_femms (void) +v8qi __builtin_ia32_pavgusb (v8qi, v8qi) +v2si __builtin_ia32_pf2id (v2sf) +v2sf __builtin_ia32_pfacc (v2sf, v2sf) +v2sf __builtin_ia32_pfadd (v2sf, v2sf) +v2si __builtin_ia32_pfcmpeq (v2sf, v2sf) +v2si __builtin_ia32_pfcmpge (v2sf, v2sf) +v2si __builtin_ia32_pfcmpgt (v2sf, v2sf) +v2sf __builtin_ia32_pfmax (v2sf, v2sf) +v2sf __builtin_ia32_pfmin (v2sf, v2sf) +v2sf __builtin_ia32_pfmul (v2sf, v2sf) +v2sf __builtin_ia32_pfrcp (v2sf) +v2sf __builtin_ia32_pfrcpit1 (v2sf, v2sf) +v2sf __builtin_ia32_pfrcpit2 (v2sf, v2sf) +v2sf __builtin_ia32_pfrsqrt (v2sf) +v2sf __builtin_ia32_pfrsqrtit1 (v2sf, v2sf) +v2sf __builtin_ia32_pfsub (v2sf, v2sf) +v2sf __builtin_ia32_pfsubr (v2sf, v2sf) +v2sf __builtin_ia32_pi2fd (v2si) +v4hi __builtin_ia32_pmulhrw (v4hi, v4hi) +@end smallexample + +The following built-in functions are available when both @option{-m3dnow} +and @option{-march=athlon} are used. All of them generate the machine +instruction that is part of the name. + +@smallexample +v2si __builtin_ia32_pf2iw (v2sf) +v2sf __builtin_ia32_pfnacc (v2sf, v2sf) +v2sf __builtin_ia32_pfpnacc (v2sf, v2sf) +v2sf __builtin_ia32_pi2fw (v2si) +v2sf __builtin_ia32_pswapdsf (v2sf) +v2si __builtin_ia32_pswapdsi (v2si) +@end smallexample + +@node MIPS DSP Built-in Functions +@subsection MIPS DSP Built-in Functions + +The MIPS DSP Application-Specific Extension (ASE) includes new +instructions that are designed to improve the performance of DSP and +media applications. It provides instructions that operate on packed +8-bit/16-bit integer data, Q7, Q15 and Q31 fractional data. + +GCC supports MIPS DSP operations using both the generic +vector extensions (@pxref{Vector Extensions}) and a collection of +MIPS-specific built-in functions. Both kinds of support are +enabled by the @option{-mdsp} command-line option. + +Revision 2 of the ASE was introduced in the second half of 2006. +This revision adds extra instructions to the original ASE, but is +otherwise backwards-compatible with it. You can select revision 2 +using the command-line option @option{-mdspr2}; this option implies +@option{-mdsp}. + +The SCOUNT and POS bits of the DSP control register are global. The +WRDSP, EXTPDP, EXTPDPV and MTHLIP instructions modify the SCOUNT and +POS bits. During optimization, the compiler will not delete these +instructions and it will not delete calls to functions containing +these instructions. + +At present, GCC only provides support for operations on 32-bit +vectors. The vector type associated with 8-bit integer data is +usually called @code{v4i8}, the vector type associated with Q7 +is usually called @code{v4q7}, the vector type associated with 16-bit +integer data is usually called @code{v2i16}, and the vector type +associated with Q15 is usually called @code{v2q15}. They can be +defined in C as follows: + +@smallexample +typedef signed char v4i8 __attribute__ ((vector_size(4))); +typedef signed char v4q7 __attribute__ ((vector_size(4))); +typedef short v2i16 __attribute__ ((vector_size(4))); +typedef short v2q15 __attribute__ ((vector_size(4))); +@end smallexample + +@code{v4i8}, @code{v4q7}, @code{v2i16} and @code{v2q15} values are +initialized in the same way as aggregates. For example: + +@smallexample +v4i8 a = @{1, 2, 3, 4@}; +v4i8 b; +b = (v4i8) @{5, 6, 7, 8@}; + +v2q15 c = @{0x0fcb, 0x3a75@}; +v2q15 d; +d = (v2q15) @{0.1234 * 0x1.0p15, 0.4567 * 0x1.0p15@}; +@end smallexample + +@emph{Note:} The CPU's endianness determines the order in which values +are packed. On little-endian targets, the first value is the least +significant and the last value is the most significant. The opposite +order applies to big-endian targets. For example, the code above will +set the lowest byte of @code{a} to @code{1} on little-endian targets +and @code{4} on big-endian targets. + +@emph{Note:} Q7, Q15 and Q31 values must be initialized with their integer +representation. As shown in this example, the integer representation +of a Q7 value can be obtained by multiplying the fractional value by +@code{0x1.0p7}. The equivalent for Q15 values is to multiply by +@code{0x1.0p15}. The equivalent for Q31 values is to multiply by +@code{0x1.0p31}. + +The table below lists the @code{v4i8} and @code{v2q15} operations for which +hardware support exists. @code{a} and @code{b} are @code{v4i8} values, +and @code{c} and @code{d} are @code{v2q15} values. + +@multitable @columnfractions .50 .50 +@item C code @tab MIPS instruction +@item @code{a + b} @tab @code{addu.qb} +@item @code{c + d} @tab @code{addq.ph} +@item @code{a - b} @tab @code{subu.qb} +@item @code{c - d} @tab @code{subq.ph} +@end multitable + +The table below lists the @code{v2i16} operation for which +hardware support exists for the DSP ASE REV 2. @code{e} and @code{f} are +@code{v2i16} values. + +@multitable @columnfractions .50 .50 +@item C code @tab MIPS instruction +@item @code{e * f} @tab @code{mul.ph} +@end multitable + +It is easier to describe the DSP built-in functions if we first define +the following types: + +@smallexample +typedef int q31; +typedef int i32; +typedef unsigned int ui32; +typedef long long a64; +@end smallexample + +@code{q31} and @code{i32} are actually the same as @code{int}, but we +use @code{q31} to indicate a Q31 fractional value and @code{i32} to +indicate a 32-bit integer value. Similarly, @code{a64} is the same as +@code{long long}, but we use @code{a64} to indicate values that will +be placed in one of the four DSP accumulators (@code{$ac0}, +@code{$ac1}, @code{$ac2} or @code{$ac3}). + +Also, some built-in functions prefer or require immediate numbers as +parameters, because the corresponding DSP instructions accept both immediate +numbers and register operands, or accept immediate numbers only. The +immediate parameters are listed as follows. + +@smallexample +imm0_3: 0 to 3. +imm0_7: 0 to 7. +imm0_15: 0 to 15. +imm0_31: 0 to 31. +imm0_63: 0 to 63. +imm0_255: 0 to 255. +imm_n32_31: -32 to 31. +imm_n512_511: -512 to 511. +@end smallexample + +The following built-in functions map directly to a particular MIPS DSP +instruction. Please refer to the architecture specification +for details on what each instruction does. + +@smallexample +v2q15 __builtin_mips_addq_ph (v2q15, v2q15) +v2q15 __builtin_mips_addq_s_ph (v2q15, v2q15) +q31 __builtin_mips_addq_s_w (q31, q31) +v4i8 __builtin_mips_addu_qb (v4i8, v4i8) +v4i8 __builtin_mips_addu_s_qb (v4i8, v4i8) +v2q15 __builtin_mips_subq_ph (v2q15, v2q15) +v2q15 __builtin_mips_subq_s_ph (v2q15, v2q15) +q31 __builtin_mips_subq_s_w (q31, q31) +v4i8 __builtin_mips_subu_qb (v4i8, v4i8) +v4i8 __builtin_mips_subu_s_qb (v4i8, v4i8) +i32 __builtin_mips_addsc (i32, i32) +i32 __builtin_mips_addwc (i32, i32) +i32 __builtin_mips_modsub (i32, i32) +i32 __builtin_mips_raddu_w_qb (v4i8) +v2q15 __builtin_mips_absq_s_ph (v2q15) +q31 __builtin_mips_absq_s_w (q31) +v4i8 __builtin_mips_precrq_qb_ph (v2q15, v2q15) +v2q15 __builtin_mips_precrq_ph_w (q31, q31) +v2q15 __builtin_mips_precrq_rs_ph_w (q31, q31) +v4i8 __builtin_mips_precrqu_s_qb_ph (v2q15, v2q15) +q31 __builtin_mips_preceq_w_phl (v2q15) +q31 __builtin_mips_preceq_w_phr (v2q15) +v2q15 __builtin_mips_precequ_ph_qbl (v4i8) +v2q15 __builtin_mips_precequ_ph_qbr (v4i8) +v2q15 __builtin_mips_precequ_ph_qbla (v4i8) +v2q15 __builtin_mips_precequ_ph_qbra (v4i8) +v2q15 __builtin_mips_preceu_ph_qbl (v4i8) +v2q15 __builtin_mips_preceu_ph_qbr (v4i8) +v2q15 __builtin_mips_preceu_ph_qbla (v4i8) +v2q15 __builtin_mips_preceu_ph_qbra (v4i8) +v4i8 __builtin_mips_shll_qb (v4i8, imm0_7) +v4i8 __builtin_mips_shll_qb (v4i8, i32) +v2q15 __builtin_mips_shll_ph (v2q15, imm0_15) +v2q15 __builtin_mips_shll_ph (v2q15, i32) +v2q15 __builtin_mips_shll_s_ph (v2q15, imm0_15) +v2q15 __builtin_mips_shll_s_ph (v2q15, i32) +q31 __builtin_mips_shll_s_w (q31, imm0_31) +q31 __builtin_mips_shll_s_w (q31, i32) +v4i8 __builtin_mips_shrl_qb (v4i8, imm0_7) +v4i8 __builtin_mips_shrl_qb (v4i8, i32) +v2q15 __builtin_mips_shra_ph (v2q15, imm0_15) +v2q15 __builtin_mips_shra_ph (v2q15, i32) +v2q15 __builtin_mips_shra_r_ph (v2q15, imm0_15) +v2q15 __builtin_mips_shra_r_ph (v2q15, i32) +q31 __builtin_mips_shra_r_w (q31, imm0_31) +q31 __builtin_mips_shra_r_w (q31, i32) +v2q15 __builtin_mips_muleu_s_ph_qbl (v4i8, v2q15) +v2q15 __builtin_mips_muleu_s_ph_qbr (v4i8, v2q15) +v2q15 __builtin_mips_mulq_rs_ph (v2q15, v2q15) +q31 __builtin_mips_muleq_s_w_phl (v2q15, v2q15) +q31 __builtin_mips_muleq_s_w_phr (v2q15, v2q15) +a64 __builtin_mips_dpau_h_qbl (a64, v4i8, v4i8) +a64 __builtin_mips_dpau_h_qbr (a64, v4i8, v4i8) +a64 __builtin_mips_dpsu_h_qbl (a64, v4i8, v4i8) +a64 __builtin_mips_dpsu_h_qbr (a64, v4i8, v4i8) +a64 __builtin_mips_dpaq_s_w_ph (a64, v2q15, v2q15) +a64 __builtin_mips_dpaq_sa_l_w (a64, q31, q31) +a64 __builtin_mips_dpsq_s_w_ph (a64, v2q15, v2q15) +a64 __builtin_mips_dpsq_sa_l_w (a64, q31, q31) +a64 __builtin_mips_mulsaq_s_w_ph (a64, v2q15, v2q15) +a64 __builtin_mips_maq_s_w_phl (a64, v2q15, v2q15) +a64 __builtin_mips_maq_s_w_phr (a64, v2q15, v2q15) +a64 __builtin_mips_maq_sa_w_phl (a64, v2q15, v2q15) +a64 __builtin_mips_maq_sa_w_phr (a64, v2q15, v2q15) +i32 __builtin_mips_bitrev (i32) +i32 __builtin_mips_insv (i32, i32) +v4i8 __builtin_mips_repl_qb (imm0_255) +v4i8 __builtin_mips_repl_qb (i32) +v2q15 __builtin_mips_repl_ph (imm_n512_511) +v2q15 __builtin_mips_repl_ph (i32) +void __builtin_mips_cmpu_eq_qb (v4i8, v4i8) +void __builtin_mips_cmpu_lt_qb (v4i8, v4i8) +void __builtin_mips_cmpu_le_qb (v4i8, v4i8) +i32 __builtin_mips_cmpgu_eq_qb (v4i8, v4i8) +i32 __builtin_mips_cmpgu_lt_qb (v4i8, v4i8) +i32 __builtin_mips_cmpgu_le_qb (v4i8, v4i8) +void __builtin_mips_cmp_eq_ph (v2q15, v2q15) +void __builtin_mips_cmp_lt_ph (v2q15, v2q15) +void __builtin_mips_cmp_le_ph (v2q15, v2q15) +v4i8 __builtin_mips_pick_qb (v4i8, v4i8) +v2q15 __builtin_mips_pick_ph (v2q15, v2q15) +v2q15 __builtin_mips_packrl_ph (v2q15, v2q15) +i32 __builtin_mips_extr_w (a64, imm0_31) +i32 __builtin_mips_extr_w (a64, i32) +i32 __builtin_mips_extr_r_w (a64, imm0_31) +i32 __builtin_mips_extr_s_h (a64, i32) +i32 __builtin_mips_extr_rs_w (a64, imm0_31) +i32 __builtin_mips_extr_rs_w (a64, i32) +i32 __builtin_mips_extr_s_h (a64, imm0_31) +i32 __builtin_mips_extr_r_w (a64, i32) +i32 __builtin_mips_extp (a64, imm0_31) +i32 __builtin_mips_extp (a64, i32) +i32 __builtin_mips_extpdp (a64, imm0_31) +i32 __builtin_mips_extpdp (a64, i32) +a64 __builtin_mips_shilo (a64, imm_n32_31) +a64 __builtin_mips_shilo (a64, i32) +a64 __builtin_mips_mthlip (a64, i32) +void __builtin_mips_wrdsp (i32, imm0_63) +i32 __builtin_mips_rddsp (imm0_63) +i32 __builtin_mips_lbux (void *, i32) +i32 __builtin_mips_lhx (void *, i32) +i32 __builtin_mips_lwx (void *, i32) +i32 __builtin_mips_bposge32 (void) +a64 __builtin_mips_madd (a64, i32, i32); +a64 __builtin_mips_maddu (a64, ui32, ui32); +a64 __builtin_mips_msub (a64, i32, i32); +a64 __builtin_mips_msubu (a64, ui32, ui32); +a64 __builtin_mips_mult (i32, i32); +a64 __builtin_mips_multu (ui32, ui32); +@end smallexample + +The following built-in functions map directly to a particular MIPS DSP REV 2 +instruction. Please refer to the architecture specification +for details on what each instruction does. + +@smallexample +v4q7 __builtin_mips_absq_s_qb (v4q7); +v2i16 __builtin_mips_addu_ph (v2i16, v2i16); +v2i16 __builtin_mips_addu_s_ph (v2i16, v2i16); +v4i8 __builtin_mips_adduh_qb (v4i8, v4i8); +v4i8 __builtin_mips_adduh_r_qb (v4i8, v4i8); +i32 __builtin_mips_append (i32, i32, imm0_31); +i32 __builtin_mips_balign (i32, i32, imm0_3); +i32 __builtin_mips_cmpgdu_eq_qb (v4i8, v4i8); +i32 __builtin_mips_cmpgdu_lt_qb (v4i8, v4i8); +i32 __builtin_mips_cmpgdu_le_qb (v4i8, v4i8); +a64 __builtin_mips_dpa_w_ph (a64, v2i16, v2i16); +a64 __builtin_mips_dps_w_ph (a64, v2i16, v2i16); +v2i16 __builtin_mips_mul_ph (v2i16, v2i16); +v2i16 __builtin_mips_mul_s_ph (v2i16, v2i16); +q31 __builtin_mips_mulq_rs_w (q31, q31); +v2q15 __builtin_mips_mulq_s_ph (v2q15, v2q15); +q31 __builtin_mips_mulq_s_w (q31, q31); +a64 __builtin_mips_mulsa_w_ph (a64, v2i16, v2i16); +v4i8 __builtin_mips_precr_qb_ph (v2i16, v2i16); +v2i16 __builtin_mips_precr_sra_ph_w (i32, i32, imm0_31); +v2i16 __builtin_mips_precr_sra_r_ph_w (i32, i32, imm0_31); +i32 __builtin_mips_prepend (i32, i32, imm0_31); +v4i8 __builtin_mips_shra_qb (v4i8, imm0_7); +v4i8 __builtin_mips_shra_r_qb (v4i8, imm0_7); +v4i8 __builtin_mips_shra_qb (v4i8, i32); +v4i8 __builtin_mips_shra_r_qb (v4i8, i32); +v2i16 __builtin_mips_shrl_ph (v2i16, imm0_15); +v2i16 __builtin_mips_shrl_ph (v2i16, i32); +v2i16 __builtin_mips_subu_ph (v2i16, v2i16); +v2i16 __builtin_mips_subu_s_ph (v2i16, v2i16); +v4i8 __builtin_mips_subuh_qb (v4i8, v4i8); +v4i8 __builtin_mips_subuh_r_qb (v4i8, v4i8); +v2q15 __builtin_mips_addqh_ph (v2q15, v2q15); +v2q15 __builtin_mips_addqh_r_ph (v2q15, v2q15); +q31 __builtin_mips_addqh_w (q31, q31); +q31 __builtin_mips_addqh_r_w (q31, q31); +v2q15 __builtin_mips_subqh_ph (v2q15, v2q15); +v2q15 __builtin_mips_subqh_r_ph (v2q15, v2q15); +q31 __builtin_mips_subqh_w (q31, q31); +q31 __builtin_mips_subqh_r_w (q31, q31); +a64 __builtin_mips_dpax_w_ph (a64, v2i16, v2i16); +a64 __builtin_mips_dpsx_w_ph (a64, v2i16, v2i16); +a64 __builtin_mips_dpaqx_s_w_ph (a64, v2q15, v2q15); +a64 __builtin_mips_dpaqx_sa_w_ph (a64, v2q15, v2q15); +a64 __builtin_mips_dpsqx_s_w_ph (a64, v2q15, v2q15); +a64 __builtin_mips_dpsqx_sa_w_ph (a64, v2q15, v2q15); +@end smallexample + + +@node MIPS Paired-Single Support +@subsection MIPS Paired-Single Support + +The MIPS64 architecture includes a number of instructions that +operate on pairs of single-precision floating-point values. +Each pair is packed into a 64-bit floating-point register, +with one element being designated the ``upper half'' and +the other being designated the ``lower half''. + +GCC supports paired-single operations using both the generic +vector extensions (@pxref{Vector Extensions}) and a collection of +MIPS-specific built-in functions. Both kinds of support are +enabled by the @option{-mpaired-single} command-line option. + +The vector type associated with paired-single values is usually +called @code{v2sf}. It can be defined in C as follows: + +@smallexample +typedef float v2sf __attribute__ ((vector_size (8))); +@end smallexample + +@code{v2sf} values are initialized in the same way as aggregates. +For example: + +@smallexample +v2sf a = @{1.5, 9.1@}; +v2sf b; +float e, f; +b = (v2sf) @{e, f@}; +@end smallexample + +@emph{Note:} The CPU's endianness determines which value is stored in +the upper half of a register and which value is stored in the lower half. +On little-endian targets, the first value is the lower one and the second +value is the upper one. The opposite order applies to big-endian targets. +For example, the code above will set the lower half of @code{a} to +@code{1.5} on little-endian targets and @code{9.1} on big-endian targets. + +@node MIPS Loongson Built-in Functions +@subsection MIPS Loongson Built-in Functions + +GCC provides intrinsics to access the SIMD instructions provided by the +ST Microelectronics Loongson-2E and -2F processors. These intrinsics, +available after inclusion of the @code{loongson.h} header file, +operate on the following 64-bit vector types: + +@itemize +@item @code{uint8x8_t}, a vector of eight unsigned 8-bit integers; +@item @code{uint16x4_t}, a vector of four unsigned 16-bit integers; +@item @code{uint32x2_t}, a vector of two unsigned 32-bit integers; +@item @code{int8x8_t}, a vector of eight signed 8-bit integers; +@item @code{int16x4_t}, a vector of four signed 16-bit integers; +@item @code{int32x2_t}, a vector of two signed 32-bit integers. +@end itemize + +The intrinsics provided are listed below; each is named after the +machine instruction to which it corresponds, with suffixes added as +appropriate to distinguish intrinsics that expand to the same machine +instruction yet have different argument types. Refer to the architecture +documentation for a description of the functionality of each +instruction. + +@smallexample +int16x4_t packsswh (int32x2_t s, int32x2_t t); +int8x8_t packsshb (int16x4_t s, int16x4_t t); +uint8x8_t packushb (uint16x4_t s, uint16x4_t t); +uint32x2_t paddw_u (uint32x2_t s, uint32x2_t t); +uint16x4_t paddh_u (uint16x4_t s, uint16x4_t t); +uint8x8_t paddb_u (uint8x8_t s, uint8x8_t t); +int32x2_t paddw_s (int32x2_t s, int32x2_t t); +int16x4_t paddh_s (int16x4_t s, int16x4_t t); +int8x8_t paddb_s (int8x8_t s, int8x8_t t); +uint64_t paddd_u (uint64_t s, uint64_t t); +int64_t paddd_s (int64_t s, int64_t t); +int16x4_t paddsh (int16x4_t s, int16x4_t t); +int8x8_t paddsb (int8x8_t s, int8x8_t t); +uint16x4_t paddush (uint16x4_t s, uint16x4_t t); +uint8x8_t paddusb (uint8x8_t s, uint8x8_t t); +uint64_t pandn_ud (uint64_t s, uint64_t t); +uint32x2_t pandn_uw (uint32x2_t s, uint32x2_t t); +uint16x4_t pandn_uh (uint16x4_t s, uint16x4_t t); +uint8x8_t pandn_ub (uint8x8_t s, uint8x8_t t); +int64_t pandn_sd (int64_t s, int64_t t); +int32x2_t pandn_sw (int32x2_t s, int32x2_t t); +int16x4_t pandn_sh (int16x4_t s, int16x4_t t); +int8x8_t pandn_sb (int8x8_t s, int8x8_t t); +uint16x4_t pavgh (uint16x4_t s, uint16x4_t t); +uint8x8_t pavgb (uint8x8_t s, uint8x8_t t); +uint32x2_t pcmpeqw_u (uint32x2_t s, uint32x2_t t); +uint16x4_t pcmpeqh_u (uint16x4_t s, uint16x4_t t); +uint8x8_t pcmpeqb_u (uint8x8_t s, uint8x8_t t); +int32x2_t pcmpeqw_s (int32x2_t s, int32x2_t t); +int16x4_t pcmpeqh_s (int16x4_t s, int16x4_t t); +int8x8_t pcmpeqb_s (int8x8_t s, int8x8_t t); +uint32x2_t pcmpgtw_u (uint32x2_t s, uint32x2_t t); +uint16x4_t pcmpgth_u (uint16x4_t s, uint16x4_t t); +uint8x8_t pcmpgtb_u (uint8x8_t s, uint8x8_t t); +int32x2_t pcmpgtw_s (int32x2_t s, int32x2_t t); +int16x4_t pcmpgth_s (int16x4_t s, int16x4_t t); +int8x8_t pcmpgtb_s (int8x8_t s, int8x8_t t); +uint16x4_t pextrh_u (uint16x4_t s, int field); +int16x4_t pextrh_s (int16x4_t s, int field); +uint16x4_t pinsrh_0_u (uint16x4_t s, uint16x4_t t); +uint16x4_t pinsrh_1_u (uint16x4_t s, uint16x4_t t); +uint16x4_t pinsrh_2_u (uint16x4_t s, uint16x4_t t); +uint16x4_t pinsrh_3_u (uint16x4_t s, uint16x4_t t); +int16x4_t pinsrh_0_s (int16x4_t s, int16x4_t t); +int16x4_t pinsrh_1_s (int16x4_t s, int16x4_t t); +int16x4_t pinsrh_2_s (int16x4_t s, int16x4_t t); +int16x4_t pinsrh_3_s (int16x4_t s, int16x4_t t); +int32x2_t pmaddhw (int16x4_t s, int16x4_t t); +int16x4_t pmaxsh (int16x4_t s, int16x4_t t); +uint8x8_t pmaxub (uint8x8_t s, uint8x8_t t); +int16x4_t pminsh (int16x4_t s, int16x4_t t); +uint8x8_t pminub (uint8x8_t s, uint8x8_t t); +uint8x8_t pmovmskb_u (uint8x8_t s); +int8x8_t pmovmskb_s (int8x8_t s); +uint16x4_t pmulhuh (uint16x4_t s, uint16x4_t t); +int16x4_t pmulhh (int16x4_t s, int16x4_t t); +int16x4_t pmullh (int16x4_t s, int16x4_t t); +int64_t pmuluw (uint32x2_t s, uint32x2_t t); +uint8x8_t pasubub (uint8x8_t s, uint8x8_t t); +uint16x4_t biadd (uint8x8_t s); +uint16x4_t psadbh (uint8x8_t s, uint8x8_t t); +uint16x4_t pshufh_u (uint16x4_t dest, uint16x4_t s, uint8_t order); +int16x4_t pshufh_s (int16x4_t dest, int16x4_t s, uint8_t order); +uint16x4_t psllh_u (uint16x4_t s, uint8_t amount); +int16x4_t psllh_s (int16x4_t s, uint8_t amount); +uint32x2_t psllw_u (uint32x2_t s, uint8_t amount); +int32x2_t psllw_s (int32x2_t s, uint8_t amount); +uint16x4_t psrlh_u (uint16x4_t s, uint8_t amount); +int16x4_t psrlh_s (int16x4_t s, uint8_t amount); +uint32x2_t psrlw_u (uint32x2_t s, uint8_t amount); +int32x2_t psrlw_s (int32x2_t s, uint8_t amount); +uint16x4_t psrah_u (uint16x4_t s, uint8_t amount); +int16x4_t psrah_s (int16x4_t s, uint8_t amount); +uint32x2_t psraw_u (uint32x2_t s, uint8_t amount); +int32x2_t psraw_s (int32x2_t s, uint8_t amount); +uint32x2_t psubw_u (uint32x2_t s, uint32x2_t t); +uint16x4_t psubh_u (uint16x4_t s, uint16x4_t t); +uint8x8_t psubb_u (uint8x8_t s, uint8x8_t t); +int32x2_t psubw_s (int32x2_t s, int32x2_t t); +int16x4_t psubh_s (int16x4_t s, int16x4_t t); +int8x8_t psubb_s (int8x8_t s, int8x8_t t); +uint64_t psubd_u (uint64_t s, uint64_t t); +int64_t psubd_s (int64_t s, int64_t t); +int16x4_t psubsh (int16x4_t s, int16x4_t t); +int8x8_t psubsb (int8x8_t s, int8x8_t t); +uint16x4_t psubush (uint16x4_t s, uint16x4_t t); +uint8x8_t psubusb (uint8x8_t s, uint8x8_t t); +uint32x2_t punpckhwd_u (uint32x2_t s, uint32x2_t t); +uint16x4_t punpckhhw_u (uint16x4_t s, uint16x4_t t); +uint8x8_t punpckhbh_u (uint8x8_t s, uint8x8_t t); +int32x2_t punpckhwd_s (int32x2_t s, int32x2_t t); +int16x4_t punpckhhw_s (int16x4_t s, int16x4_t t); +int8x8_t punpckhbh_s (int8x8_t s, int8x8_t t); +uint32x2_t punpcklwd_u (uint32x2_t s, uint32x2_t t); +uint16x4_t punpcklhw_u (uint16x4_t s, uint16x4_t t); +uint8x8_t punpcklbh_u (uint8x8_t s, uint8x8_t t); +int32x2_t punpcklwd_s (int32x2_t s, int32x2_t t); +int16x4_t punpcklhw_s (int16x4_t s, int16x4_t t); +int8x8_t punpcklbh_s (int8x8_t s, int8x8_t t); +@end smallexample + +@menu +* Paired-Single Arithmetic:: +* Paired-Single Built-in Functions:: +* MIPS-3D Built-in Functions:: +@end menu + +@node Paired-Single Arithmetic +@subsubsection Paired-Single Arithmetic + +The table below lists the @code{v2sf} operations for which hardware +support exists. @code{a}, @code{b} and @code{c} are @code{v2sf} +values and @code{x} is an integral value. + +@multitable @columnfractions .50 .50 +@item C code @tab MIPS instruction +@item @code{a + b} @tab @code{add.ps} +@item @code{a - b} @tab @code{sub.ps} +@item @code{-a} @tab @code{neg.ps} +@item @code{a * b} @tab @code{mul.ps} +@item @code{a * b + c} @tab @code{madd.ps} +@item @code{a * b - c} @tab @code{msub.ps} +@item @code{-(a * b + c)} @tab @code{nmadd.ps} +@item @code{-(a * b - c)} @tab @code{nmsub.ps} +@item @code{x ? a : b} @tab @code{movn.ps}/@code{movz.ps} +@end multitable + +Note that the multiply-accumulate instructions can be disabled +using the command-line option @code{-mno-fused-madd}. + +@node Paired-Single Built-in Functions +@subsubsection Paired-Single Built-in Functions + +The following paired-single functions map directly to a particular +MIPS instruction. Please refer to the architecture specification +for details on what each instruction does. + +@table @code +@item v2sf __builtin_mips_pll_ps (v2sf, v2sf) +Pair lower lower (@code{pll.ps}). + +@item v2sf __builtin_mips_pul_ps (v2sf, v2sf) +Pair upper lower (@code{pul.ps}). + +@item v2sf __builtin_mips_plu_ps (v2sf, v2sf) +Pair lower upper (@code{plu.ps}). + +@item v2sf __builtin_mips_puu_ps (v2sf, v2sf) +Pair upper upper (@code{puu.ps}). + +@item v2sf __builtin_mips_cvt_ps_s (float, float) +Convert pair to paired single (@code{cvt.ps.s}). + +@item float __builtin_mips_cvt_s_pl (v2sf) +Convert pair lower to single (@code{cvt.s.pl}). + +@item float __builtin_mips_cvt_s_pu (v2sf) +Convert pair upper to single (@code{cvt.s.pu}). + +@item v2sf __builtin_mips_abs_ps (v2sf) +Absolute value (@code{abs.ps}). + +@item v2sf __builtin_mips_alnv_ps (v2sf, v2sf, int) +Align variable (@code{alnv.ps}). + +@emph{Note:} The value of the third parameter must be 0 or 4 +modulo 8, otherwise the result will be unpredictable. Please read the +instruction description for details. +@end table + +The following multi-instruction functions are also available. +In each case, @var{cond} can be any of the 16 floating-point conditions: +@code{f}, @code{un}, @code{eq}, @code{ueq}, @code{olt}, @code{ult}, +@code{ole}, @code{ule}, @code{sf}, @code{ngle}, @code{seq}, @code{ngl}, +@code{lt}, @code{nge}, @code{le} or @code{ngt}. + +@table @code +@item v2sf __builtin_mips_movt_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d}) +@itemx v2sf __builtin_mips_movf_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d}) +Conditional move based on floating point comparison (@code{c.@var{cond}.ps}, +@code{movt.ps}/@code{movf.ps}). + +The @code{movt} functions return the value @var{x} computed by: + +@smallexample +c.@var{cond}.ps @var{cc},@var{a},@var{b} +mov.ps @var{x},@var{c} +movt.ps @var{x},@var{d},@var{cc} +@end smallexample + +The @code{movf} functions are similar but use @code{movf.ps} instead +of @code{movt.ps}. + +@item int __builtin_mips_upper_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}) +@itemx int __builtin_mips_lower_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}) +Comparison of two paired-single values (@code{c.@var{cond}.ps}, +@code{bc1t}/@code{bc1f}). + +These functions compare @var{a} and @var{b} using @code{c.@var{cond}.ps} +and return either the upper or lower half of the result. For example: + +@smallexample +v2sf a, b; +if (__builtin_mips_upper_c_eq_ps (a, b)) + upper_halves_are_equal (); +else + upper_halves_are_unequal (); + +if (__builtin_mips_lower_c_eq_ps (a, b)) + lower_halves_are_equal (); +else + lower_halves_are_unequal (); +@end smallexample +@end table + +@node MIPS-3D Built-in Functions +@subsubsection MIPS-3D Built-in Functions + +The MIPS-3D Application-Specific Extension (ASE) includes additional +paired-single instructions that are designed to improve the performance +of 3D graphics operations. Support for these instructions is controlled +by the @option{-mips3d} command-line option. + +The functions listed below map directly to a particular MIPS-3D +instruction. Please refer to the architecture specification for +more details on what each instruction does. + +@table @code +@item v2sf __builtin_mips_addr_ps (v2sf, v2sf) +Reduction add (@code{addr.ps}). + +@item v2sf __builtin_mips_mulr_ps (v2sf, v2sf) +Reduction multiply (@code{mulr.ps}). + +@item v2sf __builtin_mips_cvt_pw_ps (v2sf) +Convert paired single to paired word (@code{cvt.pw.ps}). + +@item v2sf __builtin_mips_cvt_ps_pw (v2sf) +Convert paired word to paired single (@code{cvt.ps.pw}). + +@item float __builtin_mips_recip1_s (float) +@itemx double __builtin_mips_recip1_d (double) +@itemx v2sf __builtin_mips_recip1_ps (v2sf) +Reduced precision reciprocal (sequence step 1) (@code{recip1.@var{fmt}}). + +@item float __builtin_mips_recip2_s (float, float) +@itemx double __builtin_mips_recip2_d (double, double) +@itemx v2sf __builtin_mips_recip2_ps (v2sf, v2sf) +Reduced precision reciprocal (sequence step 2) (@code{recip2.@var{fmt}}). + +@item float __builtin_mips_rsqrt1_s (float) +@itemx double __builtin_mips_rsqrt1_d (double) +@itemx v2sf __builtin_mips_rsqrt1_ps (v2sf) +Reduced precision reciprocal square root (sequence step 1) +(@code{rsqrt1.@var{fmt}}). + +@item float __builtin_mips_rsqrt2_s (float, float) +@itemx double __builtin_mips_rsqrt2_d (double, double) +@itemx v2sf __builtin_mips_rsqrt2_ps (v2sf, v2sf) +Reduced precision reciprocal square root (sequence step 2) +(@code{rsqrt2.@var{fmt}}). +@end table + +The following multi-instruction functions are also available. +In each case, @var{cond} can be any of the 16 floating-point conditions: +@code{f}, @code{un}, @code{eq}, @code{ueq}, @code{olt}, @code{ult}, +@code{ole}, @code{ule}, @code{sf}, @code{ngle}, @code{seq}, +@code{ngl}, @code{lt}, @code{nge}, @code{le} or @code{ngt}. + +@table @code +@item int __builtin_mips_cabs_@var{cond}_s (float @var{a}, float @var{b}) +@itemx int __builtin_mips_cabs_@var{cond}_d (double @var{a}, double @var{b}) +Absolute comparison of two scalar values (@code{cabs.@var{cond}.@var{fmt}}, +@code{bc1t}/@code{bc1f}). + +These functions compare @var{a} and @var{b} using @code{cabs.@var{cond}.s} +or @code{cabs.@var{cond}.d} and return the result as a boolean value. +For example: + +@smallexample +float a, b; +if (__builtin_mips_cabs_eq_s (a, b)) + true (); +else + false (); +@end smallexample + +@item int __builtin_mips_upper_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}) +@itemx int __builtin_mips_lower_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}) +Absolute comparison of two paired-single values (@code{cabs.@var{cond}.ps}, +@code{bc1t}/@code{bc1f}). + +These functions compare @var{a} and @var{b} using @code{cabs.@var{cond}.ps} +and return either the upper or lower half of the result. For example: + +@smallexample +v2sf a, b; +if (__builtin_mips_upper_cabs_eq_ps (a, b)) + upper_halves_are_equal (); +else + upper_halves_are_unequal (); + +if (__builtin_mips_lower_cabs_eq_ps (a, b)) + lower_halves_are_equal (); +else + lower_halves_are_unequal (); +@end smallexample + +@item v2sf __builtin_mips_movt_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d}) +@itemx v2sf __builtin_mips_movf_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d}) +Conditional move based on absolute comparison (@code{cabs.@var{cond}.ps}, +@code{movt.ps}/@code{movf.ps}). + +The @code{movt} functions return the value @var{x} computed by: + +@smallexample +cabs.@var{cond}.ps @var{cc},@var{a},@var{b} +mov.ps @var{x},@var{c} +movt.ps @var{x},@var{d},@var{cc} +@end smallexample + +The @code{movf} functions are similar but use @code{movf.ps} instead +of @code{movt.ps}. + +@item int __builtin_mips_any_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}) +@itemx int __builtin_mips_all_c_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}) +@itemx int __builtin_mips_any_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}) +@itemx int __builtin_mips_all_cabs_@var{cond}_ps (v2sf @var{a}, v2sf @var{b}) +Comparison of two paired-single values +(@code{c.@var{cond}.ps}/@code{cabs.@var{cond}.ps}, +@code{bc1any2t}/@code{bc1any2f}). + +These functions compare @var{a} and @var{b} using @code{c.@var{cond}.ps} +or @code{cabs.@var{cond}.ps}. The @code{any} forms return true if either +result is true and the @code{all} forms return true if both results are true. +For example: + +@smallexample +v2sf a, b; +if (__builtin_mips_any_c_eq_ps (a, b)) + one_is_true (); +else + both_are_false (); + +if (__builtin_mips_all_c_eq_ps (a, b)) + both_are_true (); +else + one_is_false (); +@end smallexample + +@item int __builtin_mips_any_c_@var{cond}_4s (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d}) +@itemx int __builtin_mips_all_c_@var{cond}_4s (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d}) +@itemx int __builtin_mips_any_cabs_@var{cond}_4s (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d}) +@itemx int __builtin_mips_all_cabs_@var{cond}_4s (v2sf @var{a}, v2sf @var{b}, v2sf @var{c}, v2sf @var{d}) +Comparison of four paired-single values +(@code{c.@var{cond}.ps}/@code{cabs.@var{cond}.ps}, +@code{bc1any4t}/@code{bc1any4f}). + +These functions use @code{c.@var{cond}.ps} or @code{cabs.@var{cond}.ps} +to compare @var{a} with @var{b} and to compare @var{c} with @var{d}. +The @code{any} forms return true if any of the four results are true +and the @code{all} forms return true if all four results are true. +For example: + +@smallexample +v2sf a, b, c, d; +if (__builtin_mips_any_c_eq_4s (a, b, c, d)) + some_are_true (); +else + all_are_false (); + +if (__builtin_mips_all_c_eq_4s (a, b, c, d)) + all_are_true (); +else + some_are_false (); +@end smallexample +@end table + +@node picoChip Built-in Functions +@subsection picoChip Built-in Functions + +GCC provides an interface to selected machine instructions from the +picoChip instruction set. + +@table @code +@item int __builtin_sbc (int @var{value}) +Sign bit count. Return the number of consecutive bits in @var{value} +which have the same value as the sign-bit. The result is the number of +leading sign bits minus one, giving the number of redundant sign bits in +@var{value}. + +@item int __builtin_byteswap (int @var{value}) +Byte swap. Return the result of swapping the upper and lower bytes of +@var{value}. + +@item int __builtin_brev (int @var{value}) +Bit reversal. Return the result of reversing the bits in +@var{value}. Bit 15 is swapped with bit 0, bit 14 is swapped with bit 1, +and so on. + +@item int __builtin_adds (int @var{x}, int @var{y}) +Saturating addition. Return the result of adding @var{x} and @var{y}, +storing the value 32767 if the result overflows. + +@item int __builtin_subs (int @var{x}, int @var{y}) +Saturating subtraction. Return the result of subtracting @var{y} from +@var{x}, storing the value @minus{}32768 if the result overflows. + +@item void __builtin_halt (void) +Halt. The processor will stop execution. This built-in is useful for +implementing assertions. + +@end table + +@node Other MIPS Built-in Functions +@subsection Other MIPS Built-in Functions + +GCC provides other MIPS-specific built-in functions: + +@table @code +@item void __builtin_mips_cache (int @var{op}, const volatile void *@var{addr}) +Insert a @samp{cache} instruction with operands @var{op} and @var{addr}. +GCC defines the preprocessor macro @code{___GCC_HAVE_BUILTIN_MIPS_CACHE} +when this function is available. +@end table + +@node PowerPC AltiVec/VSX Built-in Functions +@subsection PowerPC AltiVec Built-in Functions + +GCC provides an interface for the PowerPC family of processors to access +the AltiVec operations described in Motorola's AltiVec Programming +Interface Manual. The interface is made available by including +@code{} and using @option{-maltivec} and +@option{-mabi=altivec}. The interface supports the following vector +types. + +@smallexample +vector unsigned char +vector signed char +vector bool char + +vector unsigned short +vector signed short +vector bool short +vector pixel + +vector unsigned int +vector signed int +vector bool int +vector float +@end smallexample + +If @option{-mvsx} is used the following additional vector types are +implemented. + +@smallexample +vector unsigned long +vector signed long +vector double +@end smallexample + +The long types are only implemented for 64-bit code generation, and +the long type is only used in the floating point/integer conversion +instructions. + +GCC's implementation of the high-level language interface available from +C and C++ code differs from Motorola's documentation in several ways. + +@itemize @bullet + +@item +A vector constant is a list of constant expressions within curly braces. + +@item +A vector initializer requires no cast if the vector constant is of the +same type as the variable it is initializing. + +@item +If @code{signed} or @code{unsigned} is omitted, the signedness of the +vector type is the default signedness of the base type. The default +varies depending on the operating system, so a portable program should +always specify the signedness. + +@item +Compiling with @option{-maltivec} adds keywords @code{__vector}, +@code{vector}, @code{__pixel}, @code{pixel}, @code{__bool} and +@code{bool}. When compiling ISO C, the context-sensitive substitution +of the keywords @code{vector}, @code{pixel} and @code{bool} is +disabled. To use them, you must include @code{} instead. + +@item +GCC allows using a @code{typedef} name as the type specifier for a +vector type. + +@item +For C, overloaded functions are implemented with macros so the following +does not work: + +@smallexample + vec_add ((vector signed int)@{1, 2, 3, 4@}, foo); +@end smallexample + +Since @code{vec_add} is a macro, the vector constant in the example +is treated as four separate arguments. Wrap the entire argument in +parentheses for this to work. +@end itemize + +@emph{Note:} Only the @code{} interface is supported. +Internally, GCC uses built-in functions to achieve the functionality in +the aforementioned header file, but they are not supported and are +subject to change without notice. + +The following interfaces are supported for the generic and specific +AltiVec operations and the AltiVec predicates. In cases where there +is a direct mapping between generic and specific operations, only the +generic names are shown here, although the specific operations can also +be used. + +Arguments that are documented as @code{const int} require literal +integral values within the range required for that operation. + +@smallexample +vector signed char vec_abs (vector signed char); +vector signed short vec_abs (vector signed short); +vector signed int vec_abs (vector signed int); +vector float vec_abs (vector float); + +vector signed char vec_abss (vector signed char); +vector signed short vec_abss (vector signed short); +vector signed int vec_abss (vector signed int); + +vector signed char vec_add (vector bool char, vector signed char); +vector signed char vec_add (vector signed char, vector bool char); +vector signed char vec_add (vector signed char, vector signed char); +vector unsigned char vec_add (vector bool char, vector unsigned char); +vector unsigned char vec_add (vector unsigned char, vector bool char); +vector unsigned char vec_add (vector unsigned char, + vector unsigned char); +vector signed short vec_add (vector bool short, vector signed short); +vector signed short vec_add (vector signed short, vector bool short); +vector signed short vec_add (vector signed short, vector signed short); +vector unsigned short vec_add (vector bool short, + vector unsigned short); +vector unsigned short vec_add (vector unsigned short, + vector bool short); +vector unsigned short vec_add (vector unsigned short, + vector unsigned short); +vector signed int vec_add (vector bool int, vector signed int); +vector signed int vec_add (vector signed int, vector bool int); +vector signed int vec_add (vector signed int, vector signed int); +vector unsigned int vec_add (vector bool int, vector unsigned int); +vector unsigned int vec_add (vector unsigned int, vector bool int); +vector unsigned int vec_add (vector unsigned int, vector unsigned int); +vector float vec_add (vector float, vector float); + +vector float vec_vaddfp (vector float, vector float); + +vector signed int vec_vadduwm (vector bool int, vector signed int); +vector signed int vec_vadduwm (vector signed int, vector bool int); +vector signed int vec_vadduwm (vector signed int, vector signed int); +vector unsigned int vec_vadduwm (vector bool int, vector unsigned int); +vector unsigned int vec_vadduwm (vector unsigned int, vector bool int); +vector unsigned int vec_vadduwm (vector unsigned int, + vector unsigned int); + +vector signed short vec_vadduhm (vector bool short, + vector signed short); +vector signed short vec_vadduhm (vector signed short, + vector bool short); +vector signed short vec_vadduhm (vector signed short, + vector signed short); +vector unsigned short vec_vadduhm (vector bool short, + vector unsigned short); +vector unsigned short vec_vadduhm (vector unsigned short, + vector bool short); +vector unsigned short vec_vadduhm (vector unsigned short, + vector unsigned short); + +vector signed char vec_vaddubm (vector bool char, vector signed char); +vector signed char vec_vaddubm (vector signed char, vector bool char); +vector signed char vec_vaddubm (vector signed char, vector signed char); +vector unsigned char vec_vaddubm (vector bool char, + vector unsigned char); +vector unsigned char vec_vaddubm (vector unsigned char, + vector bool char); +vector unsigned char vec_vaddubm (vector unsigned char, + vector unsigned char); + +vector unsigned int vec_addc (vector unsigned int, vector unsigned int); + +vector unsigned char vec_adds (vector bool char, vector unsigned char); +vector unsigned char vec_adds (vector unsigned char, vector bool char); +vector unsigned char vec_adds (vector unsigned char, + vector unsigned char); +vector signed char vec_adds (vector bool char, vector signed char); +vector signed char vec_adds (vector signed char, vector bool char); +vector signed char vec_adds (vector signed char, vector signed char); +vector unsigned short vec_adds (vector bool short, + vector unsigned short); +vector unsigned short vec_adds (vector unsigned short, + vector bool short); +vector unsigned short vec_adds (vector unsigned short, + vector unsigned short); +vector signed short vec_adds (vector bool short, vector signed short); +vector signed short vec_adds (vector signed short, vector bool short); +vector signed short vec_adds (vector signed short, vector signed short); +vector unsigned int vec_adds (vector bool int, vector unsigned int); +vector unsigned int vec_adds (vector unsigned int, vector bool int); +vector unsigned int vec_adds (vector unsigned int, vector unsigned int); +vector signed int vec_adds (vector bool int, vector signed int); +vector signed int vec_adds (vector signed int, vector bool int); +vector signed int vec_adds (vector signed int, vector signed int); + +vector signed int vec_vaddsws (vector bool int, vector signed int); +vector signed int vec_vaddsws (vector signed int, vector bool int); +vector signed int vec_vaddsws (vector signed int, vector signed int); + +vector unsigned int vec_vadduws (vector bool int, vector unsigned int); +vector unsigned int vec_vadduws (vector unsigned int, vector bool int); +vector unsigned int vec_vadduws (vector unsigned int, + vector unsigned int); + +vector signed short vec_vaddshs (vector bool short, + vector signed short); +vector signed short vec_vaddshs (vector signed short, + vector bool short); +vector signed short vec_vaddshs (vector signed short, + vector signed short); + +vector unsigned short vec_vadduhs (vector bool short, + vector unsigned short); +vector unsigned short vec_vadduhs (vector unsigned short, + vector bool short); +vector unsigned short vec_vadduhs (vector unsigned short, + vector unsigned short); + +vector signed char vec_vaddsbs (vector bool char, vector signed char); +vector signed char vec_vaddsbs (vector signed char, vector bool char); +vector signed char vec_vaddsbs (vector signed char, vector signed char); + +vector unsigned char vec_vaddubs (vector bool char, + vector unsigned char); +vector unsigned char vec_vaddubs (vector unsigned char, + vector bool char); +vector unsigned char vec_vaddubs (vector unsigned char, + vector unsigned char); + +vector float vec_and (vector float, vector float); +vector float vec_and (vector float, vector bool int); +vector float vec_and (vector bool int, vector float); +vector bool int vec_and (vector bool int, vector bool int); +vector signed int vec_and (vector bool int, vector signed int); +vector signed int vec_and (vector signed int, vector bool int); +vector signed int vec_and (vector signed int, vector signed int); +vector unsigned int vec_and (vector bool int, vector unsigned int); +vector unsigned int vec_and (vector unsigned int, vector bool int); +vector unsigned int vec_and (vector unsigned int, vector unsigned int); +vector bool short vec_and (vector bool short, vector bool short); +vector signed short vec_and (vector bool short, vector signed short); +vector signed short vec_and (vector signed short, vector bool short); +vector signed short vec_and (vector signed short, vector signed short); +vector unsigned short vec_and (vector bool short, + vector unsigned short); +vector unsigned short vec_and (vector unsigned short, + vector bool short); +vector unsigned short vec_and (vector unsigned short, + vector unsigned short); +vector signed char vec_and (vector bool char, vector signed char); +vector bool char vec_and (vector bool char, vector bool char); +vector signed char vec_and (vector signed char, vector bool char); +vector signed char vec_and (vector signed char, vector signed char); +vector unsigned char vec_and (vector bool char, vector unsigned char); +vector unsigned char vec_and (vector unsigned char, vector bool char); +vector unsigned char vec_and (vector unsigned char, + vector unsigned char); + +vector float vec_andc (vector float, vector float); +vector float vec_andc (vector float, vector bool int); +vector float vec_andc (vector bool int, vector float); +vector bool int vec_andc (vector bool int, vector bool int); +vector signed int vec_andc (vector bool int, vector signed int); +vector signed int vec_andc (vector signed int, vector bool int); +vector signed int vec_andc (vector signed int, vector signed int); +vector unsigned int vec_andc (vector bool int, vector unsigned int); +vector unsigned int vec_andc (vector unsigned int, vector bool int); +vector unsigned int vec_andc (vector unsigned int, vector unsigned int); +vector bool short vec_andc (vector bool short, vector bool short); +vector signed short vec_andc (vector bool short, vector signed short); +vector signed short vec_andc (vector signed short, vector bool short); +vector signed short vec_andc (vector signed short, vector signed short); +vector unsigned short vec_andc (vector bool short, + vector unsigned short); +vector unsigned short vec_andc (vector unsigned short, + vector bool short); +vector unsigned short vec_andc (vector unsigned short, + vector unsigned short); +vector signed char vec_andc (vector bool char, vector signed char); +vector bool char vec_andc (vector bool char, vector bool char); +vector signed char vec_andc (vector signed char, vector bool char); +vector signed char vec_andc (vector signed char, vector signed char); +vector unsigned char vec_andc (vector bool char, vector unsigned char); +vector unsigned char vec_andc (vector unsigned char, vector bool char); +vector unsigned char vec_andc (vector unsigned char, + vector unsigned char); + +vector unsigned char vec_avg (vector unsigned char, + vector unsigned char); +vector signed char vec_avg (vector signed char, vector signed char); +vector unsigned short vec_avg (vector unsigned short, + vector unsigned short); +vector signed short vec_avg (vector signed short, vector signed short); +vector unsigned int vec_avg (vector unsigned int, vector unsigned int); +vector signed int vec_avg (vector signed int, vector signed int); + +vector signed int vec_vavgsw (vector signed int, vector signed int); + +vector unsigned int vec_vavguw (vector unsigned int, + vector unsigned int); + +vector signed short vec_vavgsh (vector signed short, + vector signed short); + +vector unsigned short vec_vavguh (vector unsigned short, + vector unsigned short); + +vector signed char vec_vavgsb (vector signed char, vector signed char); + +vector unsigned char vec_vavgub (vector unsigned char, + vector unsigned char); + +vector float vec_copysign (vector float); + +vector float vec_ceil (vector float); + +vector signed int vec_cmpb (vector float, vector float); + +vector bool char vec_cmpeq (vector signed char, vector signed char); +vector bool char vec_cmpeq (vector unsigned char, vector unsigned char); +vector bool short vec_cmpeq (vector signed short, vector signed short); +vector bool short vec_cmpeq (vector unsigned short, + vector unsigned short); +vector bool int vec_cmpeq (vector signed int, vector signed int); +vector bool int vec_cmpeq (vector unsigned int, vector unsigned int); +vector bool int vec_cmpeq (vector float, vector float); + +vector bool int vec_vcmpeqfp (vector float, vector float); + +vector bool int vec_vcmpequw (vector signed int, vector signed int); +vector bool int vec_vcmpequw (vector unsigned int, vector unsigned int); + +vector bool short vec_vcmpequh (vector signed short, + vector signed short); +vector bool short vec_vcmpequh (vector unsigned short, + vector unsigned short); + +vector bool char vec_vcmpequb (vector signed char, vector signed char); +vector bool char vec_vcmpequb (vector unsigned char, + vector unsigned char); + +vector bool int vec_cmpge (vector float, vector float); + +vector bool char vec_cmpgt (vector unsigned char, vector unsigned char); +vector bool char vec_cmpgt (vector signed char, vector signed char); +vector bool short vec_cmpgt (vector unsigned short, + vector unsigned short); +vector bool short vec_cmpgt (vector signed short, vector signed short); +vector bool int vec_cmpgt (vector unsigned int, vector unsigned int); +vector bool int vec_cmpgt (vector signed int, vector signed int); +vector bool int vec_cmpgt (vector float, vector float); + +vector bool int vec_vcmpgtfp (vector float, vector float); + +vector bool int vec_vcmpgtsw (vector signed int, vector signed int); + +vector bool int vec_vcmpgtuw (vector unsigned int, vector unsigned int); + +vector bool short vec_vcmpgtsh (vector signed short, + vector signed short); + +vector bool short vec_vcmpgtuh (vector unsigned short, + vector unsigned short); + +vector bool char vec_vcmpgtsb (vector signed char, vector signed char); + +vector bool char vec_vcmpgtub (vector unsigned char, + vector unsigned char); + +vector bool int vec_cmple (vector float, vector float); + +vector bool char vec_cmplt (vector unsigned char, vector unsigned char); +vector bool char vec_cmplt (vector signed char, vector signed char); +vector bool short vec_cmplt (vector unsigned short, + vector unsigned short); +vector bool short vec_cmplt (vector signed short, vector signed short); +vector bool int vec_cmplt (vector unsigned int, vector unsigned int); +vector bool int vec_cmplt (vector signed int, vector signed int); +vector bool int vec_cmplt (vector float, vector float); + +vector float vec_ctf (vector unsigned int, const int); +vector float vec_ctf (vector signed int, const int); + +vector float vec_vcfsx (vector signed int, const int); + +vector float vec_vcfux (vector unsigned int, const int); + +vector signed int vec_cts (vector float, const int); + +vector unsigned int vec_ctu (vector float, const int); + +void vec_dss (const int); + +void vec_dssall (void); + +void vec_dst (const vector unsigned char *, int, const int); +void vec_dst (const vector signed char *, int, const int); +void vec_dst (const vector bool char *, int, const int); +void vec_dst (const vector unsigned short *, int, const int); +void vec_dst (const vector signed short *, int, const int); +void vec_dst (const vector bool short *, int, const int); +void vec_dst (const vector pixel *, int, const int); +void vec_dst (const vector unsigned int *, int, const int); +void vec_dst (const vector signed int *, int, const int); +void vec_dst (const vector bool int *, int, const int); +void vec_dst (const vector float *, int, const int); +void vec_dst (const unsigned char *, int, const int); +void vec_dst (const signed char *, int, const int); +void vec_dst (const unsigned short *, int, const int); +void vec_dst (const short *, int, const int); +void vec_dst (const unsigned int *, int, const int); +void vec_dst (const int *, int, const int); +void vec_dst (const unsigned long *, int, const int); +void vec_dst (const long *, int, const int); +void vec_dst (const float *, int, const int); + +void vec_dstst (const vector unsigned char *, int, const int); +void vec_dstst (const vector signed char *, int, const int); +void vec_dstst (const vector bool char *, int, const int); +void vec_dstst (const vector unsigned short *, int, const int); +void vec_dstst (const vector signed short *, int, const int); +void vec_dstst (const vector bool short *, int, const int); +void vec_dstst (const vector pixel *, int, const int); +void vec_dstst (const vector unsigned int *, int, const int); +void vec_dstst (const vector signed int *, int, const int); +void vec_dstst (const vector bool int *, int, const int); +void vec_dstst (const vector float *, int, const int); +void vec_dstst (const unsigned char *, int, const int); +void vec_dstst (const signed char *, int, const int); +void vec_dstst (const unsigned short *, int, const int); +void vec_dstst (const short *, int, const int); +void vec_dstst (const unsigned int *, int, const int); +void vec_dstst (const int *, int, const int); +void vec_dstst (const unsigned long *, int, const int); +void vec_dstst (const long *, int, const int); +void vec_dstst (const float *, int, const int); + +void vec_dststt (const vector unsigned char *, int, const int); +void vec_dststt (const vector signed char *, int, const int); +void vec_dststt (const vector bool char *, int, const int); +void vec_dststt (const vector unsigned short *, int, const int); +void vec_dststt (const vector signed short *, int, const int); +void vec_dststt (const vector bool short *, int, const int); +void vec_dststt (const vector pixel *, int, const int); +void vec_dststt (const vector unsigned int *, int, const int); +void vec_dststt (const vector signed int *, int, const int); +void vec_dststt (const vector bool int *, int, const int); +void vec_dststt (const vector float *, int, const int); +void vec_dststt (const unsigned char *, int, const int); +void vec_dststt (const signed char *, int, const int); +void vec_dststt (const unsigned short *, int, const int); +void vec_dststt (const short *, int, const int); +void vec_dststt (const unsigned int *, int, const int); +void vec_dststt (const int *, int, const int); +void vec_dststt (const unsigned long *, int, const int); +void vec_dststt (const long *, int, const int); +void vec_dststt (const float *, int, const int); + +void vec_dstt (const vector unsigned char *, int, const int); +void vec_dstt (const vector signed char *, int, const int); +void vec_dstt (const vector bool char *, int, const int); +void vec_dstt (const vector unsigned short *, int, const int); +void vec_dstt (const vector signed short *, int, const int); +void vec_dstt (const vector bool short *, int, const int); +void vec_dstt (const vector pixel *, int, const int); +void vec_dstt (const vector unsigned int *, int, const int); +void vec_dstt (const vector signed int *, int, const int); +void vec_dstt (const vector bool int *, int, const int); +void vec_dstt (const vector float *, int, const int); +void vec_dstt (const unsigned char *, int, const int); +void vec_dstt (const signed char *, int, const int); +void vec_dstt (const unsigned short *, int, const int); +void vec_dstt (const short *, int, const int); +void vec_dstt (const unsigned int *, int, const int); +void vec_dstt (const int *, int, const int); +void vec_dstt (const unsigned long *, int, const int); +void vec_dstt (const long *, int, const int); +void vec_dstt (const float *, int, const int); + +vector float vec_expte (vector float); + +vector float vec_floor (vector float); + +vector float vec_ld (int, const vector float *); +vector float vec_ld (int, const float *); +vector bool int vec_ld (int, const vector bool int *); +vector signed int vec_ld (int, const vector signed int *); +vector signed int vec_ld (int, const int *); +vector signed int vec_ld (int, const long *); +vector unsigned int vec_ld (int, const vector unsigned int *); +vector unsigned int vec_ld (int, const unsigned int *); +vector unsigned int vec_ld (int, const unsigned long *); +vector bool short vec_ld (int, const vector bool short *); +vector pixel vec_ld (int, const vector pixel *); +vector signed short vec_ld (int, const vector signed short *); +vector signed short vec_ld (int, const short *); +vector unsigned short vec_ld (int, const vector unsigned short *); +vector unsigned short vec_ld (int, const unsigned short *); +vector bool char vec_ld (int, const vector bool char *); +vector signed char vec_ld (int, const vector signed char *); +vector signed char vec_ld (int, const signed char *); +vector unsigned char vec_ld (int, const vector unsigned char *); +vector unsigned char vec_ld (int, const unsigned char *); + +vector signed char vec_lde (int, const signed char *); +vector unsigned char vec_lde (int, const unsigned char *); +vector signed short vec_lde (int, const short *); +vector unsigned short vec_lde (int, const unsigned short *); +vector float vec_lde (int, const float *); +vector signed int vec_lde (int, const int *); +vector unsigned int vec_lde (int, const unsigned int *); +vector signed int vec_lde (int, const long *); +vector unsigned int vec_lde (int, const unsigned long *); + +vector float vec_lvewx (int, float *); +vector signed int vec_lvewx (int, int *); +vector unsigned int vec_lvewx (int, unsigned int *); +vector signed int vec_lvewx (int, long *); +vector unsigned int vec_lvewx (int, unsigned long *); + +vector signed short vec_lvehx (int, short *); +vector unsigned short vec_lvehx (int, unsigned short *); + +vector signed char vec_lvebx (int, char *); +vector unsigned char vec_lvebx (int, unsigned char *); + +vector float vec_ldl (int, const vector float *); +vector float vec_ldl (int, const float *); +vector bool int vec_ldl (int, const vector bool int *); +vector signed int vec_ldl (int, const vector signed int *); +vector signed int vec_ldl (int, const int *); +vector signed int vec_ldl (int, const long *); +vector unsigned int vec_ldl (int, const vector unsigned int *); +vector unsigned int vec_ldl (int, const unsigned int *); +vector unsigned int vec_ldl (int, const unsigned long *); +vector bool short vec_ldl (int, const vector bool short *); +vector pixel vec_ldl (int, const vector pixel *); +vector signed short vec_ldl (int, const vector signed short *); +vector signed short vec_ldl (int, const short *); +vector unsigned short vec_ldl (int, const vector unsigned short *); +vector unsigned short vec_ldl (int, const unsigned short *); +vector bool char vec_ldl (int, const vector bool char *); +vector signed char vec_ldl (int, const vector signed char *); +vector signed char vec_ldl (int, const signed char *); +vector unsigned char vec_ldl (int, const vector unsigned char *); +vector unsigned char vec_ldl (int, const unsigned char *); + +vector float vec_loge (vector float); + +vector unsigned char vec_lvsl (int, const volatile unsigned char *); +vector unsigned char vec_lvsl (int, const volatile signed char *); +vector unsigned char vec_lvsl (int, const volatile unsigned short *); +vector unsigned char vec_lvsl (int, const volatile short *); +vector unsigned char vec_lvsl (int, const volatile unsigned int *); +vector unsigned char vec_lvsl (int, const volatile int *); +vector unsigned char vec_lvsl (int, const volatile unsigned long *); +vector unsigned char vec_lvsl (int, const volatile long *); +vector unsigned char vec_lvsl (int, const volatile float *); + +vector unsigned char vec_lvsr (int, const volatile unsigned char *); +vector unsigned char vec_lvsr (int, const volatile signed char *); +vector unsigned char vec_lvsr (int, const volatile unsigned short *); +vector unsigned char vec_lvsr (int, const volatile short *); +vector unsigned char vec_lvsr (int, const volatile unsigned int *); +vector unsigned char vec_lvsr (int, const volatile int *); +vector unsigned char vec_lvsr (int, const volatile unsigned long *); +vector unsigned char vec_lvsr (int, const volatile long *); +vector unsigned char vec_lvsr (int, const volatile float *); + +vector float vec_madd (vector float, vector float, vector float); + +vector signed short vec_madds (vector signed short, + vector signed short, + vector signed short); + +vector unsigned char vec_max (vector bool char, vector unsigned char); +vector unsigned char vec_max (vector unsigned char, vector bool char); +vector unsigned char vec_max (vector unsigned char, + vector unsigned char); +vector signed char vec_max (vector bool char, vector signed char); +vector signed char vec_max (vector signed char, vector bool char); +vector signed char vec_max (vector signed char, vector signed char); +vector unsigned short vec_max (vector bool short, + vector unsigned short); +vector unsigned short vec_max (vector unsigned short, + vector bool short); +vector unsigned short vec_max (vector unsigned short, + vector unsigned short); +vector signed short vec_max (vector bool short, vector signed short); +vector signed short vec_max (vector signed short, vector bool short); +vector signed short vec_max (vector signed short, vector signed short); +vector unsigned int vec_max (vector bool int, vector unsigned int); +vector unsigned int vec_max (vector unsigned int, vector bool int); +vector unsigned int vec_max (vector unsigned int, vector unsigned int); +vector signed int vec_max (vector bool int, vector signed int); +vector signed int vec_max (vector signed int, vector bool int); +vector signed int vec_max (vector signed int, vector signed int); +vector float vec_max (vector float, vector float); + +vector float vec_vmaxfp (vector float, vector float); + +vector signed int vec_vmaxsw (vector bool int, vector signed int); +vector signed int vec_vmaxsw (vector signed int, vector bool int); +vector signed int vec_vmaxsw (vector signed int, vector signed int); + +vector unsigned int vec_vmaxuw (vector bool int, vector unsigned int); +vector unsigned int vec_vmaxuw (vector unsigned int, vector bool int); +vector unsigned int vec_vmaxuw (vector unsigned int, + vector unsigned int); + +vector signed short vec_vmaxsh (vector bool short, vector signed short); +vector signed short vec_vmaxsh (vector signed short, vector bool short); +vector signed short vec_vmaxsh (vector signed short, + vector signed short); + +vector unsigned short vec_vmaxuh (vector bool short, + vector unsigned short); +vector unsigned short vec_vmaxuh (vector unsigned short, + vector bool short); +vector unsigned short vec_vmaxuh (vector unsigned short, + vector unsigned short); + +vector signed char vec_vmaxsb (vector bool char, vector signed char); +vector signed char vec_vmaxsb (vector signed char, vector bool char); +vector signed char vec_vmaxsb (vector signed char, vector signed char); + +vector unsigned char vec_vmaxub (vector bool char, + vector unsigned char); +vector unsigned char vec_vmaxub (vector unsigned char, + vector bool char); +vector unsigned char vec_vmaxub (vector unsigned char, + vector unsigned char); + +vector bool char vec_mergeh (vector bool char, vector bool char); +vector signed char vec_mergeh (vector signed char, vector signed char); +vector unsigned char vec_mergeh (vector unsigned char, + vector unsigned char); +vector bool short vec_mergeh (vector bool short, vector bool short); +vector pixel vec_mergeh (vector pixel, vector pixel); +vector signed short vec_mergeh (vector signed short, + vector signed short); +vector unsigned short vec_mergeh (vector unsigned short, + vector unsigned short); +vector float vec_mergeh (vector float, vector float); +vector bool int vec_mergeh (vector bool int, vector bool int); +vector signed int vec_mergeh (vector signed int, vector signed int); +vector unsigned int vec_mergeh (vector unsigned int, + vector unsigned int); + +vector float vec_vmrghw (vector float, vector float); +vector bool int vec_vmrghw (vector bool int, vector bool int); +vector signed int vec_vmrghw (vector signed int, vector signed int); +vector unsigned int vec_vmrghw (vector unsigned int, + vector unsigned int); + +vector bool short vec_vmrghh (vector bool short, vector bool short); +vector signed short vec_vmrghh (vector signed short, + vector signed short); +vector unsigned short vec_vmrghh (vector unsigned short, + vector unsigned short); +vector pixel vec_vmrghh (vector pixel, vector pixel); + +vector bool char vec_vmrghb (vector bool char, vector bool char); +vector signed char vec_vmrghb (vector signed char, vector signed char); +vector unsigned char vec_vmrghb (vector unsigned char, + vector unsigned char); + +vector bool char vec_mergel (vector bool char, vector bool char); +vector signed char vec_mergel (vector signed char, vector signed char); +vector unsigned char vec_mergel (vector unsigned char, + vector unsigned char); +vector bool short vec_mergel (vector bool short, vector bool short); +vector pixel vec_mergel (vector pixel, vector pixel); +vector signed short vec_mergel (vector signed short, + vector signed short); +vector unsigned short vec_mergel (vector unsigned short, + vector unsigned short); +vector float vec_mergel (vector float, vector float); +vector bool int vec_mergel (vector bool int, vector bool int); +vector signed int vec_mergel (vector signed int, vector signed int); +vector unsigned int vec_mergel (vector unsigned int, + vector unsigned int); + +vector float vec_vmrglw (vector float, vector float); +vector signed int vec_vmrglw (vector signed int, vector signed int); +vector unsigned int vec_vmrglw (vector unsigned int, + vector unsigned int); +vector bool int vec_vmrglw (vector bool int, vector bool int); + +vector bool short vec_vmrglh (vector bool short, vector bool short); +vector signed short vec_vmrglh (vector signed short, + vector signed short); +vector unsigned short vec_vmrglh (vector unsigned short, + vector unsigned short); +vector pixel vec_vmrglh (vector pixel, vector pixel); + +vector bool char vec_vmrglb (vector bool char, vector bool char); +vector signed char vec_vmrglb (vector signed char, vector signed char); +vector unsigned char vec_vmrglb (vector unsigned char, + vector unsigned char); + +vector unsigned short vec_mfvscr (void); + +vector unsigned char vec_min (vector bool char, vector unsigned char); +vector unsigned char vec_min (vector unsigned char, vector bool char); +vector unsigned char vec_min (vector unsigned char, + vector unsigned char); +vector signed char vec_min (vector bool char, vector signed char); +vector signed char vec_min (vector signed char, vector bool char); +vector signed char vec_min (vector signed char, vector signed char); +vector unsigned short vec_min (vector bool short, + vector unsigned short); +vector unsigned short vec_min (vector unsigned short, + vector bool short); +vector unsigned short vec_min (vector unsigned short, + vector unsigned short); +vector signed short vec_min (vector bool short, vector signed short); +vector signed short vec_min (vector signed short, vector bool short); +vector signed short vec_min (vector signed short, vector signed short); +vector unsigned int vec_min (vector bool int, vector unsigned int); +vector unsigned int vec_min (vector unsigned int, vector bool int); +vector unsigned int vec_min (vector unsigned int, vector unsigned int); +vector signed int vec_min (vector bool int, vector signed int); +vector signed int vec_min (vector signed int, vector bool int); +vector signed int vec_min (vector signed int, vector signed int); +vector float vec_min (vector float, vector float); + +vector float vec_vminfp (vector float, vector float); + +vector signed int vec_vminsw (vector bool int, vector signed int); +vector signed int vec_vminsw (vector signed int, vector bool int); +vector signed int vec_vminsw (vector signed int, vector signed int); + +vector unsigned int vec_vminuw (vector bool int, vector unsigned int); +vector unsigned int vec_vminuw (vector unsigned int, vector bool int); +vector unsigned int vec_vminuw (vector unsigned int, + vector unsigned int); + +vector signed short vec_vminsh (vector bool short, vector signed short); +vector signed short vec_vminsh (vector signed short, vector bool short); +vector signed short vec_vminsh (vector signed short, + vector signed short); + +vector unsigned short vec_vminuh (vector bool short, + vector unsigned short); +vector unsigned short vec_vminuh (vector unsigned short, + vector bool short); +vector unsigned short vec_vminuh (vector unsigned short, + vector unsigned short); + +vector signed char vec_vminsb (vector bool char, vector signed char); +vector signed char vec_vminsb (vector signed char, vector bool char); +vector signed char vec_vminsb (vector signed char, vector signed char); + +vector unsigned char vec_vminub (vector bool char, + vector unsigned char); +vector unsigned char vec_vminub (vector unsigned char, + vector bool char); +vector unsigned char vec_vminub (vector unsigned char, + vector unsigned char); + +vector signed short vec_mladd (vector signed short, + vector signed short, + vector signed short); +vector signed short vec_mladd (vector signed short, + vector unsigned short, + vector unsigned short); +vector signed short vec_mladd (vector unsigned short, + vector signed short, + vector signed short); +vector unsigned short vec_mladd (vector unsigned short, + vector unsigned short, + vector unsigned short); + +vector signed short vec_mradds (vector signed short, + vector signed short, + vector signed short); + +vector unsigned int vec_msum (vector unsigned char, + vector unsigned char, + vector unsigned int); +vector signed int vec_msum (vector signed char, + vector unsigned char, + vector signed int); +vector unsigned int vec_msum (vector unsigned short, + vector unsigned short, + vector unsigned int); +vector signed int vec_msum (vector signed short, + vector signed short, + vector signed int); + +vector signed int vec_vmsumshm (vector signed short, + vector signed short, + vector signed int); + +vector unsigned int vec_vmsumuhm (vector unsigned short, + vector unsigned short, + vector unsigned int); + +vector signed int vec_vmsummbm (vector signed char, + vector unsigned char, + vector signed int); + +vector unsigned int vec_vmsumubm (vector unsigned char, + vector unsigned char, + vector unsigned int); + +vector unsigned int vec_msums (vector unsigned short, + vector unsigned short, + vector unsigned int); +vector signed int vec_msums (vector signed short, + vector signed short, + vector signed int); + +vector signed int vec_vmsumshs (vector signed short, + vector signed short, + vector signed int); + +vector unsigned int vec_vmsumuhs (vector unsigned short, + vector unsigned short, + vector unsigned int); + +void vec_mtvscr (vector signed int); +void vec_mtvscr (vector unsigned int); +void vec_mtvscr (vector bool int); +void vec_mtvscr (vector signed short); +void vec_mtvscr (vector unsigned short); +void vec_mtvscr (vector bool short); +void vec_mtvscr (vector pixel); +void vec_mtvscr (vector signed char); +void vec_mtvscr (vector unsigned char); +void vec_mtvscr (vector bool char); + +vector unsigned short vec_mule (vector unsigned char, + vector unsigned char); +vector signed short vec_mule (vector signed char, + vector signed char); +vector unsigned int vec_mule (vector unsigned short, + vector unsigned short); +vector signed int vec_mule (vector signed short, vector signed short); + +vector signed int vec_vmulesh (vector signed short, + vector signed short); + +vector unsigned int vec_vmuleuh (vector unsigned short, + vector unsigned short); + +vector signed short vec_vmulesb (vector signed char, + vector signed char); + +vector unsigned short vec_vmuleub (vector unsigned char, + vector unsigned char); + +vector unsigned short vec_mulo (vector unsigned char, + vector unsigned char); +vector signed short vec_mulo (vector signed char, vector signed char); +vector unsigned int vec_mulo (vector unsigned short, + vector unsigned short); +vector signed int vec_mulo (vector signed short, vector signed short); + +vector signed int vec_vmulosh (vector signed short, + vector signed short); + +vector unsigned int vec_vmulouh (vector unsigned short, + vector unsigned short); + +vector signed short vec_vmulosb (vector signed char, + vector signed char); + +vector unsigned short vec_vmuloub (vector unsigned char, + vector unsigned char); + +vector float vec_nmsub (vector float, vector float, vector float); + +vector float vec_nor (vector float, vector float); +vector signed int vec_nor (vector signed int, vector signed int); +vector unsigned int vec_nor (vector unsigned int, vector unsigned int); +vector bool int vec_nor (vector bool int, vector bool int); +vector signed short vec_nor (vector signed short, vector signed short); +vector unsigned short vec_nor (vector unsigned short, + vector unsigned short); +vector bool short vec_nor (vector bool short, vector bool short); +vector signed char vec_nor (vector signed char, vector signed char); +vector unsigned char vec_nor (vector unsigned char, + vector unsigned char); +vector bool char vec_nor (vector bool char, vector bool char); + +vector float vec_or (vector float, vector float); +vector float vec_or (vector float, vector bool int); +vector float vec_or (vector bool int, vector float); +vector bool int vec_or (vector bool int, vector bool int); +vector signed int vec_or (vector bool int, vector signed int); +vector signed int vec_or (vector signed int, vector bool int); +vector signed int vec_or (vector signed int, vector signed int); +vector unsigned int vec_or (vector bool int, vector unsigned int); +vector unsigned int vec_or (vector unsigned int, vector bool int); +vector unsigned int vec_or (vector unsigned int, vector unsigned int); +vector bool short vec_or (vector bool short, vector bool short); +vector signed short vec_or (vector bool short, vector signed short); +vector signed short vec_or (vector signed short, vector bool short); +vector signed short vec_or (vector signed short, vector signed short); +vector unsigned short vec_or (vector bool short, vector unsigned short); +vector unsigned short vec_or (vector unsigned short, vector bool short); +vector unsigned short vec_or (vector unsigned short, + vector unsigned short); +vector signed char vec_or (vector bool char, vector signed char); +vector bool char vec_or (vector bool char, vector bool char); +vector signed char vec_or (vector signed char, vector bool char); +vector signed char vec_or (vector signed char, vector signed char); +vector unsigned char vec_or (vector bool char, vector unsigned char); +vector unsigned char vec_or (vector unsigned char, vector bool char); +vector unsigned char vec_or (vector unsigned char, + vector unsigned char); + +vector signed char vec_pack (vector signed short, vector signed short); +vector unsigned char vec_pack (vector unsigned short, + vector unsigned short); +vector bool char vec_pack (vector bool short, vector bool short); +vector signed short vec_pack (vector signed int, vector signed int); +vector unsigned short vec_pack (vector unsigned int, + vector unsigned int); +vector bool short vec_pack (vector bool int, vector bool int); + +vector bool short vec_vpkuwum (vector bool int, vector bool int); +vector signed short vec_vpkuwum (vector signed int, vector signed int); +vector unsigned short vec_vpkuwum (vector unsigned int, + vector unsigned int); + +vector bool char vec_vpkuhum (vector bool short, vector bool short); +vector signed char vec_vpkuhum (vector signed short, + vector signed short); +vector unsigned char vec_vpkuhum (vector unsigned short, + vector unsigned short); + +vector pixel vec_packpx (vector unsigned int, vector unsigned int); + +vector unsigned char vec_packs (vector unsigned short, + vector unsigned short); +vector signed char vec_packs (vector signed short, vector signed short); +vector unsigned short vec_packs (vector unsigned int, + vector unsigned int); +vector signed short vec_packs (vector signed int, vector signed int); + +vector signed short vec_vpkswss (vector signed int, vector signed int); + +vector unsigned short vec_vpkuwus (vector unsigned int, + vector unsigned int); + +vector signed char vec_vpkshss (vector signed short, + vector signed short); + +vector unsigned char vec_vpkuhus (vector unsigned short, + vector unsigned short); + +vector unsigned char vec_packsu (vector unsigned short, + vector unsigned short); +vector unsigned char vec_packsu (vector signed short, + vector signed short); +vector unsigned short vec_packsu (vector unsigned int, + vector unsigned int); +vector unsigned short vec_packsu (vector signed int, vector signed int); + +vector unsigned short vec_vpkswus (vector signed int, + vector signed int); + +vector unsigned char vec_vpkshus (vector signed short, + vector signed short); + +vector float vec_perm (vector float, + vector float, + vector unsigned char); +vector signed int vec_perm (vector signed int, + vector signed int, + vector unsigned char); +vector unsigned int vec_perm (vector unsigned int, + vector unsigned int, + vector unsigned char); +vector bool int vec_perm (vector bool int, + vector bool int, + vector unsigned char); +vector signed short vec_perm (vector signed short, + vector signed short, + vector unsigned char); +vector unsigned short vec_perm (vector unsigned short, + vector unsigned short, + vector unsigned char); +vector bool short vec_perm (vector bool short, + vector bool short, + vector unsigned char); +vector pixel vec_perm (vector pixel, + vector pixel, + vector unsigned char); +vector signed char vec_perm (vector signed char, + vector signed char, + vector unsigned char); +vector unsigned char vec_perm (vector unsigned char, + vector unsigned char, + vector unsigned char); +vector bool char vec_perm (vector bool char, + vector bool char, + vector unsigned char); + +vector float vec_re (vector float); + +vector signed char vec_rl (vector signed char, + vector unsigned char); +vector unsigned char vec_rl (vector unsigned char, + vector unsigned char); +vector signed short vec_rl (vector signed short, vector unsigned short); +vector unsigned short vec_rl (vector unsigned short, + vector unsigned short); +vector signed int vec_rl (vector signed int, vector unsigned int); +vector unsigned int vec_rl (vector unsigned int, vector unsigned int); + +vector signed int vec_vrlw (vector signed int, vector unsigned int); +vector unsigned int vec_vrlw (vector unsigned int, vector unsigned int); + +vector signed short vec_vrlh (vector signed short, + vector unsigned short); +vector unsigned short vec_vrlh (vector unsigned short, + vector unsigned short); + +vector signed char vec_vrlb (vector signed char, vector unsigned char); +vector unsigned char vec_vrlb (vector unsigned char, + vector unsigned char); + +vector float vec_round (vector float); + +vector float vec_recip (vector float, vector float); + +vector float vec_rsqrt (vector float); + +vector float vec_rsqrte (vector float); + +vector float vec_sel (vector float, vector float, vector bool int); +vector float vec_sel (vector float, vector float, vector unsigned int); +vector signed int vec_sel (vector signed int, + vector signed int, + vector bool int); +vector signed int vec_sel (vector signed int, + vector signed int, + vector unsigned int); +vector unsigned int vec_sel (vector unsigned int, + vector unsigned int, + vector bool int); +vector unsigned int vec_sel (vector unsigned int, + vector unsigned int, + vector unsigned int); +vector bool int vec_sel (vector bool int, + vector bool int, + vector bool int); +vector bool int vec_sel (vector bool int, + vector bool int, + vector unsigned int); +vector signed short vec_sel (vector signed short, + vector signed short, + vector bool short); +vector signed short vec_sel (vector signed short, + vector signed short, + vector unsigned short); +vector unsigned short vec_sel (vector unsigned short, + vector unsigned short, + vector bool short); +vector unsigned short vec_sel (vector unsigned short, + vector unsigned short, + vector unsigned short); +vector bool short vec_sel (vector bool short, + vector bool short, + vector bool short); +vector bool short vec_sel (vector bool short, + vector bool short, + vector unsigned short); +vector signed char vec_sel (vector signed char, + vector signed char, + vector bool char); +vector signed char vec_sel (vector signed char, + vector signed char, + vector unsigned char); +vector unsigned char vec_sel (vector unsigned char, + vector unsigned char, + vector bool char); +vector unsigned char vec_sel (vector unsigned char, + vector unsigned char, + vector unsigned char); +vector bool char vec_sel (vector bool char, + vector bool char, + vector bool char); +vector bool char vec_sel (vector bool char, + vector bool char, + vector unsigned char); + +vector signed char vec_sl (vector signed char, + vector unsigned char); +vector unsigned char vec_sl (vector unsigned char, + vector unsigned char); +vector signed short vec_sl (vector signed short, vector unsigned short); +vector unsigned short vec_sl (vector unsigned short, + vector unsigned short); +vector signed int vec_sl (vector signed int, vector unsigned int); +vector unsigned int vec_sl (vector unsigned int, vector unsigned int); + +vector signed int vec_vslw (vector signed int, vector unsigned int); +vector unsigned int vec_vslw (vector unsigned int, vector unsigned int); + +vector signed short vec_vslh (vector signed short, + vector unsigned short); +vector unsigned short vec_vslh (vector unsigned short, + vector unsigned short); + +vector signed char vec_vslb (vector signed char, vector unsigned char); +vector unsigned char vec_vslb (vector unsigned char, + vector unsigned char); + +vector float vec_sld (vector float, vector float, const int); +vector signed int vec_sld (vector signed int, + vector signed int, + const int); +vector unsigned int vec_sld (vector unsigned int, + vector unsigned int, + const int); +vector bool int vec_sld (vector bool int, + vector bool int, + const int); +vector signed short vec_sld (vector signed short, + vector signed short, + const int); +vector unsigned short vec_sld (vector unsigned short, + vector unsigned short, + const int); +vector bool short vec_sld (vector bool short, + vector bool short, + const int); +vector pixel vec_sld (vector pixel, + vector pixel, + const int); +vector signed char vec_sld (vector signed char, + vector signed char, + const int); +vector unsigned char vec_sld (vector unsigned char, + vector unsigned char, + const int); +vector bool char vec_sld (vector bool char, + vector bool char, + const int); + +vector signed int vec_sll (vector signed int, + vector unsigned int); +vector signed int vec_sll (vector signed int, + vector unsigned short); +vector signed int vec_sll (vector signed int, + vector unsigned char); +vector unsigned int vec_sll (vector unsigned int, + vector unsigned int); +vector unsigned int vec_sll (vector unsigned int, + vector unsigned short); +vector unsigned int vec_sll (vector unsigned int, + vector unsigned char); +vector bool int vec_sll (vector bool int, + vector unsigned int); +vector bool int vec_sll (vector bool int, + vector unsigned short); +vector bool int vec_sll (vector bool int, + vector unsigned char); +vector signed short vec_sll (vector signed short, + vector unsigned int); +vector signed short vec_sll (vector signed short, + vector unsigned short); +vector signed short vec_sll (vector signed short, + vector unsigned char); +vector unsigned short vec_sll (vector unsigned short, + vector unsigned int); +vector unsigned short vec_sll (vector unsigned short, + vector unsigned short); +vector unsigned short vec_sll (vector unsigned short, + vector unsigned char); +vector bool short vec_sll (vector bool short, vector unsigned int); +vector bool short vec_sll (vector bool short, vector unsigned short); +vector bool short vec_sll (vector bool short, vector unsigned char); +vector pixel vec_sll (vector pixel, vector unsigned int); +vector pixel vec_sll (vector pixel, vector unsigned short); +vector pixel vec_sll (vector pixel, vector unsigned char); +vector signed char vec_sll (vector signed char, vector unsigned int); +vector signed char vec_sll (vector signed char, vector unsigned short); +vector signed char vec_sll (vector signed char, vector unsigned char); +vector unsigned char vec_sll (vector unsigned char, + vector unsigned int); +vector unsigned char vec_sll (vector unsigned char, + vector unsigned short); +vector unsigned char vec_sll (vector unsigned char, + vector unsigned char); +vector bool char vec_sll (vector bool char, vector unsigned int); +vector bool char vec_sll (vector bool char, vector unsigned short); +vector bool char vec_sll (vector bool char, vector unsigned char); + +vector float vec_slo (vector float, vector signed char); +vector float vec_slo (vector float, vector unsigned char); +vector signed int vec_slo (vector signed int, vector signed char); +vector signed int vec_slo (vector signed int, vector unsigned char); +vector unsigned int vec_slo (vector unsigned int, vector signed char); +vector unsigned int vec_slo (vector unsigned int, vector unsigned char); +vector signed short vec_slo (vector signed short, vector signed char); +vector signed short vec_slo (vector signed short, vector unsigned char); +vector unsigned short vec_slo (vector unsigned short, + vector signed char); +vector unsigned short vec_slo (vector unsigned short, + vector unsigned char); +vector pixel vec_slo (vector pixel, vector signed char); +vector pixel vec_slo (vector pixel, vector unsigned char); +vector signed char vec_slo (vector signed char, vector signed char); +vector signed char vec_slo (vector signed char, vector unsigned char); +vector unsigned char vec_slo (vector unsigned char, vector signed char); +vector unsigned char vec_slo (vector unsigned char, + vector unsigned char); + +vector signed char vec_splat (vector signed char, const int); +vector unsigned char vec_splat (vector unsigned char, const int); +vector bool char vec_splat (vector bool char, const int); +vector signed short vec_splat (vector signed short, const int); +vector unsigned short vec_splat (vector unsigned short, const int); +vector bool short vec_splat (vector bool short, const int); +vector pixel vec_splat (vector pixel, const int); +vector float vec_splat (vector float, const int); +vector signed int vec_splat (vector signed int, const int); +vector unsigned int vec_splat (vector unsigned int, const int); +vector bool int vec_splat (vector bool int, const int); + +vector float vec_vspltw (vector float, const int); +vector signed int vec_vspltw (vector signed int, const int); +vector unsigned int vec_vspltw (vector unsigned int, const int); +vector bool int vec_vspltw (vector bool int, const int); + +vector bool short vec_vsplth (vector bool short, const int); +vector signed short vec_vsplth (vector signed short, const int); +vector unsigned short vec_vsplth (vector unsigned short, const int); +vector pixel vec_vsplth (vector pixel, const int); + +vector signed char vec_vspltb (vector signed char, const int); +vector unsigned char vec_vspltb (vector unsigned char, const int); +vector bool char vec_vspltb (vector bool char, const int); + +vector signed char vec_splat_s8 (const int); + +vector signed short vec_splat_s16 (const int); + +vector signed int vec_splat_s32 (const int); + +vector unsigned char vec_splat_u8 (const int); + +vector unsigned short vec_splat_u16 (const int); + +vector unsigned int vec_splat_u32 (const int); + +vector signed char vec_sr (vector signed char, vector unsigned char); +vector unsigned char vec_sr (vector unsigned char, + vector unsigned char); +vector signed short vec_sr (vector signed short, + vector unsigned short); +vector unsigned short vec_sr (vector unsigned short, + vector unsigned short); +vector signed int vec_sr (vector signed int, vector unsigned int); +vector unsigned int vec_sr (vector unsigned int, vector unsigned int); + +vector signed int vec_vsrw (vector signed int, vector unsigned int); +vector unsigned int vec_vsrw (vector unsigned int, vector unsigned int); + +vector signed short vec_vsrh (vector signed short, + vector unsigned short); +vector unsigned short vec_vsrh (vector unsigned short, + vector unsigned short); + +vector signed char vec_vsrb (vector signed char, vector unsigned char); +vector unsigned char vec_vsrb (vector unsigned char, + vector unsigned char); + +vector signed char vec_sra (vector signed char, vector unsigned char); +vector unsigned char vec_sra (vector unsigned char, + vector unsigned char); +vector signed short vec_sra (vector signed short, + vector unsigned short); +vector unsigned short vec_sra (vector unsigned short, + vector unsigned short); +vector signed int vec_sra (vector signed int, vector unsigned int); +vector unsigned int vec_sra (vector unsigned int, vector unsigned int); + +vector signed int vec_vsraw (vector signed int, vector unsigned int); +vector unsigned int vec_vsraw (vector unsigned int, + vector unsigned int); + +vector signed short vec_vsrah (vector signed short, + vector unsigned short); +vector unsigned short vec_vsrah (vector unsigned short, + vector unsigned short); + +vector signed char vec_vsrab (vector signed char, vector unsigned char); +vector unsigned char vec_vsrab (vector unsigned char, + vector unsigned char); + +vector signed int vec_srl (vector signed int, vector unsigned int); +vector signed int vec_srl (vector signed int, vector unsigned short); +vector signed int vec_srl (vector signed int, vector unsigned char); +vector unsigned int vec_srl (vector unsigned int, vector unsigned int); +vector unsigned int vec_srl (vector unsigned int, + vector unsigned short); +vector unsigned int vec_srl (vector unsigned int, vector unsigned char); +vector bool int vec_srl (vector bool int, vector unsigned int); +vector bool int vec_srl (vector bool int, vector unsigned short); +vector bool int vec_srl (vector bool int, vector unsigned char); +vector signed short vec_srl (vector signed short, vector unsigned int); +vector signed short vec_srl (vector signed short, + vector unsigned short); +vector signed short vec_srl (vector signed short, vector unsigned char); +vector unsigned short vec_srl (vector unsigned short, + vector unsigned int); +vector unsigned short vec_srl (vector unsigned short, + vector unsigned short); +vector unsigned short vec_srl (vector unsigned short, + vector unsigned char); +vector bool short vec_srl (vector bool short, vector unsigned int); +vector bool short vec_srl (vector bool short, vector unsigned short); +vector bool short vec_srl (vector bool short, vector unsigned char); +vector pixel vec_srl (vector pixel, vector unsigned int); +vector pixel vec_srl (vector pixel, vector unsigned short); +vector pixel vec_srl (vector pixel, vector unsigned char); +vector signed char vec_srl (vector signed char, vector unsigned int); +vector signed char vec_srl (vector signed char, vector unsigned short); +vector signed char vec_srl (vector signed char, vector unsigned char); +vector unsigned char vec_srl (vector unsigned char, + vector unsigned int); +vector unsigned char vec_srl (vector unsigned char, + vector unsigned short); +vector unsigned char vec_srl (vector unsigned char, + vector unsigned char); +vector bool char vec_srl (vector bool char, vector unsigned int); +vector bool char vec_srl (vector bool char, vector unsigned short); +vector bool char vec_srl (vector bool char, vector unsigned char); + +vector float vec_sro (vector float, vector signed char); +vector float vec_sro (vector float, vector unsigned char); +vector signed int vec_sro (vector signed int, vector signed char); +vector signed int vec_sro (vector signed int, vector unsigned char); +vector unsigned int vec_sro (vector unsigned int, vector signed char); +vector unsigned int vec_sro (vector unsigned int, vector unsigned char); +vector signed short vec_sro (vector signed short, vector signed char); +vector signed short vec_sro (vector signed short, vector unsigned char); +vector unsigned short vec_sro (vector unsigned short, + vector signed char); +vector unsigned short vec_sro (vector unsigned short, + vector unsigned char); +vector pixel vec_sro (vector pixel, vector signed char); +vector pixel vec_sro (vector pixel, vector unsigned char); +vector signed char vec_sro (vector signed char, vector signed char); +vector signed char vec_sro (vector signed char, vector unsigned char); +vector unsigned char vec_sro (vector unsigned char, vector signed char); +vector unsigned char vec_sro (vector unsigned char, + vector unsigned char); + +void vec_st (vector float, int, vector float *); +void vec_st (vector float, int, float *); +void vec_st (vector signed int, int, vector signed int *); +void vec_st (vector signed int, int, int *); +void vec_st (vector unsigned int, int, vector unsigned int *); +void vec_st (vector unsigned int, int, unsigned int *); +void vec_st (vector bool int, int, vector bool int *); +void vec_st (vector bool int, int, unsigned int *); +void vec_st (vector bool int, int, int *); +void vec_st (vector signed short, int, vector signed short *); +void vec_st (vector signed short, int, short *); +void vec_st (vector unsigned short, int, vector unsigned short *); +void vec_st (vector unsigned short, int, unsigned short *); +void vec_st (vector bool short, int, vector bool short *); +void vec_st (vector bool short, int, unsigned short *); +void vec_st (vector pixel, int, vector pixel *); +void vec_st (vector pixel, int, unsigned short *); +void vec_st (vector pixel, int, short *); +void vec_st (vector bool short, int, short *); +void vec_st (vector signed char, int, vector signed char *); +void vec_st (vector signed char, int, signed char *); +void vec_st (vector unsigned char, int, vector unsigned char *); +void vec_st (vector unsigned char, int, unsigned char *); +void vec_st (vector bool char, int, vector bool char *); +void vec_st (vector bool char, int, unsigned char *); +void vec_st (vector bool char, int, signed char *); + +void vec_ste (vector signed char, int, signed char *); +void vec_ste (vector unsigned char, int, unsigned char *); +void vec_ste (vector bool char, int, signed char *); +void vec_ste (vector bool char, int, unsigned char *); +void vec_ste (vector signed short, int, short *); +void vec_ste (vector unsigned short, int, unsigned short *); +void vec_ste (vector bool short, int, short *); +void vec_ste (vector bool short, int, unsigned short *); +void vec_ste (vector pixel, int, short *); +void vec_ste (vector pixel, int, unsigned short *); +void vec_ste (vector float, int, float *); +void vec_ste (vector signed int, int, int *); +void vec_ste (vector unsigned int, int, unsigned int *); +void vec_ste (vector bool int, int, int *); +void vec_ste (vector bool int, int, unsigned int *); + +void vec_stvewx (vector float, int, float *); +void vec_stvewx (vector signed int, int, int *); +void vec_stvewx (vector unsigned int, int, unsigned int *); +void vec_stvewx (vector bool int, int, int *); +void vec_stvewx (vector bool int, int, unsigned int *); + +void vec_stvehx (vector signed short, int, short *); +void vec_stvehx (vector unsigned short, int, unsigned short *); +void vec_stvehx (vector bool short, int, short *); +void vec_stvehx (vector bool short, int, unsigned short *); +void vec_stvehx (vector pixel, int, short *); +void vec_stvehx (vector pixel, int, unsigned short *); + +void vec_stvebx (vector signed char, int, signed char *); +void vec_stvebx (vector unsigned char, int, unsigned char *); +void vec_stvebx (vector bool char, int, signed char *); +void vec_stvebx (vector bool char, int, unsigned char *); + +void vec_stl (vector float, int, vector float *); +void vec_stl (vector float, int, float *); +void vec_stl (vector signed int, int, vector signed int *); +void vec_stl (vector signed int, int, int *); +void vec_stl (vector unsigned int, int, vector unsigned int *); +void vec_stl (vector unsigned int, int, unsigned int *); +void vec_stl (vector bool int, int, vector bool int *); +void vec_stl (vector bool int, int, unsigned int *); +void vec_stl (vector bool int, int, int *); +void vec_stl (vector signed short, int, vector signed short *); +void vec_stl (vector signed short, int, short *); +void vec_stl (vector unsigned short, int, vector unsigned short *); +void vec_stl (vector unsigned short, int, unsigned short *); +void vec_stl (vector bool short, int, vector bool short *); +void vec_stl (vector bool short, int, unsigned short *); +void vec_stl (vector bool short, int, short *); +void vec_stl (vector pixel, int, vector pixel *); +void vec_stl (vector pixel, int, unsigned short *); +void vec_stl (vector pixel, int, short *); +void vec_stl (vector signed char, int, vector signed char *); +void vec_stl (vector signed char, int, signed char *); +void vec_stl (vector unsigned char, int, vector unsigned char *); +void vec_stl (vector unsigned char, int, unsigned char *); +void vec_stl (vector bool char, int, vector bool char *); +void vec_stl (vector bool char, int, unsigned char *); +void vec_stl (vector bool char, int, signed char *); + +vector signed char vec_sub (vector bool char, vector signed char); +vector signed char vec_sub (vector signed char, vector bool char); +vector signed char vec_sub (vector signed char, vector signed char); +vector unsigned char vec_sub (vector bool char, vector unsigned char); +vector unsigned char vec_sub (vector unsigned char, vector bool char); +vector unsigned char vec_sub (vector unsigned char, + vector unsigned char); +vector signed short vec_sub (vector bool short, vector signed short); +vector signed short vec_sub (vector signed short, vector bool short); +vector signed short vec_sub (vector signed short, vector signed short); +vector unsigned short vec_sub (vector bool short, + vector unsigned short); +vector unsigned short vec_sub (vector unsigned short, + vector bool short); +vector unsigned short vec_sub (vector unsigned short, + vector unsigned short); +vector signed int vec_sub (vector bool int, vector signed int); +vector signed int vec_sub (vector signed int, vector bool int); +vector signed int vec_sub (vector signed int, vector signed int); +vector unsigned int vec_sub (vector bool int, vector unsigned int); +vector unsigned int vec_sub (vector unsigned int, vector bool int); +vector unsigned int vec_sub (vector unsigned int, vector unsigned int); +vector float vec_sub (vector float, vector float); + +vector float vec_vsubfp (vector float, vector float); + +vector signed int vec_vsubuwm (vector bool int, vector signed int); +vector signed int vec_vsubuwm (vector signed int, vector bool int); +vector signed int vec_vsubuwm (vector signed int, vector signed int); +vector unsigned int vec_vsubuwm (vector bool int, vector unsigned int); +vector unsigned int vec_vsubuwm (vector unsigned int, vector bool int); +vector unsigned int vec_vsubuwm (vector unsigned int, + vector unsigned int); + +vector signed short vec_vsubuhm (vector bool short, + vector signed short); +vector signed short vec_vsubuhm (vector signed short, + vector bool short); +vector signed short vec_vsubuhm (vector signed short, + vector signed short); +vector unsigned short vec_vsubuhm (vector bool short, + vector unsigned short); +vector unsigned short vec_vsubuhm (vector unsigned short, + vector bool short); +vector unsigned short vec_vsubuhm (vector unsigned short, + vector unsigned short); + +vector signed char vec_vsububm (vector bool char, vector signed char); +vector signed char vec_vsububm (vector signed char, vector bool char); +vector signed char vec_vsububm (vector signed char, vector signed char); +vector unsigned char vec_vsububm (vector bool char, + vector unsigned char); +vector unsigned char vec_vsububm (vector unsigned char, + vector bool char); +vector unsigned char vec_vsububm (vector unsigned char, + vector unsigned char); + +vector unsigned int vec_subc (vector unsigned int, vector unsigned int); + +vector unsigned char vec_subs (vector bool char, vector unsigned char); +vector unsigned char vec_subs (vector unsigned char, vector bool char); +vector unsigned char vec_subs (vector unsigned char, + vector unsigned char); +vector signed char vec_subs (vector bool char, vector signed char); +vector signed char vec_subs (vector signed char, vector bool char); +vector signed char vec_subs (vector signed char, vector signed char); +vector unsigned short vec_subs (vector bool short, + vector unsigned short); +vector unsigned short vec_subs (vector unsigned short, + vector bool short); +vector unsigned short vec_subs (vector unsigned short, + vector unsigned short); +vector signed short vec_subs (vector bool short, vector signed short); +vector signed short vec_subs (vector signed short, vector bool short); +vector signed short vec_subs (vector signed short, vector signed short); +vector unsigned int vec_subs (vector bool int, vector unsigned int); +vector unsigned int vec_subs (vector unsigned int, vector bool int); +vector unsigned int vec_subs (vector unsigned int, vector unsigned int); +vector signed int vec_subs (vector bool int, vector signed int); +vector signed int vec_subs (vector signed int, vector bool int); +vector signed int vec_subs (vector signed int, vector signed int); + +vector signed int vec_vsubsws (vector bool int, vector signed int); +vector signed int vec_vsubsws (vector signed int, vector bool int); +vector signed int vec_vsubsws (vector signed int, vector signed int); + +vector unsigned int vec_vsubuws (vector bool int, vector unsigned int); +vector unsigned int vec_vsubuws (vector unsigned int, vector bool int); +vector unsigned int vec_vsubuws (vector unsigned int, + vector unsigned int); + +vector signed short vec_vsubshs (vector bool short, + vector signed short); +vector signed short vec_vsubshs (vector signed short, + vector bool short); +vector signed short vec_vsubshs (vector signed short, + vector signed short); + +vector unsigned short vec_vsubuhs (vector bool short, + vector unsigned short); +vector unsigned short vec_vsubuhs (vector unsigned short, + vector bool short); +vector unsigned short vec_vsubuhs (vector unsigned short, + vector unsigned short); + +vector signed char vec_vsubsbs (vector bool char, vector signed char); +vector signed char vec_vsubsbs (vector signed char, vector bool char); +vector signed char vec_vsubsbs (vector signed char, vector signed char); + +vector unsigned char vec_vsububs (vector bool char, + vector unsigned char); +vector unsigned char vec_vsububs (vector unsigned char, + vector bool char); +vector unsigned char vec_vsububs (vector unsigned char, + vector unsigned char); + +vector unsigned int vec_sum4s (vector unsigned char, + vector unsigned int); +vector signed int vec_sum4s (vector signed char, vector signed int); +vector signed int vec_sum4s (vector signed short, vector signed int); + +vector signed int vec_vsum4shs (vector signed short, vector signed int); + +vector signed int vec_vsum4sbs (vector signed char, vector signed int); + +vector unsigned int vec_vsum4ubs (vector unsigned char, + vector unsigned int); + +vector signed int vec_sum2s (vector signed int, vector signed int); + +vector signed int vec_sums (vector signed int, vector signed int); + +vector float vec_trunc (vector float); + +vector signed short vec_unpackh (vector signed char); +vector bool short vec_unpackh (vector bool char); +vector signed int vec_unpackh (vector signed short); +vector bool int vec_unpackh (vector bool short); +vector unsigned int vec_unpackh (vector pixel); + +vector bool int vec_vupkhsh (vector bool short); +vector signed int vec_vupkhsh (vector signed short); + +vector unsigned int vec_vupkhpx (vector pixel); + +vector bool short vec_vupkhsb (vector bool char); +vector signed short vec_vupkhsb (vector signed char); + +vector signed short vec_unpackl (vector signed char); +vector bool short vec_unpackl (vector bool char); +vector unsigned int vec_unpackl (vector pixel); +vector signed int vec_unpackl (vector signed short); +vector bool int vec_unpackl (vector bool short); + +vector unsigned int vec_vupklpx (vector pixel); + +vector bool int vec_vupklsh (vector bool short); +vector signed int vec_vupklsh (vector signed short); + +vector bool short vec_vupklsb (vector bool char); +vector signed short vec_vupklsb (vector signed char); + +vector float vec_xor (vector float, vector float); +vector float vec_xor (vector float, vector bool int); +vector float vec_xor (vector bool int, vector float); +vector bool int vec_xor (vector bool int, vector bool int); +vector signed int vec_xor (vector bool int, vector signed int); +vector signed int vec_xor (vector signed int, vector bool int); +vector signed int vec_xor (vector signed int, vector signed int); +vector unsigned int vec_xor (vector bool int, vector unsigned int); +vector unsigned int vec_xor (vector unsigned int, vector bool int); +vector unsigned int vec_xor (vector unsigned int, vector unsigned int); +vector bool short vec_xor (vector bool short, vector bool short); +vector signed short vec_xor (vector bool short, vector signed short); +vector signed short vec_xor (vector signed short, vector bool short); +vector signed short vec_xor (vector signed short, vector signed short); +vector unsigned short vec_xor (vector bool short, + vector unsigned short); +vector unsigned short vec_xor (vector unsigned short, + vector bool short); +vector unsigned short vec_xor (vector unsigned short, + vector unsigned short); +vector signed char vec_xor (vector bool char, vector signed char); +vector bool char vec_xor (vector bool char, vector bool char); +vector signed char vec_xor (vector signed char, vector bool char); +vector signed char vec_xor (vector signed char, vector signed char); +vector unsigned char vec_xor (vector bool char, vector unsigned char); +vector unsigned char vec_xor (vector unsigned char, vector bool char); +vector unsigned char vec_xor (vector unsigned char, + vector unsigned char); + +int vec_all_eq (vector signed char, vector bool char); +int vec_all_eq (vector signed char, vector signed char); +int vec_all_eq (vector unsigned char, vector bool char); +int vec_all_eq (vector unsigned char, vector unsigned char); +int vec_all_eq (vector bool char, vector bool char); +int vec_all_eq (vector bool char, vector unsigned char); +int vec_all_eq (vector bool char, vector signed char); +int vec_all_eq (vector signed short, vector bool short); +int vec_all_eq (vector signed short, vector signed short); +int vec_all_eq (vector unsigned short, vector bool short); +int vec_all_eq (vector unsigned short, vector unsigned short); +int vec_all_eq (vector bool short, vector bool short); +int vec_all_eq (vector bool short, vector unsigned short); +int vec_all_eq (vector bool short, vector signed short); +int vec_all_eq (vector pixel, vector pixel); +int vec_all_eq (vector signed int, vector bool int); +int vec_all_eq (vector signed int, vector signed int); +int vec_all_eq (vector unsigned int, vector bool int); +int vec_all_eq (vector unsigned int, vector unsigned int); +int vec_all_eq (vector bool int, vector bool int); +int vec_all_eq (vector bool int, vector unsigned int); +int vec_all_eq (vector bool int, vector signed int); +int vec_all_eq (vector float, vector float); + +int vec_all_ge (vector bool char, vector unsigned char); +int vec_all_ge (vector unsigned char, vector bool char); +int vec_all_ge (vector unsigned char, vector unsigned char); +int vec_all_ge (vector bool char, vector signed char); +int vec_all_ge (vector signed char, vector bool char); +int vec_all_ge (vector signed char, vector signed char); +int vec_all_ge (vector bool short, vector unsigned short); +int vec_all_ge (vector unsigned short, vector bool short); +int vec_all_ge (vector unsigned short, vector unsigned short); +int vec_all_ge (vector signed short, vector signed short); +int vec_all_ge (vector bool short, vector signed short); +int vec_all_ge (vector signed short, vector bool short); +int vec_all_ge (vector bool int, vector unsigned int); +int vec_all_ge (vector unsigned int, vector bool int); +int vec_all_ge (vector unsigned int, vector unsigned int); +int vec_all_ge (vector bool int, vector signed int); +int vec_all_ge (vector signed int, vector bool int); +int vec_all_ge (vector signed int, vector signed int); +int vec_all_ge (vector float, vector float); + +int vec_all_gt (vector bool char, vector unsigned char); +int vec_all_gt (vector unsigned char, vector bool char); +int vec_all_gt (vector unsigned char, vector unsigned char); +int vec_all_gt (vector bool char, vector signed char); +int vec_all_gt (vector signed char, vector bool char); +int vec_all_gt (vector signed char, vector signed char); +int vec_all_gt (vector bool short, vector unsigned short); +int vec_all_gt (vector unsigned short, vector bool short); +int vec_all_gt (vector unsigned short, vector unsigned short); +int vec_all_gt (vector bool short, vector signed short); +int vec_all_gt (vector signed short, vector bool short); +int vec_all_gt (vector signed short, vector signed short); +int vec_all_gt (vector bool int, vector unsigned int); +int vec_all_gt (vector unsigned int, vector bool int); +int vec_all_gt (vector unsigned int, vector unsigned int); +int vec_all_gt (vector bool int, vector signed int); +int vec_all_gt (vector signed int, vector bool int); +int vec_all_gt (vector signed int, vector signed int); +int vec_all_gt (vector float, vector float); + +int vec_all_in (vector float, vector float); + +int vec_all_le (vector bool char, vector unsigned char); +int vec_all_le (vector unsigned char, vector bool char); +int vec_all_le (vector unsigned char, vector unsigned char); +int vec_all_le (vector bool char, vector signed char); +int vec_all_le (vector signed char, vector bool char); +int vec_all_le (vector signed char, vector signed char); +int vec_all_le (vector bool short, vector unsigned short); +int vec_all_le (vector unsigned short, vector bool short); +int vec_all_le (vector unsigned short, vector unsigned short); +int vec_all_le (vector bool short, vector signed short); +int vec_all_le (vector signed short, vector bool short); +int vec_all_le (vector signed short, vector signed short); +int vec_all_le (vector bool int, vector unsigned int); +int vec_all_le (vector unsigned int, vector bool int); +int vec_all_le (vector unsigned int, vector unsigned int); +int vec_all_le (vector bool int, vector signed int); +int vec_all_le (vector signed int, vector bool int); +int vec_all_le (vector signed int, vector signed int); +int vec_all_le (vector float, vector float); + +int vec_all_lt (vector bool char, vector unsigned char); +int vec_all_lt (vector unsigned char, vector bool char); +int vec_all_lt (vector unsigned char, vector unsigned char); +int vec_all_lt (vector bool char, vector signed char); +int vec_all_lt (vector signed char, vector bool char); +int vec_all_lt (vector signed char, vector signed char); +int vec_all_lt (vector bool short, vector unsigned short); +int vec_all_lt (vector unsigned short, vector bool short); +int vec_all_lt (vector unsigned short, vector unsigned short); +int vec_all_lt (vector bool short, vector signed short); +int vec_all_lt (vector signed short, vector bool short); +int vec_all_lt (vector signed short, vector signed short); +int vec_all_lt (vector bool int, vector unsigned int); +int vec_all_lt (vector unsigned int, vector bool int); +int vec_all_lt (vector unsigned int, vector unsigned int); +int vec_all_lt (vector bool int, vector signed int); +int vec_all_lt (vector signed int, vector bool int); +int vec_all_lt (vector signed int, vector signed int); +int vec_all_lt (vector float, vector float); + +int vec_all_nan (vector float); + +int vec_all_ne (vector signed char, vector bool char); +int vec_all_ne (vector signed char, vector signed char); +int vec_all_ne (vector unsigned char, vector bool char); +int vec_all_ne (vector unsigned char, vector unsigned char); +int vec_all_ne (vector bool char, vector bool char); +int vec_all_ne (vector bool char, vector unsigned char); +int vec_all_ne (vector bool char, vector signed char); +int vec_all_ne (vector signed short, vector bool short); +int vec_all_ne (vector signed short, vector signed short); +int vec_all_ne (vector unsigned short, vector bool short); +int vec_all_ne (vector unsigned short, vector unsigned short); +int vec_all_ne (vector bool short, vector bool short); +int vec_all_ne (vector bool short, vector unsigned short); +int vec_all_ne (vector bool short, vector signed short); +int vec_all_ne (vector pixel, vector pixel); +int vec_all_ne (vector signed int, vector bool int); +int vec_all_ne (vector signed int, vector signed int); +int vec_all_ne (vector unsigned int, vector bool int); +int vec_all_ne (vector unsigned int, vector unsigned int); +int vec_all_ne (vector bool int, vector bool int); +int vec_all_ne (vector bool int, vector unsigned int); +int vec_all_ne (vector bool int, vector signed int); +int vec_all_ne (vector float, vector float); + +int vec_all_nge (vector float, vector float); + +int vec_all_ngt (vector float, vector float); + +int vec_all_nle (vector float, vector float); + +int vec_all_nlt (vector float, vector float); + +int vec_all_numeric (vector float); + +int vec_any_eq (vector signed char, vector bool char); +int vec_any_eq (vector signed char, vector signed char); +int vec_any_eq (vector unsigned char, vector bool char); +int vec_any_eq (vector unsigned char, vector unsigned char); +int vec_any_eq (vector bool char, vector bool char); +int vec_any_eq (vector bool char, vector unsigned char); +int vec_any_eq (vector bool char, vector signed char); +int vec_any_eq (vector signed short, vector bool short); +int vec_any_eq (vector signed short, vector signed short); +int vec_any_eq (vector unsigned short, vector bool short); +int vec_any_eq (vector unsigned short, vector unsigned short); +int vec_any_eq (vector bool short, vector bool short); +int vec_any_eq (vector bool short, vector unsigned short); +int vec_any_eq (vector bool short, vector signed short); +int vec_any_eq (vector pixel, vector pixel); +int vec_any_eq (vector signed int, vector bool int); +int vec_any_eq (vector signed int, vector signed int); +int vec_any_eq (vector unsigned int, vector bool int); +int vec_any_eq (vector unsigned int, vector unsigned int); +int vec_any_eq (vector bool int, vector bool int); +int vec_any_eq (vector bool int, vector unsigned int); +int vec_any_eq (vector bool int, vector signed int); +int vec_any_eq (vector float, vector float); + +int vec_any_ge (vector signed char, vector bool char); +int vec_any_ge (vector unsigned char, vector bool char); +int vec_any_ge (vector unsigned char, vector unsigned char); +int vec_any_ge (vector signed char, vector signed char); +int vec_any_ge (vector bool char, vector unsigned char); +int vec_any_ge (vector bool char, vector signed char); +int vec_any_ge (vector unsigned short, vector bool short); +int vec_any_ge (vector unsigned short, vector unsigned short); +int vec_any_ge (vector signed short, vector signed short); +int vec_any_ge (vector signed short, vector bool short); +int vec_any_ge (vector bool short, vector unsigned short); +int vec_any_ge (vector bool short, vector signed short); +int vec_any_ge (vector signed int, vector bool int); +int vec_any_ge (vector unsigned int, vector bool int); +int vec_any_ge (vector unsigned int, vector unsigned int); +int vec_any_ge (vector signed int, vector signed int); +int vec_any_ge (vector bool int, vector unsigned int); +int vec_any_ge (vector bool int, vector signed int); +int vec_any_ge (vector float, vector float); + +int vec_any_gt (vector bool char, vector unsigned char); +int vec_any_gt (vector unsigned char, vector bool char); +int vec_any_gt (vector unsigned char, vector unsigned char); +int vec_any_gt (vector bool char, vector signed char); +int vec_any_gt (vector signed char, vector bool char); +int vec_any_gt (vector signed char, vector signed char); +int vec_any_gt (vector bool short, vector unsigned short); +int vec_any_gt (vector unsigned short, vector bool short); +int vec_any_gt (vector unsigned short, vector unsigned short); +int vec_any_gt (vector bool short, vector signed short); +int vec_any_gt (vector signed short, vector bool short); +int vec_any_gt (vector signed short, vector signed short); +int vec_any_gt (vector bool int, vector unsigned int); +int vec_any_gt (vector unsigned int, vector bool int); +int vec_any_gt (vector unsigned int, vector unsigned int); +int vec_any_gt (vector bool int, vector signed int); +int vec_any_gt (vector signed int, vector bool int); +int vec_any_gt (vector signed int, vector signed int); +int vec_any_gt (vector float, vector float); + +int vec_any_le (vector bool char, vector unsigned char); +int vec_any_le (vector unsigned char, vector bool char); +int vec_any_le (vector unsigned char, vector unsigned char); +int vec_any_le (vector bool char, vector signed char); +int vec_any_le (vector signed char, vector bool char); +int vec_any_le (vector signed char, vector signed char); +int vec_any_le (vector bool short, vector unsigned short); +int vec_any_le (vector unsigned short, vector bool short); +int vec_any_le (vector unsigned short, vector unsigned short); +int vec_any_le (vector bool short, vector signed short); +int vec_any_le (vector signed short, vector bool short); +int vec_any_le (vector signed short, vector signed short); +int vec_any_le (vector bool int, vector unsigned int); +int vec_any_le (vector unsigned int, vector bool int); +int vec_any_le (vector unsigned int, vector unsigned int); +int vec_any_le (vector bool int, vector signed int); +int vec_any_le (vector signed int, vector bool int); +int vec_any_le (vector signed int, vector signed int); +int vec_any_le (vector float, vector float); + +int vec_any_lt (vector bool char, vector unsigned char); +int vec_any_lt (vector unsigned char, vector bool char); +int vec_any_lt (vector unsigned char, vector unsigned char); +int vec_any_lt (vector bool char, vector signed char); +int vec_any_lt (vector signed char, vector bool char); +int vec_any_lt (vector signed char, vector signed char); +int vec_any_lt (vector bool short, vector unsigned short); +int vec_any_lt (vector unsigned short, vector bool short); +int vec_any_lt (vector unsigned short, vector unsigned short); +int vec_any_lt (vector bool short, vector signed short); +int vec_any_lt (vector signed short, vector bool short); +int vec_any_lt (vector signed short, vector signed short); +int vec_any_lt (vector bool int, vector unsigned int); +int vec_any_lt (vector unsigned int, vector bool int); +int vec_any_lt (vector unsigned int, vector unsigned int); +int vec_any_lt (vector bool int, vector signed int); +int vec_any_lt (vector signed int, vector bool int); +int vec_any_lt (vector signed int, vector signed int); +int vec_any_lt (vector float, vector float); + +int vec_any_nan (vector float); + +int vec_any_ne (vector signed char, vector bool char); +int vec_any_ne (vector signed char, vector signed char); +int vec_any_ne (vector unsigned char, vector bool char); +int vec_any_ne (vector unsigned char, vector unsigned char); +int vec_any_ne (vector bool char, vector bool char); +int vec_any_ne (vector bool char, vector unsigned char); +int vec_any_ne (vector bool char, vector signed char); +int vec_any_ne (vector signed short, vector bool short); +int vec_any_ne (vector signed short, vector signed short); +int vec_any_ne (vector unsigned short, vector bool short); +int vec_any_ne (vector unsigned short, vector unsigned short); +int vec_any_ne (vector bool short, vector bool short); +int vec_any_ne (vector bool short, vector unsigned short); +int vec_any_ne (vector bool short, vector signed short); +int vec_any_ne (vector pixel, vector pixel); +int vec_any_ne (vector signed int, vector bool int); +int vec_any_ne (vector signed int, vector signed int); +int vec_any_ne (vector unsigned int, vector bool int); +int vec_any_ne (vector unsigned int, vector unsigned int); +int vec_any_ne (vector bool int, vector bool int); +int vec_any_ne (vector bool int, vector unsigned int); +int vec_any_ne (vector bool int, vector signed int); +int vec_any_ne (vector float, vector float); + +int vec_any_nge (vector float, vector float); + +int vec_any_ngt (vector float, vector float); + +int vec_any_nle (vector float, vector float); + +int vec_any_nlt (vector float, vector float); + +int vec_any_numeric (vector float); + +int vec_any_out (vector float, vector float); +@end smallexample + +If the vector/scalar (VSX) instruction set is available, the following +additional functions are available: + +@smallexample +vector double vec_abs (vector double); +vector double vec_add (vector double, vector double); +vector double vec_and (vector double, vector double); +vector double vec_and (vector double, vector bool long); +vector double vec_and (vector bool long, vector double); +vector double vec_andc (vector double, vector double); +vector double vec_andc (vector double, vector bool long); +vector double vec_andc (vector bool long, vector double); +vector double vec_ceil (vector double); +vector bool long vec_cmpeq (vector double, vector double); +vector bool long vec_cmpge (vector double, vector double); +vector bool long vec_cmpgt (vector double, vector double); +vector bool long vec_cmple (vector double, vector double); +vector bool long vec_cmplt (vector double, vector double); +vector float vec_div (vector float, vector float); +vector double vec_div (vector double, vector double); +vector double vec_floor (vector double); +vector double vec_ld (int, const vector double *); +vector double vec_ld (int, const double *); +vector double vec_ldl (int, const vector double *); +vector double vec_ldl (int, const double *); +vector unsigned char vec_lvsl (int, const volatile double *); +vector unsigned char vec_lvsr (int, const volatile double *); +vector double vec_madd (vector double, vector double, vector double); +vector double vec_max (vector double, vector double); +vector double vec_min (vector double, vector double); +vector float vec_msub (vector float, vector float, vector float); +vector double vec_msub (vector double, vector double, vector double); +vector float vec_mul (vector float, vector float); +vector double vec_mul (vector double, vector double); +vector float vec_nearbyint (vector float); +vector double vec_nearbyint (vector double); +vector float vec_nmadd (vector float, vector float, vector float); +vector double vec_nmadd (vector double, vector double, vector double); +vector double vec_nmsub (vector double, vector double, vector double); +vector double vec_nor (vector double, vector double); +vector double vec_or (vector double, vector double); +vector double vec_or (vector double, vector bool long); +vector double vec_or (vector bool long, vector double); +vector double vec_perm (vector double, + vector double, + vector unsigned char); +vector double vec_rint (vector double); +vector double vec_recip (vector double, vector double); +vector double vec_rsqrt (vector double); +vector double vec_rsqrte (vector double); +vector double vec_sel (vector double, vector double, vector bool long); +vector double vec_sel (vector double, vector double, vector unsigned long); +vector double vec_sub (vector double, vector double); +vector float vec_sqrt (vector float); +vector double vec_sqrt (vector double); +void vec_st (vector double, int, vector double *); +void vec_st (vector double, int, double *); +vector double vec_trunc (vector double); +vector double vec_xor (vector double, vector double); +vector double vec_xor (vector double, vector bool long); +vector double vec_xor (vector bool long, vector double); +int vec_all_eq (vector double, vector double); +int vec_all_ge (vector double, vector double); +int vec_all_gt (vector double, vector double); +int vec_all_le (vector double, vector double); +int vec_all_lt (vector double, vector double); +int vec_all_nan (vector double); +int vec_all_ne (vector double, vector double); +int vec_all_nge (vector double, vector double); +int vec_all_ngt (vector double, vector double); +int vec_all_nle (vector double, vector double); +int vec_all_nlt (vector double, vector double); +int vec_all_numeric (vector double); +int vec_any_eq (vector double, vector double); +int vec_any_ge (vector double, vector double); +int vec_any_gt (vector double, vector double); +int vec_any_le (vector double, vector double); +int vec_any_lt (vector double, vector double); +int vec_any_nan (vector double); +int vec_any_ne (vector double, vector double); +int vec_any_nge (vector double, vector double); +int vec_any_ngt (vector double, vector double); +int vec_any_nle (vector double, vector double); +int vec_any_nlt (vector double, vector double); +int vec_any_numeric (vector double); + +vector double vec_vsx_ld (int, const vector double *); +vector double vec_vsx_ld (int, const double *); +vector float vec_vsx_ld (int, const vector float *); +vector float vec_vsx_ld (int, const float *); +vector bool int vec_vsx_ld (int, const vector bool int *); +vector signed int vec_vsx_ld (int, const vector signed int *); +vector signed int vec_vsx_ld (int, const int *); +vector signed int vec_vsx_ld (int, const long *); +vector unsigned int vec_vsx_ld (int, const vector unsigned int *); +vector unsigned int vec_vsx_ld (int, const unsigned int *); +vector unsigned int vec_vsx_ld (int, const unsigned long *); +vector bool short vec_vsx_ld (int, const vector bool short *); +vector pixel vec_vsx_ld (int, const vector pixel *); +vector signed short vec_vsx_ld (int, const vector signed short *); +vector signed short vec_vsx_ld (int, const short *); +vector unsigned short vec_vsx_ld (int, const vector unsigned short *); +vector unsigned short vec_vsx_ld (int, const unsigned short *); +vector bool char vec_vsx_ld (int, const vector bool char *); +vector signed char vec_vsx_ld (int, const vector signed char *); +vector signed char vec_vsx_ld (int, const signed char *); +vector unsigned char vec_vsx_ld (int, const vector unsigned char *); +vector unsigned char vec_vsx_ld (int, const unsigned char *); + +void vec_vsx_st (vector double, int, vector double *); +void vec_vsx_st (vector double, int, double *); +void vec_vsx_st (vector float, int, vector float *); +void vec_vsx_st (vector float, int, float *); +void vec_vsx_st (vector signed int, int, vector signed int *); +void vec_vsx_st (vector signed int, int, int *); +void vec_vsx_st (vector unsigned int, int, vector unsigned int *); +void vec_vsx_st (vector unsigned int, int, unsigned int *); +void vec_vsx_st (vector bool int, int, vector bool int *); +void vec_vsx_st (vector bool int, int, unsigned int *); +void vec_vsx_st (vector bool int, int, int *); +void vec_vsx_st (vector signed short, int, vector signed short *); +void vec_vsx_st (vector signed short, int, short *); +void vec_vsx_st (vector unsigned short, int, vector unsigned short *); +void vec_vsx_st (vector unsigned short, int, unsigned short *); +void vec_vsx_st (vector bool short, int, vector bool short *); +void vec_vsx_st (vector bool short, int, unsigned short *); +void vec_vsx_st (vector pixel, int, vector pixel *); +void vec_vsx_st (vector pixel, int, unsigned short *); +void vec_vsx_st (vector pixel, int, short *); +void vec_vsx_st (vector bool short, int, short *); +void vec_vsx_st (vector signed char, int, vector signed char *); +void vec_vsx_st (vector signed char, int, signed char *); +void vec_vsx_st (vector unsigned char, int, vector unsigned char *); +void vec_vsx_st (vector unsigned char, int, unsigned char *); +void vec_vsx_st (vector bool char, int, vector bool char *); +void vec_vsx_st (vector bool char, int, unsigned char *); +void vec_vsx_st (vector bool char, int, signed char *); +@end smallexample + +Note that the @samp{vec_ld} and @samp{vec_st} builtins will always +generate the Altivec @samp{LVX} and @samp{STVX} instructions even +if the VSX instruction set is available. The @samp{vec_vsx_ld} and +@samp{vec_vsx_st} builtins will always generate the VSX @samp{LXVD2X}, +@samp{LXVW4X}, @samp{STXVD2X}, and @samp{STXVW4X} instructions. + +GCC provides a few other builtins on Powerpc to access certain instructions: +@smallexample +float __builtin_recipdivf (float, float); +float __builtin_rsqrtf (float); +double __builtin_recipdiv (double, double); +double __builtin_rsqrt (double); +long __builtin_bpermd (long, long); +int __builtin_bswap16 (int); +@end smallexample + +The @code{vec_rsqrt}, @code{__builtin_rsqrt}, and +@code{__builtin_rsqrtf} functions generate multiple instructions to +implement the reciprocal sqrt functionality using reciprocal sqrt +estimate instructions. + +The @code{__builtin_recipdiv}, and @code{__builtin_recipdivf} +functions generate multiple instructions to implement division using +the reciprocal estimate instructions. + +@node RX Built-in Functions +@subsection RX Built-in Functions +GCC supports some of the RX instructions which cannot be expressed in +the C programming language via the use of built-in functions. The +following functions are supported: + +@deftypefn {Built-in Function} void __builtin_rx_brk (void) +Generates the @code{brk} machine instruction. +@end deftypefn + +@deftypefn {Built-in Function} void __builtin_rx_clrpsw (int) +Generates the @code{clrpsw} machine instruction to clear the specified +bit in the processor status word. +@end deftypefn + +@deftypefn {Built-in Function} void __builtin_rx_int (int) +Generates the @code{int} machine instruction to generate an interrupt +with the specified value. +@end deftypefn + +@deftypefn {Built-in Function} void __builtin_rx_machi (int, int) +Generates the @code{machi} machine instruction to add the result of +multiplying the top 16-bits of the two arguments into the +accumulator. +@end deftypefn + +@deftypefn {Built-in Function} void __builtin_rx_maclo (int, int) +Generates the @code{maclo} machine instruction to add the result of +multiplying the bottom 16-bits of the two arguments into the +accumulator. +@end deftypefn + +@deftypefn {Built-in Function} void __builtin_rx_mulhi (int, int) +Generates the @code{mulhi} machine instruction to place the result of +multiplying the top 16-bits of the two arguments into the +accumulator. +@end deftypefn + +@deftypefn {Built-in Function} void __builtin_rx_mullo (int, int) +Generates the @code{mullo} machine instruction to place the result of +multiplying the bottom 16-bits of the two arguments into the +accumulator. +@end deftypefn + +@deftypefn {Built-in Function} int __builtin_rx_mvfachi (void) +Generates the @code{mvfachi} machine instruction to read the top +32-bits of the accumulator. +@end deftypefn + +@deftypefn {Built-in Function} int __builtin_rx_mvfacmi (void) +Generates the @code{mvfacmi} machine instruction to read the middle +32-bits of the accumulator. +@end deftypefn + +@deftypefn {Built-in Function} int __builtin_rx_mvfc (int) +Generates the @code{mvfc} machine instruction which reads the control +register specified in its argument and returns its value. +@end deftypefn + +@deftypefn {Built-in Function} void __builtin_rx_mvtachi (int) +Generates the @code{mvtachi} machine instruction to set the top +32-bits of the accumulator. +@end deftypefn + +@deftypefn {Built-in Function} void __builtin_rx_mvtaclo (int) +Generates the @code{mvtaclo} machine instruction to set the bottom +32-bits of the accumulator. +@end deftypefn + +@deftypefn {Built-in Function} void __builtin_rx_mvtc (int reg, int val) +Generates the @code{mvtc} machine instruction which sets control +register number @code{reg} to @code{val}. +@end deftypefn + +@deftypefn {Built-in Function} void __builtin_rx_mvtipl (int) +Generates the @code{mvtipl} machine instruction set the interrupt +priority level. +@end deftypefn + +@deftypefn {Built-in Function} void __builtin_rx_racw (int) +Generates the @code{racw} machine instruction to round the accumulator +according to the specified mode. +@end deftypefn + +@deftypefn {Built-in Function} int __builtin_rx_revw (int) +Generates the @code{revw} machine instruction which swaps the bytes in +the argument so that bits 0--7 now occupy bits 8--15 and vice versa, +and also bits 16--23 occupy bits 24--31 and vice versa. +@end deftypefn + +@deftypefn {Built-in Function} void __builtin_rx_rmpa (void) +Generates the @code{rmpa} machine instruction which initiates a +repeated multiply and accumulate sequence. +@end deftypefn + +@deftypefn {Built-in Function} void __builtin_rx_round (float) +Generates the @code{round} machine instruction which returns the +floating point argument rounded according to the current rounding mode +set in the floating point status word register. +@end deftypefn + +@deftypefn {Built-in Function} int __builtin_rx_sat (int) +Generates the @code{sat} machine instruction which returns the +saturated value of the argument. +@end deftypefn + +@deftypefn {Built-in Function} void __builtin_rx_setpsw (int) +Generates the @code{setpsw} machine instruction to set the specified +bit in the processor status word. +@end deftypefn + +@deftypefn {Built-in Function} void __builtin_rx_wait (void) +Generates the @code{wait} machine instruction. +@end deftypefn + +@node SPARC VIS Built-in Functions +@subsection SPARC VIS Built-in Functions + +GCC supports SIMD operations on the SPARC using both the generic vector +extensions (@pxref{Vector Extensions}) as well as built-in functions for +the SPARC Visual Instruction Set (VIS). When you use the @option{-mvis} +switch, the VIS extension is exposed as the following built-in functions: + +@smallexample +typedef int v2si __attribute__ ((vector_size (8))); +typedef short v4hi __attribute__ ((vector_size (8))); +typedef short v2hi __attribute__ ((vector_size (4))); +typedef char v8qi __attribute__ ((vector_size (8))); +typedef char v4qi __attribute__ ((vector_size (4))); + +void * __builtin_vis_alignaddr (void *, long); +int64_t __builtin_vis_faligndatadi (int64_t, int64_t); +v2si __builtin_vis_faligndatav2si (v2si, v2si); +v4hi __builtin_vis_faligndatav4hi (v4si, v4si); +v8qi __builtin_vis_faligndatav8qi (v8qi, v8qi); + +v4hi __builtin_vis_fexpand (v4qi); + +v4hi __builtin_vis_fmul8x16 (v4qi, v4hi); +v4hi __builtin_vis_fmul8x16au (v4qi, v4hi); +v4hi __builtin_vis_fmul8x16al (v4qi, v4hi); +v4hi __builtin_vis_fmul8sux16 (v8qi, v4hi); +v4hi __builtin_vis_fmul8ulx16 (v8qi, v4hi); +v2si __builtin_vis_fmuld8sux16 (v4qi, v2hi); +v2si __builtin_vis_fmuld8ulx16 (v4qi, v2hi); + +v4qi __builtin_vis_fpack16 (v4hi); +v8qi __builtin_vis_fpack32 (v2si, v2si); +v2hi __builtin_vis_fpackfix (v2si); +v8qi __builtin_vis_fpmerge (v4qi, v4qi); + +int64_t __builtin_vis_pdist (v8qi, v8qi, int64_t); +@end smallexample + +@node SPU Built-in Functions +@subsection SPU Built-in Functions + +GCC provides extensions for the SPU processor as described in the +Sony/Toshiba/IBM SPU Language Extensions Specification, which can be +found at @uref{http://cell.scei.co.jp/} or +@uref{http://www.ibm.com/developerworks/power/cell/}. GCC's +implementation differs in several ways. + +@itemize @bullet + +@item +The optional extension of specifying vector constants in parentheses is +not supported. + +@item +A vector initializer requires no cast if the vector constant is of the +same type as the variable it is initializing. + +@item +If @code{signed} or @code{unsigned} is omitted, the signedness of the +vector type is the default signedness of the base type. The default +varies depending on the operating system, so a portable program should +always specify the signedness. + +@item +By default, the keyword @code{__vector} is added. The macro +@code{vector} is defined in @code{} and can be +undefined. + +@item +GCC allows using a @code{typedef} name as the type specifier for a +vector type. + +@item +For C, overloaded functions are implemented with macros so the following +does not work: + +@smallexample + spu_add ((vector signed int)@{1, 2, 3, 4@}, foo); +@end smallexample + +Since @code{spu_add} is a macro, the vector constant in the example +is treated as four separate arguments. Wrap the entire argument in +parentheses for this to work. + +@item +The extended version of @code{__builtin_expect} is not supported. + +@end itemize + +@emph{Note:} Only the interface described in the aforementioned +specification is supported. Internally, GCC uses built-in functions to +implement the required functionality, but these are not supported and +are subject to change without notice. + +@node Target Format Checks +@section Format Checks Specific to Particular Target Machines + +For some target machines, GCC supports additional options to the +format attribute +(@pxref{Function Attributes,,Declaring Attributes of Functions}). + +@menu +* Solaris Format Checks:: +* Darwin Format Checks:: +@end menu + +@node Solaris Format Checks +@subsection Solaris Format Checks + +Solaris targets support the @code{cmn_err} (or @code{__cmn_err__}) format +check. @code{cmn_err} accepts a subset of the standard @code{printf} +conversions, and the two-argument @code{%b} conversion for displaying +bit-fields. See the Solaris man page for @code{cmn_err} for more information. + +@node Darwin Format Checks +@subsection Darwin Format Checks + +Darwin targets support the @code{CFString} (or @code{__CFString__}) in the format +attribute context. Declarations made with such attribution will be parsed for correct syntax +and format argument types. However, parsing of the format string itself is currently undefined +and will not be carried out by this version of the compiler. + +Additionally, @code{CFStringRefs} (defined by the @code{CoreFoundation} headers) may +also be used as format arguments. Note that the relevant headers are only likely to be +available on Darwin (OSX) installations. On such installations, the XCode and system +documentation provide descriptions of @code{CFString}, @code{CFStringRefs} and +associated functions. + +@node Pragmas +@section Pragmas Accepted by GCC +@cindex pragmas +@cindex @code{#pragma} + +GCC supports several types of pragmas, primarily in order to compile +code originally written for other compilers. Note that in general +we do not recommend the use of pragmas; @xref{Function Attributes}, +for further explanation. + +@menu +* ARM Pragmas:: +* M32C Pragmas:: +* MeP Pragmas:: +* RS/6000 and PowerPC Pragmas:: +* Darwin Pragmas:: +* Solaris Pragmas:: +* Symbol-Renaming Pragmas:: +* Structure-Packing Pragmas:: +* Weak Pragmas:: +* Diagnostic Pragmas:: +* Visibility Pragmas:: +* Push/Pop Macro Pragmas:: +* Function Specific Option Pragmas:: +@end menu + +@node ARM Pragmas +@subsection ARM Pragmas + +The ARM target defines pragmas for controlling the default addition of +@code{long_call} and @code{short_call} attributes to functions. +@xref{Function Attributes}, for information about the effects of these +attributes. + +@table @code +@item long_calls +@cindex pragma, long_calls +Set all subsequent functions to have the @code{long_call} attribute. + +@item no_long_calls +@cindex pragma, no_long_calls +Set all subsequent functions to have the @code{short_call} attribute. + +@item long_calls_off +@cindex pragma, long_calls_off +Do not affect the @code{long_call} or @code{short_call} attributes of +subsequent functions. +@end table + +@node M32C Pragmas +@subsection M32C Pragmas + +@table @code +@item GCC memregs @var{number} +@cindex pragma, memregs +Overrides the command-line option @code{-memregs=} for the current +file. Use with care! This pragma must be before any function in the +file, and mixing different memregs values in different objects may +make them incompatible. This pragma is useful when a +performance-critical function uses a memreg for temporary values, +as it may allow you to reduce the number of memregs used. + +@item ADDRESS @var{name} @var{address} +@cindex pragma, address +For any declared symbols matching @var{name}, this does three things +to that symbol: it forces the symbol to be located at the given +address (a number), it forces the symbol to be volatile, and it +changes the symbol's scope to be static. This pragma exists for +compatibility with other compilers, but note that the common +@code{1234H} numeric syntax is not supported (use @code{0x1234} +instead). Example: + +@example +#pragma ADDRESS port3 0x103 +char port3; +@end example + +@end table + +@node MeP Pragmas +@subsection MeP Pragmas + +@table @code + +@item custom io_volatile (on|off) +@cindex pragma, custom io_volatile +Overrides the command line option @code{-mio-volatile} for the current +file. Note that for compatibility with future GCC releases, this +option should only be used once before any @code{io} variables in each +file. + +@item GCC coprocessor available @var{registers} +@cindex pragma, coprocessor available +Specifies which coprocessor registers are available to the register +allocator. @var{registers} may be a single register, register range +separated by ellipses, or comma-separated list of those. Example: + +@example +#pragma GCC coprocessor available $c0...$c10, $c28 +@end example + +@item GCC coprocessor call_saved @var{registers} +@cindex pragma, coprocessor call_saved +Specifies which coprocessor registers are to be saved and restored by +any function using them. @var{registers} may be a single register, +register range separated by ellipses, or comma-separated list of +those. Example: + +@example +#pragma GCC coprocessor call_saved $c4...$c6, $c31 +@end example + +@item GCC coprocessor subclass '(A|B|C|D)' = @var{registers} +@cindex pragma, coprocessor subclass +Creates and defines a register class. These register classes can be +used by inline @code{asm} constructs. @var{registers} may be a single +register, register range separated by ellipses, or comma-separated +list of those. Example: + +@example +#pragma GCC coprocessor subclass 'B' = $c2, $c4, $c6 + +asm ("cpfoo %0" : "=B" (x)); +@end example + +@item GCC disinterrupt @var{name} , @var{name} @dots{} +@cindex pragma, disinterrupt +For the named functions, the compiler adds code to disable interrupts +for the duration of those functions. Any functions so named, which +are not encountered in the source, cause a warning that the pragma was +not used. Examples: + +@example +#pragma disinterrupt foo +#pragma disinterrupt bar, grill +int foo () @{ @dots{} @} +@end example + +@item GCC call @var{name} , @var{name} @dots{} +@cindex pragma, call +For the named functions, the compiler always uses a register-indirect +call model when calling the named functions. Examples: + +@example +extern int foo (); +#pragma call foo +@end example + +@end table + +@node RS/6000 and PowerPC Pragmas +@subsection RS/6000 and PowerPC Pragmas + +The RS/6000 and PowerPC targets define one pragma for controlling +whether or not the @code{longcall} attribute is added to function +declarations by default. This pragma overrides the @option{-mlongcall} +option, but not the @code{longcall} and @code{shortcall} attributes. +@xref{RS/6000 and PowerPC Options}, for more information about when long +calls are and are not necessary. + +@table @code +@item longcall (1) +@cindex pragma, longcall +Apply the @code{longcall} attribute to all subsequent function +declarations. + +@item longcall (0) +Do not apply the @code{longcall} attribute to subsequent function +declarations. +@end table + +@c Describe h8300 pragmas here. +@c Describe sh pragmas here. +@c Describe v850 pragmas here. + +@node Darwin Pragmas +@subsection Darwin Pragmas + +The following pragmas are available for all architectures running the +Darwin operating system. These are useful for compatibility with other +Mac OS compilers. + +@table @code +@item mark @var{tokens}@dots{} +@cindex pragma, mark +This pragma is accepted, but has no effect. + +@item options align=@var{alignment} +@cindex pragma, options align +This pragma sets the alignment of fields in structures. The values of +@var{alignment} may be @code{mac68k}, to emulate m68k alignment, or +@code{power}, to emulate PowerPC alignment. Uses of this pragma nest +properly; to restore the previous setting, use @code{reset} for the +@var{alignment}. + +@item segment @var{tokens}@dots{} +@cindex pragma, segment +This pragma is accepted, but has no effect. + +@item unused (@var{var} [, @var{var}]@dots{}) +@cindex pragma, unused +This pragma declares variables to be possibly unused. GCC will not +produce warnings for the listed variables. The effect is similar to +that of the @code{unused} attribute, except that this pragma may appear +anywhere within the variables' scopes. +@end table + +@node Solaris Pragmas +@subsection Solaris Pragmas + +The Solaris target supports @code{#pragma redefine_extname} +(@pxref{Symbol-Renaming Pragmas}). It also supports additional +@code{#pragma} directives for compatibility with the system compiler. + +@table @code +@item align @var{alignment} (@var{variable} [, @var{variable}]...) +@cindex pragma, align + +Increase the minimum alignment of each @var{variable} to @var{alignment}. +This is the same as GCC's @code{aligned} attribute @pxref{Variable +Attributes}). Macro expansion occurs on the arguments to this pragma +when compiling C and Objective-C@. It does not currently occur when +compiling C++, but this is a bug which may be fixed in a future +release. + +@item fini (@var{function} [, @var{function}]...) +@cindex pragma, fini + +This pragma causes each listed @var{function} to be called after +main, or during shared module unloading, by adding a call to the +@code{.fini} section. + +@item init (@var{function} [, @var{function}]...) +@cindex pragma, init + +This pragma causes each listed @var{function} to be called during +initialization (before @code{main}) or during shared module loading, by +adding a call to the @code{.init} section. + +@end table + +@node Symbol-Renaming Pragmas +@subsection Symbol-Renaming Pragmas + +For compatibility with the Solaris and Tru64 UNIX system headers, GCC +supports two @code{#pragma} directives which change the name used in +assembly for a given declaration. @code{#pragma extern_prefix} is only +available on platforms whose system headers need it. To get this effect +on all platforms supported by GCC, use the asm labels extension (@pxref{Asm +Labels}). + +@table @code +@item redefine_extname @var{oldname} @var{newname} +@cindex pragma, redefine_extname + +This pragma gives the C function @var{oldname} the assembly symbol +@var{newname}. The preprocessor macro @code{__PRAGMA_REDEFINE_EXTNAME} +will be defined if this pragma is available (currently on all platforms). + +@item extern_prefix @var{string} +@cindex pragma, extern_prefix + +This pragma causes all subsequent external function and variable +declarations to have @var{string} prepended to their assembly symbols. +This effect may be terminated with another @code{extern_prefix} pragma +whose argument is an empty string. The preprocessor macro +@code{__PRAGMA_EXTERN_PREFIX} will be defined if this pragma is +available (currently only on Tru64 UNIX)@. +@end table + +These pragmas and the asm labels extension interact in a complicated +manner. Here are some corner cases you may want to be aware of. + +@enumerate +@item Both pragmas silently apply only to declarations with external +linkage. Asm labels do not have this restriction. + +@item In C++, both pragmas silently apply only to declarations with +``C'' linkage. Again, asm labels do not have this restriction. + +@item If any of the three ways of changing the assembly name of a +declaration is applied to a declaration whose assembly name has +already been determined (either by a previous use of one of these +features, or because the compiler needed the assembly name in order to +generate code), and the new name is different, a warning issues and +the name does not change. + +@item The @var{oldname} used by @code{#pragma redefine_extname} is +always the C-language name. + +@item If @code{#pragma extern_prefix} is in effect, and a declaration +occurs with an asm label attached, the prefix is silently ignored for +that declaration. + +@item If @code{#pragma extern_prefix} and @code{#pragma redefine_extname} +apply to the same declaration, whichever triggered first wins, and a +warning issues if they contradict each other. (We would like to have +@code{#pragma redefine_extname} always win, for consistency with asm +labels, but if @code{#pragma extern_prefix} triggers first we have no +way of knowing that that happened.) +@end enumerate + +@node Structure-Packing Pragmas +@subsection Structure-Packing Pragmas + +For compatibility with Microsoft Windows compilers, GCC supports a +set of @code{#pragma} directives which change the maximum alignment of +members of structures (other than zero-width bitfields), unions, and +classes subsequently defined. The @var{n} value below always is required +to be a small power of two and specifies the new alignment in bytes. + +@enumerate +@item @code{#pragma pack(@var{n})} simply sets the new alignment. +@item @code{#pragma pack()} sets the alignment to the one that was in +effect when compilation started (see also command-line option +@option{-fpack-struct[=@var{n}]} @pxref{Code Gen Options}). +@item @code{#pragma pack(push[,@var{n}])} pushes the current alignment +setting on an internal stack and then optionally sets the new alignment. +@item @code{#pragma pack(pop)} restores the alignment setting to the one +saved at the top of the internal stack (and removes that stack entry). +Note that @code{#pragma pack([@var{n}])} does not influence this internal +stack; thus it is possible to have @code{#pragma pack(push)} followed by +multiple @code{#pragma pack(@var{n})} instances and finalized by a single +@code{#pragma pack(pop)}. +@end enumerate + +Some targets, e.g.@: i386 and powerpc, support the @code{ms_struct} +@code{#pragma} which lays out a structure as the documented +@code{__attribute__ ((ms_struct))}. +@enumerate +@item @code{#pragma ms_struct on} turns on the layout for structures +declared. +@item @code{#pragma ms_struct off} turns off the layout for structures +declared. +@item @code{#pragma ms_struct reset} goes back to the default layout. +@end enumerate + +@node Weak Pragmas +@subsection Weak Pragmas + +For compatibility with SVR4, GCC supports a set of @code{#pragma} +directives for declaring symbols to be weak, and defining weak +aliases. + +@table @code +@item #pragma weak @var{symbol} +@cindex pragma, weak +This pragma declares @var{symbol} to be weak, as if the declaration +had the attribute of the same name. The pragma may appear before +or after the declaration of @var{symbol}. It is not an error for +@var{symbol} to never be defined at all. + +@item #pragma weak @var{symbol1} = @var{symbol2} +This pragma declares @var{symbol1} to be a weak alias of @var{symbol2}. +It is an error if @var{symbol2} is not defined in the current +translation unit. +@end table + +@node Diagnostic Pragmas +@subsection Diagnostic Pragmas + +GCC allows the user to selectively enable or disable certain types of +diagnostics, and change the kind of the diagnostic. For example, a +project's policy might require that all sources compile with +@option{-Werror} but certain files might have exceptions allowing +specific types of warnings. Or, a project might selectively enable +diagnostics and treat them as errors depending on which preprocessor +macros are defined. + +@table @code +@item #pragma GCC diagnostic @var{kind} @var{option} +@cindex pragma, diagnostic + +Modifies the disposition of a diagnostic. Note that not all +diagnostics are modifiable; at the moment only warnings (normally +controlled by @samp{-W@dots{}}) can be controlled, and not all of them. +Use @option{-fdiagnostics-show-option} to determine which diagnostics +are controllable and which option controls them. + +@var{kind} is @samp{error} to treat this diagnostic as an error, +@samp{warning} to treat it like a warning (even if @option{-Werror} is +in effect), or @samp{ignored} if the diagnostic is to be ignored. +@var{option} is a double quoted string which matches the command-line +option. + +@example +#pragma GCC diagnostic warning "-Wformat" +#pragma GCC diagnostic error "-Wformat" +#pragma GCC diagnostic ignored "-Wformat" +@end example + +Note that these pragmas override any command-line options. GCC keeps +track of the location of each pragma, and issues diagnostics according +to the state as of that point in the source file. Thus, pragmas occurring +after a line do not affect diagnostics caused by that line. + +@item #pragma GCC diagnostic push +@itemx #pragma GCC diagnostic pop + +Causes GCC to remember the state of the diagnostics as of each +@code{push}, and restore to that point at each @code{pop}. If a +@code{pop} has no matching @code{push}, the command line options are +restored. + +@example +#pragma GCC diagnostic error "-Wuninitialized" + foo(a); /* error is given for this one */ +#pragma GCC diagnostic push +#pragma GCC diagnostic ignored "-Wuninitialized" + foo(b); /* no diagnostic for this one */ +#pragma GCC diagnostic pop + foo(c); /* error is given for this one */ +#pragma GCC diagnostic pop + foo(d); /* depends on command line options */ +@end example + +@end table + +GCC also offers a simple mechanism for printing messages during +compilation. + +@table @code +@item #pragma message @var{string} +@cindex pragma, diagnostic + +Prints @var{string} as a compiler message on compilation. The message +is informational only, and is neither a compilation warning nor an error. + +@smallexample +#pragma message "Compiling " __FILE__ "..." +@end smallexample + +@var{string} may be parenthesized, and is printed with location +information. For example, + +@smallexample +#define DO_PRAGMA(x) _Pragma (#x) +#define TODO(x) DO_PRAGMA(message ("TODO - " #x)) + +TODO(Remember to fix this) +@end smallexample + +prints @samp{/tmp/file.c:4: note: #pragma message: +TODO - Remember to fix this}. + +@end table + +@node Visibility Pragmas +@subsection Visibility Pragmas + +@table @code +@item #pragma GCC visibility push(@var{visibility}) +@itemx #pragma GCC visibility pop +@cindex pragma, visibility + +This pragma allows the user to set the visibility for multiple +declarations without having to give each a visibility attribute +@xref{Function Attributes}, for more information about visibility and +the attribute syntax. + +In C++, @samp{#pragma GCC visibility} affects only namespace-scope +declarations. Class members and template specializations are not +affected; if you want to override the visibility for a particular +member or instantiation, you must use an attribute. + +@end table + + +@node Push/Pop Macro Pragmas +@subsection Push/Pop Macro Pragmas + +For compatibility with Microsoft Windows compilers, GCC supports +@samp{#pragma push_macro(@var{"macro_name"})} +and @samp{#pragma pop_macro(@var{"macro_name"})}. + +@table @code +@item #pragma push_macro(@var{"macro_name"}) +@cindex pragma, push_macro +This pragma saves the value of the macro named as @var{macro_name} to +the top of the stack for this macro. + +@item #pragma pop_macro(@var{"macro_name"}) +@cindex pragma, pop_macro +This pragma sets the value of the macro named as @var{macro_name} to +the value on top of the stack for this macro. If the stack for +@var{macro_name} is empty, the value of the macro remains unchanged. +@end table + +For example: + +@smallexample +#define X 1 +#pragma push_macro("X") +#undef X +#define X -1 +#pragma pop_macro("X") +int x [X]; +@end smallexample + +In this example, the definition of X as 1 is saved by @code{#pragma +push_macro} and restored by @code{#pragma pop_macro}. + +@node Function Specific Option Pragmas +@subsection Function Specific Option Pragmas + +@table @code +@item #pragma GCC target (@var{"string"}...) +@cindex pragma GCC target + +This pragma allows you to set target specific options for functions +defined later in the source file. One or more strings can be +specified. Each function that is defined after this point will be as +if @code{attribute((target("STRING")))} was specified for that +function. The parenthesis around the options is optional. +@xref{Function Attributes}, for more information about the +@code{target} attribute and the attribute syntax. + +The @code{#pragma GCC target} attribute is not implemented in GCC versions earlier +than 4.4 for the i386/x86_64 and 4.6 for the PowerPC backends. At +present, it is not implemented for other backends. +@end table + +@table @code +@item #pragma GCC optimize (@var{"string"}...) +@cindex pragma GCC optimize + +This pragma allows you to set global optimization options for functions +defined later in the source file. One or more strings can be +specified. Each function that is defined after this point will be as +if @code{attribute((optimize("STRING")))} was specified for that +function. The parenthesis around the options is optional. +@xref{Function Attributes}, for more information about the +@code{optimize} attribute and the attribute syntax. + +The @samp{#pragma GCC optimize} pragma is not implemented in GCC +versions earlier than 4.4. +@end table + +@table @code +@item #pragma GCC push_options +@itemx #pragma GCC pop_options +@cindex pragma GCC push_options +@cindex pragma GCC pop_options + +These pragmas maintain a stack of the current target and optimization +options. It is intended for include files where you temporarily want +to switch to using a different @samp{#pragma GCC target} or +@samp{#pragma GCC optimize} and then to pop back to the previous +options. + +The @samp{#pragma GCC push_options} and @samp{#pragma GCC pop_options} +pragmas are not implemented in GCC versions earlier than 4.4. +@end table + +@table @code +@item #pragma GCC reset_options +@cindex pragma GCC reset_options + +This pragma clears the current @code{#pragma GCC target} and +@code{#pragma GCC optimize} to use the default switches as specified +on the command line. + +The @samp{#pragma GCC reset_options} pragma is not implemented in GCC +versions earlier than 4.4. +@end table + +@node Unnamed Fields +@section Unnamed struct/union fields within structs/unions +@cindex @code{struct} +@cindex @code{union} + +As permitted by ISO C1X and for compatibility with other compilers, +GCC allows you to define +a structure or union that contains, as fields, structures and unions +without names. For example: + +@smallexample +struct @{ + int a; + union @{ + int b; + float c; + @}; + int d; +@} foo; +@end smallexample + +In this example, the user would be able to access members of the unnamed +union with code like @samp{foo.b}. Note that only unnamed structs and +unions are allowed, you may not have, for example, an unnamed +@code{int}. + +You must never create such structures that cause ambiguous field definitions. +For example, this structure: + +@smallexample +struct @{ + int a; + struct @{ + int a; + @}; +@} foo; +@end smallexample + +It is ambiguous which @code{a} is being referred to with @samp{foo.a}. +The compiler gives errors for such constructs. + +@opindex fms-extensions +Unless @option{-fms-extensions} is used, the unnamed field must be a +structure or union definition without a tag (for example, @samp{struct +@{ int a; @};}). If @option{-fms-extensions} is used, the field may +also be a definition with a tag such as @samp{struct foo @{ int a; +@};}, a reference to a previously defined structure or union such as +@samp{struct foo;}, or a reference to a @code{typedef} name for a +previously defined structure or union type. + +@opindex fplan9-extensions +The option @option{-fplan9-extensions} enables +@option{-fms-extensions} as well as two other extensions. First, a +pointer to a structure is automatically converted to a pointer to an +anonymous field for assignments and function calls. For example: + +@smallexample +struct s1 @{ int a; @}; +struct s2 @{ struct s1; @}; +extern void f1 (struct s1 *); +void f2 (struct s2 *p) @{ f1 (p); @} +@end smallexample + +In the call to @code{f1} inside @code{f2}, the pointer @code{p} is +converted into a pointer to the anonymous field. + +Second, when the type of an anonymous field is a @code{typedef} for a +@code{struct} or @code{union}, code may refer to the field using the +name of the @code{typedef}. + +@smallexample +typedef struct @{ int a; @} s1; +struct s2 @{ s1; @}; +s1 f1 (struct s2 *p) @{ return p->s1; @} +@end smallexample + +These usages are only permitted when they are not ambiguous. + +@node Thread-Local +@section Thread-Local Storage +@cindex Thread-Local Storage +@cindex @acronym{TLS} +@cindex @code{__thread} + +Thread-local storage (@acronym{TLS}) is a mechanism by which variables +are allocated such that there is one instance of the variable per extant +thread. The run-time model GCC uses to implement this originates +in the IA-64 processor-specific ABI, but has since been migrated +to other processors as well. It requires significant support from +the linker (@command{ld}), dynamic linker (@command{ld.so}), and +system libraries (@file{libc.so} and @file{libpthread.so}), so it +is not available everywhere. + +At the user level, the extension is visible with a new storage +class keyword: @code{__thread}. For example: + +@smallexample +__thread int i; +extern __thread struct state s; +static __thread char *p; +@end smallexample + +The @code{__thread} specifier may be used alone, with the @code{extern} +or @code{static} specifiers, but with no other storage class specifier. +When used with @code{extern} or @code{static}, @code{__thread} must appear +immediately after the other storage class specifier. + +The @code{__thread} specifier may be applied to any global, file-scoped +static, function-scoped static, or static data member of a class. It may +not be applied to block-scoped automatic or non-static data member. + +When the address-of operator is applied to a thread-local variable, it is +evaluated at run-time and returns the address of the current thread's +instance of that variable. An address so obtained may be used by any +thread. When a thread terminates, any pointers to thread-local variables +in that thread become invalid. + +No static initialization may refer to the address of a thread-local variable. + +In C++, if an initializer is present for a thread-local variable, it must +be a @var{constant-expression}, as defined in 5.19.2 of the ANSI/ISO C++ +standard. + +See @uref{http://www.akkadia.org/drepper/tls.pdf, +ELF Handling For Thread-Local Storage} for a detailed explanation of +the four thread-local storage addressing models, and how the run-time +is expected to function. + +@menu +* C99 Thread-Local Edits:: +* C++98 Thread-Local Edits:: +@end menu + +@node C99 Thread-Local Edits +@subsection ISO/IEC 9899:1999 Edits for Thread-Local Storage + +The following are a set of changes to ISO/IEC 9899:1999 (aka C99) +that document the exact semantics of the language extension. + +@itemize @bullet +@item +@cite{5.1.2 Execution environments} + +Add new text after paragraph 1 + +@quotation +Within either execution environment, a @dfn{thread} is a flow of +control within a program. It is implementation defined whether +or not there may be more than one thread associated with a program. +It is implementation defined how threads beyond the first are +created, the name and type of the function called at thread +startup, and how threads may be terminated. However, objects +with thread storage duration shall be initialized before thread +startup. +@end quotation + +@item +@cite{6.2.4 Storage durations of objects} + +Add new text before paragraph 3 + +@quotation +An object whose identifier is declared with the storage-class +specifier @w{@code{__thread}} has @dfn{thread storage duration}. +Its lifetime is the entire execution of the thread, and its +stored value is initialized only once, prior to thread startup. +@end quotation + +@item +@cite{6.4.1 Keywords} + +Add @code{__thread}. + +@item +@cite{6.7.1 Storage-class specifiers} + +Add @code{__thread} to the list of storage class specifiers in +paragraph 1. + +Change paragraph 2 to + +@quotation +With the exception of @code{__thread}, at most one storage-class +specifier may be given [@dots{}]. The @code{__thread} specifier may +be used alone, or immediately following @code{extern} or +@code{static}. +@end quotation + +Add new text after paragraph 6 + +@quotation +The declaration of an identifier for a variable that has +block scope that specifies @code{__thread} shall also +specify either @code{extern} or @code{static}. + +The @code{__thread} specifier shall be used only with +variables. +@end quotation +@end itemize + +@node C++98 Thread-Local Edits +@subsection ISO/IEC 14882:1998 Edits for Thread-Local Storage + +The following are a set of changes to ISO/IEC 14882:1998 (aka C++98) +that document the exact semantics of the language extension. + +@itemize @bullet +@item +@b{[intro.execution]} + +New text after paragraph 4 + +@quotation +A @dfn{thread} is a flow of control within the abstract machine. +It is implementation defined whether or not there may be more than +one thread. +@end quotation + +New text after paragraph 7 + +@quotation +It is unspecified whether additional action must be taken to +ensure when and whether side effects are visible to other threads. +@end quotation + +@item +@b{[lex.key]} + +Add @code{__thread}. + +@item +@b{[basic.start.main]} + +Add after paragraph 5 + +@quotation +The thread that begins execution at the @code{main} function is called +the @dfn{main thread}. It is implementation defined how functions +beginning threads other than the main thread are designated or typed. +A function so designated, as well as the @code{main} function, is called +a @dfn{thread startup function}. It is implementation defined what +happens if a thread startup function returns. It is implementation +defined what happens to other threads when any thread calls @code{exit}. +@end quotation + +@item +@b{[basic.start.init]} + +Add after paragraph 4 + +@quotation +The storage for an object of thread storage duration shall be +statically initialized before the first statement of the thread startup +function. An object of thread storage duration shall not require +dynamic initialization. +@end quotation + +@item +@b{[basic.start.term]} + +Add after paragraph 3 + +@quotation +The type of an object with thread storage duration shall not have a +non-trivial destructor, nor shall it be an array type whose elements +(directly or indirectly) have non-trivial destructors. +@end quotation + +@item +@b{[basic.stc]} + +Add ``thread storage duration'' to the list in paragraph 1. + +Change paragraph 2 + +@quotation +Thread, static, and automatic storage durations are associated with +objects introduced by declarations [@dots{}]. +@end quotation + +Add @code{__thread} to the list of specifiers in paragraph 3. + +@item +@b{[basic.stc.thread]} + +New section before @b{[basic.stc.static]} + +@quotation +The keyword @code{__thread} applied to a non-local object gives the +object thread storage duration. + +A local variable or class data member declared both @code{static} +and @code{__thread} gives the variable or member thread storage +duration. +@end quotation + +@item +@b{[basic.stc.static]} + +Change paragraph 1 + +@quotation +All objects which have neither thread storage duration, dynamic +storage duration nor are local [@dots{}]. +@end quotation + +@item +@b{[dcl.stc]} + +Add @code{__thread} to the list in paragraph 1. + +Change paragraph 1 + +@quotation +With the exception of @code{__thread}, at most one +@var{storage-class-specifier} shall appear in a given +@var{decl-specifier-seq}. The @code{__thread} specifier may +be used alone, or immediately following the @code{extern} or +@code{static} specifiers. [@dots{}] +@end quotation + +Add after paragraph 5 + +@quotation +The @code{__thread} specifier can be applied only to the names of objects +and to anonymous unions. +@end quotation + +@item +@b{[class.mem]} + +Add after paragraph 6 + +@quotation +Non-@code{static} members shall not be @code{__thread}. +@end quotation +@end itemize + +@node Binary constants +@section Binary constants using the @samp{0b} prefix +@cindex Binary constants using the @samp{0b} prefix + +Integer constants can be written as binary constants, consisting of a +sequence of @samp{0} and @samp{1} digits, prefixed by @samp{0b} or +@samp{0B}. This is particularly useful in environments that operate a +lot on the bit-level (like microcontrollers). + +The following statements are identical: + +@smallexample +i = 42; +i = 0x2a; +i = 052; +i = 0b101010; +@end smallexample + +The type of these constants follows the same rules as for octal or +hexadecimal integer constants, so suffixes like @samp{L} or @samp{UL} +can be applied. + +@node C++ Extensions +@chapter Extensions to the C++ Language +@cindex extensions, C++ language +@cindex C++ language extensions + +The GNU compiler provides these extensions to the C++ language (and you +can also use most of the C language extensions in your C++ programs). If you +want to write code that checks whether these features are available, you can +test for the GNU compiler the same way as for C programs: check for a +predefined macro @code{__GNUC__}. You can also use @code{__GNUG__} to +test specifically for GNU C++ (@pxref{Common Predefined Macros,, +Predefined Macros,cpp,The GNU C Preprocessor}). + +@menu +* C++ Volatiles:: What constitutes an access to a volatile object. +* Restricted Pointers:: C99 restricted pointers and references. +* Vague Linkage:: Where G++ puts inlines, vtables and such. +* C++ Interface:: You can use a single C++ header file for both + declarations and definitions. +* Template Instantiation:: Methods for ensuring that exactly one copy of + each needed template instantiation is emitted. +* Bound member functions:: You can extract a function pointer to the + method denoted by a @samp{->*} or @samp{.*} expression. +* C++ Attributes:: Variable, function, and type attributes for C++ only. +* Namespace Association:: Strong using-directives for namespace association. +* Type Traits:: Compiler support for type traits +* Java Exceptions:: Tweaking exception handling to work with Java. +* Deprecated Features:: Things will disappear from g++. +* Backwards Compatibility:: Compatibilities with earlier definitions of C++. +@end menu + +@node C++ Volatiles +@section When is a Volatile C++ Object Accessed? +@cindex accessing volatiles +@cindex volatile read +@cindex volatile write +@cindex volatile access + +The C++ standard differs from the C standard in its treatment of +volatile objects. It fails to specify what constitutes a volatile +access, except to say that C++ should behave in a similar manner to C +with respect to volatiles, where possible. However, the different +lvalueness of expressions between C and C++ complicate the behavior. +G++ behaves the same as GCC for volatile access, @xref{C +Extensions,,Volatiles}, for a description of GCC's behavior. + +The C and C++ language specifications differ when an object is +accessed in a void context: + +@smallexample +volatile int *src = @var{somevalue}; +*src; +@end smallexample + +The C++ standard specifies that such expressions do not undergo lvalue +to rvalue conversion, and that the type of the dereferenced object may +be incomplete. The C++ standard does not specify explicitly that it +is lvalue to rvalue conversion which is responsible for causing an +access. There is reason to believe that it is, because otherwise +certain simple expressions become undefined. However, because it +would surprise most programmers, G++ treats dereferencing a pointer to +volatile object of complete type as GCC would do for an equivalent +type in C@. When the object has incomplete type, G++ issues a +warning; if you wish to force an error, you must force a conversion to +rvalue with, for instance, a static cast. + +When using a reference to volatile, G++ does not treat equivalent +expressions as accesses to volatiles, but instead issues a warning that +no volatile is accessed. The rationale for this is that otherwise it +becomes difficult to determine where volatile access occur, and not +possible to ignore the return value from functions returning volatile +references. Again, if you wish to force a read, cast the reference to +an rvalue. + +G++ implements the same behavior as GCC does when assigning to a +volatile object -- there is no reread of the assigned-to object, the +assigned rvalue is reused. Note that in C++ assignment expressions +are lvalues, and if used as an lvalue, the volatile object will be +referred to. For instance, @var{vref} will refer to @var{vobj}, as +expected, in the following example: + +@smallexample +volatile int vobj; +volatile int &vref = vobj = @var{something}; +@end smallexample + +@node Restricted Pointers +@section Restricting Pointer Aliasing +@cindex restricted pointers +@cindex restricted references +@cindex restricted this pointer + +As with the C front end, G++ understands the C99 feature of restricted pointers, +specified with the @code{__restrict__}, or @code{__restrict} type +qualifier. Because you cannot compile C++ by specifying the @option{-std=c99} +language flag, @code{restrict} is not a keyword in C++. + +In addition to allowing restricted pointers, you can specify restricted +references, which indicate that the reference is not aliased in the local +context. + +@smallexample +void fn (int *__restrict__ rptr, int &__restrict__ rref) +@{ + /* @r{@dots{}} */ +@} +@end smallexample + +@noindent +In the body of @code{fn}, @var{rptr} points to an unaliased integer and +@var{rref} refers to a (different) unaliased integer. + +You may also specify whether a member function's @var{this} pointer is +unaliased by using @code{__restrict__} as a member function qualifier. + +@smallexample +void T::fn () __restrict__ +@{ + /* @r{@dots{}} */ +@} +@end smallexample + +@noindent +Within the body of @code{T::fn}, @var{this} will have the effective +definition @code{T *__restrict__ const this}. Notice that the +interpretation of a @code{__restrict__} member function qualifier is +different to that of @code{const} or @code{volatile} qualifier, in that it +is applied to the pointer rather than the object. This is consistent with +other compilers which implement restricted pointers. + +As with all outermost parameter qualifiers, @code{__restrict__} is +ignored in function definition matching. This means you only need to +specify @code{__restrict__} in a function definition, rather than +in a function prototype as well. + +@node Vague Linkage +@section Vague Linkage +@cindex vague linkage + +There are several constructs in C++ which require space in the object +file but are not clearly tied to a single translation unit. We say that +these constructs have ``vague linkage''. Typically such constructs are +emitted wherever they are needed, though sometimes we can be more +clever. + +@table @asis +@item Inline Functions +Inline functions are typically defined in a header file which can be +included in many different compilations. Hopefully they can usually be +inlined, but sometimes an out-of-line copy is necessary, if the address +of the function is taken or if inlining fails. In general, we emit an +out-of-line copy in all translation units where one is needed. As an +exception, we only emit inline virtual functions with the vtable, since +it will always require a copy. + +Local static variables and string constants used in an inline function +are also considered to have vague linkage, since they must be shared +between all inlined and out-of-line instances of the function. + +@item VTables +@cindex vtable +C++ virtual functions are implemented in most compilers using a lookup +table, known as a vtable. The vtable contains pointers to the virtual +functions provided by a class, and each object of the class contains a +pointer to its vtable (or vtables, in some multiple-inheritance +situations). If the class declares any non-inline, non-pure virtual +functions, the first one is chosen as the ``key method'' for the class, +and the vtable is only emitted in the translation unit where the key +method is defined. + +@emph{Note:} If the chosen key method is later defined as inline, the +vtable will still be emitted in every translation unit which defines it. +Make sure that any inline virtuals are declared inline in the class +body, even if they are not defined there. + +@item @code{type_info} objects +@cindex @code{type_info} +@cindex RTTI +C++ requires information about types to be written out in order to +implement @samp{dynamic_cast}, @samp{typeid} and exception handling. +For polymorphic classes (classes with virtual functions), the @samp{type_info} +object is written out along with the vtable so that @samp{dynamic_cast} +can determine the dynamic type of a class object at runtime. For all +other types, we write out the @samp{type_info} object when it is used: when +applying @samp{typeid} to an expression, throwing an object, or +referring to a type in a catch clause or exception specification. + +@item Template Instantiations +Most everything in this section also applies to template instantiations, +but there are other options as well. +@xref{Template Instantiation,,Where's the Template?}. + +@end table + +When used with GNU ld version 2.8 or later on an ELF system such as +GNU/Linux or Solaris 2, or on Microsoft Windows, duplicate copies of +these constructs will be discarded at link time. This is known as +COMDAT support. + +On targets that don't support COMDAT, but do support weak symbols, GCC +will use them. This way one copy will override all the others, but +the unused copies will still take up space in the executable. + +For targets which do not support either COMDAT or weak symbols, +most entities with vague linkage will be emitted as local symbols to +avoid duplicate definition errors from the linker. This will not happen +for local statics in inlines, however, as having multiple copies will +almost certainly break things. + +@xref{C++ Interface,,Declarations and Definitions in One Header}, for +another way to control placement of these constructs. + +@node C++ Interface +@section #pragma interface and implementation + +@cindex interface and implementation headers, C++ +@cindex C++ interface and implementation headers +@cindex pragmas, interface and implementation + +@code{#pragma interface} and @code{#pragma implementation} provide the +user with a way of explicitly directing the compiler to emit entities +with vague linkage (and debugging information) in a particular +translation unit. + +@emph{Note:} As of GCC 2.7.2, these @code{#pragma}s are not useful in +most cases, because of COMDAT support and the ``key method'' heuristic +mentioned in @ref{Vague Linkage}. Using them can actually cause your +program to grow due to unnecessary out-of-line copies of inline +functions. Currently (3.4) the only benefit of these +@code{#pragma}s is reduced duplication of debugging information, and +that should be addressed soon on DWARF 2 targets with the use of +COMDAT groups. + +@table @code +@item #pragma interface +@itemx #pragma interface "@var{subdir}/@var{objects}.h" +@kindex #pragma interface +Use this directive in @emph{header files} that define object classes, to save +space in most of the object files that use those classes. Normally, +local copies of certain information (backup copies of inline member +functions, debugging information, and the internal tables that implement +virtual functions) must be kept in each object file that includes class +definitions. You can use this pragma to avoid such duplication. When a +header file containing @samp{#pragma interface} is included in a +compilation, this auxiliary information will not be generated (unless +the main input source file itself uses @samp{#pragma implementation}). +Instead, the object files will contain references to be resolved at link +time. + +The second form of this directive is useful for the case where you have +multiple headers with the same name in different directories. If you +use this form, you must specify the same string to @samp{#pragma +implementation}. + +@item #pragma implementation +@itemx #pragma implementation "@var{objects}.h" +@kindex #pragma implementation +Use this pragma in a @emph{main input file}, when you want full output from +included header files to be generated (and made globally visible). The +included header file, in turn, should use @samp{#pragma interface}. +Backup copies of inline member functions, debugging information, and the +internal tables used to implement virtual functions are all generated in +implementation files. + +@cindex implied @code{#pragma implementation} +@cindex @code{#pragma implementation}, implied +@cindex naming convention, implementation headers +If you use @samp{#pragma implementation} with no argument, it applies to +an include file with the same basename@footnote{A file's @dfn{basename} +was the name stripped of all leading path information and of trailing +suffixes, such as @samp{.h} or @samp{.C} or @samp{.cc}.} as your source +file. For example, in @file{allclass.cc}, giving just +@samp{#pragma implementation} +by itself is equivalent to @samp{#pragma implementation "allclass.h"}. + +In versions of GNU C++ prior to 2.6.0 @file{allclass.h} was treated as +an implementation file whenever you would include it from +@file{allclass.cc} even if you never specified @samp{#pragma +implementation}. This was deemed to be more trouble than it was worth, +however, and disabled. + +Use the string argument if you want a single implementation file to +include code from multiple header files. (You must also use +@samp{#include} to include the header file; @samp{#pragma +implementation} only specifies how to use the file---it doesn't actually +include it.) + +There is no way to split up the contents of a single header file into +multiple implementation files. +@end table + +@cindex inlining and C++ pragmas +@cindex C++ pragmas, effect on inlining +@cindex pragmas in C++, effect on inlining +@samp{#pragma implementation} and @samp{#pragma interface} also have an +effect on function inlining. + +If you define a class in a header file marked with @samp{#pragma +interface}, the effect on an inline function defined in that class is +similar to an explicit @code{extern} declaration---the compiler emits +no code at all to define an independent version of the function. Its +definition is used only for inlining with its callers. + +@opindex fno-implement-inlines +Conversely, when you include the same header file in a main source file +that declares it as @samp{#pragma implementation}, the compiler emits +code for the function itself; this defines a version of the function +that can be found via pointers (or by callers compiled without +inlining). If all calls to the function can be inlined, you can avoid +emitting the function by compiling with @option{-fno-implement-inlines}. +If any calls were not inlined, you will get linker errors. + +@node Template Instantiation +@section Where's the Template? +@cindex template instantiation + +C++ templates are the first language feature to require more +intelligence from the environment than one usually finds on a UNIX +system. Somehow the compiler and linker have to make sure that each +template instance occurs exactly once in the executable if it is needed, +and not at all otherwise. There are two basic approaches to this +problem, which are referred to as the Borland model and the Cfront model. + +@table @asis +@item Borland model +Borland C++ solved the template instantiation problem by adding the code +equivalent of common blocks to their linker; the compiler emits template +instances in each translation unit that uses them, and the linker +collapses them together. The advantage of this model is that the linker +only has to consider the object files themselves; there is no external +complexity to worry about. This disadvantage is that compilation time +is increased because the template code is being compiled repeatedly. +Code written for this model tends to include definitions of all +templates in the header file, since they must be seen to be +instantiated. + +@item Cfront model +The AT&T C++ translator, Cfront, solved the template instantiation +problem by creating the notion of a template repository, an +automatically maintained place where template instances are stored. A +more modern version of the repository works as follows: As individual +object files are built, the compiler places any template definitions and +instantiations encountered in the repository. At link time, the link +wrapper adds in the objects in the repository and compiles any needed +instances that were not previously emitted. The advantages of this +model are more optimal compilation speed and the ability to use the +system linker; to implement the Borland model a compiler vendor also +needs to replace the linker. The disadvantages are vastly increased +complexity, and thus potential for error; for some code this can be +just as transparent, but in practice it can been very difficult to build +multiple programs in one directory and one program in multiple +directories. Code written for this model tends to separate definitions +of non-inline member templates into a separate file, which should be +compiled separately. +@end table + +When used with GNU ld version 2.8 or later on an ELF system such as +GNU/Linux or Solaris 2, or on Microsoft Windows, G++ supports the +Borland model. On other systems, G++ implements neither automatic +model. + +A future version of G++ will support a hybrid model whereby the compiler +will emit any instantiations for which the template definition is +included in the compile, and store template definitions and +instantiation context information into the object file for the rest. +The link wrapper will extract that information as necessary and invoke +the compiler to produce the remaining instantiations. The linker will +then combine duplicate instantiations. + +In the mean time, you have the following options for dealing with +template instantiations: + +@enumerate +@item +@opindex frepo +Compile your template-using code with @option{-frepo}. The compiler will +generate files with the extension @samp{.rpo} listing all of the +template instantiations used in the corresponding object files which +could be instantiated there; the link wrapper, @samp{collect2}, will +then update the @samp{.rpo} files to tell the compiler where to place +those instantiations and rebuild any affected object files. The +link-time overhead is negligible after the first pass, as the compiler +will continue to place the instantiations in the same files. + +This is your best option for application code written for the Borland +model, as it will just work. Code written for the Cfront model will +need to be modified so that the template definitions are available at +one or more points of instantiation; usually this is as simple as adding +@code{#include } to the end of each template header. + +For library code, if you want the library to provide all of the template +instantiations it needs, just try to link all of its object files +together; the link will fail, but cause the instantiations to be +generated as a side effect. Be warned, however, that this may cause +conflicts if multiple libraries try to provide the same instantiations. +For greater control, use explicit instantiation as described in the next +option. + +@item +@opindex fno-implicit-templates +Compile your code with @option{-fno-implicit-templates} to disable the +implicit generation of template instances, and explicitly instantiate +all the ones you use. This approach requires more knowledge of exactly +which instances you need than do the others, but it's less +mysterious and allows greater control. You can scatter the explicit +instantiations throughout your program, perhaps putting them in the +translation units where the instances are used or the translation units +that define the templates themselves; you can put all of the explicit +instantiations you need into one big file; or you can create small files +like + +@smallexample +#include "Foo.h" +#include "Foo.cc" + +template class Foo; +template ostream& operator << + (ostream&, const Foo&); +@end smallexample + +for each of the instances you need, and create a template instantiation +library from those. + +If you are using Cfront-model code, you can probably get away with not +using @option{-fno-implicit-templates} when compiling files that don't +@samp{#include} the member template definitions. + +If you use one big file to do the instantiations, you may want to +compile it without @option{-fno-implicit-templates} so you get all of the +instances required by your explicit instantiations (but not by any +other files) without having to specify them as well. + +G++ has extended the template instantiation syntax given in the ISO +standard to allow forward declaration of explicit instantiations +(with @code{extern}), instantiation of the compiler support data for a +template class (i.e.@: the vtable) without instantiating any of its +members (with @code{inline}), and instantiation of only the static data +members of a template class, without the support data or member +functions (with (@code{static}): + +@smallexample +extern template int max (int, int); +inline template class Foo; +static template class Foo; +@end smallexample + +@item +Do nothing. Pretend G++ does implement automatic instantiation +management. Code written for the Borland model will work fine, but +each translation unit will contain instances of each of the templates it +uses. In a large program, this can lead to an unacceptable amount of code +duplication. +@end enumerate + +@node Bound member functions +@section Extracting the function pointer from a bound pointer to member function +@cindex pmf +@cindex pointer to member function +@cindex bound pointer to member function + +In C++, pointer to member functions (PMFs) are implemented using a wide +pointer of sorts to handle all the possible call mechanisms; the PMF +needs to store information about how to adjust the @samp{this} pointer, +and if the function pointed to is virtual, where to find the vtable, and +where in the vtable to look for the member function. If you are using +PMFs in an inner loop, you should really reconsider that decision. If +that is not an option, you can extract the pointer to the function that +would be called for a given object/PMF pair and call it directly inside +the inner loop, to save a bit of time. + +Note that you will still be paying the penalty for the call through a +function pointer; on most modern architectures, such a call defeats the +branch prediction features of the CPU@. This is also true of normal +virtual function calls. + +The syntax for this extension is + +@smallexample +extern A a; +extern int (A::*fp)(); +typedef int (*fptr)(A *); + +fptr p = (fptr)(a.*fp); +@end smallexample + +For PMF constants (i.e.@: expressions of the form @samp{&Klasse::Member}), +no object is needed to obtain the address of the function. They can be +converted to function pointers directly: + +@smallexample +fptr p1 = (fptr)(&A::foo); +@end smallexample + +@opindex Wno-pmf-conversions +You must specify @option{-Wno-pmf-conversions} to use this extension. + +@node C++ Attributes +@section C++-Specific Variable, Function, and Type Attributes + +Some attributes only make sense for C++ programs. + +@table @code +@item init_priority (@var{priority}) +@cindex @code{init_priority} attribute + + +In Standard C++, objects defined at namespace scope are guaranteed to be +initialized in an order in strict accordance with that of their definitions +@emph{in a given translation unit}. No guarantee is made for initializations +across translation units. However, GNU C++ allows users to control the +order of initialization of objects defined at namespace scope with the +@code{init_priority} attribute by specifying a relative @var{priority}, +a constant integral expression currently bounded between 101 and 65535 +inclusive. Lower numbers indicate a higher priority. + +In the following example, @code{A} would normally be created before +@code{B}, but the @code{init_priority} attribute has reversed that order: + +@smallexample +Some_Class A __attribute__ ((init_priority (2000))); +Some_Class B __attribute__ ((init_priority (543))); +@end smallexample + +@noindent +Note that the particular values of @var{priority} do not matter; only their +relative ordering. + +@item java_interface +@cindex @code{java_interface} attribute + +This type attribute informs C++ that the class is a Java interface. It may +only be applied to classes declared within an @code{extern "Java"} block. +Calls to methods declared in this interface will be dispatched using GCJ's +interface table mechanism, instead of regular virtual table dispatch. + +@end table + +See also @ref{Namespace Association}. + +@node Namespace Association +@section Namespace Association + +@strong{Caution:} The semantics of this extension are not fully +defined. Users should refrain from using this extension as its +semantics may change subtly over time. It is possible that this +extension will be removed in future versions of G++. + +A using-directive with @code{__attribute ((strong))} is stronger +than a normal using-directive in two ways: + +@itemize @bullet +@item +Templates from the used namespace can be specialized and explicitly +instantiated as though they were members of the using namespace. + +@item +The using namespace is considered an associated namespace of all +templates in the used namespace for purposes of argument-dependent +name lookup. +@end itemize + +The used namespace must be nested within the using namespace so that +normal unqualified lookup works properly. + +This is useful for composing a namespace transparently from +implementation namespaces. For example: + +@smallexample +namespace std @{ + namespace debug @{ + template struct A @{ @}; + @} + using namespace debug __attribute ((__strong__)); + template <> struct A @{ @}; // @r{ok to specialize} + + template void f (A); +@} + +int main() +@{ + f (std::A()); // @r{lookup finds} std::f + f (std::A()); +@} +@end smallexample + +@node Type Traits +@section Type Traits + +The C++ front-end implements syntactic extensions that allow to +determine at compile time various characteristics of a type (or of a +pair of types). + +@table @code +@item __has_nothrow_assign (type) +If @code{type} is const qualified or is a reference type then the trait is +false. Otherwise if @code{__has_trivial_assign (type)} is true then the trait +is true, else if @code{type} is a cv class or union type with copy assignment +operators that are known not to throw an exception then the trait is true, +else it is false. Requires: @code{type} shall be a complete type, +(possibly cv-qualified) @code{void}, or an array of unknown bound. + +@item __has_nothrow_copy (type) +If @code{__has_trivial_copy (type)} is true then the trait is true, else if +@code{type} is a cv class or union type with copy constructors that +are known not to throw an exception then the trait is true, else it is false. +Requires: @code{type} shall be a complete type, (possibly cv-qualified) +@code{void}, or an array of unknown bound. + +@item __has_nothrow_constructor (type) +If @code{__has_trivial_constructor (type)} is true then the trait is +true, else if @code{type} is a cv class or union type (or array +thereof) with a default constructor that is known not to throw an +exception then the trait is true, else it is false. Requires: +@code{type} shall be a complete type, (possibly cv-qualified) +@code{void}, or an array of unknown bound. + +@item __has_trivial_assign (type) +If @code{type} is const qualified or is a reference type then the trait is +false. Otherwise if @code{__is_pod (type)} is true then the trait is +true, else if @code{type} is a cv class or union type with a trivial +copy assignment ([class.copy]) then the trait is true, else it is +false. Requires: @code{type} shall be a complete type, (possibly +cv-qualified) @code{void}, or an array of unknown bound. + +@item __has_trivial_copy (type) +If @code{__is_pod (type)} is true or @code{type} is a reference type +then the trait is true, else if @code{type} is a cv class or union type +with a trivial copy constructor ([class.copy]) then the trait +is true, else it is false. Requires: @code{type} shall be a complete +type, (possibly cv-qualified) @code{void}, or an array of unknown bound. + +@item __has_trivial_constructor (type) +If @code{__is_pod (type)} is true then the trait is true, else if +@code{type} is a cv class or union type (or array thereof) with a +trivial default constructor ([class.ctor]) then the trait is true, +else it is false. Requires: @code{type} shall be a complete +type, (possibly cv-qualified) @code{void}, or an array of unknown bound. + +@item __has_trivial_destructor (type) +If @code{__is_pod (type)} is true or @code{type} is a reference type then +the trait is true, else if @code{type} is a cv class or union type (or +array thereof) with a trivial destructor ([class.dtor]) then the trait +is true, else it is false. Requires: @code{type} shall be a complete +type, (possibly cv-qualified) @code{void}, or an array of unknown bound. + +@item __has_virtual_destructor (type) +If @code{type} is a class type with a virtual destructor +([class.dtor]) then the trait is true, else it is false. Requires: +@code{type} shall be a complete type, (possibly cv-qualified) +@code{void}, or an array of unknown bound. + +@item __is_abstract (type) +If @code{type} is an abstract class ([class.abstract]) then the trait +is true, else it is false. Requires: @code{type} shall be a complete +type, (possibly cv-qualified) @code{void}, or an array of unknown bound. + +@item __is_base_of (base_type, derived_type) +If @code{base_type} is a base class of @code{derived_type} +([class.derived]) then the trait is true, otherwise it is false. +Top-level cv qualifications of @code{base_type} and +@code{derived_type} are ignored. For the purposes of this trait, a +class type is considered is own base. Requires: if @code{__is_class +(base_type)} and @code{__is_class (derived_type)} are true and +@code{base_type} and @code{derived_type} are not the same type +(disregarding cv-qualifiers), @code{derived_type} shall be a complete +type. Diagnostic is produced if this requirement is not met. + +@item __is_class (type) +If @code{type} is a cv class type, and not a union type +([basic.compound]) the trait is true, else it is false. + +@item __is_empty (type) +If @code{__is_class (type)} is false then the trait is false. +Otherwise @code{type} is considered empty if and only if: @code{type} +has no non-static data members, or all non-static data members, if +any, are bit-fields of length 0, and @code{type} has no virtual +members, and @code{type} has no virtual base classes, and @code{type} +has no base classes @code{base_type} for which +@code{__is_empty (base_type)} is false. Requires: @code{type} shall +be a complete type, (possibly cv-qualified) @code{void}, or an array +of unknown bound. + +@item __is_enum (type) +If @code{type} is a cv enumeration type ([basic.compound]) the trait is +true, else it is false. + +@item __is_literal_type (type) +If @code{type} is a literal type ([basic.types]) the trait is +true, else it is false. Requires: @code{type} shall be a complete type, +(possibly cv-qualified) @code{void}, or an array of unknown bound. + +@item __is_pod (type) +If @code{type} is a cv POD type ([basic.types]) then the trait is true, +else it is false. Requires: @code{type} shall be a complete type, +(possibly cv-qualified) @code{void}, or an array of unknown bound. + +@item __is_polymorphic (type) +If @code{type} is a polymorphic class ([class.virtual]) then the trait +is true, else it is false. Requires: @code{type} shall be a complete +type, (possibly cv-qualified) @code{void}, or an array of unknown bound. + +@item __is_standard_layout (type) +If @code{type} is a standard-layout type ([basic.types]) the trait is +true, else it is false. Requires: @code{type} shall be a complete +type, (possibly cv-qualified) @code{void}, or an array of unknown bound. + +@item __is_trivial (type) +If @code{type} is a trivial type ([basic.types]) the trait is +true, else it is false. Requires: @code{type} shall be a complete +type, (possibly cv-qualified) @code{void}, or an array of unknown bound. + +@item __is_union (type) +If @code{type} is a cv union type ([basic.compound]) the trait is +true, else it is false. + +@end table + +@node Java Exceptions +@section Java Exceptions + +The Java language uses a slightly different exception handling model +from C++. Normally, GNU C++ will automatically detect when you are +writing C++ code that uses Java exceptions, and handle them +appropriately. However, if C++ code only needs to execute destructors +when Java exceptions are thrown through it, GCC will guess incorrectly. +Sample problematic code is: + +@smallexample + struct S @{ ~S(); @}; + extern void bar(); // @r{is written in Java, and may throw exceptions} + void foo() + @{ + S s; + bar(); + @} +@end smallexample + +@noindent +The usual effect of an incorrect guess is a link failure, complaining of +a missing routine called @samp{__gxx_personality_v0}. + +You can inform the compiler that Java exceptions are to be used in a +translation unit, irrespective of what it might think, by writing +@samp{@w{#pragma GCC java_exceptions}} at the head of the file. This +@samp{#pragma} must appear before any functions that throw or catch +exceptions, or run destructors when exceptions are thrown through them. + +You cannot mix Java and C++ exceptions in the same translation unit. It +is believed to be safe to throw a C++ exception from one file through +another file compiled for the Java exception model, or vice versa, but +there may be bugs in this area. + +@node Deprecated Features +@section Deprecated Features + +In the past, the GNU C++ compiler was extended to experiment with new +features, at a time when the C++ language was still evolving. Now that +the C++ standard is complete, some of those features are superseded by +superior alternatives. Using the old features might cause a warning in +some cases that the feature will be dropped in the future. In other +cases, the feature might be gone already. + +While the list below is not exhaustive, it documents some of the options +that are now deprecated: + +@table @code +@item -fexternal-templates +@itemx -falt-external-templates +These are two of the many ways for G++ to implement template +instantiation. @xref{Template Instantiation}. The C++ standard clearly +defines how template definitions have to be organized across +implementation units. G++ has an implicit instantiation mechanism that +should work just fine for standard-conforming code. + +@item -fstrict-prototype +@itemx -fno-strict-prototype +Previously it was possible to use an empty prototype parameter list to +indicate an unspecified number of parameters (like C), rather than no +parameters, as C++ demands. This feature has been removed, except where +it is required for backwards compatibility. @xref{Backwards Compatibility}. +@end table + +G++ allows a virtual function returning @samp{void *} to be overridden +by one returning a different pointer type. This extension to the +covariant return type rules is now deprecated and will be removed from a +future version. + +The G++ minimum and maximum operators (@samp{?}) and +their compound forms (@samp{?=}) have been deprecated +and are now removed from G++. Code using these operators should be +modified to use @code{std::min} and @code{std::max} instead. + +The named return value extension has been deprecated, and is now +removed from G++. + +The use of initializer lists with new expressions has been deprecated, +and is now removed from G++. + +Floating and complex non-type template parameters have been deprecated, +and are now removed from G++. + +The implicit typename extension has been deprecated and is now +removed from G++. + +The use of default arguments in function pointers, function typedefs +and other places where they are not permitted by the standard is +deprecated and will be removed from a future version of G++. + +G++ allows floating-point literals to appear in integral constant expressions, +e.g. @samp{ enum E @{ e = int(2.2 * 3.7) @} } +This extension is deprecated and will be removed from a future version. + +G++ allows static data members of const floating-point type to be declared +with an initializer in a class definition. The standard only allows +initializers for static members of const integral types and const +enumeration types so this extension has been deprecated and will be removed +from a future version. + +@node Backwards Compatibility +@section Backwards Compatibility +@cindex Backwards Compatibility +@cindex ARM [Annotated C++ Reference Manual] + +Now that there is a definitive ISO standard C++, G++ has a specification +to adhere to. The C++ language evolved over time, and features that +used to be acceptable in previous drafts of the standard, such as the ARM +[Annotated C++ Reference Manual], are no longer accepted. In order to allow +compilation of C++ written to such drafts, G++ contains some backwards +compatibilities. @emph{All such backwards compatibility features are +liable to disappear in future versions of G++.} They should be considered +deprecated. @xref{Deprecated Features}. + +@table @code +@item For scope +If a variable is declared at for scope, it used to remain in scope until +the end of the scope which contained the for statement (rather than just +within the for scope). G++ retains this, but issues a warning, if such a +variable is accessed outside the for scope. + +@item Implicit C language +Old C system header files did not contain an @code{extern "C" @{@dots{}@}} +scope to set the language. On such systems, all header files are +implicitly scoped inside a C language scope. Also, an empty prototype +@code{()} will be treated as an unspecified number of arguments, rather +than no arguments, as C++ demands. +@end table diff --git a/gcc/doc/fragments.texi b/gcc/doc/fragments.texi new file mode 100644 index 000000000..76f27925e --- /dev/null +++ b/gcc/doc/fragments.texi @@ -0,0 +1,248 @@ +@c Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998, +@c 1999, 2000, 2001, 2003, 2004, 2005, 2008, 2012 Free Software Foundation, Inc. +@c This is part of the GCC manual. +@c For copying conditions, see the file gcc.texi. + +@node Fragments +@chapter Makefile Fragments +@cindex makefile fragment + +When you configure GCC using the @file{configure} script, it will +construct the file @file{Makefile} from the template file +@file{Makefile.in}. When it does this, it can incorporate makefile +fragments from the @file{config} directory. These are used to set +Makefile parameters that are not amenable to being calculated by +autoconf. The list of fragments to incorporate is set by +@file{config.gcc} (and occasionally @file{config.build} +and @file{config.host}); @xref{System Config}. + +Fragments are named either @file{t-@var{target}} or @file{x-@var{host}}, +depending on whether they are relevant to configuring GCC to produce +code for a particular target, or to configuring GCC to run on a +particular host. Here @var{target} and @var{host} are mnemonics +which usually have some relationship to the canonical system name, but +no formal connection. + +If these files do not exist, it means nothing needs to be added for a +given target or host. Most targets need a few @file{t-@var{target}} +fragments, but needing @file{x-@var{host}} fragments is rare. + +@menu +* Target Fragment:: Writing @file{t-@var{target}} files. +* Host Fragment:: Writing @file{x-@var{host}} files. +@end menu + +@node Target Fragment +@section Target Makefile Fragments +@cindex target makefile fragment +@cindex @file{t-@var{target}} + +Target makefile fragments can set these Makefile variables. + +@table @code +@findex LIBGCC2_CFLAGS +@item LIBGCC2_CFLAGS +Compiler flags to use when compiling @file{libgcc2.c}. + +@findex LIB2FUNCS_EXTRA +@item LIB2FUNCS_EXTRA +A list of source file names to be compiled or assembled and inserted +into @file{libgcc.a}. + +@findex Floating Point Emulation +@item Floating Point Emulation +To have GCC include software floating point libraries in @file{libgcc.a} +define @code{FPBIT} and @code{DPBIT} along with a few rules as follows: +@smallexample +# We want fine grained libraries, so use the new code +# to build the floating point emulation libraries. +FPBIT = fp-bit.c +DPBIT = dp-bit.c + + +fp-bit.c: $(srcdir)/config/fp-bit.c + echo '#define FLOAT' > fp-bit.c + cat $(srcdir)/config/fp-bit.c >> fp-bit.c + +dp-bit.c: $(srcdir)/config/fp-bit.c + cat $(srcdir)/config/fp-bit.c > dp-bit.c +@end smallexample + +You may need to provide additional #defines at the beginning of @file{fp-bit.c} +and @file{dp-bit.c} to control target endianness and other options. + + +@findex CRTSTUFF_T_CFLAGS +@item CRTSTUFF_T_CFLAGS +Special flags used when compiling @file{crtstuff.c}. +@xref{Initialization}. + +@findex CRTSTUFF_T_CFLAGS_S +@item CRTSTUFF_T_CFLAGS_S +Special flags used when compiling @file{crtstuff.c} for shared +linking. Used if you use @file{crtbeginS.o} and @file{crtendS.o} +in @code{EXTRA-PARTS}. +@xref{Initialization}. + +@findex MULTILIB_OPTIONS +@item MULTILIB_OPTIONS +For some targets, invoking GCC in different ways produces objects +that can not be linked together. For example, for some targets GCC +produces both big and little endian code. For these targets, you must +arrange for multiple versions of @file{libgcc.a} to be compiled, one for +each set of incompatible options. When GCC invokes the linker, it +arranges to link in the right version of @file{libgcc.a}, based on +the command line options used. + +The @code{MULTILIB_OPTIONS} macro lists the set of options for which +special versions of @file{libgcc.a} must be built. Write options that +are mutually incompatible side by side, separated by a slash. Write +options that may be used together separated by a space. The build +procedure will build all combinations of compatible options. + +For example, if you set @code{MULTILIB_OPTIONS} to @samp{m68000/m68020 +msoft-float}, @file{Makefile} will build special versions of +@file{libgcc.a} using the following sets of options: @option{-m68000}, +@option{-m68020}, @option{-msoft-float}, @samp{-m68000 -msoft-float}, and +@samp{-m68020 -msoft-float}. + +@findex MULTILIB_DIRNAMES +@item MULTILIB_DIRNAMES +If @code{MULTILIB_OPTIONS} is used, this variable specifies the +directory names that should be used to hold the various libraries. +Write one element in @code{MULTILIB_DIRNAMES} for each element in +@code{MULTILIB_OPTIONS}. If @code{MULTILIB_DIRNAMES} is not used, the +default value will be @code{MULTILIB_OPTIONS}, with all slashes treated +as spaces. + +@code{MULTILIB_DIRNAMES} describes the multilib directories using GCC +conventions and is applied to directories that are part of the GCC +installation. When multilib-enabled, the compiler will add a +subdirectory of the form @var{prefix}/@var{multilib} before each +directory in the search path for libraries and crt files. + +For example, if @code{MULTILIB_OPTIONS} is set to @samp{m68000/m68020 +msoft-float}, then the default value of @code{MULTILIB_DIRNAMES} is +@samp{m68000 m68020 msoft-float}. You may specify a different value if +you desire a different set of directory names. + +@findex MULTILIB_MATCHES +@item MULTILIB_MATCHES +Sometimes the same option may be written in two different ways. If an +option is listed in @code{MULTILIB_OPTIONS}, GCC needs to know about +any synonyms. In that case, set @code{MULTILIB_MATCHES} to a list of +items of the form @samp{option=option} to describe all relevant +synonyms. For example, @samp{m68000=mc68000 m68020=mc68020}. + +@findex MULTILIB_EXCEPTIONS +@item MULTILIB_EXCEPTIONS +Sometimes when there are multiple sets of @code{MULTILIB_OPTIONS} being +specified, there are combinations that should not be built. In that +case, set @code{MULTILIB_EXCEPTIONS} to be all of the switch exceptions +in shell case syntax that should not be built. + +For example the ARM processor cannot execute both hardware floating +point instructions and the reduced size THUMB instructions at the same +time, so there is no need to build libraries with both of these +options enabled. Therefore @code{MULTILIB_EXCEPTIONS} is set to: +@smallexample +*mthumb/*mhard-float* +@end smallexample + +@findex MULTILIB_EXTRA_OPTS +@item MULTILIB_EXTRA_OPTS +Sometimes it is desirable that when building multiple versions of +@file{libgcc.a} certain options should always be passed on to the +compiler. In that case, set @code{MULTILIB_EXTRA_OPTS} to be the list +of options to be used for all builds. If you set this, you should +probably set @code{CRTSTUFF_T_CFLAGS} to a dash followed by it. + +@findex NATIVE_SYSTEM_HEADER_DIR +@item NATIVE_SYSTEM_HEADER_DIR +If the default location for system headers is not @file{/usr/include}, +you must set this to the directory containing the headers. This value +should match the value of the @code{SYSTEM_INCLUDE_DIR} macro. + +@findex MULTILIB_OSDIRNAMES +@item MULTILIB_OSDIRNAMES +If @code{MULTILIB_OPTIONS} is used, this variable specifies +a list of subdirectory names, that are used to modify the search +path depending on the chosen multilib. Unlike @code{MULTILIB_DIRNAMES}, +@code{MULTILIB_OSDIRNAMES} describes the multilib directories using +operating systems conventions, and is applied to the directories such as +@code{lib} or those in the @env{LIBRARY_PATH} environment variable. +The format is either the same as of +@code{MULTILIB_DIRNAMES}, or a set of mappings. When it is the same +as @code{MULTILIB_DIRNAMES}, it describes the multilib directories +using operating system conventions, rather than GCC conventions. When it is a set +of mappings of the form @var{gccdir}=@var{osdir}, the left side gives +the GCC convention and the right gives the equivalent OS defined +location. If the @var{osdir} part begins with a @samp{!}, +GCC will not search in the non-multilib directory and use +exclusively the multilib directory. Otherwise, the compiler will +examine the search path for libraries and crt files twice; the first +time it will add @var{multilib} to each directory in the search path, +the second it will not. + +For configurations that support both multilib and multiarch, +@code{MULTILIB_OSDIRNAMES} also encodes the multiarch name, thus +subsuming @code{MULTIARCH_DIRNAME}. The multiarch name is appended to +each directory name, separated by a colon (e.g. +@samp{../lib32:i386-linux-gnu}). + +Each multiarch subdirectory will be searched before the corresponding OS +multilib directory, for example @samp{/lib/i386-linux-gnu} before +@samp{/lib/../lib32}. The multiarch name will also be used to modify the +system header search path, as explained for @code{MULTIARCH_DIRNAME}. + +@findex MULTIARCH_DIRNAME +@item MULTIARCH_DIRNAME +This variable specifies the multiarch name for configurations that are +multiarch-enabled but not multilibbed configurations. + +The multiarch name is used to augment the search path for libraries, crt +files and system header files with additional locations. The compiler +will add a multiarch subdirectory of the form +@var{prefix}/@var{multiarch} before each directory in the library and +crt search path. It will also add two directories +@code{LOCAL_INCLUDE_DIR}/@var{multiarch} and +@code{NATIVE_SYSTEM_HEADER_DIR}/@var{multiarch}) to the system header +search path, respectively before @code{LOCAL_INCLUDE_DIR} and +@code{NATIVE_SYSTEM_HEADER_DIR}. + +@code{MULTIARCH_DIRNAME} is not used for configurations that support +both multilib and multiarch. In that case, multiarch names are encoded +in @code{MULTILIB_OSDIRNAMES} instead. + +More documentation about multiarch can be found at +@uref{http://wiki.debian.org/Multiarch}. + +@findex SPECS +@item SPECS +Unfortunately, setting @code{MULTILIB_EXTRA_OPTS} is not enough, since +it does not affect the build of target libraries, at least not the +build of the default multilib. One possible work-around is to use +@code{DRIVER_SELF_SPECS} to bring options from the @file{specs} file +as if they had been passed in the compiler driver command line. +However, you don't want to be adding these options after the toolchain +is installed, so you can instead tweak the @file{specs} file that will +be used during the toolchain build, while you still install the +original, built-in @file{specs}. The trick is to set @code{SPECS} to +some other filename (say @file{specs.install}), that will then be +created out of the built-in specs, and introduce a @file{Makefile} +rule to generate the @file{specs} file that's going to be used at +build time out of your @file{specs.install}. + +@item T_CFLAGS +These are extra flags to pass to the C compiler. They are used both +when building GCC, and when compiling things with the just-built GCC@. +This variable is deprecated and should not be used. +@end table + +@node Host Fragment +@section Host Makefile Fragments +@cindex host makefile fragment +@cindex @file{x-@var{host}} + +The use of @file{x-@var{host}} fragments is discouraged. You should only +use it for makefile dependencies. diff --git a/gcc/doc/frontends.texi b/gcc/doc/frontends.texi new file mode 100644 index 000000000..6268c196e --- /dev/null +++ b/gcc/doc/frontends.texi @@ -0,0 +1,63 @@ +@c Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998, +@c 1999, 2000, 2001, 2002, 2004, 2008, 2010 Free Software Foundation, Inc. +@c This is part of the GCC manual. +@c For copying conditions, see the file gcc.texi. + +@node G++ and GCC +@chapter Programming Languages Supported by GCC + +@cindex GCC +@cindex GNU Compiler Collection +@cindex GNU C Compiler +@cindex Ada +@cindex Fortran +@cindex Go +@cindex Java +@cindex Objective-C +@cindex Objective-C++ +GCC stands for ``GNU Compiler Collection''. GCC is an integrated +distribution of compilers for several major programming languages. These +languages currently include C, C++, Objective-C, Objective-C++, Java, +Fortran, Ada, and Go. + +The abbreviation @dfn{GCC} has multiple meanings in common use. The +current official meaning is ``GNU Compiler Collection'', which refers +generically to the complete suite of tools. The name historically stood +for ``GNU C Compiler'', and this usage is still common when the emphasis +is on compiling C programs. Finally, the name is also used when speaking +of the @dfn{language-independent} component of GCC: code shared among the +compilers for all supported languages. + +The language-independent component of GCC includes the majority of the +optimizers, as well as the ``back ends'' that generate machine code for +various processors. + +@cindex COBOL +@cindex Mercury +@cindex Pascal +The part of a compiler that is specific to a particular language is +called the ``front end''. In addition to the front ends that are +integrated components of GCC, there are several other front ends that +are maintained separately. These support languages such as Pascal, +Mercury, and COBOL@. To use these, they must be built together with +GCC proper. + +@cindex C++ +@cindex G++ +@cindex Ada +@cindex GNAT +Most of the compilers for languages other than C have their own names. +The C++ compiler is G++, the Ada compiler is GNAT, and so on. When we +talk about compiling one of those languages, we might refer to that +compiler by its own name, or as GCC@. Either is correct. + +@cindex compiler compared to C++ preprocessor +@cindex intermediate C version, nonexistent +@cindex C intermediate output, nonexistent +Historically, compilers for many languages, including C++ and Fortran, +have been implemented as ``preprocessors'' which emit another high +level language such as C@. None of the compilers included in GCC are +implemented this way; they all generate machine code directly. This +sort of preprocessor should not be confused with the @dfn{C +preprocessor}, which is an integral feature of the C, C++, Objective-C +and Objective-C++ languages. diff --git a/gcc/doc/fsf-funding.7 b/gcc/doc/fsf-funding.7 new file mode 100644 index 000000000..1e3595d52 --- /dev/null +++ b/gcc/doc/fsf-funding.7 @@ -0,0 +1,184 @@ +.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is turned on, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.ie \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. nr % 0 +. rr F +.\} +.el \{\ +. de IX +.. +.\} +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "FSF-FUNDING 7" +.TH FSF-FUNDING 7 "2013-04-12" "gcc-4.6.4" "GNU" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +fsf\-funding \- Funding Free Software +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +.SS "Funding Free Software" +.IX Subsection "Funding Free Software" +If you want to have more free software a few years from now, it makes +sense for you to help encourage people to contribute funds for its +development. The most effective approach known is to encourage +commercial redistributors to donate. +.PP +Users of free software systems can boost the pace of development by +encouraging for-a-fee distributors to donate part of their selling price +to free software developers\-\-\-the Free Software Foundation, and others. +.PP +The way to convince distributors to do this is to demand it and expect +it from them. So when you compare distributors, judge them partly by +how much they give to free software development. Show distributors +they must compete to be the one who gives the most. +.PP +To make this approach work, you must insist on numbers that you can +compare, such as, \*(L"We will donate ten dollars to the Frobnitz project +for each disk sold.\*(R" Don't be satisfied with a vague promise, such as +\&\*(L"A portion of the profits are donated,\*(R" since it doesn't give a basis +for comparison. +.PP +Even a precise fraction \*(L"of the profits from this disk\*(R" is not very +meaningful, since creative accounting and unrelated business decisions +can greatly alter what fraction of the sales price counts as profit. +If the price you pay is \f(CW$50\fR, ten percent of the profit is probably +less than a dollar; it might be a few cents, or nothing at all. +.PP +Some redistributors do development work themselves. This is useful too; +but to keep everyone honest, you need to inquire how much they do, and +what kind. Some kinds of development make much more long-term +difference than others. For example, maintaining a separate version of +a program contributes very little; maintaining the standard version of a +program for the whole community contributes much. Easy new ports +contribute little, since someone else would surely do them; difficult +ports such as adding a new \s-1CPU\s0 to the \s-1GNU\s0 Compiler Collection contribute more; +major new features or packages contribute the most. +.PP +By establishing the idea that supporting further development is \*(L"the +proper thing to do\*(R" when distributing free software for a fee, we can +assure a steady flow of resources into making more free software. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fIgpl\fR\|(7), \fIgfdl\fR\|(7). +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright (c) 1994 Free Software Foundation, Inc. +Verbatim copying and redistribution of this section is permitted +without royalty; alteration is not permitted. diff --git a/gcc/doc/g++.1 b/gcc/doc/g++.1 new file mode 100644 index 000000000..37b7abdd4 --- /dev/null +++ b/gcc/doc/g++.1 @@ -0,0 +1,17436 @@ +.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is turned on, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.ie \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. nr % 0 +. rr F +.\} +.el \{\ +. de IX +.. +.\} +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "GCC 1" +.TH GCC 1 "2013-04-12" "gcc-4.6.4" "GNU" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +gcc \- GNU project C and C++ compiler +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +gcc [\fB\-c\fR|\fB\-S\fR|\fB\-E\fR] [\fB\-std=\fR\fIstandard\fR] + [\fB\-g\fR] [\fB\-pg\fR] [\fB\-O\fR\fIlevel\fR] + [\fB\-W\fR\fIwarn\fR...] [\fB\-pedantic\fR] + [\fB\-I\fR\fIdir\fR...] [\fB\-L\fR\fIdir\fR...] + [\fB\-D\fR\fImacro\fR[=\fIdefn\fR]...] [\fB\-U\fR\fImacro\fR] + [\fB\-f\fR\fIoption\fR...] [\fB\-m\fR\fImachine-option\fR...] + [\fB\-o\fR \fIoutfile\fR] [@\fIfile\fR] \fIinfile\fR... +.PP +Only the most useful options are listed here; see below for the +remainder. \fBg++\fR accepts mostly the same options as \fBgcc\fR. +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +When you invoke \s-1GCC\s0, it normally does preprocessing, compilation, +assembly and linking. The \*(L"overall options\*(R" allow you to stop this +process at an intermediate stage. For example, the \fB\-c\fR option +says not to run the linker. Then the output consists of object files +output by the assembler. +.PP +Other options are passed on to one stage of processing. Some options +control the preprocessor and others the compiler itself. Yet other +options control the assembler and linker; most of these are not +documented here, since you rarely need to use any of them. +.PP +Most of the command line options that you can use with \s-1GCC\s0 are useful +for C programs; when an option is only useful with another language +(usually \*(C+), the explanation says so explicitly. If the description +for a particular option does not mention a source language, you can use +that option with all supported languages. +.PP +The \fBgcc\fR program accepts options and file names as operands. Many +options have multi-letter names; therefore multiple single-letter options +may \fInot\fR be grouped: \fB\-dv\fR is very different from \fB\-d\ \-v\fR. +.PP +You can mix options and other arguments. For the most part, the order +you use doesn't matter. Order does matter when you use several +options of the same kind; for example, if you specify \fB\-L\fR more +than once, the directories are searched in the order specified. Also, +the placement of the \fB\-l\fR option is significant. +.PP +Many options have long names starting with \fB\-f\fR or with +\&\fB\-W\fR\-\-\-for example, +\&\fB\-fmove\-loop\-invariants\fR, \fB\-Wformat\fR and so on. Most of +these have both positive and negative forms; the negative form of +\&\fB\-ffoo\fR would be \fB\-fno\-foo\fR. This manual documents +only one of these two forms, whichever one is not the default. +.SH "OPTIONS" +.IX Header "OPTIONS" +.SS "Option Summary" +.IX Subsection "Option Summary" +Here is a summary of all the options, grouped by type. Explanations are +in the following sections. +.IP "\fIOverall Options\fR" 4 +.IX Item "Overall Options" +\&\fB\-c \-S \-E \-o\fR \fIfile\fR \fB\-no\-canonical\-prefixes +\&\-pipe \-pass\-exit\-codes +\&\-x\fR \fIlanguage\fR \fB\-v \-### \-\-help\fR[\fB=\fR\fIclass\fR[\fB,...\fR]] \fB\-\-target\-help +\&\-\-version \-wrapper @\fR\fIfile\fR \fB\-fplugin=\fR\fIfile\fR \fB\-fplugin\-arg\-\fR\fIname\fR\fB=\fR\fIarg\fR +\&\fB\-fdump\-ada\-spec\fR[\fB\-slim\fR] \fB\-fdump\-go\-spec=\fR\fIfile\fR +.IP "\fIC Language Options\fR" 4 +.IX Item "C Language Options" +\&\fB\-ansi \-std=\fR\fIstandard\fR \fB\-fgnu89\-inline +\&\-aux\-info\fR \fIfilename\fR +\&\fB\-fno\-asm \-fno\-builtin \-fno\-builtin\-\fR\fIfunction\fR +\&\fB\-fhosted \-ffreestanding \-fopenmp \-fms\-extensions \-fplan9\-extensions +\&\-trigraphs \-no\-integrated\-cpp \-traditional \-traditional\-cpp +\&\-fallow\-single\-precision \-fcond\-mismatch \-flax\-vector\-conversions +\&\-fsigned\-bitfields \-fsigned\-char +\&\-funsigned\-bitfields \-funsigned\-char\fR +.IP "\fI\*(C+ Language Options\fR" 4 +.IX Item " Language Options" +\&\fB\-fabi\-version=\fR\fIn\fR \fB\-fno\-access\-control \-fcheck\-new +\&\-fconserve\-space \-fconstexpr\-depth=\fR\fIn\fR \fB\-ffriend\-injection +\&\-fno\-elide\-constructors +\&\-fno\-enforce\-eh\-specs +\&\-ffor\-scope \-fno\-for\-scope \-fno\-gnu\-keywords +\&\-fno\-implicit\-templates +\&\-fno\-implicit\-inline\-templates +\&\-fno\-implement\-inlines \-fms\-extensions +\&\-fno\-nonansi\-builtins \-fnothrow\-opt \-fno\-operator\-names +\&\-fno\-optional\-diags \-fpermissive +\&\-fno\-pretty\-templates +\&\-frepo \-fno\-rtti \-fstats \-ftemplate\-depth=\fR\fIn\fR +\&\fB\-fno\-threadsafe\-statics \-fuse\-cxa\-atexit \-fno\-weak \-nostdinc++ +\&\-fno\-default\-inline \-fvisibility\-inlines\-hidden +\&\-fvisibility\-ms\-compat +\&\-Wabi \-Wconversion\-null \-Wctor\-dtor\-privacy +\&\-Wnoexcept \-Wnon\-virtual\-dtor \-Wreorder +\&\-Weffc++ \-Wstrict\-null\-sentinel +\&\-Wno\-non\-template\-friend \-Wold\-style\-cast +\&\-Woverloaded\-virtual \-Wno\-pmf\-conversions +\&\-Wsign\-promo\fR +.IP "\fIObjective-C and Objective\-\*(C+ Language Options\fR" 4 +.IX Item "Objective-C and Objective- Language Options" +\&\fB\-fconstant\-string\-class=\fR\fIclass-name\fR +\&\fB\-fgnu\-runtime \-fnext\-runtime +\&\-fno\-nil\-receivers +\&\-fobjc\-abi\-version=\fR\fIn\fR +\&\fB\-fobjc\-call\-cxx\-cdtors +\&\-fobjc\-direct\-dispatch +\&\-fobjc\-exceptions +\&\-fobjc\-gc +\&\-fobjc\-nilcheck +\&\-fobjc\-std=objc1 +\&\-freplace\-objc\-classes +\&\-fzero\-link +\&\-gen\-decls +\&\-Wassign\-intercept +\&\-Wno\-protocol \-Wselector +\&\-Wstrict\-selector\-match +\&\-Wundeclared\-selector\fR +.IP "\fILanguage Independent Options\fR" 4 +.IX Item "Language Independent Options" +\&\fB\-fmessage\-length=\fR\fIn\fR +\&\fB\-fdiagnostics\-show\-location=\fR[\fBonce\fR|\fBevery-line\fR] +\&\fB\-fno\-diagnostics\-show\-option\fR +.IP "\fIWarning Options\fR" 4 +.IX Item "Warning Options" +\&\fB\-fsyntax\-only \-fmax\-errors=\fR\fIn\fR \fB\-pedantic +\&\-pedantic\-errors +\&\-w \-Wextra \-Wall \-Waddress \-Waggregate\-return \-Warray\-bounds +\&\-Wno\-attributes \-Wno\-builtin\-macro\-redefined +\&\-Wc++\-compat \-Wc++0x\-compat \-Wcast\-align \-Wcast\-qual +\&\-Wchar\-subscripts \-Wclobbered \-Wcomment +\&\-Wconversion \-Wcoverage\-mismatch \-Wno\-cpp \-Wno\-deprecated +\&\-Wno\-deprecated\-declarations \-Wdisabled\-optimization +\&\-Wno\-div\-by\-zero \-Wdouble\-promotion \-Wempty\-body \-Wenum\-compare +\&\-Wno\-endif\-labels \-Werror \-Werror=* +\&\-Wfatal\-errors \-Wfloat\-equal \-Wformat \-Wformat=2 +\&\-Wno\-format\-contains\-nul \-Wno\-format\-extra\-args \-Wformat\-nonliteral +\&\-Wformat\-security \-Wformat\-y2k +\&\-Wframe\-larger\-than=\fR\fIlen\fR \fB\-Wjump\-misses\-init \-Wignored\-qualifiers +\&\-Wimplicit \-Wimplicit\-function\-declaration \-Wimplicit\-int +\&\-Winit\-self \-Winline +\&\-Wno\-int\-to\-pointer\-cast \-Wno\-invalid\-offsetof +\&\-Winvalid\-pch \-Wlarger\-than=\fR\fIlen\fR \fB\-Wunsafe\-loop\-optimizations +\&\-Wlogical\-op \-Wlong\-long +\&\-Wmain \-Wmissing\-braces \-Wmissing\-field\-initializers +\&\-Wmissing\-format\-attribute \-Wmissing\-include\-dirs +\&\-Wno\-mudflap +\&\-Wno\-multichar \-Wnonnull \-Wno\-overflow +\&\-Woverlength\-strings \-Wpacked \-Wpacked\-bitfield\-compat \-Wpadded +\&\-Wparentheses \-Wpedantic\-ms\-format \-Wno\-pedantic\-ms\-format +\&\-Wpointer\-arith \-Wno\-pointer\-to\-int\-cast +\&\-Wredundant\-decls +\&\-Wreturn\-type \-Wsequence\-point \-Wshadow +\&\-Wsign\-compare \-Wsign\-conversion \-Wstack\-protector +\&\-Wstrict\-aliasing \-Wstrict\-aliasing=n +\&\-Wstrict\-overflow \-Wstrict\-overflow=\fR\fIn\fR +\&\fB\-Wsuggest\-attribute=\fR[\fBpure\fR|\fBconst\fR|\fBnoreturn\fR] +\&\fB\-Wswitch \-Wswitch\-default \-Wswitch\-enum \-Wsync\-nand +\&\-Wsystem\-headers \-Wtrampolines \-Wtrigraphs \-Wtype\-limits \-Wundef +\&\-Wuninitialized \-Wunknown\-pragmas \-Wno\-pragmas +\&\-Wunsuffixed\-float\-constants \-Wunused \-Wunused\-function +\&\-Wunused\-label \-Wunused\-parameter \-Wno\-unused\-result \-Wunused\-value +\&\-Wunused\-variable \-Wunused\-but\-set\-parameter \-Wunused\-but\-set\-variable +\&\-Wvariadic\-macros \-Wvla \-Wvolatile\-register\-var \-Wwrite\-strings\fR +.IP "\fIC and Objective-C-only Warning Options\fR" 4 +.IX Item "C and Objective-C-only Warning Options" +\&\fB\-Wbad\-function\-cast \-Wmissing\-declarations +\&\-Wmissing\-parameter\-type \-Wmissing\-prototypes \-Wnested\-externs +\&\-Wold\-style\-declaration \-Wold\-style\-definition +\&\-Wstrict\-prototypes \-Wtraditional \-Wtraditional\-conversion +\&\-Wdeclaration\-after\-statement \-Wpointer\-sign\fR +.IP "\fIDebugging Options\fR" 4 +.IX Item "Debugging Options" +\&\fB\-d\fR\fIletters\fR \fB\-dumpspecs \-dumpmachine \-dumpversion +\&\-fdbg\-cnt\-list \-fdbg\-cnt=\fR\fIcounter-value-list\fR +\&\fB\-fdump\-noaddr \-fdump\-unnumbered \-fdump\-unnumbered\-links +\&\-fdump\-translation\-unit\fR[\fB\-\fR\fIn\fR] +\&\fB\-fdump\-class\-hierarchy\fR[\fB\-\fR\fIn\fR] +\&\fB\-fdump\-ipa\-all \-fdump\-ipa\-cgraph \-fdump\-ipa\-inline +\&\-fdump\-statistics +\&\-fdump\-tree\-all +\&\-fdump\-tree\-original\fR[\fB\-\fR\fIn\fR] +\&\fB\-fdump\-tree\-optimized\fR[\fB\-\fR\fIn\fR] +\&\fB\-fdump\-tree\-cfg \-fdump\-tree\-vcg \-fdump\-tree\-alias +\&\-fdump\-tree\-ch +\&\-fdump\-tree\-ssa\fR[\fB\-\fR\fIn\fR] \fB\-fdump\-tree\-pre\fR[\fB\-\fR\fIn\fR] +\&\fB\-fdump\-tree\-ccp\fR[\fB\-\fR\fIn\fR] \fB\-fdump\-tree\-dce\fR[\fB\-\fR\fIn\fR] +\&\fB\-fdump\-tree\-gimple\fR[\fB\-raw\fR] \fB\-fdump\-tree\-mudflap\fR[\fB\-\fR\fIn\fR] +\&\fB\-fdump\-tree\-dom\fR[\fB\-\fR\fIn\fR] +\&\fB\-fdump\-tree\-dse\fR[\fB\-\fR\fIn\fR] +\&\fB\-fdump\-tree\-phiprop\fR[\fB\-\fR\fIn\fR] +\&\fB\-fdump\-tree\-phiopt\fR[\fB\-\fR\fIn\fR] +\&\fB\-fdump\-tree\-forwprop\fR[\fB\-\fR\fIn\fR] +\&\fB\-fdump\-tree\-copyrename\fR[\fB\-\fR\fIn\fR] +\&\fB\-fdump\-tree\-nrv \-fdump\-tree\-vect +\&\-fdump\-tree\-sink +\&\-fdump\-tree\-sra\fR[\fB\-\fR\fIn\fR] +\&\fB\-fdump\-tree\-forwprop\fR[\fB\-\fR\fIn\fR] +\&\fB\-fdump\-tree\-fre\fR[\fB\-\fR\fIn\fR] +\&\fB\-fdump\-tree\-vrp\fR[\fB\-\fR\fIn\fR] +\&\fB\-ftree\-vectorizer\-verbose=\fR\fIn\fR +\&\fB\-fdump\-tree\-storeccp\fR[\fB\-\fR\fIn\fR] +\&\fB\-fdump\-final\-insns=\fR\fIfile\fR +\&\fB\-fcompare\-debug\fR[\fB=\fR\fIopts\fR] \fB\-fcompare\-debug\-second +\&\-feliminate\-dwarf2\-dups \-feliminate\-unused\-debug\-types +\&\-feliminate\-unused\-debug\-symbols \-femit\-class\-debug\-always +\&\-fenable\-icf\-debug +\&\-fmem\-report \-fpre\-ipa\-mem\-report \-fpost\-ipa\-mem\-report \-fprofile\-arcs +\&\-frandom\-seed=\fR\fIstring\fR \fB\-fsched\-verbose=\fR\fIn\fR +\&\fB\-fsel\-sched\-verbose \-fsel\-sched\-dump\-cfg \-fsel\-sched\-pipelining\-verbose +\&\-fstack\-usage \-ftest\-coverage \-ftime\-report \-fvar\-tracking +\&\-fvar\-tracking\-assignments \-fvar\-tracking\-assignments\-toggle +\&\-g \-g\fR\fIlevel\fR \fB\-gtoggle \-gcoff \-gdwarf\-\fR\fIversion\fR +\&\fB\-ggdb \-gstabs \-gstabs+ \-gstrict\-dwarf \-gno\-strict\-dwarf +\&\-gvms \-gxcoff \-gxcoff+ +\&\-fno\-merge\-debug\-strings \-fno\-dwarf2\-cfi\-asm +\&\-fdebug\-prefix\-map=\fR\fIold\fR\fB=\fR\fInew\fR +\&\fB\-femit\-struct\-debug\-baseonly \-femit\-struct\-debug\-reduced +\&\-femit\-struct\-debug\-detailed\fR[\fB=\fR\fIspec-list\fR] +\&\fB\-p \-pg \-print\-file\-name=\fR\fIlibrary\fR \fB\-print\-libgcc\-file\-name +\&\-print\-multi\-directory \-print\-multi\-lib \-print\-multi\-os\-directory +\&\-print\-prog\-name=\fR\fIprogram\fR \fB\-print\-search\-dirs \-Q +\&\-print\-sysroot \-print\-sysroot\-headers\-suffix +\&\-save\-temps \-save\-temps=cwd \-save\-temps=obj \-time\fR[\fB=\fR\fIfile\fR] +.IP "\fIOptimization Options\fR" 4 +.IX Item "Optimization Options" +\&\fB\-falign\-functions[=\fR\fIn\fR\fB] \-falign\-jumps[=\fR\fIn\fR\fB] +\&\-falign\-labels[=\fR\fIn\fR\fB] \-falign\-loops[=\fR\fIn\fR\fB] \-fassociative\-math +\&\-fauto\-inc\-dec \-fbranch\-probabilities \-fbranch\-target\-load\-optimize +\&\-fbranch\-target\-load\-optimize2 \-fbtr\-bb\-exclusive \-fcaller\-saves +\&\-fcheck\-data\-deps \-fcombine\-stack\-adjustments \-fconserve\-stack +\&\-fcompare\-elim \-fcprop\-registers \-fcrossjumping +\&\-fcse\-follow\-jumps \-fcse\-skip\-blocks \-fcx\-fortran\-rules +\&\-fcx\-limited\-range +\&\-fdata\-sections \-fdce \-fdce \-fdelayed\-branch +\&\-fdelete\-null\-pointer\-checks \-fdse \-fdevirtualize \-fdse +\&\-fearly\-inlining \-fipa\-sra \-fexpensive\-optimizations \-ffast\-math +\&\-ffinite\-math\-only \-ffloat\-store \-fexcess\-precision=\fR\fIstyle\fR +\&\fB\-fforward\-propagate \-ffp\-contract=\fR\fIstyle\fR \fB\-ffunction\-sections +\&\-fgcse \-fgcse\-after\-reload \-fgcse\-las \-fgcse\-lm \-fgraphite\-identity +\&\-fgcse\-sm \-fif\-conversion \-fif\-conversion2 \-findirect\-inlining +\&\-finline\-functions \-finline\-functions\-called\-once \-finline\-limit=\fR\fIn\fR +\&\fB\-finline\-small\-functions \-fipa\-cp \-fipa\-cp\-clone \-fipa\-matrix\-reorg +\&\-fipa\-pta \-fipa\-profile \-fipa\-pure\-const \-fipa\-reference +\&\-fipa\-struct\-reorg \-fira\-algorithm=\fR\fIalgorithm\fR +\&\fB\-fira\-region=\fR\fIregion\fR +\&\fB\-fira\-loop\-pressure \-fno\-ira\-share\-save\-slots +\&\-fno\-ira\-share\-spill\-slots \-fira\-verbose=\fR\fIn\fR +\&\fB\-fivopts \-fkeep\-inline\-functions \-fkeep\-static\-consts +\&\-floop\-block \-floop\-flatten \-floop\-interchange \-floop\-strip\-mine +\&\-floop\-parallelize\-all \-flto \-flto\-compression\-level +\&\-flto\-partition=\fR\fIalg\fR \fB\-flto\-report \-fmerge\-all\-constants +\&\-fmerge\-constants \-fmodulo\-sched \-fmodulo\-sched\-allow\-regmoves +\&\-fmove\-loop\-invariants fmudflap \-fmudflapir \-fmudflapth \-fno\-branch\-count\-reg +\&\-fno\-default\-inline +\&\-fno\-defer\-pop \-fno\-function\-cse \-fno\-guess\-branch\-probability +\&\-fno\-inline \-fno\-math\-errno \-fno\-peephole \-fno\-peephole2 +\&\-fno\-sched\-interblock \-fno\-sched\-spec \-fno\-signed\-zeros +\&\-fno\-toplevel\-reorder \-fno\-trapping\-math \-fno\-zero\-initialized\-in\-bss +\&\-fomit\-frame\-pointer \-foptimize\-register\-move \-foptimize\-sibling\-calls +\&\-fpartial\-inlining \-fpeel\-loops \-fpredictive\-commoning +\&\-fprefetch\-loop\-arrays +\&\-fprofile\-correction \-fprofile\-dir=\fR\fIpath\fR \fB\-fprofile\-generate +\&\-fprofile\-generate=\fR\fIpath\fR +\&\fB\-fprofile\-use \-fprofile\-use=\fR\fIpath\fR \fB\-fprofile\-values +\&\-freciprocal\-math \-fregmove \-frename\-registers \-freorder\-blocks +\&\-freorder\-blocks\-and\-partition \-freorder\-functions +\&\-frerun\-cse\-after\-loop \-freschedule\-modulo\-scheduled\-loops +\&\-frounding\-math \-fsched2\-use\-superblocks \-fsched\-pressure +\&\-fsched\-spec\-load \-fsched\-spec\-load\-dangerous +\&\-fsched\-stalled\-insns\-dep[=\fR\fIn\fR\fB] \-fsched\-stalled\-insns[=\fR\fIn\fR\fB] +\&\-fsched\-group\-heuristic \-fsched\-critical\-path\-heuristic +\&\-fsched\-spec\-insn\-heuristic \-fsched\-rank\-heuristic +\&\-fsched\-last\-insn\-heuristic \-fsched\-dep\-count\-heuristic +\&\-fschedule\-insns \-fschedule\-insns2 \-fsection\-anchors +\&\-fselective\-scheduling \-fselective\-scheduling2 +\&\-fsel\-sched\-pipelining \-fsel\-sched\-pipelining\-outer\-loops +\&\-fsignaling\-nans \-fsingle\-precision\-constant \-fsplit\-ivs\-in\-unroller +\&\-fsplit\-wide\-types \-fstack\-protector \-fstack\-protector\-all +\&\-fstrict\-aliasing \-fstrict\-overflow \-fthread\-jumps \-ftracer +\&\-ftree\-bit\-ccp +\&\-ftree\-builtin\-call\-dce \-ftree\-ccp \-ftree\-ch \-ftree\-copy\-prop +\&\-ftree\-copyrename \-ftree\-dce \-ftree\-dominator\-opts \-ftree\-dse +\&\-ftree\-forwprop \-ftree\-fre \-ftree\-loop\-if\-convert +\&\-ftree\-loop\-if\-convert\-stores \-ftree\-loop\-im +\&\-ftree\-phiprop \-ftree\-loop\-distribution \-ftree\-loop\-distribute\-patterns +\&\-ftree\-loop\-ivcanon \-ftree\-loop\-linear \-ftree\-loop\-optimize +\&\-ftree\-parallelize\-loops=\fR\fIn\fR \fB\-ftree\-pre \-ftree\-pta \-ftree\-reassoc +\&\-ftree\-sink \-ftree\-sra \-ftree\-switch\-conversion +\&\-ftree\-ter \-ftree\-vect\-loop\-version \-ftree\-vectorize \-ftree\-vrp +\&\-funit\-at\-a\-time \-funroll\-all\-loops \-funroll\-loops +\&\-funsafe\-loop\-optimizations \-funsafe\-math\-optimizations \-funswitch\-loops +\&\-fvariable\-expansion\-in\-unroller \-fvect\-cost\-model \-fvpt \-fweb +\&\-fwhole\-program \-fwpa \-fuse\-linker\-plugin +\&\-\-param\fR \fIname\fR\fB=\fR\fIvalue\fR +\&\fB\-O \-O0 \-O1 \-O2 \-O3 \-Os \-Ofast\fR +.IP "\fIPreprocessor Options\fR" 4 +.IX Item "Preprocessor Options" +\&\fB\-A\fR\fIquestion\fR\fB=\fR\fIanswer\fR +\&\fB\-A\-\fR\fIquestion\fR[\fB=\fR\fIanswer\fR] +\&\fB\-C \-dD \-dI \-dM \-dN +\&\-D\fR\fImacro\fR[\fB=\fR\fIdefn\fR] \fB\-E \-H +\&\-idirafter\fR \fIdir\fR +\&\fB\-include\fR \fIfile\fR \fB\-imacros\fR \fIfile\fR +\&\fB\-iprefix\fR \fIfile\fR \fB\-iwithprefix\fR \fIdir\fR +\&\fB\-iwithprefixbefore\fR \fIdir\fR \fB\-isystem\fR \fIdir\fR +\&\fB\-imultilib\fR \fIdir\fR \fB\-isysroot\fR \fIdir\fR +\&\fB\-M \-MM \-MF \-MG \-MP \-MQ \-MT \-nostdinc +\&\-P \-fworking\-directory \-remap +\&\-trigraphs \-undef \-U\fR\fImacro\fR \fB\-Wp,\fR\fIoption\fR +\&\fB\-Xpreprocessor\fR \fIoption\fR +.IP "\fIAssembler Option\fR" 4 +.IX Item "Assembler Option" +\&\fB\-Wa,\fR\fIoption\fR \fB\-Xassembler\fR \fIoption\fR +.IP "\fILinker Options\fR" 4 +.IX Item "Linker Options" +\&\fIobject-file-name\fR \fB\-l\fR\fIlibrary\fR +\&\fB\-nostartfiles \-nodefaultlibs \-nostdlib \-pie \-rdynamic +\&\-s \-static \-static\-libgcc \-static\-libstdc++ \-shared +\&\-shared\-libgcc \-symbolic +\&\-T\fR \fIscript\fR \fB\-Wl,\fR\fIoption\fR \fB\-Xlinker\fR \fIoption\fR +\&\fB\-u\fR \fIsymbol\fR +.IP "\fIDirectory Options\fR" 4 +.IX Item "Directory Options" +\&\fB\-B\fR\fIprefix\fR \fB\-I\fR\fIdir\fR \fB\-iplugindir=\fR\fIdir\fR +\&\-iquote\fIdir\fR \-L\fIdir\fR \-specs=\fIfile\fR \-I\- +\&\-\-sysroot=\fIdir\fR +.IP "\fIMachine Dependent Options\fR" 4 +.IX Item "Machine Dependent Options" +\&\fI\s-1ARC\s0 Options\fR +\&\fB\-EB \-EL +\&\-mmangle\-cpu \-mcpu=\fR\fIcpu\fR \fB\-mtext=\fR\fItext-section\fR +\&\fB\-mdata=\fR\fIdata-section\fR \fB\-mrodata=\fR\fIreadonly-data-section\fR +.Sp +\&\fI\s-1ARM\s0 Options\fR +\&\fB\-mapcs\-frame \-mno\-apcs\-frame +\&\-mabi=\fR\fIname\fR +\&\fB\-mapcs\-stack\-check \-mno\-apcs\-stack\-check +\&\-mapcs\-float \-mno\-apcs\-float +\&\-mapcs\-reentrant \-mno\-apcs\-reentrant +\&\-msched\-prolog \-mno\-sched\-prolog +\&\-mlittle\-endian \-mbig\-endian \-mwords\-little\-endian +\&\-mfloat\-abi=\fR\fIname\fR \fB\-msoft\-float \-mhard\-float \-mfpe +\&\-mfp16\-format=\fR\fIname\fR +\&\fB\-mthumb\-interwork \-mno\-thumb\-interwork +\&\-mcpu=\fR\fIname\fR \fB\-march=\fR\fIname\fR \fB\-mfpu=\fR\fIname\fR +\&\fB\-mstructure\-size\-boundary=\fR\fIn\fR +\&\fB\-mabort\-on\-noreturn +\&\-mlong\-calls \-mno\-long\-calls +\&\-msingle\-pic\-base \-mno\-single\-pic\-base +\&\-mpic\-register=\fR\fIreg\fR +\&\fB\-mnop\-fun\-dllimport +\&\-mcirrus\-fix\-invalid\-insns \-mno\-cirrus\-fix\-invalid\-insns +\&\-mpoke\-function\-name +\&\-mthumb \-marm +\&\-mtpcs\-frame \-mtpcs\-leaf\-frame +\&\-mcaller\-super\-interworking \-mcallee\-super\-interworking +\&\-mtp=\fR\fIname\fR +\&\fB\-mword\-relocations +\&\-mfix\-cortex\-m3\-ldrd\fR +.Sp +\&\fI\s-1AVR\s0 Options\fR +\&\fB\-mmcu=\fR\fImcu\fR \fB\-mno\-interrupts +\&\-mcall\-prologues \-mtiny\-stack \-mint8\fR +.Sp +\&\fIBlackfin Options\fR +\&\fB\-mcpu=\fR\fIcpu\fR[\fB\-\fR\fIsirevision\fR] +\&\fB\-msim \-momit\-leaf\-frame\-pointer \-mno\-omit\-leaf\-frame\-pointer +\&\-mspecld\-anomaly \-mno\-specld\-anomaly \-mcsync\-anomaly \-mno\-csync\-anomaly +\&\-mlow\-64k \-mno\-low64k \-mstack\-check\-l1 \-mid\-shared\-library +\&\-mno\-id\-shared\-library \-mshared\-library\-id=\fR\fIn\fR +\&\fB\-mleaf\-id\-shared\-library \-mno\-leaf\-id\-shared\-library +\&\-msep\-data \-mno\-sep\-data \-mlong\-calls \-mno\-long\-calls +\&\-mfast\-fp \-minline\-plt \-mmulticore \-mcorea \-mcoreb \-msdram +\&\-micplb\fR +.Sp +\&\fI\s-1CRIS\s0 Options\fR +\&\fB\-mcpu=\fR\fIcpu\fR \fB\-march=\fR\fIcpu\fR \fB\-mtune=\fR\fIcpu\fR +\&\fB\-mmax\-stack\-frame=\fR\fIn\fR \fB\-melinux\-stacksize=\fR\fIn\fR +\&\fB\-metrax4 \-metrax100 \-mpdebug \-mcc\-init \-mno\-side\-effects +\&\-mstack\-align \-mdata\-align \-mconst\-align +\&\-m32\-bit \-m16\-bit \-m8\-bit \-mno\-prologue\-epilogue \-mno\-gotplt +\&\-melf \-maout \-melinux \-mlinux \-sim \-sim2 +\&\-mmul\-bug\-workaround \-mno\-mul\-bug\-workaround\fR +.Sp +\&\fI\s-1CRX\s0 Options\fR +\&\fB\-mmac \-mpush\-args\fR +.Sp +\&\fIDarwin Options\fR +\&\fB\-all_load \-allowable_client \-arch \-arch_errors_fatal +\&\-arch_only \-bind_at_load \-bundle \-bundle_loader +\&\-client_name \-compatibility_version \-current_version +\&\-dead_strip +\&\-dependency\-file \-dylib_file \-dylinker_install_name +\&\-dynamic \-dynamiclib \-exported_symbols_list +\&\-filelist \-flat_namespace \-force_cpusubtype_ALL +\&\-force_flat_namespace \-headerpad_max_install_names +\&\-iframework +\&\-image_base \-init \-install_name \-keep_private_externs +\&\-multi_module \-multiply_defined \-multiply_defined_unused +\&\-noall_load \-no_dead_strip_inits_and_terms +\&\-nofixprebinding \-nomultidefs \-noprebind \-noseglinkedit +\&\-pagezero_size \-prebind \-prebind_all_twolevel_modules +\&\-private_bundle \-read_only_relocs \-sectalign +\&\-sectobjectsymbols \-whyload \-seg1addr +\&\-sectcreate \-sectobjectsymbols \-sectorder +\&\-segaddr \-segs_read_only_addr \-segs_read_write_addr +\&\-seg_addr_table \-seg_addr_table_filename \-seglinkedit +\&\-segprot \-segs_read_only_addr \-segs_read_write_addr +\&\-single_module \-static \-sub_library \-sub_umbrella +\&\-twolevel_namespace \-umbrella \-undefined +\&\-unexported_symbols_list \-weak_reference_mismatches +\&\-whatsloaded \-F \-gused \-gfull \-mmacosx\-version\-min=\fR\fIversion\fR +\&\fB\-mkernel \-mone\-byte\-bool\fR +.Sp +\&\fI\s-1DEC\s0 Alpha Options\fR +\&\fB\-mno\-fp\-regs \-msoft\-float \-malpha\-as \-mgas +\&\-mieee \-mieee\-with\-inexact \-mieee\-conformant +\&\-mfp\-trap\-mode=\fR\fImode\fR \fB\-mfp\-rounding\-mode=\fR\fImode\fR +\&\fB\-mtrap\-precision=\fR\fImode\fR \fB\-mbuild\-constants +\&\-mcpu=\fR\fIcpu-type\fR \fB\-mtune=\fR\fIcpu-type\fR +\&\fB\-mbwx \-mmax \-mfix \-mcix +\&\-mfloat\-vax \-mfloat\-ieee +\&\-mexplicit\-relocs \-msmall\-data \-mlarge\-data +\&\-msmall\-text \-mlarge\-text +\&\-mmemory\-latency=\fR\fItime\fR +.Sp +\&\fI\s-1DEC\s0 Alpha/VMS Options\fR +\&\fB\-mvms\-return\-codes \-mdebug\-main=\fR\fIprefix\fR \fB\-mmalloc64\fR +.Sp +\&\fI\s-1FR30\s0 Options\fR +\&\fB\-msmall\-model \-mno\-lsim\fR +.Sp +\&\fI\s-1FRV\s0 Options\fR +\&\fB\-mgpr\-32 \-mgpr\-64 \-mfpr\-32 \-mfpr\-64 +\&\-mhard\-float \-msoft\-float +\&\-malloc\-cc \-mfixed\-cc \-mdword \-mno\-dword +\&\-mdouble \-mno\-double +\&\-mmedia \-mno\-media \-mmuladd \-mno\-muladd +\&\-mfdpic \-minline\-plt \-mgprel\-ro \-multilib\-library\-pic +\&\-mlinked\-fp \-mlong\-calls \-malign\-labels +\&\-mlibrary\-pic \-macc\-4 \-macc\-8 +\&\-mpack \-mno\-pack \-mno\-eflags \-mcond\-move \-mno\-cond\-move +\&\-moptimize\-membar \-mno\-optimize\-membar +\&\-mscc \-mno\-scc \-mcond\-exec \-mno\-cond\-exec +\&\-mvliw\-branch \-mno\-vliw\-branch +\&\-mmulti\-cond\-exec \-mno\-multi\-cond\-exec \-mnested\-cond\-exec +\&\-mno\-nested\-cond\-exec \-mtomcat\-stats +\&\-mTLS \-mtls +\&\-mcpu=\fR\fIcpu\fR +.Sp +\&\fIGNU/Linux Options\fR +\&\fB\-mglibc \-muclibc \-mbionic \-mandroid +\&\-tno\-android\-cc \-tno\-android\-ld\fR +.Sp +\&\fIH8/300 Options\fR +\&\fB\-mrelax \-mh \-ms \-mn \-mint32 \-malign\-300\fR +.Sp +\&\fI\s-1HPPA\s0 Options\fR +\&\fB\-march=\fR\fIarchitecture-type\fR +\&\fB\-mbig\-switch \-mdisable\-fpregs \-mdisable\-indexing +\&\-mfast\-indirect\-calls \-mgas \-mgnu\-ld \-mhp\-ld +\&\-mfixed\-range=\fR\fIregister-range\fR +\&\fB\-mjump\-in\-delay \-mlinker\-opt \-mlong\-calls +\&\-mlong\-load\-store \-mno\-big\-switch \-mno\-disable\-fpregs +\&\-mno\-disable\-indexing \-mno\-fast\-indirect\-calls \-mno\-gas +\&\-mno\-jump\-in\-delay \-mno\-long\-load\-store +\&\-mno\-portable\-runtime \-mno\-soft\-float +\&\-mno\-space\-regs \-msoft\-float \-mpa\-risc\-1\-0 +\&\-mpa\-risc\-1\-1 \-mpa\-risc\-2\-0 \-mportable\-runtime +\&\-mschedule=\fR\fIcpu-type\fR \fB\-mspace\-regs \-msio \-mwsio +\&\-munix=\fR\fIunix-std\fR \fB\-nolibdld \-static \-threads\fR +.Sp +\&\fIi386 and x86\-64 Options\fR +\&\fB\-mtune=\fR\fIcpu-type\fR \fB\-march=\fR\fIcpu-type\fR +\&\fB\-mfpmath=\fR\fIunit\fR +\&\fB\-masm=\fR\fIdialect\fR \fB\-mno\-fancy\-math\-387 +\&\-mno\-fp\-ret\-in\-387 \-msoft\-float +\&\-mno\-wide\-multiply \-mrtd \-malign\-double +\&\-mpreferred\-stack\-boundary=\fR\fInum\fR +\&\fB\-mincoming\-stack\-boundary=\fR\fInum\fR +\&\fB\-mcld \-mcx16 \-msahf \-mmovbe \-mcrc32 \-mrecip +\&\-mvzeroupper \-mprefer\-avx128 +\&\-mmmx \-msse \-msse2 \-msse3 \-mssse3 \-msse4.1 \-msse4.2 \-msse4 \-mavx +\&\-maes \-mpclmul \-mfsgsbase \-mrdrnd \-mf16c \-mfused\-madd +\&\-msse4a \-m3dnow \-mpopcnt \-mabm \-mbmi \-mtbm \-mfma4 \-mxop \-mlwp +\&\-mthreads \-mno\-align\-stringops \-minline\-all\-stringops +\&\-minline\-stringops\-dynamically \-mstringop\-strategy=\fR\fIalg\fR +\&\fB\-mpush\-args \-maccumulate\-outgoing\-args \-m128bit\-long\-double +\&\-m96bit\-long\-double \-mregparm=\fR\fInum\fR \fB\-msseregparm +\&\-mveclibabi=\fR\fItype\fR \fB\-mvect8\-ret\-in\-mem +\&\-mpc32 \-mpc64 \-mpc80 \-mstackrealign +\&\-momit\-leaf\-frame\-pointer \-mno\-red\-zone \-mno\-tls\-direct\-seg\-refs +\&\-mcmodel=\fR\fIcode-model\fR \fB\-mabi=\fR\fIname\fR +\&\fB\-m32 \-m64 \-mlarge\-data\-threshold=\fR\fInum\fR +\&\fB\-msse2avx \-mfentry \-m8bit\-idiv +\&\-mavx256\-split\-unaligned\-load \-mavx256\-split\-unaligned\-store\fR +.Sp +\&\fIi386 and x86\-64 Windows Options\fR +\&\fB\-mconsole \-mcygwin \-mno\-cygwin \-mdll +\&\-mnop\-fun\-dllimport \-mthread +\&\-municode \-mwin32 \-mwindows \-fno\-set\-stack\-executable\fR +.Sp +\&\fI\s-1IA\-64\s0 Options\fR +\&\fB\-mbig\-endian \-mlittle\-endian \-mgnu\-as \-mgnu\-ld \-mno\-pic +\&\-mvolatile\-asm\-stop \-mregister\-names \-msdata \-mno\-sdata +\&\-mconstant\-gp \-mauto\-pic \-mfused\-madd +\&\-minline\-float\-divide\-min\-latency +\&\-minline\-float\-divide\-max\-throughput +\&\-mno\-inline\-float\-divide +\&\-minline\-int\-divide\-min\-latency +\&\-minline\-int\-divide\-max\-throughput +\&\-mno\-inline\-int\-divide +\&\-minline\-sqrt\-min\-latency \-minline\-sqrt\-max\-throughput +\&\-mno\-inline\-sqrt +\&\-mdwarf2\-asm \-mearly\-stop\-bits +\&\-mfixed\-range=\fR\fIregister-range\fR \fB\-mtls\-size=\fR\fItls-size\fR +\&\fB\-mtune=\fR\fIcpu-type\fR \fB\-milp32 \-mlp64 +\&\-msched\-br\-data\-spec \-msched\-ar\-data\-spec \-msched\-control\-spec +\&\-msched\-br\-in\-data\-spec \-msched\-ar\-in\-data\-spec \-msched\-in\-control\-spec +\&\-msched\-spec\-ldc \-msched\-spec\-control\-ldc +\&\-msched\-prefer\-non\-data\-spec\-insns \-msched\-prefer\-non\-control\-spec\-insns +\&\-msched\-stop\-bits\-after\-every\-cycle \-msched\-count\-spec\-in\-critical\-path +\&\-msel\-sched\-dont\-check\-control\-spec \-msched\-fp\-mem\-deps\-zero\-cost +\&\-msched\-max\-memory\-insns\-hard\-limit \-msched\-max\-memory\-insns=\fR\fImax-insns\fR +.Sp +\&\fI\s-1IA\-64/VMS\s0 Options\fR +\&\fB\-mvms\-return\-codes \-mdebug\-main=\fR\fIprefix\fR \fB\-mmalloc64\fR +.Sp +\&\fI\s-1LM32\s0 Options\fR +\&\fB\-mbarrel\-shift\-enabled \-mdivide\-enabled \-mmultiply\-enabled +\&\-msign\-extend\-enabled \-muser\-enabled\fR +.Sp +\&\fIM32R/D Options\fR +\&\fB\-m32r2 \-m32rx \-m32r +\&\-mdebug +\&\-malign\-loops \-mno\-align\-loops +\&\-missue\-rate=\fR\fInumber\fR +\&\fB\-mbranch\-cost=\fR\fInumber\fR +\&\fB\-mmodel=\fR\fIcode-size-model-type\fR +\&\fB\-msdata=\fR\fIsdata-type\fR +\&\fB\-mno\-flush\-func \-mflush\-func=\fR\fIname\fR +\&\fB\-mno\-flush\-trap \-mflush\-trap=\fR\fInumber\fR +\&\fB\-G\fR \fInum\fR +.Sp +\&\fIM32C Options\fR +\&\fB\-mcpu=\fR\fIcpu\fR \fB\-msim \-memregs=\fR\fInumber\fR +.Sp +\&\fIM680x0 Options\fR +\&\fB\-march=\fR\fIarch\fR \fB\-mcpu=\fR\fIcpu\fR \fB\-mtune=\fR\fItune\fR +\&\fB\-m68000 \-m68020 \-m68020\-40 \-m68020\-60 \-m68030 \-m68040 +\&\-m68060 \-mcpu32 \-m5200 \-m5206e \-m528x \-m5307 \-m5407 +\&\-mcfv4e \-mbitfield \-mno\-bitfield \-mc68000 \-mc68020 +\&\-mnobitfield \-mrtd \-mno\-rtd \-mdiv \-mno\-div \-mshort +\&\-mno\-short \-mhard\-float \-m68881 \-msoft\-float \-mpcrel +\&\-malign\-int \-mstrict\-align \-msep\-data \-mno\-sep\-data +\&\-mshared\-library\-id=n \-mid\-shared\-library \-mno\-id\-shared\-library +\&\-mxgot \-mno\-xgot\fR +.Sp +\&\fIM68hc1x Options\fR +\&\fB\-m6811 \-m6812 \-m68hc11 \-m68hc12 \-m68hcs12 +\&\-mauto\-incdec \-minmax \-mlong\-calls \-mshort +\&\-msoft\-reg\-count=\fR\fIcount\fR +.Sp +\&\fIMCore Options\fR +\&\fB\-mhardlit \-mno\-hardlit \-mdiv \-mno\-div \-mrelax\-immediates +\&\-mno\-relax\-immediates \-mwide\-bitfields \-mno\-wide\-bitfields +\&\-m4byte\-functions \-mno\-4byte\-functions \-mcallgraph\-data +\&\-mno\-callgraph\-data \-mslow\-bytes \-mno\-slow\-bytes \-mno\-lsim +\&\-mlittle\-endian \-mbig\-endian \-m210 \-m340 \-mstack\-increment\fR +.Sp +\&\fIMeP Options\fR +\&\fB\-mabsdiff \-mall\-opts \-maverage \-mbased=\fR\fIn\fR \fB\-mbitops +\&\-mc=\fR\fIn\fR \fB\-mclip \-mconfig=\fR\fIname\fR \fB\-mcop \-mcop32 \-mcop64 \-mivc2 +\&\-mdc \-mdiv \-meb \-mel \-mio\-volatile \-ml \-mleadz \-mm \-mminmax +\&\-mmult \-mno\-opts \-mrepeat \-ms \-msatur \-msdram \-msim \-msimnovec \-mtf +\&\-mtiny=\fR\fIn\fR +.Sp +\&\fIMicroBlaze Options\fR +\&\fB\-msoft\-float \-mhard\-float \-msmall\-divides \-mcpu=\fR\fIcpu\fR +\&\fB\-mmemcpy \-mxl\-soft\-mul \-mxl\-soft\-div \-mxl\-barrel\-shift +\&\-mxl\-pattern\-compare \-mxl\-stack\-check \-mxl\-gp\-opt \-mno\-clearbss +\&\-mxl\-multiply\-high \-mxl\-float\-convert \-mxl\-float\-sqrt +\&\-mxl\-mode\-\fR\fIapp-model\fR +.Sp +\&\fI\s-1MIPS\s0 Options\fR +\&\fB\-EL \-EB \-march=\fR\fIarch\fR \fB\-mtune=\fR\fIarch\fR +\&\fB\-mips1 \-mips2 \-mips3 \-mips4 \-mips32 \-mips32r2 +\&\-mips64 \-mips64r2 +\&\-mips16 \-mno\-mips16 \-mflip\-mips16 +\&\-minterlink\-mips16 \-mno\-interlink\-mips16 +\&\-mabi=\fR\fIabi\fR \fB\-mabicalls \-mno\-abicalls +\&\-mshared \-mno\-shared \-mplt \-mno\-plt \-mxgot \-mno\-xgot +\&\-mgp32 \-mgp64 \-mfp32 \-mfp64 \-mhard\-float \-msoft\-float +\&\-msingle\-float \-mdouble\-float \-mdsp \-mno\-dsp \-mdspr2 \-mno\-dspr2 +\&\-mfpu=\fR\fIfpu-type\fR +\&\fB\-msmartmips \-mno\-smartmips +\&\-mpaired\-single \-mno\-paired\-single \-mdmx \-mno\-mdmx +\&\-mips3d \-mno\-mips3d \-mmt \-mno\-mt \-mllsc \-mno\-llsc +\&\-mlong64 \-mlong32 \-msym32 \-mno\-sym32 +\&\-G\fR\fInum\fR \fB\-mlocal\-sdata \-mno\-local\-sdata +\&\-mextern\-sdata \-mno\-extern\-sdata \-mgpopt \-mno\-gopt +\&\-membedded\-data \-mno\-embedded\-data +\&\-muninit\-const\-in\-rodata \-mno\-uninit\-const\-in\-rodata +\&\-mcode\-readable=\fR\fIsetting\fR +\&\fB\-msplit\-addresses \-mno\-split\-addresses +\&\-mexplicit\-relocs \-mno\-explicit\-relocs +\&\-mcheck\-zero\-division \-mno\-check\-zero\-division +\&\-mdivide\-traps \-mdivide\-breaks +\&\-mmemcpy \-mno\-memcpy \-mlong\-calls \-mno\-long\-calls +\&\-mmad \-mno\-mad \-mfused\-madd \-mno\-fused\-madd \-nocpp +\&\-mfix\-r4000 \-mno\-fix\-r4000 \-mfix\-r4400 \-mno\-fix\-r4400 +\&\-mfix\-r10000 \-mno\-fix\-r10000 \-mfix\-vr4120 \-mno\-fix\-vr4120 +\&\-mfix\-vr4130 \-mno\-fix\-vr4130 \-mfix\-sb1 \-mno\-fix\-sb1 +\&\-mflush\-func=\fR\fIfunc\fR \fB\-mno\-flush\-func +\&\-mbranch\-cost=\fR\fInum\fR \fB\-mbranch\-likely \-mno\-branch\-likely +\&\-mfp\-exceptions \-mno\-fp\-exceptions +\&\-mvr4130\-align \-mno\-vr4130\-align \-msynci \-mno\-synci +\&\-mrelax\-pic\-calls \-mno\-relax\-pic\-calls \-mmcount\-ra\-address\fR +.Sp +\&\fI\s-1MMIX\s0 Options\fR +\&\fB\-mlibfuncs \-mno\-libfuncs \-mepsilon \-mno\-epsilon \-mabi=gnu +\&\-mabi=mmixware \-mzero\-extend \-mknuthdiv \-mtoplevel\-symbols +\&\-melf \-mbranch\-predict \-mno\-branch\-predict \-mbase\-addresses +\&\-mno\-base\-addresses \-msingle\-exit \-mno\-single\-exit\fR +.Sp +\&\fI\s-1MN10300\s0 Options\fR +\&\fB\-mmult\-bug \-mno\-mult\-bug +\&\-mno\-am33 \-mam33 \-mam33\-2 \-mam34 +\&\-mtune=\fR\fIcpu-type\fR +\&\fB\-mreturn\-pointer\-on\-d0 +\&\-mno\-crt0 \-mrelax \-mliw\fR +.Sp +\&\fI\s-1PDP\-11\s0 Options\fR +\&\fB\-mfpu \-msoft\-float \-mac0 \-mno\-ac0 \-m40 \-m45 \-m10 +\&\-mbcopy \-mbcopy\-builtin \-mint32 \-mno\-int16 +\&\-mint16 \-mno\-int32 \-mfloat32 \-mno\-float64 +\&\-mfloat64 \-mno\-float32 \-mabshi \-mno\-abshi +\&\-mbranch\-expensive \-mbranch\-cheap +\&\-munix\-asm \-mdec\-asm\fR +.Sp +\&\fIpicoChip Options\fR +\&\fB\-mae=\fR\fIae_type\fR \fB\-mvliw\-lookahead=\fR\fIN\fR +\&\fB\-msymbol\-as\-address \-mno\-inefficient\-warnings\fR +.Sp +\&\fIPowerPC Options\fR +See \s-1RS/6000\s0 and PowerPC Options. +.Sp +\&\fI\s-1RS/6000\s0 and PowerPC Options\fR +\&\fB\-mcpu=\fR\fIcpu-type\fR +\&\fB\-mtune=\fR\fIcpu-type\fR +\&\fB\-mcmodel=\fR\fIcode-model\fR +\&\fB\-mpower \-mno\-power \-mpower2 \-mno\-power2 +\&\-mpowerpc \-mpowerpc64 \-mno\-powerpc +\&\-maltivec \-mno\-altivec +\&\-mpowerpc\-gpopt \-mno\-powerpc\-gpopt +\&\-mpowerpc\-gfxopt \-mno\-powerpc\-gfxopt +\&\-mmfcrf \-mno\-mfcrf \-mpopcntb \-mno\-popcntb \-mpopcntd \-mno\-popcntd +\&\-mfprnd \-mno\-fprnd +\&\-mcmpb \-mno\-cmpb \-mmfpgpr \-mno\-mfpgpr \-mhard\-dfp \-mno\-hard\-dfp +\&\-mnew\-mnemonics \-mold\-mnemonics +\&\-mfull\-toc \-mminimal\-toc \-mno\-fp\-in\-toc \-mno\-sum\-in\-toc +\&\-m64 \-m32 \-mxl\-compat \-mno\-xl\-compat \-mpe +\&\-malign\-power \-malign\-natural +\&\-msoft\-float \-mhard\-float \-mmultiple \-mno\-multiple +\&\-msingle\-float \-mdouble\-float \-msimple\-fpu +\&\-mstring \-mno\-string \-mupdate \-mno\-update +\&\-mavoid\-indexed\-addresses \-mno\-avoid\-indexed\-addresses +\&\-mfused\-madd \-mno\-fused\-madd \-mbit\-align \-mno\-bit\-align +\&\-mstrict\-align \-mno\-strict\-align \-mrelocatable +\&\-mno\-relocatable \-mrelocatable\-lib \-mno\-relocatable\-lib +\&\-mtoc \-mno\-toc \-mlittle \-mlittle\-endian \-mbig \-mbig\-endian +\&\-mdynamic\-no\-pic \-maltivec \-mswdiv \-msingle\-pic\-base +\&\-mprioritize\-restricted\-insns=\fR\fIpriority\fR +\&\fB\-msched\-costly\-dep=\fR\fIdependence_type\fR +\&\fB\-minsert\-sched\-nops=\fR\fIscheme\fR +\&\fB\-mcall\-sysv \-mcall\-netbsd +\&\-maix\-struct\-return \-msvr4\-struct\-return +\&\-mabi=\fR\fIabi-type\fR \fB\-msecure\-plt \-mbss\-plt +\&\-mblock\-move\-inline\-limit=\fR\fInum\fR +\&\fB\-misel \-mno\-isel +\&\-misel=yes \-misel=no +\&\-mspe \-mno\-spe +\&\-mspe=yes \-mspe=no +\&\-mpaired +\&\-mgen\-cell\-microcode \-mwarn\-cell\-microcode +\&\-mvrsave \-mno\-vrsave +\&\-mmulhw \-mno\-mulhw +\&\-mdlmzb \-mno\-dlmzb +\&\-mfloat\-gprs=yes \-mfloat\-gprs=no \-mfloat\-gprs=single \-mfloat\-gprs=double +\&\-mprototype \-mno\-prototype +\&\-msim \-mmvme \-mads \-myellowknife \-memb \-msdata +\&\-msdata=\fR\fIopt\fR \fB\-mvxworks \-G\fR \fInum\fR \fB\-pthread +\&\-mrecip \-mrecip=\fR\fIopt\fR \fB\-mno\-recip \-mrecip\-precision +\&\-mno\-recip\-precision +\&\-mveclibabi=\fR\fItype\fR \fB\-mfriz \-mno\-friz\fR +.Sp +\&\fI\s-1RX\s0 Options\fR +\&\fB\-m64bit\-doubles \-m32bit\-doubles \-fpu \-nofpu +\&\-mcpu= +\&\-mbig\-endian\-data \-mlittle\-endian\-data +\&\-msmall\-data +\&\-msim \-mno\-sim +\&\-mas100\-syntax \-mno\-as100\-syntax +\&\-mrelax +\&\-mmax\-constant\-size= +\&\-mint\-register= +\&\-msave\-acc\-in\-interrupts\fR +.Sp +\&\fIS/390 and zSeries Options\fR +\&\fB\-mtune=\fR\fIcpu-type\fR \fB\-march=\fR\fIcpu-type\fR +\&\fB\-mhard\-float \-msoft\-float \-mhard\-dfp \-mno\-hard\-dfp +\&\-mlong\-double\-64 \-mlong\-double\-128 +\&\-mbackchain \-mno\-backchain \-mpacked\-stack \-mno\-packed\-stack +\&\-msmall\-exec \-mno\-small\-exec \-mmvcle \-mno\-mvcle +\&\-m64 \-m31 \-mdebug \-mno\-debug \-mesa \-mzarch +\&\-mtpf\-trace \-mno\-tpf\-trace \-mfused\-madd \-mno\-fused\-madd +\&\-mwarn\-framesize \-mwarn\-dynamicstack \-mstack\-size \-mstack\-guard\fR +.Sp +\&\fIScore Options\fR +\&\fB\-meb \-mel +\&\-mnhwloop +\&\-muls +\&\-mmac +\&\-mscore5 \-mscore5u \-mscore7 \-mscore7d\fR +.Sp +\&\fI\s-1SH\s0 Options\fR +\&\fB\-m1 \-m2 \-m2e +\&\-m2a\-nofpu \-m2a\-single\-only \-m2a\-single \-m2a +\&\-m3 \-m3e +\&\-m4\-nofpu \-m4\-single\-only \-m4\-single \-m4 +\&\-m4a\-nofpu \-m4a\-single\-only \-m4a\-single \-m4a \-m4al +\&\-m5\-64media \-m5\-64media\-nofpu +\&\-m5\-32media \-m5\-32media\-nofpu +\&\-m5\-compact \-m5\-compact\-nofpu +\&\-mb \-ml \-mdalign \-mrelax +\&\-mbigtable \-mfmovd \-mhitachi \-mrenesas \-mno\-renesas \-mnomacsave +\&\-mieee \-mno\-ieee \-mbitops \-misize \-minline\-ic_invalidate \-mpadstruct +\&\-mspace \-mprefergot \-musermode \-multcost=\fR\fInumber\fR \fB\-mdiv=\fR\fIstrategy\fR +\&\fB\-mdivsi3_libfunc=\fR\fIname\fR \fB\-mfixed\-range=\fR\fIregister-range\fR +\&\fB\-madjust\-unroll \-mindexed\-addressing \-mgettrcost=\fR\fInumber\fR \fB\-mpt\-fixed +\&\-maccumulate\-outgoing\-args \-minvalid\-symbols\fR +.Sp +\&\fISolaris 2 Options\fR +\&\fB\-mimpure\-text \-mno\-impure\-text +\&\-threads \-pthreads \-pthread\fR +.Sp +\&\fI\s-1SPARC\s0 Options\fR +\&\fB\-mcpu=\fR\fIcpu-type\fR +\&\fB\-mtune=\fR\fIcpu-type\fR +\&\fB\-mcmodel=\fR\fIcode-model\fR +\&\fB\-m32 \-m64 \-mapp\-regs \-mno\-app\-regs +\&\-mfaster\-structs \-mno\-faster\-structs +\&\-mfpu \-mno\-fpu \-mhard\-float \-msoft\-float +\&\-mhard\-quad\-float \-msoft\-quad\-float +\&\-mlittle\-endian +\&\-mstack\-bias \-mno\-stack\-bias +\&\-munaligned\-doubles \-mno\-unaligned\-doubles +\&\-mv8plus \-mno\-v8plus \-mvis \-mno\-vis +\&\-mfix\-at697f\fR +.Sp +\&\fI\s-1SPU\s0 Options\fR +\&\fB\-mwarn\-reloc \-merror\-reloc +\&\-msafe\-dma \-munsafe\-dma +\&\-mbranch\-hints +\&\-msmall\-mem \-mlarge\-mem \-mstdmain +\&\-mfixed\-range=\fR\fIregister-range\fR +\&\fB\-mea32 \-mea64 +\&\-maddress\-space\-conversion \-mno\-address\-space\-conversion +\&\-mcache\-size=\fR\fIcache-size\fR +\&\fB\-matomic\-updates \-mno\-atomic\-updates\fR +.Sp +\&\fISystem V Options\fR +\&\fB\-Qy \-Qn \-YP,\fR\fIpaths\fR \fB\-Ym,\fR\fIdir\fR +.Sp +\&\fIV850 Options\fR +\&\fB\-mlong\-calls \-mno\-long\-calls \-mep \-mno\-ep +\&\-mprolog\-function \-mno\-prolog\-function \-mspace +\&\-mtda=\fR\fIn\fR \fB\-msda=\fR\fIn\fR \fB\-mzda=\fR\fIn\fR +\&\fB\-mapp\-regs \-mno\-app\-regs +\&\-mdisable\-callt \-mno\-disable\-callt +\&\-mv850e2v3 +\&\-mv850e2 +\&\-mv850e1 \-mv850es +\&\-mv850e +\&\-mv850 \-mbig\-switch\fR +.Sp +\&\fI\s-1VAX\s0 Options\fR +\&\fB\-mg \-mgnu \-munix\fR +.Sp +\&\fIVxWorks Options\fR +\&\fB\-mrtp \-non\-static \-Bstatic \-Bdynamic +\&\-Xbind\-lazy \-Xbind\-now\fR +.Sp +\&\fIx86\-64 Options\fR +See i386 and x86\-64 Options. +.Sp +\&\fIXstormy16 Options\fR +\&\fB\-msim\fR +.Sp +\&\fIXtensa Options\fR +\&\fB\-mconst16 \-mno\-const16 +\&\-mfused\-madd \-mno\-fused\-madd +\&\-mforce\-no\-pic +\&\-mserialize\-volatile \-mno\-serialize\-volatile +\&\-mtext\-section\-literals \-mno\-text\-section\-literals +\&\-mtarget\-align \-mno\-target\-align +\&\-mlongcalls \-mno\-longcalls\fR +.Sp +\&\fIzSeries Options\fR +See S/390 and zSeries Options. +.IP "\fICode Generation Options\fR" 4 +.IX Item "Code Generation Options" +\&\fB\-fcall\-saved\-\fR\fIreg\fR \fB\-fcall\-used\-\fR\fIreg\fR +\&\fB\-ffixed\-\fR\fIreg\fR \fB\-fexceptions +\&\-fnon\-call\-exceptions \-funwind\-tables +\&\-fasynchronous\-unwind\-tables +\&\-finhibit\-size\-directive \-finstrument\-functions +\&\-finstrument\-functions\-exclude\-function\-list=\fR\fIsym\fR\fB,\fR\fIsym\fR\fB,... +\&\-finstrument\-functions\-exclude\-file\-list=\fR\fIfile\fR\fB,\fR\fIfile\fR\fB,... +\&\-fno\-common \-fno\-ident +\&\-fpcc\-struct\-return \-fpic \-fPIC \-fpie \-fPIE +\&\-fno\-jump\-tables +\&\-frecord\-gcc\-switches +\&\-freg\-struct\-return \-fshort\-enums +\&\-fshort\-double \-fshort\-wchar +\&\-fverbose\-asm \-fpack\-struct[=\fR\fIn\fR\fB] \-fstack\-check +\&\-fstack\-limit\-register=\fR\fIreg\fR \fB\-fstack\-limit\-symbol=\fR\fIsym\fR +\&\fB\-fno\-stack\-limit \-fsplit\-stack +\&\-fleading\-underscore \-ftls\-model=\fR\fImodel\fR +\&\fB\-ftrapv \-fwrapv \-fbounds\-check +\&\-fvisibility \-fstrict\-volatile\-bitfields\fR +.SS "Options Controlling the Kind of Output" +.IX Subsection "Options Controlling the Kind of Output" +Compilation can involve up to four stages: preprocessing, compilation +proper, assembly and linking, always in that order. \s-1GCC\s0 is capable of +preprocessing and compiling several files either into several +assembler input files, or into one assembler input file; then each +assembler input file produces an object file, and linking combines all +the object files (those newly compiled, and those specified as input) +into an executable file. +.PP +For any given input file, the file name suffix determines what kind of +compilation is done: +.IP "\fIfile\fR\fB.c\fR" 4 +.IX Item "file.c" +C source code which must be preprocessed. +.IP "\fIfile\fR\fB.i\fR" 4 +.IX Item "file.i" +C source code which should not be preprocessed. +.IP "\fIfile\fR\fB.ii\fR" 4 +.IX Item "file.ii" +\&\*(C+ source code which should not be preprocessed. +.IP "\fIfile\fR\fB.m\fR" 4 +.IX Item "file.m" +Objective-C source code. Note that you must link with the \fIlibobjc\fR +library to make an Objective-C program work. +.IP "\fIfile\fR\fB.mi\fR" 4 +.IX Item "file.mi" +Objective-C source code which should not be preprocessed. +.IP "\fIfile\fR\fB.mm\fR" 4 +.IX Item "file.mm" +.PD 0 +.IP "\fIfile\fR\fB.M\fR" 4 +.IX Item "file.M" +.PD +Objective\-\*(C+ source code. Note that you must link with the \fIlibobjc\fR +library to make an Objective\-\*(C+ program work. Note that \fB.M\fR refers +to a literal capital M. +.IP "\fIfile\fR\fB.mii\fR" 4 +.IX Item "file.mii" +Objective\-\*(C+ source code which should not be preprocessed. +.IP "\fIfile\fR\fB.h\fR" 4 +.IX Item "file.h" +C, \*(C+, Objective-C or Objective\-\*(C+ header file to be turned into a +precompiled header (default), or C, \*(C+ header file to be turned into an +Ada spec (via the \fB\-fdump\-ada\-spec\fR switch). +.IP "\fIfile\fR\fB.cc\fR" 4 +.IX Item "file.cc" +.PD 0 +.IP "\fIfile\fR\fB.cp\fR" 4 +.IX Item "file.cp" +.IP "\fIfile\fR\fB.cxx\fR" 4 +.IX Item "file.cxx" +.IP "\fIfile\fR\fB.cpp\fR" 4 +.IX Item "file.cpp" +.IP "\fIfile\fR\fB.CPP\fR" 4 +.IX Item "file.CPP" +.IP "\fIfile\fR\fB.c++\fR" 4 +.IX Item "file.c++" +.IP "\fIfile\fR\fB.C\fR" 4 +.IX Item "file.C" +.PD +\&\*(C+ source code which must be preprocessed. Note that in \fB.cxx\fR, +the last two letters must both be literally \fBx\fR. Likewise, +\&\fB.C\fR refers to a literal capital C. +.IP "\fIfile\fR\fB.mm\fR" 4 +.IX Item "file.mm" +.PD 0 +.IP "\fIfile\fR\fB.M\fR" 4 +.IX Item "file.M" +.PD +Objective\-\*(C+ source code which must be preprocessed. +.IP "\fIfile\fR\fB.mii\fR" 4 +.IX Item "file.mii" +Objective\-\*(C+ source code which should not be preprocessed. +.IP "\fIfile\fR\fB.hh\fR" 4 +.IX Item "file.hh" +.PD 0 +.IP "\fIfile\fR\fB.H\fR" 4 +.IX Item "file.H" +.IP "\fIfile\fR\fB.hp\fR" 4 +.IX Item "file.hp" +.IP "\fIfile\fR\fB.hxx\fR" 4 +.IX Item "file.hxx" +.IP "\fIfile\fR\fB.hpp\fR" 4 +.IX Item "file.hpp" +.IP "\fIfile\fR\fB.HPP\fR" 4 +.IX Item "file.HPP" +.IP "\fIfile\fR\fB.h++\fR" 4 +.IX Item "file.h++" +.IP "\fIfile\fR\fB.tcc\fR" 4 +.IX Item "file.tcc" +.PD +\&\*(C+ header file to be turned into a precompiled header or Ada spec. +.IP "\fIfile\fR\fB.f\fR" 4 +.IX Item "file.f" +.PD 0 +.IP "\fIfile\fR\fB.for\fR" 4 +.IX Item "file.for" +.IP "\fIfile\fR\fB.ftn\fR" 4 +.IX Item "file.ftn" +.PD +Fixed form Fortran source code which should not be preprocessed. +.IP "\fIfile\fR\fB.F\fR" 4 +.IX Item "file.F" +.PD 0 +.IP "\fIfile\fR\fB.FOR\fR" 4 +.IX Item "file.FOR" +.IP "\fIfile\fR\fB.fpp\fR" 4 +.IX Item "file.fpp" +.IP "\fIfile\fR\fB.FPP\fR" 4 +.IX Item "file.FPP" +.IP "\fIfile\fR\fB.FTN\fR" 4 +.IX Item "file.FTN" +.PD +Fixed form Fortran source code which must be preprocessed (with the traditional +preprocessor). +.IP "\fIfile\fR\fB.f90\fR" 4 +.IX Item "file.f90" +.PD 0 +.IP "\fIfile\fR\fB.f95\fR" 4 +.IX Item "file.f95" +.IP "\fIfile\fR\fB.f03\fR" 4 +.IX Item "file.f03" +.IP "\fIfile\fR\fB.f08\fR" 4 +.IX Item "file.f08" +.PD +Free form Fortran source code which should not be preprocessed. +.IP "\fIfile\fR\fB.F90\fR" 4 +.IX Item "file.F90" +.PD 0 +.IP "\fIfile\fR\fB.F95\fR" 4 +.IX Item "file.F95" +.IP "\fIfile\fR\fB.F03\fR" 4 +.IX Item "file.F03" +.IP "\fIfile\fR\fB.F08\fR" 4 +.IX Item "file.F08" +.PD +Free form Fortran source code which must be preprocessed (with the +traditional preprocessor). +.IP "\fIfile\fR\fB.go\fR" 4 +.IX Item "file.go" +Go source code. +.IP "\fIfile\fR\fB.ads\fR" 4 +.IX Item "file.ads" +Ada source code file which contains a library unit declaration (a +declaration of a package, subprogram, or generic, or a generic +instantiation), or a library unit renaming declaration (a package, +generic, or subprogram renaming declaration). Such files are also +called \fIspecs\fR. +.IP "\fIfile\fR\fB.adb\fR" 4 +.IX Item "file.adb" +Ada source code file containing a library unit body (a subprogram or +package body). Such files are also called \fIbodies\fR. +.IP "\fIfile\fR\fB.s\fR" 4 +.IX Item "file.s" +Assembler code. +.IP "\fIfile\fR\fB.S\fR" 4 +.IX Item "file.S" +.PD 0 +.IP "\fIfile\fR\fB.sx\fR" 4 +.IX Item "file.sx" +.PD +Assembler code which must be preprocessed. +.IP "\fIother\fR" 4 +.IX Item "other" +An object file to be fed straight into linking. +Any file name with no recognized suffix is treated this way. +.PP +You can specify the input language explicitly with the \fB\-x\fR option: +.IP "\fB\-x\fR \fIlanguage\fR" 4 +.IX Item "-x language" +Specify explicitly the \fIlanguage\fR for the following input files +(rather than letting the compiler choose a default based on the file +name suffix). This option applies to all following input files until +the next \fB\-x\fR option. Possible values for \fIlanguage\fR are: +.Sp +.Vb 9 +\& c c\-header cpp\-output +\& c++ c++\-header c++\-cpp\-output +\& objective\-c objective\-c\-header objective\-c\-cpp\-output +\& objective\-c++ objective\-c++\-header objective\-c++\-cpp\-output +\& assembler assembler\-with\-cpp +\& ada +\& f77 f77\-cpp\-input f95 f95\-cpp\-input +\& go +\& java +.Ve +.IP "\fB\-x none\fR" 4 +.IX Item "-x none" +Turn off any specification of a language, so that subsequent files are +handled according to their file name suffixes (as they are if \fB\-x\fR +has not been used at all). +.IP "\fB\-pass\-exit\-codes\fR" 4 +.IX Item "-pass-exit-codes" +Normally the \fBgcc\fR program will exit with the code of 1 if any +phase of the compiler returns a non-success return code. If you specify +\&\fB\-pass\-exit\-codes\fR, the \fBgcc\fR program will instead return with +numerically highest error produced by any phase that returned an error +indication. The C, \*(C+, and Fortran frontends return 4, if an internal +compiler error is encountered. +.PP +If you only want some of the stages of compilation, you can use +\&\fB\-x\fR (or filename suffixes) to tell \fBgcc\fR where to start, and +one of the options \fB\-c\fR, \fB\-S\fR, or \fB\-E\fR to say where +\&\fBgcc\fR is to stop. Note that some combinations (for example, +\&\fB\-x cpp-output \-E\fR) instruct \fBgcc\fR to do nothing at all. +.IP "\fB\-c\fR" 4 +.IX Item "-c" +Compile or assemble the source files, but do not link. The linking +stage simply is not done. The ultimate output is in the form of an +object file for each source file. +.Sp +By default, the object file name for a source file is made by replacing +the suffix \fB.c\fR, \fB.i\fR, \fB.s\fR, etc., with \fB.o\fR. +.Sp +Unrecognized input files, not requiring compilation or assembly, are +ignored. +.IP "\fB\-S\fR" 4 +.IX Item "-S" +Stop after the stage of compilation proper; do not assemble. The output +is in the form of an assembler code file for each non-assembler input +file specified. +.Sp +By default, the assembler file name for a source file is made by +replacing the suffix \fB.c\fR, \fB.i\fR, etc., with \fB.s\fR. +.Sp +Input files that don't require compilation are ignored. +.IP "\fB\-E\fR" 4 +.IX Item "-E" +Stop after the preprocessing stage; do not run the compiler proper. The +output is in the form of preprocessed source code, which is sent to the +standard output. +.Sp +Input files which don't require preprocessing are ignored. +.IP "\fB\-o\fR \fIfile\fR" 4 +.IX Item "-o file" +Place output in file \fIfile\fR. This applies regardless to whatever +sort of output is being produced, whether it be an executable file, +an object file, an assembler file or preprocessed C code. +.Sp +If \fB\-o\fR is not specified, the default is to put an executable +file in \fIa.out\fR, the object file for +\&\fI\fIsource\fI.\fIsuffix\fI\fR in \fI\fIsource\fI.o\fR, its +assembler file in \fI\fIsource\fI.s\fR, a precompiled header file in +\&\fI\fIsource\fI.\fIsuffix\fI.gch\fR, and all preprocessed C source on +standard output. +.IP "\fB\-v\fR" 4 +.IX Item "-v" +Print (on standard error output) the commands executed to run the stages +of compilation. Also print the version number of the compiler driver +program and of the preprocessor and the compiler proper. +.IP "\fB\-###\fR" 4 +.IX Item "-###" +Like \fB\-v\fR except the commands are not executed and arguments +are quoted unless they contain only alphanumeric characters or \f(CW\*(C`./\-_\*(C'\fR. +This is useful for shell scripts to capture the driver-generated command lines. +.IP "\fB\-pipe\fR" 4 +.IX Item "-pipe" +Use pipes rather than temporary files for communication between the +various stages of compilation. This fails to work on some systems where +the assembler is unable to read from a pipe; but the \s-1GNU\s0 assembler has +no trouble. +.IP "\fB\-\-help\fR" 4 +.IX Item "--help" +Print (on the standard output) a description of the command line options +understood by \fBgcc\fR. If the \fB\-v\fR option is also specified +then \fB\-\-help\fR will also be passed on to the various processes +invoked by \fBgcc\fR, so that they can display the command line options +they accept. If the \fB\-Wextra\fR option has also been specified +(prior to the \fB\-\-help\fR option), then command line options which +have no documentation associated with them will also be displayed. +.IP "\fB\-\-target\-help\fR" 4 +.IX Item "--target-help" +Print (on the standard output) a description of target-specific command +line options for each tool. For some targets extra target-specific +information may also be printed. +.IP "\fB\-\-help={\fR\fIclass\fR|[\fB^\fR]\fIqualifier\fR\fB}\fR[\fB,...\fR]" 4 +.IX Item "--help={class|[^]qualifier}[,...]" +Print (on the standard output) a description of the command line +options understood by the compiler that fit into all specified classes +and qualifiers. These are the supported classes: +.RS 4 +.IP "\fBoptimizers\fR" 4 +.IX Item "optimizers" +This will display all of the optimization options supported by the +compiler. +.IP "\fBwarnings\fR" 4 +.IX Item "warnings" +This will display all of the options controlling warning messages +produced by the compiler. +.IP "\fBtarget\fR" 4 +.IX Item "target" +This will display target-specific options. Unlike the +\&\fB\-\-target\-help\fR option however, target-specific options of the +linker and assembler will not be displayed. This is because those +tools do not currently support the extended \fB\-\-help=\fR syntax. +.IP "\fBparams\fR" 4 +.IX Item "params" +This will display the values recognized by the \fB\-\-param\fR +option. +.IP "\fIlanguage\fR" 4 +.IX Item "language" +This will display the options supported for \fIlanguage\fR, where +\&\fIlanguage\fR is the name of one of the languages supported in this +version of \s-1GCC\s0. +.IP "\fBcommon\fR" 4 +.IX Item "common" +This will display the options that are common to all languages. +.RE +.RS 4 +.Sp +These are the supported qualifiers: +.IP "\fBundocumented\fR" 4 +.IX Item "undocumented" +Display only those options which are undocumented. +.IP "\fBjoined\fR" 4 +.IX Item "joined" +Display options which take an argument that appears after an equal +sign in the same continuous piece of text, such as: +\&\fB\-\-help=target\fR. +.IP "\fBseparate\fR" 4 +.IX Item "separate" +Display options which take an argument that appears as a separate word +following the original option, such as: \fB\-o output-file\fR. +.RE +.RS 4 +.Sp +Thus for example to display all the undocumented target-specific +switches supported by the compiler the following can be used: +.Sp +.Vb 1 +\& \-\-help=target,undocumented +.Ve +.Sp +The sense of a qualifier can be inverted by prefixing it with the +\&\fB^\fR character, so for example to display all binary warning +options (i.e., ones that are either on or off and that do not take an +argument), which have a description the following can be used: +.Sp +.Vb 1 +\& \-\-help=warnings,^joined,^undocumented +.Ve +.Sp +The argument to \fB\-\-help=\fR should not consist solely of inverted +qualifiers. +.Sp +Combining several classes is possible, although this usually +restricts the output by so much that there is nothing to display. One +case where it does work however is when one of the classes is +\&\fItarget\fR. So for example to display all the target-specific +optimization options the following can be used: +.Sp +.Vb 1 +\& \-\-help=target,optimizers +.Ve +.Sp +The \fB\-\-help=\fR option can be repeated on the command line. Each +successive use will display its requested class of options, skipping +those that have already been displayed. +.Sp +If the \fB\-Q\fR option appears on the command line before the +\&\fB\-\-help=\fR option, then the descriptive text displayed by +\&\fB\-\-help=\fR is changed. Instead of describing the displayed +options, an indication is given as to whether the option is enabled, +disabled or set to a specific value (assuming that the compiler +knows this at the point where the \fB\-\-help=\fR option is used). +.Sp +Here is a truncated example from the \s-1ARM\s0 port of \fBgcc\fR: +.Sp +.Vb 5 +\& % gcc \-Q \-mabi=2 \-\-help=target \-c +\& The following options are target specific: +\& \-mabi= 2 +\& \-mabort\-on\-noreturn [disabled] +\& \-mapcs [disabled] +.Ve +.Sp +The output is sensitive to the effects of previous command line +options, so for example it is possible to find out which optimizations +are enabled at \fB\-O2\fR by using: +.Sp +.Vb 1 +\& \-Q \-O2 \-\-help=optimizers +.Ve +.Sp +Alternatively you can discover which binary optimizations are enabled +by \fB\-O3\fR by using: +.Sp +.Vb 3 +\& gcc \-c \-Q \-O3 \-\-help=optimizers > /tmp/O3\-opts +\& gcc \-c \-Q \-O2 \-\-help=optimizers > /tmp/O2\-opts +\& diff /tmp/O2\-opts /tmp/O3\-opts | grep enabled +.Ve +.RE +.IP "\fB\-no\-canonical\-prefixes\fR" 4 +.IX Item "-no-canonical-prefixes" +Do not expand any symbolic links, resolve references to \fB/../\fR +or \fB/./\fR, or make the path absolute when generating a relative +prefix. +.IP "\fB\-\-version\fR" 4 +.IX Item "--version" +Display the version number and copyrights of the invoked \s-1GCC\s0. +.IP "\fB\-wrapper\fR" 4 +.IX Item "-wrapper" +Invoke all subcommands under a wrapper program. The name of the +wrapper program and its parameters are passed as a comma separated +list. +.Sp +.Vb 1 +\& gcc \-c t.c \-wrapper gdb,\-\-args +.Ve +.Sp +This will invoke all subprograms of \fBgcc\fR under +\&\fBgdb \-\-args\fR, thus the invocation of \fBcc1\fR will be +\&\fBgdb \-\-args cc1 ...\fR. +.IP "\fB\-fplugin=\fR\fIname\fR\fB.so\fR" 4 +.IX Item "-fplugin=name.so" +Load the plugin code in file \fIname\fR.so, assumed to be a +shared object to be dlopen'd by the compiler. The base name of +the shared object file is used to identify the plugin for the +purposes of argument parsing (See +\&\fB\-fplugin\-arg\-\fR\fIname\fR\fB\-\fR\fIkey\fR\fB=\fR\fIvalue\fR below). +Each plugin should define the callback functions specified in the +Plugins \s-1API\s0. +.IP "\fB\-fplugin\-arg\-\fR\fIname\fR\fB\-\fR\fIkey\fR\fB=\fR\fIvalue\fR" 4 +.IX Item "-fplugin-arg-name-key=value" +Define an argument called \fIkey\fR with a value of \fIvalue\fR +for the plugin called \fIname\fR. +.IP "\fB\-fdump\-ada\-spec\fR[\fB\-slim\fR]" 4 +.IX Item "-fdump-ada-spec[-slim]" +For C and \*(C+ source and include files, generate corresponding Ada +specs. +.IP "\fB\-fdump\-go\-spec=\fR\fIfile\fR" 4 +.IX Item "-fdump-go-spec=file" +For input files in any language, generate corresponding Go +declarations in \fIfile\fR. This generates Go \f(CW\*(C`const\*(C'\fR, +\&\f(CW\*(C`type\*(C'\fR, \f(CW\*(C`var\*(C'\fR, and \f(CW\*(C`func\*(C'\fR declarations which may be a +useful way to start writing a Go interface to code written in some +other language. +.IP "\fB@\fR\fIfile\fR" 4 +.IX Item "@file" +Read command-line options from \fIfile\fR. The options read are +inserted in place of the original @\fIfile\fR option. If \fIfile\fR +does not exist, or cannot be read, then the option will be treated +literally, and not removed. +.Sp +Options in \fIfile\fR are separated by whitespace. A whitespace +character may be included in an option by surrounding the entire +option in either single or double quotes. Any character (including a +backslash) may be included by prefixing the character to be included +with a backslash. The \fIfile\fR may itself contain additional +@\fIfile\fR options; any such options will be processed recursively. +.SS "Compiling \*(C+ Programs" +.IX Subsection "Compiling Programs" +\&\*(C+ source files conventionally use one of the suffixes \fB.C\fR, +\&\fB.cc\fR, \fB.cpp\fR, \fB.CPP\fR, \fB.c++\fR, \fB.cp\fR, or +\&\fB.cxx\fR; \*(C+ header files often use \fB.hh\fR, \fB.hpp\fR, +\&\fB.H\fR, or (for shared template code) \fB.tcc\fR; and +preprocessed \*(C+ files use the suffix \fB.ii\fR. \s-1GCC\s0 recognizes +files with these names and compiles them as \*(C+ programs even if you +call the compiler the same way as for compiling C programs (usually +with the name \fBgcc\fR). +.PP +However, the use of \fBgcc\fR does not add the \*(C+ library. +\&\fBg++\fR is a program that calls \s-1GCC\s0 and treats \fB.c\fR, +\&\fB.h\fR and \fB.i\fR files as \*(C+ source files instead of C source +files unless \fB\-x\fR is used, and automatically specifies linking +against the \*(C+ library. This program is also useful when +precompiling a C header file with a \fB.h\fR extension for use in \*(C+ +compilations. On many systems, \fBg++\fR is also installed with +the name \fBc++\fR. +.PP +When you compile \*(C+ programs, you may specify many of the same +command-line options that you use for compiling programs in any +language; or command-line options meaningful for C and related +languages; or options that are meaningful only for \*(C+ programs. +.SS "Options Controlling C Dialect" +.IX Subsection "Options Controlling C Dialect" +The following options control the dialect of C (or languages derived +from C, such as \*(C+, Objective-C and Objective\-\*(C+) that the compiler +accepts: +.IP "\fB\-ansi\fR" 4 +.IX Item "-ansi" +In C mode, this is equivalent to \fB\-std=c90\fR. In \*(C+ mode, it is +equivalent to \fB\-std=c++98\fR. +.Sp +This turns off certain features of \s-1GCC\s0 that are incompatible with \s-1ISO\s0 +C90 (when compiling C code), or of standard \*(C+ (when compiling \*(C+ code), +such as the \f(CW\*(C`asm\*(C'\fR and \f(CW\*(C`typeof\*(C'\fR keywords, and +predefined macros such as \f(CW\*(C`unix\*(C'\fR and \f(CW\*(C`vax\*(C'\fR that identify the +type of system you are using. It also enables the undesirable and +rarely used \s-1ISO\s0 trigraph feature. For the C compiler, +it disables recognition of \*(C+ style \fB//\fR comments as well as +the \f(CW\*(C`inline\*(C'\fR keyword. +.Sp +The alternate keywords \f(CW\*(C`_\|_asm_\|_\*(C'\fR, \f(CW\*(C`_\|_extension_\|_\*(C'\fR, +\&\f(CW\*(C`_\|_inline_\|_\*(C'\fR and \f(CW\*(C`_\|_typeof_\|_\*(C'\fR continue to work despite +\&\fB\-ansi\fR. You would not want to use them in an \s-1ISO\s0 C program, of +course, but it is useful to put them in header files that might be included +in compilations done with \fB\-ansi\fR. Alternate predefined macros +such as \f(CW\*(C`_\|_unix_\|_\*(C'\fR and \f(CW\*(C`_\|_vax_\|_\*(C'\fR are also available, with or +without \fB\-ansi\fR. +.Sp +The \fB\-ansi\fR option does not cause non-ISO programs to be +rejected gratuitously. For that, \fB\-pedantic\fR is required in +addition to \fB\-ansi\fR. +.Sp +The macro \f(CW\*(C`_\|_STRICT_ANSI_\|_\*(C'\fR is predefined when the \fB\-ansi\fR +option is used. Some header files may notice this macro and refrain +from declaring certain functions or defining certain macros that the +\&\s-1ISO\s0 standard doesn't call for; this is to avoid interfering with any +programs that might use these names for other things. +.Sp +Functions that would normally be built in but do not have semantics +defined by \s-1ISO\s0 C (such as \f(CW\*(C`alloca\*(C'\fR and \f(CW\*(C`ffs\*(C'\fR) are not built-in +functions when \fB\-ansi\fR is used. +.IP "\fB\-std=\fR" 4 +.IX Item "-std=" +Determine the language standard. This option +is currently only supported when compiling C or \*(C+. +.Sp +The compiler can accept several base standards, such as \fBc90\fR or +\&\fBc++98\fR, and \s-1GNU\s0 dialects of those standards, such as +\&\fBgnu90\fR or \fBgnu++98\fR. By specifying a base standard, the +compiler will accept all programs following that standard and those +using \s-1GNU\s0 extensions that do not contradict it. For example, +\&\fB\-std=c90\fR turns off certain features of \s-1GCC\s0 that are +incompatible with \s-1ISO\s0 C90, such as the \f(CW\*(C`asm\*(C'\fR and \f(CW\*(C`typeof\*(C'\fR +keywords, but not other \s-1GNU\s0 extensions that do not have a meaning in +\&\s-1ISO\s0 C90, such as omitting the middle term of a \f(CW\*(C`?:\*(C'\fR +expression. On the other hand, by specifying a \s-1GNU\s0 dialect of a +standard, all features the compiler support are enabled, even when +those features change the meaning of the base standard and some +strict-conforming programs may be rejected. The particular standard +is used by \fB\-pedantic\fR to identify which features are \s-1GNU\s0 +extensions given that version of the standard. For example +\&\fB\-std=gnu90 \-pedantic\fR would warn about \*(C+ style \fB//\fR +comments, while \fB\-std=gnu99 \-pedantic\fR would not. +.Sp +A value for this option must be provided; possible values are +.RS 4 +.IP "\fBc90\fR" 4 +.IX Item "c90" +.PD 0 +.IP "\fBc89\fR" 4 +.IX Item "c89" +.IP "\fBiso9899:1990\fR" 4 +.IX Item "iso9899:1990" +.PD +Support all \s-1ISO\s0 C90 programs (certain \s-1GNU\s0 extensions that conflict +with \s-1ISO\s0 C90 are disabled). Same as \fB\-ansi\fR for C code. +.IP "\fBiso9899:199409\fR" 4 +.IX Item "iso9899:199409" +\&\s-1ISO\s0 C90 as modified in amendment 1. +.IP "\fBc99\fR" 4 +.IX Item "c99" +.PD 0 +.IP "\fBc9x\fR" 4 +.IX Item "c9x" +.IP "\fBiso9899:1999\fR" 4 +.IX Item "iso9899:1999" +.IP "\fBiso9899:199x\fR" 4 +.IX Item "iso9899:199x" +.PD +\&\s-1ISO\s0 C99. Note that this standard is not yet fully supported; see +<\fBhttp://gcc.gnu.org/gcc\-4.6/c99status.html\fR> for more information. The +names \fBc9x\fR and \fBiso9899:199x\fR are deprecated. +.IP "\fBc1x\fR" 4 +.IX Item "c1x" +\&\s-1ISO\s0 C1X, the draft of the next revision of the \s-1ISO\s0 C standard. +Support is limited and experimental and features enabled by this +option may be changed or removed if changed in or removed from the +standard draft. +.IP "\fBgnu90\fR" 4 +.IX Item "gnu90" +.PD 0 +.IP "\fBgnu89\fR" 4 +.IX Item "gnu89" +.PD +\&\s-1GNU\s0 dialect of \s-1ISO\s0 C90 (including some C99 features). This +is the default for C code. +.IP "\fBgnu99\fR" 4 +.IX Item "gnu99" +.PD 0 +.IP "\fBgnu9x\fR" 4 +.IX Item "gnu9x" +.PD +\&\s-1GNU\s0 dialect of \s-1ISO\s0 C99. When \s-1ISO\s0 C99 is fully implemented in \s-1GCC\s0, +this will become the default. The name \fBgnu9x\fR is deprecated. +.IP "\fBgnu1x\fR" 4 +.IX Item "gnu1x" +\&\s-1GNU\s0 dialect of \s-1ISO\s0 C1X. Support is limited and experimental and +features enabled by this option may be changed or removed if changed +in or removed from the standard draft. +.IP "\fBc++98\fR" 4 +.IX Item "c++98" +The 1998 \s-1ISO\s0 \*(C+ standard plus amendments. Same as \fB\-ansi\fR for +\&\*(C+ code. +.IP "\fBgnu++98\fR" 4 +.IX Item "gnu++98" +\&\s-1GNU\s0 dialect of \fB\-std=c++98\fR. This is the default for +\&\*(C+ code. +.IP "\fBc++0x\fR" 4 +.IX Item "c++0x" +The working draft of the upcoming \s-1ISO\s0 \*(C+0x standard. This option +enables experimental features that are likely to be included in +\&\*(C+0x. The working draft is constantly changing, and any feature that is +enabled by this flag may be removed from future versions of \s-1GCC\s0 if it is +not part of the \*(C+0x standard. +.IP "\fBgnu++0x\fR" 4 +.IX Item "gnu++0x" +\&\s-1GNU\s0 dialect of \fB\-std=c++0x\fR. This option enables +experimental features that may be removed in future versions of \s-1GCC\s0. +.RE +.RS 4 +.RE +.IP "\fB\-fgnu89\-inline\fR" 4 +.IX Item "-fgnu89-inline" +The option \fB\-fgnu89\-inline\fR tells \s-1GCC\s0 to use the traditional +\&\s-1GNU\s0 semantics for \f(CW\*(C`inline\*(C'\fR functions when in C99 mode. + This option +is accepted and ignored by \s-1GCC\s0 versions 4.1.3 up to but not including +4.3. In \s-1GCC\s0 versions 4.3 and later it changes the behavior of \s-1GCC\s0 in +C99 mode. Using this option is roughly equivalent to adding the +\&\f(CW\*(C`gnu_inline\*(C'\fR function attribute to all inline functions. +.Sp +The option \fB\-fno\-gnu89\-inline\fR explicitly tells \s-1GCC\s0 to use the +C99 semantics for \f(CW\*(C`inline\*(C'\fR when in C99 or gnu99 mode (i.e., it +specifies the default behavior). This option was first supported in +\&\s-1GCC\s0 4.3. This option is not supported in \fB\-std=c90\fR or +\&\fB\-std=gnu90\fR mode. +.Sp +The preprocessor macros \f(CW\*(C`_\|_GNUC_GNU_INLINE_\|_\*(C'\fR and +\&\f(CW\*(C`_\|_GNUC_STDC_INLINE_\|_\*(C'\fR may be used to check which semantics are +in effect for \f(CW\*(C`inline\*(C'\fR functions. +.IP "\fB\-aux\-info\fR \fIfilename\fR" 4 +.IX Item "-aux-info filename" +Output to the given filename prototyped declarations for all functions +declared and/or defined in a translation unit, including those in header +files. This option is silently ignored in any language other than C. +.Sp +Besides declarations, the file indicates, in comments, the origin of +each declaration (source file and line), whether the declaration was +implicit, prototyped or unprototyped (\fBI\fR, \fBN\fR for new or +\&\fBO\fR for old, respectively, in the first character after the line +number and the colon), and whether it came from a declaration or a +definition (\fBC\fR or \fBF\fR, respectively, in the following +character). In the case of function definitions, a K&R\-style list of +arguments followed by their declarations is also provided, inside +comments, after the declaration. +.IP "\fB\-fno\-asm\fR" 4 +.IX Item "-fno-asm" +Do not recognize \f(CW\*(C`asm\*(C'\fR, \f(CW\*(C`inline\*(C'\fR or \f(CW\*(C`typeof\*(C'\fR as a +keyword, so that code can use these words as identifiers. You can use +the keywords \f(CW\*(C`_\|_asm_\|_\*(C'\fR, \f(CW\*(C`_\|_inline_\|_\*(C'\fR and \f(CW\*(C`_\|_typeof_\|_\*(C'\fR +instead. \fB\-ansi\fR implies \fB\-fno\-asm\fR. +.Sp +In \*(C+, this switch only affects the \f(CW\*(C`typeof\*(C'\fR keyword, since +\&\f(CW\*(C`asm\*(C'\fR and \f(CW\*(C`inline\*(C'\fR are standard keywords. You may want to +use the \fB\-fno\-gnu\-keywords\fR flag instead, which has the same +effect. In C99 mode (\fB\-std=c99\fR or \fB\-std=gnu99\fR), this +switch only affects the \f(CW\*(C`asm\*(C'\fR and \f(CW\*(C`typeof\*(C'\fR keywords, since +\&\f(CW\*(C`inline\*(C'\fR is a standard keyword in \s-1ISO\s0 C99. +.IP "\fB\-fno\-builtin\fR" 4 +.IX Item "-fno-builtin" +.PD 0 +.IP "\fB\-fno\-builtin\-\fR\fIfunction\fR" 4 +.IX Item "-fno-builtin-function" +.PD +Don't recognize built-in functions that do not begin with +\&\fB_\|_builtin_\fR as prefix. +.Sp +\&\s-1GCC\s0 normally generates special code to handle certain built-in functions +more efficiently; for instance, calls to \f(CW\*(C`alloca\*(C'\fR may become single +instructions that adjust the stack directly, and calls to \f(CW\*(C`memcpy\*(C'\fR +may become inline copy loops. The resulting code is often both smaller +and faster, but since the function calls no longer appear as such, you +cannot set a breakpoint on those calls, nor can you change the behavior +of the functions by linking with a different library. In addition, +when a function is recognized as a built-in function, \s-1GCC\s0 may use +information about that function to warn about problems with calls to +that function, or to generate more efficient code, even if the +resulting code still contains calls to that function. For example, +warnings are given with \fB\-Wformat\fR for bad calls to +\&\f(CW\*(C`printf\*(C'\fR, when \f(CW\*(C`printf\*(C'\fR is built in, and \f(CW\*(C`strlen\*(C'\fR is +known not to modify global memory. +.Sp +With the \fB\-fno\-builtin\-\fR\fIfunction\fR option +only the built-in function \fIfunction\fR is +disabled. \fIfunction\fR must not begin with \fB_\|_builtin_\fR. If a +function is named that is not built-in in this version of \s-1GCC\s0, this +option is ignored. There is no corresponding +\&\fB\-fbuiltin\-\fR\fIfunction\fR option; if you wish to enable +built-in functions selectively when using \fB\-fno\-builtin\fR or +\&\fB\-ffreestanding\fR, you may define macros such as: +.Sp +.Vb 2 +\& #define abs(n) _\|_builtin_abs ((n)) +\& #define strcpy(d, s) _\|_builtin_strcpy ((d), (s)) +.Ve +.IP "\fB\-fhosted\fR" 4 +.IX Item "-fhosted" +Assert that compilation takes place in a hosted environment. This implies +\&\fB\-fbuiltin\fR. A hosted environment is one in which the +entire standard library is available, and in which \f(CW\*(C`main\*(C'\fR has a return +type of \f(CW\*(C`int\*(C'\fR. Examples are nearly everything except a kernel. +This is equivalent to \fB\-fno\-freestanding\fR. +.IP "\fB\-ffreestanding\fR" 4 +.IX Item "-ffreestanding" +Assert that compilation takes place in a freestanding environment. This +implies \fB\-fno\-builtin\fR. A freestanding environment +is one in which the standard library may not exist, and program startup may +not necessarily be at \f(CW\*(C`main\*(C'\fR. The most obvious example is an \s-1OS\s0 kernel. +This is equivalent to \fB\-fno\-hosted\fR. +.IP "\fB\-fopenmp\fR" 4 +.IX Item "-fopenmp" +Enable handling of OpenMP directives \f(CW\*(C`#pragma omp\*(C'\fR in C/\*(C+ and +\&\f(CW\*(C`!$omp\*(C'\fR in Fortran. When \fB\-fopenmp\fR is specified, the +compiler generates parallel code according to the OpenMP Application +Program Interface v3.0 <\fBhttp://www.openmp.org/\fR>. This option +implies \fB\-pthread\fR, and thus is only supported on targets that +have support for \fB\-pthread\fR. +.IP "\fB\-fms\-extensions\fR" 4 +.IX Item "-fms-extensions" +Accept some non-standard constructs used in Microsoft header files. +.Sp +In \*(C+ code, this allows member names in structures to be similar +to previous types declarations. +.Sp +.Vb 4 +\& typedef int UOW; +\& struct ABC { +\& UOW UOW; +\& }; +.Ve +.Sp +Some cases of unnamed fields in structures and unions are only +accepted with this option. +.IP "\fB\-fplan9\-extensions\fR" 4 +.IX Item "-fplan9-extensions" +Accept some non-standard constructs used in Plan 9 code. +.Sp +This enables \fB\-fms\-extensions\fR, permits passing pointers to +structures with anonymous fields to functions which expect pointers to +elements of the type of the field, and permits referring to anonymous +fields declared using a typedef. This is only +supported for C, not \*(C+. +.IP "\fB\-trigraphs\fR" 4 +.IX Item "-trigraphs" +Support \s-1ISO\s0 C trigraphs. The \fB\-ansi\fR option (and \fB\-std\fR +options for strict \s-1ISO\s0 C conformance) implies \fB\-trigraphs\fR. +.IP "\fB\-no\-integrated\-cpp\fR" 4 +.IX Item "-no-integrated-cpp" +Performs a compilation in two passes: preprocessing and compiling. This +option allows a user supplied \*(L"cc1\*(R", \*(L"cc1plus\*(R", or \*(L"cc1obj\*(R" via the +\&\fB\-B\fR option. The user supplied compilation step can then add in +an additional preprocessing step after normal preprocessing but before +compiling. The default is to use the integrated cpp (internal cpp) +.Sp +The semantics of this option will change if \*(L"cc1\*(R", \*(L"cc1plus\*(R", and +\&\*(L"cc1obj\*(R" are merged. +.IP "\fB\-traditional\fR" 4 +.IX Item "-traditional" +.PD 0 +.IP "\fB\-traditional\-cpp\fR" 4 +.IX Item "-traditional-cpp" +.PD +Formerly, these options caused \s-1GCC\s0 to attempt to emulate a pre-standard +C compiler. They are now only supported with the \fB\-E\fR switch. +The preprocessor continues to support a pre-standard mode. See the \s-1GNU\s0 +\&\s-1CPP\s0 manual for details. +.IP "\fB\-fcond\-mismatch\fR" 4 +.IX Item "-fcond-mismatch" +Allow conditional expressions with mismatched types in the second and +third arguments. The value of such an expression is void. This option +is not supported for \*(C+. +.IP "\fB\-flax\-vector\-conversions\fR" 4 +.IX Item "-flax-vector-conversions" +Allow implicit conversions between vectors with differing numbers of +elements and/or incompatible element types. This option should not be +used for new code. +.IP "\fB\-funsigned\-char\fR" 4 +.IX Item "-funsigned-char" +Let the type \f(CW\*(C`char\*(C'\fR be unsigned, like \f(CW\*(C`unsigned char\*(C'\fR. +.Sp +Each kind of machine has a default for what \f(CW\*(C`char\*(C'\fR should +be. It is either like \f(CW\*(C`unsigned char\*(C'\fR by default or like +\&\f(CW\*(C`signed char\*(C'\fR by default. +.Sp +Ideally, a portable program should always use \f(CW\*(C`signed char\*(C'\fR or +\&\f(CW\*(C`unsigned char\*(C'\fR when it depends on the signedness of an object. +But many programs have been written to use plain \f(CW\*(C`char\*(C'\fR and +expect it to be signed, or expect it to be unsigned, depending on the +machines they were written for. This option, and its inverse, let you +make such a program work with the opposite default. +.Sp +The type \f(CW\*(C`char\*(C'\fR is always a distinct type from each of +\&\f(CW\*(C`signed char\*(C'\fR or \f(CW\*(C`unsigned char\*(C'\fR, even though its behavior +is always just like one of those two. +.IP "\fB\-fsigned\-char\fR" 4 +.IX Item "-fsigned-char" +Let the type \f(CW\*(C`char\*(C'\fR be signed, like \f(CW\*(C`signed char\*(C'\fR. +.Sp +Note that this is equivalent to \fB\-fno\-unsigned\-char\fR, which is +the negative form of \fB\-funsigned\-char\fR. Likewise, the option +\&\fB\-fno\-signed\-char\fR is equivalent to \fB\-funsigned\-char\fR. +.IP "\fB\-fsigned\-bitfields\fR" 4 +.IX Item "-fsigned-bitfields" +.PD 0 +.IP "\fB\-funsigned\-bitfields\fR" 4 +.IX Item "-funsigned-bitfields" +.IP "\fB\-fno\-signed\-bitfields\fR" 4 +.IX Item "-fno-signed-bitfields" +.IP "\fB\-fno\-unsigned\-bitfields\fR" 4 +.IX Item "-fno-unsigned-bitfields" +.PD +These options control whether a bit-field is signed or unsigned, when the +declaration does not use either \f(CW\*(C`signed\*(C'\fR or \f(CW\*(C`unsigned\*(C'\fR. By +default, such a bit-field is signed, because this is consistent: the +basic integer types such as \f(CW\*(C`int\*(C'\fR are signed types. +.SS "Options Controlling \*(C+ Dialect" +.IX Subsection "Options Controlling Dialect" +This section describes the command-line options that are only meaningful +for \*(C+ programs; but you can also use most of the \s-1GNU\s0 compiler options +regardless of what language your program is in. For example, you +might compile a file \f(CW\*(C`firstClass.C\*(C'\fR like this: +.PP +.Vb 1 +\& g++ \-g \-frepo \-O \-c firstClass.C +.Ve +.PP +In this example, only \fB\-frepo\fR is an option meant +only for \*(C+ programs; you can use the other options with any +language supported by \s-1GCC\s0. +.PP +Here is a list of options that are \fIonly\fR for compiling \*(C+ programs: +.IP "\fB\-fabi\-version=\fR\fIn\fR" 4 +.IX Item "-fabi-version=n" +Use version \fIn\fR of the \*(C+ \s-1ABI\s0. Version 2 is the version of the +\&\*(C+ \s-1ABI\s0 that first appeared in G++ 3.4. Version 1 is the version of +the \*(C+ \s-1ABI\s0 that first appeared in G++ 3.2. Version 0 will always be +the version that conforms most closely to the \*(C+ \s-1ABI\s0 specification. +Therefore, the \s-1ABI\s0 obtained using version 0 will change as \s-1ABI\s0 bugs +are fixed. +.Sp +The default is version 2. +.Sp +Version 3 corrects an error in mangling a constant address as a +template argument. +.Sp +Version 4 implements a standard mangling for vector types. +.Sp +Version 5 corrects the mangling of attribute const/volatile on +function pointer types, decltype of a plain decl, and use of a +function parameter in the declaration of another parameter. +.Sp +See also \fB\-Wabi\fR. +.IP "\fB\-fno\-access\-control\fR" 4 +.IX Item "-fno-access-control" +Turn off all access checking. This switch is mainly useful for working +around bugs in the access control code. +.IP "\fB\-fcheck\-new\fR" 4 +.IX Item "-fcheck-new" +Check that the pointer returned by \f(CW\*(C`operator new\*(C'\fR is non-null +before attempting to modify the storage allocated. This check is +normally unnecessary because the \*(C+ standard specifies that +\&\f(CW\*(C`operator new\*(C'\fR will only return \f(CW0\fR if it is declared +\&\fB\f(BIthrow()\fB\fR, in which case the compiler will always check the +return value even without this option. In all other cases, when +\&\f(CW\*(C`operator new\*(C'\fR has a non-empty exception specification, memory +exhaustion is signalled by throwing \f(CW\*(C`std::bad_alloc\*(C'\fR. See also +\&\fBnew (nothrow)\fR. +.IP "\fB\-fconserve\-space\fR" 4 +.IX Item "-fconserve-space" +Put uninitialized or runtime-initialized global variables into the +common segment, as C does. This saves space in the executable at the +cost of not diagnosing duplicate definitions. If you compile with this +flag and your program mysteriously crashes after \f(CW\*(C`main()\*(C'\fR has +completed, you may have an object that is being destroyed twice because +two definitions were merged. +.Sp +This option is no longer useful on most targets, now that support has +been added for putting variables into \s-1BSS\s0 without making them common. +.IP "\fB\-fconstexpr\-depth=\fR\fIn\fR" 4 +.IX Item "-fconstexpr-depth=n" +Set the maximum nested evaluation depth for \*(C+0x constexpr functions +to \fIn\fR. A limit is needed to detect endless recursion during +constant expression evaluation. The minimum specified by the standard +is 512. +.IP "\fB\-fno\-deduce\-init\-list\fR" 4 +.IX Item "-fno-deduce-init-list" +Disable deduction of a template type parameter as +std::initializer_list from a brace-enclosed initializer list, i.e. +.Sp +.Vb 4 +\& template auto forward(T t) \-> decltype (realfn (t)) +\& { +\& return realfn (t); +\& } +\& +\& void f() +\& { +\& forward({1,2}); // call forward> +\& } +.Ve +.Sp +This option is present because this deduction is an extension to the +current specification in the \*(C+0x working draft, and there was +some concern about potential overload resolution problems. +.IP "\fB\-ffriend\-injection\fR" 4 +.IX Item "-ffriend-injection" +Inject friend functions into the enclosing namespace, so that they are +visible outside the scope of the class in which they are declared. +Friend functions were documented to work this way in the old Annotated +\&\*(C+ Reference Manual, and versions of G++ before 4.1 always worked +that way. However, in \s-1ISO\s0 \*(C+ a friend function which is not declared +in an enclosing scope can only be found using argument dependent +lookup. This option causes friends to be injected as they were in +earlier releases. +.Sp +This option is for compatibility, and may be removed in a future +release of G++. +.IP "\fB\-fno\-elide\-constructors\fR" 4 +.IX Item "-fno-elide-constructors" +The \*(C+ standard allows an implementation to omit creating a temporary +which is only used to initialize another object of the same type. +Specifying this option disables that optimization, and forces G++ to +call the copy constructor in all cases. +.IP "\fB\-fno\-enforce\-eh\-specs\fR" 4 +.IX Item "-fno-enforce-eh-specs" +Don't generate code to check for violation of exception specifications +at runtime. This option violates the \*(C+ standard, but may be useful +for reducing code size in production builds, much like defining +\&\fB\s-1NDEBUG\s0\fR. This does not give user code permission to throw +exceptions in violation of the exception specifications; the compiler +will still optimize based on the specifications, so throwing an +unexpected exception will result in undefined behavior. +.IP "\fB\-ffor\-scope\fR" 4 +.IX Item "-ffor-scope" +.PD 0 +.IP "\fB\-fno\-for\-scope\fR" 4 +.IX Item "-fno-for-scope" +.PD +If \fB\-ffor\-scope\fR is specified, the scope of variables declared in +a \fIfor-init-statement\fR is limited to the \fBfor\fR loop itself, +as specified by the \*(C+ standard. +If \fB\-fno\-for\-scope\fR is specified, the scope of variables declared in +a \fIfor-init-statement\fR extends to the end of the enclosing scope, +as was the case in old versions of G++, and other (traditional) +implementations of \*(C+. +.Sp +The default if neither flag is given to follow the standard, +but to allow and give a warning for old-style code that would +otherwise be invalid, or have different behavior. +.IP "\fB\-fno\-gnu\-keywords\fR" 4 +.IX Item "-fno-gnu-keywords" +Do not recognize \f(CW\*(C`typeof\*(C'\fR as a keyword, so that code can use this +word as an identifier. You can use the keyword \f(CW\*(C`_\|_typeof_\|_\*(C'\fR instead. +\&\fB\-ansi\fR implies \fB\-fno\-gnu\-keywords\fR. +.IP "\fB\-fno\-implicit\-templates\fR" 4 +.IX Item "-fno-implicit-templates" +Never emit code for non-inline templates which are instantiated +implicitly (i.e. by use); only emit code for explicit instantiations. +.IP "\fB\-fno\-implicit\-inline\-templates\fR" 4 +.IX Item "-fno-implicit-inline-templates" +Don't emit code for implicit instantiations of inline templates, either. +The default is to handle inlines differently so that compiles with and +without optimization will need the same set of explicit instantiations. +.IP "\fB\-fno\-implement\-inlines\fR" 4 +.IX Item "-fno-implement-inlines" +To save space, do not emit out-of-line copies of inline functions +controlled by \fB#pragma implementation\fR. This will cause linker +errors if these functions are not inlined everywhere they are called. +.IP "\fB\-fms\-extensions\fR" 4 +.IX Item "-fms-extensions" +Disable pedantic warnings about constructs used in \s-1MFC\s0, such as implicit +int and getting a pointer to member function via non-standard syntax. +.IP "\fB\-fno\-nonansi\-builtins\fR" 4 +.IX Item "-fno-nonansi-builtins" +Disable built-in declarations of functions that are not mandated by +\&\s-1ANSI/ISO\s0 C. These include \f(CW\*(C`ffs\*(C'\fR, \f(CW\*(C`alloca\*(C'\fR, \f(CW\*(C`_exit\*(C'\fR, +\&\f(CW\*(C`index\*(C'\fR, \f(CW\*(C`bzero\*(C'\fR, \f(CW\*(C`conjf\*(C'\fR, and other related functions. +.IP "\fB\-fnothrow\-opt\fR" 4 +.IX Item "-fnothrow-opt" +Treat a \f(CW\*(C`throw()\*(C'\fR exception specification as though it were a +\&\f(CW\*(C`noexcept\*(C'\fR specification to reduce or eliminate the text size +overhead relative to a function with no exception specification. If +the function has local variables of types with non-trivial +destructors, the exception specification will actually make the +function smaller because the \s-1EH\s0 cleanups for those variables can be +optimized away. The semantic effect is that an exception thrown out of +a function with such an exception specification will result in a call +to \f(CW\*(C`terminate\*(C'\fR rather than \f(CW\*(C`unexpected\*(C'\fR. +.IP "\fB\-fno\-operator\-names\fR" 4 +.IX Item "-fno-operator-names" +Do not treat the operator name keywords \f(CW\*(C`and\*(C'\fR, \f(CW\*(C`bitand\*(C'\fR, +\&\f(CW\*(C`bitor\*(C'\fR, \f(CW\*(C`compl\*(C'\fR, \f(CW\*(C`not\*(C'\fR, \f(CW\*(C`or\*(C'\fR and \f(CW\*(C`xor\*(C'\fR as +synonyms as keywords. +.IP "\fB\-fno\-optional\-diags\fR" 4 +.IX Item "-fno-optional-diags" +Disable diagnostics that the standard says a compiler does not need to +issue. Currently, the only such diagnostic issued by G++ is the one for +a name having multiple meanings within a class. +.IP "\fB\-fpermissive\fR" 4 +.IX Item "-fpermissive" +Downgrade some diagnostics about nonconformant code from errors to +warnings. Thus, using \fB\-fpermissive\fR will allow some +nonconforming code to compile. +.IP "\fB\-fno\-pretty\-templates\fR" 4 +.IX Item "-fno-pretty-templates" +When an error message refers to a specialization of a function +template, the compiler will normally print the signature of the +template followed by the template arguments and any typedefs or +typenames in the signature (e.g. \f(CW\*(C`void f(T) [with T = int]\*(C'\fR +rather than \f(CW\*(C`void f(int)\*(C'\fR) so that it's clear which template is +involved. When an error message refers to a specialization of a class +template, the compiler will omit any template arguments which match +the default template arguments for that template. If either of these +behaviors make it harder to understand the error message rather than +easier, using \fB\-fno\-pretty\-templates\fR will disable them. +.IP "\fB\-frepo\fR" 4 +.IX Item "-frepo" +Enable automatic template instantiation at link time. This option also +implies \fB\-fno\-implicit\-templates\fR. +.IP "\fB\-fno\-rtti\fR" 4 +.IX Item "-fno-rtti" +Disable generation of information about every class with virtual +functions for use by the \*(C+ runtime type identification features +(\fBdynamic_cast\fR and \fBtypeid\fR). If you don't use those parts +of the language, you can save some space by using this flag. Note that +exception handling uses the same information, but it will generate it as +needed. The \fBdynamic_cast\fR operator can still be used for casts that +do not require runtime type information, i.e. casts to \f(CW\*(C`void *\*(C'\fR or to +unambiguous base classes. +.IP "\fB\-fstats\fR" 4 +.IX Item "-fstats" +Emit statistics about front-end processing at the end of the compilation. +This information is generally only useful to the G++ development team. +.IP "\fB\-fstrict\-enums\fR" 4 +.IX Item "-fstrict-enums" +Allow the compiler to optimize using the assumption that a value of +enumeration type can only be one of the values of the enumeration (as +defined in the \*(C+ standard; basically, a value which can be +represented in the minimum number of bits needed to represent all the +enumerators). This assumption may not be valid if the program uses a +cast to convert an arbitrary integer value to the enumeration type. +.IP "\fB\-ftemplate\-depth=\fR\fIn\fR" 4 +.IX Item "-ftemplate-depth=n" +Set the maximum instantiation depth for template classes to \fIn\fR. +A limit on the template instantiation depth is needed to detect +endless recursions during template class instantiation. \s-1ANSI/ISO\s0 \*(C+ +conforming programs must not rely on a maximum depth greater than 17 +(changed to 1024 in \*(C+0x). +.IP "\fB\-fno\-threadsafe\-statics\fR" 4 +.IX Item "-fno-threadsafe-statics" +Do not emit the extra code to use the routines specified in the \*(C+ +\&\s-1ABI\s0 for thread-safe initialization of local statics. You can use this +option to reduce code size slightly in code that doesn't need to be +thread-safe. +.IP "\fB\-fuse\-cxa\-atexit\fR" 4 +.IX Item "-fuse-cxa-atexit" +Register destructors for objects with static storage duration with the +\&\f(CW\*(C`_\|_cxa_atexit\*(C'\fR function rather than the \f(CW\*(C`atexit\*(C'\fR function. +This option is required for fully standards-compliant handling of static +destructors, but will only work if your C library supports +\&\f(CW\*(C`_\|_cxa_atexit\*(C'\fR. +.IP "\fB\-fno\-use\-cxa\-get\-exception\-ptr\fR" 4 +.IX Item "-fno-use-cxa-get-exception-ptr" +Don't use the \f(CW\*(C`_\|_cxa_get_exception_ptr\*(C'\fR runtime routine. This +will cause \f(CW\*(C`std::uncaught_exception\*(C'\fR to be incorrect, but is necessary +if the runtime routine is not available. +.IP "\fB\-fvisibility\-inlines\-hidden\fR" 4 +.IX Item "-fvisibility-inlines-hidden" +This switch declares that the user does not attempt to compare +pointers to inline methods where the addresses of the two functions +were taken in different shared objects. +.Sp +The effect of this is that \s-1GCC\s0 may, effectively, mark inline methods with +\&\f(CW\*(C`_\|_attribute_\|_ ((visibility ("hidden")))\*(C'\fR so that they do not +appear in the export table of a \s-1DSO\s0 and do not require a \s-1PLT\s0 indirection +when used within the \s-1DSO\s0. Enabling this option can have a dramatic effect +on load and link times of a \s-1DSO\s0 as it massively reduces the size of the +dynamic export table when the library makes heavy use of templates. +.Sp +The behavior of this switch is not quite the same as marking the +methods as hidden directly, because it does not affect static variables +local to the function or cause the compiler to deduce that +the function is defined in only one shared object. +.Sp +You may mark a method as having a visibility explicitly to negate the +effect of the switch for that method. For example, if you do want to +compare pointers to a particular inline method, you might mark it as +having default visibility. Marking the enclosing class with explicit +visibility will have no effect. +.Sp +Explicitly instantiated inline methods are unaffected by this option +as their linkage might otherwise cross a shared library boundary. +.IP "\fB\-fvisibility\-ms\-compat\fR" 4 +.IX Item "-fvisibility-ms-compat" +This flag attempts to use visibility settings to make \s-1GCC\s0's \*(C+ +linkage model compatible with that of Microsoft Visual Studio. +.Sp +The flag makes these changes to \s-1GCC\s0's linkage model: +.RS 4 +.IP "1." 4 +It sets the default visibility to \f(CW\*(C`hidden\*(C'\fR, like +\&\fB\-fvisibility=hidden\fR. +.IP "2." 4 +Types, but not their members, are not hidden by default. +.IP "3." 4 +The One Definition Rule is relaxed for types without explicit +visibility specifications which are defined in more than one different +shared object: those declarations are permitted if they would have +been permitted when this option was not used. +.RE +.RS 4 +.Sp +In new code it is better to use \fB\-fvisibility=hidden\fR and +export those classes which are intended to be externally visible. +Unfortunately it is possible for code to rely, perhaps accidentally, +on the Visual Studio behavior. +.Sp +Among the consequences of these changes are that static data members +of the same type with the same name but defined in different shared +objects will be different, so changing one will not change the other; +and that pointers to function members defined in different shared +objects may not compare equal. When this flag is given, it is a +violation of the \s-1ODR\s0 to define types with the same name differently. +.RE +.IP "\fB\-fno\-weak\fR" 4 +.IX Item "-fno-weak" +Do not use weak symbol support, even if it is provided by the linker. +By default, G++ will use weak symbols if they are available. This +option exists only for testing, and should not be used by end-users; +it will result in inferior code and has no benefits. This option may +be removed in a future release of G++. +.IP "\fB\-nostdinc++\fR" 4 +.IX Item "-nostdinc++" +Do not search for header files in the standard directories specific to +\&\*(C+, but do still search the other standard directories. (This option +is used when building the \*(C+ library.) +.PP +In addition, these optimization, warning, and code generation options +have meanings only for \*(C+ programs: +.IP "\fB\-fno\-default\-inline\fR" 4 +.IX Item "-fno-default-inline" +Do not assume \fBinline\fR for functions defined inside a class scope. + Note that these +functions will have linkage like inline functions; they just won't be +inlined by default. +.IP "\fB\-Wabi\fR (C, Objective-C, \*(C+ and Objective\-\*(C+ only)" 4 +.IX Item "-Wabi (C, Objective-C, and Objective- only)" +Warn when G++ generates code that is probably not compatible with the +vendor-neutral \*(C+ \s-1ABI\s0. Although an effort has been made to warn about +all such cases, there are probably some cases that are not warned about, +even though G++ is generating incompatible code. There may also be +cases where warnings are emitted even though the code that is generated +will be compatible. +.Sp +You should rewrite your code to avoid these warnings if you are +concerned about the fact that code generated by G++ may not be binary +compatible with code generated by other compilers. +.Sp +The known incompatibilities in \fB\-fabi\-version=2\fR (the default) include: +.RS 4 +.IP "\(bu" 4 +A template with a non-type template parameter of reference type is +mangled incorrectly: +.Sp +.Vb 3 +\& extern int N; +\& template struct S {}; +\& void n (S) {2} +.Ve +.Sp +This is fixed in \fB\-fabi\-version=3\fR. +.IP "\(bu" 4 +\&\s-1SIMD\s0 vector types declared using \f(CW\*(C`_\|_attribute ((vector_size))\*(C'\fR are +mangled in a non-standard way that does not allow for overloading of +functions taking vectors of different sizes. +.Sp +The mangling is changed in \fB\-fabi\-version=4\fR. +.RE +.RS 4 +.Sp +The known incompatibilities in \fB\-fabi\-version=1\fR include: +.IP "\(bu" 4 +Incorrect handling of tail-padding for bit-fields. G++ may attempt to +pack data into the same byte as a base class. For example: +.Sp +.Vb 2 +\& struct A { virtual void f(); int f1 : 1; }; +\& struct B : public A { int f2 : 1; }; +.Ve +.Sp +In this case, G++ will place \f(CW\*(C`B::f2\*(C'\fR into the same byte +as\f(CW\*(C`A::f1\*(C'\fR; other compilers will not. You can avoid this problem +by explicitly padding \f(CW\*(C`A\*(C'\fR so that its size is a multiple of the +byte size on your platform; that will cause G++ and other compilers to +layout \f(CW\*(C`B\*(C'\fR identically. +.IP "\(bu" 4 +Incorrect handling of tail-padding for virtual bases. G++ does not use +tail padding when laying out virtual bases. For example: +.Sp +.Vb 3 +\& struct A { virtual void f(); char c1; }; +\& struct B { B(); char c2; }; +\& struct C : public A, public virtual B {}; +.Ve +.Sp +In this case, G++ will not place \f(CW\*(C`B\*(C'\fR into the tail-padding for +\&\f(CW\*(C`A\*(C'\fR; other compilers will. You can avoid this problem by +explicitly padding \f(CW\*(C`A\*(C'\fR so that its size is a multiple of its +alignment (ignoring virtual base classes); that will cause G++ and other +compilers to layout \f(CW\*(C`C\*(C'\fR identically. +.IP "\(bu" 4 +Incorrect handling of bit-fields with declared widths greater than that +of their underlying types, when the bit-fields appear in a union. For +example: +.Sp +.Vb 1 +\& union U { int i : 4096; }; +.Ve +.Sp +Assuming that an \f(CW\*(C`int\*(C'\fR does not have 4096 bits, G++ will make the +union too small by the number of bits in an \f(CW\*(C`int\*(C'\fR. +.IP "\(bu" 4 +Empty classes can be placed at incorrect offsets. For example: +.Sp +.Vb 1 +\& struct A {}; +\& +\& struct B { +\& A a; +\& virtual void f (); +\& }; +\& +\& struct C : public B, public A {}; +.Ve +.Sp +G++ will place the \f(CW\*(C`A\*(C'\fR base class of \f(CW\*(C`C\*(C'\fR at a nonzero offset; +it should be placed at offset zero. G++ mistakenly believes that the +\&\f(CW\*(C`A\*(C'\fR data member of \f(CW\*(C`B\*(C'\fR is already at offset zero. +.IP "\(bu" 4 +Names of template functions whose types involve \f(CW\*(C`typename\*(C'\fR or +template template parameters can be mangled incorrectly. +.Sp +.Vb 2 +\& template +\& void f(typename Q::X) {} +\& +\& template