diff options
Diffstat (limited to 'doc/argot_error.3')
-rw-r--r-- | doc/argot_error.3 | 184 |
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: + |