File: shhmsg.txt

package info (click to toggle)
shhmsg 1.4.1-1
  • links: PTS
  • area: main
  • in suites: woody
  • size: 148 kB
  • ctags: 78
  • sloc: ansic: 319; makefile: 134; sh: 10
file content (316 lines) | stat: -rw-r--r-- 9,532 bytes parent folder | download | duplicates (5)
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
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
                      [Thanks to Louis W.  Erickson for contributing this file]
------------------------------------------------------------------------------

INTRODUCTION:

This is a quick overview of all the functions included in this
library, with all their inputs and return values listed and defined in
one place, so you don't need to refer to the header and/or the sources
as much.

------------------------------------------------------------------------------

USING THE LIBRARY:

Before calling the library, make and install it.  Include shhmsg.h in
every module that will make calls to the library.  You probably also
want to set the application name before using the output functions.
See msgSetName, below.

link with the library like so:

    cc foo.c -o foo -lshhmsg

or, include it directly, if it's not in the system path:

    cc bar.c -o bar libshhmsg.a

------------------------------------------------------------------------------

A word about streams:

This library uses three file streams.  One is used for error messages,
one for informational messages, and one for verbose messages.  These
normally default to stderr, stdout, and stderr, respectively.  They
can, however be easily changed, by calling the stream management
functions, and set to any stream the caller likes, including stdout,
stderr, opened pipes, open files, an open to /dev/console, whatever.
The documents refer to them as the "error stream", the "message
stream", and the "verbose stream".  These names have nothing to do
with what stream they may be actually pointing to.

------------------------------------------------------------------------------

Controlling the library:

There is one initialization function, and several control functions.

------------------------------------------------------------------------------

FUNCTION: void msgSetName(const char *s);

DESCRIPTION:

Call msgSetName with the name of the application as the parameter.
Note that argv[0] is a perfectly valid (perhaps encouraged) place to
get this, and all preceding path information to the program name will
be stripped off before it is displayed.

SAMPLE:

    msgSetName(argv[0]);

==========================

FUNCTION: void msgSetQuiet(int onoff);

DESCRIPTION:

This function sets an internal flag with whatever you pass in.  It
controls the behavior of msgMessage (see below).  A non-zero will
silence msgMessage, and a zero value will make it produce output.

You can use the constants MSG_QUIET and MSG_OUTPUT, defined in the
header file, if you want, or 0 or 1, or whatever.

SAMPLE:

    msgSetQuiet(MSG_OFF);

==========================

FUNCTION: void msgSetVerbose(int level);

DESCRIPTION:

This function controls what calls to the msgVerbose function occur.
If the first parameter to that function is greater than the currently
set level, the function produces output.  If you call this function
from code, the value of what you pass becomes the currently set level.

If you pass MSG_VERBOSE_NONE, all calls to msgVerbose will produce no
output, quieting your program a great deal.

