mirror of https://gerrit.osmocom.org/asn1c
man page formatting
This commit is contained in:
parent
db361a6b08
commit
e687e75833
127
asn1c/asn1c.1
127
asn1c/asn1c.1
|
@ -1,138 +1,119 @@
|
|||
.TH asn1c 1 "\*(Dt" "ASN.1 Compiler" "ASN.1 Compiler"
|
||||
.TH asn1c 1 "2014-10-23" "ASN.1 Compiler"
|
||||
.if n .ad l \" Turn off justifications
|
||||
.nh \" Turn off hyphenation; can damage formatting in technical documents.
|
||||
.SH NAME
|
||||
asn1c \- ASN.1 Compiler
|
||||
asn1c \(em the ASN.1 Compiler
|
||||
.SH SYNOPSIS
|
||||
asn1c [\fB\-E\fR [\fB-F\fR] | \fB\-P\fR | \fB\-R\fR]
|
||||
[\fB\-S\fR\fIdir\fR] [\fB-X\fR]
|
||||
[\fB\-W\fR\fIdebug-\fR...] [\fB\-f\fR\fIoption\fR] [\fB\-gen-\fR\fIoption\fR] [\fB\-pdu=\fR{\fBall\fR|\fBauto\fR|\fIType\fR}\fR]
|
||||
[\fB\-print-\fR\fIoption\fR]
|
||||
\fIinfile\fR...
|
||||
\fIinput-filenames\fR...
|
||||
.SH DESCRIPTION
|
||||
asn1c compiles ASN.1 specifications into a set of
|
||||
target language (C/C++) encoders and decoders for BER, DER, PER, XER
|
||||
and other encoding rules.
|
||||
.SH OPTIONS
|
||||
.TP
|
||||
\fIOverall Options\fR
|
||||
\fB\-E \-F \-P \-R\fR
|
||||
.BI "\-S " directory
|
||||
\fB\-X
|
||||
.TP
|
||||
\fIWarning Options\fR
|
||||
.br
|
||||
\fB\-Werror \-Wdebug-lexer \-Wdebug-fixer \-Wdebug-compiler\fR
|
||||
.TP
|
||||
\fILanguage Options\fR
|
||||
.br
|
||||
\fB\-fbless-SIZE \-fcompound-names \-findirect-choice
|
||||
.BI "\-fknown-extern-type="<name>
|
||||
\fB\-fno-constraints \-fno-include-deps \-funnamed-unions \-fwide-types
|
||||
.TP
|
||||
\fICodecs Generation Options\fR
|
||||
.br
|
||||
.B \-gen-PER \-pdu=\fR{\fBall\fR|\fBauto\fR|\fIType\fR}
|
||||
.TP
|
||||
\fIOutput Options\fR
|
||||
.br
|
||||
.B \-print-constraints \-print-lines
|
||||
.SH OVERALL OPTIONS
|
||||
.TP
|
||||
.SS Stage Selection Options
|
||||
.TP 4
|
||||
.B \-E
|
||||
Stop after the parsing stage and print the reconstructed ASN.1
|
||||
specification code to the standard output.
|
||||
.TP
|
||||
Run the parsing stage only.
|
||||
Print the reconstructed ASN.1 text.
|
||||
.TP 4
|
||||
.B \-F
|
||||
Used together with \c
|
||||
Used together with
|
||||
.B \-E\c
|
||||
, instructs the compiler to stop after the ASN.1 syntax
|
||||
tree fixing stage and dump the reconstructed ASN.1 specification
|
||||
to the standard output.
|
||||
.TP
|
||||
.TP 4
|
||||
.B \-P
|
||||
Dump the compiled output to the standard output instead of creating the
|
||||
target language files on disk.
|
||||
.TP
|
||||
.TP 4
|
||||
.B \-R
|
||||
Restrict the compiler to generate only the ASN.1 tables,
|
||||
omitting the usual support code.
|
||||
.TP
|
||||
.TP 4
|
||||
\fB\-S\fR \fIdirectory\fR
|
||||
Use the specified directory with ASN.1 skeleton files.
|
||||
.TP
|
||||
.TP 4
|
||||
.B \-X
|
||||
Generate an XML DTD schema for the specified ASN.1 files.
|
||||
.SH WARNING OPTIONS
|
||||
.TP
|
||||
.SS Warning Options
|
||||
.TP 4
|
||||
.B \-Werror
|
||||
Treat warnings as errors; abort if any warning is produced.
|
||||
.TP
|
||||
.TP 4
|
||||
.B \-Wdebug-lexer
|
||||
Enable lexer debugging during the ASN.1 parsing stage.
|
||||
.TP
|
||||
.TP 4
|
||||
.B \-Wdebug-fixer
|
||||
Enable ASN.1 syntax tree fixer debugging during the fixing stage.
|
||||
.TP
|
||||
.TP 4
|
||||
.B \-Wdebug-compiler
|
||||
Enable debugging during the actual compile time.
|
||||
.SH LANGUAGE OPTIONS
|
||||
.TP
|
||||
.SS Language Options
|
||||
.TP 4
|
||||
.B \-fbless-SIZE
|
||||
Allow SIZE() constraint for INTEGER, ENUMERATED, and other types for which this
|
||||
constraint is normally prohibited by the standard. This is a violation of
|
||||
ASN.1 standard, and the compiler may fail to produce a meaningful code.
|
||||
.TP
|
||||
constraint is normally prohibited by the standard.
|
||||
This is a violation of ASN.1 standard, and the compiler may
|
||||
fail to\ produce a meaningful code.
|
||||
.TP 4
|
||||
.B \-fcompound-names
|
||||
Using this option prevents name collisions in the target source code
|
||||
by using complex names for target language structures. (Name collisions
|
||||
may occur if the ASN.1 module reuses the same identifiers in multiple
|
||||
contexts).
|
||||
.TP
|
||||
by using complex names for target language structures.
|
||||
(Name\ collisions may occur if the ASN.1 module reuses the same identifiers
|
||||
in multiple contexts).
|
||||
.TP 4
|
||||
.B \-findirect-choice
|
||||
When generating code for a CHOICE type, compile the CHOICE members as indirect
|
||||
pointers instead of declaring them inline. Consider using this option
|
||||
together with
|
||||
pointers instead of declaring them inline.
|
||||
Consider using this option together with
|
||||
.B \-fno-include-deps
|
||||
to prevent circular references.
|
||||
.TP
|
||||
.TP 4
|
||||
.BI "\-fknown-extern-type="<name>
|
||||
Pretend the specified type is known. The compiler will assume the target
|
||||
language source files for the given type have been provided manually.
|
||||
.TP
|
||||
Pretend the specified type is known.
|
||||
The compiler will assume the target language source files
|
||||
for the given type have been provided manually.
|
||||
.TP 4
|
||||
.B \-fno-constraints
|
||||
Do not generate ASN.1 subtype constraint checking code. This may make a shorter executable.
|
||||
.TP
|
||||
Do not generate ASN.1 subtype constraint checking code.
|
||||
This may make a shorter executable.
|
||||
.TP 4
|
||||
.B \-fno-include-deps
|
||||
Do not generate courtesy #include lines for non-critical type dependencies.
|
||||
Helps prevent namespace collisions.
|
||||
.TP
|
||||
.TP 4
|
||||
.B \-funnamed-unions
|
||||
Enable unnamed unions in the definitions of target language's structures.
|
||||
.TP
|
||||
.TP 4
|
||||
.B \-fwide-types
|
||||
Use the unbounded size data types (INTEGER_t, ENUMERATED_t, REAL_t) by default,
|
||||
instead of the native machine's data types (long, double).
|
||||
.SH CODECS GENERATION OPTIONS
|
||||
.TP
|
||||
.SS Codecs Generation Options
|
||||
.TP 4
|
||||
.B \-gen-PER
|
||||
Generate Packed Encoding Rules (PER) support code.
|
||||
.TP
|
||||
.TP 4
|
||||
.B \-pdu=\fR{\fBall\fR|\fBauto\fR|\fIType\fR}
|
||||
Create a PDU table for specified types, or discover Protocol Data Units
|
||||
automatically. In case of -pdu=\fBall\fR, all ASN.1 types defined in
|
||||
all modules will form a PDU table. In case of -pdu=\fBauto\fR, all types
|
||||
not referenced by any other type will form a PDU table.
|
||||
If \fIType\fR is an ASN.1 type identifier, it is added to a PDU table.
|
||||
The last form may be specified multiple times to add any number of PDUs.
|
||||
.SH OUTPUT OPTIONS
|
||||
.TP
|
||||
Create a PDU table for specified types, or discover Protocol Data Units automatically.
|
||||
In case of -pdu=\fBall\fR, all ASN.1 types defined in all modules will form a PDU table.
|
||||
In case of -pdu=\fBauto\fR, all types not referenced by any other type will form a PDU table.
|
||||
If\ \fIType\fR is an ASN.1 type identifier, it is added to a PDU table.
|
||||
The\ last form may be specified multiple times to add any number of PDUs.
|
||||
.SS Output Options
|
||||
.TP 4
|
||||
.B \-print-constraints
|
||||
When -EF are also specified, this option forces the compiler to explain
|
||||
its internal understanding of subtype constraints.
|
||||
.TP
|
||||
.TP 4
|
||||
.B \-print-lines
|
||||
Generate "-- #line" comments in \fB-E\fR output.
|
||||
.SH SEE ALSO
|
||||
.TP
|
||||
.TP 4
|
||||
\&\fIunber\fR\|(1), \&\fIenber\fR\|(1)
|
||||
.SH AUTHORS
|
||||
Lev Walkin <vlm@lionet.info>
|
||||
|
|
|
@ -1,49 +1,53 @@
|
|||
.de Vb
|
||||
.TH enber 1 "2014-10-23" "unber counterpart"
|
||||
.if n .ad l \" Turn off justifications
|
||||
.nh \" Turn off hyphenation; can damage formatting in technical documents.
|
||||
.de Vb \" Verbatim begin.
|
||||
.sp
|
||||
.in +4
|
||||
.ft CW
|
||||
.nf
|
||||
..
|
||||
.de Ve
|
||||
.de Ve \" Verbatim end.
|
||||
.ft R
|
||||
.in
|
||||
.fi
|
||||
.sp
|
||||
..
|
||||
.TH enber 1 "\*(Dt" "unber counterpart" "unber counterpart"
|
||||
.SH NAME
|
||||
enber \- Convert the unber XML output back into BER
|
||||
enber \(em Convert the unber XML output back into BER
|
||||
.SH SYNOPSIS
|
||||
enber [\fB-n\fR] [\fB-\fR] [\fIinfile\fR...]
|
||||
enber [\fB\-n\fR] [\fB\-\fR] [\fIinput-filenames\fR...]
|
||||
.SH DESCRIPTION
|
||||
enber convers the XML-formatted files produced by \fIunber\fR\|(1) back into the BER format.
|
||||
A single dash denotes the standard input.
|
||||
.SH OPTIONS
|
||||
.TP
|
||||
.TP 4
|
||||
\fB\-n\fR
|
||||
Disable input validation. By default, enber performs some basic validity checks
|
||||
Disable input validation.
|
||||
By default, enber performs some basic validity checks
|
||||
against XML input.
|
||||
.SH EXAMPLES
|
||||
Decode a BER sequence and immediately encode it back
|
||||
.Vb
|
||||
\& unber \fB-p\fR \fIfilename.ber\fR | enber \fB-\fR > \fIreconstructed.ber\fR
|
||||
unber \fB\-p\fR \fIfilename.ber\fR | enber \fB\-\fR > \fIreconstructed.ber\fR
|
||||
.Ve
|
||||
.SH FOOTNOTES
|
||||
This program does not attempt to perform full-fledged XML parsing. It is merely
|
||||
compatible with \fIunber\fR\|(1)'s output.
|
||||
This program does not attempt to perform full-fledged XML parsing.
|
||||
It is merely compatible with \fIunber\fR\|(1)'s output.
|
||||
In particular, XML style comments are not supported.
|
||||
A hash "\fB#\fR" or two dashes "\fB--\fR" following a whitespace is treated as a beginning of a comment line, which is ignored completely.
|
||||
Empty lines are ignored as well.
|
||||
.P
|
||||
The following example demostrates the use of comments:
|
||||
.Vb
|
||||
\& <C O="0" T="[1]" TL="2" V="2">
|
||||
\& <I O="2" T="[1]" TL="2" V="Indefinite">
|
||||
\& \fB--\fR </I O="4" T="[UNIVERSAL 0]" L="4">
|
||||
\& \fB#\fR Do not terminate:
|
||||
\& \fB#\fR the absence of end-of-content octets is intentional!
|
||||
\& </C O="6" T="[1]" L="6">
|
||||
<C O="0" T="[1]" TL="2" V="2">
|
||||
<I O="2" T="[1]" TL="2" V="Indefinite">
|
||||
\fB--\fR </I O="4" T="[UNIVERSAL 0]" L="4">
|
||||
\fB#\fR Do not terminate:
|
||||
\fB#\fR the absence of end-of-content octets is intentional!
|
||||
</C O="6" T="[1]" L="6">
|
||||
.Ve
|
||||
.SH SEE ALSO
|
||||
.TP
|
||||
\&\fIunber\fR\|(1), \&\fIasn1c\fR\|(1)
|
||||
\fIunber\fR\|(1), \&\fIasn1c\fR\|(1)
|
||||
.SH AUTHORS
|
||||
Lev Walkin <vlm@lionet.info>
|
||||
|
|
|
@ -1,18 +1,27 @@
|
|||
.de Vb
|
||||
.TH unber 1 "2014-10-23" "ASN.1 BER Decoder"
|
||||
.if n .ad l \" Turn off justifications
|
||||
.nh \" Turn off hyphenation; can damage formatting in technical documents.
|
||||
.de Vb \" Verbatim.
|
||||
.sp
|
||||
.ft CW
|
||||
.nf
|
||||
..
|
||||
.de Ve
|
||||
.de Vbi \" Verbatim, indented.
|
||||
.sp
|
||||
.ft CW
|
||||
.nf
|
||||
.in +4
|
||||
..
|
||||
.de Ve \" Verbatim end.
|
||||
.ft R
|
||||
.in
|
||||
.fi
|
||||
.sp
|
||||
..
|
||||
.TH unber 1 "\*(Dt" "ASN.1 BER Decoder" "ASN.1 BER Decoder"
|
||||
.SH NAME
|
||||
unber \- ASN.1 BER Decoder
|
||||
unber \(em the ASN.1 BER Decoder
|
||||
.SH SYNOPSIS
|
||||
unber [\fB-1\fR] [\fB-i\fRindent] [\fB-m\fR] [\fB-p\fR] [\fB\-s\fR\fIskip\fR] [\fB\-t\fR\fIhex-string\fR] [\fB-\fR] [\fIinfile\fR...]
|
||||
unber [\fB\-1\fR] [\fB\-i\fRindent] [\fB\-m\fR] [\fB\-p\fR] [\fB\-s\fR\fIskip\fR] [\fB\-t\fR\fIhex\-string\fR] [\fB\-\fR] [\fIinput-filenames\fR...]
|
||||
.SH DESCRIPTION
|
||||
unber presents the internal structure of BER-encoded files as human readable text.
|
||||
A single dash denotes the standard input.
|
||||
|
@ -26,14 +35,16 @@ This may be useful if the input contains garbage past the single BER sequence.
|
|||
By default, unber continues decoding until the end of file (input stream).
|
||||
.TP
|
||||
\fB\-i\fR \fIindent\fR
|
||||
Use the specified number of spaces for output indentation. Default is 4 spaces.
|
||||
Use the specified number of spaces for output indentation.
|
||||
Default is 4 spaces.
|
||||
.TP
|
||||
\fB\-m\fR
|
||||
Generate shorter output while still preserving BER encoding information.
|
||||
.TP
|
||||
\fB\-p\fR
|
||||
Do \fInot\fR attempt pretty-printing of known ASN.1 types (BOOLEAN, INTEGER, OBJECT IDENTIFIER, etc). By default, some ASN.1 types are converted into
|
||||
the text representation. This option is required for \&\fIenber\fR\|(1).
|
||||
Do \fInot\fR attempt pretty-printing of known ASN.1 types (BOOLEAN, INTEGER, OBJECT IDENTIFIER, etc).
|
||||
By default, some ASN.1 types are converted into the text representation.
|
||||
This option is required for \&\fIenber\fR\|(1).
|
||||
.TP
|
||||
\fB\-s\fR \fIskip\fR
|
||||
Ignore the first \fIskip\fR bytes in the input stream; useful for stripping off
|
||||
|
@ -41,14 +52,15 @@ lower level protocol framing data.
|
|||
.TP
|
||||
\fB\-t\fR \fIhex-string\fR
|
||||
Interpret the hex-string as a sequence of hexadecimal values representing
|
||||
the start of BER TLV encoding. Print the human readable explanation.
|
||||
the start of BER TLV encoding.
|
||||
Print the human readable explanation.
|
||||
.SH XML FORMAT
|
||||
unber dumps the output in the regular XML format which preserves most of the
|
||||
information from the underlying binary encoding.
|
||||
.P
|
||||
The XML opening tag format is as follows:
|
||||
.Vb
|
||||
\&<\fBtform\fR O="\fBoff\fR" T="\fBtag\fR" TL="\fBtl_len\fR" V="{Indefinite|\fBv_len\fR}" [A="\fBtype\fR"] [\fBF\fR]>
|
||||
<\fBtform\fR O="\fBoff\fR" T="\fBtag\fR" TL="\fBtl_len\fR" V="{Indefinite|\fBv_len\fR}" [A="\fBtype\fR"] [\fBF\fR]>
|
||||
.Ve
|
||||
Where:
|
||||
.TP
|
||||
|
@ -71,33 +83,34 @@ The length of the value (V, encoded by the L), may be "Indefinite".
|
|||
Likely name of the underlying ASN.1 type (for UNIVERSAL tags).
|
||||
.TP
|
||||
[\fBF\fR]
|
||||
Indicates that the value was reformatted (pretty-printed). This will never appear in the output produced using \fB-p\fR command line option.
|
||||
Indicates that the value was reformatted (pretty-printed).
|
||||
This will never appear in the output produced using \fB\-p\fR command line option.
|
||||
.P
|
||||
Sample XML output:
|
||||
.Vb
|
||||
\&<I O="0" T="[UNIVERSAL 16]" TL="2" V="Indefinite" A="SEQUENCE">
|
||||
\& <P O="2" T="[UNIVERSAL 19]" TL="2" V="2" A="PrintableString">US</P>
|
||||
\& <C O="6" T="[UNIVERSAL 16]" TL="2" V="6" A="SEQUENCE">
|
||||
\& <P O="8" T="[UNIVERSAL 2]" TL="2" V="4" A="INTEGER" F>832970823</P>
|
||||
\& </C O="14" T="[UNIVERSAL 16]" A="SEQUENCE" L="8">
|
||||
\&</I O="14" T="[UNIVERSAL 0]" TL="2" L="16">
|
||||
<I O="0" T="[UNIVERSAL 16]" TL="2" V="Indefinite" A="SEQUENCE">
|
||||
<P O="2" T="[UNIVERSAL 19]" TL="2" V="2" A="PrintableString">US</P>
|
||||
<C O="6" T="[UNIVERSAL 16]" TL="2" V="6" A="SEQUENCE">
|
||||
<P O="8" T="[UNIVERSAL 2]" TL="2" V="4" A="INTEGER" F>832970823</P>
|
||||
</C O="14" T="[UNIVERSAL 16]" A="SEQUENCE" L="8">
|
||||
</I O="14" T="[UNIVERSAL 0]" TL="2" L="16">
|
||||
.Ve
|
||||
.SH EXAMPLES
|
||||
Decode the given Tag/Length sequence specified in hexadecimal form:
|
||||
.Vb
|
||||
\& unber \fB-t\fR "\fIbf 20\fR"
|
||||
.Vbi
|
||||
unber \fB\-t\fR "\fIbf 20\fR"
|
||||
.Ve
|
||||
Decode the DER file using two-spaces indentation:
|
||||
.Vb
|
||||
\& unber \fB-i\fR \fI2\fR \fIfilename.der\fR
|
||||
.Vbi
|
||||
unber \fB\-i\fR \fI2\fR \fIfilename.der\fR
|
||||
.Ve
|
||||
Decode the binary stream taken from the standard input:
|
||||
.Vb
|
||||
\& cat \fI...\fR | unber \fB-\fR
|
||||
.Vbi
|
||||
cat \fIfilename.der\fR | unber \fB\-\fR
|
||||
.Ve
|
||||
Decode the binary stream and encode it back into an identical stream (see \&\fIenber\fR\|(1)):
|
||||
.Vb
|
||||
\& cat \fI...\fR | unber \fB-p\fR \fB-\fR | enber \fB-\fR > \fIfilename.ber\fR
|
||||
.Vbi
|
||||
cat \fIfilename.der\fR | unber \fB\-p\fR \fB\-\fR | enber \fB\-\fR > \fIfilename.ber\fR
|
||||
.Ve
|
||||
.SH FOOTNOTES
|
||||
The constructed XML output is not necessarily well-formed.
|
||||
|
@ -107,9 +120,9 @@ terminated with the end-of-content octets, will cause the terminating \fB</I>\fR
|
|||
XML tag to disappear.
|
||||
Thus, invalid BER framing directly causes invalid XML output.
|
||||
.P
|
||||
The \&\fIenber\fR\|(1) utility understands such XML correctly.
|
||||
The \fIenber\fR\|(1) utility understands such XML correctly.
|
||||
.SH SEE ALSO
|
||||
.TP
|
||||
\&\fIenber\fR\|(1), \&\fIasn1c\fR\|(1)
|
||||
\fIenber\fR\|(1), \fIasn1c\fR\|(1)
|
||||
.SH AUTHORS
|
||||
Lev Walkin <vlm@lionet.info>
|
||||
|
|
Loading…
Reference in New Issue