Go to the first, previous, next, last section, table of contents.

## Data types

This section describes some fundamental GAS data types.

- Symbols: The symbolS structure
- Expressions: The expressionS structure
- Fixups: The fixS structure
- Frags: The fragS structure

### Symbols

The definition for `struct symbol`, also known as `symbolS`, is located in ``struc-symbol.h'`. Symbol structures contain the following fields:

`sy_value`
  This is an `expressionS` that describes the value of the symbol. It might refer to one or more other symbols; if so, its true value may not be known until `resolve_symbol_value` is called in `write_object_file`. The expression is often simply a constant. Before `resolve_symbol_value` is called, the value is the offset from the frag (see section Frags). Afterward, the frag address has been added in.
`sy_resolved`
  This field is non-zero if the symbol's value has been completely resolved. It is used during the final pass over the symbol table.
`sy_resolving`
  This field is used to detect loops while resolving the symbol's value.
`sy_used_in_reloc`
  This field is non-zero if the symbol is used by a relocation entry. If a local symbol is used in a relocation entry, it must be possible to redirect those relocations to other symbols, or this symbol cannot be removed from the final symbol list.
`sy_next`
`sy_previous`
  These pointers to other `symbolS` structures describe a singly or doubly linked list. (If `SYMBOLS_NEED_BACKPOINTERS` is not defined, the `sy_previous` field will be omitted; `SYMBOLS_NEED_BACKPOINTERS` is always defined if `BFD_ASSEMBLER`.) These fields should be accessed with the `symbol_next` and `symbol_previous` macros.
`sy_frag`
  This points to the frag (see section Frags) that this symbol is attached to.
`sy_used`
  Whether the symbol is used as an operand or in an expression. Note: Not all of the backends keep this information accurate; backends which use this bit are responsible for setting it when a symbol is used in backend routines.
`sy_mri_common`
  Whether the symbol is an MRI common symbol created by the `COMMON` pseudo-op when assembling in MRI mode.
`bsym`
  If `BFD_ASSEMBLER` is defined, this points to the BFD `asymbol` that will be used in writing the object file.
`sy_name_offset`
  (Only used if `BFD_ASSEMBLER` is not defined.) This is the position of the symbol's name in the string table of the object file. On some formats, this will start at position 4, with position 0 reserved for unnamed symbols. This field is not used until `write_object_file` is called.
`sy_symbol`
  (Only used if `BFD_ASSEMBLER` is not defined.) This is the format-specific symbol structure, as it would be written into the object file.
`sy_number`
  (Only used if `BFD_ASSEMBLER` is not defined.) This is a 24-bit symbol number, for use in constructing relocation table entries.
`sy_obj`
  This format-specific data is of type `OBJ_SYMFIELD_TYPE`. If no macro by that name is defined in ``obj-format.h'`, this field is not defined.
`sy_tc`
  This processor-specific data is of type `TC_SYMFIELD_TYPE`. If no macro by that name is defined in ``targ-cpu.h'`, this field is not defined.
`TARGET_SYMBOL_FIELDS`
  If this macro is defined, it defines additional fields in the symbol structure. This macro is obsolete, and should be replaced when possible by uses of `OBJ_SYMFIELD_TYPE` and `TC_SYMFIELD_TYPE`.

There are a number of access routines used to extract the fields of a `symbolS` structure. When possible, these routines should be used rather than referring to the fields directly. These routines will work for any GAS version.

`S_SET_VALUE`
  Set the symbol's value.
`S_GET_VALUE`
  Get the symbol's value. This will cause `resolve_symbol_value` to be called if necessary, so `S_GET_VALUE` should only be called when it is safe to resolve symbols (i.e., after the entire input file has been read and all symbols have been defined).
`S_SET_SEGMENT`
  Set the section of the symbol.
`S_GET_SEGMENT`
  Get the symbol's section.
`S_GET_NAME`
  Get the name of the symbol.
`S_SET_NAME`
  Set the name of the symbol.
`S_IS_EXTERNAL`
  Return non-zero if the symbol is externally visible.
`S_IS_EXTERN`
  A synonym for `S_IS_EXTERNAL`. Don't use it.
`S_IS_WEAK`
  Return non-zero if the symbol is weak.
`S_IS_COMMON`
  Return non-zero if this is a common symbol. Common symbols are sometimes represented as undefined symbols with a value, in which case this function will not be reliable.
`S_IS_DEFINED`
  Return non-zero if this symbol is defined. This function is not reliable when called on a common symbol.
`S_IS_DEBUG`
  Return non-zero if this is a debugging symbol.
