LSEG(1)                    Commands and Applications                   LSEG(1)

NAME

       lseg - list segments in an Object Module Format file

SYNOPSIS

       lseg [-d] file ...

DESCRIPTION

       lseg  lists  segments in an OMF (object module format) file. Four kinds
       of files use object module format: object files (the output of  an  as‐
       sembler or compiler and the input to a linker), library files (segments
       that a linker can extract to resolve references in other object files),
       load  files (the output of a linker, ready for execution), and run-time
       library files (segments that can be loaded as needed  and  purged  from
       memory when no longer needed).  A full description of OMF files is pro‐
       vided in Appendix F of Apple IIGS GS/OS Reference.

       lseg prints a report that includes the type, size,  and  name  of  each
       segment  of  each  file.   Any  file that is not a valid OMF file is so
       noted.

       lseg can be used on executable files in the  following  ways:  to  help
       discover the location of stack segments (for later editing to appropri‐
       ate sizes), as an aid in determining how to segment large C files whose
       segments  exceed  the bank size, and for deciding which segments to re‐
       combine after excessive segmentation.

       lseg examines each code segment and tries to figure out how many  bytes
       of  local  storage are allocated from the stack at execution time. This
       will be determined only if the startup code matches a recognized  algo‐
       rithm, such as those used by ORCA/C. If it can be determined, the value
       is printed in the column labeled "Stack".  This value does not  include
       parameters  passed  into  the routine, or other use of the stack by the
       routine.

       You can combine lseg with other tools to ensure your program  allocates
       the correct amount of run-time stack space:

               Run  lseg  on  your  program's object file to identify routines
               with significant local storage. If a segment has  an  unusually
               large  allocation,  examine its source code and see whether ar‐
               rays can be made static (if the routine is  not  recursive)  or
               can be allocated from standard memory by malloc(3).

               Add  calls  to the stack(3) routines _beginStackCheck and _end����
               StackCheck to report overall run-time storage allocation.

               You can also use ORCA/C's #pragma debug with a  parameter  that
               sets  bit  0  (a value of 1), which causes the run-time code to
               check stack space at the beginning of each  function  and  halt
               the program if there is not enough.

               Run lseg on your program's linked file to determine if it has a
               "Direct-page/Stack" segment. (If not, the system will  allocate
               4096 bytes of stack when it runs.)  You can set this value with
               #pragma stacksize in programs compiled by ORCA/C.

        If your program uses significantly less stack space at  run-time  than
        is specified in the Direct-page/Stack segment, reduce the size so more
        is available to other programs that run at the  same  time.   If  your
        program  uses  more  stack  space than allocated, it can cause serious
        problems such as system crashes.

        Note: Be sure to remove run-time checking in the final version of  you
        program after you determine the appropriate stack size.

        lseg  returns  status  of 0 on success, and >0 if an error (e.g., file
        not found) occurs.

OPTIONS

       lseg recognizes one option:

       -d     Print the segment and stack sizes in decimal  rather  than  hex‐
              idecimal.

AUTHOR

       Jawaid Bazyar for GNO/ME 1.0; updated by Dave Tribby for GNO/ME 2.0.6.



GNO                             September 1997                         LSEG(1)