<HTML> <HEAD> <!-- This HTML file has been created by texi2html 1.51 from /mnt/apple/gdb/source/gdb.apple/source/gdb/gdb/doc/stabs.texinfo on 23 November 1999 --> <TITLE>STABS - Variables</TITLE> </HEAD> <BODY> Go to the <A HREF="stabs_1.html">first</A>, <A HREF="stabs_3.html">previous</A>, <A HREF="stabs_5.html">next</A>, <A HREF="stabs_14.html">last</A> section, <A HREF="stabs_toc.html">table of contents</A>. <P><HR><P> <H1><A NAME="SEC17" HREF="stabs_toc.html#TOC17">Variables</A></H1> <P> Different types of stabs describe the various ways that variables can be allocated: on the stack, globally, in registers, in common blocks, statically, or as arguments to a function. </P> <H2><A NAME="SEC18" HREF="stabs_toc.html#TOC18">Automatic Variables Allocated on the Stack</A></H2> <P> If a variable's scope is local to a function and its lifetime is only as long as that function executes (C calls such variables <STRONG>automatic</STRONG>), it can be allocated in a register (see section <A HREF="stabs_4.html#SEC20">Register Variables</A>) or on the stack. </P> <P> <A NAME="IDX25"></A> <A NAME="IDX26"></A> Each variable allocated on the stack has a stab with the symbol descriptor omitted. Since type information should begin with a digit, <SAMP>`-'</SAMP>, or <SAMP>`('</SAMP>, only those characters precluded from being used for symbol descriptors. However, the Acorn RISC machine (ARM) is said to get this wrong: it puts out a mere type definition here, without the preceding <SAMP>`<VAR>type-number</VAR>='</SAMP>. This is a bad idea; there is no guarantee that type descriptors are distinct from symbol descriptors. Stabs for stack variables use the <CODE>N_LSYM</CODE> stab type, or <CODE>C_LSYM</CODE> for XCOFF. </P> <P> The value of the stab is the offset of the variable within the local variables. On most machines this is an offset from the frame pointer and is negative. The location of the stab specifies which block it is defined in; see section <A HREF="stabs_2.html#SEC14">Block Structure</A>. </P> <P> For example, the following C code: </P> <PRE> int main () { int x; } </PRE> <P> produces the following stabs: </P> <PRE> .stabs "main:F1",36,0,0,_main # 36 is N_FUN .stabs "x:1",128,0,0,-12 # 128 is N_LSYM .stabn 192,0,0,LBB2 # 192 is N_LBRAC .stabn 224,0,0,LBE2 # 224 is N_RBRAC </PRE> <P> See section <A HREF="stabs_2.html#SEC12">Procedures</A> for more information on the <CODE>N_FUN</CODE> stab, and section <A HREF="stabs_2.html#SEC14">Block Structure</A> for more information on the <CODE>N_LBRAC</CODE> and <CODE>N_RBRAC</CODE> stabs. </P> <H2><A NAME="SEC19" HREF="stabs_toc.html#TOC19">Global Variables</A></H2> <P> <A NAME="IDX27"></A> <A NAME="IDX28"></A> A variable whose scope is not specific to just one source file is represented by the <SAMP>`G'</SAMP> symbol descriptor. These stabs use the <CODE>N_GSYM</CODE> stab type (C_GSYM for XCOFF). The type information for the stab (see section <A HREF="stabs_1.html#SEC4">The String Field</A>) gives the type of the variable. </P> <P> For example, the following source code: </P> <PRE> char g_foo = 'c'; </PRE> <P> yields the following assembly code: </P> <PRE> .stabs "g_foo:G2",32,0,0,0 # 32 is N_GSYM .global _g_foo .data _g_foo: .byte 99 </PRE> <P> The address of the variable represented by the <CODE>N_GSYM</CODE> is not contained in the <CODE>N_GSYM</CODE> stab. The debugger gets this information from the external symbol for the global variable. In the example above, the <CODE>.global _g_foo</CODE> and <CODE>_g_foo:</CODE> lines tell the assembler to produce an external symbol. </P> <P> Some compilers, like GCC, output <CODE>N_GSYM</CODE> stabs only once, where the variable is defined. Other compilers, like SunOS4 /bin/cc, output a <CODE>N_GSYM</CODE> stab for each compilation unit which references the variable. </P> <H2><A NAME="SEC20" HREF="stabs_toc.html#TOC20">Register Variables</A></H2> <P> <A NAME="IDX29"></A> <A NAME="IDX30"></A> Register variables have their own stab type, <CODE>N_RSYM</CODE> (<CODE>C_RSYM</CODE> for XCOFF), and their own symbol descriptor, <SAMP>`r'</SAMP>. The stab's value is the number of the register where the variable data will be stored. </P> <P> AIX defines a separate symbol descriptor <SAMP>`d'</SAMP> for floating point registers. This seems unnecessary; why not just just give floating point registers different register numbers? I have not verified whether the compiler actually uses <SAMP>`d'</SAMP>. </P> <P> If the register is explicitly allocated to a global variable, but not initialized, as in: </P> <PRE> register int g_bar asm ("%g5"); </PRE> <P> then the stab may be emitted at the end of the object file, with the other bss symbols. </P> <H2><A NAME="SEC21" HREF="stabs_toc.html#TOC21">Common Blocks</A></H2> <P> A common block is a statically allocated section of memory which can be referred to by several source files. It may contain several variables. I believe Fortran is the only language with this feature. </P> <P> <A NAME="IDX31"></A> <A NAME="IDX32"></A> <A NAME="IDX33"></A> <A NAME="IDX34"></A> A <CODE>N_BCOMM</CODE> stab begins a common block and an <CODE>N_ECOMM</CODE> stab ends it. The only field that is significant in these two stabs is the string, which names a normal (non-debugging) symbol that gives the address of the common block. According to IBM documentation, only the <CODE>N_BCOMM</CODE> has the name of the common block (even though their compiler actually puts it both places). </P> <P> <A NAME="IDX35"></A> <A NAME="IDX36"></A> The stabs for the members of the common block are between the <CODE>N_BCOMM</CODE> and the <CODE>N_ECOMM</CODE>; the value of each stab is the offset within the common block of that variable. IBM uses the <CODE>C_ECOML</CODE> stab type, and there is a corresponding <CODE>N_ECOML</CODE> stab type, but Sun's Fortran compiler uses <CODE>N_GSYM</CODE> instead. The variables within a common block use the <SAMP>`V'</SAMP> symbol descriptor (I believe this is true of all Fortran variables). Other stabs (at least type declarations using <CODE>C_DECL</CODE>) can also be between the <CODE>N_BCOMM</CODE> and the <CODE>N_ECOMM</CODE>. </P> <H2><A NAME="SEC22" HREF="stabs_toc.html#TOC22">Static Variables</A></H2> <P> Initialized static variables are represented by the <SAMP>`S'</SAMP> and <SAMP>`V'</SAMP> symbol descriptors. <SAMP>`S'</SAMP> means file scope static, and <SAMP>`V'</SAMP> means procedure scope static. One exception: in XCOFF, IBM's xlc compiler always uses <SAMP>`V'</SAMP>, and whether it is file scope or not is distinguished by whether the stab is located within a function. </P> <P> <A NAME="IDX37"></A> <A NAME="IDX38"></A> <A NAME="IDX39"></A> <A NAME="IDX40"></A> In a.out files, <CODE>N_STSYM</CODE> means the data section, <CODE>N_FUN</CODE> means the text section, and <CODE>N_LCSYM</CODE> means the bss section. For those systems with a read-only data section separate from the text section (Solaris), <CODE>N_ROSYM</CODE> means the read-only data section. </P> <P> For example, the source lines: </P> <PRE> static const int var_const = 5; static int var_init = 2; static int var_noinit; </PRE> <P> yield the following stabs: </P> <PRE> .stabs "var_const:S1",36,0,0,_var_const # 36 is N_FUN ... .stabs "var_init:S1",38,0,0,_var_init # 38 is N_STSYM ... .stabs "var_noinit:S1",40,0,0,_var_noinit # 40 is N_LCSYM </PRE> <P> <A NAME="IDX41"></A> <A NAME="IDX42"></A> <A NAME="IDX43"></A> In XCOFF files, the stab type need not indicate the section; <CODE>C_STSYM</CODE> can be used for all statics. Also, each static variable is enclosed in a static block. A <CODE>C_BSTAT</CODE> (emitted with a <SAMP>`.bs'</SAMP> assembler directive) symbol begins the static block; its value is the symbol number of the csect symbol whose value is the address of the static block, its section is the section of the variables in that static block, and its name is <SAMP>`.bs'</SAMP>. A <CODE>C_ESTAT</CODE> (emitted with a <SAMP>`.es'</SAMP> assembler directive) symbol ends the static block; its name is <SAMP>`.es'</SAMP> and its value and section are ignored. </P> <P> In ECOFF files, the storage class is used to specify the section, so the stab type need not indicate the section. </P> <P> In ELF files, for the SunPRO compiler version 2.0.1, symbol descriptor <SAMP>`S'</SAMP> means that the address is absolute (the linker relocates it) and symbol descriptor <SAMP>`V'</SAMP> means that the address is relative to the start of the relevant section for that compilation unit. SunPRO has plans to have the linker stop relocating stabs; I suspect that their the debugger gets the address from the corresponding ELF (not stab) symbol. I'm not sure how to find which symbol of that name is the right one. The clean way to do all this would be to have a the value of a symbol descriptor <SAMP>`S'</SAMP> symbol be an offset relative to the start of the file, just like everything else, but that introduces obvious compatibility problems. For more information on linker stab relocation, See section <A HREF="stabs_13.html#SEC89">Having the Linker Relocate Stabs in ELF</A>. </P> <H2><A NAME="SEC23" HREF="stabs_toc.html#TOC23">Fortran Based Variables</A></H2> <P> Fortran (at least, the Sun and SGI dialects of FORTRAN-77) has a feature which allows allocating arrays with <CODE>malloc</CODE>, but which avoids blurring the line between arrays and pointers the way that C does. In stabs such a variable uses the <SAMP>`b'</SAMP> symbol descriptor. </P> <P> For example, the Fortran declarations </P> <PRE> real foo, foo10(10), foo10_5(10,5) pointer (foop, foo) pointer (foo10p, foo10) pointer (foo105p, foo10_5) </PRE> <P> produce the stabs </P> <PRE> foo:b6 foo10:bar3;1;10;6 foo10_5:bar3;1;5;ar3;1;10;6 </PRE> <P> In this example, <CODE>real</CODE> is type 6 and type 3 is an integral type which is the type of the subscripts of the array (probably <CODE>integer</CODE>). </P> <P> The <SAMP>`b'</SAMP> symbol descriptor is like <SAMP>`V'</SAMP> in that it denotes a statically allocated symbol whose scope is local to a function; see See section <A HREF="stabs_4.html#SEC22">Static Variables</A>. The value of the symbol, instead of being the address of the variable itself, is the address of a pointer to that variable. So in the above example, the value of the <CODE>foo</CODE> stab is the address of a pointer to a real, the value of the <CODE>foo10</CODE> stab is the address of a pointer to a 10-element array of reals, and the value of the <CODE>foo10_5</CODE> stab is the address of a pointer to a 5-element array of 10-element arrays of reals. </P> <H2><A NAME="SEC24" HREF="stabs_toc.html#TOC24">Parameters</A></H2> <P> Formal parameters to a function are represented by a stab (or sometimes two; see below) for each parameter. The stabs are in the order in which the debugger should print the parameters (i.e., the order in which the parameters are declared in the source file). The exact form of the stab depends on how the parameter is being passed. </P> <P> <A NAME="IDX44"></A> <A NAME="IDX45"></A> Parameters passed on the stack use the symbol descriptor <SAMP>`p'</SAMP> and the <CODE>N_PSYM</CODE> symbol type (or <CODE>C_PSYM</CODE> for XCOFF). The value of the symbol is an offset used to locate the parameter on the stack; its exact meaning is machine-dependent, but on most machines it is an offset from the frame pointer. </P> <P> As a simple example, the code: </P> <PRE> main (argc, argv) int argc; char **argv; </PRE> <P> produces the stabs: </P> <PRE> .stabs "main:F1",36,0,0,_main # 36 is N_FUN .stabs "argc:p1",160,0,0,68 # 160 is N_PSYM .stabs "argv:p20=*21=*2",160,0,0,72 </PRE> <P> The type definition of <CODE>argv</CODE> is interesting because it contains several type definitions. Type 21 is pointer to type 2 (char) and <CODE>argv</CODE> (type 20) is pointer to type 21. </P> <P> The following symbol descriptors are also said to go with <CODE>N_PSYM</CODE>. The value of the symbol is said to be an offset from the argument pointer (I'm not sure whether this is true or not). </P> <PRE> pP (<<??>>) pF Fortran function parameter X (function result variable) </PRE> <H3><A NAME="SEC25" HREF="stabs_toc.html#TOC25">Passing Parameters in Registers</A></H3> <P> If the parameter is passed in a register, then traditionally there are two symbols for each argument: </P> <PRE> .stabs "arg:p1" . . . ; N_PSYM .stabs "arg:r1" . . . ; N_RSYM </PRE> <P> Debuggers use the second one to find the value, and the first one to know that it is an argument. </P> <P> <A NAME="IDX46"></A> <A NAME="IDX47"></A> Because that approach is kind of ugly, some compilers use symbol descriptor <SAMP>`P'</SAMP> or <SAMP>`R'</SAMP> to indicate an argument which is in a register. Symbol type <CODE>C_RPSYM</CODE> is used in XCOFF and <CODE>N_RSYM</CODE> is used otherwise. The symbol's value is the register number. <SAMP>`P'</SAMP> and <SAMP>`R'</SAMP> mean the same thing; the difference is that <SAMP>`P'</SAMP> is a GNU invention and <SAMP>`R'</SAMP> is an IBM (XCOFF) invention. As of version 4.9, GDB should handle either one. </P> <P> There is at least one case where GCC uses a <SAMP>`p'</SAMP> and <SAMP>`r'</SAMP> pair rather than <SAMP>`P'</SAMP>; this is where the argument is passed in the argument list and then loaded into a register. </P> <P> According to the AIX documentation, symbol descriptor <SAMP>`D'</SAMP> is for a parameter passed in a floating point register. This seems unnecessary--why not just use <SAMP>`R'</SAMP> with a register number which indicates that it's a floating point register? I haven't verified whether the system actually does what the documentation indicates. </P> <P> On the sparc and hppa, for a <SAMP>`P'</SAMP> symbol whose type is a structure or union, the register contains the address of the structure. On the sparc, this is also true of a <SAMP>`p'</SAMP> and <SAMP>`r'</SAMP> pair (using Sun <CODE>cc</CODE>) or a <SAMP>`p'</SAMP> symbol. However, if a (small) structure is really in a register, <SAMP>`r'</SAMP> is used. And, to top it all off, on the hppa it might be a structure which was passed on the stack and loaded into a register and for which there is a <SAMP>`p'</SAMP> and <SAMP>`r'</SAMP> pair! I believe that symbol descriptor <SAMP>`i'</SAMP> is supposed to deal with this case (it is said to mean "value parameter by reference, indirect access"; I don't know the source for this information), but I don't know details or what compilers or debuggers use it, if any (not GDB or GCC). It is not clear to me whether this case needs to be dealt with differently than parameters passed by reference (see section <A HREF="stabs_4.html#SEC27">Passing Parameters by Reference</A>). </P> <H3><A NAME="SEC26" HREF="stabs_toc.html#TOC26">Storing Parameters as Local Variables</A></H3> <P> There is a case similar to an argument in a register, which is an argument that is actually stored as a local variable. Sometimes this happens when the argument was passed in a register and then the compiler stores it as a local variable. If possible, the compiler should claim that it's in a register, but this isn't always done. </P> <P> If a parameter is passed as one type and converted to a smaller type by the prologue (for example, the parameter is declared as a <CODE>float</CODE>, but the calling conventions specify that it is passed as a <CODE>double</CODE>), then GCC2 (sometimes) uses a pair of symbols. The first symbol uses symbol descriptor <SAMP>`p'</SAMP> and the type which is passed. The second symbol has the type and location which the parameter actually has after the prologue. For example, suppose the following C code appears with no prototypes involved: </P> <PRE> void subr (f) float f; { </PRE> <P> if <CODE>f</CODE> is passed as a double at stack offset 8, and the prologue converts it to a float in register number 0, then the stabs look like: </P> <PRE> .stabs "f:p13",160,0,3,8 # 160 is <CODE>N_PSYM</CODE>, here 13 is <CODE>double</CODE> .stabs "f:r12",64,0,3,0 # 64 is <CODE>N_RSYM</CODE>, here 12 is <CODE>float</CODE> </PRE> <P> In both stabs 3 is the line number where <CODE>f</CODE> is declared (see section <A HREF="stabs_2.html#SEC11">Line Numbers</A>). </P> <P> <A NAME="IDX48"></A> GCC, at least on the 960, has another solution to the same problem. It uses a single <SAMP>`p'</SAMP> symbol descriptor for an argument which is stored as a local variable but uses <CODE>N_LSYM</CODE> instead of <CODE>N_PSYM</CODE>. In this case, the value of the symbol is an offset relative to the local variables for that function, not relative to the arguments; on some machines those are the same thing, but not on all. </P> <P> On the VAX or on other machines in which the calling convention includes the number of words of arguments actually passed, the debugger (GDB at least) uses the parameter symbols to keep track of whether it needs to print nameless arguments in addition to the formal parameters which it has printed because each one has a stab. For example, in </P> <PRE> extern int fprintf (FILE *stream, char *format, ...); ... fprintf (stdout, "%d\n", x); </PRE> <P> there are stabs for <CODE>stream</CODE> and <CODE>format</CODE>. On most machines, the debugger can only print those two arguments (because it has no way of knowing that additional arguments were passed), but on the VAX or other machines with a calling convention which indicates the number of words of arguments, the debugger can print all three arguments. To do so, the parameter symbol (symbol descriptor <SAMP>`p'</SAMP>) (not necessarily <SAMP>`r'</SAMP> or symbol descriptor omitted symbols) needs to contain the actual type as passed (for example, <CODE>double</CODE> not <CODE>float</CODE> if it is passed as a double and converted to a float). </P> <H3><A NAME="SEC27" HREF="stabs_toc.html#TOC27">Passing Parameters by Reference</A></H3> <P> If the parameter is passed by reference (e.g., Pascal <CODE>VAR</CODE> parameters), then the symbol descriptor is <SAMP>`v'</SAMP> if it is in the argument list, or <SAMP>`a'</SAMP> if it in a register. Other than the fact that these contain the address of the parameter rather than the parameter itself, they are identical to <SAMP>`p'</SAMP> and <SAMP>`R'</SAMP>, respectively. I believe <SAMP>`a'</SAMP> is an AIX invention; <SAMP>`v'</SAMP> is supported by all stabs-using systems as far as I know. </P> <H3><A NAME="SEC28" HREF="stabs_toc.html#TOC28">Passing Conformant Array Parameters</A></H3> <P> Conformant arrays are a feature of Modula-2, and perhaps other languages, in which the size of an array parameter is not known to the called function until run-time. Such parameters have two stabs: a <SAMP>`x'</SAMP> for the array itself, and a <SAMP>`C'</SAMP>, which represents the size of the array. The value of the <SAMP>`x'</SAMP> stab is the offset in the argument list where the address of the array is stored (it this right? it is a guess); the value of the <SAMP>`C'</SAMP> stab is the offset in the argument list where the size of the array (in elements? in bytes?) is stored. </P> <P><HR><P> Go to the <A HREF="stabs_1.html">first</A>, <A HREF="stabs_3.html">previous</A>, <A HREF="stabs_5.html">next</A>, <A HREF="stabs_14.html">last</A> section, <A HREF="stabs_toc.html">table of contents</A>. </BODY> </HTML>