aboutsummaryrefslogtreecommitdiff
path: root/doc/grecs_error.3
blob: d747d9ac963f41bcfec282aa7b24ff8a5c482c4d (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
.\" This file is part of grecs -*- nroff -*-
.\" Copyright (C) 2007, 2009-2011 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/>.
.\" This file is part of SLB. 
.\" Copyright (C) 2011 Sergey Poznyakoff
.\"
.TH GRECS_ERROR 3 "May 4, 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 is defined as:
.sp
.nf
.in +5
typedef struct {
     char *file;
     int line;
} 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.
.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.