3.9.3.1 Inept excess verbiage

Although the author of a library function may take pride in putting its activities on display, it should be assumed that virtual code applications running on avram have other agendas for the console, so the library interface module should prevent direct output from the external library.

More thoughtful API’s may have a verbosity setting, which should be used in preference to this workaround, but failing that, it is easy to dispense with console output generated by calls to external library functions by using some combination of the following functions.

Function: void avm_turn_off_stdout ()

Calling this function will suppress all output to the standard output stream until the next time avm_turn_on_stdout is called. Additional calls to this function without intervening calls to avm_turn_on_stdout may be made safely with no effect. The standard output stream is flushed as a side effect of calling this function.

Function: void avm_turn_on_stdout ()

Calling this function will allow output to the standard output stream to resume if it has been suppressed previously by a call to avm_turn_off_stdout. If avm_turn_off_stdout has not been previously called, this function has no effect. Any output that would have been sent to stdout during the time it was turned off will be lost.

Function: void avm_turn_off_stderr ()

This function performs a similar service to that of avm_turn_off_stdout but pertains to the standard error stream. The standard error and the standard output streams are controlled independently even if both of them are piped to the same console.

Function: void avm_turn_on_stderr ()

This function performs a similar service to that of avm_turn_on_stdout but pertains to the standard error stream.

As an example, the following code fragment will prevent any output to standard output taking place as a side effect of blather, but will allow error messages to standard error. Note that ouput should not be left permanently turned off.

...
#include <avm/mwrap.h>
...

x = y + z;
avm_turn_off_stdout ();
w = blather (foo, bar, baz);
avm_turn_on_stdout ();
return w;
...

One possible issue with these functions is that they rely on a feature of the GNU C library that might not be portable to non-GNU systems and has not been widely tested on other platforms.

Another issue is that a library function could be both careless enough to clutter the console unconditionally and meticulous enough to check for I/O errors after each attempted write. Writing while the output stream is disabled will return an I/O error to the caller (i.e., to the verbose library function) for appropriate action, which could include terminating the process.

This document was generated on November 8, 2012 using texi2html 1.82.