It is frequently necessary to write error messages to the standard error output, and often these messages must begin with the program's invocation name. Libretto provides functions to perform such actions; they are detailed in this section.
Note, however, that since there is no portable way to determine a program's invocation name at runtime, your program must supply the invocation name before using any functions that might use it.
This function is used to tell Libretto the invocation name of your program. It should in general be used only once, at the beginning of ‘main’, thus:
int main (int argc, char **argv) { /* Declare variables here. */ msg_set_invocation_name (argv[0]); /* Rest of main goes here. */ return 0; }However, it is legal to call it more than once in a given program, even if such usage changes the invocation name. It is also legal to subsequently change ‘argv’; Libretto's idea of the invocation name will not change.
Note that calling this function alters data that is global to each process, though using it once at the start of ‘main’ should not have a detrimental effect on multi-threaded applications.
Once you have called ‘msg_set_invocation_name’, the following variables will be non-empty:
These variables contain the invocation name of the program being run. ‘libretto_program_name’ contains the full name, possibly including a path to the executable, while ‘libretto_program_short_name’ contains only the base name of the executable. Until ‘msg_set_invocation_name’ has been called, both these variables are the empty string.
This function prints the string given by fmt on stderr. See Formatted I/O for details of the formatting rules. The formatted message is preceded by the program's short invocation name, a colon, and a space.
This function acts like ‘msg_write’ except that in addition, it causes the program to quit and return the value 1 to the calling process. It uses ‘exit’ to quit the program, so any functions registered with ‘atexit’ will be called automatically. This function never returns.
This function acts like ‘msg_fatal’ except that the value returned to the calling process is taken from status rather than being fixed at 1. status should be greater than zero, but as a special extension, if it is negative, the program will be exited using abort(), showing abnormal program termination. This function never returns.
These functions behave like ‘msg_write’, ‘msg_fatal’ and ‘msg_fataln’ respectively, except that the messages written are in a format appropriate for compiler messages (according to the GNU coding standards). That is, the formatted message is prefixed by file (the name of the current source file), a colon, line (the current line in the source file), another colon, and a space. An example:
msg_cc_write ("foo.c", 42, "A useless message\n");would print
foo.c:42: A useless message
These functions behave like ‘msg_write’, ‘msg_fatal’ and ‘msg_fataln’ respectively, except that the messages written are in a format appropriate for a program with a concept of `source file' and `line number' (according to the GNU coding standards). That is, the formatted message is prefixed by the program's short invocation name, a colon, file (the name of the current source file), another colon, line (the current line in the source file), a third colon, and a space. An example:
msg_l_write ("foo.c", 42, "A useless message\n");in a program whose invocation name is ‘foo’ would print
foo:foo.c:42: A useless message
These functions behave like ‘msg_write’, ‘msg_fatal’ and ‘msg_fataln’ respectively, except that the messages written are in a format appropriate for a multi-process program, where each process must identify its process id (pid) when writing a message. That is, the formatted message is prefixed by the program's short invocation name, an opening square bracket, the pid, a closing square bracket, a colon, and a space. An example:
msg_pid_write ("A useless message\n");in a process whose invocation name is ‘foo’ and whose pid is 1742 would print
foo[1742]: A useless message
This function formats a message on stderr according to format and any additional arguments. It is equivalent to ‘file_printf’ (see Formatted output functions) with stderr as the file.
This function prints usage messages on stderr. fmt and any remaining arguments are parsed as for ‘msg_write’; note particularly that any occurrence of ‘%V’ is replaced by the value of libretto_program_short_name (see below). After the message is formatted, if status is non-negative, the program is terminated with that value.