1.\" $NetBSD: stab.5,v 1.11 2002/02/13 08:18:16 ross Exp $ 2.\" 3.\" Copyright (c) 1980, 1991, 1993 4.\" The Regents of the University of California. All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. All advertising materials mentioning features or use of this software 15.\" must display the following acknowledgement: 16.\" This product includes software developed by the University of 17.\" California, Berkeley and its contributors. 18.\" 4. Neither the name of the University nor the names of its contributors 19.\" may be used to endorse or promote products derived from this software 20.\" without specific prior written permission. 21.\" 22.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 23.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 24.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 25.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 26.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 27.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 28.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 29.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 30.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 31.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 32.\" SUCH DAMAGE. 33.\" 34.\" @(#)stab.5 8.1 (Berkeley) 6/5/93 35.\" 36.Dd June 5, 1993 37.Dt STAB 5 38.Os 39.Sh NAME 40.Nm stab 41.Nd symbol table types 42.Sh SYNOPSIS 43.Fd #include \*[Lt]stab.h\*[Gt] 44.Sh DESCRIPTION 45The file 46.Aq Pa stab.h 47defines some of the symbol table 48.Fa n_type 49field values for a.out files. 50These are the types for permanent symbols (i.e. not local labels, etc.) 51used by the old debugger 52.Em sdb 53and the Berkeley Pascal compiler 54.Ic pc . 55Symbol table entries can be produced by the 56.Pa .stabs 57assembler directive. 58This allows one to specify a double-quote delimited name, a symbol type, 59one char and one short of information about the symbol, and an unsigned 60long (usually an address). 61To avoid having to produce an explicit label for the address field, 62the 63.Pa .stabd 64directive can be used to implicitly address the current location. 65If no name is needed, symbol table entries can be generated using the 66.Pa .stabn 67directive. 68The loader promises to preserve the order of symbol table entries produced 69by 70.Pa .stab 71directives. 72As described in 73.Xr a.out 5 , 74an element of the symbol table 75consists of the following structure: 76.Bd -literal 77/* 78* Format of a symbol table entry. 79*/ 80 81struct nlist { 82 union { 83 char *n_name; /* for use when in-core */ 84 long n_strx; /* index into file string table */ 85 } n_un; 86 unsigned char n_type; /* type flag */ 87 char n_other; /* unused */ 88 short n_desc; /* see struct desc, below */ 89 unsigned n_value; /* address or offset or line */ 90}; 91.Ed 92.Pp 93The low bits of the 94.Fa n_type 95field are used to place a symbol into 96at most one segment, according to 97the following masks, defined in 98.Aq Pa a.out.h . 99A symbol can be in none of these segments by having none of these segment 100bits set. 101.Bd -literal 102/* 103* Simple values for n_type. 104*/ 105 106#define N_UNDF 0x0 /* undefined */ 107#define N_ABS 0x2 /* absolute */ 108#define N_TEXT 0x4 /* text */ 109#define N_DATA 0x6 /* data */ 110#define N_BSS 0x8 /* bss */ 111 112#define N_EXT 01 /* external bit, or'ed in */ 113.Ed 114.Pp 115The 116.Fa n_value 117field of a symbol is relocated by the linker, 118.Xr ld 1 119as an address within the appropriate segment. 120.Fa n_value 121fields of symbols not in any segment are unchanged by the linker. 122In addition, the linker will discard certain symbols, according to rules 123of its own, unless the 124.Fa n_type 125field has one of the following bits set: 126.Bd -literal 127/* 128* Other permanent symbol table entries have some of the N_STAB bits set. 129* These are given in \*[Lt]stab.h\*[Gt] 130*/ 131 132#define N_STAB 0xe0 /* if any of these bits set, don't discard */ 133.Ed 134.Pp 135This allows up to 112 (7 \(** 16) symbol types, split between the various 136segments. 137Some of these have already been claimed. 138The old symbolic debugger, 139.Em sdb , 140uses the following n_type values: 141.Bd -literal 142#define N_GSYM 0x20 /* global symbol: name,,0,type,0 */ 143#define N_FNAME 0x22 /* procedure name (f77 kludge): name,,0 */ 144#define N_FUN 0x24 /* procedure: name,,0,linenumber,address */ 145#define N_STSYM 0x26 /* static symbol: name,,0,type,address */ 146#define N_LCSYM 0x28 /* .lcomm symbol: name,,0,type,address */ 147#define N_RSYM 0x40 /* register sym: name,,0,type,register */ 148#define N_SLINE 0x44 /* src line: 0,,0,linenumber,address */ 149#define N_SSYM 0x60 /* structure elt: name,,0,type,struct_offset */ 150#define N_SO 0x64 /* source file name: name,,0,0,address */ 151#define N_LSYM 0x80 /* local sym: name,,0,type,offset */ 152#define N_SOL 0x84 /* #included file name: name,,0,0,address */ 153#define N_PSYM 0xa0 /* parameter: name,,0,type,offset */ 154#define N_ENTRY 0xa4 /* alternative entry: name,linenumber,address */ 155#define N_LBRAC 0xc0 /* left bracket: 0,,0,nesting level,address */ 156#define N_RBRAC 0xe0 /* right bracket: 0,,0,nesting level,address */ 157#define N_BCOMM 0xe2 /* begin common: name,, */ 158#define N_ECOMM 0xe4 /* end common: name,, */ 159#define N_ECOML 0xe8 /* end common (local name): ,,address */ 160#define N_LENG 0xfe /* second stab entry with length information */ 161.Ed 162.Pp 163where the comments give 164.Em sdb 165conventional use for 166.Pa .stab 167.Fa s 168and the 169.Fa n_name , 170.Fa n_other , 171.Fa n_desc , 172and 173.Fa n_value 174fields 175of the given 176.Fa n_type . 177.Em Sdb 178uses the 179.Fa n_desc 180field to hold a type specifier in the form used 181by the Portable C Compiler, 182.Xr cc 1 ; 183see the header file 184.Pa pcc.h 185for details on the format of these type values. 186.Pp 187The Berkeley Pascal compiler, 188.Ic pc , 189uses the following 190.Fa n_type 191value: 192.Bd -literal 193#define N_PC 0x30 /* global pascal symbol: name,,0,subtype,line */ 194.Ed 195.Pp 196and uses the following subtypes to do type checking across separately 197compiled files: 198.Bd -unfilled -offset indent 1991 source file name 2002 included file name 2013 global label 2024 global constant 2035 global type 2046 global variable 2057 global function 2068 global procedure 2079 external function 20810 external procedure 20911 library variable 21012 library routine 211.Ed 212.Sh SEE ALSO 213.Xr as 1 , 214.Xr gdb 1 , 215.Xr ld 1 , 216.Xr a.out 5 217.Sh HISTORY 218The 219.Nm stab 220file appeared in 221.Bx 4.0 . 222.Sh BUGS 223More basic types are needed. 224