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 assembler 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 provided 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 appropriate sizes), as an aid in determining how to segment large C files whose segments exceed the bank size, and for deciding which segments to recombine 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 algorithm, 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 arrays 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 _endStackCheck 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 hexidecimal.

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