mirror of https://github.com/GnoConsortium/gno.git
99 lines
3.4 KiB
Groff
99 lines
3.4 KiB
Groff
.\"
|
|
.\" $Id: lseg.1,v 1.3 1997/09/28 16:41:12 gdr Exp $
|
|
.\"
|
|
.TH LSEG 1 "September 1997" "GNO" "Commands and Applications"
|
|
.SH NAME
|
|
.BR lseg
|
|
\- list segments in an Object Module Format file
|
|
.SH SYNOPSIS
|
|
.BR lseg
|
|
.RB [ -d ]
|
|
.IR file " ..."
|
|
.SH DESCRIPTION
|
|
.BR 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
|
|
.IR "Apple IIGS GS/OS Reference" .
|
|
.PP
|
|
.BR lseg
|
|
prints a report that includes the type, size, and name of each segment of each
|
|
.IR file .
|
|
Any file that is not a valid OMF file is so noted.
|
|
.PP
|
|
.BR 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.
|
|
.PP
|
|
.BR 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.
|
|
.PP
|
|
You can combine
|
|
.BR lseg
|
|
with other tools to ensure your program allocates the correct
|
|
amount of run-time stack space:
|
|
.RS 1
|
|
.IP
|
|
Run
|
|
.BR 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
|
|
.IR malloc (3).
|
|
.IP
|
|
Add calls to the
|
|
.BR stack (3)
|
|
routines
|
|
.BR _beginStackCheck " and " _endStackCheck
|
|
to report overall run-time storage allocation.
|
|
.IP
|
|
You can also use ORCA/C's
|
|
.BR "#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.
|
|
.IP
|
|
Run
|
|
.BR 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
|
|
.BR "#pragma stacksize"
|
|
in programs compiled by ORCA/C.
|
|
.PP
|
|
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.
|
|
.PP
|
|
Note: Be sure to remove run-time checking in the final version of you
|
|
program after you determine the appropriate stack size.
|
|
.PP
|
|
.BR lseg
|
|
returns status of 0 on success, and >0 if an error (e.g., file
|
|
not found) occurs.
|
|
.SH OPTIONS
|
|
.BR lseg
|
|
recognizes one option:
|
|
.IP \fB-d\fR
|
|
Print the segment and stack sizes in decimal rather than hexidecimal.
|
|
.SH AUTHOR
|
|
Jawaid Bazyar for GNO/ME 1.0; updated by Dave Tribby for GNO/ME 2.0.6.
|