Reduce memory and time consumption on certain malformed input files

[mandoc.git] / mandoc.3

diff --git a/mandoc.3 b/mandoc.3
index 2ee6eae181d3ebcb39409dcdece29be7e8f27c40..f05fdac997bf15eac5439096a5bb67a594d5d591 100644 (file)
--- a/mandoc.3
+++ b/mandoc.3
@@ -1,4 +1,4 @@
-.\"    $Id: mandoc.3,v 1.26 2014/09/03 23:21:47 schwarze Exp $
+.\"    $Id: mandoc.3,v 1.29 2014/11/26 23:42:14 schwarze Exp $

 .\"
 .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
 .\" Copyright (c) 2010 Ingo Schwarze <schwarze@openbsd.org>
 .\"
 .\" Copyright (c) 2009, 2010, 2011 Kristaps Dzonsons <kristaps@bsd.lv>
 .\" Copyright (c) 2010 Ingo Schwarze <schwarze@openbsd.org>


@@ -15,7 +15,7 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"

-.Dd $Mdocdate: September 3 2014 $
+.Dd $Mdocdate: November 26 2014 $

 .Dt MANDOC 3
 .Os
 .Sh NAME
 .Dt MANDOC 3
 .Os
 .Sh NAME


@@ -52,6 +52,7 @@
 .Fa "int options"
 .Fa "enum mandoclevel wlevel"
 .Fa "mandocmsg mmsg"
 .Fa "int options"
 .Fa "enum mandoclevel wlevel"
 .Fa "mandocmsg mmsg"

+.Fa "const struct mchars *mchars"

 .Fa "char *defos"
 .Fc
 .Ft void
 .Fa "char *defos"
 .Fc
 .Ft void


@@ -80,7 +81,6 @@
 .Fa "struct mparse *parse"
 .Fa "int *fd"
 .Fa "const char *fname"
 .Fa "struct mparse *parse"
 .Fa "int *fd"
 .Fa "const char *fname"

-.Fa "pid_t *child_pid"

 .Fc
 .Ft "enum mandoclevel"
 .Fo mparse_readfd
 .Fc
 .Ft "enum mandoclevel"
 .Fo mparse_readfd


@@ -110,7 +110,6 @@
 .Ft "enum mandoclevel"
 .Fo mparse_wait
 .Fa "struct mparse *parse"
 .Ft "enum mandoclevel"
 .Fo mparse_wait
 .Fa "struct mparse *parse"

-.Fa "pid_t child_pid"

 .Fc
 .In sys/types.h
 .In mandoc.h
 .Fc
 .In sys/types.h
 .In mandoc.h


@@ -173,6 +172,8 @@ The following describes a general parse sequence:
 .Bl -enum
 .It
 initiate a parsing sequence with
 .Bl -enum
 .It
 initiate a parsing sequence with

+.Xr mchars_alloc 3
+and

 .Fn mparse_alloc ;
 .It
 parse files or file descriptors with
 .Fn mparse_alloc ;
 .It
 parse files or file descriptors with


@@ -187,7 +188,9 @@ or
 .Fn man_node ;
 .It
 free all allocated memory with
 .Fn man_node ;
 .It
 free all allocated memory with

-.Fn mparse_free ,
+.Fn mparse_free
+and
+.Xr mchars_free 3 ,

 or invoke
 .Fn mparse_reset
 and parse new files.
 or invoke
 .Fn mparse_reset
 and parse new files.


@@ -208,6 +211,12 @@ A fatal error, error, or warning message during parsing.
 A classification of an
 .Vt "enum mandocerr"
 as regards system operation.
 A classification of an
 .Vt "enum mandocerr"
 as regards system operation.

+.It Vt "struct mchars"
+An opaque pointer to a a character table.
+Created with
+.Xr mchars_alloc 3
+and freed with
+.Xr mchars_free 3 .

 .It Vt "struct mparse"
 An opaque pointer to a running parse sequence.
 Created with
 .It Vt "struct mparse"
 An opaque pointer to a running parse sequence.
 Created with


@@ -332,6 +341,9 @@ A callback function to handle errors and warnings.
 See
 .Pa main.c
 for an example.
 See
 .Pa main.c
 for an example.

+.It Ar mchars
+An opaque pointer to a a character table obtained from
+.Xr mchars_alloc 3 .

 .It Ar defos
 A default string for the
 .Xr mdoc 7
 .It Ar defos
 A default string for the
 .Xr mdoc 7


@@ -384,20 +396,18 @@ open with
 .Xr gunzip 1 ;
 otherwise, with
 .Xr open 2 .
 .Xr gunzip 1 ;
 otherwise, with
 .Xr open 2 .

+If
+.Xr open 2
+fails, append
+.Pa .gz
+and try with
+.Xr gunzip 1 .

 Return a file descriptor open for reading in
 .Fa fd ,
 or -1 on failure.
 It can be passed to
 .Fn mparse_readfd
 or used directly.
 Return a file descriptor open for reading in
 .Fa fd ,
 or -1 on failure.
 It can be passed to
 .Fn mparse_readfd
 or used directly.

-If applicable, return the
-.Xr gunzip 1
-child process ID in
-.Fa child_pid ,
-or otherwise 0.
-If non-zero, it should be passed to
-.Fn mparse_wait
-after completing the parse sequence.

 Declared in
 .In mandoc.h ,
 implemented in
 Declared in
 .In mandoc.h ,
 implemented in


@@ -406,14 +416,18 @@ implemented in
 Parse a file or file descriptor.
 If
 .Va fd
 Parse a file or file descriptor.
 If
 .Va fd

-is -1,
+is -1, open

 .Va fname
 .Va fname

-is opened for reading.
+with
+.Fn mparse_open .

 Otherwise,
 .Va fname
 is assumed to be the name associated with
 .Va fd .
 Otherwise,
 .Va fname
 is assumed to be the name associated with
 .Va fd .

-This may be called multiple times with different parameters; however,
+Calls
+.Fn mparse_wait
+before returning.
+This function may be called multiple times with different parameters; however,

 .Fn mparse_reset
 should be invoked between parses.
 Declared in
 .Fn mparse_reset
 should be invoked between parses.
 Declared in


@@ -457,11 +471,12 @@ implemented in
 .It Fn mparse_wait
 Bury a
 .Xr gunzip 1
 .It Fn mparse_wait
 Bury a
 .Xr gunzip 1

-child process
-.Fa child_pid
-that was spawned with
+child process that was spawned with

 .Fn mparse_open .
 To be called after the parse sequence is complete.
 .Fn mparse_open .
 To be called after the parse sequence is complete.

+Not needed after
+.Fn mparse_readfd ,
+but does no harm in that case, either.

 Returns
 .Dv MANDOCLEVEL_OK
 on success and
 Returns
 .Dv MANDOCLEVEL_OK
 on success and