.\"Modified from man(1) of FreeBSD, the NetBSD mdoc.template, and mdoc.samples.
.\"See Also:
.\"man mdoc.samples for a complete listing of options
.\"man mdoc for the short list of editing options
.\"/usr/share/misc/mdoc.template
.Dd 9/20/10               \" DATE 
.Dt symbols 1      \" Program name and manual section number 
.Os Darwin
.Sh NAME                 \" Section Header - required - don't modify 
.Nm symbols
.\" The following lines are read in generating the apropos(man -k) database. Use only key
.\" words here as the database is built based on the words here and in the .ND line. 
.\" Use .Nm macro to designate other names for the documented program.
.Nd display symbol information about a file or process
.Sh SYNOPSIS             \" Section Header - required - don't modify
.Nm
.Op Fl help
.Op Fl w
.Op Fl uuid
.Op Fl arch Ar arch_name
.Op Fl saveSignature Ar path
.Op Fl symbolsPackageDir Ar path
.Op Fl lookup Ar (0x1234 | symbol) ...
file...
pid...
process-name...
signature...
dSYM...
.Sh DESCRIPTION          \" Section Header - required - don't modify
The
.Nm
command may be used to examine library, symbol, and source line information in files and running processes.
.Pp
You may need root privileges to examine running processes.
.Pp
The symbols command can be used to determine symbol availability to tools such as Instruments, dtrace, and sample. 
.Sh COMMON OPTIONS
.Bl -tag -width "printDsymPaths "
.It Fl help
Print a more extensive list of options
.It Fl v
Print version information
.It Fl w
Print wide output, do not clip to terminal width
.It Fl uuid
Print UUID info only.
.It Fl arch Ar arch_name
Specify the target architecture. The default value is
.Ar current
, which matches the current system architecture. If the current architecture is not available in the targeted file or process, the symbols command will attempt to use
.Ar any64bit
, which matches the first available 64-bit architecture. If there is no 64-bit architecture available, the symbols command will finally fall back to
.Ar any
, which matches the first available architecture. The value
.Ar all
may be used to iterate over all architectures in a target. The arch name may also be any of the commonly used architecture mnemonics, for example
.Ar i386 ,
.Ar x86_64 ,
or
.Ar arm
.It Fl cpuType Ar #
Specify the target architecture cpu type as a numeric value
.It Fl cpuSubtype Ar #
Specify the target architecture cpu subtype as a numeric value
.It Fl noHeaders
Do not print library level information. This also suppresses printing of any lower level information, which implies
.Fl noRegions ,
.Fl noSymbols ,
and
.Fl noSources
.It Fl noRegions
Do not print segment/section level information. This also suppresses printing of any lower level information, which implies
.Fl noSymbols
and
.Fl noSources
.It Fl noSymbols
Do not print symbol level information. This also suppresses printing of any lower level information, which implies
.Fl noSources
.It Fl noSources
Do not print source level information
.It Fl noDemangling
Do not print the human readable form of symbol names, instead print the name used by the linker
.It Fl printSignature
Print a "signature" for each target, which can later be used as input to the symbols command. This is a way to archive target data for later use. See also the
.Fl saveSignature
flag
.It Fl deepSignature
Causes all signatures to be "deep copies", containing complete copies of all available information
.It Fl fullSourcePath
Print the entire source path for each source info
.It Fl printDsymPaths
Print the path of the dSYM file (if found) used when creating symbol information
.It Fl lookup Ar (0x1234 | symbol)
Find one or more addresses or symbols in the targets. Symbols may contain simple shell globbing style patterns.
.El
.Sh OUTPUT
Output from
.Nm
has the following format:
.Pp
target [arch_name, elapsed-time]:
  UUID symbol-owner-path [FLAGS]
    address (size) region-name
      address (size) symbol-name [FLAGS]
        address (size) sourcefile : line #
