Files Reference

XCOFF Object File Format

Purpose

The extended common object file format (XCOFF) is the object file format for the operating system. XCOFF combines the standard common object file format (COFF) with the TOC module format concept, which provides for dynamic linking and replacement of units within an object file. In AIX 4.3, XCOFF has been extended to provide for 64-bit object files and executable files.

XCOFF is the formal definition of machine-image object and executable files. These object files are produced by language processors (assemblers and compilers) and binders, and are used primarily by binders and the system loaders.

The default name for an XCOFF executable file is a.out.

Note: This information lists bits in big-endian order.

Read the following information to learn more about XCOFF object files:

• Composite File Header
• Sections and Section Headers
• Relocation Information for XCOFF File (reloc.h)
• Line Number Information for XCOFF File (linenum.h)
• Symbol Table Information
• dbx Stabstrings

Writing Applications that Use XCOFF Declarations

Programs can be written to understand 32-bit XCOFF files, 64-bit XCOFF files, or both. The programs themselves may be compiled in 32-bit mode or 64-bit mode to create 32-bit or 64-bit programs. By defining preprocessor macros, applications can select the proper structure definitions from the XCOFF header files.

Note: This document uses "XCOFF32" and "XCOFF64" as shorthand for "32-bit XCOFF" and "64-bit XCOFF", respectively.

Selecting XCOFF32 Declarations

To select the XCOFF32 definitions, an application merely needs to include the appropriate header files. Only XCOFF32 structures, fields, and preprocessor defines will be included. Structure names and field names will match those in previous versions of the operating system, so existing programs can be recompiled without change.

Note: Existing uses of shorthand type notation (e.g., UINT, ULONG) have been removed.

Selecting XCOFF64 Declarations

To select the XCOFF64 definitions, an application should define the preprocessor macro __XCOFF64__. When XCOFF header files are included, the structures, fields, and preprocessor defines for XCOFF64 will be included. Where possible, the structure names and field names are identical to the XCOFF32 names, but field sizes and offsets may differ.

Selecting Both XCOFF32 and XCOFF64 Declarations

To select structure definitions for both XCOFF32 and XCOFF64, an application should define both the preprocessor macros __XCOFF32__ and __XCOFF64__. This will define structures for both kinds of XCOFF files. Structures and typedef names for XCOFF64 files will have the suffix "_64" added to them. (Consult the header files for details.)

Selecting Hybrid XCOFF Declarations

An application may choose to select single structures that contain field definitions for both XCOFF32 and XCOFF64 files. For fields that have the same size and offset in both XCOFF32 and XCOFF64 definitions, the field names are retained. For fields whose size or offset differ between XCOFF32 and XCOFF64 definitions, the XCOFF32 fields have a "32" suffix, while the XCOFF64 fields have a "64" suffix. To select hybrid structure definitions, an application should define the preprocessor macro __XCOFF_HYBRID__. For example, the symbol table definition (in /usr/include/syms.h) will have the names n_offset32 and n_offset64, which should be used for the 32-bit XCOFF and 64-bit XCOFF respectively.

Understanding XCOFF

Assemblers and compilers produce XCOFF object files as output. The binder combines individual object files into an XCOFF executable file. The system loader reads an XCOFF executable file to create an executable memory image of a program. The symbolic debugger reads an XCOFF executable file to provide symbolic access to functions and variables of an executable memory image.

An XCOFF file contains the following parts:

• A composite header consisting of:
  • A file header
  • An optional auxiliary header
  • Section headers, one for each of the file's raw-data sections
• Raw-data sections, at most one per section header
• Optional relocation information for individual raw-data sections
• Optional line number information for individual raw-data sections
• An optional symbol table
• An optional string table, which is used for all symbol names in XCOFF64 and for symbol names longer than 8 bytes in XCOFF32.

Not every XCOFF file contains every part. A minimal XCOFF file contains only the file header.

Object and Executable Files

XCOFF object files and executable files are similar in structure. An XCOFF executable file (or "module") must contain an auxiliary header, a loader section header, and a loader section.

The loader raw-data section contains information needed to dynamically load a module into memory for execution. Loading an XCOFF executable file into memory creates the following logical segments:

• A text segment (initialized from the .text section of the XCOFF file).
• A data segment, consisting of initialized data (initialized from the .data section of the XCOFF file) followed by uninitialized data (initialized by the system loader to 0). The length of uninitialized data is specified in the .bss section header of the XCOFF file.

The XCOFF file Organization illustrates the structure of the XCOFF object file.

XCOFF Header Files

The xcoff.h file defines the structure of the XCOFF file. The xcoff.h file includes the following files:

The a.out.h file includes the xcoff.h file. All of the XCOFF include files include the xcoff32_64.h file.

For more information on sections of the XCOFF object file, see "Sections and Section Headers." For more information on the symbol table, see "Symbol Table Information." For more information on the string table, see "String Table." For more information on the Debug section, see "Debug Section."

Composite File Header

The following sections describe the XCOFF composite file header components:

• File Header (filehdr.h)
• Auxiliary Header (aouthdr.h)
• Section Headers (scnhdr.h)

File Header (filehdr.h)

The filehdr.h file defines the file header of an XCOFF file. The file header is 20 bytes long in XCOFF32 and 24 bytes long in XCOFF64. The structure contains the fields shown in the following table.

Field Definitions

Auxiliary Header (aouthdr.h)

The auxiliary header contains system-dependent and implementation-dependent information, which is used for loading and executing a module. Information in the auxiliary header minimizes how much of the file must be processed by the system loader at execution time.

The binder generates an auxiliary header for use by the system loader. Auxiliary headers are not required for an object file that is not to be loaded. When auxiliary headers are generated by compilers and assemblers, the headers are ignored by the binder.

The auxiliary header immediately follows the file header.

Note: If the value of the f_opthdr field is 0, the auxiliary header does not exist.

The C language structure for the auxiliary header is defined in the aouthdr.h file. The auxiliary header contains the fields shown in the following table.

Field Definitions

The following information defines the auxiliary header fields. For entries with two labels, the label in parentheses is the alternate original COFF a.out file format name.

Section_offset_value=o_entry-s_paddr[o_snentry - 1],

The following definitions are extensions used by the system loader. In general, an object file may contain multiple sections of a given type, but in a module, only a single occurrence of the .text, .data, .bss, and .loader sections may exist.

Section Headers (scnhdr.h)

Each section of an XCOFF file has a corresponding section header, although some section headers may not have a corresponding raw-data section. A section header provides identification and file-accessing information for each section contained within an XCOFF file. Each section header in an XCOFF32 file is 40 bytes long, while XCOFF64 section headers are 72 bytes long. The C language structure for a section header can be found in the scnhdr.h file. A section header contains the fields shown in the following table.

Field Definitions

The following information defines the section header fields:

s_name

Specifies an 8-byte, null-padded section name. An 8-byte section name will not have a terminating null character. Use the s_flags field instead of the s_name field to determine a section type. Two sections of the same type may have different names, allowing certain applications to distinguish between them.

s_paddr

Specifies the physical address of the section. This is the address assigned and used by the compilers and the binder for the first byte of the section. This field should contain 0 for all sections except the .text , .data , and .bss sections.

s_vaddr

Specifies the virtual address of the section. This field has the same value as the s_paddr field.

s_size

Specifies the size (in bytes) of this section.

s_scnptr

Specifies a file pointer (byte offset from the beginning of the file) to this section's raw data. If this field contains 0, this section has no raw data. Otherwise, the size of the raw data must be contained in the s_size field.

s_relptr

Specifies a file pointer (byte offset from the beginning of the file) to the relocation entries for this section. If this section has no relocation entries, this field must contain 0.

s_lnnoptr

Specifies a file pointer (byte offset from the beginning of the file) to the line number entries for this section. If this section has no line number entries, this field must contain 0.

s_nreloc

