aboutsummaryrefslogtreecommitdiff
path: root/doc/argot_error.3
diff options
context:
space:
mode:
Diffstat (limited to 'doc/argot_error.3')
-rw-r--r--doc/argot_error.3184
1 files changed, 184 insertions, 0 deletions
diff --git a/doc/argot_error.3 b/doc/argot_error.3
new file mode 100644
index 0000000..ab623dc
--- /dev/null
+++ b/doc/argot_error.3
@@ -0,0 +1,184 @@
+.\" This file is part of argot -*- nroff -*-
+.\" Copyright (C) 2007-2016 Sergey Poznyakoff
+.\"
+.\" Grecs is free software; you can redistribute it and/or modify
+.\" it under the terms of the GNU General Public License as published by
+.\" the Free Software Foundation; either version 3, or (at your option)
+.\" any later version.
+.\"
+.\" Grecs is distributed in the hope that it will be useful,
+.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+.\" GNU General Public License for more details.
+.\"
+.\" You should have received a copy of the GNU General Public License
+.\" along with Grecs. If not, see <http://www.gnu.org/licenses/>.
+.\"
+.TH ARGOT_ERROR 3 "July 1, 2011" "ARGOT" "Grecs User Reference"
+.SH NAME
+argot_error, argot_warning \- argot error reporting functions
+.SH SYNOPSIS
+.nf
+.B #include <argot.h>
+.sp
+.BI "void argot_error(argot_locus_t " "*locus" ", int " "errnum" ", "
+.ti +17
+.BI "const char " "*format" ", ...);"
+.br
+.BI "void argot_warning(argot_locus_t " "*locus" ", int " "errnum" ", "
+.ti +17
+.BI "const char " "*format" ", ...);"
+.sp
+.BI "void (*argot_print_diag_fun)(argot_locus_t " "*locus" ", "
+.ti +17
+.BI "int " "err" ", int " "errnum" ", const char " "*msg" );
+.sp
+.B extern int argot_error_count;
+.SH DESCRIPTION
+.BI argot_error ()
+is a error reporting function for \fBargot\fR library. It flushes
+stdout, and outputs to stderr the file name and line number, as
+supplied by the
+.BI locus
+argument, a colon and a space, the message specified by the
+.BR printf (3)-style
+format string \fIformat\fR, and, if \fIerrnum\fR is non-zero, a second
+colon and a space followed by the string given by
+.BI perror (errnum).
+Any arguments required for format should follow \fIformat\fR in the
+argument list. The output is terminated by a newline character.
+.PP
+If \fIlocus\fR is \fBNULL\fR, it is ignored and no file location is
+printed.
+.PP
+Each call to
+.BI argot_error ()
+increments the value of the
+.BI argot_error_count
+global variable.
+The
+.BI argot_warning ()
+function works the same as
+.BI argot_error (),
+except that it outputs, before the formatted message and after the
+file location, the word \fBwarning\fR, followed by a semicolon
+and a space character. It does not modify the
+.BI argot_error_count
+variable.
+.PP
+Calling program can modify the behavior of both functions by setting
+.BI argot_print_diag_fun
+to the address of a custom error-reporting function. This function is
+called with the following arguments:
+.TP
+.I locus
+Location in the file where the error or warning condition is
+encountered. Can be \fBNULL\fR if the condition occurred outside of
+input file context.
+.TP
+.I err
+This argument is \fB1\fR, if the function is called to report an error
+condition and \fB0\fR otherwise (i.e. a warning).
+.TP
+.I errnum
+System error code, or \fB0\fR, if no system error occurred.
+.TP
+.I msg
+Formatted message.
+.PP
+The \fBargot_locus_t\fR structure consists of two \fBpoints\fR, each
+point describing the beginning and the end of the input fragment in
+question:
+.sp
+.nf
+.in +5
+struct argot_locus_point {
+ char *file;
+ unsigned line;
+ unsigned col;
+};
+typedef struct {
+ struct argot_locus_point beg;
+ struct argot_locus_point end;
+} argot_locus_t;
+.in
+.fi
+.PP
+The \fBfile\fR member points to the file name, and the \fBline\fR
+member contains the input line number and the \fBcol\fR member
+contains the column number. Both lines and columns are numbered from
+1.
+.PP
+On output, the \fBargot_locus_t\fR structure is formatted as follows:
+.sp
+.nf
+.in +5
+\fBBEGFILE\fR:\fBBEGLINE\fR.\fBBEGCOL\fR\-\fBENDFILE\fR:\fBENDLINE\fR.\fBENDCOL\fR
+.in
+.fi
+.PP
+If \fBBEGFILE\fR equals \fBENDFILE\fR in the sense of
+.BR strcmp (3),
+then the output is contracted to:
+.sp
+.nf
+.in +5
+\fBFILE\fR:\fBBEGLINE\fR.\fBBEGCOL\fR\-\fBENDLINE\fR.\fBENDCOL\fR
+.in
+.fi
+.PP
+Furthermore, if \fBBEGLINE\fR equals \fBENDLINE\fR, then the format
+is:
+.sp
+.nf
+.in +5
+\fBFILE\fR:\fBLINE\fR.\fBBEGCOL\fR\-\fBENDCOL\fR
+.in
+.fi
+.PP
+Finally, if \fBBEGCOL\fR\ equals \fBENDCOL\fR, the output is
+simplified to
+.sp
+.nf
+.in +5
+\fBFILE\fR:\fBLINE\fR.\fBCOL\fR
+.in
+.fi
+.PP
+If \fBbeg.col\fR is \fB0\fR, then only the \fBbeg\fR part is
+formatted:
+.sp
+.nf
+.in +5
+\fBFILE\fR:\fBLINE\fR
+.in
+.fi
+.SH RETURN VALUE
+None.
+.SH "SEE ALSO"
+.BR errno (3)
+.SH AUTHORS
+Sergey Poznyakoff
+.SH "BUG REPORTS"
+Report bugs to <gray+argot@gnu.org.ua>.
+.SH COLOPHON
+The \fBGrecs\fR library is constantly changing, so this manual page
+may be incorrect or out-of-date. For the latest copy of \fBGrecs\fR
+documentation, visit <http://www.gnu.org.ua/software/argot>.
+.SH COPYRIGHT
+Copyright \(co 2011 Sergey Poznyakoff
+.br
+.na
+License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
+.br
+.ad
+This is free software: you are free to change and redistribute it.
+There is NO WARRANTY, to the extent permitted by law.
+.\" Local variables:
+.\" eval: (add-hook 'write-file-hooks 'time-stamp)
+.\" time-stamp-start: ".TH [A-Z_][A-Z0-9_]* [0-9] \""
+.\" time-stamp-format: "%:B %:d, %:y"
+.\" time-stamp-end: "\""
+.\" time-stamp-line-limit: 20
+.\" end:
+

Return to:

Send suggestions and report system problems to the System administrator.