Man page for a??

October 1, 2009 – 11:14 pm

A2P

Section: Perl Programmers Reference Guide (1)
Updated: 2005-04-04
Index
Return to Main Contents

NAME

a2p - Awk to Perl translator

SYNOPSIS

a2p [options] [filename]

DESCRIPTION

A2p takes an awk script specified on the command line (or from
standard input) and produces a comparable perl script on the
standard output.

OPTIONS

Options include:

-D<number>

sets debugging flags.

-F<character>

tells a2p that this awk script is always invoked with this -F
switch.

-n<fieldlist>

specifies the names of the input fields if input does not have to be
split into an array. If you were translating an awk script that
processes the password file, you might say:

a2p -7 -nlogin.password.uid.gid.gcos.shell.home

Any delimiter can be used to separate the field names.

-<number>

causes a2p to assume that input will always have that many fields.

-o

tells a2p to use old awk behavior. The only current differences are:

*

Old awk always has a line loop, even if there are no line
actions, whereas new awk does not.

*

In old awk, sprintf is extremely greedy about its arguments.
For example, given the statement



        print sprintf(some_args), extra_args;

old awk considers extra_args to be arguments to "sprintf"; new awk
considers them arguments to "print".

Considerations

A2p cannot do as good a job translating as a human would, but it
usually does pretty well. There are some areas where you may want to
examine the perl script produced and tweak it some. Here are some of
them, in no particular order.

There is an awk idiom of putting int() around a string expression to
force numeric interpretation, even though the argument is always
integer anyway. This is generally unneeded in perl, but a2p can’t
tell if the argument is always going to be integer, so it leaves it
in. You may wish to remove it.

Perl differentiates numeric comparison from string comparison. Awk
has one operator for both that decides at run time which comparison to
do. A2p does not try to do a complete job of awk emulation at this
point. Instead it guesses which one you want. It’s almost always
right, but it can be spoofed. All such guesses are marked with the
comment ""#???"". You should go through and check them. You might
want to run at least once with the -w switch to perl, which will
warn you if you use == where you should have used eq.

Perl does not attempt to emulate the behavior of awk in which
nonexistent array elements spring into existence simply by being
referenced. If somehow you are relying on this mechanism to create
null entries for a subsequent for…in, they won’t be there in perl.

If a2p makes a split line that assigns to a list of variables that
looks like (Fld1, Fld2, Fld3…) you may want to rerun a2p using the
-n option mentioned above. This will let you name the fields
throughout the script. If it splits to an array instead, the script
is probably referring to the number of fields somewhere.

The exit statement in awk doesn’t necessarily exit; it goes to the END
block if there is one. Awk scripts that do contortions within the END
block to bypass the block under such circumstances can be simplified
by removing the conditional in the END block and just exiting directly
from the perl script.

Perl has two kinds of array, numerically-indexed and associative.
Perl associative arrays are called “hashes”. Awk arrays are usually
translated to hashes, but if you happen to know that the index is
always going to be numeric you could change the {…} to [...].
Iteration over a hash is done using the keys() function, but iteration
over an array is NOT. You might need to modify any loop that iterates
over such an array.

Awk starts by assuming OFMT has the value %.6g. Perl starts by
assuming its equivalent, $#, to have the value %.20g. You’ll want to
set $# explicitly if you use the default value of OFMT.

Near the top of the line loop will be the split operation that is
implicit in the awk script. There are times when you can move this
down past some conditionals that test the entire record so that the
split is not done as often.