Specifies the number of relocation entries for this section. In an XCOFF32 file, if more than 65,534 relocation entries are required, the field value will be 65535, and an STYP_OVRFLO section header will contain the actual count of relocation entries in the s_paddr field. Refer to the discussion of overflow headers in "Sections and Section Headers" . If this field is set to 65535, the s_nlnno field must also be set to 65535.

s_nlnno

Specifies the number of line number entries for this section. In an XCOFF32 file, if more than 65,534 line number entries are required, the field value will be 65535, and an STYP_OVRFLO section header will contain the actual number of line number entries in the s_vaddr field. Refer to the discussion of overflow headers in "Sections and Section Headers" . If this field is set to 65535, the s_nreloc field must also be set to 65535.

s_flags

Specifies flags defining the section type. The low-order pair of bytes is used. A section type identifies the contents of a section and specifies how the section is to be processed by the binder or the system loader. Only a single bit value may be assigned to the s_flags field. This value must not be the sum or bitwise OR of multiple flags. The two high-order bytes should contain 0.

Valid bit values are:

Value

Flag

0x0000

Reserved.

0x0001

Reserved.

0x0002

Reserved.

0x0004

Reserved.

0x0008

STYP_PAD

Specifies a pad section. A section of this type is used to provide alignment padding between sections within an XCOFF executable object file. This section header type is obsolete since padding is allowed in an XCOFF file without a corresponding pad section header.

0x0010

Reserved.

0x0020

STYP_TEXT

Specifies an executable text (code) section. A section of this type contains the executable instructions of a program.

0x0040

STYP_DATA

Specifies an initialized data section. A section of this type contains the initialized data and the TOC of a program.

0x0080

STYP_BSS

Specifies an uninitialized data section. A section header of this type defines the uninitialized data of a program.

0x0100

STYP_EXCEPT

Specifies an exception section. A section of this type provides information to identify the reason that a trap or exception occurred within an executable object program.

0x0200

STYP_INFO

Specifies a comment section. A section of this type provides comments or data to special processing utility programs.

0x0400

Reserved.

0x0800

Reserved.

0x1000

STYP_LOADER

Specifies a loader section. A section of this type contains object file information for the system loader to load an XCOFF executable. The information includes imported symbols, exported symbols, relocation data, type-check information, and shared object names.

0x2000

STYP_DEBUG

Specifies a debug section. A section of this type contains stabstring information used by the symbolic debugger.

0x4000

STYP_TYPCHK

Specifies a type-check section. A section of this type contains parameter/argument type-check strings used by the binder.

0x8000

STYP_OVRFLO

Note: An XCOFF64 file may not contain an overflow section header.

Specifies a relocation or line-number field overflow section. A section header of this type contains the count of relocation entries and line number entries for some other section. This section header is required when either of the counts exceeds 65,534. See the s_nreloc and s_nlnno fields in "Sections and Section Headers" for more information on overflow headers.

 

For general information on the XCOFF file format, see "XCOFF Object (a.out) File Format."

Sections and Section Headers

Section headers are defined to provide a variety of information about the contents of an XCOFF file. Programs that process XCOFF files will recognize only some of the valid sections.

See the following information to learn more about XCOFF file sections:

• Loader Section (loader.h)
• Debug Section
• Type-Check Section
• Exception Section
• Comment Section

Current applications do not use the s_name field to determine the section type. Nevertheless, conventional names are used by system tools, as shown in the following table.

Some fields of a section header may not always be used, or may have special usage. This pertains to the following fields:

An XCOFF file provides special meaning to the following sections:

• The .text, .data, and .bss sections define the memory image of the program. The relocation parts associated with the .text and .data sections contain the full binder relocation information so it can be used for replacement link editing. Only the .text section is associated with a line number part. The parts associated with the executable code are produced by the compilers and assemblers.
• The .pad section is defined as a null-filled, raw-data section that is used to align a subsequent section in the file on some defined boundary such as a file block boundary or a system page boundary. Padding is allowed in an XCOFF file without a corresponding section header.
• The .loader section is a raw-data section defined to contain the dynamic loader information. This section is generated by the binder and has its own self-contained symbol table and relocation table. There is no reference to this section from the XCOFF Symbol Table.
• The .debug section is a raw-data section defined to contain the stab (symbol table) or dictionary information required by the symbolic debugger.
• The .typchk section is a raw-data section defined to contain parameter and argument type-checking strings.
• The .except section is a raw-data section defined to contain the exception tables used to identify the reasons for an exception in program execution.
• The .info comment section is a raw-data section defined to contain comments or data that are of significance to special processing utility programs.
• The .debug, .except, .info, and .typchk sections are produced by compilers and assemblers. References to these sections or to items within these sections are made from the XCOFF Symbol Table.

For more information on XCOFF file sections, see "Loader Section (loader.h)," "Debug Section," "Type-Check Section," "Exception Section," and "Comment Section."

Loader Section (loader.h)

The loader section contains information required by the system loader to load and relocate an executable XCOFF object. The loader section is generated by the binder. The loader section has an s_flags section type flag of STYP_LOADER in the XCOFF section header. By convention, .loader is the loader section name. The data in this section is not referenced by entries in the XCOFF symbol table.

The loader section consists of the following parts:

• Header fields
• Symbol table
• Relocation table
• Import file ID strings
• Symbol name string table

The C language structure for the loader section can be found in the loader.h file.

Loader Header Field Definitions

The following table describes the loader section's header field definitions.

The following information defines the loader section's header fields:

Loader Symbol Table Field Definitions

The loader section symbol table contains the symbol table entries that the system loader needs for its import and export symbol processing and dynamic relocation processing.

The loader.h file defines the symbol table fields. Each entry is 24 bytes long.

There are three implicit external symbols, one each for the .text, .data, and .bss sections. These symbols are referenced using symbol table index values 0, 1, and 2, respectively. The first symbol contained in the loader section symbol table is referenced using an index value of 3.

The symbol table fields are:

Bit 0     0x80  Reserved.
Bit 1     0x40  Specifies an imported symbol.
Bit 2     0x20  Specifies an entry point descriptor symbol.
Bit 3     0x10  Specifies an exported symbol.
Bit 4     0x08  Reserved.
Bits 5-7  0x07  Symbol type--see below.

l_smclas

l_ifile

l_parm

Loader Relocation Table Field Definitions

The Loader Section Relocation Table Structure contains all the relocation information that the system loader needs to properly relocate an executable XCOFF file when it is loaded. The loader.h file defines the relocation table fields. Each entry in the loader section relocation table is 12 bytes long in XCOFF32 and 16 bytes long in XCOFF64. The l_vaddr, l_symndx, and l_rtype fields have the same meaning as the corresponding fields of the regular relocation entries, which are defined in the reloc.h file. See "Relocation Information for XCOFF File (reloc.h)" for more information.

The loader.h file defines the following fields:

Loader Import File ID Name Table Definition

The loader section import file ID name strings of a module provide a list of dependent modules that the system loader must load in order for the module to load successfully. However, this list does not contain the names of modules that the named modules themselves depend on.

Each import file ID name consists of three null-delimited strings.

The first import file ID is a default LIBPATH value to be used by the system loader. The LIBPATH information consists of file paths separated by colons. There is no base name or archive member name, so the file path is followed by three null bytes.

Each entry in the import file ID name table consists of:

• Import file ID path name
• Null delimiter (ASCII Null Character)
• Import file ID base name
• Null delimiter
• Import file ID archive-file-member name
• Null delimiter

For example:

/usr/lib\0mylib.a\0shr.o\0

Loader String Table Definition

The loader section string table contains the parameter type-checking strings, all symbols names for an XCOFF64 file, and the names of symbols longer than 8 bytes for an XCOFF32 file. Each string consists of a 2-byte length field followed by the string.

Symbol names are null-terminated. The value in the length-field includes the length of the string plus the length of the null terminator but does not include the length of the length field itself.

