This is Info file pm.info, produced by Makeinfo version 1.68 from the input file bigpm.texi.  File: pm.info, Node: B/JVM/Jasmin/CompileState, Next: B/JVM/Jasmin/Emit, Prev: B/JVM/Jasmin, Up: Module List Internal package used by B::JVM::Jasmin to keep state of compilation ******************************************************************** NAME ==== B::JVM::Jasmin::CompileState - Internal package used by B::JVM::Jasmin to keep state of compilation SYNOPSIS ======== use B::JVM::Jasmin::CompileState; my $state = new B::JVM::Jasmin::CompileState([HASHREF]); DESCRIPTION =========== This class is used to store the internal state of the compiler as it runs. Certain global information must be accounted for, and instead of making a bunch of global variables, I thought it would be better to keep track of this via a sub-package. AUTHOR ====== Bradley M. Kuhn, bkuhn@ebb.org, http://www.ebb.org/bkuhn COPYRIGHT ========= Copyright (C) 1999, Bradley M. Kuhn, All Rights Reserved. LICENSE ======= You may distribute under the terms of either the GNU General Public License or the Artistic License, as specified in the LICENSE file that was shipped with this distribution. SEE ALSO ======== perl(1), jasmin(1), B::JVM::Jasmin(3). DETAILED DOCUMENTATION ====================== B::JVM::Jasmin::CompileState Package Variables ---------------------------------------------- $VERSION Version number of B::JVM::Jasmin::CompileState. It should always match the version of B::JVM::Jasmin @ISA Canonical @ISA array, derives from nothing Modules used by B::JVM::Jasmin::CompileState -------------------------------------------- Carp Used for error reporting File::Spec::Functions Used to do some operations on files IO::File used for creating lexically scoped file handles B::JVM::Jasmin::Emit Needed for creating emitter objects for output Methods in B::JVM::Jasmin::CompileState --------------------------------------- B::JVM::Jasmin::CompileState::new usage: B::JVM::Jasmin::CompileState::new(HASHREF) Creates a new object of the class. First, it checks for the validity of the keys of the given initialization package (valid keys are kept in @validUserParameters), and if everything checks out, it sets up a few defaults if none were given and returns the blessed object. Accepted User Parameters: mainClassName The name to be used for the Java class that will correspond to the "main::" package. Defaults to "Main" if none is given. currentPackage This is the current package being compiled. Should be updated by the user using the setCurrentPackage method. There is really no need to initialize it until compilation starts. Consequently, the value defaults to undef. outputDirectory A directory to use for creation of output files. Defaults to the current working directory. keepIntermediateFiles If true, intermediate files that are generated during the compilation process are kept for user inspection. B::JVM::Jasmin::CompileState::createNewFile usage: $obj->createNewFile($packageName, [$className]) Creates a new file entry in the compiler state object and opens a new file handle for use when writing out jasmin files. If the file has already been created, nothing is done. This is typically called whenever a new package is discovered, so that a seperate class file can be generated for that package (class) in True Java Style (TM) :) B::JVM::Jasmin::CompileState::emit usage: $obj->emit([PACAKGE_NAME]) returns the emitter object associated with the given package, PACAKGE_NAME. If PACKAGE_NAME is missing, then the emitter object of the currentPackage is returned B::JVM::Jasmin::CompileState::setCurrentMethod usage: $obj->setCurrentMethod($methodName) Set the current method to be $methodName B::JVM::Jasmin::CompileState::setCurrentPackage usage: $obj->setCurrentPackage($packageName) Set the current package to be $packageName B::JVM::Jasmin::CompileState::clearCurrentMethod usage: $obj->clearCurrentMethod() Clear the current method name stored B::JVM::Jasmin::CompileState::getCurrentMethod usage: $obj->getCurrentMethod() Return the current method B::JVM::Jasmin::CompileState::DESTORY usage: $obj->DESTROY() Default destructor for the object  File: pm.info, Node: B/JVM/Jasmin/Emit, Next: B/JVM/Utils, Prev: B/JVM/Jasmin/CompileState, Up: Module List Package used by B::JVM::Jasmin to emit Jasmin syntaxed file *********************************************************************************** NAME ==== B::JVM::Jasmin::Emit - Package used by B::JVM::Jasmin to emit Jasmin syntaxed file SYNOPSIS ======== use B::JVM::Jasmin::Emit; my $emitter = new B::JVM::Emit(FILEHANDLE); # ... $emitter->DIRECTIVE_NAME([@ARGS]); # ... $emitter->OPCODE_NAME([@ARGS]); # ... $emitter->OPCODE_NAME([@ARGS]); DESCRIPTION =========== This class is used emit JVM assembler code in Jasmin syntax. Each method one can use is either an opcode or a directive supported by Jasmin syntax. AUTHOR ====== Bradley M. Kuhn, bkuhn@ebb.org, http://www.ebb.org/bkuhn COPYRIGHT ========= Copyright (C) 1999, Bradley M. Kuhn, All Rights Reserved. LICENSE ======= You may distribute under the terms of either the GNU General Public License or the Artistic License, as specified in the LICENSE file that was shipped with this distribution. SEE ALSO ======== perl(1), B::JVM::Jasmin(3), B::JVM::Emit(3). DETAILED DOCUMENTATION ====================== B::JVM::Jasmin::Emit Package Variables -------------------------------------- $VERSION Version number of B::JVM::Jasmin::Emit. For now, it should always match the version of B::JVM::Jasmin @EXPORT_OK All the methods that one can grab from B::JVM::Jasmin::Emit @EXPORT We don't export anything by default. Modules used by B::JVM::Jasmin::Emit ------------------------------------ Carp Used for error reporting B::JVM::Utils Used to get needed utility functions, such as ExtractMethodData and IsValidMethodString Methods in B::JVM::Jasmin::Emit ------------------------------- B::JVM::Jasmin::Emit::new usage: B::JVM::Emit::new(FILEHANDLE, [SOURCE_FILE_NAME]) Creates a new object of the class. It assumes that FILEHANDLE is a lexically scoped file handle open for writing, and that SOURCE_FILE_NAME that should be used for a source directive. SOURCE_FILE_NAME is optional, but may annoys someone firing up your code in the Java debugger. B::JVM::Emit::Jasmin::_clearMethodData() usage: $jasminEmitter->_clearMethodData() Clear out the method data elements of the Jasmin emitter B::JVM::Emit::Jasmin::source usage: B::JVM::Emit::Jasmin::source(SOURCE_FILE_NAME) Emits the source file name directive. B::JVM::Emit::Jasmin::comment usage: `B::JVM::Emit::Jasmin::comment($methodName, $commentString)' Puts `$commentString' in a comment in the file, in the code for method `$metohdName'. B::JVM::Emit::Jasmin::super usage: B::JVM::Emit::Jasmin::super(CLASS_NAME) sends class directive, using CLASS_NAME, to the output file B::JVM::Emit::Jasmin::class usage: B::JVM::Emit::Jasmin::class(ACCESS_SPEC, CLASS_NAME) sends class directive, using CLASS_NAME to the ACCESS_SPEC, to the output file B::JVM::Emit::Jasmin::interface usage: B::JVM::Emit::Jasmin::interface(ACCESS_SPEC, INTERFACE_NAME) sends interface directive, using INTERFACE_NAME to the ACCESS_SPEC, to the output file B::JVM::Emit::Jasmin::implements usage: B::JVM::Emit::Jasmin::implements(CLASS_NAME) sends implements directive, using CLASS_NAME to the output file B::JVM::Emit::Jasmin::labelCreate usage: `$emitter-'labelCreate($methodName, $labelNameRequested)> In method, $methodName, creates a new label, whose name will "resemble" $labelNameRequested. This label is not actually sent to the output, that must be done later with `$emitter-'labelSend($methodName, $value)>. Note that the value returned from this method is the actual label name assigned and will only "resemble" (i.e., not match exactly) the `$labelNameRequested'. B::JVM::Emit::Jasmin::labelSend usage: `$emitter-'labelSend($methodName, $labelName)> Send a label, `$labelName', to the output of method, `$methodName'. This label must be valid label previously returned from `$emitter-'labelCreate($methodName, $someValue)>. B::JVM::Emit::Jasmin::field usage: B::JVM::Emit::Jasmin::field(ACCESS_SPEC, FIELD_NAME, TYPE, [VALUE]) sends field directive, using the arguments given, to the output file B::JVM::Emit::Jasmin::methodStart usage: $emitter->methodStart(METHOD_NAME, ACCESS_SPEC, [STACK_SIZE]) sends method directive and other directives needed to start up a new method. Also sets the current method for the emitter. STACK_SIZE is optional. However, a stack size is always set to a default value (currently 256), because if it is not set, a number of problems occur with the stack. B::JVM::Emit::Jasmin::methodCreateLocal usage: $emitter->methodCreateLocal(METHOD_NAME, VARIABLE_NAME_REQUEST, VARIABLE_TYPE, [LABEL1], [LABEL2]) Creates a local of type VARIABLE_TYPE, with a given name in method, METHOD_NAME. If LABEL1 is given, LABEL2 must be given, and vice versa. If the labels are given, then the variable is only valid between those two labels in the resulting assembler source. methodCreateLocal attempts to give a variable name that "resembles" VARIABLE_NAME_REQUEST. If the labels are given, it is guaranteed that the variable name will "resemble" the VARIABLE_NAME_REQUEST. If the labels are not given, it is very likely that an old local variable of the same type will be returned. The actual variable name given will be returned. It is imperative that the user of methodCreateLocal use this variable name, and not VARIABLE_NAME_REQUEST, for obvious reasons. B::JVM::Emit::Jasmin::methodFreeLocal usage: $emitter->methodFreeLocal(METHOD_NAME VARIABLE_NAME) Indicates that the local, VARIABLE_NAME, in method, METHOD_NAME, is no longer in use. It is not required that locals be freed in this manner, however, many, many locals can be allocated unnecessarily if this is not done. B::JVM::Emit::Jasmin::methodEnd usage: `$emitter-'methodEnd($method, [$debug])> Finishes up a method, `$method', that is currently being emitted. If $debug is defined and is true, then ".line" directives will be put into the output for debugging purposes. B::JVM::Emit::Jasmin::astore usage: $emitter->astore([METHOD, VARIABLE]) Emits an "astore" instruction, using the VARIABLE name in METHOD given, if one is given. If VARIABLE is given, it is looked up in variables created with B::JVM::Emit::Jasmin::methodCreateLocal() for the given method, METHOD. B::JVM::Emit::Jasmin::invokevirtual usage: $emitter->invokevirtual(METHOD_IN, METHOD_INVOKED) Emits an "invokevirtual" instruction to invoke METHOD_INVOKED in the code for METHOD_IN B::JVM::Emit::Jasmin::ifne usage: `$emitter-'ifne($methodName, $labelName)> Emits an "ifne" instruction with argument, `$labelName' in the code for method, `$methodName'. This label, `$labelName' must be valid label previously returned from `$emitter-'labelCreate($methodName, $someValue)>. B::JVM::Emit::Jasmin::ifeq usage: `$emitter-'ifeq($methodName, $labelName)> Emits an "ifeq" instruction with argument, `$labelName' in the code for method, `$methodName'. This label, `$labelName' must be valid label previously returned from `$emitter-'labelCreate($methodName, $someValue)>. B::JVM::Emit::Jasmin::aload usage: $emitter->aload([METHOD, VARIABLE]) Emits an "aload" instruction, using the VARIABLE name in METHOD given, if one is given. If VARIABLE is given, it is looked up in variables created with B::JVM::Emit::Jasmin::methodCreateLocal() for the given method, METHOD. B::JVM::Emit::Jasmin::invokestatic usage: $emitter->invokevirtual(METHOD_IN, METHOD_INVOKED) Emits an "invokestatic" instruction to invoke METHOD_INVOKED in the code for METHOD_IN B::JVM::Emit::Jasmin::iconst usage: $emitter->iconst(METHOD, VALUE) Emits an "iconst" instruction, using the value of VALUE for the constant, in the method named METHOD. B::JVM::Emit::Jasmin::istore usage: $emitter->istore([METHOD, VARIABLE]) Emits an "istore" instruction, using the VARIABLE name in METHOD given, if one is given. If VARIABLE is given, it is looked up in variables created with B::JVM::Emit::Jasmin::methodCreateLocal() for the given method, METHOD. B::JVM::Emit::Jasmin::iload usage: $emitter->iload([METHOD, VARIABLE]) Emits an "iload" instruction, using the VARIABLE name in METHOD given, if one is given. If VARIABLE is given, it is looked up in variables created with B::JVM::Emit::Jasmin::methodCreateLocal() for the given method, METHOD. B::JVM::Emit::Jasmin::iand usage: $emitter->iand([METHOD]) Emits an "iand" instruction, in METHOD given, if one is given. B::JVM::Emit::Jasmin::pop usage: $emitter->pop([METHOD]) Emits an "pop" instruction, in METHOD given, if one is given. B::JVM::Emit::Jasmin::getstatic usage: $emitter->getstatic(METHOD_IN, FIELD, TYPE) Emits an "getstatic" instruction for the field, FIELD, of type, TYPE in the code for METHOD_IN B::JVM::Emit::Jasmin::ldc usage: $emitter->ldc(METHOD_IN, VALUE) Emits an "ldc" instruction with the value of VALUE, in the method METHOD_IN. B::JVM::Emit::Jasmin::newObject usage: $emitter->newObject(METHOD_IN, CLASS) Emits an "new" instruction for the class, CLASS in the body for the method, METHOD_IN. CLASS must be a valid class name. B::JVM::Emit::Jasmin::invokespecial usage: $emitter->invokespecial(METHOD_IN, METHOD_INVOKED) Emits an "invokespecial" instruction to invoke METHOD_INVOKED in the code for METHOD_IN B::JVM::Emit::Jasmin::dup usage: `$emitter-'dup($method)> Emits an "dup" instruction in the code for the method, `$method' B::JVM::Emit::Jasmin::swap usage: `$emitter-'swap($method)> Emits an "swap" instruction in the code for the method, `$method' B::JVM::Emit::Jasmin::gotoLabel usage: `$emitter-'gotoLabel($methodName, $labelName)> Emits an "goto" instruction with argument, `$labelName' in the code for method, `$methodName'. This label, `$labelName' must be valid label previously returned from `$emitter-'labelCreate($methodName, $someValue)>. B::JVM::Emit::Jasmin::returnVoid usage: $emitter->returnVoid(METHOD_IN) Emits an "return" instruction in the code for method, METHOD_IN. B::JVM::Emit::Jasmin::iinc usage: `$emitter-'iinc($method, $variable, $amount)> Emits an "iinc" instruction, using the `$variable' name in the method, `$method'. The variable, `$variable' must have one previously returned from `methodCreateLocal($method, ...)' that has not been freed with `methodFreeLocal($method, ...)' yet. `$amount' is the integer amount to increment `$variable' by. B::JVM::Emit::Jasmin::bipush usage: `$emitter-'bipush($method, $value)> Emits an "bipush" instruction, into the method, `$method' using the value of $value. Note that an "iconst" or an "iconst_m1" instruction is emitted if the $value is the range where "iconst" will work. B::JVM::Emit::Jasmin::aastore usage: `$emitter-'aastore($method)> Emits an "aastore" instruction, into the method, `$method'. B::JVM::Emit::Jasmin::isub usage: `$emitter-'isub($method)> Emits an "isub" instruction, into the method, `$method'. B::JVM::Emit::Jasmin::nop usage: `$emitter-'nop($method)> Emits a "nop" instruction, into the method, `$method'. B::JVM::Emit::Jasmin::aaload usage: `$emitter-'aaload($method)> Emits an "aaload" instruction, into the method, `$method'. B::JVM::Emit::Jasmin::anewarray usage: `$emitter-'anewarray($method, $type)> Emits an "anewarray" instruction, into the method, `$method'. The new array will be of type $type. The method will fail if $type is not a valid JVM type identifier.  File: pm.info, Node: B/JVM/Utils, Next: B/LexInfo, Prev: B/JVM/Jasmin/Emit, Up: Module List Utility functions for B::JVM **************************** NAME ==== B::JVM::Utils - Utility functions for B::JVM SYNOPSIS ======== use B::JVM::Utils qw(method1 method2); DESCRIPTION =========== This package is a set of utilties that are useful when compiling Perl to the JVM architecture. They are a hodgepodge of utilties that don't really fit anywhere else. AUTHOR ====== Bradley M. Kuhn, bkuhn@ebb.org, http://www.ebb.org/bkuhn COPYRIGHT ========= Copyright (C) 1999, Bradley M. Kuhn, All Rights Reserved. LICENSE ======= You may distribute under the terms of either the GNU General Public License or the Artistic License, as specified in the LICENSE file that was shipped with this distribution. SEE ALSO ======== perl(1), B::JVM::Jasmin(3), B::JVM::Emit(3). DETAILED DOCUMENTATION ====================== B::JVM::Jasmin::Utils Package Variables --------------------------------------- $VERSION Version number of B::JVM::Utils. For now, it should always match the version of B::JVM::Jasmin @EXPORT_OK All the methods that one can grab from B::JVM::Utils. @EXPORT We don't export anything by default. Modules used by B::JVM::Utils ----------------------------- Carp Used for error reporting Methods in B::JVM::Utils ------------------------ B::JVM::ExtractMethodData usage: B::JVM::ExtractMethodData(METHOD_STRING) Takes a string that is believed to a valid method string for a JVM method, and if it is a valid method string, returns a hash reference that looks like: { methodName => NAME_OF_THE_METHOD, returnType => TYPE_ID_OF_RETURN_TYPE, argumentTypes => [ ARGUMENT_1_RETURN_TYPE_ID, ARGUMENT_1_RETURN_TYPE_ID, ... ] } An undefined value is returned if the method string is not valid. B::JVM::Utils::IsValidMethodString usage: B::JVM::Utils::IsValidMethodString(METHOD_STRING) Takes a string that is believed to a valid method name for a JVM method, and returns a true iff. the METHOD_STRING is a valid JVM method name B::JVM::Utils usage: B::JVM::Utils:IsValidTypeIdentifier(TYPE_ID) Takes a string that is believed to a valid type identifitier name on the JVM, and returns a true iff. the TYPE_ID is a valid JVM type identifier  File: pm.info, Node: B/LexInfo, Next: B/Lint, Prev: B/JVM/Utils, Up: Module List Show information about subroutine lexical variables *************************************************** NAME ==== B::LexInfo - Show information about subroutine lexical variables SYNOPSIS ======== use B::ShowLex (); my $lexi = B::ShowLex->new; DESCRIPTION =========== Perl stores lexical variable names and values inside a *padlist* within the subroutine. Certain lexicals will maintain certain attributes after the the variable "goes out of scope". For example, when a scalar is assigned a string value, this value remains after the variable has gone out of scope, but is overridden the next time it is assigned to. Lexical Arrays and Hashes will retain their storage space for the maximum number of entries stored at any given point in time. This module provides methods to record this information, which can be dumped out as-is or to compare two "snapshots". The information learned from these snapshots can be valuable in a number of ways. METHODS ======= new Create a new *B::LexInfo* object: my $lexi = B::LexInfo->new; cvlexinfo Create a padlist snapshot from a single subroutine: my $info = $lexi->cvlexinfo('Foo::bar'); stash_cvlexinfo Create a list of padlist snapshots for each subroutine in the given package: my $info = $lexi->stash_cvlexinfo('Foo'); dumper Return a reference to a stringified padlist snapshot: print ${ $lexi->dumper($info) } diff Compare two padlist snapshots and return the difference: my $before = $lexi->stash_cvlexinfo(__PACKAGE__); ... let some code run my $after = $lexi->stash_cvlexinfo(__PACKAGE__); my $diff = B::LexInfo->diff($before, $after); print $$diff; NOTE: This function relies on the *diff -u* command. You might need to configure *$B::LexInfo::TmpDir* and/or *$B::LexInfo::DiffCmd* to values other than the defaults in *LexInfo.pm*. cvrundiff Take a padlist snapshot of a subroutine, run the subroutine with the given arguments, take another snapshot and return a diff of the snapshots. my $diff = $lexi->cvrundiff('Foo::bar', "arg1", $arg2); print $$diff; Complete example: package Foo; use B::LexInfo (); sub bar { my($string) = @_; } my $lexi = B::LexInfo->new; my $diff = $lexi->cvrundiff('Foo::bar', "a string"); print $$diff; Produces: --- /tmp/B_LexInfo_1848.before Mon Jun 28 19:48:41 1999 +++ /tmp/B_LexInfo_1848.after Mon Jun 28 19:48:41 1999 @@ -2,8 +2,10 @@ { 'Foo::bar' => { '$string' => { - 'TYPE' => 'NULL', - 'NULL' => '0x80efd58' + 'TYPE' => 'PV', + 'LEN' => 9, + 'PV' => 'a string', + 'CUR' => 8 }, '__SPECIAL__1' => { 'TYPE' => 'NULL', SNAPSHOT INFO ============= Snapshots are built using Perl structures and stringified using Data::Dumper. Hash key order is sorted and preserved if you you the Tie::IxHash module installed. Entry names are that of the variable itself or *__SPECIAL__$n* for entries that are used by Perl internally. The key/value pairs for each entry depends on the variable type and state. Docs on that to come, in the meantime, study: http://gisle.aas.no/perl/illguts/ SEE ALSO ======== B(3), Apache::RegistryLexInfo(3), Devel::Peek(3) AUTHOR ====== Doug MacEachern  File: pm.info, Node: B/Lint, Next: B/Showlex, Prev: B/LexInfo, Up: Module List Perl lint ********* NAME ==== B::Lint - Perl lint SYNOPSIS ======== perl -MO=Lint[,OPTIONS] foo.pl DESCRIPTION =========== The B::Lint module is equivalent to an extended version of the -w option of *perl*. It is named after the program *lint* which carries out a similar process for C programs. OPTIONS AND LINT CHECKS ======================= Option words are separated by commas (not whitespace) and follow the usual conventions of compiler backend options. Following any options (indicated by a leading -) come lint check arguments. Each such argument (apart from the special all and none options) is a word representing one possible lint check (turning on that check) or is *no-foo* (turning off that check). Before processing the check arguments, a standard list of checks is turned on. Later options override earlier ones. Available options are: context Produces a warning whenever an array is used in an implicit scalar context. For example, both of the lines $foo = length(@bar); $foo = @bar; will elicit a warning. Using an explicit B silences the warning. For example, $foo = scalar(@bar); *implicit-read* and *implicit-write* These options produce a warning whenever an operation implicitly reads or (respectively) writes to one of Perl's special variables. For example, *implicit-read* will warn about these: /foo/; and *implicit-write* will warn about these: s/foo/bar/; Both *implicit-read* and *implicit-write* warn about this: for (@a) { ... } *dollar-underscore* This option warns whenever $_ is used either explicitly anywhere or as the implicit argument of a print statement. *private-names* This option warns on each use of any variable, subroutine or method name that lives in a non-current package but begins with an underscore ("_"). Warnings aren't issued for the special case of the single character name "_" by itself (e.g. $_ and @_). *undefined-subs* This option warns whenever an undefined subroutine is invoked. This option will only catch explicitly invoked subroutines such as `foo()' and not indirect invocations such as `&$subref()' or `$obj->meth()'. Note that some programs or modules delay definition of subs until runtime by means of the AUTOLOAD mechanism. *regexp-variables* This option warns whenever one of the regexp variables $', $& or $' is used. Any occurrence of any of these variables in your program can slow your whole program down. See *Note Perlre: (perl.info)perlre, for details. all Turn all warnings on. none Turn all warnings off. NON LINT-CHECK OPTIONS ====================== *-u Package* Normally, Lint only checks the main code of the program together with all subs defined in package main. The -u option lets you include other package names whose subs are then checked by Lint. BUGS ==== This is only a very preliminary version. AUTHOR ====== Malcolm Beattie, mbeattie@sable.ox.ac.uk.  File: pm.info, Node: B/Showlex, Next: B/Size, Prev: B/Lint, Up: Module List Show lexical variables used in functions or files ************************************************* NAME ==== B::Showlex - Show lexical variables used in functions or files SYNOPSIS ======== perl -MO=Showlex[,SUBROUTINE] foo.pl DESCRIPTION =========== When a subroutine name is provided in OPTIONS, prints the lexical variables used in that subroutine. Otherwise, prints the file-scope lexicals in the file. AUTHOR ====== Malcolm Beattie, `mbeattie@sable.ox.ac.uk'  File: pm.info, Node: B/Size, Next: B/Stackobj, Prev: B/Showlex, Up: Module List Measure size of Perl OPs and SVs ******************************** NAME ==== B::Size - Measure size of Perl OPs and SVs SYNOPSIS ======== use B::Size (); DESCRIPTION =========== See B::TerseSize SEE ALSO ======== B::TerseSize(3), Apache::Status(3) AUTHOR ====== Doug MacEachern  File: pm.info, Node: B/Stackobj, Next: B/Terse, Prev: B/Size, Up: Module List Helper module for CC backend **************************** NAME ==== B::Stackobj - Helper module for CC backend SYNOPSIS ======== use B::Stackobj; DESCRIPTION =========== See `ext/B/README'. AUTHOR ====== Malcolm Beattie, `mbeattie@sable.ox.ac.uk'  File: pm.info, Node: B/Terse, Next: B/TerseSize, Prev: B/Stackobj, Up: Module List Walk Perl syntax tree, printing terse info about ops **************************************************** NAME ==== B::Terse - Walk Perl syntax tree, printing terse info about ops SYNOPSIS ======== perl -MO=Terse[,OPTIONS] foo.pl DESCRIPTION =========== See `ext/B/README'. AUTHOR ====== Malcolm Beattie, `mbeattie@sable.ox.ac.uk'  File: pm.info, Node: B/TerseSize, Next: B/Tree, Prev: B/Terse, Up: Module List Printing info about ops and their (estimated) size ************************************************** NAME ==== B::TerseSize - Printing info about ops and their (estimated) size SYNOPSIS ======== perl -MO=TerseSize[,OPTIONS] foo.pl DESCRIPTION =========== The *B::Size* and *B::TerseSize* modules attempt to measure the size of Perl op codes. The output of *B::TerseSize* is similar to that of B::Terse, but includes the size of each OP in the tree and the PADLIST (subroutine lexical variables). The module can be run just as other compiler backends or used via *Apache::Status* (version 2.02 and higher). If the *Apache::Status* StatusTerseSize option is enabled, there will be a main menu item added, "Memory Usage". Clicking on this link will cause *B::TerseSize* to produce a summary of package memory usage. This summary can take quite a while to produce, as each package subroutine syntax tree will be walked, adding up the information. This information will be cached, so running httpd in -X (non-forking mode) is a good choice. When browsing the Apache::Status "Symbol Table Dump", a "Memory Usage" link will be at the bottom of each page. These summaries also include measurements of package global variables. The Apache::Status symbol table browser will also provide an option to dump a subroutine tree along with the other subroutine options. CAVEATS ======= The memory measurements are only an estimate. But, chances are, if a measurement is not accurate, it is smaller than the actual size. The "execution order" option under Apache::Status can only be run once unless you are using Perl 5.6.0+ or apply the *patches/b_clearsym_60.pat* to older Perls. SEE ALSO ======== B(3), B::Size(3), B::LexInfo(3), Apache::Status(3) AUTHOR ====== Doug MacEachern based in part on B::Terse by Malcolm Beattie  File: pm.info, Node: B/Tree, Next: B/Xref, Prev: B/TerseSize, Up: Module List Simplified version of B::Graph for demonstration ************************************************ NAME ==== B::Tree - Simplified version of B::Graph for demonstration SYNOPSIS ======== perl -MO=Tree program | dot -Tps > tree.ps DESCRIPTION =========== This is a very cut-down version of `B::Graph'; it generates minimalist tree graphs of the op tree of a Perl program, merely connecting the op nodes and labelling each node with the type of op. It was written as an example of how to write compiler modules for "Professional Perl", but I've found it extremely useful for creating simple op tree graphs for use in presentations on Perl internals. It requires the CPAN `GraphViz' module and the GraphViz package from `http://www.research.att.com/sw/tools/graphviz/'. It takes no options. AUTHOR ====== Simon Cozens, `simon@cpan.org' SEE ALSO ======== *Note GraphViz: GraphViz,, *Note B/Graph: B/Graph,  File: pm.info, Node: B/Xref, Next: BIND/Conf_Parser, Prev: B/Tree, Up: Module List Generates cross reference reports for Perl programs *************************************************** NAME ==== B::Xref - Generates cross reference reports for Perl programs SYNOPSIS ======== perl -MO=Xref[,OPTIONS] foo.pl DESCRIPTION =========== The B::Xref module is used to generate a cross reference listing of all definitions and uses of variables, subroutines and formats in a Perl program. It is implemented as a backend for the Perl compiler. The report generated is in the following format: File filename1 Subroutine subname1 Package package1 object1 C object2 C ... Package package2 ... Each File section reports on a single file. Each Subroutine section reports on a single subroutine apart from the special cases "(definitions)" and "(main)". These report, respectively, on subroutine definitions found by the initial symbol table walk and on the main part of the program or module external to all subroutines. The report is then grouped by the Package of each variable, subroutine or format with the special case "(lexicals)" meaning lexical variables. Each object name (implicitly qualified by its containing Package) includes its type character(s) at the beginning where possible. Lexical variables are easier to track and even included dereferencing information where possible. The `line numbers' are a comma separated list of line numbers (some preceded by code letters) where that object is used in some way. Simple uses aren't preceded by a code letter. Introductions (such as where a lexical is first defined with my) are indicated with the letter "i". Subroutine and method calls are indicated by the character "&". Subroutine definitions are indicated by "s" and format definitions by "f". OPTIONS ======= Option words are separated by commas (not whitespace) and follow the usual conventions of compiler backend options. `-oFILENAME' Directs output to FILENAME instead of standard output. -r Raw output. Instead of producing a human-readable report, outputs a line in machine-readable form for each definition/use of a variable/sub/format. `-D[tO]' (Internal) debug options, probably only useful if -r included. The t option prints the object on the top of the stack as it's being tracked. The O option prints each operator as it's being processed in the execution order of the program. BUGS ==== Non-lexical variables are quite difficult to track through a program. Sometimes the type of a non-lexical variable's use is impossible to determine. Introductions of non-lexical non-scalars don't seem to be reported properly. AUTHOR ====== Malcolm Beattie, mbeattie@sable.ox.ac.uk.  File: pm.info, Node: BIND/Conf_Parser, Next: BSD/Ipfwgen, Prev: B/Xref, Up: Module List Parser class for BIND configuration files ***************************************** NAME ==== BIND::Conf_Parser - Parser class for BIND configuration files SYNOPSIS ======== # Should really be a subclass use BIND::Conf_Parser; $p = BIND::Conf_Parser->new; $p->parse_file("/etc/named.conf"); $p->parse_fh(STDIN); $p->parse("server 10.0.0.1 { bogus yes; };"); # For one-shot parsing BIND::Conf_Parser->parse_file("/etc/named.conf") BIND::Conf_Parser->parse_fh(STDIN); BIND::Conf_Parser->parse("server 10.0.0.1 { bogus yes; };"); DESCRIPTION =========== `BIND::Conf_Parser' implements a virtual base class for parsing BIND (Berkeley Internet Name Domain) server version 8 configuration files ("named.conf"). The parsing methods shown in the synopsis perform syntactic analysis only. As each meaningful semantic 'chunk' is parsed, a callback method is invoked with the parsed information. The following methods are the public entry points for the base class: $p = BIND::Conf_Parser->new The object constructor takes no arguments. $p->parse_file( $filename ) The given filename is parsed in its entirety. $p->parse_fh( $fh [, $filename] ) The given filehandle is parsed in its entirety. An optional filename may be given for inclusion in any error messages that are generated during the parsing. If it is not included a default of "a file handle" will be used. $p->parse( $statements [, $filename] ); The given scalar is parsed in its entirety. Partial statements will be treated as a syntax error. An optional filename may be given for inclusion in any error messages that are generated during the parsing. If it is not included a default of "a scalar" will be used. For conveniance, the last three methods may also be called as class methods (that is, with the class name instead of a constructed object reference), in which case they will call new() method and use the resulting object. All three return the object used, whether passed in or constructed at call-time. In order to make the parser useful, you must make a subclass where you override one or more of the following methods as appropriate: $self->handle_logging_category( $name, \@names ) $self->handle_logging_channel( $name, \%options ) $self->handle_key( $name, $algo, $secret ) $self->handle_acl( $name, $addrmatchlist ) $self->handle_option( $option, $argument ) $self->handle_server( $name, \%options ) $self->handle_trusted_key( $domain, \@key_definition) $self->handle_empty_zone( $name, $class, \%options ) $self->handle_zone( $name, $class, $type, \%options ) $self->handle_control( $socket_type, \@type_specific_data ) The exact format of the data passed to the above routines is not currently documented outside of the source to the class, but should be found to be fairly natural. USAGE ===== A typical usage would run something like: # Define a subclass package Parser; use BIND::Conf_Parser; use vars qw(@ISA); @ISA = qw(BIND::Conf_Parser); # implement handle_* methods for config file statements that # we're interested in sub handle_option { my($self, $option, $argument) = @_; return unless $option eq "directory"; $named_dir = $argument; } sub handle_zone { my($self, $name, $class, $type, $options) = @_; return unless $type eq "master" && $class eq "in"; $files{$name} = $options->{file}; } # later, back at the ranch... package main; Parser->parse_file("/etc/named.conf"); WARNING: if the subclass is defined at the end of the main program source file, the assignment to *@ISA* may need to be wrapped in a BEGIN block, ala BEGIN { @ISA = qw(BIND::Conf_Parser); } BUGS ==== `BIND::Conf_Parser' does not perform all the syntactic checks performed by the parser in `named' itself. For example, port numbers are not verified to be positive intergers in the range 0 to 65535. The parse() method cannot be called multiple times with parts of statements. Comments are not passed to a callback method. Some callbacks are invoked before the semicolon that terminates the corresponding syntactic form is actually recognized. It is therefore possible for a syntax error to not be detected until after a callback is invoked for the presumably completly parsed form. No attempt is made to delay the invocation of callbacks to the completion of toplevel statements. NOTE ==== This version of `BIND::Conf_Parser' corresponds to BIND version 8.2.2 and understands the statements, options, and forms of that version. Since the BIND developers have only made upward compatible changes to the syntax, `BIND::Conf_Parser' will correctly parse valid config files for previous versions of BIND. A `BIND::Conf_Parser' object is a blessed anonymous hash. In an attempt to prevent modules trampling on each other I propose that any subclass that requires persistant state between calls to the callback routines (handle_foo()) and other subclass methods should prefix its keys names with its own name separated by _'s. For example, a hypothetical `BIND::Conf_Parser::Keys' module would keep data under keys that started with 'bind_conf_parser_keys_', e.g., 'bind_conf_parser_keys_key_count'. The 'state' key is reserved for use by application specific one-shot parsers (this is expected to encompass most uses of `BIND::Conf_Parser'). `BIND::Conf_Parser' reserves for itself all keys beginning with an underbar. COPYRIGHT ========= Copyright 1998-1999 Philip Guenther. All rights reserved. This library is free software; you can redistribute it and/or This program is free software; redistribution and modification in any form is explicitly permitted provided that all versions retain this copyright notice and the following disclaimer. This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  File: pm.info, Node: BSD/Ipfwgen, Next: BSD/Itimer, Prev: BIND/Conf_Parser, Up: Module List Module to aid in the creation of ipfw-based firewalls ***************************************************** NAME ==== BSD::Ipfwgen - Module to aid in the creation of ipfw-based firewalls SYNOPSIS ======== use BSD::Ipfwgen; outside qw(**interface list**); leaf qw(**interface list**); consolidate qw(**network list**); us qw(**network list**); not_us qw(**network list**); to_us qw(**network list**); from_us qw(**network list**); symmetric qw(**network list**); count_by_interface(); count_by_address qw(**network list**); count_by_udp qw(**port list**); count_by_tcp qw(**port list**); no_looping() no_spoofing_us() no_spoofing_by_us() no_leaf_spoofing() tcp_from_rules($port, $rules); tcp_to_rules($port, $rules); udp_from_rules($port, $rules); udp_to_rules($port, $rules); from_net_rules($network, $rules); to_net_rules($network, $rules); to_me_rules($rules) not_to_me_rules($rules) from_me_rules($rules) not_from_me_rules($rules) in_interface_rules($interface, $rules); out_interface_rules($interface, $rules); drop_unwanted qw(**network list**); generate qw(**options**) **port list** is a list of integers. 80, 23, etc. **network list** is a list of network address. 207.33.90.32/27 etc. **interface list** is a list of interface names. de0, fxp1 etc **options** is a list of the valid options: DEFAULT-ACCEPT, INSECURE $rules is a newline separated set of L rules. DESCRIPTION =========== Ipfwgen is designed to make writing complex firewalls easier and safer. It handles generating some of the harder rulesets: anti-spoofing, anti-looping, and anti land-attack. Ipfwgen does not try to reduce the complexity of firewall building. What it does do is allow you to write a perl program which generates a firewal. It's expected that the firewalls generated by Ipfwgen will be examined by a human and installed manually. Ipfwgen commands must be given in a particular sequence. First are the declaritive commands: *outside*, *leaf*, *consolidate*, *us*, *not_us*, and symmetric. Then the rule-specification commands: almost everything else. Ipfwgen keeps an internal database of the rules that are in progress. After all the rule-specification commands are done, then the firewall gets compiled. The generate command compiles the specifications into actuall `ipfw' in this node commands and dumps them on STDOUT. DECLARATIVE COMMANDS ==================== The declaritive commands must preceed all others. *outside*(INTERFACEs) Specifies that an interface is connected to the Internet at large and that the packets coming in from that interface should not be from "us". *leaf*(INTERFACEs) Specifies that an interface leads to a network with no other connections. Routing to a leaf can be assumed to be symmetric. *consolidate*(NETWORKSs) Specifies that addresses within the network specified should be ignored and that the network address should be used instead when a list of IP addresses for the firewall system is needed. This is primarily used to avoid needing to list a large number of IP addresses on web servers with many virtual hosts. *us*(NETWORKs) Specifies network ranges that comprise the address space that is routed by "us". The *us* command implies that we are the only source of routes for the addresses specifed. *not_us*(NETWORKs) Specifies networks that are within "us" but should not be. For example, "us" may claim to include 209.66.121.0/24, but in reality, the first few addresses aren't ours. This situation can be handled using "not_us". *to_us*(NETWORKs) Specifies networks that we may legitimately receive traffic on behalf of. Don't filter it when incomming at the edges. *from_us*(NETWORKs) Specifies networks that we may legitimately send traffic on behalf of. Don't filter it when outgoing at the edges. symmetric(NETWORKs) Specifies that the routes to a network are expected to be symmetric. COUNTING SPECIFICATIONS ======================= These are all optional. *count_by_interface*() Requests that traffic be counted by interface. Both incoming and outgoing will be counted. *count_by_address*(NETWORKs) Requests that traffic be tracked on a per NETWORK bases. *count_by_udp*(PORTs) Requests that traffic be tracked on a per PORT basis for udp. *count_by_tcp*(PORTs) Requests that traffic be tracked on a per PORT basis for udp. SPOOFING AND LOOPING ==================== Ipfwgen makes an attempt to generate all the anti-looping and anti-spoofing rules. These are all optional, but anti land-attack rules will be added automatically. *no_looping*() Specifies that obvious packet loops should be prevented. For example, do not route packets meant for us out and outside interface. *no_spoofing_us*() Specifies that if there is an "outside" interface, the packets arriving on it should be checked to make sure that they don't claim to come from ourselves. *no_spoofing_by_us*() Specifies that we should only route packets out our "outside" interface that came from us. *no_leaf_spoofing*() Only accept packets from a leaf interface that come from and address that routes over the leaf interface. Do not accept any packets from anyone that claim to be from addresses that route over a leaf interface unless that came in over the leaf interface. FILTER BY ADDRESSES RULES ========================= These are all optional. *from_net_rules*(network,rules) Apply the specified ruleset to packets that came from an address with the network specified. *to_net_rules*(network,rules) Apply the specified ruleset to packets that are destined for an address with the network specified. *drop_unwanted*(networks) A quick way to list the networks that you do not with to communicate with. FITLER BY PORT ============== These are all optional. *tcp_from_rules*(port,rules) Apply the rules specified to tcp packets that came from the specified port. *tcp_to_rules*(port,rules) Apply the rules specified to tcp packets that are destined for the specified port. *udp_from_rules*(port,rules) Apply the rules specified to udp packets that came from the specified port. *udp_to_rules*(port,rules) Apply the rules specified to udp packets that are destined for the specified port. ORIGINATION AND TERMINATION =========================== These are all optional. These filters will be generated anyway to handle the anti land-attack rules. *to_me_rules*(rules) Apply the specified rules to packets that are destined for this machine. *not_to_me_rules*(rules) Apply the specified rules to packets that are not destined for this machine. *from_me_rules*(rules) Apply the specified rules to packets that are sent from this machine. *not_from_me_rules*(rules) Apply the specified rules to packets that came from some other machine. FILTER BY INTERFACE =================== These are all optional, but these filters will be generated anyway to do the anti-looping and anti-spoofing rules. *in_interface_rules*(interface,rules) Apply the specified rules to packets that arrived on the specified interface. *out_interface_rules*(interface,rules) Apply the specified rules to packets that are departing over the specified interface. GENERATE OPTIONS ================ Once the rules have been declared, they must be compiled into actual firewall commands. The command to compile them is generate(options). The generate command should be given last. The compiled rules are dumped on STDOUT. They are not automatically executed. Running generate() cannot harm your system. Running the output from a program that includes generate() can harm your system so be careful! The following options are understood. DEFAULT-ACCEPT Specifies that unless packets are specifically rejected, they should be accepted. The default is that packets that are not specifically accpeted are rejected. INSECURE When building the firewall, add in a rule to accept all packets as a temporary measure. When the firewall is completely built, remove the rule. This creates a window of opportunity for attack. On the other hand, it helps prevent accididental computer death when rebuilding the firewall. It's a good idea to use INSECURE while testing your firewall, but not to use it for final deployment. LOG_DENIES Specifies that in general, when packets are denied, they should be logged. Some rules will still not log: the anti-looping rules tend to deny a lot of packets and logging those is both boring and wasteful. Rules that are defined by hand will that use =deny will log the denies if this is set. RULE LANGUAGE ============= Whenever a command argument includes filtering rules, the rules are expected to be passed in as a single string with the individual rules separated with newlines. META RULES ---------- Ipfwgen rule generation can be modified with special "rules". =label name Specifies a skipto target label. Don't worry about the numbering of the rules. Add a label wherever needed. Some labels are already defined so don't be alarmed if you get an un-expected duplicate. =rulenum num If possible, set the current rule number to num. =gap [size] Make a gap in the rule numbering by rounding up to the next multiple of size. =countby num When incrementing rule numbers, increment by num. META ACTIONS ------------ In addtion to the standard actions defined by `ipfw' in this node, there are some new ones defined by Ipfwgen. =skiprule Specifies that the action for this filter rule is to skip over the following rule. =skipto label Specifies that the action for this filter rule is to skip to the rule after where the label is specified. =deny Specifies that the action for this filter rule is to deny the packet. Packets denied using =deny will be logged if the generate option LOG_DENIES is specified. =deny_log Specifies that the action for this filter is to deny the packet. Just plain *deny log* can be used insted. =deny_no_log Specifies that the action for this filter is to deny the packet. Just plain deny can be used instead. META SPECIFIERS --------------- Ipfwgen provides a shorthand way to specify certain things. =ME The =ME specifier will be replaced by the IP address of the firewall system. If the firewall system has more than one IP address the rule will be replicated as necessary to put them all in. =skiprule still works. =US The =US specifier will be replaced by the network defined by the *us*() command. If more than one network was defined, then the rule with the =US specifier will be replicated as necessary to put them all in. =skiprule still works. =TOUS The =US specifier will be replaced by the network defined by the *to_us*() command. If more than one network was defined, then the rule with the =US specifier will be replicated as necessary to put them all in. =skiprule still works. =FROMUS The =FROMUS specifier will be replaced by the network defined by the *from_us*() command. If more than one network was defined, then the rule with the =US specifier will be replicated as necessary to put them all in. =skiprule still works. =IN The =IN specifier will be replaced by the interfaces that the firewall system has. This will likely require replicating the rule with the specifier. =skiprule still works. =host:hostname The =host:hostname specifier will be replaced with the IP address of the hosthame given. Only one IP address will be substituted in so do not use this with hosts that have multiple IP addresses. The =host:hostname specifier is the only specifier that can be used more than once in a rule and the only one that can be combined with other specifiers. =IF0 FreeBSD treats the first interface a specially. The =IF0 specifier will be replaced by the name of the first interface. =IF0 can be combined with other meta specifiers. SEQUENCE ======== The rules generated by Ipfwgen are processed in the following sequence: 1. Counting rules. Count packets in by interfaces; count packets out by interface; count packets from udp ports; count packets to udp ports; count packets from tcp ports; count packets to tcp pots; count packets from and to particular networks. 2. Apply filters on packets that are from the firewall system (*to_me_rules*). Apply filters on packets that are not from the firewall system (*not_to_me_rules*). 3. Apply filters on packets that are to the firewall system (*from_me_rules*). Apply filters on packets that are not to the firewall system (*not_from_me_rules*). 4. Apply filters for packets that came in via a particular interface. (*in_interface_rules*). This includes loop prevention on point-to-point interfaces. This also includes preventing others from spoofing us and leaf nodes from spoofing anyone. 5. Apply filters for packets that are going out via a particular interface (*out_interface_rules*). This includes loop prevention on outside interfaces and on broadcast networks. This also includes preventing us from spoofing others. 6. Accept packets that are part of established TCP connections. 7. Apply filters for packets that are coming from a particular network (*from_net_rules*). This includes preventing anyone from spoofing traffic from leaf nodes. 8. Apply filters for packets that are going to a particular network (*to_net_rules*). This includes dropping unwanted networks. 9. Apply filters for packets that are coming from a particular udp port. 10. Apply filters for packets that are going to a particular udp port. 11. Apply filters for packets that are coming from a particular tcp port. 12. Apply filters for packets that are going to a particular tcp port. 13. Accept or deny the rest as per the DEFAULT-ACCEPT option. EXAMPLE ======= #/usr/local/bin/perl -w use strict; use BSD::Ipfwgen; use IO::Handle; outside 'fxp0'; leaf 'etha32'; consolidate '209.66.121.128/25'; us qw( 140.174.82.0/24 207.33.232.0/22 207.33.184.0/22 207.33.240.0/21 209.157.64.0/19 140.174.154.0/24 207.33.66.0/24 209.66.121.0/24 ); not_us qw( 209.66.121.0/29 ); symmetric qw( 209.66.121.0/27 ); count_by_interface(); count_by_tcp qw(80 119 21 53 25 871 513 23 6667); count_by_address qw(); drop_unwanted qw( 192.168.0.0:255.255.0.0 172.16.0.0:255.240.0.0 10.0.0.0:255.0.0.0 ); no_looping(); no_spoofing_us(); no_spoofing_by_us(); no_leaf_spoofing(); to_me_rules <<''; =deny udp from not 140.174.82.0/26 to any 111,2049 # portmap, NFS =deny tcp from not 140.174.82.0/26 to any 111 # portmap from_me_rules <<''; =deny udp from any 111,2049 to not 140.174.82.0/26 # portmap, NFS =deny tcp from any 111 to not 140.174.82.0/26 # portmap to_net_rules ('=host:mac84', <<''); =skiprule tcp from 140.174.82.32/27 to =host:mac84 6000 # mac84 =deny tcp from any to =host:mac84 6000 generate qw(INSECURE DEFAULT-ACCEPT); REQUIREMENTS ============ Ipfwgen generates commands that work with FreeBSD 2.2.5's firewall program: `ipfw' in this node. Ipfwgen makes use of features that were only recently added to ipfw: skipto, xmit, recv. BUGS ==== Ipfwgen cannot currently deal non-exclusive thru traffic. For ISPs this means that it cannot deal with customers that have redundent connections. Fixing this is not terribly hard. The firewalls generated by Ipfwgen are often not optimal. If anyone wishes to write an optimizer, that would be great! The firewalls generated by Ipfwgen can be hard to read. Ipfwgen expects the netmasks on point to point links to be accurate. Nothing else really cares about such netmasks so this may lead to some problems. Some of the internal structures aren't very enlightened. For example, everything having to do with get_netmask() and mark_addresses() could be redone for clarity and speed. COPYRIGHT ========= Copyright (C) 1998, David Muir Sharnoff. All rights reserved. License hearby granted for anyone to use this module at their own risk. Please feed useful changes back to muir@idiom.com.