`S_IS_LOCAL`
  Return non-zero if this is a local assembler symbol which should not be included in the final symbol table. Note that this is not the opposite of `S_IS_EXTERNAL`. The ``-L'` assembler option affects the return value of this function.
`S_SET_EXTERNAL`
  Mark the symbol as externally visible.
`S_CLEAR_EXTERNAL`
  Mark the symbol as not externally visible.
`S_SET_WEAK`
  Mark the symbol as weak.
`S_GET_TYPE`
`S_GET_DESC`
`S_GET_OTHER`
  Get the `type`, `desc`, and `other` fields of the symbol. These are only defined for object file formats for which they make sense (primarily a.out).
`S_SET_TYPE`
`S_SET_DESC`
`S_SET_OTHER`
  Set the `type`, `desc`, and `other` fields of the symbol. These are only defined for object file formats for which they make sense (primarily a.out).
`S_GET_SIZE`
  Get the size of a symbol. This is only defined for object file formats for which it makes sense (primarily ELF).
`S_SET_SIZE`
  Set the size of a symbol. This is only defined for object file formats for which it makes sense (primarily ELF).

### Expressions

Expressions are stored in an `expressionS` structure. The structure is defined in ``expr.h'`.

The macro `expression` will create an `expressionS` structure based on the text found at the global variable `input_line_pointer`.

A single `expressionS` structure can represent a single operation. Complex expressions are formed by creating expression symbols and combining them in `expressionS` structures. An expression symbol is created by calling `make_expr_symbol`. An expression symbol should naturally never appear in a symbol table, and the implementation of `S_IS_LOCAL` (see section Symbols) reflects that. The function `expr_symbol_where` returns non-zero if a symbol is an expression symbol, and also returns the file and line for the expression which caused it to be created.

The `expressionS` structure has two symbol fields, a number field, an operator field, and a field indicating whether the number is unsigned.

The operator field is of type `operatorT`, and describes how to interpret the other fields; see the definition in ``expr.h'` for the possibilities.

An `operatorT` value of `O_big` indicates either a floating point number, stored in the global variable `generic_floating_point_number`, or an integer to large to store in an `offsetT` type, stored in the global array `generic_bignum`. This rather inflexible approach makes it impossible to use floating point numbers or large expressions in complex expressions.

### Fixups

A fixup is basically anything which can not be resolved in the first pass. Sometimes a fixup can be resolved by the end of the assembly; if not, the fixup becomes a relocation entry in the object file.

A fixup is created by a call to `fix_new` or `fix_new_exp`. Both take a frag (see section Frags), a position within the frag, a size, an indication of whether the fixup is PC relative, and a type. In a `BFD_ASSEMBLER` GAS, the type is nominally a `bfd_reloc_code_real_type`, but several targets use other type codes to represent fixups that can not be described as relocations.

The `fixS` structure has a number of fields, several of which are obsolete or are only used by a particular target. The important fields are:

`fx_frag`
  The frag (see section Frags) this fixup is in.
`fx_where`
  The location within the frag where the fixup occurs.
`fx_addsy`
  The symbol this fixup is against. Typically, the value of this symbol is added into the object contents. This may be NULL.
`fx_subsy`
  The value of this symbol is subtracted from the object contents. This is normally NULL.
`fx_offset`
  A number which is added into the fixup.
`fx_addnumber`
  Some CPU backends use this field to convey information between `md_apply_fix` and `tc_gen_reloc`. The machine independent code does not use it.
`fx_next`
  The next fixup in the section.
`fx_r_type`
  The type of the fixup. This field is only defined if `BFD_ASSEMBLER`, or if the target defines `NEED_FX_R_TYPE`.
`fx_size`
  The size of the fixup. This is mostly used for error checking.
`fx_pcrel`
  Whether the fixup is PC relative.
`fx_done`
  Non-zero if the fixup has been applied, and no relocation entry needs to be generated.
`fx_file`
`fx_line`
  The file and line where the fixup was created.
`tc_fix_data`
  This has the type `TC_FIX_TYPE`, and is only defined if the target defines that macro.

### Frags

The `fragS` structure is defined in ``as.h'`. Each frag represents a portion of the final object file. As GAS reads the source file, it creates frags to hold the data that it reads. At the end of the assembly the frags and fixups are processed to produce the final contents.

`fr_address`
  The address of the frag. This is not set until the assembler rescans the list of all frags after the entire input file is parsed. The function `relax_segment` fills in this field.
`fr_next`
  Pointer to the next frag in this (sub)section.
`fr_fix`
  Fixed number of characters we know we're going to emit to the output file. May be zero.