The default value is MSG_VERBOSE_DEFAULT.  It has special behavior.
If you do not call msgSetVerbose, or you call it with
MSG_VERBOSE_DEFAULT, then the current verbosity level is read from an
environmental variable.  The variable is based on the name set with
msgSetName.  The program takes the first ten bytes, forces everything
to upper case, and appends "_LEVEL" to it to make the name.  You can
set this variable (export it if you're using bash or sh) and then the
program will produce that much output.  Notice that this is a numeric
value of -1, so all prompts will be suppressed if there is none set.
Spaces in the name are NOT affected, and must be part of the
environmental variable's name.

NOTE: Because the special values used to control the extended behavior
are negative numbers, the user of negative levels is not recommended.
Levels from 0 to MAX_INT should be ok.

SAMPLE:

    msgSetVerbose(2);

-or-

    msgSetVerbose(MSG_VERBOSE_DEFAULT);

==========================

FUNCTION: void msgSetShowNameAlways(int onoff)

DESCRIPTION:

Some of the functions in the library prepend the name of the
application set with msgSetName to the strings they output.  Some
functions do this SOMETIMES.  Calling this with a non-zero parameter
will make ALL of the functions in the library do this.  Calling it
with a 0 will return the default behavior.  When using this as a debug
engine, having the name prepended is useful.  The default value is
"off".

There are predefined constants, MSG_ON and MSG_OFF in the header file,
if you want to use them.

SAMPLE:

    msgSetShowNameAlways(MSG_ON);

==========================

FUNCTION: FILE *msgSetErrorStream(FILE *f)

DESCRIPTION:

This function sets the file stream that the error functions (msgError,
msgFatal, msgPerror, and msgFatalPerror) output to.  The return value
is the old stream that was in use (to be closed, if needed).  No
opening or closing of these streams is performed by the library.

Passing in NULL will return the library to it's default value (stderr)
and return you the steam currently in use.

SAMPLE:

    FILE *fl;
    fl = fopen("/dev/console", "w");
    msgSetErrorStream(fl);
    ...
    fclose(msgSetErrorStream(NULL));

==========================

FUNCTION: FILE *msgSetMessageStream(FILE *f);

DESCRIPTION:

This function controls the stream that msgMessage outputs to.  It
normally uses stdout, but this can be changed to anything you want.
The library does no opening or closing of this stream, the application
must do this.

Passing in a NULL returns the library to the default of stdout, and
returns the current stream in use.

SAMPLE:

    FILE *fl;
    fl = fopen("output", "w");
    msgSetMessageStream(fl);
    ...
    fclose(msgSetMessageStream(NULL));

==========================

FUNCTION: FILE *msgSetVerboseStream(FILE *f);

DESCRIPTION:

This function controls what stream the msgVerbose function outputs to.
The default value is stderr.  The library does no opening or closing
of this file.

Passing in a NULL restores the library to the default of stderr, and
returns the value currently in use.

SAMPLE:

    FILE *fl;
    fl = fopen("output", "w");
    msgSetVerboseStream(fl);
    ...
    fclose(msgSetVerboseStream(NULL));

------------------------------------------------------------------------------

Using the library to report errors:

FUNCTION: void msgError(const char *format, ...)

DESCRIPTION:

Pass msgError printf-like arguments, and it will print the name of the
program, followed by ": ", then your passed in arguments to whatever
the error stream is set to.

SAMPLE:

    msgError("you need to have more than %d things!\n", iThings);

==========================

FUNCTION: void msgFatal(const char *fmt, ...)

DESCRIPTION:

This function, called with printf-like arguments, will print the name
of the program, a ": ", then your output, to whatever the error stream
is set to.  It will then exit the running program, with an exit code
of 99.

SAMPLE:

    msgFatal("cannot open: %s\n", szFileName);

==========================

FUNCTION: void msgPerror(const char *fmt, ...)

DESCRIPTION:

msgPerror, named for the C library call perror, will print out your
passed in, printf-like arguments, then a ": ", then the textual error
code represented by the system global errno.  All output goes to the
stream set as the current error stream.

If errno represents "no error", then the function returns, doing
nothing.

The program name is not output, unless the msgSetShowNameAlways
function has forced it to do so.

SAMPLE:

    msgPerror("can't open %s", filename);

==========================

FUNCTION: void msgFatalPerror(const char *fmt, ...)

DESCRIPTION:

Like msgPerror, this function accepts printf-like arguments, and
displays those to the stream set as the error stream, followed by a
": ", then the textual error string that the global errno indicates.

If errno is not reporting an error, the call returns, having done
nothing.

The call normally does not output the program name, but a call to
msgSetShowNameAlways can force this.

If an error is set, the function will not return, exiting with a
return code of 99.

SAMPLE:

    msgFatalPerror("can't continue: %s file missing!", filename);

==========================

FUNCTION: void msgMessage(const char *format, ...)

DESCRIPTION:

msgMessage will take your output, format is as printf would, and
output it to the message stream.  If quiet mode has been set with
msgSetQuiet, nothing is output.  Normally, the program name is not
output, but if msgSetShowNameAlways has been called, the name of the
program, then a ": " will be prepended to the message.

SAMPLE:

    msgMessage("something went wrong!\n");

==========================

FUNCTION: msgVerbose(int level, const char *fmt, ...)

DESCRIPTION:

msgVerbose accepts a "verbosity level", followed by printf-like
arguments.  If the current verbosity level is greater than or equal to
the passed in value, the output will be formatted, and sent to the
verbose stream.  See above, in the msgSetVerbose description, for the
different fixed values, and methods of getting them.

The program name is not automatically output, unless
msgSetShowNameAlways has been called with a non-zero parameter.

Note that this can be quite useful to track program flow, if these are
used liberally at function entry and exit points, with a high
verbosity level.

SAMPLE:

    msgVerbose(5, "entering the CalcFooBar function!\n");