The parameter type-checking strings contain binary values and are not null-terminated. The value in the length field includes the length of the string only but does not include the length of the length field itself.

The symbol table entries of the loader section contain a byte offset value that points to the first byte of the string instead of to the length field.

Loader Section Header Contents

The contents of the section header fields for the loader section are:

For general information on the XCOFF file format, see "XCOFF Object (a.out) File Format."

For more information on XCOFF file sections, see "Sections and Section Headers," "Debug Section," "Type-Check Section," "Exception Section," and "Comment Section."

Debug Section

The debug section contains the symbolic debugger stabstrings (symbol table strings). It is generated by the compilers and assemblers. It provides symbol attribute information for use by the symbolic debugger. The debug section has a section type flag of STYP_DEBUG in the XCOFF section header. By convention, .debug is the debug section name. The data in this section is referenced from entries in the XCOFF symbol table. A stabstring is a null-terminated character string. Each string is preceded by a 2-byte length field in XCOFF32 or a 4-byte length field in XCOFF64.

Field Definitions

The following two fields are repeated for each symbolic debugger stabstring:

• A 2-byte (XCOFF32) or 4-byte (XCOFF64) length field containing the length of the string. The value contained in the length field includes the length of the terminating null character but does not include the length of the length field itself.
• The symbolic debugger stabstring.

Refer to discussion of symbolic debugger stabstring grammar for the specific format of the stabstrings.

Debug Section Header Contents

The contents of the section header fields for the debug section are:

For general information on the XCOFF file format, see "XCOFF Object (a.out) File Format."

For more information on XCOFF file sections, see "Sections and Section Headers," "Debug Section," "Type-Check Section,", "Exception Section," and "Comment Section."

Type-Check Section

The type-check section contains the type-checking hash strings and is produced by compilers and assemblers. It is used by the binder to detect variable mismatches and argument interface errors when linking separately compiled object files. (The type-checking hash strings in the loader section are used to detect these errors prior to running a program.) The type-check section has a section type flag of STYP_TYPCHK in the XCOFF section header. By convention, .typchk is the type-check section name. The strings in this section are referenced from entries in the XCOFF symbol table.

Field Definitions

The following two fields are repeated for each parameter type-checking string:

• A 2-byte length field containing the length of the type-checking string. The value contained in the length field does not include the length of the length field itself.
• The parameter type-checking hash string.

Type Encoding and Checking Format for Data

The type-checking hash strings are used to detect errors prior to execution of a program. Information about all external symbols (data and functions) is encoded by the compilers and then checked for consistency at bind time and load time. The type-checking strings are designed to enforce the maximum checking required by the semantics of each particular language supported, as well as provide protection to applications written in more than one language.

The type encoding and checking mechanism features 4-part hash encoding that provides some flexibility in checking. The mechanism also uses a unique value, UNIVERSAL, that matches any code. The UNIVERSAL hash can be used as an escape mechanism for assembly programs or for programs in which type information or subroutine interfaces might not be known. The UNIVERSAL hash is four blank ASCII characters (0x20202020) or four null characters (0x00000000).

The following fields are associated with the type encoding and checking mechanism:

Section Header Contents

The contents of the section header fields for the type-check section are:

For general information on the XCOFF file format, see "XCOFF Object (a.out) File Format."

For more information on XCOFF file sections, see "Sections and Section Headers," "Debug Section," "Type-Check Section," "Exception Section," and "Comment Section."

Exception Section

The exception section contains addresses of trap instructions, source language identification codes, and trap reason codes. This section is produced by compilers and assemblers, and used during or after run time to identify the reason that a specific trap or exception occurred. The exception section has a section type flag of STYP_EXCEPT in the XCOFF section header. By convention, .except is the exception section name. Data in the exception section is referenced from entries in the XCOFF symbol table.

An exception table entry with a value of 0 in the e_reason field contains the symbol table index to a function's C_EXT or C_HIDEXT symbol table entry. Reference from the symbol table to an entry in the exception table is via the function auxiliary symbol table entry. For more information on this entry, see "csect Auxiliary Entry for C_EXT andC_HIDEXT Symbols" .

The C language structure for the exception section entries can be found in the exceptab.h file.

The exception section entries contain the fields shown in the following tables.

Field Definitions

The following defines the fields listed of the exception section:

Section Header Contents

The following fields are the contents of the section header fields for the exception section.

For general information on the XCOFF file format, see "XCOFF Object (a.out) File Format."

For more information on XCOFF file sections, see "Sections and Section Headers," "Debug Section," "Type-Check Section," "Exception Section," and "Comment Section."

Comment Section

The comment section contains information of special processing significance to an application. This section can be produced by compilers and assemblers and used during or after run time to fulfill a special processing need of an application. The comment section has a section type flag of STYP_INFO in the XCOFF section header. By convention, .info is the comment section name. Data in the comment section is referenced from C_INFO entries in the XCOFF symbol table.

The contents of a comment section consists of repeated instances of a 4-byte length field followed by a string of bytes (containing any binary value). The length of each string is stored in its preceding 4-byte length field. The string of bytes need not be terminated by a null character nor by any other special character. The specified length does not include the length of the length field itself. A length of 0 is allowed. The format of the string of bytes is not specified.

A comment section string is referenced from an entry in the XCOFF symbol table. The storage class of the symbol making a reference is C_INFO. See "Symbol Table Field Contents by Storage Class" for more information.

A C_INFO symbol is associated with the nearest C_FILE, C_EXT, or C_HIDEXT symbol preceding it.

Section Header Contents

The following fields are the contents of the section header fields for the comment section.

For general information on the XCOFF file format, see "XCOFF Object (a.out) File Format."

For more information on XCOFF file sections, see "Sections and Section Headers," "Debug Section," "Type-Check Section," "Exception Section," and "Comment Section."

Relocation Information for XCOFF File (reloc.h)

The .text section and .data section may have relocation information. The relocation information is used by the binder to modify the .text section and .data section contents with address and byte-offset information of individual XCOFF object files collected into an XCOFF executable file.

The compilers and assemblers are responsible for generating the relocation entries for the .text and .data sections.

The binder generates relocation information for the .loader section, as required by the system loader.

Each relocation entry of the .text and .data section is 10 bytes long (14 for XCOFF64). (A relocation entry in the .loader section is 12 bytes long (16 for XCOFF64) and is explained in the loader section description in this document. See "Relocation Table Field Definitions" for more information.) The C language structure for a relocation entry can be found in the reloc.h file. A relocation entry contains the fields shown in the following table.

The relocation entries for the .text and .data sections are part of their respective sections. The relocation entry refers to a location to be modified. The relocation entries for a section must be in ascending address order.

(The loader section contains a single set of relocation entries used by the system loader, so a section number is required within each relocation entry to identify the section that needs to be modified.)

Field Definitions

The following defines the relocation-information fields:

r_vaddr

Specifies the virtual address of the value that requires modification by the binder. The byte offset value to the data that requires modification from the beginning of the section that contains the data can be calculated as follows:

offset_in_section = r_vaddr - s_paddr

r_symndx

Specifies a zero-based index into the XCOFF symbol table for locating the referenced symbol. The symbol table entry contains an address used to calculate a modification value to be applied at the r_vaddr relocation address.

r_rsize

Specifies the relocation size and sign. Its contents are detailed in the following list:

0x80 (1 bit)

Indicates whether the relocation reference is signed (1) or unsigned (0).

0x40 (1 bit)

If this field is one, it indicates that the binder replaced the original instruction by a branch instruction to a special fixup instruction sequence.

0x3F(6 bits)

Specifies the bit length of the relocatable reference minus one. The current architecture allows for fields of up to 32 bits (XCOFF32) or 64 bits (XCOFF64) to be relocated.

 

r_rtype

Specifies an 8-bit relocation type field that indicates to the binder which relocation algorithm to use for calculating the modification value. This value is applied at the relocatable reference location specified by the r_vaddr field. The following relocation types are defined:

0x00

R_POS

Specifies positive relocation. Provides the address of the symbol specified by the r_symndx field.

0x01

R_NEG

Specifies negative relocation. Provides the negative of the address of the symbol specified by the r_symndx field.

0x02

R_REL

Specifies relative-to-self relocation. Provides a displacement value between the address of the symbol specified by the r_symndx field and the address of the csect to be modified.

0x03

R_TOC

Specifies relative-to-TOC relocation. Provides a displacement value that is the difference between the address value in the symbol specified by the r_symndx field and the address of the TOC anchor csect. The TOC anchor csect has a symbol table csect auxiliary entry with an x_smclass (storage mapping class) value of XMC_TC0. The TOC anchor csect must be of zero length. There may be only one TOC anchor csect per XCOFF section.

0x04

R_TRL

Specifies TOC Relative Indirect Load (modifiable) relocation. Provides a displacement value that is the difference between the address value in the symbol specified by the r_symndx field and the address of the TOC anchor csect. This relocation entry is treated the same as an R_TOC relocation entry. It provides the following additional information concerning the instruction being relocated: The instruction that is referenced by the r_vaddr field is a load instruction. That load instruction is permitted to be modified by the binder to become a compute address instruction. Changing an instruction from a load instruction to a compute address instruction avoids a storage reference during execution. A compute address instruction can be used if the address contained at the address specified by the r_symndx field has a value that itself references a r_symndx field that can be accessed with a valid in-range displacement relative to the TOC anchor address. That is, the target of the TOC entry is from -32,768 to 32,767, inclusive, from the TOC anchor address. If a compute address instruction is generated by the binder, the R_TRL relocation type is changed to become a R_TRLA type. This allows the reverse transformation, if required. Compilers are permitted to generate this relocation type.

0x13

R_TRLA

Specifies TOC Relative Load Address (modifiable LA to L) relocation. Provides a displacement value that is the difference between the address value in the symbol specified by the r_symndx field and the address of the TOC anchor csect. This relocation entry is treated the same as an R_TOC relocation entry. It provides the following additional information concerning the instruction being relocated: The instruction that is referenced by the r_vaddr field is a compute address instruction. The compute address instruction is modified by the binder to become a load instruction whenever the calculated displacement value is outside the valid displacement range relative to the TOC anchor address. This relocation type provides the binder with a means to transform a compute address instruction into a load instruction whenever required. If a load instruction is generated by the binder, the R_TRLA relocation type is changed to become an R_TRL type. Compilers are not permitted to generate this relocation type.

0x05

R_GL

Specifies Global Linkage-External TOC address relocation. Provides the address of the TOC associated with a defined external symbol. The external symbol with the required TOC address is specified by the r_symndx field of the relocation entry. This relocation entry provides a method of accessing the address of the TOC contained within the same executable where the r_symndx external symbol is defined.

0x06

R_TCL

Specifies local object TOC address relocation. Provides the address of the TOC associated with a defined external symbol. The external symbol for which the TOC address is required is specified by the r_symndx field of the relocation entry. The external symbol is defined locally within the resultant executable. This relocation entry provides a method of accessing the address of the TOC contained within the same executable where the r_symndx external symbol is defined.

0x0C

R_RL

Treated the same as the R_POS relocation type.

0x0D

R_RLA

Treated the same as the R_POS relocation type.

0x0F

R_REF

Specifies a nonrelocating reference to prevent garbage collection (by the binder) of a symbol. This relocation type is intended to provide compilers and assemblers a method to specify that a given csect has a dependency upon another csect without using any space in the actual csect. The reason for making the dependency reference is to prevent the binder from garbage-collecting (eliminating) a csect for which another csect has an implicit dependency.

0x08

R_BA

Treated the same as the R_RBA relocation type.

0x18

R_RBA

Specifies branch absolute relocation. Provides the address of the symbol specified by the r_symndx field as the target address of a branch instruction. The instruction can be modified to a (relative) branch instruction if the target address is relocatable.

0x0A

R_BR

Treated the same as the R_RBR relocation type.

0x1A

R_RBR

Specifies (relative) branch relocation. Provides a displacement value between the address of the symbol specified by the r_symndx field and the address of the csect containing the branch instruction to be modified. The instruction can be modified to an absolute branch instruction if the target address is not relocatable.

The R_RBR relocation type is the standard branch relocation type used by compilers and assemblers for the . This relocation type along with glink code allows an executable object file to have a text section that is position-independent.

 

Additional Relocation Features

Standard practice is to retain relocation information only for unresolved references or references between distinct sections. Once a reference is resolved, the relocation information is discarded. This is sufficient for an incremental bind and a fixed address space model. To provide the capability for rebinding and handling a relocatable address space model, the relocation information is not discarded from an XCOFF file.

For general information on the XCOFF file format, see "XCOFF Object (a.out) File Format."

For more information on relocation field table definitions, see "Relocation Table Field Definitions" in the loader section.

Line Number Information for XCOFF File (linenum.h)

Line number entries are used by the symbolic debugger to debug code at the source level. When present, there is a single line number entry for every source line that can have a symbolic debugger breakpoint. The line numbers are grouped by function. The beginning of each function is identified by the l_lnno field containing a value of 0. The first field, l_symndx , is the symbol table index to the C_EXT or C_HIDEXT symbol table entry for the function.

Each line number entry is six bytes long. The C language structure for a line number entry can be found in the linenum.h file. A line number entry contains the fields shown in the following tables.

Field Definitions

The following list defines the line number entries:

Note: If part of a function other than the beginning comes from an include file, the line numbers are absolute, rather than relative to the beginning of the function. (See the C_BINCL and C_EINCL symbol types in "Storage Classes by Usage and Symbol Value Classification" for more information.)

For general information on the XCOFF file format, see "XCOFF Object (a.out) File Format."

For information on debugging, see "Debug Section."

Symbol Table Information

One composite symbol table is defined for an XCOFF file. The symbol table contains information required by both the binder (external symbols) and the symbolic debugger (function definitions and internal and external symbols).

The symbol table consists of a list of 18-byte, fixed-length entries. Each symbol represented in the symbol table consists of at least one fixed-length entry, and some are followed by auxiliary entries of the same size.

See the following information to learn more about the symbol table:

• Symbol Table Auxiliary Information
• Symbol Table Field Contents by Storage Class
• String Table

For each external symbol, one or more auxiliary entries are required that provide additional information concerning the external symbol. There are three major types of external symbols of interest to the binder, performing the following functions:

• Define replaceable units or csects.
• Define the external names for functions or entry points within csects.
• Reference the names of external functions in another XCOFF object.

For symbols defining a replaceable unit (csect), a csect auxiliary entry defines the length and storage-mapping class of the csect. For symbols defining external names for functions within a csect, the csect auxiliary entry points to the containing csect, the parameter type-checking information, and the symbolic debugger information for the function. For symbols referencing the name of an external function, a csect auxiliary entry identifies the symbol as an external reference and points to parameter type-checking information.

Symbol Table Contents

An XCOFF symbol table has the following general contents and ordering:

• The C_FILE symbol table entries used to bracket all the symbol table entries associated with a given source file.
• The C_INFO comment section symbol table entries that are of source file scope. These follow the C_FILE entry but before the first csect definition symbol table entry.
• The symbolic debugger symbol table entries that are of file scope. These follow the C_FILE entry but before the first csect entry.
• csect definition symbol table entries used to define and bracket all the symbols contained with a csect.
• C_INFO comment section symbol table entries that follow a csect definition symbol table entry are associated with that csect.
• All symbolic debugger symbol table entries that follow a csect definition symbol table entry or label symbol table entry are associated with that csect or label.