.Pp
Symbol owner flags have the following meanings:
.Pp
.Bl -tag -width "FaultedFromTask" -compact
.It PROT
A load command has the SG_PROTECTED_VERSION_1 flag set
.It AOUT
This symbol owner is an executable
.It DYLIB
This symbol owner is a dylib or framework
.It DYLIB-STUB
This symbol owner is used only by the linker
.It DYLD
This symbol owner is the runtime dynamic linker
.It BUNDLE
This symbol owner is a loadable bundle
.It OBJECT
This symbol owner is an unlinked object file
.It KEXT-BUNDLE
This symbol owner is a kext
.It dSYM_v#
This symbol owner is a dSYM, of version '#'
.It DYLDSHAREDCACHE
This symbol owner was found in the dyld shared cache
.It ObjC-RR
This symbol owner supports manual retain-release
.It ObjC-GC
This symbol owner supports old-style garbage collection
.It SLID
This symbol owner was relocated from its base address
.It PIE
This symbol owner is compiled position independent
.It RESTRICTED
This symbol owner has a restrict segment/section
.It STATIC-LIB
This symbol-owner is from a static library (.a)
.It FaultedFromDisk
The data for this symbol owner was found on disk
.It FaultedFromTask
The data for this symbol owner was retrieved from a running task
.It FaultedFromSelfDyldSharedCache
The data for this symbol owner was found in the current processes dyld shared cache
.It FilesetEntry
This symbol owner is a member of a fileset kernel collection
.It Found-dSYM
A dSYM was found for this symbol owner
.It Found-Binary-via-dSYM-colocation
The binary for this symbol owner was found by looking up the dSYM, and then looking next to the dSYM
.It Found-Binary-via-dSYM-plist
The binary for this symbol owner was found by looking up the dSYM, and then reading its plist
.It MMap32
The symbol owner is using a mmap'd file cache for symbol information
.It MMap64
The symbol owner is using a mmap'd file cache for symbol information
.It Private
This symbol owner cannot be cached
.It Empty
No data was found for this symbol owner
.El
.Pp
Symbol flags have the following meanings:
.Pp
.Bl -tag -width "NameDwarfMIPSLinkage " -compact
.It FUNC
This symbol has executable code
.It DYLD-STUB
This symbol is a stub used by the dynamic linker
.It OBJC
This symbol is an Objective C method
.It THUMB
This symbol uses thumb instruction encoding
.It OMIT-FP
This symbol does not create a frame pointer.
.It EXT
This symbol has external visibility
.It PEXT
This symbol has private-external visibility
.It LENGTH
The length of this symbol is known, not guessed
.It NameNList
The name of this symbol comes from NList data
.It NameDwarf
The name of this symbol comes from Dwarf data
.It NameDwarfMIPSLinkage
The name of this symbol is from specialized Dwarf 
.It MangledNameNList
The mangled name of this symbol is from NList data
.It MangledNameDwarf
The mangled name of this symbol is from Dwarf data
.It MangledNameDwarfMIPSLinkage
The mangled name of this symbol is from specialized Dwarf
.It Merged
This symbol has multiple data sources
.It NList
This symbol was found in NList data
.It Dwarf
This symbol was found in Dwarf data
.It DebugMap
This symbol was found in DebugMap data
.It FunctionStarts
This symbol was found in function starts data
.El
.Sh SOURCES OF SYMBOL INFORMATION
.Nm
uses multiple sources of symbol information. All sources are queried, and the resulting data is merged.
.Pp
NLIST symbol information is found in the LINKEDIT segment. It is imprecise, and only contains a starting address, not a length or ending address. Nlist data is not required to (and typically does not) reference all symbols. Usually only external symbol information is available. Even that may be removed by use of
.Xr strip 1
.Pp
DEBUG MAP
symbol information is multi-part. A per-symbol reference in the original file points to an external file containing additional debug information, usually DWARF.
.Pp
FUNCTION STARTS symbol information is found in the LC_FUNCTION_STARTS load command of the target. It is imprecise, and only contains a starting address, not a length or ending address. Furthermore, it contains no name or mangled name information. The LC_FUNCTION_STARTS load command is optional, it may not be found in all targets.
.Pp
DWARF symbol information is true debug info. It is usually precise (but it is not required to be). When available, dwarf information is treated as more reliable than any other information source, and conflicts are resolved in favor of dwarf data.
.Pp
DSYM. A dSYM is an external file containing DWARF and NLIST symbol information.
.Sh KERNEL SYMBOLS
Kernel symbols are available by using the special pid "-1". This includes loaded kexts.
.Sh SIGNATURES
A signature is the information needed to reconstruct symbol information at a later date. For example, a signature contains a list of libraries, and for each library a UUID and the addresses the segments were loaded at. You can also ask for a "deep" signature, which contains complete information about every piece of information symbols could find. This can be very useful for later diagnosis and exploration.
.Sh SYMBOLS PACKAGE
A symbols package is a directory with "deep" signatures for one or more binary images.  When a directory is specified with -symbolsPackageDir, symbols will output a deep signature for each binary image slice it reads.  These files contain enough information to symbolicate application stack traces (such as those generated by crash reports) with function names and file names/line numbers.
.Sh EXAMPLES
.Bl -tag -width indent
.It Li "symbols /System/Library/Frameworks/AppKit.framework/AppKit"
Print out all symbol and source line information in the default architecture of AppKit.
.It Li "symbols -uuid /System/Library/Frameworks/AppKit.framework/AppKit"
Print out summarized UUID information for each arch in AppKit.
.It Li "symbols -arch i386 /System/Library/Frameworks/AppKit.framework/AppKit"
Print out all symbol and source line information in the i386 architecture of AppKit.
.It Li "symbols 7085"
Print out all symbol and source line information in pid 7085.
.It Li "symbols 7085 -lookup 0x7fff5bf0008"
Print the symbol and source line information in pid 7085 at address 0x7fff5bf0008.
.It Li "symbols Safari"
Attempt to find a process named Safari, and print its symbol and source line information.
.It Li "symbols -deepSignature -saveSignature /tmp/Safari.signature Safari"
Attempt to find a process named Safari, and save a copy of all discoverable information to a file in /tmp.
.It Li "symbols /tmp/Safari.signature -lookup \(dq*alloc*\(dq"
Using the cached information in /tmp/Safari.signature, find every method/function matching the wildcard name *alloc*
.It Li "symbols -w -1"
Print out in wide format all available information on kernel symbols
.El