include/gcc-cp-fe.def

   1 /* Interface between GCC C++ FE and GDB  -*- c -*-
   2
   3    Copyright (C) 2014-2018 Free Software Foundation, Inc.
   4
   5    This file is part of GCC.
   6
   7    This program is free software; you can redistribute it and/or modify
   8    it under the terms of the GNU General Public License as published by
   9    the Free Software Foundation; either version 3 of the License, or
  10    (at your option) any later version.
  11
  12    This program is distributed in the hope that it will be useful,
  13    but WITHOUT ANY WARRANTY; without even the implied warranty of
  14    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15    GNU General Public License for more details.
  16
  17    You should have received a copy of the GNU General Public License
  18    along with this program.  If not, see <http://www.gnu.org/licenses/>.  */
  19
  20
  21
  22 /* Push namespace NAME as the current binding level, to which
  23    newly-introduced decls will be bound.  An empty string identifies
  24    the global namespace, whereas NULL identifies an anonymous
  25    namespace.  A namespace named NAME is created in the current scope,
  26    if needed.
  27
  28    If the newly-created namespace is to be an inline namespace, see
  29    make_namespace_inline.  */
  30
  31 GCC_METHOD1 (int /* bool */, push_namespace,
  32              const char *)            /* Argument NAME.  */
  33
  34 /* Push TYPE as the current binding level, making its members visible
  35    for name lookup.  The current scope before the call must be the
  36    scope in which the class was declared.  This should be used if the
  37    definition of a class is already finished, but one wishes to define
  38    a nested class, or to enter the scope of one of its member
  39    functions.  */
  40
  41 GCC_METHOD1 (int /* bool */, push_class,
  42              gcc_type)          /* Argument TYPE.  */
  43
  44 /* Push FUNCTION_DECL as the current (empty) binding level (see
  45    reactivate_decl).  The current enclosing scope before the call must
  46    be the scope in which the function was declared.  */
  47
  48 GCC_METHOD1 (int /* bool */, push_function,
  49              gcc_decl)       /* Argument FUNCTION_DECL.  */
  50
  51 /* Make DECL visible (again?) within SCOPE.  When SCOPE is NULL, it
  52    means the current scope; if it is not NULL, it must name a function
  53    that is currently active, even if not at the top of the binding
  54    chain.
  55
  56    This function can be used to make e.g. a global function or
  57    variable visible in a namespace or local scope (overriding another
  58    enclosing definition of the same name), but its most common
  59    expected use of this primitive, that gives it its name, is to make
  60    declarations visible again after reentering a function scope,
  61    because when a function is entered with push_function, that does
  62    NOT make any of the declarations nested in it visible for name
  63    lookup.
  64
  65    There is a reason/excuse for that: unlike namespaces and classes,
  66    G++ doesn't ever have to reenter function scopes, so its name
  67    resolution infrastructure is not prepared to do that.  But wait,
  68    there is also a good use for this apparent limitation: a function
  69    may contain multiple scopes (blocks), and the name may be bound to
  70    different symbols in each of these scopes.  With this interface, as
  71    we reenter a function scope, we may choose which symbols to make
  72    visible for the code snippet, or, if there could be template
  73    functions in local scopes, for unresolved names in nested template
  74    class default arguments, or in nested template function signatures.
  75
  76    As for making a local declaration visible for the code snippet,
  77    there are two possibilities: a) introduce it upfront, while
  78    entering the scope for the user expression (see the enter_scope
  79    callback, called by g++ when encountering the push_user_expression
  80    pragma), which might save some scope switching and reactivate_decl
  81    (though this can't be helped if some declarations have to be
  82    introduced and discarded, because of multiple definitions of the
  83    same name in different scopes within a function: they have to be
  84    defined in discriminator order); or b) introduce it when its name
  85    is looked up, entering the scope, introducing the declaration,
  86    leaving the scope, and then reactivating the declaration in its
  87    local scope.
  88
  89    Here's some more detail on how reactivate_decl works.  Say there's
  90    a function foo whose body looks like this:
  91
  92    {
  93      {
  94 // point 1
  95        class c {} o __attribute__ ((__used__)); // c  , o
  96      }
  97      struct c {
  98        void f() {
  99 // point 2
 100        }
 101      } o __attribute__ ((__used__));            // c_0, o_0
 102      {
 103        class c {} p __attribute__ ((__used__)); // c_1, p
 104 // point 3
 105        o.f();
 106      }
 107    }
 108
 109    When we are about to define class c at point 1, we enter the
 110    function foo scope, and since no symbols are visible at point 1, we
 111    proceed to declare class c.  We may then define the class right
 112    away, or, if we leave the function scope, and we later wish to
 113    define it, or to define object o, we can reenter the scope and just
 114    use the previously-obtained gcc_decl to define the class, without
 115    having to reactivate the declaration.
 116
 117    Now, if we are to set up the binding context for point 2, we have
 118    to define c_0::f, and in order to do so, we have to declare and
 119    define c_0.  Before we can declare c_0, we MUST at least declare c.
 120
 121      As a general rule, before we can declare or define any local name
 122      with a discriminator, we have to at least declare any other
 123      occurrences of the same name in the same enclosing entity with
 124      lower or absent discriminator.
 125
 126    So, we declare c, then we leave the function scope and reenter it
 127    so as to declare c_0 (also with name "c", which is why we have to
 128    leave and reenter the function scope, otherwise we would get an
 129    error because of the duplicate definition; g++ will assign a
 130    discriminator because it still remembers there was an earlier
 131    declaration of c_0 within the function, it's just no longer in
 132    scope), then we can define c_0, including its member function f.
 133
 134    Likewise, if we wish to define o_0, we have to define o first.  If
 135    we wish to declare (and maybe then define) c_1, we have to at least
 136    declare (c and then) c_0 first.
 137
 138    Then, as we set up the binding context to compile a code snippet at
 139    point 3, we may choose to activate c_1, o_0 and p upfront,
 140    declaring and discarding c, c_0 and o, and then reentering the
 141    funciton scope to declare c_1, o_0 and p; or we can wait for oracle
 142    lookups of c, o or p.  If c is looked up, and the debugger resolves
 143    c in the scope to c_1, it is expected to enter the function scope
 144    from the top level, declare c, leave it, reenter it, declare c_0,
 145    leave it, reenter it, declare c_1, leave it, and then reactivate
 146    c_1 in the function scope.  If c_1 is needed as a complete type,
 147    the definition may be given right after the declaration, or the
 148    scope will have to be reentered in order to define the class.
 149
 150 .  If the code snippet is at point 2, we don't need to (re)activate
 151    any declaration: nothing from any local scope is visible.  Just
 152    entering the scope of the class containing member function f
 153    reactivates the names of its members, including the class name
 154    itself.  */
 155
 156 GCC_METHOD2 (int /* bool */, reactivate_decl,
 157              gcc_decl,          /* Argument DECL.  */
 158              gcc_decl)          /* Argument SCOPE.  */
 159
 160 /* Pop the namespace last entered with push_namespace, or class last
 161    entered with push_class, or function last entered with
 162    push_function, restoring the binding level in effect before the
 163    matching push_* call.  */
 164
 165 GCC_METHOD0 (int /* bool */, pop_binding_level)
 166
 167 /* Return the NAMESPACE_DECL, TYPE_DECL or FUNCTION_DECL of the
 168    binding level that would be popped by pop_scope.  */
 169
 170 GCC_METHOD0 (gcc_decl, get_current_binding_level_decl)
 171
 172 /* Make the current binding level an inline namespace.  It must be a
 173    namespace to begin with.  It is safe to call this more than once
 174    for the same namespace, but after the first call, subsequent ones
 175    will not return a success status.  */
 176
 177 GCC_METHOD0 (int /* bool */, make_namespace_inline)
 178
 179 /* Add USED_NS to the namespaces used by the current binding level.
 180    Use get_current_binding_level_decl to obtain USED_NS's
 181    gcc_decl.  */
 182
 183 GCC_METHOD1 (int /* bool */, add_using_namespace,
 184              gcc_decl)                  /* Argument USED_NS.  */
 185
 186 /* Introduce a namespace alias declaration, as in:
 187
 188    namespace foo = [... ::] bar;
 189
 190    After this call, namespace TARGET will be visible as ALIAS within
 191    the current namespace.  Get the declaration for TARGET by calling
 192    get_current_binding_level_decl after pushing into it.  */
 193
 194 GCC_METHOD2 (int /* bool */, add_namespace_alias,
 195              const char *,              /* Argument ALIAS.  */
 196              gcc_decl)                  /* Argument TARGET.  */
 197
 198 /* Introduce a using declaration, as in:
 199
 200    using foo::bar;
 201
 202    The TARGET decl names the qualifying scope (foo:: above) and the
 203    identifier (bar), but that does not mean that only TARGET will be
 204    brought into the current scope: all bindings of TARGET's identifier
 205    in the qualifying scope will be brought in.
 206
 207    FLAGS should specify GCC_CP_SYMBOL_USING.  If the current scope is
 208    a class scope, visibility flags must be supplied.
 209
 210    Even when TARGET is template dependent, we don't need to specify
 211    whether or not it is a typename: the supplied declaration (that
 212    could be a template-dependent type converted to declaration by
 213    get_type_decl) indicates so.  */
 214
 215 GCC_METHOD2 (int /* bool */, add_using_decl,
 216              enum gcc_cp_symbol_kind, /* Argument FLAGS.  */
 217              gcc_decl)                /* Argument TARGET.  */
 218
 219 /* Create a new "decl" in GCC, and bind it in the current binding
 220    level.  A decl is a declaration, basically a kind of symbol.
 221
 222    NAME is the name of the new symbol.  SYM_KIND is the kind of
 223    symbol being requested.  SYM_TYPE is the new symbol's C++ type;
 224    except for labels, where this is not meaningful and should be
 225    zero.  If SUBSTITUTION_NAME is not NULL, then a reference to this
 226    decl in the source will later be substituted with a dereference
 227    of a variable of the given name.  Otherwise, for symbols having
 228    an address (e.g., functions), ADDRESS is the address.  FILENAME
 229    and LINE_NUMBER refer to the symbol's source location.  If this
 230    is not known, FILENAME can be NULL and LINE_NUMBER can be 0.
 231    This function returns the new decl.
 232
 233    Use this function to register typedefs, functions and variables to
 234    namespace and local binding levels, and typedefs, member functions
 235    (static or not), and static data members to class binding levels.
 236    Class members must have their access controls specified with
 237    GCC_CP_ACCESS_* flags in SYM_KIND.
 238
 239    Note that, since access controls are disabled, we have no means to
 240    express private, protected and public.
 241
 242    There are various flags that can be set in SYM_KIND to specify
 243    additional semantics.  Look for GCC_CP_FLAGs in the definition of
 244    enum gcc_cp_symbol_kind in gcc-cp-interface.h.
 245
 246    In order to define member functions, pass GCC_CP_SYMBOL_FUNCTION in
 247    SYM_KIND, and a function_type for static member functions or a
 248    method type for non-static member functions, including constructors
 249    and destructors.  Use build_function_type to create a function
 250    type; for a method type, start by creating a function type without
 251    any compiler-introduced artificial arguments (the implicit this
 252    pointer, and the __in_chrg added to constructors and destructors,
 253    and __vtt_parm added to the former), and then use build_method_type
 254    to create the method type out of the class type and the function
 255    type.
 256
 257    For operator functions, set GCC_CP_FLAG_SPECIAL_FUNCTION in
 258    SYM_KIND, in addition to any other applicable flags, and pass as
 259    NAME a string starting with the two-character mangling for operator
 260    name: "ps" for unary plus, "mL" for multiply and assign, *=; etc.
 261    Use "cv" for type converstion operators (the target type portion
 262    may be omitted, as it is taken from the return type in SYM_TYPE).
 263    For operator"", use "li" followed by the identifier (the mangled
 264    name mandates digits specifying the length of the identifier; if
 265    present, they determine the end of the identifier, otherwise, the
 266    identifier extents to the end of the string, so that "li3_Kme" and
 267    "li_Km" are equivalent).
 268
 269    Constructors and destructors need special care, because for each
 270    constructor and destructor there may be multiple clones defined
 271    internally by the compiler.  With build_decl, you can introduce the
 272    base declaration of a constructor or a destructor, setting
 273    GCC_CP_FLAG_SPECIAL_FUNCTION the flag and using names starting with
 274    capital "C" or "D", respectively, followed by a digit (see below),
 275    a blank, or NUL ('\0').  DO NOT supply an ADDRESS or a
 276    SUBSTITUTION_NAME to build_decl, it would be meaningless (and
 277    rejected) for the base declaration; use define_cdtor_clone to
 278    introduce the address of each clone.  For constructor templates,
 279    declare the template with build_decl, and then, for each
 280    specialization, introduce it with
 281    build_function_template_specialization, and then define the
 282    addresses of each of its clones with define_cdtor_clone.
 283
 284    NAMEs for GCC_CP_FLAG_SPECIAL_FUNCTION:
 285
 286      NAME    meaning
 287      C?      constructor base declaration (? may be 1, 2, 4, blank or NUL)
 288      D?      destructor base declaration (? may be 0, 1, 2, 4, blank or NUL)
 289      nw      operator new
 290      na      operator new[]
 291      dl      operator delete
 292      da      operator delete[]
 293      ps      operator + (unary)
 294      ng      operator - (unary)
 295      ad      operator & (unary)
 296      de      operator * (unary)
 297      co      operator ~
 298      pl      operator +
 299      mi      operator -
 300      ml      operator *
 301      dv      operator /
 302      rm      operator %
 303      an      operator &
 304      or      operator |
 305      eo      operator ^
 306      aS      operator =
 307      pL      operator +=
 308      mI      operator -=
 309      mL      operator *=
 310      dV      operator /=
 311      rM      operator %=
 312      aN      operator &=
 313      oR      operator |=
 314      eO      operator ^=
 315      ls      operator <<
 316      rs      operator >>
 317      lS      operator <<=
 318      rS      operator >>=
 319      eq      operator ==
 320      ne      operator !=
 321      lt      operator <
 322      gt      operator >
 323      le      operator <=
 324      ge      operator >=
 325      nt      operator !
 326      aa      operator &&
 327      oo      operator ||
 328      pp      operator ++
 329      mm      operator --
 330      cm      operator ,
 331      pm      operator ->*
 332      pt      operator ->
 333      cl      operator ()
 334      ix      operator []
 335      qu      operator ?
 336      cv      operator <T> (conversion operator)
 337      li<id>  operator "" <id>
 338
 339    FIXME: How about attributes?  */
 340
 341 GCC_METHOD7 (gcc_decl, build_decl,
 342              const char *,            /* Argument NAME.  */
 343              enum gcc_cp_symbol_kind, /* Argument SYM_KIND.  */
 344              gcc_type,                /* Argument SYM_TYPE.  */
 345              const char *,            /* Argument SUBSTITUTION_NAME.  */
 346              gcc_address,             /* Argument ADDRESS.  */
 347              const char *,            /* Argument FILENAME.  */
 348              unsigned int)            /* Argument LINE_NUMBER.  */
 349
 350 /* Supply the ADDRESS of one of the multiple clones of constructor or
 351    destructor CDTOR.  The clone is specified by NAME, using the
 352    following name mangling conventions:
 353
 354      C1      in-charge constructor
 355      C2      not-in-charge constructor
 356      C4      unified constructor
 357      D0      deleting destructor
 358      D1      in-charge destructor
 359      D2      not-in-charge destructor
 360      D4      unified destructor
 361
 362    The following information is not necessary to use the API.
 363
 364    C1 initializes an instance of the class (rather than of derived
 365    classes), including virtual base classes, whereas C2 initializes a
 366    sub-object (of the given class type) of an instance of some derived
 367    class (or a full object that doesn't have any virtual base
 368    classes).
 369
 370    D0 and D1 destruct an instance of the class, including virtual base
 371    classes, but only the former calls operator delete to release the
 372    object's storage at the end; D2 destructs a sub-object (of the
 373    given class type) of an instance of a derived class (or a full
 374    object that doesn't have any virtual base classes).
 375
 376    The [CD]4 manglings (and symbol definitions) are non-standard, but
 377    GCC uses them in some cases: rather than assuming they are
 378    in-charge or not-in-charge, they test the implicit argument that
 379    the others ignore to tell how to behave.  These are used instead of
 380    cloning when we just can't use aliases.  */
 381
 382 GCC_METHOD3 (gcc_decl, define_cdtor_clone,
 383              const char *,            /* Argument NAME.  */
 384              gcc_decl,                /* Argument CDTOR.  */
 385              gcc_address)             /* Argument ADDRESS.  */
 386
 387 /* Return the type associated with the given declaration.  This is
 388    most useful to obtain the type associated with a forward-declared
 389    class, because it is the gcc_type, rather than the gcc_decl, that
 390    has to be used to build other types, but build_decl returns a
 391    gcc_decl rather than a gcc_type.  This call can in theory be used
 392    to obtain the type from any other declaration; it is supposed to
 393    return the same type that was supplied when the declaration was
 394    created.  */
 395
 396 GCC_METHOD1 (gcc_type, get_decl_type,
 397              gcc_decl)            /* Argument DECL.  */
 398
 399 /* Return the declaration for a type.  */
 400
 401 GCC_METHOD1 (gcc_decl, get_type_decl,
 402              gcc_type)            /* Argument TYPE.  */
 403
 404 /* Declare DECL as a friend of the current class scope, if TYPE is
 405    NULL, or of TYPE itself otherwise.  DECL may be a function or a
 406    class, be they template generics, template specializations or not
 407    templates.  TYPE must be a class type (not a template generic).
 408
 409    The add_friend call cannot introduce a declaration; even if the
 410    friend is first declared as a friend in the source code, the
 411    declaration belongs in the enclosing namespace, so it must be
 412    introduced in that namespace, and the resulting declaration can
 413    then be made a friend.
 414
 415    DECL cannot, however, be a member of a template class generic,
 416    because we have no means to introduce their declarations.  This
 417    interface has no notion of definitions for template generics.  As a
 418    consequence, users of this interface must introduce each friend
 419    template member specialization separately, i.e., instead of:
 420
 421      template <typename T> friend struct X<T>::M;
 422
 423    they must be declared as if they were:
 424
 425      friend struct X<onetype>::M;
 426      friend struct X<anothertype>::M;
 427      ... for each specialization of X.
 428
 429
 430    Specializations of a template can have each others' members as
 431    friends:
 432
 433      template <typename T> class foo {
 434        int f();
 435        template <typename U> friend int foo<U>::f();
 436      };
 437
 438    It wouldn't always be possible to define all specializations of a
 439    template class before introducing the friend declarations in their
 440    expanded, per-specialization form.
 441
 442    In order to simplify such friend declarations, and to enable
 443    incremental friend declarations as template specializations are
 444    introduced, add_friend can be called after the befriending class is
 445    fully defined, passing it a non-NULL TYPE argument naming the
 446    befriending class type.  */
 447
 448 GCC_METHOD2 (int /* bool */, add_friend,
 449              gcc_decl,                /* Argument DECL.  */
 450              gcc_type)                /* Argument TYPE.  */
 451
 452 /* Return the type of a pointer to a given base type.  */
 453
 454 GCC_METHOD1 (gcc_type, build_pointer_type,
 455              gcc_type)                  /* Argument BASE_TYPE.  */
 456
 457 /* Return the type of a reference to a given base type.  */
 458
 459 GCC_METHOD2 (gcc_type, build_reference_type,
 460              gcc_type,                  /* Argument BASE_TYPE.  */
 461              enum gcc_cp_ref_qualifiers)   /* Argument RQUALS.  */
 462
 463 /* Create a new pointer-to-member type.  MEMBER_TYPE is the data
 464    member type, while CLASS_TYPE is the class type containing the data
 465    member.  For pointers to member functions, MEMBER_TYPE must be a
 466    method type, and CLASS_TYPE must be specified even though it might
 467    be possible to extract it from the method type.  */
 468
 469 GCC_METHOD2 (gcc_type, build_pointer_to_member_type,
 470              gcc_type,                     /* Argument CLASS_TYPE.  */
 471              gcc_type)                     /* Argument MEMBER_TYPE.  */
 472
 473 /* Start a template parameter list scope and enters it, so that
 474    subsequent build_type_template_parameter and
 475    build_value_template_parameter calls create template parameters in
 476    the list.  The list is closed by a build_decl call with
 477    GCC_CP_SYMBOL_FUNCTION or GCC_CP_SYMBOL_CLASS, that, when the scope
 478    is a template parameter list, declares a template function or a
 479    template class with the then-closed parameter list.  The scope in
 480    which the new declaration is to be introduced by build_decl must be
 481    entered before calling start_template_decl, and build_decl returns
 482    to that scope, from the template parameter list scope, before
 483    introducing the declaration.  */
 484
 485 GCC_METHOD0 (int /* bool */, start_template_decl)
 486
 487 /* Build a typename template-parameter (e.g., the T in template
 488    <typename T = X>).  Either PACK_P should be nonzero, to indicate an
 489    argument pack (the last argument in a variadic template argument
 490    list, as in template <typename... T>), or DEFAULT_TYPE may be
 491    non-NULL to set the default type argument (e.g. X) for the template
 492    parameter.  FILENAME and LINE_NUMBER may specify the source
 493    location in which the template parameter was declared.  */
 494
 495 GCC_METHOD5 (gcc_type, build_type_template_parameter,
 496              const char *,                            /* Argument ID.  */
 497              int /* bool */,                      /* Argument PACK_P.  */
 498              gcc_type,                      /* Argument DEFAULT_TYPE.  */
 499              const char *,                      /* Argument FILENAME.  */
 500              unsigned int)                   /* Argument LINE_NUMBER.  */
 501
 502 /* Build a template template-parameter (e.g., the T in template
 503    <template <[...]> class T = X>).  DEFAULT_TEMPL may be non-NULL to
 504    set the default type-template argument (e.g. X) for the template
 505    template parameter.  FILENAME and LINE_NUMBER may specify the
 506    source location in which the template parameter was declared.  */
 507
 508 GCC_METHOD5 (gcc_utempl, build_template_template_parameter,
 509              const char *,                            /* Argument ID.  */
 510              int /* bool */,                      /* Argument PACK_P.  */
 511              gcc_utempl,                   /* Argument DEFAULT_TEMPL.  */
 512              const char *,                      /* Argument FILENAME.  */
 513              unsigned int)                   /* Argument LINE_NUMBER.  */
 514
 515 /* Build a value template-parameter (e.g., the V in template <typename
 516    T, T V> or in template <int V = X>).  DEFAULT_VALUE may be non-NULL
 517    to set the default value argument for the template parameter (e.g.,
 518    X).  FILENAME and LINE_NUMBER may specify the source location in
 519    which the template parameter was declared.  */
 520
 521 GCC_METHOD5 (gcc_decl, build_value_template_parameter,
 522              gcc_type,                              /* Argument TYPE.  */
 523              const char *,                            /* Argument ID.  */
 524              gcc_expr,                     /* Argument DEFAULT_VALUE.  */
 525              const char *,                      /* Argument FILENAME.  */
 526              unsigned int)                   /* Argument LINE_NUMBER.  */
 527
 528 /* Build a template-dependent typename (e.g., typename T::bar or
 529    typename T::template bart<X>).  ENCLOSING_TYPE should be the
 530    template-dependent nested name specifier (e.g., T), ID should be
 531    the name of the member of the ENCLOSING_TYPE (e.g., bar or bart),
 532    and TARGS should be non-NULL and specify the template arguments
 533    (e.g. <X>) iff ID is to name a class template.
 534
 535    In this and other calls, a template-dependent nested name specifier
 536    may be a template class parameter (build_type_template_parameter),
 537    a specialization (returned by build_dependent_type_template_id) of
 538    a template template parameter (returned by
 539    build_template_template_parameter) or a member type thereof
 540    (returned by build_dependent_typename itself).  */
 541
 542 GCC_METHOD3 (gcc_type, build_dependent_typename,
 543              gcc_type,                    /* Argument ENCLOSING_TYPE.  */
 544              const char *,                            /* Argument ID.  */
 545              const struct gcc_cp_template_args *)  /* Argument TARGS.  */
 546
 547 /* Build a template-dependent class template (e.g., T::template bart).
 548    ENCLOSING_TYPE should be the template-dependent nested name
 549    specifier (e.g., T), ID should be the name of the class template
 550    member of the ENCLOSING_TYPE (e.g., bart).  */
 551
 552 GCC_METHOD2 (gcc_utempl, build_dependent_class_template,
 553              gcc_type,                    /* Argument ENCLOSING_TYPE.  */
 554              const char *)                            /* Argument ID.  */
 555
 556 /* Build a template-dependent type template-id (e.g., T<A>).
 557    TEMPLATE_DECL should be a template template parameter (e.g., the T
 558    in template <template <[...]> class T = X>), and TARGS should
 559    specify the template arguments (e.g. <A>).  */
 560
 561 GCC_METHOD2 (gcc_type, build_dependent_type_template_id,
 562              gcc_utempl,                   /* Argument TEMPLATE_DECL.  */
 563              const struct gcc_cp_template_args *)  /* Argument TARGS.  */
 564
 565 /* Build a template-dependent expression (e.g., S::val or S::template
 566    mtf<X>, or unqualified f or template tf<X>).
 567
 568    ENCLOSING_SCOPE should be a template-dependent nested name
 569    specifier (e.g., T), a resolved namespace or class decl, or NULL
 570    for unqualified names; ID should be the name of the member of the
 571    ENCLOSING_SCOPE (e.g., val or mtf) or unqualified overloaded
 572    function; and TARGS should list template arguments (e.g. <X>) when
 573    mtf or tf are to name a template function, or be NULL otherwise.
 574
 575    Unqualified names and namespace- or class-qualified names can only
 576    resolve to overloaded functions, to be used in contexts that
 577    involve overload resolution that cannot be resolved because of
 578    template-dependent argument or return types, such as call
 579    expressions with template-dependent arguments, conversion
 580    expressions to function types with template-dependent argument
 581    types or the like.  Other cases of unqualified or
 582    non-template-dependent-qualified names should NOT use this
 583    function, and use decl_expr to convert the appropriate function or
 584    object declaration to an expression.
 585
 586    If ID is the name of a special member function, FLAGS should be
 587    GCC_CP_SYMBOL_FUNCTION|GCC_CP_FLAG_SPECIAL_FUNCTION, and ID should
 588    be one of the encodings for special member functions documented in
 589    build_decl.  Otherwise, FLAGS should be GCC_CP_SYMBOL_MASK, which
 590    suggests the symbol kind is not known (though we know it is not a
 591    type).
 592
 593    If ID denotes a conversion operator, CONV_TYPE should name the
 594    target type of the conversion.  Otherwise, CONV_TYPE must be
 595    NULL.  */
 596
 597 GCC_METHOD5 (gcc_expr, build_dependent_expr,
 598              gcc_decl,                   /* Argument ENCLOSING_SCOPE.  */
 599              enum gcc_cp_symbol_kind,              /* Argument FLAGS.  */
 600              const char *,                          /* Argument NAME.  */
 601              gcc_type,                         /* Argument CONV_TYPE.  */
 602              const struct gcc_cp_template_args *)  /* Argument TARGS.  */
 603
 604 /* Build a gcc_expr for the value VALUE in type TYPE.  */
 605
 606 GCC_METHOD2 (gcc_expr, build_literal_expr,
 607              gcc_type,            /* Argument TYPE.  */
 608              unsigned long)       /* Argument VALUE.  */
 609
 610 /* Build a gcc_expr that denotes DECL, the declaration of a variable
 611    or function in namespace scope, or of a static member variable or
 612    function.  Use QUALIFIED_P to build the operand of unary & so as to
 613    compute a pointer-to-member, rather than a regular pointer.  */
 614
 615 GCC_METHOD2 (gcc_expr, build_decl_expr,
 616              gcc_decl,                  /* Argument DECL.  */
 617              int /* bool */)            /* Argument QUALIFIED_P.  */
 618
 619 /* Build a gcc_expr that denotes the unary operation UNARY_OP applied
 620    to the gcc_expr OPERAND.  For non-expr operands, see
 621    unary_type_expr.  Besides the UNARY_OP encodings used for operator
 622    names, we support "pp_" for preincrement, and "mm_" for
 623    predecrement, "nx" for noexcept, "tw" for throw, "tr" for rethrow
 624    (pass NULL as the operand), "te" for typeid, "sz" for sizeof, "az"
 625    for alignof, "dl" for delete, "gsdl" for ::delete, "da" for
 626    delete[], "gsda" for ::delete[], "sp" for pack expansion, "sZ" for
 627    sizeof...(function argument pack).  */
 628
 629 GCC_METHOD2 (gcc_expr, build_unary_expr,
 630              const char *,        /* Argument UNARY_OP.  */
 631              gcc_expr)            /* Argument OPERAND.  */
 632
 633 /* Build a gcc_expr that denotes the binary operation BINARY_OP
 634    applied to gcc_exprs OPERAND1 and OPERAND2.  Besides the BINARY_OP
 635    encodings used for operator names, we support "ds" for the operator
 636    token ".*" and "dt" for the operator token ".".  When using
 637    operators that take a name as their second operand ("." and "->")
 638    use decl_expr to convert the gcc_decl of the member name to a
 639    gcc_expr, if the member name wasn't created with
 640    e.g. build_dependent_expr.  */
 641
 642 GCC_METHOD3 (gcc_expr, build_binary_expr,
 643              const char *,        /* Argument BINARY_OP.  */
 644              gcc_expr,            /* Argument OPERAND1.  */
 645              gcc_expr)            /* Argument OPERAND2.  */
 646
 647 /* Build a gcc_expr that denotes the ternary operation TERNARY_OP
 648    applied to gcc_exprs OPERAND1, OPERAND2 and OPERAND3.  The only
 649    supported TERNARY_OP is "qu", for the "?:" operator.  */
 650
 651 GCC_METHOD4 (gcc_expr, build_ternary_expr,
 652              const char *,        /* Argument TERNARY_OP.  */
 653              gcc_expr,            /* Argument OPERAND1.  */
 654              gcc_expr,            /* Argument OPERAND2.  */
 655              gcc_expr)            /* Argument OPERAND3.  */
 656
 657 /* Build a gcc_expr that denotes the unary operation UNARY_OP applied
 658    to the gcc_type OPERAND.  Supported unary operations taking types
 659    are "ti" for typeid, "st" for sizeof, "at" for alignof, and "sZ"
 660    for sizeof...(template argument pack).  */
 661
 662 GCC_METHOD2 (gcc_expr, build_unary_type_expr,
 663              const char *,        /* Argument UNARY_OP.  */
 664              gcc_type)            /* Argument OPERAND.  */
 665
 666 /* Build a gcc_expr that denotes the binary operation BINARY_OP
 667    applied to gcc_type OPERAND1 and gcc_expr OPERAND2.  Use this for
 668    all kinds of (single-argument) type casts ("dc", "sc", "cc", "rc"
 669    for dynamic, static, const and reinterpret casts, respectively;
 670    "cv" for functional or C-style casts).  */
 671
 672 GCC_METHOD3 (gcc_expr, build_cast_expr,
 673              const char *,        /* Argument BINARY_OP.  */
 674              gcc_type,            /* Argument OPERAND1.  */
 675              gcc_expr)            /* Argument OPERAND2.  */
 676
 677 /* Build a gcc_expr that denotes the conversion of an expression list
 678    VALUES to TYPE, with ("tl") or without ("cv") braces, or a braced
 679    initializer list of unspecified type (e.g., a component of another
 680    braced initializer list; pass "il" for CONV_OP, and NULL for
 681    TYPE).  */
 682
 683 GCC_METHOD3 (gcc_expr, build_expression_list_expr,
 684              const char *,                       /* Argument CONV_OP.  */
 685              gcc_type,                              /* Argument TYPE.  */
 686              const struct gcc_cp_function_args *) /* Argument VALUES.  */
 687
 688 /* Build a gcc_expr that denotes a new ("nw") or new[] ("na")
 689    expression of TYPE, with or without a GLOBAL_NS qualifier (prefix
 690    the NEW_OP with "gs"), with or without PLACEMENT, with or without
 691    INITIALIZER.  If it's not a placement new, PLACEMENT must be NULL
 692    (rather than a zero-length placement arg list).  If there's no
 693    specified initializer, INITIALIZER must be NULL; a zero-length arg
 694    list stands for a default initializer.  */
 695
 696 GCC_METHOD4 (gcc_expr, build_new_expr,
 697              const char *,                             /* Argument NEW_OP.  */
 698              const struct gcc_cp_function_args *,   /* Argument PLACEMENT.  */
 699              gcc_type,                                   /* Argument TYPE.  */
 700              const struct gcc_cp_function_args *) /* Argument INITIALIZER.  */
 701
 702 /* Return a call expression that calls CALLABLE with arguments ARGS.
 703    CALLABLE may be a function, a callable object, a pointer to
 704    function, an unresolved expression, an unresolved overload set, an
 705    object expression combined with a member function overload set or a
 706    pointer-to-member.  If QUALIFIED_P, CALLABLE will be interpreted as
 707    a qualified name, preventing virtual function dispatch.  */
 708
 709 GCC_METHOD3 (gcc_expr, build_call_expr,
 710              gcc_expr,                        /* Argument CALLABLE.  */
 711              int /* bool */,               /* Argument QUALIFIED_P.  */
 712              const struct gcc_cp_function_args *) /* Argument ARGS.  */
 713
 714 /* Return the type of the gcc_expr OPERAND.
 715    Use this for decltype.
 716    For decltype (auto), pass a NULL OPERAND.
 717
 718    Note: for template-dependent expressions, the result is NULL,
 719    because the type is only computed when template argument
 720    substitution is performed.  */
 721
 722 GCC_METHOD1 (gcc_type, get_expr_type,
 723              gcc_expr)            /* Argument OPERAND.  */
 724
 725 /* Introduce a specialization of a template function.
 726
 727    TEMPLATE_DECL is the template function, and TARGS are the arguments
 728    for the specialization.  ADDRESS is the address of the
 729    specialization.  FILENAME and LINE_NUMBER specify the source
 730    location associated with the template function specialization.  */
 731
 732 GCC_METHOD5 (gcc_decl, build_function_template_specialization,
 733              gcc_decl,                     /* Argument TEMPLATE_DECL.  */
 734              const struct gcc_cp_template_args *,  /* Argument TARGS.  */
 735              gcc_address,                        /* Argument ADDRESS.  */
 736              const char *,            /* Argument FILENAME.  */
 737              unsigned int)            /* Argument LINE_NUMBER.  */
 738
 739 /* Specialize a template class as an incomplete type.  A definition
 740    can be supplied later, with start_class_type.
 741
 742    TEMPLATE_DECL is the template class, and TARGS are the arguments
 743    for the specialization.  FILENAME and LINE_NUMBER specify the
 744    source location associated with the template class
 745    specialization.  */
 746
 747 GCC_METHOD4 (gcc_decl, build_class_template_specialization,
 748              gcc_decl,                     /* Argument TEMPLATE_DECL.  */
 749              const struct gcc_cp_template_args *,  /* Argument TARGS.  */
 750              const char *,            /* Argument FILENAME.  */
 751              unsigned int)            /* Argument LINE_NUMBER.  */
 752
 753 /* Start defining a 'class', 'struct' or 'union' type, entering its
 754    own binding level.  Initially it has no fields.
 755
 756    TYPEDECL is the forward-declaration of the type, returned by
 757    build_decl.  BASE_CLASSES indicate the base classes of class NAME.
 758    FILENAME and LINE_NUMBER specify the source location associated
 759    with the class definition, should they be different from those of
 760    the forward declaration.  */
 761
 762 GCC_METHOD4 (gcc_type, start_class_type,
 763              gcc_decl,                /* Argument TYPEDECL.  */
 764              const struct gcc_vbase_array *,/* Argument BASE_CLASSES.  */
 765              const char *,            /* Argument FILENAME.  */
 766              unsigned int)            /* Argument LINE_NUMBER.  */
 767
 768 /* Create a new closure class type, record it as the
 769    DISCRIMINATOR-numbered closure type in the current scope (or
 770    associated with EXTRA_SCOPE, if non-NULL), and enter the closure
 771    type's own binding level.  This primitive would sort of combine
 772    build_decl and start_class_type, if they could be used to introduce
 773    a closure type.  Initially it has no fields.
 774
 775    FILENAME and LINE_NUMBER specify the source location associated
 776    with the class.  EXTRA_SCOPE, if non-NULL, must be a PARM_DECL of
 777    the current function, or a FIELD_DECL of the current class.  If it
 778    is NULL, the current scope must be a function.  */
 779
 780 GCC_METHOD5 (gcc_type, start_closure_class_type,
 781              int,                     /* Argument DISCRIMINATOR.  */
 782              gcc_decl,                /* Argument EXTRA_SCOPE.  */
 783              enum gcc_cp_symbol_kind, /* Argument FLAGS.  */
 784              const char *,            /* Argument FILENAME.  */
 785              unsigned int)            /* Argument LINE_NUMBER.  */
 786
 787 /* Add a non-static data member to the most-recently-started
 788    unfinished struct or union type.  FIELD_NAME is the field's name.
 789    FIELD_TYPE is the type of the field.  BITSIZE and BITPOS indicate
 790    where in the struct the field occurs.  */
 791
 792 GCC_METHOD5 (gcc_decl, build_field,
 793              const char *,                 /* Argument FIELD_NAME.  */
 794              gcc_type,                     /* Argument FIELD_TYPE.  */
 795              enum gcc_cp_symbol_kind,      /* Argument FIELD_FLAGS.  */
 796              unsigned long,                /* Argument BITSIZE.  */
 797              unsigned long)                /* Argument BITPOS.  */
 798
 799 /* After all the fields have been added to a struct, class or union,
 800    the struct or union type must be "finished".  This does some final
 801    cleanups in GCC, and pops to the binding level that was in effect
 802    before the matching start_class_type or
 803    start_closure_class_type.  */
 804
 805 GCC_METHOD1 (int /* bool */, finish_class_type,
 806              unsigned long)                /* Argument SIZE_IN_BYTES.  */
 807
 808 /* Create a new 'enum' type, and record it in the current binding
 809    level.  The new type initially has no associated constants.
 810
 811    NAME is the enum name.  FILENAME and LINE_NUMBER specify its source
 812    location.  */
 813
 814 GCC_METHOD5 (gcc_type, start_enum_type,
 815              const char *,            /* Argument NAME.  */
 816              gcc_type,                /* Argument UNDERLYING_INT_TYPE. */
 817              enum gcc_cp_symbol_kind, /* Argument FLAGS.  */
 818              const char *,            /* Argument FILENAME.  */
 819              unsigned int)            /* Argument LINE_NUMBER.  */
 820
 821 /* Add a new constant to an enum type.  NAME is the constant's name
 822    and VALUE is its value.  Returns a gcc_decl for the constant.  */
 823
 824 GCC_METHOD3 (gcc_decl, build_enum_constant,
 825              gcc_type,                 /* Argument ENUM_TYPE.  */
 826              const char *,             /* Argument NAME.  */
 827              unsigned long)            /* Argument VALUE.  */
 828
 829 /* After all the constants have been added to an enum, the type must
 830    be "finished".  This does some final cleanups in GCC.  */
 831
 832 GCC_METHOD1 (int /* bool */, finish_enum_type,
 833              gcc_type)                 /* Argument ENUM_TYPE.  */
 834
 835 /* Create a new function type.  RETURN_TYPE is the type returned by
 836    the function, and ARGUMENT_TYPES is a vector, of length NARGS, of
 837    the argument types.  IS_VARARGS is true if the function is
 838    varargs.  */
 839
 840 GCC_METHOD3 (gcc_type, build_function_type,
 841              gcc_type,                     /* Argument RETURN_TYPE.  */
 842              const struct gcc_type_array *,/* Argument ARGUMENT_TYPES.  */
 843              int /* bool */)               /* Argument IS_VARARGS.  */
 844
 845 /* Create a variant of a function type with an exception
 846    specification.  FUNCTION_TYPE is a function or method type.
 847    EXCEPT_TYPES is an array with the list of exception types.  Zero as
 848    the array length implies throw() AKA noexcept(true); NULL as the
 849    pointer to gcc_type_array implies noexcept(false), which is almost
 850    equivalent (but distinguishable by the compiler) to an unspecified
 851    exception list.  */
 852
 853 GCC_METHOD2 (gcc_type, build_exception_spec_variant,
 854              gcc_type,                     /* Argument FUNCTION_TYPE.  */
 855              const struct gcc_type_array *)/* Argument EXCEPT_TYPES.  */
 856
 857 /* Create a new non-static member function type.  FUNC_TYPE is the
 858    method prototype, without the implicit THIS pointer, added as a
 859    pointer to the QUALS-qualified CLASS_TYPE.  If CLASS_TYPE is NULL,
 860    this creates a cv-qualified (member) function type not associated
 861    with any specific class, as needed to support "typedef void f(int)
 862    const;", which can later be used to declare member functions and
 863    pointers to member functions.  */
 864
 865 GCC_METHOD4 (gcc_type, build_method_type,
 866              gcc_type,                     /* Argument CLASS_TYPE.  */
 867              gcc_type,                     /* Argument FUNC_TYPE.  */
 868              enum gcc_cp_qualifiers,       /* Argument QUALS.  */
 869              enum gcc_cp_ref_qualifiers)   /* Argument RQUALS.  */
 870
 871 /* Return a declaration for the (INDEX - 1)th argument of
 872    FUNCTION_DECL, i.e., for the first argument, use zero as the index.
 873    If FUNCTION_DECL is a non-static member function, use -1 to get the
 874    implicit THIS parameter.  */
 875
 876 GCC_METHOD2 (gcc_decl, get_function_parameter_decl,
 877              gcc_decl,                       /* Argument FUNCTION_DECL.  */
 878              int)                                    /* Argument INDEX.  */
 879
 880 /* Return a lambda expr that constructs an instance of CLOSURE_TYPE.
 881    Only lambda exprs without any captures can be correctly created
 882    through these mechanisms; that's all we need to support lambdas
 883    expressions in default parameters, the only kind that may have to
 884    be introduced through this interface.  */
 885
 886 GCC_METHOD1 (gcc_expr, build_lambda_expr,
 887              gcc_type)                        /* Argument CLOSURE_TYPE.  */
 888
 889 /* Return an integer type with the given properties.  If BUILTIN_NAME
 890    is non-NULL, it must name a builtin integral type with the given
 891    signedness and size, and that is the type that will be returned.  */
 892
 893 GCC_METHOD3 (gcc_type, get_int_type,
 894              int /* bool */,               /* Argument IS_UNSIGNED.  */
 895              unsigned long,                /* Argument SIZE_IN_BYTES.  */
 896              const char *)                 /* Argument BUILTIN_NAME.  */
 897
 898 /* Return the 'char' type, a distinct type from both 'signed char' and
 899    'unsigned char' returned by int_type.  */
 900
 901 GCC_METHOD0 (gcc_type, get_char_type)
 902
 903 /* Return a floating point type with the given properties.  If BUILTIN_NAME
 904    is non-NULL, it must name a builtin integral type with the given
 905    signedness and size, and that is the type that will be returned.  */
 906
 907 GCC_METHOD2 (gcc_type, get_float_type,
 908              unsigned long,                /* Argument SIZE_IN_BYTES.  */
 909              const char *)                 /* Argument BUILTIN_NAME.  */
 910
 911 /* Return the 'void' type.  */
 912
 913 GCC_METHOD0 (gcc_type, get_void_type)
 914
 915 /* Return the 'bool' type.  */
 916
 917 GCC_METHOD0 (gcc_type, get_bool_type)
 918
 919 /* Return the std::nullptr_t type.  */
 920
 921 GCC_METHOD0 (gcc_type, get_nullptr_type)
 922
 923 /* Return the nullptr constant.  */
 924
 925 GCC_METHOD0 (gcc_expr, get_nullptr_constant)
 926
 927 /* Create a new array type.  If NUM_ELEMENTS is -1, then the array
 928    is assumed to have an unknown length.  */
 929
 930 GCC_METHOD2 (gcc_type, build_array_type,
 931              gcc_type,                    /* Argument ELEMENT_TYPE.  */
 932              int)                         /* Argument NUM_ELEMENTS.  */
 933
 934 /* Create a new array type.  NUM_ELEMENTS is a template-dependent
 935    expression.  */
 936
 937 GCC_METHOD2 (gcc_type, build_dependent_array_type,
 938              gcc_type,                    /* Argument ELEMENT_TYPE.  */
 939              gcc_expr)                    /* Argument NUM_ELEMENTS.  */
 940
 941 /* Create a new variably-sized array type.  UPPER_BOUND_NAME is the
 942    name of a local variable that holds the upper bound of the array;
 943    it is one less than the array size.  */
 944
 945 GCC_METHOD2 (gcc_type, build_vla_array_type,
 946              gcc_type,                    /* Argument ELEMENT_TYPE.  */
 947              const char *)                /* Argument UPPER_BOUND_NAME.  */
 948
 949 /* Return a qualified variant of a given base type.  QUALIFIERS says
 950    which qualifiers to use; it is composed of or'd together
 951    constants from 'enum gcc_cp_qualifiers'.  */
 952
 953 GCC_METHOD2 (gcc_type, build_qualified_type,
 954              gcc_type,                        /* Argument UNQUALIFIED_TYPE.  */
 955              enum gcc_cp_qualifiers)          /* Argument QUALIFIERS.  */
 956
 957 /* Build a complex type given its element type.  */
 958
 959 GCC_METHOD1 (gcc_type, build_complex_type,
 960              gcc_type)                    /* Argument ELEMENT_TYPE.  */
 961
 962 /* Build a vector type given its element type and number of
 963    elements.  */
 964
 965 GCC_METHOD2 (gcc_type, build_vector_type,
 966              gcc_type,                    /* Argument ELEMENT_TYPE.  */
 967              int)                         /* Argument NUM_ELEMENTS.  */
 968
 969 /* Build a constant.  NAME is the constant's name and VALUE is its
 970    value.  FILENAME and LINE_NUMBER refer to the type's source
 971    location.  If this is not known, FILENAME can be NULL and
 972    LINE_NUMBER can be 0.  */
 973
 974 GCC_METHOD5 (int /* bool */, build_constant,
 975              gcc_type,            /* Argument TYPE.  */
 976              const char *,        /* Argument NAME.  */
 977              unsigned long,       /* Argument VALUE.  */
 978              const char *,        /* Argument FILENAME.  */
 979              unsigned int)        /* Argument LINE_NUMBER.  */
 980
 981 /* Emit an error and return an error type object.  */
 982
 983 GCC_METHOD1 (gcc_type, error,
 984              const char *)               /* Argument MESSAGE.  */
 985
 986 /* Declare a static_assert with the given CONDITION and ERRORMSG at
 987    FILENAME:LINE_NUMBER.  */
 988
 989 GCC_METHOD4 (int /* bool */, add_static_assert,
 990              gcc_expr,     /* Argument CONDITION.  */
 991              const char *, /* Argument ERRORMSG.  */
 992              const char *, /* Argument FILENAME.  */
 993              unsigned int) /* Argument LINE_NUMBER.  */
 994
 995 #if 0
 996
 997 /* FIXME: We don't want to expose the internal implementation detail
 998    that default parms are stored in function types, and it's not clear
 999    how this or other approaches would interact with the type sharing
1000    of e.g. ctor clones, so we're leaving this out, since default args
1001    are not even present in debug information anyway.  Besides, the set
1002    of default args for a function may grow within its scope, and vary
1003    independently in other scopes.  */
1004
1005 /* Create a modified version of a function type that has default
1006    values for some of its arguments.  The returned type should ONLY be
1007    used to define functions or methods, never to declare parameters,
1008    variables, types or the like.
1009
1010    DEFAULTS must have at most as many N_ELEMENTS as there are
1011    arguments without default values in FUNCTION_TYPE.  Say, if
1012    FUNCTION_TYPE has an argument list such as (T1, T2, T3, T4 = V0)
1013    and DEFAULTS has 2 elements (V1, V2), the returned type will have
1014    the following argument list: (T1, T2 = V1, T3 = V2, T4 = V0).
1015
1016    Any NULL expressions in DEFAULTS will be marked as deferred, and
1017    they should be filled in with set_deferred_function_default_args.  */
1018
1019 GCC_METHOD2 (gcc_type, add_function_default_args,
1020              gcc_type,                       /* Argument FUNCTION_TYPE.  */
1021              const struct gcc_cp_function_args *) /* Argument DEFAULTS.  */
1022
1023 /* Fill in the first deferred default args in FUNCTION_DECL with the
1024    expressions given in DEFAULTS.  This can be used when the
1025    declaration of a parameter is needed to create a default
1026    expression, such as taking the size of an earlier parameter, or
1027    building a lambda expression in the parameter's context.  */
1028
1029 GCC_METHOD2 (int /* bool */, set_deferred_function_default_args,
1030              gcc_decl,                       /* Argument FUNCTION_DECL.  */
1031              const struct gcc_cp_function_args *) /* Argument DEFAULTS.  */
1032
1033 #endif
1034
1035
1036 /* When you add entry points, add them at the end, so that the new API
1037    version remains compatible with the old version.
1038
1039    The following conventions have been observed as to naming entry points:
1040
1041    - build_* creates (and maybe records) something and returns it;
1042    - add_* creates and records something, but doesn't return it;
1043    - get_* obtains something without creating it;
1044    - start_* marks the beginning of a compound (type, list, ...);
1045    - finish_* completes the compound when needed.
1046
1047   Entry points that return an int (bool) and don't have a return value
1048   specification return nonzero (true) on success and zero (false) on
1049   failure.  This is in line with libcc1's conventions of returning a
1050   zero-initialized value in case of e.g. a transport error.  */