The ordering of the symbol table must be arranged by the compilers and assemblers both to accommodate the symbolic debugger requirements and to permit effective management by the binder of the different sections of the object file as a result of such binder actions as garbage collection, incremental binding, and rebinding. This ordering is required by the binder so that if a csect is deleted or replaced, all the symbol table information associated with the csect can also be deleted or replaced. Likewise, if all the csects associated with a source file are deleted or replaced, all the symbol table and related information associated with the file can also be deleted or replaced.

Symbol Table Layout

The following example shows the general ordering of the symbol table.

un_external      Undefined global symbols
 
.file                Prolog --defines stabstring compaction level
.file                Source file 1
  .info              Comment section reference symbol with file scope
  stab               Global Debug symbols of a file
  csect              Replaceable unit definition (code)
     .info           Comment section reference symbol with csect scope
     function        Local/External function
         stab        Debug and local symbols of function
     function        Local/External function
         stab        Debug and local symbols of function
  ..............
  csect              Replaceable unit definition (local statics)
         stab        Debug and local statics of file
  ..............
  csect              Relocatable unit definition (global data)
         external    Defined global symbol
         stab        Debug info for global symbol
  ..............
.file                Source file 2
  stab               Global Debug symbols of a file
  csect              Replaceable unit definition (code)
         function    Local/External function
             stab    Debug and local symbols of function
  ..............
  csect              Replaceable unit definition (local statics)
      stab           Debug and Local statics of file
  ..............
  csect              Replaceable unit definition (global data)
      external       Defined global symbol
          stab       Debug info for global symbol
.file                Source file
  ..............

Symbol Table Entry (syms.h)

Each symbol, regardless of storage class and type, has a fixed-format entry in the symbol table. In addition, some symbol types may have additional (auxiliary) symbol table entries immediately following the fixed-format entry. Each entry in the symbol table is 18 bytes long. The C language structure for a symbol table entry can be found in the syms.h file. The index for the first entry in the symbol table is 0. The following table shows the structure of the fixed-format part of each symbol in the symbol table.

Field Definitions

The following defines the symbol table entry fields:

For general information on the XCOFF file format, see "XCOFF Object (a.out) File Format."

Symbol Table Auxiliary Information

The symbol table contains auxiliary entries to provide supplemental information for a symbol. The auxiliary entries for a symbol follow its symbol table entry. The length of each auxiliary entry is the same as a symbol table entry (18 bytes). The format and quantity of auxiliary entries depend on the storage class (n_sclass) and type (n_type) of the symbol table entry.

In XCOFF32, symbols having a storage class of C_EXT or C_HIDEXT and more than one auxiliary entry must have the csect auxiliary entry as the last auxiliary entry. In XCOFF64, the x_auxtype field of each auxiliary symbol table entry differentiates the symbols, but the convention is to generate the csect auxiliary symbol table entry last.

File Auxiliary Entry for C_FILE Symbols

The file auxiliary symbol table entry is defined to contain the source file name and compiler-related strings. A file auxiliary entry is optional and is used with a symbol table entry that has a storage-class value of C_FILE. The C language structure for a file auxiliary entry can be found in the x_file structure in the syms.h file.

The C_FILE symbol provides source file-name information, source-language ID and CPU-version ID information, and, optionally, compiler-version and time-stamp information.

The n_type field of the symbol table entry identifies the source language of the source file and the CPU version ID of the compiled object file. The field information is as follows:

Field Definitions

The following defines the fields listed above:

If the file auxiliary entry is not used, the symbol name is the name of the source file. If the file auxiliary entry is used, then the symbol name should be .file, and the first file auxiliary entry (by convention) contains the source file name. More than one file auxiliary entry is permitted for a given symbol table entry. The n_numaux field contains the number of file auxiliary entries.

csect Auxiliary Entry for C_EXT and C_HIDEXT Symbols

The csect auxiliary entry identifies csects (section definitions), entry points (label definitions), and external references (label declarations). A csect auxiliary entry is required for each symbol table entry that has a storage class value of C_EXT or C_HIDEXT. See "Symbol Table Entry (syms.h)" for more information. By convention, the csect auxiliary entry in an XCOFF32 file must be the last auxiliary entry for any external symbol that has more than one auxiliary entry. The C language structure for a csect auxiliary entry can be found in the x_csect structure in the syms.h file.

Field Definitions

The following defines the fields listed above:

x_scnlen

Specifies a meaning dependent on x_smtyp as follows:

If

Then

XTY_SD

x_scnlen contains the csect length.

XTY_LD

x_scnlen contains the symbol table index of the containing csect.

XTY_CM

x_scnlen contains the csect length.

XTY_ER

x_scnlen contains 0.

 

 

In the XCOFF64 format, the value of x_scnlen is divided into two fields: x_scnlen_hi, representing the upper 4 bytes of the value, and x_scnlen_lo, representing the lower 4 bytes of the value.

x_parmhash

Specifies the byte offset of the parameter type-check string in the .typchk section. The byte offset is from the beginning of the .typchk section in an XCOFF file. The byte offset points to the first byte of the parameter type-check string (not to its length field). See "Type-Check Section" for more information. A value of 0 in the x_parmhash field indicates that the parameter type-checking string is not present for this symbol, and the symbol will be treated as having a universal hash. The value should be 0 for C_HIDEXT symbols.

x_snhash

Specifies the .typchk section number. The XCOFF section number containing the parameter type-checking strings. The section numbers are one-based. For compatibility with object files generated by some compilers, if x_parmhash is not equal to 0 but x_snhash does equal 0, then the first .typchk section in the file is used. The value should be 0 for C_HIDEXT symbols.

x_smtyp

Specifies symbol alignment and type:

Bits 0-4

Contains a 5-bit csect address alignment value (log base 2). For example, a value of 3 in this field indicates 23, or 8, meaning the csect is to be aligned on an 8-byte address value. The alignment value is used only when the value of bits 5-7 of the x_smtyp field is either XTY_SD or XTY_CM.

Bits 5-7

Contains a 3-bit symbol type field. See the definitions for bits 5-7 of the l_smtype field in "Loader Section" for more information.

 

x_smclas

Specifies the csect storage-mapping class. This field permits the binder to arrange csects by their storage-mapping class. The x_smclas field is used only when the value of bits 5-7 of the x_smtyp field is either XTY_SD or XTY_CM.

The following storage-mapping classes are read-only and normally mapped to the .text section:

Value Class

Description

0     XMC_PR

Specifies program code. The csect contains the executable instructions of the program.

1     XMC_RO

Specifies a read-only constant. The csect contains data that is constant and will not change during execution of the program.

2     XMC_DB

Specifies the debug dictionary table. The csect contains symbolic-debugging data or exception-processing data. This storage mapping class was defined to permit compilers with special symbolic-debugging or exception-processing requirements to place data in csects that are loaded at execution time but that can be collected separately from the executable code of the program.

6     XMC_GL

Specifies global linkage. The csect provides the interface code necessary to handle csect relative calls to a target symbol that can be out-of-module. This global linkage csect has the same name as the target symbol and becomes the local target of the relative calls. As a result, the csect maintains position-independent code within the .text section of the executable XCOFF object file.

7     XMC_XO

Specifies extended operation. A csect of this type has no dependency on (references through) the TOC. It is intended to reside at a fixed address in memory such that it can be the target of a branch-absolute instruction.

12     XMC_TI

Reserved.

13     XMC_TB

Reserved.

The following storage-mapping classes are read/write and normally mapped to the .data or .bss section:

Value Class

Description

5     XMC_RW

Specifies read/write data. A csect of this type contains initialized or uninitialized data that is permitted to be modified during program execution. If the x_smtyp value is XTY_SD, the csect contains initialized data and is mapped into the .data section. If the x_smtyp value is XTY_CM, the csect is uninitialized and is mapped into the .bss section. Typically, all the initialized static data from a C source file is contained in a single csect of this type. The csect would have a storage class value of C_HIDEXT. An initialized definition for a global data scalar or structure from a C source file is contained in its own csect of this type. The csect would have a storage class value of C_EXT. A csect of this type is accessible by name references from other object files.

