Reduce memory and time consumption on certain malformed input files

[mandoc.git] / mandoc.3

diff --git a/mandoc.3 b/mandoc.3
index 8f76ad21fff4e65201c512e1fb8e52ea70b02841..f05fdac997bf15eac5439096a5bb67a594d5d591 100644 (file)
--- a/mandoc.3
+++ b/mandoc.3
@@ -1,4 +1,4 @@
-.\"    $Id: mandoc.3,v 1.25 2014/08/05 05:48:56 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>
@@ -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.
 .\"
-.Dd $Mdocdate: August 5 2014 $
+.Dd $Mdocdate: November 26 2014 $
 .Dt MANDOC 3
 .Os
 .Sh NAME
@@ -31,11 +31,13 @@
 .Nm mparse_free ,
 .Nm mparse_getkeep ,
 .Nm mparse_keep ,
+.Nm mparse_open ,
 .Nm mparse_readfd ,
 .Nm mparse_reset ,
 .Nm mparse_result ,
 .Nm mparse_strerror ,
 .Nm mparse_strlevel
+.Nm mparse_wait ,
 .Nd mandoc macro compiler library
 .Sh LIBRARY
 .Lb libmandoc
@@ -50,6 +52,7 @@
 .Fa "int options"
 .Fa "enum mandoclevel wlevel"
 .Fa "mandocmsg mmsg"
+.Fa "const struct mchars *mchars"
 .Fa "char *defos"
 .Fc
 .Ft void
@@ -74,6 +77,12 @@
 .Fa "struct mparse *parse"
 .Fc
 .Ft "enum mandoclevel"
+.Fo mparse_open
+.Fa "struct mparse *parse"
+.Fa "int *fd"
+.Fa "const char *fname"
+.Fc
+.Ft "enum mandoclevel"
 .Fo mparse_readfd
 .Fa "struct mparse *parse"
 .Fa "int fd"
@@ -98,6 +107,10 @@
 .Fo mparse_strlevel
 .Fa "enum mandoclevel"
 .Fc
+.Ft "enum mandoclevel"
+.Fo mparse_wait
+.Fa "struct mparse *parse"
+.Fc
 .In sys/types.h
 .In mandoc.h
 .In mdoc.h
@@ -159,6 +172,8 @@ The following describes a general parse sequence:
 .Bl -enum
 .It
 initiate a parsing sequence with
+.Xr mchars_alloc 3
+and
 .Fn mparse_alloc ;
 .It
 parse files or file descriptors with
@@ -173,7 +188,9 @@ or
 .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.
@@ -194,6 +211,12 @@ A fatal error, error, or warning message during parsing.
 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
@@ -318,6 +341,9 @@ A callback function to handle errors and warnings.
 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
@@ -361,18 +387,47 @@ Declared in
 .In mandoc.h ,
 implemented in
 .Pa read.c .
+.It Fn mparse_open
+If the
+.Fa fname
+ends in
+.Pa .gz ,
+open with
+.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.
+Declared in
+.In mandoc.h ,
+implemented in
+.Pa read.c .
 .It Fn mparse_readfd
 Parse a file or file descriptor.
 If
 .Va fd
-is -1,
+is -1, open
 .Va fname
-is opened for reading.
+with
+.Fn mparse_open .
 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
@@ -413,6 +468,28 @@ Declared in
 .In mandoc.h ,
 implemented in
 .Pa read.c .
+.It Fn mparse_wait
+Bury a
+.Xr gunzip 1
+child process that was spawned with
+.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
+.Dv MANDOCLEVEL_SYSERR
+on failure, that is, when
+.Xr wait 2
+fails, or when
+.Xr gunzip 1
+died from a signal or exited with non-zero status.
+Declared in
+.In mandoc.h ,
+implemented in
+.Pa read.c .
 .El
 .Ss Variables
 .Bl -ohang