STFE(3X)STFE(3X)NAMEstfe - routines that provide a high-level interface to basic functions
needed to access and add 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);
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 manual page).
If it's 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
Page 1
STFE(3X)STFE(3X)
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
haven't 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
Page 2
STFE(3X)STFE(3X)
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.
Page 3
STFE(3X)STFE(3X)
The programs must be loaded with the object file access routine library
libmld.a.
SEE ALSOstcu(3x), stfd(3x)
Page 4
