The Interface Definition Language (IDL) is a language for specifying operations (procedures or functions), parameters to these operations, and data types. This chapter specifies IDL and the associated Attribute Configuration Source (ACS). It includes:
Elements in the grammar that are capitalised are terminals of the grammar. For example, <Identifier> is not further expanded. Also, keywords of the language are terminals of the grammar. For example, the keyword boolean is not further expanded.
The syntax of the IDL language is derived from that of the ISO C programming language. Where a term in this description of the IDL language is not fully defined, the C-language definition of that term is implied.
This chapter specifies both language syntax and semantics. As a
result, the syntax is presented in pieces.
The following subsections define the lexemes of the IDL language.
The IDL contains keywords, which are listed in
Each object is named with a unique identifier. The maximum length of an identifier is 31 characters.
Some identifiers are used as a base from which the compiler constructs
other identifiers. These identifiers have further restrictions on
their length.
The IDL is a case-sensitive language.
Interface specifications must observe the following restrictions on names:
The punctuation used in IDL consists of the following characters:
The { (open brace) and } (close brace) characters are defined as national replacement set characters by ISO and may not be present on all keyboards. Wherever an open brace is specified, the ??< trigraph may be substituted. Wherever a close brace is specified, the ??> trigraph may be substituted. These substitutions are the same as those specified in the ISO C standard.
White space is a character sequence that can be used to delimit any of the other low-level constructs. The syntax of white space is as follows:
A language keyword, an <Identifier> or a list of <Digit>s
must be preceded by a punctuation character or by white space. A
language keyword, an <Identifier> or a list of <Digit>s
must be followed by a punctuation character or by white space. Any
punctuation character may be preceded or followed by white space.
The /* (slash and asterisk) characters introduce a comment. The contents of a comment are examined only to find the */ (asterisk and slash) that terminate it. Thus, comments do not nest. One or more comments may occur before the first non-comment lexical element of the IDL source, between any two lexical elements of the IDL source, or after the last non-comment lexical element of the IDL source.
An interface definition written in IDL has the following structure:
The structure of the interface header is as follows:
where:
<interface_header> ::= <[> <interface_attributes> <]> interface <Identifier>
If an interface defines any operations, exactly one of the uuid attribute or the local attribute must be specified. Whichever is specified must appear exactly once.
It is permissible to have neither the uuid nor the local attribute if the interface defines no operations. The version attribute may occur at most once.
The uuid attribute designates the UUID that is assigned to the interface to identify it uniquely among all interfaces. The uuid attribute is expressed by the uuid keyword followed by a string of characters that gives the literal representation of the UUID.
The textual representation of a UUID is a string that consists of 8
hexadecimal digits followed by a dash, followed by 3 groups of 4
hexadecimal digits where the groups are separated by dashes, followed
by a dash followed by 12 hexadecimal digits. Hexadecimal digits with
alphabetic representations may use upper case or lower case. The
following is an example of the textual representation of a UUID:
All UUIDs are machine generated in a manner that gives high guarantees
of uniqueness. For an architectural definition of UUIDs and a full
discussion of their guarantees, refer to
The version attribute identifies a specific version of a remote
interface when multiple versions of the interface exist.
Version semantics are specified in
The major and minor version numbers of an interface must each have a value between 0 and 65,535, inclusive.
The defaulting rules for interface version numbers are as follows:
The endpoint attribute specifies the well-known endpoint(s) on which servers that export the interface will listen. Well-known endpoint values are typically assigned by the central authority that owns the protocol.
A <port_spec> is composed of two strings separated by punctuation as described in the syntax. The <Family_string> identifies the protocol family to be used; the <Port_string> identifies the well-known endpoint designation for that family.
The actual syntax of <Port_string> is family-dependent.
The local attribute provides a means to use the IDL compiler as a header generation language. When the local attribute is specified, the uuid attribute must not be specified.
Stubs are not generated for local interfaces. Checks for data transmissibility are omitted.
The pointer_default attribute specifies the default
treatment for pointers. If no pointer_default attribute is
specified in the interface attributes, and a construct requiring a
default pointer class is used, the compiler will issue an error. (See
The structure of the interface body is as follows:
where:
The syntax of the <import_list> in an import declaration is as follows:
where: <Import_string> gives a system dependent name for an import source.
The IDL [??]import[??] declaration specifies another interface definition whose types and constants are used by the importing interface. It is similar to the [??]include[??] declaration in C. The imported definition must in itself adhere to all specifications in this chapter.
The following subsections specify the syntax and semantics of constant declarations.
The syntax for a constant declaration is as follows:
The <integer_size> keyword hyper must not appear in a
constant declaration. <Character> is a character from the
portable character set specified in
In the production <string>, no <Character> is permitted to be the " (double quote) character, which is the delimiter, unless it is immediately preceded by the \ (backslash) character. In the production <character_constant>, no <Character> may be the ' (single quote) character, which is the delimiter, unless it is immediately preceded by the \ (backslash) character.
<Integer_literal> may appear if and only if <const_type_spec> is long, short, small, unsigned long, unsigned short or unsigned small.
A <character_constant> may appear if and only if <const_type_spec> is char. NULL may appear if and only if <const_type_spec> is void*.
TRUE or FALSE may appear if and only if <const_type_spec> is boolean.
<string> may appear if and only if <const_type_spec> is char*. Within a <string> a \ (backslash) is interpreted as introducing an escape sequence, as defined in ISO C standard, Section 3.1.3.4. White space within a <string> is significant and is preserved as part of the text of the string.
An <Identifier> must have been defined in a preceding constant
declaration. The type that <Identifier> was defined to be in
that declaration must be consistent with the <const_type_spec>
in the current declaration.
The syntax for type declarations and tagged declarations is as follows:
If a <simple_type_spec> is an <Identifier>, that <Identifier> must have been defined previously.
The base types are the fundamental data types of the IDL. Any other
data types in an interface definition are derived from these types.
The syntax rules for use of the base types are as follows:
| Type | Range |
|---|---|
| hyper | -263, ..., 263-1 |
| long | -231, ..., 231-1 |
| short | -215, ..., 215-1 |
| small | -27, ..., 27-1 |
| unsigned hyper | 0, ..., 264-1 |
| unsigned long | 0, ..., 232-1 |
| unsigned short | 0, ..., 216-1 |
| unsigned small | 0, ..., 28-1 |
The keywords char and unsigned char are synonymous.
The boolean keyword is used to indicate a data item that can only take one of the values TRUE and FALSE.
A byte data item consists of opaque data: that is, its contents are not interpreted.
The void keyword is valid only in an operation or pointer declaration. In an operation declaration, it may be used to indicate an operation that does not return a function result value. In a pointer declaration, it must be used in conjunction with the context_handle attribute.
The handle_t type is used to declare a primitive handle object.
A primitive handle can be declared in a type declaration or in a
parameter list. If it is declared in a parameter list, it must be the
first parameter in the list.
The syntax of constructed types is as follows:
The syntax of structures is as follows:
ISO C semantics apply to IDL structures.
The following subsections describe IDL unions.
The syntax for a union definition is:
Encapsulated unions are created with the <union_switch>
production.
A union that is created without the use of the <union_switch> production is a non-encapsulated union. The discriminant of a non-encapsulated union is another parameter if the union is a parameter, or another structure field if the union is a structure field.
When the non-encapsulated union is declared as a type, the <union_type_switch_attr> production must be used. When a type that is a non-encapsulated type is used to declare a structure field or a parameter, the <union_instance_switch_attr> production must be used. When a non-encapsulated union is being declared directly as a structure field or parameter, the <union_instance_switch_attr> production must be used.
In encapsulated unions, if the <union_name> is omitted, the union is assigned the name tagged_union in the generated header source.
The <default_case> defines the layout of data if the discriminant variable of the switch is not equal to any of the case values.
Within a union, the type of each <union_case_label> must be that specified by the <switch_type_spec>. Likewise the type specified in the <union_type_switch_attr> and the <union_instance_switch_attr> must be the same.
A field within a union definition must not be or contain a
conformant or conformant varying array. (See
A union arm that consists solely of a terminating semicolon is legal and specifies a null arm.
There must be at most one default case for a union.
When the <Identifier> alternative is used in the <switch_type_spec> production to declare a switch type, <Identifier> must identify a declared type that resolves to the primitive integer type, the char type, the boolean type, or an enum type; it cannot be a pointer, pipe, struct or array type.
The syntax of enumerated types is as follows:
The <Identifier>s are mapped from left to right onto consecutive integers, beginning with the value zero.
An enumeration may have up to 32,767 <Identifier>s.
IDL supports streams of typed data. The programming construct to support this is pipe, which is a type constructor that is similar to struct and union.
An in parameter that is a pipe allows a callee to pull an open-ended stream of typed data from a caller. An out parameter that is a pipe allows a callee to push an open-ended stream back to a caller. An in, out parameter that is a pipe allows for two-way transfer of data between callee and caller.
The syntax used to declare a pipe type is as follows:
Data types that are pipes are subject to several restrictions:
Also, an operation that has one or more pipe parameters must not have the
idempotent attribute.
The following sections describe the syntax and semantics of arrays.
The syntax rules for array declarations are as follows:
The bounds of each dimension of an array are expressed inside a separate <[>, <]> (bracket) pair.
If the bracket pair contains a single <const_exp> that evaluates to n, a lower bound of zero and an upper bound of n-1 are signified.
If the bracket pair is empty or contains a single * (asterisk), a lower bound of zero and an upper bound to be determined at run time are signified.
In an <array_bounds_pair> the <array_bound> preceding the .. (dot dot) indicates the lower bound of the dimension and the <array_bound> following the .. (dot dot) indicates the upper bound.
An * (asterisk) before or after .. (dot dot) means that the corresponding bound is to be determined at run time.
Any <Identifier> appearing as an array bound must resolve to an integer constant. The base type of an array cannot be a conformant array or conformant structure.
The user may declare types that are arrays and then declare
arrays of objects of such types. The semantics of an m-dimensional
array of objects of a type defined to be an n-dimensional array are
the same as the semantics of an m+n-dimensional array.
The following sections describe type attributes.
The syntax for type attributes is as follows:
The transmit_as attribute associates a presented type in the target language with an IDL transmitted type, <xmit_type>. The user must supply routines that perform conversions between the presented and transmitted types, and that release memory used to hold the converted data.
The <xmit_type> in a transmit_as attribute must be either a <base_type_spec>, a <predefined_type_spec> or an <Identifier> from a <type_declarator> that was previously defined.
The following types must not have the transmit_as attribute:
The handle attribute specifies that a type may serve as a customised handle. Customised handles permit the design of handles that are meaningful to an application. The user must provide binding and unbinding routines to convert between the custom handle type and the primitive handle type, handle_t.
The string attribute is provided to preserve the string property of data so that it may be appropriately processed by application components written in languages that support a string data type.
The string attribute only applies to one-dimensional arrays. The element type of such an array is limited to one of the following:
Note that strings of element type char or byte are terminated by the NULL character, while those of element type unsigned short or unsigned long are terminated by the array element zero (0).
For further information on objects with the string attribute, see
In many interfaces, a called procedure needs to maintain state between calls. This is done by means of a context handle. A context handle is a void* with the context_handle attribute.
There are several restrictions on the use of context handles:
The following sections describe the syntax and semantics of field attributes.
The syntax for declaring field attributes is as follows:
A <usage_attribute> must not be applied to an item of a type that resolves to a type with a <usage_attribute> in its declaration. For the form *<Identifier>, the <Identifier> in the <attr_var> must be a pointer to a <primitive_integer_type>. The context_handle attribute is not permitted on fields. Therefore, the <usage_attribute> must not resolve to context_handle in this production.
The ignore attribute is used for a pointer, contained within a structure, that must not be dereferenced. The ignore attribute is restricted to pointer members of structures.
Field attributes are used in conjunction with array declarations to specify either the size of the array, or the portion of the array that contains valid data. To do this, they associate another parameter or structure field with the array. The associated datum contains the extra information. Array parameters must associate with another parameter, and array structure fields must associate with another field. Array parameters with field attributes are not allowed to have a transmit_as attribute associated with their type. Since an array parameter with one or more of the field attributes min_is, max_is, size_is, first_is, last_is or length_is is fully described only in the presence of another parameter, it cannot be properly processed by the <type_id>_to_xmit_type routine.
An array is called conformant if it has an <array_bounds_declarator> that is empty or contains an * (asterisk). Conformant arrays have one of the attributes min_is, max_is, or size_is. If the lower bound of any dimension of an array is unspecified, the array must have the min_is attribute; if the upper bound of any dimension of an array is unspecified, the array must have the either the max_is attribute or the size_is attribute, but not both.
The min_is attribute is used to specify the minimum array indexes in each dimension of an array. Each <attr_var> in a min_is clause specifies the minimum array index in one dimension.
An <attr_var> must be non-NULL if and only if the lower bound of the corresponding dimension is empty or is an * (asterisk). At least one <attr_var> in a min_is clause must be non-NULL.
An <attr_var> must be present for each dimension of an array for which the lower bound is unspecified. The <attr_var>s in a min_is clause are in one-to-one correspondence with the dimensions of the array, with the first <attr_var> corresponding to the first dimension. If there are fewer <attr_var>s than the array has dimensions, then the behaviour is undefined.
The max_is attribute is used to specify the maximum array indexes in each dimension of an array. Each <attr_var> in a max_is clause specifies the maximum array index in one dimension.
An <attr_var> must be non-NULL if and only if the upper bound of the corresponding dimension is empty or is an * (asterisk). At least one <attr_var> in a max_is clause must be non-NULL.
An <attr_var> must be present for each dimension of an array for which the upper bound is unspecified. The <attr_var>s in a max_is clause are in one-to-one correspondence with the dimensions of the array, with the first <attr_var> corresponding to the first dimension. If there are fewer <attr_var>s than the array has dimensions, then the behaviour is undefined.
If a declaration has the max_is attribute, it must not have the
size_is attribute. (See
An <attr_var> must be non-NULL if and only if the upper bound of the corresponding dimension is empty or contains an * (asterisk). At least one <attr_var> in a size_is clause must be non-NULL.
An <attr_var> must be present for each dimension of an array for which the upper bound is unspecified. The <attr_var>s in a size_is are in a one-to-one correspondence with the dimensions of the array, with the first <attr_var> corresponding to the first dimension. If there are fewer <attr_var>s than the array has dimensions, then the behaviour is undefined.
If a declaration has a size_is attribute, it must not have a max_is attribute. A given conformant array may be declared using either the max_is or size_is attribute but not both. The relationship between the values of these attributes for a given array can be derived as follows: in the mth dimension of the array, the lowest index to be used in this dimension is specified by lower_bound_m. For a declaration using the max_is attribute, call the the mth <attr_var> max_value_m. For a declaration of the same array using the size_is attribute, call the mth <attr_var> size_value_m. For equivalent declarations, the relationship between these attribute values is then given by the equation:
An array is called varying if none of its <array_bounds_declarator> components is empty or contains an * (asterisk), and it has either a last_is, first_is or length_is attribute. An array is called conformant varying if it is conformant and it has a last_is, first_is or length_is attribute.
The last_is attribute is used to define the upper index bounds for significant elements in each dimension of an array. Each <attr_var> in a last_is clause indicates the highest index, in a given dimension, whose element value is significant both to the caller and the callee. Elements in a given dimension with indexes higher than the dimension's <attr_var> are not meaningful to caller and callee.
If the <attr_var> corresponding to a dimension in an array is null, then the value used is the corresponding dimension found in either the associated type definition for a varying array, or the value of the max_is or size_is parameter for a conformant varying array.
The <attr_var>s are in one-to-one correspondence with the dimensions of the array, with the first <attr_var> corresponding to the first dimension. If there are fewer <attr_var>s than the array has dimensions, then the behaviour is undefined.
If a declaration has a last_is attribute, it must not have a
length_is attribute. (See
The first_is attribute is used to define the lower index bounds for significant elements in each dimension of an array. Each <attr_var> in a first_is clause indicates the lowest index, in a given dimension, whose element value is significant both to the caller and the callee. Elements in a given dimension with indexes lower than the dimension's <attr_var> are not meaningful to caller and callee.
A NULL <attr_var> indicates that the lower bound for that dimension is to be used as the first_is value for that dimension. At least one <attr_var> in a first_is clause must be non-NULL.
The <attr_var>s are in one-to-one correspondence with the dimensions of the array, with the first <attr_var> corresponding to the first dimension. If there are fewer <attr_var>s than the array has dimensions, then the behaviour is undefined.
The length_is attribute is used to define the number of significant elements in each dimension of an array. Each <attr_var> in a length_is clause indicates the number of elements, in a given dimension, whose element value is significant both to the caller and the callee.
Significant elements in a given dimension are counted from the lowest significant index for that dimension. This may be the fixed lower bound for this dimension or may be specified by using a first_is clause.
At least one <attr_var> in a length_is clause must be non-NULL.
If a declaration has a length_is attribute, it must not have a last_is attribute.
A given varying array may be declared using either the last_is
or length_is attribute. The relationship between the values
of these attributes for a given array is derived as follows: in
the mth dimension of the array, the lowest index to be used in
this dimension is specified by lowest_index_m. For a
declaration using the last_is attribute, call the the
mth <attr_var> last_value_m. For a declaration of
the same array using the length_is attribute, call the
mth <attr_var> length_value_m. For equivalent
declarations, the relationship between these attribute values is then
given by the equation:
The following rules apply to the relationship between the max_is, first_is and last_is values for a dimension:
If the size_is or length_is value is negative, the
behaviour is undefined.
When declaring a string, it is necessary to declare space for one more than the maximum number of characters the string is to hold.
The following subsections describe the use of each of the field attributes with strings.
An array with the string attribute must not have any of the varying attributes; that is, first_is, last_is or length_is.
The max_is attribute names a parameter or record field that holds one more than the highest allowable index for a data character of a string.
The min_is attribute must not exceed the initial length of the declared sting.
A size_is attribute is an alternative mechanism for defining the maximum amount of string data that may be present. If a declaration has a size_is attribute, it must not have a max_is attribute.
The usage of size_is and its relationship to max_is may be
derived from the discussion contained in
The syntax for a pointer declaration is as follows:
Elsewhere in the grammar, attributes are applied to entities involving pointer declarations. The production for pointer attributes is:
A <ptr_attr> may be applied only to declarations with an explicit pointer declaration, or to the implicit pointer present for array parameters.
Pointers are used in applications in a wide variety of ways. IDL currently supports three different levels of pointer capability:
A reference pointer is one that is used for simple indirection. It has the following characteristics in any language that supports pointers:
If these restrictions are not met, the effects are undefined.
A unique pointer is more flexible than a reference pointer. However, reference and unique pointers share several important characteristics.
The characteristics of a unique pointer are as follows:
Like a reference pointer, a unique pointer must not cause any aliasing of data within the operation. As with a reference pointer, data returned from the callee is written into the existing referent specified by the pointer (if it did not have the value NULL).
A full pointer has a wider range of capabilities. The characteristics of a full pointer are as follows:
The following IDL attributes are used to indicate the supported pointer classes:
These attributes may be used on parameters, structure and union members, and in type definitions.
At most, one <ptr_attr> may appear in the interface header.
(This appears with the pointer_default attribute. See
If a <ptr_attr> that is not required according to the preceding rules appears in the interface header, it is ignored.
By default, the first1 indirection operator (an *, asterisk) in a parameter declaration is treated as a reference pointer. This is the pointer that accomplishes what is commonly termed "pass by reference". If there are multiple indirection operators in a parameter declaration, all but the first have the characteristic specified by <ptr_attr> in the interface header.
Any pointer attributes placed on a parameter (that is, directly in the syntax of an operation declaration) affect only the first pointer declaration. To affect any others, intermediate named types must be used.
If an operation returns a pointer to a type, then ptr is permitted as an operation attribute to describe the properties of the pointer. Even in the absence of this attribute, the meaning is that a full pointer is returned by the function. No pointer attribute other than ptr is permitted as an operation attribute.
By default, pointers in structure member and union arm declarations are interpreted as specified by the interface pointer attribute. In these contexts, the pointer attributes ref, ptr and unique may be applied to override the default for the top-level pointer in the pointer declaration.
Pointer attributes are allowed in typedefs. Pointer declarators at the top level of a typedef with a pointer attribute are always treated in accordance with the specified pointer attribute. Pointer declarators at the top level of a typedef without a pointer attribute and non-top-level pointers are interpreted according to the <ptr_attr> in the interface header of the interface in which it is defined.
Pointer attributes may only be applied where an explicit pointer declaration occurs. There is no way to override the pointer attribute of a declared type at the reference site.
Varying arrays of pointers bear special attention because there may be more valid elements on the return from the call than there were at the start of the call.
Because a reference pointer must not have the value NULL, special requirements apply to varying or conformant varying arrays of reference pointers. If:
then all array elements that are valid at the time of the call (the in, out case) or may be valid at the time of the return from the call must point to storage that can be written with the returned referents.
Unless the client and server have made some private arrangement, outside the IDL, that is binding on all client and server implementations, the caller must initialise all pointers of the array to point to valid memory, even those outside the limit specified by the last_is, first_is or length_is variable at the time of the call.
On the callee side, the callee stub must instantiate storage for each pointer in the varying array, regardless of the value of the associated last_is, first_is, or length_is variable at the time of the call, provided that the layout of the pointed-to storage can be determined at compile time; that is, the pointed to storage must contain no full pointers, unions, conformant arrays, conformant structures, and so on.
Varying arrays of unique and full pointers are treated differently. Again, consider the case cited above: an in, out or out varying or conformant varying array whose associated <attr_var> (last_is, first_is or length_is) is also in, out or out.
When the array elements are unique or full pointers, array elements past the limit established by the associated last_is, first_is or length_is variable need not be initialised before the call on the caller side.
The callee stub does must initialise the array elements past the limit established by the associated last_is, first_is or length_is variable. If the called user code increases the number of valid elements, it must initialise those elements before the call returns to the called stub code.
On return from a call, array elements that were not valid at the time
of a call are treated as uninitialised.
The pointer support IDL provides is very powerful and flexible. At times this flexibility collides with other features of IDL, resulting in the following restrictions:
Parameters with only the out directional attribute may, however, contain full pointers. Such pointers are not initialised at the time the manager code is called. It is the responsibility of the manager code to initialise these pointers, either to NULL or to point to accessible memory, before returning to the callee stub.
When declaring a conformant array parameter, IDL provides an alternative to using [] (brackets). A parameter that is a pointer to a type is treated as an array of that type if the parameter has any of the array attributes min_is, max_is, size_is.
Note that this equivalence of arrays and pointers is true only in parameter lists. As structure or union members, arrays and pointers are distinct. A structure or union member declared with bracket notation declares an array contained within the structure. A member declared to be a pointer is a pointer to a data element. If a structure field is a pointer and has a size_is, min_is, or max_is attribute, then it is a pointer to an array of data.
Because of parsing ambiguities, the language does not allow mixing pointer and bracket notation when declaring a pointer to a conformant array. The language does not allow declaring a pointer to a varying array. A pointer to a structure that contains a varying array must be used instead.
The array attributes controlling the valid range of elements may be applied to arrays declared as pointers, just as they apply to arrays declared with brackets; the size_is, min_is, max_is, last_is and length_is attributes may be applied to pointers, just as they may be to arrays.
A pointer to any of the base types specified in
When dealing with an operation such as:
a possible ambiguity arises. Is myarray a pointer to an array of
longs, or an array of pointers to longs? IDL defines this
signature to be an array of pointers to longs. The max_is
and size_is attributes always apply to the top-level, or
rightmost, * (asterisk) in the IDL signature of the parameter.
The syntax of an operation declaration is as follows:
The syntax for operation attributes is:
If none of idempotent, broadcast, maybe is present, at-most-once semantics are applied; the operation is executed no more than one time. If a remote call fails, it is not be retried automatically if there is any chance that the called code has started execution.
When used as an <operation_attribute>, the <ptr_attr>
must not be the ref or unique attributes. (See
An operation must not have an array type result.
The idempotent attribute indicates that the operation does not modify any state and/or yields the same result on each invocation.
An operation with the idempotent attribute must not have any pipe parameters.
The broadcast attribute specifies that the operation may be invoked multiple times concurrently as the result of a single RPC. This is different from the idempotent attribute, which specifies that a call may be retried in the event of failure. Operations with the broadcast attribute may be sent to multiple servers, effectively concurrently. The output arguments that the caller receives are taken from the first reply to return successfully. An operation with the broadcast attribute is implicitly an idempotent operation.
An operation with the broadcast attribute must not have any pipe parameters.
Depending on the network services in use, there may be some limitations on the availability and semantics of this attribute.
The maybe attribute specifies that the operation's caller must not require and must not receive a response or fault indication. An operation with the maybe attribute must not contain any output parameters and is implicitly an idempotent operation.
An operation with the maybe attribute must not have any pipe parameters.
The reflect_deletions attribute specifies that memory occupied by targets of pointers on the client will be released when the corresponding targets of pointers on the server are released. This is true only for targets that are components of in parameters of the operation.
The following sections describe the syntax and semantics of parameter declarations.
The syntax rules for parameter declarations are as follows:
<param_declarators> ::= ( [ <param_declarator>
[ , <param_declarator> ] ... ] )
| ( void )
<param_declarator> ::= <param_attributes> <type_spec> <declarator>
<param_attributes> ::= <[> <param_attribute>
[ , <param_attribute> ] ... <]>
<param_attribute> ::= <directional_attribute>
| <field_attribute>
<directional_attribute> ::= in
| out
If the <param_declarators> production consists of only a pair of parentheses, the semantics are the same as if the keyword void appeared between the parentheses. The remote operation has no parameters.
At least one directional attribute must be specified for each
parameter.
| Attribute | Meaning |
|---|---|
| in | The parameter is passed from the caller to the callee. |
| out | The parameter is passed from the callee to the caller. |
A parameter with the out attribute must be either an array or an explicitly declared pointer. An explicitly declared pointer is declared by a pointer declarator, rather than by a <declarator> with a named parameter as its type_spec.
Any parameter from which the binding for a call is to be derived must have the in attribute. If an operation has an in handle_t, in customised handle (handle) or in context handle (context_handle), and also contains an in, out context handle, the in, out context handle may be null. If an operation does not have an in handle_t, in customised handle or in context handle, but does contain one or more in, out context handles, at least one of the in, out context handles must be non-null.
If two pointer parameters in a parameter list point at the same data item, or at data structures that have some items in common, parameter aliasing is said to occur.
Aliasing is supported only for full pointers; both parameters involved in the aliasing must be full pointers. Full pointers are aliases when:
The scope of aliasing is a single instance of an RPC call. Aliasing is not preserved across nested RPCs.
Aliasing of reference pointers is not supported and yields unspecified results. Aliasing is not supported for the case where the target of one pointer is a component (for example, a structure field or array element) of another pointer. This yields unspecified results.
The following sections describe the syntax, semantics and restrictions of function pointers.
The syntax for declaration of a function pointer is:
An instance of a function pointer type allows functions to be referenced indirectly.
Function pointers are permitted only within interfaces declared with the local attribute.
Predefined types are data types derived from the base types that are
intrinsic to the IDL language. The syntax for predefined types is as
follows:
The error_status_t type is used to declare an object in which
communications and fault status information can be held. This is the
appropriate type for objects with the comm_status or
fault_status attributes.
The following types may be used to represent alternative character sets:
Data of type char is subject to ASCII/EBCDIC conversion when it
An enumeration type is said to be anonymous if it is not a type named through a typedef statement. A structure or union type is said to be anonymous if it does not have a tag and is not named through a typedef statement. The following rules apply to the usage of anonymous types:
The Attribute Configuration Source (ACS) is used to specify details of a stub to be generated. ACS is used to create a separate attribute configuration source that accompanies an IDL specification. The ACS specification affects the interface between the application code and the stub; for example, it can specify whether an explicit binding handle parameter is used. The ACS specification also affects the way stub code is generated. The ACS specification does not affect the way the data is transmitted or received during a remote procedure call; this is determined entirely by the IDL specification.
Comments in ACS conform to the same rules as IDL comments.
Each ACS source is associated with some IDL source. The following associations apply:
The syntax of an ACS specification is as follows:
<ACS_interface_header> ::= [ <ACS_interface_attr_list> ] interface
<ACS_interface_name>
<ACS_interface_attr_list> ::= <[> <ACS_interface_attrs> <]>
<ACS_interface_attrs> ::= <ACS_interface_attr> [ , <ACS_interface_attr> ] ...
<ACS_interface_attr> ::= <ACS_code_attr>
| <ACS_nocode_attr>
| <ACS_explicit_handle_attr>
| <ACS_implicit_handle_attr>
| <ACS_auto_handle_attr>
| <ACS_cs_tag_rtn_attr>
| <ACS_extern_exceps_attr>
| <ACS_binding_callout_attr>
<ACS_explicit_handle_attr> ::= explicit_handle
<ACS_implicit_handle_attr> ::= implicit_handle ( <ACS_named_type>
<Identifier> )
<ACS_auto_handle_attr> ::= auto_handle
<ACS_extern_exceps_attr> ::= extern_exceptions ( <ACS_ext_excep_list> )
<ACS_ext_exceps_list> ::= <ACS_ext_excep> [ , <ACS_ext_excep> ] ...
<ACS_ext_excep> ::= <Identifier>
<ACS_binding_callout_attr> ::= binding_callout ( <ACS_bind_call_rtn_name> )
<ACS_bind_call_rtn_name> ::= <Identifier>
<ACS_interface_name> ::= <Identifier>
<ACS_interface_body> ::= [ <ACS_body_element> ] ...
<ACS_body_element> ::= <ACS_include> ;
| <ACS_type_declaration> ;
| <ACS_oper> ;
<ACS_include> ::= include <ACS_include_list>
<ACS_include_list> ::= <ACS_include_name> [ , <ACS_include_name> ] ...
<ACS_include_name> ::= "<Import_string>"
<ACS_type_declaration> ::= typedef [ <ACS_type_attr_list> ] <ACS_named_type>
<ACS_named_type> ::= <Identifier>
<ACS_type_attr_list> ::= <[> <ACS_type_attrs> <]>
<ACS_type_attrs> ::= <ACS_type_attr> [ , <ACS_type_attr> ] ...
<ACS_type_attr> ::= <ACS_repr_attr>
| <ACS_cs_char_attr>
| <ACS_heap_attr>
<ACS_repr_attr> ::= represent_as ( <ACS_repr_type> )
<ACS_cs_char_attr> ::= cs_char C ( <ACS_cs_char_type> )
<ACS_cs_char_type> ::= <ACS_named_type>
<ACS_repr_type> ::= <Identifier>
<ACS_oper> ::= [ <ACS_oper_attr_list> ] <Identifier> ( [ <ACS_params> ] )
<ACS_oper_attr_list> ::= <[> <ACS_oper_attrs> <]>
<ACS_oper_attrs> ::= <ACS_oper_attr> [ , <ACS_oper_attr> ] ...
<ACS_oper_attr> ::= <ACS_commstat_attr>
| <ACS_faultstat_attr>
| <ACS_code_attr>
| <ACS_nocode_attr>
| <ACS_explicit_handle_attr>
| <ACS_enable_alloc_attr>
| <ACS_cs_tag_rtn_attr>
<ACS_cs_tag_rtn_attr> ::= cs_tag_rtn ( <acf_cs_tag_rtn_name> )
<ACS_cs_tag_rtn_name> ::= <Identifier>
<ACS_params> ::= <ACS_param> [ , <ACS_param> ] ...
<ACS_param> ::= [ <ACS_param_attr_list> ] <Identifier>
<ACS_param_attr_list> ::= <[> <ACS_param_attrs> <]>
<ACS_param_attrs> ::= <ACS_param_attr> [ , <ACS_param_attr> ] ...
<ACS_param_attr> ::= <ACS_commstat_attr>
| <ACS_faultstat_attr>
| <ACS_cs_stag_attr>
| <ACS_cs_drtag_attr>
| <ACS_cs_rtag_attr>
| <ACS_heap_attr>
<ACS_code_attr> ::= code
<ACS_nocode_attr> ::= nocode
<ACS_cs_stag_attr> ::= cs_stag
<ACS_cs_drtag_attr> ::= cs_drtag
<ACS_cs_rtag_attr> ::= cs_rtag
<ACS_commstat_attr> ::= comm_status
<ACS_faultstat_attr> ::= fault_status
<ACS_heap_attr> ::= heap
<ACS_enable_alloc_attr> ::= enable_allocate
<ACS_interface> ::= <ACS_interface_header> { <ACS_interface_body> }
where
The include statement specifies one or more header sources that are are included in generated stub code, for example, via C-preprocessor #include statements. The user must supply the header sources. A C-language definition source (.h file) must always be provided for use when compiling the stubs. If the stubs are being generated for another language, then a definition source for that language must be provided as well. The same ACS source may not work with different target languages.
If the include statements do not fully specify the location of the header sources, the compiler uses implementation-specific searching mechanisms to locate them. Similarly, if the file extension is not specified, then the compiler appends the appropriate file extension for the language of choice.
Include statements are necessary if, in the ACS source, there occur one or more types specified in the represent_as clause's <ACS_named_type> or the implicit_handle or cs_char attribute's <type_spec> that are not types defined in the interface definition (or any imported interfaces). Since the definitions of such types are needed by the generated stub code, the user must supply them in this manner.
The means of providing binding information to the RPC run-time system is the binding handle. Binding handles (or simply, handles) may be passed as parameters of the operation or fetched by the generated stub from a static area. A handle passed as an operation parameter is termed an explicit handle. If an explicit handle is used, it is always the first parameter of an operation. Explicit handles may be declared in the IDL source, in which case both the client and server must use the explicit handle. Explicit handles may also be declared in the ACS source, in which case the two sides (client and server) may make the decision to use an explicit handle separately.
When an interface contains one or more operations whose first parameter is not an explicit handle, and which do not have an in or in, out context handle, a means of providing a handle is needed. The implicit_handle and auto_handle attributes provide this capability.
If an interface has an operation requiring an implicit handle, and no ACS source is supplied, or the supplied ACS source does not specify either implicit_handle or auto_handle, then the default auto_handle attribute is applied. The auto_handle attribute is also applied in the event that a operation has an in, out context handle but no other binding handle mechanism.
When the auto_handle attribute is applied, the binding_callout attribute allows the client application using automatic binding to modify the binding handle obtained by the client stub before the remote procedure call is initiated.
When used as an interface attribute, the explicit_handle attribute is applied to all operations in the interface. When used as an operation attribute, it is applied to only the specified operation.
The explicit_handle attribute specifies that the operation has an additional first parameter of type handle_t and named IDL_handle, even if one is not explicitly declared in the IDL source. Customised binding handles must be declared in the IDL source. The explicit_handle attribute may occur as an interface attribute only if the implicit_handle attribute and auto_handle attribute do not occur.
The implicit_handle attribute is one of the methods for specifying handles. Under the implicit_handle method, the handle used on calls to operations without a handle in the first parameter position is the data object specified in the implicit_handle attribute.
The implicit_handle attribute must occur at most once in the ACS source. The implicit_handle attribute may occur only if the auto_handle attribute does not occur and the explicit_handle attribute does not occur as an interface attribute.
The <type_spec> specified in the implicit_handle attribute need not be specified in the associated interface definition source. If it is specified, then the definition specified in the IDL source is used; it must be either a type that resolves to the type handle_t or a type with the handle attribute. If it is not a type defined in the interface definition source, then the ACS source must contain an include statement, specifying a definition source that defines the <type_spec>. The type is treated as a customised handle; that is, as if it had the handle attribute applied to it.
The auto_handle attribute indicates that any operations needing handles are automatically bound; that is, a client that makes a call on that operation makes no specification as to which server the operation may execute on.
The environment variable RPC_DEFAULT_ENTRY must be set to the name of the namespace entry from which the stub will import bindings to be used when an operation is invoked.
The auto_handle attribute must occur at most once.
The auto_handle attribute may occur only if the implicit_handle attribute does not occur and the explicit_handle attribute does not occur as an interface attribute.
The binding callout routine provided must have a specific routine signature.
The binding_callout attribute must occur at most once.
The binding_callout attribute applies to all operations in the interface.
The represent_as attribute associates a named local type in the target language (<ACS_repr_type>) with a transfer type (<ACS_named_type>) that is transferred between caller and callee.
There are some restrictions on the types to which the represent_as attribute may be applied. The following types must not have the represent_as attribute:
At most, one of the code and nocode attributes may appear in the interface attribute list. If neither is present, the effect is as if code is present.
The nocode attribute is only honoured when generating a client stub. Servers must support all defined operations.
If code appears in the interface attribute list, stub code is be generated for any operation in the interface that does not appear in the ACS source with nocode in its operation attribute list.
If nocode appears in the interface attribute list, stub code is only generated for those operations in the interface that appear in the ACS source with code in their operation attribute lists.
At most, one of code and nocode may appear in an operation attribute list. If both the interface and the operation have a code or nocode attribute, the attribute applied to the operation overrides the attribute applied to the interface.
Two attributes, comm_status and fault_status, are available to provide a status return mechanism for certain error conditions that occur during the execution of remote routines. Portable applications must include an ACS specification that specifies these attributes.
The comm_status attribute must occur at most once per operation. It may appear as an operation attribute for the operation, or as a parameter attribute for one of the parameters of the operation.
If the comm_status attribute appears as an operation attribute, the operation must have been defined to deliver a result of type error_status_t. If the run-time system detects that some communications error (for example, a broken connection or a timeout) has occurred during execution of the operation, the error code is returned as the operation result. If the run-time system does not detect a communications failure, then the operation result has the value returned by the manager routine.
If the comm_status attribute appears as a parameter attribute, the <Identifier> associated with it need not be the <Identifier> of a parameter defined in the IDL. If the comm_status attribute does specify the <Identifier> of a parameter defined in the IDL, then the parameter must be an out parameter of type error_status_t*. In the event that the remote call completes successfully, the parameter has the value assigned by the called procedure.
If the <Identifier> associated with the comm_status attribute is not the <Identifier> of a parameter defined in the IDL, then an extra out parameter of type error_status_t* is created. This follows the last parameter defined in the IDL, unless a parameter with the fault_status attribute is present. If a parameter with the fault_status attribute is present, then the parameters are defined in the order they appear in the ACS. In the case of successful completion of the call, the extra parameter has the value error_status_ok.
If a communications error occurs during execution of the operation, the error code is returned in the parameter with the comm_status attribute.
For a summary of which errors are reported through the
comm_status mechanism when enabled, refer to
The fault_status attribute is similar to the comm_status attribute. However, it deals with certain failures of the remote routine rather than communications errors.
The fault_status attribute must occur at most once per operation. It may appear as an operation attribute for the operation, or as a parameter attribute for one of the parameters of the operation.
If the fault_status attribute appears as an operation attribute, the operation must have been defined to deliver a result of type error_status_t. If the remote procedure fails in a way that causes a fault PDU to be returned, the error code is returned as the operation result. If a failure is not detected, then the operation result has the value returned by the manager routine.
If the fault_status attribute appears as a parameter attribute, the <Identifier> associated with it need not be the <Identifier> of a parameter defined in the IDL. If the fault_status attribute does specify the <Identifier> of a parameter defined in the IDL, then the parameter must be an out parameter of type error_status_t*. In the event that the remote call completes successfully, the parameter has the value assigned by the called procedure.
If the <Identifier> associated with the fault_status attribute is not the <Identifier> of a parameter defined in the IDL, then an extra out parameter of type error_status_t* is created. This follows the last parameter defined in the IDL unless a parameter with the com_status attribute is present. If a parameter with the com_status attribute is present, then the parameters are defined in the order in which they appear in the ACS. In the case of successful completion of the call, the extra parameter has the value error_status_ok.
If a suitable error occurs during execution of the operation, the error code is returned in the parameter with the fault_status attribute.
For a summary of which exceptions are reported through the
fault_status mechanism when enabled, refer to
It is possible for one operation to have both the fault_status and the comm_status attributes, either as operation attributes or as parameter attributes.
If both attributes are applied as operation attributes, or both attributes are applied to the same parameter, then the operation or parameter has the value error_status_ok if no error occurred. Otherwise, it has the appropriate comm_status or fault_status value. Since the values returned in parameters with the comm_status attribute are disjoint from the values returned in parameters with the fault_status attribute, and it is not possible for a single call to result in two failures, there is no ambiguity in interpreting the returned status value.
If both attributes are specified for an operation, and each attribute refers to an <Identifier> that is not defined in the IDL source, then two extra parameters are defined after the last parameter defined in the IDL source. These parameters are defined in the order in which they appear in the ACS source.
By default, the IDL compiler declares and initializes in the stub code all exceptions specified by the exceptions interface attribute. The extern_exceptions attribute indicates that the exceptions it specifies are not declared by the stub code but defined and initialized in some other external manner. They may be predefined exceptions that were provided by another interface, or exceptions that are defined and initialized explicitly by the application itself.
If the extern_exceptions attribute appears without parameters, it specifies all IDL-defined exceptions.
The heap attribute specifies that the server copy of the parameter or parameter of the type so specified will always be allocated in heap memory, rather than on the stack.
Any identifier occurring as a parameter name within an operation declaration in the ACS source must also be a parameter name within the corresponding operation declaration in IDL.
The heap attribute is ignored for pipes, context handles, and scalars.
The enable_allocate attribute causes the stub to initialise stub memory management in conditions where it otherwise would not do so. It has no effect if the stub would perform the initialisation for other reasons.
Five attributes-cs_char, cs_stag,
cs_drtag, cs_rtag and cs_tag_rtn-are available for
use in conjunction with the automatic code set conversion routines to
provide a mechanism for ensuring character and code set interoperability
between clients and servers transferring characters not contained in
the Portable Character Set (PCS). (For information on the code set
conversion routines see
The cs_char attribute associates a local data type with a data type defined in the IDL source. This permits, during marshalling and umarshalling, the conversion of characters, arrays of characters, and strings of characters between the format in which application code uses them and the format in which they are transmitted over the network. The data is automatically converted between the local data type in the local code set encoding and the byte data type in the network code set encoding. The network code set is the code set encoding that the application code, through the use of the DCE RPC automatic code set conversion routines, has selected to use when transmitting the international characters over the network.
The cs_char attribute does not affect the network contract between client and server. Multiple data items (for example, the characters of an array or string) can be converted with a single stub call to user-written conversion code. The conversion can modify array size and data limit information between what is transmitted over the network and what is used by application code.
The local data type is defined in either the IDL source or an application header file. If it is not defined in the IDL source, the ACS must contain an include statement to make its definition available to the stubs.
The network data type is defined in the IDL source. When the cs_char attribute is used, this data type is always byte.
The cs_char attribute requires the following stub support routines for each local date type defined:
Buffer sizing and code set conversion routines are provided for the cs_byte and wchar_t data types. The cs_byte data type is equivalent to the byte type, while the wchar_t data type is a platform-dependent data type whose range of values can represent encodings for all members of the largest international character set that exists within the set of character/code sets supported on a host.
Buffer sizing and code set conversion routines must
follow specific signatures. See
The cs_char attribute cannot be applied to the base type of a pipe or to a type used in constructing the base type of a pipe.
The cs_char attribute cannot be applied to a type if there is an array that has this type as a base type and the array has more than one dimension, or if the attributes min_is, max_is, first_is, last_is, or string have been applied to the array. As a result, all instances of the type to which cs_char has been applied must be scalars or one-dimensional arrays. Only the length_is and/or size_is attributes can be applied to these arrays.
The following restrictions apply to the use of variables that appear in array attributes:
The cs_char attribute cannot interact with the transmit_as or represent_as attributes. This restriction imposes the following rules:
The cs_char attribute cannot be applied to any type that is the type of the referent of a pointer that has a max_is or size_is attribute applied to it. It also cannot be applied to the base type of an array parameter that has the unique or ptr attribute applied to it.
Arrays of cs_char can be fixed, varying, conformant, or conformant varying. The treatment of a scalar cs_char is similar to that of a fixed array of one element.
The number of array elements in the local and network representations of the data must be the same as the array size stated in the IDL source. Neither the number of array elements in the local representation nor the number of array elements in the network representation may exceed the array size in the IDL.
The number of array elements in the local representation and the number of array elements in the network representation need not be the same. The maximum number of array elements in the local representation and the maximum number of array elements in the network representation need not be the same.
The cs_stag, cs_drtag, and cs_rtag attributes are parameter ACS attributes that correspond to the sending tag, desired receiving tag, and receiving tag parameters defined in operations in the IDL source that handle international character data. These operation parameters tag international characters being passed in the operation's input and output parameters with code set identifying information. The cs_stag, cs_drtag, and cs_rtag attributes declare the tag parameters in the corresponding operation definition to be special code set parameters.
The cs_stag attribute identifies the code set used when the client sends international characters to the server. Operations defined in the IDL source that specify international characters in in parameters must use the cs_stag attribute in the associated ACS.
The cs_drtag attribute identifies the code set the client would like the server to use when returning international characters.
The cs_rtag attribute identifies the code set that is actually used when the server sends international characters to the client. Operations defined in the IDL file that specify international characters in out parameters must apply the cs_rtag attribute in the associated ACF.
The optional cs_tag_rtn attribute specifies the name of a routine that the client and server stubs will call to set an operation's code set tag parameters to specific code set values. The rpc_cs_get_tags() routine or a user-provided routine may be specified.
The generated header file includes a function prototype for the specified routine. If an operation that transfers international character data has the cs_tag_rtn attribute applied to it in the corresponding ACS, the code set tag parameters will not appear in the operation's definition within the generated header file. If the cs_tag_rtn attribute is not used, the operation's caller must provide appropriate values to the operation's code set tag parameters before international character data is marshalled.
When used as an ACF interface attribute, the cs_tag_rtn attribute applies to all operations defined in the corresponding IDL source. When used as an ACF operation attribute, the cs_tag_rtn attribute applies only to the operation you specify.
The specified routine name
must be distinct from any type name, procedure name, constant name,
or enumeration name appearing in the interface definition.
It must also have a specific calling signature. See
When the tag-setting routine is called from a client stub, it is called before any in parameters are marshalled. When called from a server stub, it is called before any out parameters are marshalled.
The following sections give a synopsis of the IDL grammar for quick
This section provides a synopsis of the IDL productions discussed in
(1) <interface> ::= <interface_header> { <interface_body> }
(2) <interface_header> ::= <[> <interface_attributes> <]> interface
<Identifier>
(3) <interface_attributes> ::= <interface_attribute>
[ , <interface_attribute> ] ...
(4) <interface_attribute> ::= uuid ( <Uuid_rep> )
| version ( <Integer_literal>[.<Integer_literal>])
| endpoint ( <port_spec> [ , <port_spec> ] ... )
| exceptions ( <excep_name> [ , <excep_name> ] ... )
| local
| pointer_default ( <ptr_attr> )
(5) <port_spec> ::= <Family_string> : <[> <Port_string> <]>
(5.01) <excep_name> ::= <Identifier>
(6) <interface_body> ::= [ <import> ... ] <interface_component>
[ <interface_component> ... ]
(7) <import> ::= import <import_list> ;
(8) <interface_component> ::= <export> | <op_declarator> ;
(9) <export> ::= <type_declarator> ;
| <const_declarator> ;
| <tagged_declarator> ;
(10) <import_list> ::= <import_name> [ , <import_name> ] ...
(11) <import_name> ::= "<Import_string>"
(12) <const_declarator> ::= const <const_type_spec> <Identifier> = <const_exp>
(13) <const_type_spec> ::= <primitive_integer_type>
| char
| boolean
| void *
| char *
(14) <const_exp> ::= <integer_const_exp>
| <Identifier>
| <string>
| <character_constant>
| NULL
| TRUE
| FALSE
(14.01) <integer_const_exp> ::= <conditional_exp>
(14.02) <conditional_exp> ::= <logical_or_exp>
| <logical_or_exp> ? <integer_const_exp> : <conditional_exp>
(14.03) <logical_or_exp> ::= <logical_and_exp>
| <logical_or_exp> <||> <logical_and_exp>
(14.04) <logical_and_exp> ::= <inclusive_or_exp>
| <logical_and_exp> && <inclusive_or_exp>
(14.05) <inclusive_or_exp> ::= <exclusive_or_exp>
| <inclusive_or_exp> <|> <exclusive_or_exp>
(14.06) <exclusive_or_exp> ::= <and_exp>
| <exclusive_or_exp> ^ <and_exp>
(14.07) <and_exp> ::= <equality_exp>
| <and_exp> & <equality_exp>
(14.08) <equality_exp> ::= <relational_exp>
| <equality_exp> == <relational_exp>
| <equality_exp> != <relational_exp>
(14.09) <relational_exp> ::= <shift_exp>
| <relational_exp> <<> <shift_exp>
| <relational_exp> <>> <shift_exp>
| <relational_exp> <<=> <shift_exp>
| <relational_exp> <>=> <shift_exp>
(14.10) <shift_exp> ::= <additive_exp>
| <shift_exp> <<<> <additive_exp>
| <shift_exp> <>>> <additive_exp>
(14.11) <additive_exp> ::= <multiplicative_exp>
| <additive_exp> + <multiplicative_exp>
| <additive_exp> - <multiplicative_exp>
(14.12) <multiplicative_exp> ::= <unary_exp>
| <multiplicative_exp> * <unary_exp>
| <multiplicative_exp> / <unary_exp>
| <multiplicative_exp> % <unary_exp>
(14.13) <unary_exp> ::= <primary_exp>
| + <primary_exp>
| - <primary_exp>
| ~ <primary_exp>
| ! <primary_exp>
(14.14) <primary_exp> ::= <Integer_literal>
| <Identifier>
| '(' <const_exp> ')'
(15) <string> ::= "[<Character>] ... "
(16) <character_constant> ::= '<Character>'
(17) <type_declarator> ::= typedef [ <type_attribute_list> ] <type_spec>
<declarators>
(18) <type_attribute_list> ::= <[> <type_attribute>
[ , <type_attribute> ] ... <]>
(19) <type_spec> ::= <simple_type_spec>
| <constructed_type_spec>
(20) <simple_type_spec> ::= <base_type_spec>
| <predefined_type_spec>
| <Identifier>
(21) <declarators> ::= <declarator> [ , <declarator> ] ...
(23) <declarator> ::= <pointer_opt> <direct_declarator>
(24) <direct_declarator> ::= <Identifier>
| ( <declarator> )
| <array_declarator>
| <function_declarator>
(26) <tagged_declarator> ::= <tagged_struct_declarator>
| <tagged_union_declarator>
(27) <base_type_spec> ::= <floating_pt_type>
| <integer_type>
| <char_type>
| <boolean_type>
| <byte_type>
| <void_type>
| <handle_type>
(28) <floating_pt_type> ::= float
| double
(29) <integer_type> ::= <primitive_integer_type>
| hyper [unsigned] [int]
| unsigned hyper [int]
(29.1) <primitive_integer_type> ::= <signed_integer>
| <unsigned_integer>
(30) <signed_integer> ::= <integer_size> [ int ]
(31) <unsigned_integer> ::= <integer_size> unsigned [ int ]
| unsigned <integer_size> [ int ]
(32) <integer_size> ::= long
| short
| small
(33) <char_type> ::= [ unsigned ] char
(34) <boolean_type> ::= boolean
(35) <byte_type> ::= byte
(36) <void_type> ::= void
(37) <handle_type> ::= handle_t
(38) <constructed_type_spec> ::= <struct_type>
| <union_type>
| <enumeration_type>
| <tagged_declarator>
| <pipe_type>
(39) <tagged_struct_declarator> ::= struct <tag>
| <tagged_struct>
(40) <struct_type> ::= struct { <member_list> }
(41) <tagged_struct> ::= struct <tag> { <member_list> }
(42) <tag> ::= <Identifier>
(43) <member_list> ::= <member> [ <member> ] ...
(44) <member> ::= <field_declarator> ;
(45) <field_declarator> ::= [ <field_attribute_list> ] <type_spec>
<declarators>
(46) <field_attribute_list> ::= <[> <field_attribute>
[ , <field_attribute> ] ... <]>
(47) <tagged_union_declarator> ::= union <tag>
| <tagged_union>
(48) <union_type> ::= union <union_switch> { <union_body> }
| union { <union_body_n_e> }
(48.1) <union_switch> ::= switch ( <switch_type_spec> <Identifier> )
[ <union_name> ]
(49) <switch_type_spec> ::= <primitive_integer_type>
| <char_type>
| <boolean_type>
| <Identifier>
(50) <tagged_union> ::= union <tag> <union_switch> { <union_body> }
| union <tag> { <union_body_n_e> }
(51) <union_name> ::= <Identifier>
(52) <union_body> ::= <union_case> [ <union_case> ] ...
(52.1) <union_body_n_e> ::= <union_case_n_e> [ <union_case_n_e> ] ...
(53) <union_case> ::= <union_case_label> [ <union_case_label> ] ...
<union_arm>
| <default_case>
(53.1) <union_case_n_e> ::= <union_case_label_n_e> <union_arm>
| <default_case_n_e>
(54) <union_case_label> ::= case <const_exp> :
(54.1) <union_case_label_n_e> ::= <[> case ( <const_exp>
[ , <const_exp> ] ... ) <]>
(55) <default_case> ::= default : <union_arm>
(55.1) <default_case_n_e> ::= <[> default <]> <union_arm>
(55.2) <union_arm> ::= [ <field_declarator> ] ;
(55.3) <union_type_switch_attr> ::= switch_type ( <switch_type_spec> )
(55.4) <union_instance_switch_attr> ::= switch_is ( <attr_var> )
(57) <enumeration_type> ::= enum { <Identifier> [ , <Identifier> ] ... }
(58) <pipe_type> ::= pipe <type_spec>
(59) <array_declarator> ::= <direct_declarator> <array_bounds_declarator>
(61) <array_bounds_declarator> ::= <[> [ <array_bound> ] <]>
| <[> <array_bounds_pair> <]>
(62) <array_bounds_pair> ::= <array_bound> .. <array_bound>
(63) <array_bound> ::= *
| <integer_const_exp>
| <Identifier>
(64) <type_attribute> ::= transmit_as ( <xmit_type> )
| handle
| <usage_attribute>
| <union_type_switch_attr>
| <ptr_attr>
(65) <usage_attribute> ::= string
| context_handle
(66) <xmit_type> ::= <simple_type_spec>
(67) <field_attribute> ::= first_is ( <attr_var_list> )
| last_is ( <attr_var_list> )
| length_is ( <attr_var_list> )
| min_is ( <attr_var_list> )
| max_is ( <attr_var_list> )
| size_is ( <attr_var_list> )
| <usage_attribute>
| <union_instance_switch_attr>
| ignore
| <ptr_attr>
(68) <attr_var_list> ::= <attr_var> [ , <attr_var> ] ...
(69) <attr_var> ::= [ [ * ] <Identifier> ]
(70) <pointer_opt> ::= [<pointer>]
(70.1) <ptr_attr> ::= ref
| unique
| ptr
(70.2) <pointer> ::= *...
(71) <op_declarator> ::= [ <operation_attributes> ]
<simple_type_spec> <Identifier> <param_declarators>
(72) <operation_attributes> ::= <[> <operation_attribute>
[ , <operation_attribute> ] ... <]>
(73) <operation_attribute> ::= idempotent
| broadcast
| maybe
| reflect_deletions
| <usage_attribute>
| <ptr_attr>
(74) <param_declarators> ::= ( [ <param_declarator>
[ , <param_declarator> ] ... ] )
| ( void )
(75) <param_declarator> ::= <param_attributes> <type_spec> <declarator>
(76) <param_attributes> ::= <[> <param_attribute>
[ , <param_attribute> ] ... <]>
(77) <param_attribute> ::= <directional_attribute>
| <field_attribute>
(78) <directional_attribute> ::= in
| out
(79) <function_declarator> ::= <direct_declarator> <param_declarators>
(80) <predefined_type_spec> ::= error_status_t
| <international_character_type>
(81) <international_character_type> ::= ISO_LATIN_1
| ISO_MULTI_LINGUAL
| ISO_UCS
| Production Name | Number | Used In |
|---|---|---|
| <additive_exp> | 14.11 | 14.10 |
| <and_exp> | 14.07 | 14.06 |
| <array_bound> | 63 | 61 62 |
| <array_bounds_declarator> | 61 | 59 |
| <array_bounds_pair> | 62 | 61 |
| <array_declarator> | 59 | 24 |
| <attr_var> | 69 | 55.4 68 |
| <attr_var_list> | 68 | 67 |
| <base_type_spec> | 27 | 20 |
| <boolean_type> | 34 | 27 49 |
| <byte_type> | 35 | 27 |
| <char_type> | 33 | 27 49 |
| <Character> | Terminal | 15 16 |
| <character_constant> | 16 | 14 |
| <conditional_exp> | 14.02 | 14.01 |
| <const_declarator> | 12 | 9 |
| <const_exp> | 14 | 12 14.14 54 54.1 |
| <const_type_spec> | 13 | 12 |
| <constructed_type_spec> | 38 | 19 |
| <declarator> | 23 | 21 24 75 |
| <declarators> | 21 | 17 45 |
| <default_case> | 55 | 53 |
| <default_case_n_e> | 55.1 | 53.1 |
| <direct_declarator> | 24 | 23 59 79 |
| <directional_attribute> | 78 | 77 |
| <enumeration_type> | 57 | 38 |
| <equality_exp> | 14.08 | 14.07 |
| <excep_name> | 5.01 | 4 |
| <exclusive_or_exp> | 14.06 | 14.05 |
| <export> | 9 | 8 |
| <Family_string> | Terminal | 5 |
| <field_attribute> | 67 | 46 77 |
| <field_attribute_list> | 46 | 45 |
| <field_declarator> | 45 | 44 55.2 |
| <floating_pt_type> | 28 | 27 |
| <function_declarator> | 79 | 24 |
| <handle_type> | 37 | 27 |
| <Import_string> | Terminal | 11 |
| <Identifier> | Terminal | 2 5.01 12 14 14.14 20 24 42 48.1 49 51 57 63 69 71 |
| <import> | 7 | 6 |
| <import_list> | 10 | 7 |
| <import_name> | 11 | 10 |
| <inclusive_or_exp> | 14.05 | 14.04 |
| <integer_const_exp> | 14.01 | 14 14.02 63 |
| <Integer_literal> | Terminal | 4 14.14 |
| <integer_size> | 32 | 30 31 |
| <integer_type> | 29 | 27 |
| <interface> | 1 | GOAL |
| <interface_attribute> | 4 | 3 |
| <interface_attributes> | 3 | 2 |
| <interface_body> | 6 | 1 |
| <interface_component> | 8 | 6 |
| <interface_header> | 2 | 1 |
| <international_character_type> | 81 | 80 |
| <logical_and_exp> | 14.04 | 14.03 |
| <logical_or_exp> | 14.03 | 14.02 |
| <member> | 44 | 43 |
| <member_list> | 43 | 40 41 |
| <multiplicative_exp> | 14.12 | 14.11 |
| <op_declarator> | 71 | 8 |
| <operation_attribute> | 73 | 72 |
| <operation_attributes> | 72 | 71 |
| <param_attribute> | 77 | 76 |
| <param_attributes> | 76 | 75 |
| <param_declarator> | 75 | 74 |
| <param_declarators> | 74 | 71 79 |
| <pipe_type> | 58 | 38 |
| <pointer> | 70.2 | 70 |
| <pointer_opt> | 70 | 23 |
| <port_spec> | 5 | 4 |
| <Port_string> | Terminal | 5 |
| <predefined_type_spec> | 80 | 20 |
| <primary_exp> | 14.14 | 14.13 |
| <primitive_integer_type> | 29.1 | 13 29 49 |
| <ptr_attr> | 70.1 | 4 64 67 73 |
| <relational_exp> | 14.09 | 14.08 |
| <shift_exp> | 14.10 | 14.09 |
| <signed_integer> | 30 | 29.1 |
| <simple_type_spec> | 20 | 19 66 71 |
| <string> | 15 | 14 |
| <struct_type> | 40 | 38 |
| <switch_type_spec> | 49 | 48.1 55.3 |
| <tag> | 42 | 39 41 47 50 |
| <tagged_declarator> | 26 | 9 38 |
| <tagged_struct> | 41 | 39 |
| <tagged_struct_declarator> | 39 | 26 |
| <tagged_union> | 50 | 47 |
| <tagged_union_declarator> | 47 | 26 |
| <type_attribute> | 64 | 18 |
| <type_attribute_list> | 18 | 17 |
| <type_declarator> | 17 | 9 |
| <type_spec> | 19 | 17 45 58 75 |
| <unary_exp> | 14.13 | 14.12 |
| <union_arm> | 55.2 | 53 53.1 55 55.1 |
| <union_body> | 52 | 48 50 |
| <union_body_n_e> | 52.1 | 48 50 |
| <union_case> | 53 | 52 |
| <union_case_n_e> | 53.1 | 52.1 |
| <union_case_label> | 54 | 53 |
| <union_case_label_n_e> | 54.1 | 53.1 |
| <union_instance_switch_attr> | 55.4 | 67 |
| <union_name> | 51 | 48.1 |
| <union_switch> | 48.1 | 48 50 |
| <union_type> | 48 | 38 |
| <union_type_switch_attr> | 55.3 | 64 |
| <unsigned_integer> | 31 | 29.1 |
| <usage_attribute> | 65 | 64 67 73 |
| <Uuid_rep> | Terminal | 4 |
| <void_type> | 36 | 27 |
| <xmit_type> | 66 | 64 |
| Max | ||
|---|---|---|
| Class of ID | Constructed IDs | Length |
| Interface name | <interface>_v<major_version>_<minor_version>_c_ifspec | 17 |
| <interface>_v<major_version>_<minor_version>_s_ifspec | ||
| <interface>_v<major_version>_<minor_version>_epv_t | ||
| <interface>_v<major_version>_<minor_version>_c_epv | ||
| <interface>_v<major_version>_<minor_version>_s_epv | ||
| Type with | <type_id>_to_xmit | 21 |
| transmit_as | <type_id>_from_xmit | |
| attribute | <type_id>_free_inst | |
| <type_id>_free_xmit | ||
| Type with | <type_id>_bind | 24 |
| handle | <type_id>_unbind | |
| attribute | ||
| Type with | <type_id>_rundown | 23 |
| context_handle | ||
| attribute | ||
| Type with | <type_id>_to_local | 20 |
| represent_as | <type_id>_from_local | |
| attribute | <type_id>_free_inst | |
| <type_id>_free_local |
Reserved words are keywords of the language that must not be used as user identifiers. IDL reserved words are given in the following list:
| boolean | byte | case | char |
| const | default | double | enum |
| FALSE | float | handle_t | hyper |
| import | int | interface | long |
| NULL | pipe | short | small |
| struct | switch | TRUE | typedef |
| union | unsigned | void |
The following list gives the IDL keywords that are reserved when in the context of an attribute: that is, between [] (brackets):
| broadcast | case | context_handle | endpoint |
| exceptions | first_is | handle | idempotent |
| ignore | in | last_is | length_is |
| local | max_is | maybe | min_is |
| out | ptr | pointer_default | ref |
| reflect_deletions | size_is | string | switch_is |
| switch_type | transmit_as | unique | uuid |
| version |
The following are ACS reserved words: include, interface, typedef.
The following list gives the ACS keywords that are reserved when in the context of an attribute: that is, between [] (brackets):
| auto_handle | binding_callout | code | comm_status |
| cs_char | cs_drtag | cs_rtag | cs_stag |
| cs_tag_rtn | enable_allocate | extern_exceptions | explicit_handle |
| fault_status | heap | implicit_handle | nocode |
| represent_as |
[??] Some characters or strings that appear in the printed document are not easily representable using HTML.
Please note that the html version of this specification may contain formatting aberrations. The definitive version is available as an electronic publication on CD-ROM from The Open Group.
| Contents | Next section | Index |