For aesthetic reasons you may wish to change the array base $[ from 1
back to perl's default of 0, but remember to change all array
subscripts AND all substr() and index() operations to match.

Cute comments that say ``# Here is a workaround because awk is dumb''
are passed through unmodified.

Awk scripts are often embedded in a shell script that pipes stuff into
and out of awk. Often the shell script wrapper can be incorporated
into the perl script, since perl can start up pipes into and out of
itself, and can do other things that awk can't do by itself.

Scripts that refer to the special variables RSTART and RLENGTH can
often be simplified by referring to the variables $`, $& and $', as
long as they are within the scope of the pattern match that sets them.

The produced perl script may have subroutines defined to deal with
awk's semantics regarding getline and print. Since a2p usually picks
correctness over efficiency. it is almost always possible to rewrite
such code to be more efficient by discarding the semantic sugar.

For efficiency, you may wish to remove the keyword from any return
statement that is the last statement executed in a subroutine. A2p
catches the most common case, but doesn't analyze embedded blocks for
subtler cases.

ARGV[0] translates to $ARGV0, but ARGV[n] translates to $ARGV[$n]. A
loop that tries to iterate over ARGV[0] won’t find it.

ENVIRONMENT

A2p uses no environment variables.

AUTHOR

Larry Wall <larry@wall.org>

FILES

DIAGNOSTICS

BUGS

It would be possible to emulate awk’s behavior in selecting string
versus numeric operations at run time by inspection of the operands,
but it would be gross and inefficient. Besides, a2p almost always
guesses right.

Storage for the awk syntax tree is currently static, and can run out.

Posted in Uncategorized | No Comments »

Man page for a2p?

September 10, 2009 – 5:05 am

A2PS

Section: FSF (1)
Updated: February 2000
Index
Return to Main Contents

NAME

a2ps - format files for printing on a PostScript printer

SYNOPSIS

a2ps

[OPTION]… [FILE]…

DESCRIPTION

Convert FILE(s) or standard input to PostScript.

Mandatory arguments to long options are mandatory for short options too.
Long options marked with * require a yes/no argument, corresponding
short options stand for `yes’.

Tasks:

–version: display version
–help: display this help
–guess: report guessed types of FILES
–which: report the full path of library files named FILES
–glob: report the full path of library files matching FILES
–list=defaults: display default settings and parameters
–list=TOPIC: detailed list on TOPIC (delegations, encodings, features,
variables, media, ppd, printers, prologues, style-sheets,
user-options)

After having performed the task, exit successfully. Detailed lists may
provide additional help on specific features.

Global:

-q, –quiet, –silent: be really quiet
-v, –verbose[=LEVEL]: set verbosity on, or to LEVEL
-=, –user-option=OPTION: use the user defined shortcut OPTION
–debug: enable debugging features
-D, –define=KEY[:VALUE]: unset variable KEY or set to VALUE

Sheets:

-M, –medium=NAME: use output medium NAME

The default behaviour is to use the locale category
LC_PAPER to determine the medium to use. Note that this
information is obtained from environment variables which may not be set
up in non-interactive environments (such as in a cron job).
-r, –landscape: print in landscape mode
-R, –portrait: print in portrait mode
–columns=NUM: number of columns per sheet
–rows=NUM: number of rows per sheet
–major=DIRECTION: first fill (DIRECTION=) rows, or columns
-1, -2, …, -9: predefined font sizes and layouts for 1.. 9 virtuals
-A, –file-align=MODE: align separate files according to MODE (fill, rank
page, sheet, or a number)
-j, –borders*: print borders around columns
–margin[=NUM]: define an interior margin of size NUM

The options -1.. -9 affect several primitive parameters to set up predefined
layouts with 80 columns. Therefore the order matters: `-R -f40 -2‘ is
equivalent to `-2′. To modify the layout, use `-2Rf40′, or compose primitive
options (`–columns’, `–font-size’ etc.).

Virtual pages:

–line-numbers=NUM: precede each NUM lines with its line number
-C: alias for –line-numbers=5
-f, –font-size=SIZE: use font SIZE (float) for the body text
-L, –lines-per-page=NUM: scale the font to print NUM lines per virtual
-l, –chars-per-line=NUM: scale the font to print NUM columns per virtual
-m, –catman: process FILE as a man page (same as -L66)
-T, –tabsize=NUM: set tabulator size to NUM
–non-printable-format=FMT specify how non-printable chars are printed

Headings:

-B, –no-header: no page headers at all
-b, –header[=TEXT]: set page header
-u, –underlay[=TEXT]: print TEXT under every page
–center-title[=TEXT]: set page title to TITLE
–left-title[=TEXT]: set left and right page title to TEXT
–right-title[=TEXT]
–left-footer[=TEXT]: set sheet footers to TEXT
–footer[=TEXT]
–right-footer[=TEXT]

The TEXTs may use special escapes.

Input:

-a, –pages[=RANGE]: select the pages to print
-c, –truncate-lines*: cut long lines
-i, –interpret*: interpret tab, bs and ff chars
–end-of-line=TYPE: specify the eol char (TYPE: r, n, nr, rn, any)
-X, –encoding=NAME: use input encoding NAME
-t, –title=NAME: set the name of the job
–stdin=NAME: set the name of the input file stdin
–print-anyway*: force binary printing
-Z, –delegate*: delegate files to another application
–toc[=TEXT]: generate a table of content

When delegations are enabled, a2ps may use other applications to handle the
processing of files that should not be printed as raw information, e.g., HTML
PostScript, PDF etc.

Pretty-printing:

-E, –pretty-print[=LANG]: enable pretty-printing (set style to LANG)
–highlight-level=LEVEL: set pretty printing highlight LEVEL
LEVEL can be none, normal or heavy
-g: alias for –highlight-level=heavy
–strip-level=NUM: level of comments stripping

Output:

-o, –output=FILE: leave output to file FILE. If FILE is `-’,
leave output to stdout.
–version-control=WORD: override the usual version control
–suffix=SUFFIX: override the usual backup suffix
-P, –printer=NAME: send output to printer NAME
-d: send output to the default printer

PostScript:

–prologue=FILE: include FILE.pro as PostScript prologue
–ppd[=KEY]: automatic PPD selection or set to KEY
-n, –copies=NUM: print NUM copies of each page
-s, –sides=MODE: set the duplex MODE (`1′ or `simplex’,
`2′ or `duplex’, `tumble’)
-S, –setpagedevice=K[:V]: pass a page device definition to output
–statusdict=K[:[:]V]: pass a statusdict definition to the output
-k, –page-prefeed: enable page prefeed
-K, –no-page-prefeed: disable page prefeed

By default a2ps is tuned to do what you want to, so trust it. To pretty
print the content of the `src’ directory and a table of content, and send the
result to the printer `lw’,

: $ a2ps -P lw –toc src/*

To process the files `sample.ps’ and `sample.html’ and display the result,

: $ a2ps -P display sample.ps sample.html

To process a mailbox in 4 up,

: $ a2ps -=mail -4 mailbox

To print as a booklet on the default printer, which is Duplex capable,

: $ a2ps -=book paper.dvi.gz -d

News, updates and documentation: visit http://www.inf.enst.fr/~demaille/a2ps/.

AUTHOR

Written by Akim Demaille, Miguel Santana.

REPORTING BUGS

Report bugs to <bug-a2ps@gnu.org>.

COPYRIGHT

This is free software; see the source for copying conditions. There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

Index

NAME

SYNOPSIS

DESCRIPTION

Tasks:
Global:
Sheets:
Virtual pages:
Headings:
Input:
Pretty-printing:
Output:
PostScript:

Posted in Uncategorized | No Comments »

Man page for a?

September 8, 2009 – 12:16 am

AS

Section: GNU Development Tools (1)
Updated: 2006-03-31
Index
Return to Main Contents

NAME

AS - the portable GNU assembler.

SYNOPSIS

as [-a[cdhlns][=file]] [--alternate] [-D]

[--defsym sym=val] [-f] [-g] [--gstabs]

[--gstabs+] [--gdwarf-2] [--help] [-I dir] [-J]

[-K] [-L] [--listing-lhs-width=NUM]

[--listing-lhs-width2=NUM] [--listing-rhs-width=NUM]

[--listing-cont-lines=NUM] [--keep-locals] [-o

objfile] [-R] [--reduce-memory-overheads] [--statistics]

[-v] [-version] [--version] [-W] [--warn]

[--fatal-warnings] [-w] [-x] [-Z] [@FILE]

[--target-help] [target-options]

[--|files ...]

Target Alpha options:

   [-mcpu]

   [-mdebug | -no-mdebug]

   [-relax] [-g] [-Gsize]

   [-F] [-32addr]

Target ARC options:

[-marc[5|6|7|8]]

[-EB|-EL]

Target ARM options:

   [-mcpu=processor[+extension...]]

   [-march=architecture[+extension...]]

   [-mfpu=floating-point-format]

   [-mfloat-abi=abi]

   [-meabi=ver]

   [-mthumb]

   [-EB|-EL]

   [-mapcs-32|-mapcs-26|-mapcs-float|

    -mapcs-reentrant]

   [-mthumb-interwork] [-k]

Target D10V options:

[-O]

Target D30V options:

[-O|-n|-N]

Target i386 options:

[--32|--64] [-n]

Target i960 options:

   [-ACA|-ACA_A|-ACB|-ACC|-AKA|-AKB|

    -AKC|-AMC]

   [-b] [-no-relax]

Target IP2K options:

[-mip2022|-mip2022ext]

Target M32C options:

[-m32c|-m16c]

Target M32R options:

[--m32rx|--[no-]warn-explicit-parallel-conflicts|

–W[n]p]

Target M680X0 options:

[-l] [-m68000|-m68010|-m68020|...]

Target M68HC11 options:

   [-m68hc11|-m68hc12|-m68hcs12]

   [-mshort|-mlong]

   [-mshort-double|-mlong-double]

   [--force-long-branchs] [--short-branchs]

   [--strict-direct-mode] [--print-insn-syntax]

   [--print-opcodes] [--generate-example]

Target MCORE options:

[-jsri2bsr] [-sifilter] [-relax]

[-mcpu=[210|340]]

Target MIPS options:

   [-nocpp] [-EL] [-EB] [-O[optimization level]]

   [-g[debug level]] [-G num] [-KPIC] [-call_shared]

   [-non_shared] [-xgot]

   [-mabi=ABI] [-32] [-n32] [-64] [-mfp32] [-mgp32]

   [-march=CPU] [-mtune=CPU] [-mips1] [-mips2]

   [-mips3] [-mips4] [-mips5] [-mips32] [-mips32r2]

   [-mips64] [-mips64r2]

   [-construct-floats] [-no-construct-floats]

   [-trap] [-no-break] [-break] [-no-trap]

   [-mfix7000] [-mno-fix7000]

   [-mips16] [-no-mips16]

   [-mips3d] [-no-mips3d]

   [-mdmx] [-no-mdmx]

   [-mdsp] [-mno-dsp]

   [-mmt] [-mno-mt]

   [-mdebug] [-no-mdebug]

   [-mpdr] [-mno-pdr]

Target MMIX options:

   [--fixed-special-register-names] [--globalize-symbols]

   [--gnu-syntax] [--relax] [--no-predefined-symbols]

   [--no-expand] [--no-merge-gregs] [-x]

   [--linker-allocated-gregs]

Target PDP11 options:

   [-mpic|-mno-pic] [-mall] [-mno-extensions]

   [-mextension|-mno-extension]

   [-mcpu] [-mmachine]

Target picoJava options:

[-mb|-me]

Target TIC54X options:

[-mcpu=54[123589]|-mcpu=54[56]lp] [-mfar-mode|-mf]

[-merrors-to-file <filename>|-me <filename>]

Target Z80 options:

  [-z80] [-r800]

  [ -ignore-undocumented-instructions] [-Wnud]

  [ -ignore-unportable-instructions] [-Wnup]

  [ -warn-undocumented-instructions] [-Wud]

  [ -warn-unportable-instructions] [-Wup]

  [ -forbid-undocumented-instructions] [-Fud]

  [ -forbid-unportable-instructions] [-Fup]

Target Xtensa options:

[--[no-]text-section-literals] [--[no-]absolute-literals]

[--[no-]target-align] [--[no-]longcalls]

[--[no-]transform]

[--rename-section oldname=newname]

DESCRIPTION

GNU as is really a family of assemblers.
If you use (or have used) the GNU assembler on one architecture, you
should find a fairly similar environment when you use it on another
architecture. Each version has much in common with the others,
including object file formats, most assembler directives (often called
pseudo-ops) and assembler syntax.

as is primarily intended to assemble the output of the
GNU C compiler "gcc" for use by the linker
"ld". Nevertheless, we’ve tried to make as
assemble correctly everything that other assemblers for the same
machine would assemble.
Any exceptions are documented explicitly.
This doesn’t mean as always uses the same syntax as another
assembler for the same architecture; for example, we know of several
incompatible versions of 680×0 assembly language syntax.

Each time you run as it assembles exactly one source
program. The source program is made up of one or more files.
(The standard input is also a file.)

You give as a command line that has zero or more input file
names. The input files are read (from left file name to right). A
command line argument (in any position) that has no special meaning
is taken to be an input file name.

If you give as no file names it attempts to read one input file
from the as standard input, which is normally your terminal. You
may have to type ctl-D to tell as there is no more program
to assemble.

Use – if you need to explicitly name the standard input file
in your command line.

If the source is empty, as produces a small, empty object
file.

as may write warnings and error messages to the standard error
file (usually your terminal). This should not happen when a compiler
runs as automatically. Warnings report an assumption made so
that as could keep assembling a flawed program; errors report a
grave problem that stops the assembly.

If you are invoking as via the GNU C compiler,
you can use the -Wa option to pass arguments through to the assembler.
The assembler arguments must be separated from each other (and the -Wa)
by commas. For example:

gcc -c -g -O -Wa,-alh,-L file.c

This passes two options to the assembler: -alh (emit a listing to
standard output with high-level and assembly source) and -L (retain
local symbols in the symbol table).

Usually you do not need to use this -Wa mechanism, since many compiler
command-line options are automatically passed to the assembler by the compiler.
(You can call the GNU compiler driver with the -v option to see
precisely what options it passes to each compilation pass, including the
assembler.)

OPTIONS

@file

Read command-line options from file. The options read are
inserted in place of the original @file option. If file
does not exist, or cannot be read, then the option will be treated
literally, and not removed.

Options in file are separated by whitespace. A whitespace
character may be included in an option by surrounding the entire
option in either single or double quotes. Any character (including a
backslash) may be included by prefixing the character to be included
with a backslash. The file may itself contain additional
@file options; any such options will be processed recursively.

-a[cdhlmns]

Turn on listings, in any of a variety of ways:

-ac: omit false conditionals
-ad: omit debugging directives
-ah: include high-level source
-al: include assembly
-am: include macro expansions
-an: omit forms processing
-as: include symbols
=file: set the name of the listing file

You may combine these options; for example, use -aln for assembly
listing without forms processing. The =file option, if used, must be
the last one. By itself, -a defaults to -ahls.

–alternate

Begin in alternate macro mode, see Altmacro,,".altmacro".

-D

Ignored. This option is accepted for script compatibility with calls to
other assemblers.

–defsym sym=value

Define the symbol sym to be value before assembling the input file.
value must be an integer constant. As in C, a leading 0x
indicates a hexadecimal value, and a leading 0 indicates an octal value.

-f

“fast”—skip whitespace and comment preprocessing (assume source is
compiler output).

-g

–gen-debug

Generate debugging information for each assembler source line using whichever
debug format is preferred by the target. This currently means either STABS,
ECOFF or DWARF2.

–gstabs

Generate stabs debugging information for each assembler line. This
may help debugging assembler code, if the debugger can handle it.

–gstabs+

Generate stabs debugging information for each assembler line, with GNU
extensions that probably only gdb can handle, and that could make other
debuggers crash or refuse to read your program. This
may help debugging assembler code. Currently the only GNU extension is
the location of the current working directory at assembling time.

–gdwarf-2

Generate DWARF2 debugging information for each assembler line. This
may help debugging assembler code, if the debugger can handle it. Note—this
option is only supported by some targets, not all of them.

–help

Print a summary of the command line options and exit.

–target-help

Print a summary of all target specific options and exit.

-I dir

Add directory dir to the search list for ".include" directives.

-J

Don’t warn about signed overflow.

-K

Issue warnings when difference tables altered for long displacements.

-L

–keep-locals

Keep (in the symbol table) local symbols. On traditional a.out systems
these start with L, but different systems have different local
label prefixes.

–listing-lhs-width=number

Set the maximum width, in words, of the output data column for an assembler
listing to number.

–listing-lhs-width2=number

Set the maximum width, in words, of the output data column for continuation
lines in an assembler listing to number.

–listing-rhs-width=number

Set the maximum width of an input source line, as displayed in a listing, to
number bytes.

–listing-cont-lines=number

Set the maximum number of lines printed in a listing for a single line of input
to number + 1.

-o objfile

Name the object-file output from as objfile.

-R

Fold the data section into the text section.

Set the default size of GAS’s hash tables to a prime number close to
number. Increasing this value can reduce the length of time it takes the
assembler to perform its tasks, at the expense of increasing the assembler’s
memory requirements. Similarly reducing this value can reduce the memory
requirements at the expense of speed.

–reduce-memory-overheads

This option reduces GAS’s memory requirements, at the expense of making the
assembly processes slower. Currently this switch is a synonym for
–hash-size=4051, but in the future it may have other effects as well.

–statistics

Print the maximum space (in bytes) and total time (in seconds) used by
assembly.

–strip-local-absolute

Remove local absolute symbols from the outgoing symbol table.

-v

-version

Print the as version.

–version

Print the as version and exit.

-W

–no-warn

Suppress warning messages.

–fatal-warnings

Treat warnings as errors.

–warn

Don’t suppress warning messages or treat them as errors.

-w

Ignored.

-x

Ignored.

-Z

Generate an object file even after errors.

– | files …

Standard input, or source files to assemble.

The following options are available when as is configured for
an ARC processor.

-marc[5|6|7|8]: This option selects the core processor variant.
-EB | -EL: Select either big-endian (-EB) or little-endian (-EL) output.

The following options are available when as is configured for the ARM
processor family.

-mcpu=processor[+extension...]: Specify which ARM processor variant is the target.
-march=architecture[+extension...]: Specify which ARM architecture variant is used by the target.
-mfpu=floating-point-format: Select which Floating Point architecture is the target.
-mfloat-abi=abi: Select which floating point ABI is in use.
-mthumb: Enable Thumb only instruction decoding.
-mapcs-32 | -mapcs-26 | -mapcs-float | -mapcs-reentrant: Select which procedure calling convention is in use.
-EB | -EL: Select either big-endian (-EB) or little-endian (-EL) output.
-mthumb-interwork: Specify that the code has been generated with interworking between Thumb and
ARM code in mind.
-k: Specify that PIC code has been generated.

See the info pages for documentation of the CRIS-specific options.

The following options are available when as is configured for
a D10V processor.

-O: Optimize output by parallelizing instructions.

The following options are available when as is configured for a D30V
processor.

-O: Optimize output by parallelizing instructions.
-n: Warn when nops are generated.
-N: Warn when a nop after a 32-bit multiply instruction is generated.

The following options are available when as is configured for the
Intel 80960 processor.

-ACA | -ACA_A | -ACB | -ACC | -AKA | -AKB | -AKC | -AMC: Specify which variant of the 960 architecture is the target.
-b: Add code to collect statistics about branches taken.
-no-relax: Do not alter compare-and-branch instructions for long displacements;
error if necessary.

The following options are available when as is configured for the
Ubicom IP2K series.

-mip2022ext: Specifies that the extended IP2022 instructions are allowed.
-mip2022: Restores the default behaviour, which restricts the permitted instructions to
just the basic IP2022 ones.

The following options are available when as is configured for the
Renesas M32C and M16C processors.

-m32c: Assemble M32C instructions.
-m16c: Assemble M16C instructions (the default).

The following options are available when as is configured for the
Renesas M32R (formerly Mitsubishi M32R) series.

–m32rx: Specify which processor in the M32R family is the target. The default
is normally the M32R, but this option changes it to the M32RX.
–warn-explicit-parallel-conflicts or –Wp: Produce warning messages when questionable parallel constructs are
encountered.
–no-warn-explicit-parallel-conflicts or –Wnp: Do not produce warning messages when questionable parallel constructs are
encountered.

The following options are available when as is configured for the
Motorola 68000 series.

-l

Shorten references to undefined symbols, to one word instead of two.

-m68000 | -m68008 | -m68010 | -m68020 | -m68030

| -m68040 | -m68060 | -m68302 | -m68331 | -m68332

| -m68333 | -m68340 | -mcpu32 | -m5200

Specify what processor in the 68000 family is the target. The default
is normally the 68020, but this can be changed at configuration time.

-m68881 | -m68882 | -mno-68881 | -mno-68882

The target machine does (or does not) have a floating-point coprocessor.
The default is to assume a coprocessor for 68020, 68030, and cpu32. Although
the basic 68000 is not compatible with the 68881, a combination of the
two can be specified, since it’s possible to do emulation of the
coprocessor instructions with the main processor.

-m68851 | -mno-68851

The target machine does (or does not) have a memory-management
unit coprocessor. The default is to assume an MMU for 68020 and up.

For details about the PDP-11 machine dependent features options,
see PDP-11-Options.

-mpic | -mno-pic

Generate position-independent (or position-dependent) code. The
default is -mpic.

-mall

-mall-extensions

Enable all instruction set extensions. This is the default.

-mno-extensions

Disable all instruction set extensions.

-mextension | -mno-extension

Enable (or disable) a particular instruction set extension.

-mcpu

Enable the instruction set extensions supported by a particular CPU, and
disable all other extensions.

-mmachine

Enable the instruction set extensions supported by a particular machine
model, and disable all other extensions.

The following options are available when as is configured for
a picoJava processor.

-mb: Generate “big endian” format output.
-ml: Generate “little endian” format output.

The following options are available when as is configured for the
Motorola 68HC11 or 68HC12 series.

-m68hc11 | -m68hc12 | -m68hcs12: Specify what processor is the target. The default is
defined by the configuration option when building the assembler.
-mshort: Specify to use the 16-bit integer ABI.
-mlong: Specify to use the 32-bit integer ABI.
-mshort-double: Specify to use the 32-bit double ABI.
-mlong-double: Specify to use the 64-bit double ABI.
–force-long-branchs: Relative branches are turned into absolute ones. This concerns
conditional branches, unconditional branches and branches to a
sub routine.
-S | –short-branchs: Do not turn relative branchs into absolute ones
when the offset is out of range.
–strict-direct-mode: Do not turn the direct addressing mode into extended addressing mode
when the instruction does not support direct addressing mode.
–print-insn-syntax: Print the syntax of instruction in case of error.
–print-opcodes: print the list of instructions with syntax and then exit.
–generate-example: print an example of instruction for each possible instruction and then exit.
This option is only useful for testing as.

The following options are available when as is configured
for the SPARC architecture:

-Av6 | -Av7 | -Av8 | -Asparclet | -Asparclite

-Av8plus | -Av8plusa | -Av9 | -Av9a

Explicitly select a variant of the SPARC architecture.

-Av8plus and -Av8plusa select a 32 bit environment.
-Av9 and -Av9a select a 64 bit environment.

-Av8plusa and -Av9a enable the SPARC V9 instruction set with
UltraSPARC extensions.

-xarch=v8plus | -xarch=v8plusa

For compatibility with the Solaris v9 assembler. These options are
equivalent to -Av8plus and -Av8plusa, respectively.

-bump

Warn when the assembler switches to another architecture.

The following options are available when as is configured for the ‘c54x
architecture.

-mfar-mode: Enable extended addressing mode. All addresses and relocations will assume
extended addressing (usually 23 bits).
-mcpu=CPU_VERSION: Sets the CPU version being compiled for.
-merrors-to-file FILENAME: Redirect error output to a file, for broken systems which don’t support such
behaviour in the shell.

The following options are available when as is configured for
a MIPS processor.

-G num

This option sets the largest size of an object that can be referenced
implicitly with the "gp" register. It is only accepted for targets that
use ECOFF format, such as a DECstation running Ultrix. The default value is 8.

-EB

Generate “big endian” format output.

-EL

Generate “little endian” format output.

-mips1

-mips2

-mips3

-mips4

-mips5

-mips32

-mips32r2

-mips64

-mips64r2

Generate code for a particular MIPS Instruction Set Architecture level.
-mips1 is an alias for -march=r3000, -mips2 is an
alias for -march=r6000, -mips3 is an alias for
-march=r4000 and -mips4 is an alias for -march=r8000.
-mips5, -mips32, -mips32r2, -mips64, and
-mips64r2
correspond to generic
MIPS V, MIPS32, MIPS32 Release 2, MIPS64,
and MIPS64 Release 2
ISA processors, respectively.

-march=CPU

Generate code for a particular MIPS cpu.

-mtune=cpu

Schedule and tune for a particular MIPS cpu.

-mfix7000

-mno-fix7000

Cause nops to be inserted if the read of the destination register
of an mfhi or mflo instruction occurs in the following two instructions.

-mdebug

-no-mdebug

Cause stabs-style debugging output to go into an ECOFF-style .mdebug
section instead of the standard ELF .stabs sections.

-mpdr

-mno-pdr

Control generation of ".pdr" sections.

-mgp32

-mfp32

The register sizes are normally inferred from the ISA and ABI, but these
flags force a certain group of registers to be treated as 32 bits wide at
all times. -mgp32 controls the size of general-purpose registers
and -mfp32 controls the size of floating-point registers.

-mips16

-no-mips16

Generate code for the MIPS 16 processor. This is equivalent to putting
".set mips16" at the start of the assembly file. -no-mips16
turns off this option.

-mips3d

-no-mips3d

Generate code for the MIPS-3D Application Specific Extension.
This tells the assembler to accept MIPS-3D instructions.
-no-mips3d turns off this option.

-mdmx

-no-mdmx

Generate code for the MDMX Application Specific Extension.
This tells the assembler to accept MDMX instructions.
-no-mdmx turns off this option.

-mdsp

-mno-dsp

Generate code for the DSP Application Specific Extension.
This tells the assembler to accept DSP instructions.
-mno-dsp turns off this option.

-mmt

-mno-mt

Generate code for the MT Application Specific Extension.
This tells the assembler to accept MT instructions.
-mno-mt turns off this option.

–construct-floats

–no-construct-floats

The –no-construct-floats option disables the construction of
double width floating point constants by loading the two halves of the
value into the two single width floating point registers that make up
the double width register. By default –construct-floats is
selected, allowing construction of these floating point constants.

–emulation=name

This option causes as to emulate as configured
for some other target, in all respects, including output format (choosing
between ELF and ECOFF only), handling of pseudo-opcodes which may generate
debugging information or store symbol table information, and default
endianness. The available configuration names are: mipsecoff,
mipself, mipslecoff, mipsbecoff, mipslelf,
mipsbelf. The first two do not alter the default endianness from that
of the primary target for which the assembler was configured; the others change
the default to little- or big-endian as indicated by the b or l
in the name. Using -EB or -EL will override the endianness
selection in any case.

This option is currently supported only when the primary target
as is configured for is a MIPS ELF or ECOFF target.
Furthermore, the primary target or others specified with
–enable-targets=… at configuration time must include support for
the other format, if both are to be available. For example, the Irix 5
configuration includes support for both.

Eventually, this option will support more configurations, with more
fine-grained control over the assembler’s behavior, and will be supported for
more processors.

-nocpp

as ignores this option. It is accepted for compatibility with
the native tools.

–trap

–no-trap

–break

–no-break

Control how to deal with multiplication overflow and division by zero.
–trap or –no-break (which are synonyms) take a trap exception
(and only work for Instruction Set Architecture level 2 and higher);
–break or –no-trap (also synonyms, and the default) take a
break exception.

-n

When this option is used, as will issue a warning every
time it generates a nop instruction from a macro.

The following options are available when as is configured for
an MCore processor.

-jsri2bsr

-nojsri2bsr

Enable or disable the JSRI to BSR transformation. By default this is enabled.
The command line option -nojsri2bsr can be used to disable it.

-sifilter

-nosifilter

Enable or disable the silicon filter behaviour. By default this is disabled.
The default can be overridden by the -sifilter command line option.

-relax

Alter jump instructions for long displacements.

-mcpu=[210|340]

Select the cpu type on the target hardware. This controls which instructions
can be assembled.

-EB

Assemble for a big endian target.

-EL

Assemble for a little endian target.

See the info pages for documentation of the MMIX-specific options.

The following options are available when as is configured for
an Xtensa processor.

–text-section-literals | –no-text-section-literals: With –text-section-literals, literal pools are interspersed
in the text section. The default is
–no-text-section-literals, which places literals in a
separate section in the output file. These options only affect literals
referenced via PC-relative "L32R" instructions; literals for
absolute mode "L32R" instructions are handled separately.
–absolute-literals | –no-absolute-literals: Indicate to the assembler whether "L32R" instructions use absolute
or PC-relative addressing. The default is to assume absolute addressing
if the Xtensa processor includes the absolute "L32R" addressing
option. Otherwise, only the PC-relative "L32R" mode can be used.
–target-align | –no-target-align: Enable or disable automatic alignment to reduce branch penalties at the
expense of some code density. The default is –target-align.
–longcalls | –no-longcalls: Enable or disable transformation of call instructions to allow calls
across a greater range of addresses. The default is
–no-longcalls.
–transform | –no-transform: Enable or disable all assembler transformations of Xtensa instructions.
The default is –transform;
–no-transform should be used only in the rare cases when the
instructions must be exactly as specified in the assembly source.

The following options are available when as is configured for
a Z80 family processor.

-z80

Assemble for Z80 processor.

-r800

Assemble for R800 processor.

-ignore-undocumented-instructions

-Wnud

Assemble undocumented Z80 instructions that also work on R800 without warning.

-ignore-unportable-instructions

-Wnup

Assemble all undocumented Z80 instructions without warning.

-warn-undocumented-instructions

-Wud

Issue a warning for undocumented Z80 instructions that also work on R800.

-warn-unportable-instructions

-Wup

Issue a warning for undocumented Z80 instructions that do notwork on R800.

-forbid-undocumented-instructions

-Fud

Treat all undocumented instructions as errors.

-forbid-unportable-instructions

-Fup

Treat undocumented Z80 intructions that do notwork on R800 as errors.

COPYRIGHT

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1
or any later version published by the Free Software Foundation;
with no Invariant Sections, with no Front-Cover Texts, and with no
Back-Cover Texts. A copy of the license is included in the
section entitled “GNU Free Documentation License”.

Index

NAME
SYNOPSIS
DESCRIPTION
OPTIONS
SEE ALSO
COPYRIGHT

Posted in Uncategorized | No Comments »

Man page for a???

September 7, 2009 – 11:16 am

Posted in Uncategorized | No Comments »

Man page for a???

September 7, 2009 – 11:16 am

Posted in Uncategorized | No Comments »

Man page for a???

September 7, 2009 – 11:16 am

ATTR

Section: XFS Compatibility API (1)
Updated: Extended Attributes
Index
Return to Main Contents

NAME

attr - extended attributes on XFS filesystem objects

SYNOPSIS



attr [ -LRSq ] -s attrname [ -V attrvalue ] pathname
attr [ -LRSq ] -g attrname pathname
attr [ -LRSq ] -r attrname pathname
attr [ -LRSq ] -l pathname

OVERVIEW

Extended attributes implement the ability for a user to attach
name:value pairs to objects within the XFS filesystem.

They could be used to store meta-information about the file.
For example "character-set=kanji" could tell a document browser to
use the Kanji character set when displaying that document
and "thumbnail=…" could provide a reduced resolution overview of a
high resolution graphic image.

This document describes the
attr

command, which is mostly compatible with the IRIX command of the same name.
It is thus aimed specifically at users of the XFS filesystem - for
filesystem independent extended attribute manipulation, consult the
getfattr(1)

and
setfattr(1)

documentation.

In the XFS filesystem, the
names

can be up to 256 bytes in length, terminated by the first 0 byte.
The intent is that they be printable ASCII (or other character set)
names for the attribute.
The
values

can be up to 64KB of arbitrary binary data.

Attributes can be attached to all types of XFS inodes:
regular files, directories, symbolic links, device nodes, etc.

XFS uses 2 disjoint attribute name spaces associated with every
filesystem object.
They are the
root

and
user

address spaces.
The
root

address space is accessable only to the superuser,
and then only by specifying a flag argument to the function call.
Other users will not see or be able to modify attributes in the
root

address space.
The
user

address space is protected by the normal file permissions mechanism,
so the owner of the file can decide who is able to see and/or modify
the value of attributes on any particular file.

DESCRIPTION

The
attr

utility allows the manipulation of extended attributes associated with
filesystem objects from within shell scripts.

There are four main operations that
attr

can perform:

GET

The
-g attrname

option tells
attr

to search the named object and print (to stdout) the value
associated with that attribute name.
With the
-q

flag, stdout will be exactly and only the value of the attribute,
suitable for storage directly into a file or processing via a piped command.

LIST

The
-l

option tells
attr

to list the names of all the attributes that are associated with the object,
and the number of bytes in the value of each of those attributes.
With the
-q

flag, stdout will be a simple list of only the attribute names,
one per line, suitable for input into a script.

REMOVE

The
-r attrname

option tells
attr

to remove an attribute with the given name from the object if the
attribute exists.
There is no output on sucessful completion.

SET/CREATE

The
-s attrname

option tells
attr

to set the named attribute of the object to the value read from stdin.
If an attribute with that name already exists,
its value will be replaced with this one.
If an attribute with that name does not already exist,
one will be created with this value.
With the
-V attrvalue

flag, the attribute will be set to have a value of
attrvalue

and stdin will not be read.
With the
-q

flag, stdout will not be used.
Without the
-q

flag, a message showing the attribute name and the entire value
will be printed.

When the
-L

option is given and the named object is a symbolic link,
operate on the attributes of the object referenced by the symbolic link.
Without this option, operate on the attributes of the symbolic link itself.

When the
-R

option is given and the process has appropriate privileges,
operate in the
root

attribute namespace rather that the
USER

attribute namespace.

The
-S

option is similar, except it specifies use of the
security

attribute namespace.

When the
-q

option is given
attr

will try to keep quiet.
It will output error messages (to stderr)
but will not print status messages (to stdout).

NOTES

The standard file interchange/archive programs
tar(1),

and
cpio(1)

will not archive or restore extended attributes,
while the
xfsdump(8)

program will.

CAVEATS

The list option present in the IRIX version of this command is not supported.
getfattr

provides a mechanism to retrieve all of the attribute names.

Index

NAME
SYNOPSIS
OVERVIEW
DESCRIPTION
NOTES
CAVEATS
SEE ALSO

Posted in Uncategorized | No Comments »

Man page for pid??

August 12, 2009 – 5:03 am

PIDOF

Section: Linux System Administrator’s Manual (8)
Updated: 01 Sep 1998
Index
Return to Main Contents

NAME

pidof — find the process ID of a running program.

SYNOPSIS

pidof

[-s]

[-c]

[-x]

[-o

omitpid]

[-o

omitpid..]

program

[program..]

DESCRIPTION

Pidof

finds the process id’s (pids) of the named programs. It prints those
id’s on the standard output. This program is on some systems used in
run-level change scripts, especially when the system has a
System-V like rc structure. In that case these scripts are
located in /etc/rc?.d, where ? is the runlevel. If the system has
a
start-stop-daemon

(8) program that should be used instead.

OPTIONS

-s: Single shot - this instructs the program to only return one pid.
-c: Only return process ids that are running with the same root directory.
This option does not make sense for non-root users, as they will be
unable to check the current root directory of processes they do not own.
-x: Scripts too - this causes the program to also return process id’s of
shells running the named scripts.
-o: Tells pidof to omit processes with that process id. The special
pid %PPID can be used to name the parent process of the pidof
program, in other words the calling shell or shell script.

NOTES

pidof is simply a (symbolic) link to the killall5 program,
which should also be located in /sbin.

When pidof is invoked with a full pathname to the program it
should find the pid of, it is reasonably safe. Otherwise it is possible
that it returns pids of running programs that happen to have the same name
as the program you’re after but are actually other programs.

AUTHOR

Miquel van Smoorenburg, miquels@cistron.nl

Index

NAME
SYNOPSIS
DESCRIPTION
OPTIONS
NOTES
SEE ALSO
AUTHOR

Posted in Uncategorized | No Comments »

Man page for ?s

December 1, 2008 – 4:53 am

LS

Section: User Commands (1)
Updated: June 2006
Index
Return to Main Contents

NAME

ls - list directory contents

SYNOPSIS

[OPTION]… [FILE]…

DESCRIPTION

List information about the FILEs (the current directory by default).
Sort entries alphabetically if none of -cftuvSUX nor –sort.

Mandatory arguments to long options are mandatory for short options too.

-a, –all: do not ignore entries starting with .
-A, –almost-all: do not list implied . and ..
–author: with -l, print the author of each file
-b, –escape: print octal escapes for nongraphic characters
–block-size=SIZE: use SIZE-byte blocks
-B, –ignore-backups: do not list implied entries ending with ~
-c: with -lt: sort by, and show, ctime (time of last
modification of file status information)
with -l: show ctime and sort by name
otherwise: sort by ctime
-C: list entries by columns
–color[=WHEN]: control whether color is used to distinguish file
types. WHEN may be `never’, `always’, or `auto’
-d, –directory: list directory entries instead of contents,
and do not dereference symbolic links
-D, –dired: generate output designed for Emacs’ dired mode
-f: do not sort, enable -aU, disable -lst
-F, –classify: append indicator (one of */=>@|) to entries
–file-type: likewise, except do not append `*’
–format=WORD: across -x, commas -m, horizontal -x, long -l,
single-column -1, verbose -l, vertical -C
–full-time: like -l –time-style=full-iso
-g: like -l, but do not list owner
-G, –no-group: like -l, but do not list group
-h, –human-readable: with -l, print sizes in human readable format
(e.g., 1K 234M 2G)
–si: likewise, but use powers of 1000 not 1024
-H, –dereference-command-line: follow symbolic links listed on the command line
–dereference-command-line-symlink-to-dir: follow each command line symbolic link
that points to a directory
–hide=PATTERN: do not list implied entries matching shell PATTERN
(overridden by -a or -A)
–indicator-style=WORD append indicator with style WORD to entry names:: none (default), slash (-p),
file-type (–file-type), classify (-F)
-i, –inode: with -l, print the index number of each file
-I, –ignore=PATTERN: do not list implied entries matching shell PATTERN
-k: like –block-size=1K
-l: use a long listing format
-L, –dereference: when showing file information for a symbolic
link, show information for the file the link
references rather than for the link itself
-m: fill width with a comma separated list of entries
-n, –numeric-uid-gid: like -l, but list numeric user and group IDs
-N, –literal: print raw entry names (don’t treat e.g. control
characters specially)
-o: like -l, but do not list group information
-p, –indicator-style=slash: append / indicator to directories
-q, –hide-control-chars: print ? instead of non graphic characters
–show-control-chars: show non graphic characters as-is (default
unless program is `ls’ and output is a terminal)
-Q, –quote-name: enclose entry names in double quotes
–quoting-style=WORD: use quoting style WORD for entry names:
literal, locale, shell, shell-always, c, escape
-r, –reverse: reverse order while sorting
-R, –recursive: list subdirectories recursively
-s, –size: with -l, print size of each file, in blocks
-S: sort by file size
–sort=WORD: extension -X, none -U, size -S, time -t,
version -v, status -c, time -t, atime -u,
access -u, use -u
–time=WORD: with -l, show time as WORD instead of modification
time: atime, access, use, ctime or status; use
specified time as sort key if –sort=time
–time-style=STYLE: with -l, show times using style STYLE:
full-iso, long-iso, iso, locale, +FORMAT.
FORMAT is interpreted like `date’; if FORMAT is
FORMAT1<newline>FORMAT2, FORMAT1 applies to
non-recent files and FORMAT2 to recent files;
if STYLE is prefixed with `posix-’, STYLE
takes effect only outside the POSIX locale
-t: sort by modification time
-T, –tabsize=COLS: assume tab stops at each COLS instead of 8
-u: with -lt: sort by, and show, access time
with -l: show access time and sort by name
otherwise: sort by access time
-U: do not sort; list entries in directory order
-v: sort by version
-w, –width=COLS: assume screen width instead of current value
-x: list entries by lines instead of by columns
-X: sort alphabetically by entry extension
-1: list one file per line

SELinux options:

–lcontext: Display security context. Enable -l. Lines
will probably be too wide for most displays.
-Z, –context: Display security context so it fits on most
displays. Displays only mode, user, group,
security context and file name.
–scontext: Display only security context and file name.
–help: display this help and exit
–version: output version information and exit

SIZE may be (or may be an integer optionally followed by) one of following:
kB 1000, K 1024, MB 1000*1000, M 1024*1024, and so on for G, T, P, E, Z, Y.

By default, color is not used to distinguish types of files. That is
equivalent to using –color=none. Using the –color option without the
optional WHEN argument is equivalent to using –color=always. With
–color=auto, color codes are output only if standard output is connected
to a terminal (tty). The environment variable LS_COLORS can influence the
colors, and can be set easily by the dircolors command.

Exit status is 0 if OK, 1 if minor problems, 2 if serious trouble.

AUTHOR

Written by Richard Stallman and David MacKenzie.

REPORTING BUGS

Report bugs to <bug-coreutils@gnu.org>.

COPYRIGHT

This is free software. You may redistribute copies of it under the terms of
the GNU General Public License <http://www.gnu.org/licenses/gpl.html>.
There is NO WARRANTY, to the extent permitted by law.

Index

NAME
SYNOPSIS
DESCRIPTION
AUTHOR
REPORTING BUGS
COPYRIGHT
SEE ALSO

Posted in Uncategorized | No Comments »

Man page for ?a

September 16, 2008 – 9:44 am

CA

Section: OpenSSL (1)
Updated: 2005-07-15
Index
Return to Main Contents

NAME

ca - sample minimal CA application

SYNOPSIS

openssl ca
[-verbose]
[-config filename]
[-name section]
[-gencrl]
[-revoke file]
[-crl_reason reason]
[-crl_hold instruction]
[-crl_compromise time]
[-crl_CA_compromise time]
[-crldays days]
[-crlhours hours]
[-crlexts section]
[-startdate date]
[-enddate date]
[-days arg]
[-md arg]
[-policy arg]
[-keyfile arg]
[-key arg]
[-passin arg]
[-cert file]
[-selfsign]
[-in file]
[-out file]
[-notext]
[-outdir dir]
[-infiles]
[-spkac file]
[-ss_cert file]
[-preserveDN]
[-noemailDN]
[-batch]
[-msie_hack]
[-extensions section]
[-extfile section]
[-engine id]
[-subj arg]
[-utf8]
[-multivalue-rdn]

DESCRIPTION

The ca command is a minimal CA application. It can be used
to sign certificate requests in a variety of forms and generate
CRLs it also maintains a text database of issued certificates
and their status.

The options descriptions will be divided into each purpose.

CA OPTIONS

-config filename

specifies the configuration file to use.

-name section

specifies the configuration file section to use (overrides
default_ca in the ca section).

-in filename

an input filename containing a single certificate request to be
signed by the CA.

-ss_cert filename

a single self signed certificate to be signed by the CA.

-spkac filename

a file containing a single Netscape signed public key and challenge
and additional field values to be signed by the CA. See the SPKAC FORMAT
section for information on the required format.

-infiles

if present this should be the last option, all subsequent arguments
are assumed to the the names of files containing certificate requests.

-out filename

the output file to output certificates to. The default is standard
output. The certificate details will also be printed out to this
file.

-outdir directory

the directory to output certificates to. The certificate will be
written to a filename consisting of the serial number in hex with
“.pem” appended.

-cert

the CA certificate file.

-keyfile filename

the private key to sign requests with.

-key password

the password used to encrypt the private key. Since on some
systems the command line arguments are visible (e.g. Unix with
the ‘ps’ utility) this option should be used with caution.

-selfsign

indicates the issued certificates are to be signed with the key
the certificate requests were signed with (given with -keyfile).
Cerificate requests signed with a different key are ignored. If
-spkac, -ss_cert or -gencrl are given, -selfsign is
ignored.

A consequence of using -selfsign is that the self-signed
certificate appears among the entries in the certificate database
(see the configuration option database), and uses the same
serial number counter as all other certificates sign with the
self-signed certificate.

-passin arg

the key password source. For more information about the format of arg
see the PASS PHRASE ARGUMENTS section in openssl(1).

-verbose

this prints extra details about the operations being performed.

-notext

don’t output the text form of a certificate to the output file.

-startdate date

this allows the start date to be explicitly set. The format of the
date is YYMMDDHHMMSSZ (the same as an ASN1 UTCTime structure).

-enddate date

this allows the expiry date to be explicitly set. The format of the
date is YYMMDDHHMMSSZ (the same as an ASN1 UTCTime structure).

-days arg

the number of days to certify the certificate for.

-md alg

the message digest to use. Possible values include md5, sha1 and mdc2.
This option also applies to CRLs.

-policy arg

this option defines the CA “policy” to use. This is a section in
the configuration file which decides which fields should be mandatory
or match the CA certificate. Check out the POLICY FORMAT section
for more information.

-msie_hack

this is a legacy option to make ca work with very old versions of
the IE certificate enrollment control “certenr3”. It used UniversalStrings
for almost everything. Since the old control has various security bugs
its use is strongly discouraged. The newer control “Xenroll” does not
need this option.

-preserveDN

Normally the DN order of a certificate is the same as the order of the
fields in the relevant policy section. When this option is set the order
is the same as the request. This is largely for compatibility with the
older IE enrollment control which would only accept certificates if their
DNs match the order of the request. This is not needed for Xenroll.

-noemailDN

The DN of a certificate can contain the EMAIL field if present in the
request DN, however it is good policy just having the e-mail set into
the altName extension of the certificate. When this option is set the
EMAIL field is removed from the certificate’ subject and set only in
the, eventually present, extensions. The email_in_dn keyword can be
used in the configuration file to enable this behaviour.

-batch

this sets the batch mode. In this mode no questions will be asked
and all certificates will be certified automatically.

-extensions section

the section of the configuration file containing certificate extensions
to be added when a certificate is issued (defaults to x509_extensions
unless the -extfile option is used). If no extension section is
present then, a V1 certificate is created. If the extension section
is present (even if it is empty), then a V3 certificate is created.

-extfile file

an additional configuration file to read certificate extensions from
(using the default section unless the -extensions option is also
used).

-engine id

specifying an engine (by it’s unique id string) will cause req
to attempt to obtain a functional reference to the specified engine,
thus initialising it if needed. The engine will then be set as the default
for all available algorithms.

-subj arg

supersedes subject name given in the request.
The arg must be formatted as /type0=value0/type1=value1/type2=…,
characters may be escaped by \ (backslash), no spaces are skipped.

-utf8

this option causes field values to be interpreted as UTF8 strings, by
default they are interpreted as ASCII. This means that the field
values, whether prompted from a terminal or obtained from a
configuration file, must be valid UTF8 strings.

-multivalue-rdn

this option causes the -subj argument to be interpretedt with full
support for multivalued RDNs. Example:

/DC=org/DC=OpenSSL/DC=users/UID=123456+CN=John Doe

If -multi-rdn is not used then the UID value is 123456+CN=John Doe.

CRL OPTIONS

-gencrl

this option generates a CRL based on information in the index file.

-crldays num

the number of days before the next CRL is due. That is the days from
now to place in the CRL nextUpdate field.

-crlhours num

the number of hours before the next CRL is due.

-revoke filename

a filename containing a certificate to revoke.

-crl_reason reason

revocation reason, where reason is one of: unspecified, keyCompromise,
CACompromise, affiliationChanged, superseded, cessationOfOperation,
certificateHold or removeFromCRL. The matching of reason is case
insensitive. Setting any revocation reason will make the CRL v2.

In practive removeFromCRL is not particularly useful because it is only used
in delta CRLs which are not currently implemented.

-crl_hold instruction

This sets the CRL revocation reason code to certificateHold and the hold
instruction to instruction which must be an OID. Although any OID can be
used only holdInstructionNone (the use of which is discouraged by RFC2459)
holdInstructionCallIssuer or holdInstructionReject will normally be used.

-crl_compromise time

This sets the revocation reason to keyCompromise and the compromise time to
time. time should be in GeneralizedTime format that is YYYYMMDDHHMMSSZ.

-crl_CA_compromise time

This is the same as crl_compromise except the revocation reason is set to
CACompromise.

-crlexts section

the section of the configuration file containing CRL extensions to
include. If no CRL extension section is present then a V1 CRL is
created, if the CRL extension section is present (even if it is
empty) then a V2 CRL is created. The CRL extensions specified are
CRL extensions and not CRL entry extensions. It should be noted
that some software (for example Netscape) can’t handle V2 CRLs.

CONFIGURATION FILE OPTIONS

The section of the configuration file containing options for ca
is found as follows: If the -name command line option is used,
then it names the section to be used. Otherwise the section to
be used must be named in the default_ca option of the ca section
of the configuration file (or in the default section of the
configuration file). Besides default_ca, the following options are
read directly from the ca section:

RANDFILE

preserve

msie_hack
With the exception of RANDFILE, this is probably a bug and may
change in future releases.

Many of the configuration file options are identical to command line
options. Where the option is present in the configuration file
and the command line the command line value is used. Where an
option is described as mandatory then it must be present in
the configuration file or the command line equivalent (if
any) used.

oid_file

This specifies a file containing additional OBJECT IDENTIFIERS.
Each line of the file should consist of the numerical form of the
object identifier followed by white space then the short name followed
by white space and finally the long name.

oid_section

This specifies a section in the configuration file containing extra
object identifiers. Each line should consist of the short name of the
object identifier followed by = and the numerical form. The short
and long names are the same when this option is used.

new_certs_dir

the same as the -outdir command line option. It specifies
the directory where new certificates will be placed. Mandatory.

certificate

the same as -cert. It gives the file containing the CA
certificate. Mandatory.

private_key

same as the -keyfile option. The file containing the
CA private key. Mandatory.

RANDFILE

a file used to read and write random number seed information, or
an EGD socket (see RAND_egd(3)).

default_days

the same as the -days option. The number of days to certify
a certificate for.

default_startdate

the same as the -startdate option. The start date to certify
a certificate for. If not set the current time is used.

default_enddate

the same as the -enddate option. Either this option or
default_days (or the command line equivalents) must be
present.

default_crl_hours default_crl_days

the same as the -crlhours and the -crldays options. These
will only be used if neither command line option is present. At
least one of these must be present to generate a CRL.

default_md

the same as the -md option. The message digest to use. Mandatory.

database

the text database file to use. Mandatory. This file must be present
though initially it will be empty.

unique_subject

if the value yes is given, the valid certificate entries in the
database must have unique subjects. if the value no is given,
several valid certificate entries may have the exact same subject.
The default value is yes, to be compatible with older (pre 0.9.8)
versions of OpenSSL. However, to make CA certificate roll-over easier,
it’s recommended to use the value no, especially if combined with
the -selfsign command line option.

serial

a text file containing the next serial number to use in hex. Mandatory.
This file must be present and contain a valid serial number.

crlnumber

a text file containing the next CRL number to use in hex. The crl number
will be inserted in the CRLs only if this file exists. If this file is
present, it must contain a valid CRL number.

x509_extensions

the same as -extensions.

crl_extensions

the same as -crlexts.

preserve

the same as -preserveDN

email_in_dn

the same as -noemailDN. If you want the EMAIL field to be removed
from the DN of the certificate simply set this to ‘no’. If not present
the default is to allow for the EMAIL filed in the certificate’s DN.

msie_hack

the same as -msie_hack

policy

the same as -policy. Mandatory. See the POLICY FORMAT section
for more information.

name_opt, cert_opt

these options allow the format used to display the certificate details
when asking the user to confirm signing. All the options supported by
the x509 utilities -nameopt and -certopt switches can be used
here, except the no_signame and no_sigdump are permanently set
and cannot be disabled (this is because the certificate signature cannot
be displayed because the certificate has not been signed at this point).

For convenience the values ca_default are accepted by both to produce
a reasonable output.

If neither option is present the format used in earlier versions of
OpenSSL is used. Use of the old format is strongly discouraged because
it only displays fields mentioned in the policy section, mishandles
multicharacter string types and does not display extensions.

copy_extensions

determines how extensions in certificate requests should be handled.
If set to none or this option is not present then extensions are
ignored and not copied to the certificate. If set to copy then any
extensions present in the request that are not already present are copied
to the certificate. If set to copyall then all extensions in the
request are copied to the certificate: if the extension is already present
in the certificate it is deleted first. See the WARNINGS section before
using this option.

The main use of this option is to allow a certificate request to supply
values for certain extensions such as subjectAltName.

POLICY FORMAT

The policy section consists of a set of variables corresponding to
certificate DN fields. If the value is “match” then the field value
must match the same field in the CA certificate. If the value is
“supplied” then it must be present. If the value is “optional” then
it may be present. Any fields not mentioned in the policy section
are silently deleted, unless the -preserveDN option is set but
this can be regarded more of a quirk than intended behaviour.

SPKAC FORMAT

The input to the -spkac command line option is a Netscape
signed public key and challenge. This will usually come from
the KEYGEN tag in an HTML form to create a new private key.
It is however possible to create SPKACs using the spkac utility.

The file should contain the variable SPKAC set to the value of
the SPKAC and also the required DN components as name value pairs.
If you need to include the same component twice then it can be
preceded by a number and a ‘.’.

EXAMPLES

Note: these examples assume that the ca directory structure is
already set up and the relevant files already exist. This usually
involves creating a CA certificate and private key with req, a
serial number file and an empty index file and placing them in
the relevant directories.

To use the sample configuration file below the directories demoCA,
demoCA/private and demoCA/newcerts would be created. The CA
certificate would be copied to demoCA/cacert.pem and its private
key to demoCA/private/cakey.pem. A file demoCA/serial would be
created containing for example “01” and the empty index file
demoCA/index.txt.

Sign a certificate request:

openssl ca -in req.pem -out newcert.pem

Sign a certificate request, using CA extensions:

openssl ca -in req.pem -extensions v3_ca -out newcert.pem

Generate a CRL

openssl ca -gencrl -out crl.pem

Sign several requests:

openssl ca -infiles req1.pem req2.pem req3.pem

Certify a Netscape SPKAC:

openssl ca -spkac spkac.txt

A sample SPKAC file (the SPKAC line has been truncated for clarity):



 SPKAC=MIG0MGAwXDANBgkqhkiG9w0BAQEFAANLADBIAkEAn7PDhCeV/xIxUg8V70YRxK2A5

 CN=Steve Test

 emailAddress=steve@openssl.org

 0.OU=OpenSSL Group

 1.OU=Another Group

A sample configuration file with the relevant sections for ca:



 [ ca ]

 default_ca      = CA_default            # The default ca section



 [ CA_default ]

dir = ./demoCA # top dir
database = $dir/index.txt # index file.
new_certs_dir = $dir/newcerts # new certs dir



 certificate    = $dir/cacert.pem       # The CA cert

 serial         = $dir/serial           # serial no file

 private_key    = $dir/private/cakey.pem# CA private key

 RANDFILE       = $dir/private/.rand    # random number file

default_days = 365 # how long to certify for
default_crl_days= 30 # how long before next CRL
default_md = md5 # md to use

policy = policy_any # default policy
email_in_dn = no # Don’t add the email into cert DN

name_opt = ca_default # Subject name display option
cert_opt = ca_default # Certificate display option
copy_extensions = none # Don’t copy extensions from request



 [ policy_any ]

 countryName            = supplied

 stateOrProvinceName    = optional

 organizationName       = optional

 organizationalUnitName = optional

 commonName             = supplied

 emailAddress           = optional

FILES

Note: the location of all files can change either by compile time options,
configuration file entries, environment variables or command line options.
The values below reflect the default values.



 /usr/local/ssl/lib/openssl.cnf - master configuration file

 ./demoCA                       - main CA directory

 ./demoCA/cacert.pem            - CA certificate

 ./demoCA/private/cakey.pem     - CA private key

 ./demoCA/serial                - CA serial number file

 ./demoCA/serial.old            - CA serial number backup file

 ./demoCA/index.txt             - CA text database file

 ./demoCA/index.txt.old         - CA text database backup file

 ./demoCA/certs                 - certificate output file

 ./demoCA/.rnd                  - CA random seed information

ENVIRONMENT VARIABLES

OPENSSL_CONF reflects the location of master configuration file it can
be overridden by the -config command line option.

RESTRICTIONS

The text database index file is a critical part of the process and
if corrupted it can be difficult to fix. It is theoretically possible
to rebuild the index file from all the issued certificates and a current
CRL: however there is no option to do this.

V2 CRL features like delta CRLs are not currently supported.

Although several requests can be input and handled at once it is only
possible to include one SPKAC or self signed certificate.

BUGS

The use of an in memory text database can cause problems when large
numbers of certificates are present because, as the name implies
the database has to be kept in memory.

The ca command really needs rewriting or the required functionality
exposed at either a command or interface level so a more friendly utility
(perl script or GUI) can handle things properly. The scripts CA.sh and
CA.pl help a little but not very much.

Any fields in a request that are not present in a policy are silently
deleted. This does not happen if the -preserveDN option is used. To
enforce the absence of the EMAIL field within the DN, as suggested by
RFCs, regardless the contents of the request’ subject the -noemailDN
option can be used. The behaviour should be more friendly and
configurable.

Cancelling some commands by refusing to certify a certificate can
create an empty file.

WARNINGS

The ca command is quirky and at times downright unfriendly.

The ca utility was originally meant as an example of how to do things
in a CA. It was not supposed to be used as a full blown CA itself:
nevertheless some people are using it for this purpose.

The ca command is effectively a single user command: no locking is
done on the various files and attempts to run more than one ca command
on the same database can have unpredictable results.

The copy_extensions option should be used with caution. If care is
not taken then it can be a security risk. For example if a certificate
request contains a basicConstraints extension with CA:TRUE and the
copy_extensions value is set to copyall and the user does not spot
this when the certificate is displayed then this will hand the requestor
a valid CA certificate.

This situation can be avoided by setting copy_extensions to copy
and including basicConstraints with CA:FALSE in the configuration file.
Then if the request contains a basicConstraints extension it will be
ignored.

It is advisable to also include values for other extensions such
as keyUsage to prevent a request supplying its own values.

Additional restrictions can be placed on the CA certificate itself.
For example if the CA certificate has:

basicConstraints = CA:TRUE, pathlen:0

then even if a certificate is issued with CA:TRUE it will not be valid.

Index

NAME
SYNOPSIS
DESCRIPTION
CA OPTIONS
CRL OPTIONS
CONFIGURATION FILE OPTIONS
POLICY FORMAT
SPKAC FORMAT
EXAMPLES
FILES
ENVIRONMENT VARIABLES
RESTRICTIONS
BUGS
WARNINGS
SEE ALSO

Posted in Uncategorized | No Comments »

Man page for i?

May 14, 2008 – 7:06 am

ID

Section: User Commands (1)
Updated: May 2006
Index
Return to Main Contents

NAME

id - print user identity

SYNOPSIS

[OPTION]… [USERNAME]

DESCRIPTION

Print information for USERNAME, or the current user.

-a: ignore, for compatibility with other versions
-Z, –context: print only the security context
-g, –group: print only the effective group ID
-G, –groups: print all group IDs
-n, –name: print a name instead of a number, for -ugG
-r, –real: print the real ID instead of the effective ID, with -ugG
-u, –user: print only the effective user ID
–help: display this help and exit
–version: output version information and exit

Without any OPTION, print some useful set of identified information.

AUTHOR

Written by Arnold Robbins and David MacKenzie.

REPORTING BUGS

Report bugs to <bug-coreutils@gnu.org>.

COPYRIGHT

Index

NAME
SYNOPSIS
DESCRIPTION
AUTHOR
REPORTING BUGS
COPYRIGHT
SEE ALSO

Posted in Uncategorized | No Comments »