`fr_var`
  Variable number of characters we may output, after the initial `fr_fix` characters. May be zero.
`fr_offset`
  The interpretation of this field is controlled by `fr_type`. Generally, if `fr_var` is non-zero, this is a repeat count: the `fr_var` characters are output `fr_offset` times.
`line`
  Holds line number info when an assembler listing was requested.
`fr_type`
  Relaxation state. This field indicates the interpretation of `fr_offset`, `fr_symbol` and the variable-length tail of the frag, as well as the treatment it gets in various phases of processing. It does not affect the initial `fr_fix` characters; they are always supposed to be output verbatim (fixups aside). See below for specific values this field can have.
`fr_subtype`
  Relaxation substate. If the macro `md_relax_frag` isn't defined, this is assumed to be an index into `TC_GENERIC_RELAX_TABLE` for the generic relaxation code to process (see section Relaxation). If `md_relax_frag` is defined, this field is available for any use by the CPU-specific code.
`fr_symbol`
  This normally indicates the symbol to use when relaxing the frag according to `fr_type`.
`fr_opcode`
  Points to the lowest-addressed byte of the opcode, for use in relaxation.
`fr_pcrel_adjust`
`fr_bsr`
  These fields are only used in the NS32k configuration. But since `struct frag` is defined before the CPU-specific header files are included, they must unconditionally be defined.
`fr_file`
`fr_line`
  The file and line where this frag was last modified.
`fr_literal`
  Declared as a one-character array, this last field grows arbitrarily large to hold the actual contents of the frag.

These are the possible relaxation states, provided in the enumeration type `relax_stateT`, and the interpretations they represent for the other fields:

`rs_align`
`rs_align_code`
  The start of the following frag should be aligned on some boundary. In this frag, `fr_offset` is the logarithm (base 2) of the alignment in bytes. (For example, if alignment on an 8-byte boundary were desired, `fr_offset` would have a value of 3.) The variable characters indicate the fill pattern to be used. The `fr_subtype` field holds the maximum number of bytes to skip when doing this alignment. If more bytes are needed, the alignment is not done. An `fr_subtype` value of 0 means no maximum, which is the normal case. Target backends can use `rs_align_code` to handle certain types of alignment differently.
`rs_broken_word`
  This indicates that "broken word" processing should be done (see section Broken words). If broken word processing is not necessary on the target machine, this enumerator value will not be defined.
`rs_fill`
  The variable characters are to be repeated `fr_offset` times. If `fr_offset` is 0, this frag has a length of `fr_fix`. Most frags have this type.
`rs_machine_dependent`
  Displacement relaxation is to be done on this frag. The target is indicated by `fr_symbol` and `fr_offset`, and `fr_subtype` indicates the particular machine-specific addressing mode desired. See section Relaxation.
`rs_org`
  The start of the following frag should be pushed back to some specific offset within the section. (Some assemblers use the value as an absolute address; GAS does not handle final absolute addresses, but rather requires that the linker set them.) The offset is given by `fr_symbol` and `fr_offset`; one character from the variable-length tail is used as the fill character.

A chain of frags is built up for each subsection. The data structure describing a chain is called a `frchainS`, and contains the following fields:

`frch_root`
  Points to the first frag in the chain. May be NULL if there are no frags in this chain.
`frch_last`
  Points to the last frag in the chain, or NULL if there are none.
`frch_next`
  Next in the list of `frchainS` structures.
`frch_seg`
  Indicates the section this frag chain belongs to.
`frch_subseg`
  Subsection (subsegment) number of this frag chain.
`fix_root, fix_tail`
  (Defined only if `BFD_ASSEMBLER` is defined). Point to first and last `fixS` structures associated with this subsection.
`frch_obstack`
  Not currently used. Intended to be used for frag allocation for this subsection. This should reduce frag generation caused by switching sections.
`frch_frag_now`
  The current frag for this subsegment.

A `frchainS` corresponds to a subsection; each section has a list of `frchainS` records associated with it. In most cases, only one subsection of each section is used, so the list will only be one element long, but any processing of frag chains should be prepared to deal with multiple chains per section.

After the input files have been completely processed, and no more frags are to be generated, the frag chains are joined into one per section for further processing. After this point, it is safe to operate on one chain per section.

The assembler always has a current frag, named `frag_now`. More space is allocated for the current frag using the `frag_more` function; this returns a pointer to the amount of requested space. Relaxing is done using variant frags allocated by `frag_var` or `frag_variant` (see section Relaxation).

Go to the first, previous, next, last section, table of contents.