ruby-elf 1.0.0

data/manpages/missingstatic.1

@@ -0,0 +1,176 @@
+'\" t
+.\"     Title: missingstatic
+.\"    Author: 
+.\" Generator: DocBook XSL-NS Stylesheets v1.76.0 <http://docbook.sf.net/>
+.\"      Date: October 2008
+.\"    Manual: Reference
+.\"    Source: ruby-elf
+.\"  Language: English
+.\"
+.TH "MISSINGSTATIC" "1" "October 2008" "ruby-elf" "Reference"
+.\" -----------------------------------------------------------------
+.\" * Define some portability stuff
+.\" -----------------------------------------------------------------
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.\" http://bugs.debian.org/507673
+.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\" -----------------------------------------------------------------
+.\" * set default formatting
+.\" -----------------------------------------------------------------
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.\" -----------------------------------------------------------------
+.\" * MAIN CONTENT STARTS HERE *
+.\" -----------------------------------------------------------------
+.SH "NAME"
+missingstatic \- ELF analyzer to identify missing static modifiers
+.SH "SYNOPSIS"
+.HP \w'\fBmissingstatic\fR\ 'u
+\fBmissingstatic\fR [\fB\-\-hidden\-only\fR] [\fB\-\-show\-type\fR] [\fB\-\-exclude\-regexp\fR\ \fIregular\-expression\fR] [\fB\-\-exclude\-tags\fR\ \fItags\-file\fR] [\fB\-\-quiet\fR] [\fB\-\-recursive\fR] [\fB@\fR\fIfile\fR | \fIfile\fR...]
+.SH "DESCRIPTION"
+.PP
+
+\fBmissingstatic\fR
+is a script that analyses ELF object files to identify symbols that are unused outside their compilation unit\&. Those symbols are usually candidate for the
+\fBstatic\fR
+modifier, to make the symbol local to the unit\&.
+.PP
+In addition to symbols that are used only internally to an unit, this script will most likely report the almost entire set of externally\-visible API in the case of libraries\&. For this reason, options are provided to reduce the scope of action\&.
+.SH "OPTIONS"
+.PP
+\fB\-h\fR, \fB\-\-hidden\-only\fR
+.RS 4
+Only show symbols that have hidden visibility\&. Hidden symbols are not visible from outside the module, and thus will ignore the external visible symbols that compose the externally\-visible API\&. This option is only useful for libraries that make proper use of visibility attributes\&.
+.RE
+.PP
+\fB\-t\fR, \fB\-\-show\-type\fR
+.RS 4
+Show the type of the symbol\&. The symbols reported by the script might be functions, variables, or constants\&. By default, only the name of the symbol, with this option, a letter in front of the symbol will tell you the type of it; the letters are the same as used by GNU
+\fBnm\fR(1):
+.PP
+T
+.RS 4
+The symbol is in the text (code) section, and is thus a function
+.RE
+.PP
+B
+.RS 4
+The symbol is in the uninitialised data section (known as BSS), and is thus a variable\&.
+.RE
+.PP
+D
+.RS 4
+The symbol is in the initialised data section, and is thus a variable\&.
+.RE
+.PP
+R
+.RS 4
+The symbol is in the read only data section, and is thus a constant\&.
+.RE
+.sp
+.RE
+.PP
+\fB\-x\fR \fIregular\-expression\fR, \fB\-\-exclude\-regexp\fR \fIregular\-expression\fR
+.RS 4
+Ignore symbols whose name triggers the given regular expression\&. This option is useful to hide all the symbols of the public API of a library if they all have the same prefix\&. It can be used multiple times\&.
+.RE
+.PP
+\fB\-X\fR \fItags\-file\fR, \fB\-\-exclude\-tags\fR \fItags\-file\fR
+.RS 4
+Ignore symbols present in a tags file created by
+\fBexuberant\-ctags\fR\&. This option is useful to hide all the symbols in the public header files of a project, by creating a list of public\-visible symbols\&. See the
+EXAMPLES
+section for how to generate such a tags file\&. It can be used multiple times\&.
+.RE
+.PP
+\fB\-q\fR, \fB\-\-quiet\fR
+.RS 4
+Do not output warnings and errors to the standard error\&. Designed to increase the signal\-to\-noise ratio when analysing eterogeneous trees recursively, or when producing output to redirect to automated systems\&.
+.RE
+.PP
+\fB\-R\fR, \fB\-\-recursive\fR
+.RS 4
+Recursively descend into directories to search for files to scan\&. This affects both the paths passed from the command line and those found in argument files\&.
+.RE
+.PP
+\fB@\fR\fIpath\fR
+.RS 4
+Read the list of files to analyse from the given file (or standard input if
+\fIpath\fR
+is
+\-)\&. Useful to pass a long list of files\&. When used with stdin or named pipes, this also allows asynchronous analysis\&.
+.RE
+.SH "EXAMPLES"
+.SS "Generating the tags file"
+.PP
+To generate a tags file compatible with the
+\fB\-\-exclude\-tags\fR
+command\-line option, you can use
+\fBexuberant-ctags\fR(1)
+with a command similar to the following:
+.PP
+\fBExample\ \&1.\ \& Generate a tags file for public header files\fR
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+              exuberant\-ctags \-\-c\-kinds=px \-f public\-symbols include/public/*\&.h
+            
+.fi
+.if n \{\
+.RE
+.\}
+.SS "Sorting missingstatic output"
+.PP
+Since sorting by translation unit is non\-trivial inside the script, piping through
+\fBsort\fR(1)
+is suggested\&. Using the
+\fB\-k\fR
+option it\*(Aqs possible to sort for the desired key, may it be the symbol name, the translation unit name or the symbol type\&.
+.PP
+\fBExample\ \&2.\ \&Sorting missingstatic output for translation unit name\fR
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+              find \&. \-name \*(Aq*\&.o\*(Aq | missingstatic \-h | sort \-k2
+            
+.fi
+.if n \{\
+.RE
+.\}
+.SH "BUGS AND MISSING FEATURES"
+.PP
+
+\fBmissingstatic\fR
+assumes that all the sources for a module and just that module will be passed to it, if more or less sources will be passed to the command, the results might not be the expected ones\&.
+.PP
+Parsing of files to provide further arguments (\fB@\fR\fIfile\fR) is not entirely comforming to other tools handling of the same syntax\&. No options are parsed from the file, and filenames are expected to be separated by newlines rather than whitespace\&.
+.PP
+Symbolic links are only followed when they are passed directly to the command line, or through @\-lists; symbolic links are
+\fInot\fR
+followed when using the
+\fB\-\-recursive\fR
+option, to avoid loops\&.
+.SH "SEE ALSO"
+.PP
+
+\m[blue]\fBFlameeyes\*(Aqs Weblog\fR\m[]
+http://blog\&.flameeyes\&.eu/
+.PP
+Related tools:
+\fBnm\fR(1),
+\fBexuberant-ctags\fR(1)\&.
+.SH "AUTHOR"
+.PP
+\fBDiego E. Pettenò\fR <\&flameeyes@gmail.com\&>
+.RS 4
+Author and main contributor.
+.RE

data/manpages/rbelf-size.1

@@ -0,0 +1,186 @@
+'\" t
+.\"     Title: rbelf-size
+.\"    Author: 
+.\" Generator: DocBook XSL-NS Stylesheets v1.76.0 <http://docbook.sf.net/>
+.\"      Date: October 2008
+.\"    Manual: Reference
+.\"    Source: ruby-elf
+.\"  Language: English
+.\"
+.TH "RBELF\-SIZE" "1" "October 2008" "ruby-elf" "Reference"
+.\" -----------------------------------------------------------------
+.\" * Define some portability stuff
+.\" -----------------------------------------------------------------
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.\" http://bugs.debian.org/507673
+.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\" -----------------------------------------------------------------
+.\" * set default formatting
+.\" -----------------------------------------------------------------
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.\" -----------------------------------------------------------------
+.\" * MAIN CONTENT STARTS HERE *
+.\" -----------------------------------------------------------------
+.SH "NAME"
+rbelf-size \- List section sizes of ELF files
+.SH "SYNOPSIS"
+.HP \w'\fBrbelf\-size\fR\ 'u
+\fBrbelf\-size\fR [\fB\-\-relocation\-stats\fR\ [\fB\-\-decibel\fR]] [\fB\-\-quiet\fR] [\fB\-\-recursive\fR] [\fB@\fR\fIfile\fR | \fIfile\fR...]
+.SH "DESCRIPTION"
+.PP
+
+\fBrbelf\-size\fR
+is a replacement for the standard
+\fBsize\fR(1)
+utility, as provided by GNU binutils and similar suites\&. Instead of showing the sum of all the invariant, variant and unallocated sections as the size, it divides them depending on how they are treated, differentiating between invariant data, invariant code, variant data and relocated invariant data\&.
+.SH "OPTIONS"
+.PP
+\fB\-r\fR, \fB\-\-relocation\-stats\fR
+.RS 4
+Instead of reporting size data compatible with
+\fBsize\fR(1)
+report size for shared, private and relocated areas\&. This is helpful to assess the validity of shared object approaches\&.
+.RE
+.PP
+\fB\-d\fR, \fB\-\-decibel\fR
+.RS 4
+When using the
+\fB\-\-relocation\-stats\fR
+option, a ratio is displayed between the size of relocated and shared code areas, to better assess the advantages and disadvantages for shared object approaches\&.
+.sp
+Since that ratio can easily skyrocket into thousands if there is very little relocated data, and a lot of shared data, it might be easier to appreciate the results by using a logaritmic scale\&.
+.RE
+.PP
+\fB\-q\fR, \fB\-\-quiet\fR
+.RS 4
+Do not output warnings and errors to the standard error\&. Designed to increase the signal\-to\-noise ratio when analysing eterogeneous trees recursively, or when producing output to redirect to automated systems\&.
+.RE
+.PP
+\fB\-R\fR, \fB\-\-recursive\fR
+.RS 4
+Recursively descend into directories to search for files to scan\&. This affects both the paths passed from the command line and those found in argument files\&.
+.RE
+.PP
+\fB@\fR\fIpath\fR
+.RS 4
+Read the list of files to analyse from the given file (or standard input if
+\fIpath\fR
+is
+\-)\&. Useful to pass a long list of files\&. When used with stdin or named pipes, this also allows asynchronous analysis\&.
+.RE
+.SH "COMPATIBLE OUTPUT"
+.PP
+The output of
+\fBrbelf\-size\fR
+differs from that of
+\fBsize\fR
+for the number and type of columns it outputs\&. While the original BSD command outputs the size of the "text", "data" and "bss" sections, this tool splits them further\&.
+.PP
+exec
+.RS 4
+Counts in all the sections containing executable code, this includes the
+\fI\&.text\fR
+section, and others\&.
+.RE
+.PP
+data
+.RS 4
+Counts in all the sections containing variable data, this excludes read\-only data sections, but includes relocated data and other kind of allocated and writeable data sections\&. If the compiler is GCC or outputs GCC\-compatible section names this won\*(Aqt count in relocated constants\&.
+.RE
+.PP
+relro
+.RS 4
+Counts in the relocated constants (read\-only relocated data)\&. This column will be non\-null only for binaries compiled by GCC or by compilers emitting GCC\-compatible section names\&. The sections counted in this entry will are relocated at runtime, but are never otherwise modified\&. The reason why this is separated is that this section may be touched by
+\fBprelink\fR(8)
+so that the runtime relocation is not needed, and thus would count just as common constant data\&.
+.RE
+.PP
+bss
+.RS 4
+Just like
+\fBsize\fR
+bss column, this counts in the size of sections that are allocated at runtime as mapped to the zero page\&. It supports TLS
+\fI\&.tbss\fR
+section\&.
+.RE
+.PP
+total
+.RS 4
+Counts in the sum of all the previous sections\&.
+.RE
+.SH "RELOCATION STATISTICS"
+.PP
+When using shared objects rather than static linking, there are many trade\-offs to be made\&. One of these relates to the amount of code that will get relocated (and thus becomes private, per\-process resident memory)\&.
+.PP
+The
+\fB\-\-relocation\-stats\fR
+option was devised as a mean to assess the cost/benefit of using shared objects, rather than using static link (e\&.g\&. with multicall binaries)\&.
+.PP
+shared
+.RS 4
+Areas of memory that are always shared among processes; these include executable areas with Position Indipendent Code, and read\-only data areas\&.
+.sp
+Generally, this is what we would want to have as big as possible, compared to the rest\&.
+.RE
+.PP
+private
+.RS 4
+Areas of memory that will always be private to the process; these includes writeable data areas and areas remapped to the zero page (what above is called bss)\&.
+.sp
+This is a worst\-case value, as even though the writeable sections _may_ become private, if they are left untouched they will be shared among multiple (if not all) processes\&. It is, though, useful to consider the worst\-case scenario for assesment\&.
+.RE
+.PP
+relocated
+.RS 4
+This value sums up the size of the memory areas that will be relocated when using shared objects (or Position Indipendent Executables)\&. Relocated areas include \&.data\&.rel\&.ro sections, which contain data read\-only for the code, but written to by the dynamic linker\&.
+.sp
+Again this value is an approximation nearing the worst\-case scenario\&.
+.RE
+.PP
+ratio
+.RS 4
+The ratio between shared and relocated code in the current executable or shared object\&. Using this value you can have a quick idea of the cost/benefit of using shared objects for a particular task\&.
+.sp
+When using
+\fB\-\-decibel\fR
+the value will be represented in deciBels, which should make it even easier to understand: a negative value shows a overly high cost, while a value between 1 and 10 will indicate some work might be needed to improve the benefits\&.
+.RE
+.SH "BUGS AND MISSING FEATURES"
+.PP
+The name
+\fItotal\fR
+for the sum of the colums is misleading since it\*(Aqs actually not the total size of the file, nor the total size of the allocated entries\&.
+.PP
+Right now, all the sections are counted in if their flags match, it might be better to limit to allocated sections all over the place\&.
+.PP
+The size of the columns is fixed to 8 digits, it might not be enough to fill in enough space for some big ELF files\&.
+.PP
+Parsing of files to provide further arguments (\fB@\fR\fIfile\fR) is not entirely comforming to other tools handling of the same syntax\&. No options are parsed from the file, and filenames are expected to be separated by newlines rather than whitespace\&.
+.PP
+Symbolic links are only followed when they are passed directly to the command line, or through @\-lists; symbolic links are
+\fInot\fR
+followed when using the
+\fB\-\-recursive\fR
+option, to avoid loops\&.
+.SH "SEE ALSO"
+.PP
+
+\m[blue]\fBFlameeyes\*(Aqs Weblog\fR\m[]
+http://blog\&.flameeyes\&.eu/
+.PP
+Related tools:
+\fBcowstats\fR(1),
+\fBsize\fR(1),
+\fBprelink\fR(8)\&.
+.SH "AUTHOR"
+.PP
+\fBDiego E. Pettenò\fR <\&flameeyes@gmail.com\&>
+.RS 4
+Author and main contributor.
+.RE

data/manpages/verify-lfs.1

@@ -0,0 +1,95 @@
+'\" t
+.\"     Title: verify-lfs
+.\"    Author: 
+.\" Generator: DocBook XSL-NS Stylesheets v1.76.0 <http://docbook.sf.net/>
+.\"      Date: December 2010
+.\"    Manual: Reference
+.\"    Source: ruby-elf
+.\"  Language: English
+.\"
+.TH "VERIFY\-LFS" "1" "December 2010" "ruby-elf" "Reference"
+.\" -----------------------------------------------------------------
+.\" * Define some portability stuff
+.\" -----------------------------------------------------------------
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.\" http://bugs.debian.org/507673
+.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\" -----------------------------------------------------------------
+.\" * set default formatting
+.\" -----------------------------------------------------------------
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.\" -----------------------------------------------------------------
+.\" * MAIN CONTENT STARTS HERE *
+.\" -----------------------------------------------------------------
+.SH "NAME"
+verify-lfs \- ELF analyzer to identify software not using solely LFS interfaces
+.SH "SYNOPSIS"
+.HP \w'\fBverify\-lfs\fR\ 'u
+\fBverify\-lfs\fR [\fB\-\-objects\fR] [\fB\-\-quiet\fR] [\fB\-\-recursive\fR] [\fB@\fR\fIfile\fR | \fIfile\fR...]
+.SH "DESCRIPTION"
+.PP
+
+\fBverify\-lfs\fR
+is a script that analyses the symbols required by ELF executables and libraries, listing the objects that rely entirely or partially on the pre\-largefile interface functions of glibc\&.
+.SH "OPTIONS"
+.PP
+\fB\-o\fR, \fB\-\-objects\fR
+.RS 4
+Scan for relocatable object files (ET_REL) rather than executables or dynamic libraries\&. This mode is designed to help identify which object might be miscompiled to not use LFS functions as it was instead intended\&.
+.RE
+.PP
+\fB\-q\fR, \fB\-\-quiet\fR
+.RS 4
+Do not output warnings and errors to the standard error\&. Designed to increase the signal\-to\-noise ratio when analysing eterogeneous trees recursively, or when producing output to redirect to automated systems\&.
+.RE
+.PP
+\fB\-R\fR, \fB\-\-recursive\fR
+.RS 4
+Recursively descend into directories to search for files to scan\&. This affects both the paths passed from the command line and those found in argument files\&.
+.RE
+.PP
+\fB@\fR\fIpath\fR
+.RS 4
+Read the list of files to analyse from the given file (or standard input if
+\fIpath\fR
+is
+\-)\&. Useful to pass a long list of files\&. When used with stdin or named pipes, this also allows asynchronous analysis\&.
+.RE
+.SH "BUGS AND MISSING FEATURES"
+.PP
+
+\fBverify\-lfs\fR
+uses a manually\-tweaked regular expression to identify which interface is being used; this expressions might be incomplete or lead to false positive, please double\-check the results, and report back if you have hit false positives, or false negatives\&.
+.PP
+Parsing of files to provide further arguments (\fB@\fR\fIfile\fR) is not entirely comforming to other tools handling of the same syntax\&. No options are parsed from the file, and filenames are expected to be separated by newlines rather than whitespace\&.
+.PP
+Symbolic links are only followed when they are passed directly to the command line, or through @\-lists; symbolic links are
+\fInot\fR
+followed when using the
+\fB\-\-recursive\fR
+option, to avoid loops\&.
+.SH "CREDITS"
+.PP
+The original idea for this script comes from the
+summarise\-stat64
+Perl script written by Greg Banks of SGI\&. A huge thanks to Greg for the idea and the script\&.
+.SH "SEE ALSO"
+.PP
+
+\m[blue]\fBFlameeyes\*(Aqs Weblog\fR\m[]
+http://blog\&.flameeyes\&.eu/
+.PP
+Related tools:
+\fBnm\fR(1)\&.
+.SH "AUTHOR"
+.PP
+\fBDiego E. Pettenò\fR <\&flameeyes@gmail.com\&>
+.RS 4
+Author and main contributor.
+.RE