STFD(3)             RISC/os Reference Manual              STFD(3)



NAME
     stfd - routines that provide access to per file descriptor
          section of the symbol table

SYNOPSIS
     #include <syms.h>

     long stcurrentifd ()

     long stifdmax ()

     void stsetfd (ifd)
     long ifd;

     long stfdadd (filename)
     char *filename;

     long stsymadd (iss, value, st, sc, freloc, index)
     long iss;
     long value;
     long st;
     long sc;
     long freloc;
     long index;

     long stauxadd (aux)
     AUXU aux;

     long ststradd (cp)
     char *cp;

     long stlineadd (line)
     long line;

     long stpdadd (isym)
     long isym;

     long stifdpcfd (pcfd1)
     pCFDR pcfd1;

     pCFDR stpcfdifd (ifd)
     long ifd;

     pSYMR stpsymifdisym (ifd, isym)
     long ifd;
     long isym;

     pAUXU stpauxifdiaux (ifd, iaux)
     long ifd;
     long iaux;





                        Printed 11/19/92                   Page 1

STFD(3)             RISC/os Reference Manual              STFD(3)



     pAUXU stpauxiaux (iaux)
     long iaux;

     char *ststriss (iss)
     long iss;

     char *ststrifdiss (ifd, iss)
     long ifd;
     long iss;

     pPDR stppdifdisym (ifd, isym)
     long ifd;
     long isym;

     char * stmalloc (ptr, psize, itemsize, baseitems)
     char *ptr;
     long *size;
     long itemsize;
     long baseitems;

DESCRIPTION
     The stfd routines provide an interface to objects handled on
     a per file descriptor (or fd) level (for example, local sym-
     bols, auxiliaries, local strings, line numbers, optimization
     entries, procedure descriptor entries, and the file descrip-
     tors).  These routines constitute a group because they deal
     with objects corresponding to fields in the FDR structure.

     A fd can be activated by reading an existing one into memory
     or by creating a new one.  The compilation unit routines
     st_readbinary and st_readst read file descriptors and their
     constituent parts into memory from a symbol table on disk.

     st_fdadd adds a file descriptor to the list of file descrip-
     tors. The lang field is initialized from a user specified
     global st_lang that should be set to a constant designated
     for the language in symconst.h. The fMerge field is initial-
     ized from the user specified global st_merge that specifies
     whether the file is to start with the attribute of being
     able to be merged with identical files at load time. The
     fBigendian field is initialized by the gethostsex routine
     (see sex(3)), which determines the permanent byte ordering
     for the auxiliary and line number entries for this file.

     st_fdadd adds the null string to the new files string table
     that is accessible by the constant issNull (0).  It also
     adds the filename to the string table and sets the rss
     field. Finally, the current file is set to the newly added
     file so that later calls operate on that file.

     All routines for fd-level objects handle only the current
     file unless a file index is specified. The current file can



 Page 2                 Printed 11/19/92

STFD(3)             RISC/os Reference Manual              STFD(3)



     also be set with st_setfd.

     Programs can find the current file by calling st_currentifd,
     which returns the current index. Programs can find the
     number of files by calling st_ifdmax. The fd routines only
     require working with indices to do most things.  They allow
     more in-depth manipulation by allowing users to get the com-
     pile time file descriptor (CFDR) that contains memory
     pointers to the per file tables (rather than indices or
     offsets used in disk files). Users can retrieve a pointer to
     the CFDR by calling st_pcfd_ifd with the index to the
     desired file. The inverse mapping st_ifd_pcfd exists, as
     well.

     Each of fd's constituent parts has an add routine:
     st_symadd, st_stradd, st_lineadd, st_pdadd, and st_auxadd.
     The parameters of the add routines correspond to the fields
     of the added object. The pdadd routine lets users fill in
     the isym field only. Further information can be added by
     directly accessing the procedure descriptor entry.

     The add routines return an index that can be used to
     retrieve a pointer to part of the desired object with one of
     the following routines:  st_psym_isym, st_str_iss, and
     st_paux_iaux. NOTE: These routines only return objects
     within the current file. The following routines allow for
     file specification:  st_psym_ifd_isym, st_aux_ifd_iaux, and
     st_str_ifd_iss.

     st_ppd_ifd_isym allows access to procedures through the file
     index for the file where they occur and the isym field of
     the entry that points at the local symbol for that pro-
     cedure.

     The return index from st_symadd should be used to get a
     dense number (see stcu(3)). That number should be the ucode
     block number for the object the symbol describes.

AUTHOR
     Mark I. Himelstein.

SEE ALSO
     stcu(3), stfe(3).

BUGS
     The interface will added to incrementally, as needed.









                        Printed 11/19/92                   Page 3