summaryrefslogtreecommitdiffabout
path: root/doc/grecs_error.3
blob: fac92b1d2174c6591944971cf144122a453b8e53 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
.\" This file is part of grecs -*- nroff -*-
.\" Copyright (C) 2007, 2009-2012 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 GRECS_ERROR 3 "July 1, 2011" "GRECS" "Grecs User Reference"
.SH NAME
grecs_error, grecs_warning \- grecs error reporting functions
.SH SYNOPSIS
.nf
.B #include <grecs.h>
.sp
.BI "void grecs_error(grecs_locus_t " "*locus" ", int " "errnum"  ", "
.ti +17
.BI       "const char " "*format" ", ...);"
.br
.BI "void grecs_warning(grecs_locus_t " "*locus" ", int " "errnum" ", "
.ti +17
.BI       "const char " "*format" ", ...);"
.sp
.BI "void (*grecs_print_diag_fun)(grecs_locus_t " "*locus" ", "
.ti +17
.BI       "int " "err" ", int " "errnum" ", const char " "*msg" );
.sp
.B extern int grecs_error_count;
.SH DESCRIPTION
.BI grecs_error ()
is a error reporting function for \fBgrecs\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 grecs_error ()
increments the value of the
.BI grecs_error_count
global variable.
The
.BI grecs_warning ()
function works the same as
.BI grecs_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 grecs_error_count
variable.
.PP
Calling program can modify the behavior of both functions by setting
.BI grecs_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 \fBgrecs_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 grecs_locus_point {
     char *file;
     unsigned line;
     unsigned col;
};
typedef struct {
     struct grecs_locus_point beg;
     struct grecs_locus_point end;
} grecs_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 \fBgrecs_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+grecs@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/grecs>.
.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.