15     XMC_TC0

Specifies TOC anchor for TOC addressability. This is a zero-length csect whose n_value address provides the base address for TOC relative addressability. Only one csect of type XMC_TC0 is permitted per section of an XCOFF object file. In implementations that permit compilers and assemblers to generate multiple .data sections, there must be a csect of type XMC_TC0 in each section that contains data that is referenced (by way of a relocation entry) as a TOC-relative data item. Some hardware architectures limit the value that a relative displacement field within a load instruction may contain. This limit then becomes an inherent limit on the size of a TOC for an executable XCOFF object. For and RS/6000 , this limit is 65,536 bytes, or 16,384 4-byte TOC entries.

3     XMC_TC

Specifies general TOC entry. A csect of this type is usually 4 bytes in length and contains the address of another csect or global symbol. This csect provides addressability to other csects or symbols. The symbols may be contained in either the local executable XCOFF object or in another executable XCOFF object. Special processing semantics are used by the binder to eliminate duplicate TOC entries as follows:

• Symbols that have a storage class value of C_EXT are global symbols and must have names (a non-null n_name field). These symbols require no special TOC processing logic to combine duplicate entries. Duplicate entries with the same n_name value are combined into a single entry.
• Symbols that have a storage class value of C_HIDEXT are not global symbols, and duplicate entries are resolved by context. Any two such symbols will be defined as duplicates and combined into a single entry whenever the following conditions are met:
  • The n_name fields are the same. That is, they have either a null name or the same name string.
  • Each is 4 bytes long.
  • Each has a single RLD entry that references external symbols with the same name.

To minimize the number of duplicate TOC entries that cannot be combined by the binder, compilers and assemblers should adhere to a common naming convention for TOC entries. By convention, compilers and assemblers produce TOC entries that have a storage class value of C_HIDEXT and an n_name string that is the same as the n_name value for the symbol that the TOC entry addresses.

16     XMC_TD

Specifies scalar data entry in the TOC. A csect that is a special form of an XMC_RW csect that is directly accessed from the TOC by compiler generated code. This lets some frequently used globol symbols be accessed directly from the TOC rather than indirectly through an address pointer csect contained in the TOC. A csect of type XMC_TD has the following characteristics:

• The compiler generates code that is TOC relative to directly access the data contained in the csect of type XMC_TD.
• It is 4-bytes long or less.
• It has initialized data that can be modified as the program runs.
• If a same named csect of type XMC_RW or XMC_UA exist, it is replaced by the XMC_TD csect.

For the cases where TOC scalar cannot reside in the TOC, the binder must be capable of transforming the compiler generated TOC relative instruction into a conventional indirect addressing instruction sequence. This transformation is necessary if the TOC scalar is contained in a shared object.

10     XMC_DS

Specifies a csect containing a function descriptor, which contains the following three values:

• The address of the executable code for a function.
• The address of the TOC anchor (TOC base address) of the module that contains the function.
• The environment pointer (used by languages such as Pascal and PL/I).

There is only one function descriptor csect for a function, and it must be contained within the same executable as the function itself is contained. The function descriptor has a storage class value of C_EXT and has an n_name value that is the same as the name of the function in the source file. The addresses of function descriptors are imported to and exported from an executable XCOFF file.

8     XMC_SV

Specifies 32-bit supervisor call descriptor csect. The supervisor call descriptors are contained within the operating system kernel. To an application program, the reference to a supervisor call descriptor is treated the same as a reference to a regular function descriptor. It is through the import/export mechanism that a function descriptor is treated as a supervisor call descriptor. These symbols are only available to 32-bit programs.

17     XMC_SV64

Specifies 64-bit supervisor call descriptor csect. See XMV_SV for supervisor call information. These symbols are only available to 64-bit programs.

18     XMC_SV3264

Specifies supervisor call descriptor csect for both 32-bit and 64-bit. See XMV_SV for supervisor call information. These symbols are available to both 32-bit and 64-bit programs.

4     XMC_UA

Unclassified. This csect is treated as read/write. This csect is frequently produced by an assembler or object file translator program that cannot determine the true classification of the resultant csect.

9     XMC_BS

Specifies BSS class (uninitialized static internal). A csect of this type is uninitialized, and is intended to be mapped into the .bss section. This type of csect must have a x_smtyp value of XTY_CM.

11     XMC_UC

Specifies unnamed FORTRAN common. A csect of this type is intended for an unnamed and uninitialized FORTRAN common. It is intended to be mapped into the .bss section. This type of csect must have a x_smtyp value of XTY_CM.

 

x_stab

Reserved (Unused for 64-bit).

x_snstab

Reserved (Unused for 64-bit).

Auxiliary Entries for the C_EXT and C_HIDEXT Symbols

Auxiliary symbol table entries are defined in XCOFF to contain reference and size information associated with a defined function. These auxiliary entries are produced by compilers and assembler for use by the symbolic debuggers. In XCOFF32, a function auxiliary symbol table entry contains the required information. In XCOFF64, both a function auxiliary entry and an exeption auxiliary entry may be needed. When both auxiliary entries are generated for a single C_EXT or C_HIDEXT symbol, the x_size and x_endndx fields must have the same values.

The function auxiliary symbol table entry is defined in the following table.

Field Definitions

The following defines the fields listed in the Function Auxiliary Entry Format table:

The exception auxiliary symbol table entry, defined in XCOFF64 only, is shown in the following table.

Field Definitions

The following defines the fields listed in the Exception Auxiliary Entry Format table:

Block Auxiliary Entry for the C_BLOCK and C_FCN Symbols

The section auxiliary symbol table entry is defined in XCOFF to provide information associated with the begin and end blocks of functions. The section auxiliary symbol table entry is produced by compilers for use by the symbolic debuggers.

Field Definitions

The following defines the fields above:

Section Auxiliary Entry for the C_STAT Symbol

The section auxiliary symbol table entry ID is defined in XCOFF32 to provide information in the symbol table concerning the size of sections produced by a compiler or assembler. The generation of this information by a compiler is optional, and is ignored and removed by the binder.

Field Definitions

The following list defines the fields:

For general information on the XCOFF file format, see "XCOFF Object (a.out) File Format." For more information on the symbol table, see "Symbol Table Information."

For information on debugging, see "Debug Section."

Symbol Table Field Contents by Storage Class

This section defines the symbol table field contents for each of the defined storage classes (n_sclass ) that are used in XCOFF. The following table lists storage class entries in alphabetic order. See "Symbol Table Entry (syms.h)" for more information.

Notes:

1. *For long name, the n_offset value is an offset into the .debug section.
2. **For long name, the n_offset value is an offset into the string table.

Storage Classes by Usage and Symbol Value Classification

Following are the storage classes used and relocated by the binder. The symbol values (n_value ) are addresses.

Following are storage classes used by the binder and symbolic debugger or by other utilities for file scoping and accessing purposes:

Following are the storage classes that exist only for symbolic debugging purposes:

For general information on the XCOFF file format, see "XCOFF Object (a.out) File Format." For more information on the symbol table, see "Symbol Table Information."

For information on debugging, see "Debug Section."

String Table

IN XCOFF32, the string table contains the names of symbols that are longer than 8 bytes. In XCOFF64, the string table contains the names of all symbols. If the string table is present, the first 4 bytes contain the length (in bytes) of the string table, including the length of this length field. The remainder of the table is a sequence of null-terminated ASCII strings. If the n_zeroes field in the symbol table entry is 0, then the n_offset field gives the byte offset into the string table of the name of the symbol.

If a string table is not used, it may be omitted entirely, or a string table consisting of only the length field (containing a value of 0 or 4) may be used. A value of 4 is preferable. The following table shows string table organization.

For general information on the XCOFF file format, see "XCOFF Object (a.out) File Format."

dbx Stabstrings

The debug section contains the symbolic debugger stabstrings (symbol table strings). It is generated by the compilers and assemblers. It provides symbol attribute information for use by the symbolic debugger.

