version 1.128, 2014/12/02 11:31:51 |
version 1.132, 2015/01/15 04:26:40 |
|
|
.\" $Id$ |
.\" $Id$ |
.\" |
.\" |
.\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv> |
.\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv> |
.\" Copyright (c) 2012, 2014 Ingo Schwarze <schwarze@openbsd.org> |
.\" Copyright (c) 2012, 2014, 2015 Ingo Schwarze <schwarze@openbsd.org> |
.\" |
.\" |
.\" Permission to use, copy, modify, and distribute this software for any |
.\" Permission to use, copy, modify, and distribute this software for any |
.\" purpose with or without fee is hereby granted, provided that the above |
.\" purpose with or without fee is hereby granted, provided that the above |
Line 85 Override the default operating system |
|
Line 85 Override the default operating system |
|
for the |
for the |
.Xr mdoc 7 |
.Xr mdoc 7 |
.Sq \&Os |
.Sq \&Os |
|
and for the |
|
.Xr man 7 |
|
.Sq \&TH |
macro. |
macro. |
.It Fl h |
.It Fl h |
Display only the SYNOPSIS lines. |
Display only the SYNOPSIS lines. |
Line 156 to be reported on the standard error output and to aff |
|
Line 159 to be reported on the standard error output and to aff |
|
The |
The |
.Ar level |
.Ar level |
can be |
can be |
.Cm warning , |
.Cm warning |
.Cm error , |
|
or |
or |
.Cm fatal . |
.Cm error ; |
The default is |
.Cm all |
.Fl W Ns Cm fatal ; |
|
.Fl W Ns Cm all |
|
is an alias for |
is an alias for |
.Fl W Ns Cm warning . |
.Cm warning . |
|
By default, |
|
.Nm |
|
is silent. |
See |
See |
.Sx EXIT STATUS |
.Sx EXIT STATUS |
and |
and |
Line 529 At least one warning occurred, but no error, and |
|
Line 532 At least one warning occurred, but no error, and |
|
.Fl W Ns Cm warning |
.Fl W Ns Cm warning |
was specified. |
was specified. |
.It 3 |
.It 3 |
At least one parsing error occurred, but no fatal error, and |
At least one parsing error occurred, and |
.Fl W Ns Cm error |
.Fl W Ns Cm error |
or |
or |
.Fl W Ns Cm warning |
.Fl W Ns Cm warning |
was specified. |
was specified. |
.It 4 |
|
A fatal parsing error occurred. |
|
.It 5 |
.It 5 |
Invalid command line arguments were specified. |
Invalid command line arguments were specified. |
No input files have been read. |
No input files have been read. |
.It 6 |
.It 6 |
An operating system error occurred, for example memory exhaustion or an |
An operating system error occurred, for example exhaustion |
error accessing input files. |
of memory, file descriptors, or process table entries. |
Such errors cause |
Such errors cause |
.Nm |
.Nm |
to exit at once, possibly in the middle of parsing or formatting a file. |
to exit at once, possibly in the middle of parsing or formatting a file. |
|
|
.Pp |
.Pp |
Message levels have the following meanings: |
Message levels have the following meanings: |
.Bl -tag -width "warning" |
.Bl -tag -width "warning" |
.It Cm syserr |
|
Opening or reading an input file failed, so the parser cannot |
|
even be started and no output is produced from that input file. |
|
.It Cm fatal |
|
The parser is unable to parse a given input file at all. |
|
No formatted output is produced from that input file. |
|
.It Cm error |
.It Cm error |
An input file contains syntax that cannot be safely interpreted, |
An input file contains syntax that cannot be safely interpreted, |
either because it is invalid or because |
either because it is invalid or because |
Line 616 the parser is able to continue, and the error does not |
|
Line 611 the parser is able to continue, and the error does not |
|
generation of formatted output, but typically, preparing that |
generation of formatted output, but typically, preparing that |
output involves information loss, broken document structure |
output involves information loss, broken document structure |
or unintended formatting. |
or unintended formatting. |
|
.Pp |
|
Non-existent or unreadable input files are also reported on the |
|
.Cm error |
|
level. |
|
In that case, the parser cannot even be started and no output |
|
is produced from those input files. |
.It Cm warning |
.It Cm warning |
An input file uses obsolete, discouraged or non-portable syntax. |
An input file uses obsolete, discouraged or non-portable syntax. |
All the same, the meaning of the input is unambiguous and a correct |
All the same, the meaning of the input is unambiguous and a correct |
|
|
.Cm warning |
.Cm warning |
and |
and |
.Cm error |
.Cm error |
levels are hidden unless their level, or a lower level, is requested using a |
levels except those about non-existent or unreadable input files |
|
are hidden unless their level, or a lower level, is requested using a |
.Fl W |
.Fl W |
option or |
option or |
.Fl T Ns Cm lint |
.Fl T Ns Cm lint |
Line 1266 keeps the code more readable. |
|
Line 1268 keeps the code more readable. |
|
.It "ignore data in cell" |
.It "ignore data in cell" |
.It "data block still open" |
.It "data block still open" |
.It "ignoring extra data cells" |
.It "ignoring extra data cells" |
|
.It "ignoring macro in table" |
.El |
.El |
.Ss "Errors related to roff, mdoc, and man code" |
.Ss "Errors related to roff, mdoc, and man code" |
.Bl -ohang |
.Bl -ohang |
|
.It Sy "input too large" |
|
.Pq mdoc , man |
|
Currently, |
|
.Nm |
|
cannot handle input files larger than its arbitrary size limit |
|
of 2^31 bytes (2 Gigabytes). |
|
Since useful manuals are always small, this is not a problem in practice. |
|
Parsing is aborted as soon as the condition is detected. |
.It Sy "input stack limit exceeded, infinite loop?" |
.It Sy "input stack limit exceeded, infinite loop?" |
.Pq roff |
.Pq roff |
Explicit recursion limits are implemented for the following features, |
Explicit recursion limits are implemented for the following features, |
|
|
.Ic \&gsize |
.Ic \&gsize |
statement has a non-numeric or negative argument or no argument at all. |
statement has a non-numeric or negative argument or no argument at all. |
The invalid request or statement is ignored. |
The invalid request or statement is ignored. |
|
.It Sy "NOT IMPLEMENTED: .so with absolute path or \(dq..\(dq" |
|
.Pq roff |
|
For security reasons, |
|
.Nm |
|
allows |
|
.Ic \&so |
|
file inclusion requests only with relative paths |
|
and only without ascending to any parent directory. |
|
By requesting the inclusion of a sensitive file, a malicious document |
|
might otherwise trick a privileged user into inadvertently displaying |
|
the file on the screen, revealing the file content to bystanders. |
|
.Nm |
|
only shows the path as it appears behind |
|
.Ic \&so . |
|
.It Sy ".so request failed" |
|
.Pq roff |
|
Servicing a |
|
.Ic \&so |
|
request requires reading an external file, but the file could not be |
|
opened. |
|
.Nm |
|
only shows the path as it appears behind |
|
.Ic \&so . |
.It Sy "skipping all arguments" |
.It Sy "skipping all arguments" |
.Pq mdoc , man , eqn , roff |
.Pq mdoc , man , eqn , roff |
An |
An |
Line 1495 macro is invoked with more than one argument, or a req |
|
Line 1529 macro is invoked with more than one argument, or a req |
|
.Ic \&de |
.Ic \&de |
family is invoked with more than two arguments. |
family is invoked with more than two arguments. |
The excess arguments are ignored. |
The excess arguments are ignored. |
.El |
|
.Ss FATAL errors |
|
.Bl -ohang |
|
.It Sy "input too large" |
|
.Pq mdoc , man |
|
Currently, |
|
.Nm |
|
cannot handle input files larger than its arbitrary size limit |
|
of 2^31 bytes (2 Gigabytes). |
|
Since useful manuals are always small, this is not a problem in practice. |
|
Parsing is aborted as soon as the condition is detected. |
|
.It Sy "NOT IMPLEMENTED: .so with absolute path or \(dq..\(dq" |
|
.Pq roff |
|
For security reasons, |
|
.Nm |
|
allows |
|
.Ic \&so |
|
file inclusion requests only with relative paths |
|
and only without ascending to any parent directory. |
|
By requesting the inclusion of a sensitive file, a malicious document |
|
might otherwise trick a privileged user into inadvertently displaying |
|
the file on the screen, revealing the file content to bystanders. |
|
The parser exits immediately. |
|
.It Sy ".so request failed" |
|
.Pq roff |
|
Servicing a |
|
.Ic \&so |
|
request requires reading an external file. |
|
While trying to do so, an |
|
.Xr open 2 , |
|
.Xr stat 2 , |
|
or |
|
.Xr read 2 |
|
system call failed. |
|
The parser exits immediately. |
|
Before showing this message, |
|
.Nm |
|
always shows another message explaining why the system call failed. |
|
.El |
.El |
.Sh COMPATIBILITY |
.Sh COMPATIBILITY |
This section summarises |
This section summarises |