stfe(3X)

NAME
     stfe - Routines that provide a high-level interface to the symbol
     table

SYNOPSIS
     #include <syms.h>

     "long st_filebegin(char *filename);

     "long st_endallfiles(void);

     "long st_fileend(long idn);

     "long st_blockbegin(long iss, long value, long sc);

     "long st_textblock(void);

     "long st_blockend(long size);

     "long st_procend(long idn);

     "long st_procbegin(long idn);

     "char *st_str_idn(long idn);

     "char *st_sym_idn(long idn, long *sc, long *st, long *value, long
     *index);

     "long st_abs_ifd_index(long ifd, long index);

     "long st_fglobal_idn(long idn);

     "pSYMR st_psym_idn_offset(long idn; long offset);

     "long st_pdadd_idn(long idn);

IMPLEMENTATION
     IRIX systems (o32 ABI only)

DESCRIPTION
     The stfe routines provide a high-level interface to the symbol table
     based on common needs of the compiler front-ends.

     st_filebegin
             Takes a file name and calls st_fdadd (see the stfd man page).
             If it is a new file, a symbol is added to the symbol table for
             it and the user supplied routine, st_feinit, is called.  This
             allows special once per file things to be initialized (for
             example, the C front-end adds basic type auxiliaries to each
             file's aux table so that all variables of that type can refer
             to a single instance instead of making individual copies of
             them).  st_filebegin returns a dense number that references
             the symbol added for this file.  It tracks files as they
             appear in a CPP line directive with a stack.  It detects (from
             the order of the CPP directives) that a file ends and calls
             st_filend.  If a file is closed with a st_fileend, a new
             instance of the filename is created (for example, multiply
             included files).

     st_fileend
             Requires the dense number from the corresponding st_filebegin
             call for the file in question.  It then generates an end
             symbol and patches the references so that the index field of
             the begin file points to that of one beyond the end file.  The
             end file points to the begin file.

     st_endallfiles
             Is called at the end of execution to close off all files that
             have not been ended by previous calls to st_filebegin.  CPP
             directives might not reflect the return to the original source
             file; therefore, this routine can possibly close many files.

     st_blockbegin
             Supports language blocks (for example, C's left curly brace
             blocks), beginning of structures, and unions.  If the storage
             class is scText, it is the former; if it is scInfo, it is one
             of the latter.  The iss (index into string space) specifies
             the name of the structure/etc, if any.

     If the storage class is scText, we must check the result of
     st_blockbegin.  It returns a dense number for outer blocks and a zero
     for nested blocks.  The non-zero block number should be used in the
     BGNB ucode.  Users of languages without nested blocks that provide
     variable declarations can ignore the rest of this paragraph.  Nested
     blocks are two-staged: one stage happens when we detect the language
     block and the other stage happens when we know the block has content.
     If the block has content (for example, local variables), the front-end
     must call st_textblock to get a non-zero dense number for the block's
     BGNB ucode. If the block has no content and st_textblock is not
     called, the block's st_blockbegin and st_blockend do not produce block
     and end symbols.

     If it is scInfo, st_blockbegin creates a begin block symbol in the
     symbol table and returns a dense number referencing it.  The dense
     number is necessary to build the auxiliary required to reference the
     structure/etc. It goes in the aux after the TIR along with a file
     index. This dense number is also noted in a stack of blocks used by
     st_blockend.

     st_blockbegin should not be called for language blocks when the
     front-end is not producing debugging symbols.

     st_blockend requires that blocks occur in a nested fashion. It
     retrieves the dense number for the most recently started block and
     creates a corresponding end symbol. As in fileend, both the begin and
     end symbol index fields point at the other end's symbol.  If the
     symbol ends a structure/etc., as determined by the storage class of
     the begin symbol, the size parameter is assigned to the begin symbol's
     value field.  It's usually the size of the structure or max value of a
     enum.  We only know it at this point. The dense number of the end
     symbol is returned so that the ucode ENDB can be use it.  If it is an
     ignored text block, the dense number is zero and no ENDB should be
     generated.

     In general, defined external procedures or functions appear in the
     symbols table and the externals table. The external table definition
     must occur first through the use of a st_extadd.  After that
     definition, st_procbegin can be called with a dense number referring
     to the external symbol for that procedure. It checks to be sure we
     have a defined procedure (by checking the storage class). It adds a
     procedure symbol to the symbol table. The external's index should
     point at its auxiliary data type information (or if debugging is off,
     indexNil).  This index is copied into the regular symbol's index field
     or a copy of its type is generated (if the external is in a different
     file than the regular symbol).  Next, we put the index to symbol in
     the external's index field. The external's dense number is used as a
     block number in ucodes referencing it and is used to add a procedure
     when in the st_pdadd_idn.

     st_procend
             Creates an end symbol and fixes the indices as in blockend and
             fileend, except that the end procedure reference is kept in
             the begin procedure's aux rather than in the index field
             (because the begin procedure has a type as well as an end
             reference). This must be called with the dense number of the
             procedure's external symbol as an argument and returns the
             dense number of the end symbol to be used in the END ucode.

     st_str_idn
             Returns the string associated with symbol or external
             referenced by the dense number argument. If the symbol was
             anonymous (for example, there was no symbol) a (char *)-1 is
             returned.

     st_sym_idn
             Returns the same result as st_str_idn, except that the rest of
             the fields of the symbol specified by the idn are returned in
             the arguments.

     st_fglobal_idn
             Returns a 1 if the symbol associated with the specified idn is
             non-static; otherwise, a 0 is returned.

     st_abs_ifd_index
             Returns the absolute offset for a dense number. If the symbol
             is global, the global's index is returned. If the symbol
             occurred in a file, the sum of all symbols in files occurring
             before that file and the symbol's index within the file is
             returned.

     st_pdadd_idn
             Adds an entry to the procedure table for the st_proc entry
             generated by procbegin. This should be called when the front-
             end generates code for the procedure in question.

     The programs must be loaded with the object file access routine
     library libmld.a.

SEE ALSO
     stcu(3x), stfd(3x)

     This man page is available only online.