See "Debug Section" for a general discussion.

Stabstring Terminal Symbols

In the stabstring grammar, there are five types of terminal symbols, which are written in all capital letters. These symbols are described by the regular expressions in the following list:

Note: The [ ] (brackets) denote one instance, [ ]* (brackets asterisk) denote zero or more instances, [ ]+ (brackets plus sign) denote one or more instances, ( ) (parentheses) denote zero or one instance, .* (dot asterisk) denotes a sequence of zero or more bytes, and | (pipe) denotes alternatives.

Stabstring Grammar

REALs may be preceded by white space, and STRINGs may contain any characters, including null and blank characters. Otherwise, there are no null or blank characters in a stabstring.

Long stabstrings can be split across multiple symbol table entries for easier handling. In the stabstring grammar, a # (pound sign) indicates a point at which a stabstring may be continued. A continuation is indicated by using either the ? (question mark) or \ as the last character in the string. The next part of the stabstring is in the name of the next symbol table entry. If an alternative for a production is empty, the grammar shows the keyword /*EMPTY*/.

The following list contains the stabstring grammar:

Stabstring:

Basic structure of stabstring:

NAME : Class

Name of object followed by object classification

:Class

Unnamed object classification.

 

 

Class:

Object classifications:

c = Constant ;

Constant object

 

NamedType

User-defined types and tags

Parameter

Argument to subprogram

Procedure

Subprogram declaration

Variable

Variable in program

Label

Label object.

 

Constant:

Constant declarations:

b OrdValue

Boolean constant

c OrdValue

Character constant

e TypeID , OrdValue

Enumeration constant

i INTEGER

Integer constant

r REAL

Floating point constant

s STRING

String constant

C REAL, REAL

Complex constant

S TypeID , NumElements , NumBits , BitPattern

Set constant.

 

OrdValue:

Associated numeric value: INTEGER

NumElements:

Number of elements in the set: INTEGER

NumBits:

Number of bits in item: INTEGER

NumBytes:

Number of bytes in item: INTEGER

BitPattern:

Hexadecimal representation, up to 32 bytes: HEXINTEGER

NamedType:

User-defined types and tags:

t TypeID

User-defined type (TYPE or typedef), excluding those that are valid for T TypeID

T TypeID

Struct, union, class, or enumeration tag

 

Parameter:

Argument to procedure or function:

a TypeID

Passed by reference in general register

p TypeID

Passed by value on stack

v TypeID

Passed by reference on stack

C TypeID

Constant passed by value on stack

D TypeID

Passed by value in floating point register

R TypeID

Passed by value in general register

 

Procedure:

Procedure or function declaration:

Proc

Procedure at current scoping level

Proc , NAME : NAME

Procedure named 1st NAME, local to 2nd NAME, where 2nd NAME is different from the current scope.

 

Variable:

Variable in program:

TypeID

Local (automatic) variable of type TypeID

d TypeID

Floating register variable of type TypeID

r TypeID

Register variable of type TypeID

G TypeID

Global (external) variable of type TypeID

S TypeID

Module variable of type TypeID (C static global)

V TypeID

Own variable of type TypeID (C static local)

Y

FORTRAN pointer variable

Z TypeID NAME

FORTRAN pointee variable

 

Label:

Label:

L

Label name.

 

Proc:

Different types of functions and procedures:

f TypeID

Private function of type TypeID

g TypeID

Generic function (FORTRAN)

m TypeID

Module (Modula-2, ext. Pascal)

J TypeID

Internal function of type TypeID

F TypeID

External function of type TypeID

I

(capital i) Internal procedure

P

External procedure

Q

Private procedure

 

TypeID:

Type declarations and identifiers:

INTEGER

Type number of previously defined type

INTEGER = TypeDef

New type number described by TypeDef

INTEGER = TypeAttrs TypeDef

New type with special type attributes

 

TypeAttrs:

@ TypeAttrList ;

Note: Type attributes (TypeAttrs) are extra information associated with a type, such as alignment constraints or pointer-checking semantics. The dbx program recognizes only the size attribute and the packed attribute. The size attribute denotes the total size of a padded element within an array. The packed attribute indicates that a type is a packed type. Any other attributes are ignored by dbx.

TypeAttrList:

List of special type attributes:

TypeAttrList ;

@ TypeAttr
TypeAttr

TypeAttr:

Special type attributes:

a INTEGER

Align boundary

s INTEGER

Size in bits

p INTEGER

Pointer class (for checking)

P

Packed type

Other

Anything not covered is skipped entirely

 

TypeDef:

Basic descriptions of objects:

INTEGER

Type number of a previously defined type

b TypeID ; # NumBytes

Pascal space type

c TypeID ; # NumBits

Complex type TypeID

d TypeID

File of type TypeID

e EnumSpec ;

Enumerated type (default size, 32 bits)

g TypeID ; # NumBits

Floating-point type of size NumBits

For i types, ModuleName refers to the Modula-2 module from which it is imported.

i NAME : NAME ;

Imported type ModuleName:Name

i NAME : NAME , TypeID ;

Imported type ModuleName:Name of type TypeID

k TypeID

C++ constant type

l ; #

Usage-is-index; specific to COBOL

m OptVBaseSpec OptMultiBaseSpec TypeID : TypeID : TypeID ;

C++ pointer to member type; the first TypeID is the member type; the second is the type of the class

n TypeID ; # NumBytes

String type, with maximum string length indicated by NumBytes

o NAME ;

Opaque type

o NAME , TypeID

Opaque type with definition of TypeID

w TypeID

Wide character

z TypeID ; # NumBytes

Pascal gstring type

C Usage

COBOL Picture

I NumBytes ; # PicSize

(uppercase i) Index is type; specific to COBOL

K CobolFileDesc;

COBOL File Descriptor

M TypeID ; # Bound

Multiple instance type of TypeID with length indicated by Bound

N

Pascal Stringptr

S TypeID

Set of type TypeID

* TypeID

Pointer of type TypeID

& TypeID

C++ reference type

V TypeID

C++ volatile type

Z

C++ ellipses parameter type

 

Array Subrange ProcedureType

For function types rather than declarations

Record

Record, structure, union, or group types

 

EnumSpec:

List of enumerated scalars:

EnumList

Enumerated type (C and other languages)

TypeID : EnumList

C++ enumerated type with repeating integer type

 

EnumList:
Enum

EnumList Enum

Enum:

Enumerated scalar description:
NAME : OrdValue , #

Array:

Array descriptions:

a TypeID ; # TypeID

Array; FirstTypeID is the index type

A TypeID

Open array of TypeID

D INTEGER , TypeID

N-dimensional dynamic array of TypeID

E INTEGER , TypeID

N-dimensional dynamic subarray of TypeID

O INTEGER , TypeID

New open array

P TypeID ; # TypeID

Packed array

 

Subrange:

Subrange descriptions:

r TypeID ; # Bound ; # Bound

Subrange type (for example, char, int,\,), lower and upper bounds

 

Bound:

Upper and lower bound descriptions:

INTEGER

Constant bound

Boundtype INTEGER

Variable or dynamic bound; value is address of or offset to bound

J

Bound is indeterminable (no bounds)

 

Boundtype:

Adjustable subrange descriptions:

A

Bound passed by reference on stack

S

Bound passed by value in static storage

T

Bound passed by value on stack

a

Bound passed by reference in register

t

Bound passed by value in register

 

ProcedureType:

Function variables (1st type C only; others Modula-2 & Pascal)

f TypeID ;

Function returning type TypeID

f TypeID , NumParams ; TParamList ;

Function of N parameters returning type TypeID

p NumParams ; TParamList ;

Procedure of N parameters

R NumParams ; NamedTParamList

Pascal subroutine parameter

F TypeID, NumParams ; NamedTParamList ;

Pascal function parameter

 

NumParams:

Number of parameters in routine:

INTEGER.

TParamList:

Types of parameters in Modula-2 function variable:

TParam

Type of parameter and passing method

TParamList TParam

 

 

TParam:

Type and passing method

TypeID , PassBy ; #

NamedTParamList:

Types of parameters in Pascal-routine variable:
/*EMPTY*/
NamedTPList

NamedTPList:

NamedTParam NamedTPList NamedTParam

NamedTParam:

Named type and passing method:
Name : TypeID , PassBy InitBody ; #
: TypeID , PassBy InitBody ; #
Unnamed parameter

Record:

Types of structure declarations:

• s NumBytes # FieldList ;
•           Structure or record definition
• u NumBytes # FieldList ;
•           Union
• v NumBytes # FieldList VariantPart ;
•            Variant Record
• Y NumBytes ClassKey OptPBV OptBaseSpecList ( ExtendedFieldListOptNameResolutionList ;
•            C++ class
• G Redefinition , n NumBits # FieldList ;
•            COBOL group without conditionals

Gn NumBits FieldList ;

• G Redefinition , c NumBits # CondFieldList ;
•           COBOL group with conditionals

Gc NumBits CondFieldList ;

OptVBaseSpec:

v

ptr-to-mem class has virtual bases.

/*EMPTY*/

Class has no virtual bases.

 

OptMultiBaseSpec:

m

Class is multi-based.

/*EMPTY*/

Class is not multi-based.

 

OptPBV:

V

Class is always passed by value.

/*EMPTY*/

Class is never passed by value.

 

ClassKey:

s

struct

u

union

c

class

 

OptBaseSpecList:

/*EMPTY*/ BaseSpecList

BaseSpecList:

BaseSpec
BaseSpecList , BaseSpec

BaseSpec:

VirtualAccessSpec BaseClassOffset : ClassTypeID

BaseClassOffset:

INTEGER

Base record offset in bytes

 

ClassTypeID:

TypeID

Base class type identifier

 

VirtualAccessSpec:

v AccessSpec

Virtual

v

Virtual

AccessSpec

/*EMPTY*/

 

GenSpec:

c

Compiler-generated

/*EMPTY*/

 

AccessSpec:

i #

Private

o #

Protected

u #

Public

 

AnonSpec:

a

Anonymous union member

/*EMPTY*/

 

VirtualSpec:

v p

Pure virtual

v

Virtual

/*EMPTY*/

 

 

ExtendedFieldList:

ExtendedFieldList ExtendedField
/*EMPTY*/

ExtendedField:

GenSpec AccessSpec AnonSpec DataMember
GenSpec VirtualSpec AccessSpec OptVirtualFuncIndex MemberFunction
AccessSpec AnonSpec NestedClass
AnonSpec FriendClass
AnonSpec FriendFunction

DataMember:

MemberAttrs : Field ;

MemberAttrs:

IsStatic IsVtblPtr IsVBasePtr

IsStatic:

/*EMPTY*/

s

Member is static.

 

IsVtblPtr:

/*EMPTY*/

p INTEGER NAME

Member is vtbl pointer; NAME is the external name of v-table.

 

IsVBasePtr:

/*EMPTY*/

b

Member is vbase pointer.

r

Member is vbase self-pointer.

 

 

Member Function:

[ FuncType MemberFuncAttrs : NAME : TypeID ; #

MemberFuncAttrs:

IsStatic IsInline IsConst IsVolatile

IsInline:

/*EMPTY*/

i

Inline function

 

IsConst:

/*EMPTY*/

k

const member function

 

IsVolatile:

/*EMPTY*/

V

Volatile member function

 

NestedClass:

N TypeID ; #

FriendClass:

( TypeID ; #

FriendFunction:

] NAME : TypeID ; #

OptVirtualFuncIndex:

/*EMPTY*/ INTEGER

FuncType:

f

Member function

c

Constructor

d

Destructor

 

InitBody:

STRING
/*EMPTY*/

OptNameResolutionList:

/*EMPTY*/
) NameResolutionList

NameResolutionList: NameResolution

NameResolution , NameResolutionList

NameResolution: MemberName : ClassTypeID

Name is resolved by compiler.

MemberName :

   Name is ambiguous.

 

MemberName:

NAME

FieldList:

Structure content descriptions:

Field

/*EMPTY*/

FieldList Field

Member of record or union.

 

Field:

Structure-member type description:

NAME : TypeID , BitOffset , NumBits ; #

VariantPart:

Variant portion of variant record:

[ Vtag VFieldList ]

Variant description

 

VTag:

Variant record tag:

( Field

Member of variant record

( NAME : ; #

Variant key name

 

VFieldList:

Variant record content descriptions:

VList
VFieldList VList

Member of variant record

VList:

Variant record fields:

VField
VField VariantPart

Member of variant record

 

VField:

Variant record member type description:

( VRangeList : FieldList

Variant with field list

 

VRangeList:

List of variant field labels:

VRange
VRangeList , VRange

Member of variant record

 

VRange:

Variant field descriptions:

b OrdValue

Boolean variant

c OrdValue

Character variant

e TypeID , OrdValue

Enumeration variant

i INTEGER

Integer variant

r TypeID ; Bound ; Bound

Subrange variant

 

CondFieldList:

Conditions,#FieldList
FieldList# ;

Conditions:

/*Empty*/
Conditions condition

BitOffset:

Offset in bits from beginning of structure: INTEGER

Usage:

Cobol usage description:
PICStorageType NumBits , EditDescription , PicSize ;
Redefinition , PICStorageType NumBits , EditDescription , PicSize ;
PICStorageType NumBits , EditDescription , PicSize , # Condition ;
Redefinition , PICStorageType NumBits , EditDescription , PicSize , # Condition ;

Redefinition:

Cobol redefinition: r NAME

PICStorageType:

Cobol PICTURE types:

a

Alphabetic

b

Alphabetic, edited

c

Alphanumeric

d

Alphanumeric, edited

e

Numeric, signed, trailing, included

f

Numeric, signed, trailing, separate

g

Numeric, signed, leading, included

h

Numeric, signed, leading, separate

i

Numeric, signed, default, comp

j

Numeric, unsigned, default, comp

k

Numeric, packed, decimal, signed

l

Numeric, packed, decimal, unsigned

m

Numeric, unsigned, comp-x

n

Numeric, unsigned, comp-5

o

Numeric, signed, comp-5

p

Numeric, edited

q

Numeric, unsigned

s

Indexed item

t

Pointer

 

EditDescription:

Cobol edit description:

STRING

Edit characters in an alpha PIC

INTEGER

Decimal point position in a numeric PIC

 

PicSize:

Cobol description length:

INTEGER

Number of repeated '9's in numeric clause, or length of edit format for edited numeric

 

Condition:

Conditional variable descriptions:

NAME : INTEGER = q ConditionType , ValueList ; #

ConditionType:

Condition descriptions:

ConditionPrimitive , KanjiChar

ConditionPrimitive:

Primitive type of Condition:

n Sign DecimalSite

Numeric conditional

a

Alphanumeric conditional

f

Figurative conditional

 

Sign:

For types with explicit sign:

+

Positive

-

Negative

[^+-]

Not specified

 

DecimalSite:

Number of places from left for implied decimal point:

INTEGER

KanjiChar:

0 only if Kanji character in value: INTEGER

ValueList

Values associated with condition names

Value ValueList Value

 

Value

Values associated with condition names:

INTEGER : ArbitraryCharacters #

Integer indicates length of string

 

CobolFileDesc:

COBOL file description:
Organization AccessMethod NumBytes

Organization:

COBOL file-description organization:

i

Indexed

l

Line Sequential

r

Relative

s

Sequential

 

AccessMethod:

COBOL file description access method:

d

Dynamic

o

Sort

r

Random

s

Sequential

 

PassBy:

Parameter passing method:

INTEGER

0 = passed-by reference; 1 = passed-by value