Previous: , Up: Messages and Message Lists   [Contents][Index]


6.3.4 Printing Messages

Use the following function to get a text representation of a message object.

Function: int qsmm_msg_str (char *bufp, size_t bufsz, qsmm_msg_t msg, struct qsmm_dump_msg_desc_s *desc_p)

This function stores in a buffer bufp with size bufsz bytes a text representation of a message msg. If desc_p is not NULL, the function generates the text representation according to parameters in *desc_p. If desc_p is NULL, the function generates the text representation according to default parameters.

If desc_p is not NULL, the function sets desc_p->out_sz to the number of bytes required to store the text representation not counting finalizing byte 0. That number does not depend on bufsz. To determine the length of a text representation in this way, the function supports passing 0 for both bufp and bufsz.

If bufsz is positive, the function always finalizes a string written to bufp with byte 0. If the string and its finalizing byte 0 occupy more than bufsz bytes, the function truncates the string. In this case, desc_p->out_sz is greater than or equal to bufsz (if desc_p is not NULL).

If the buffer is large enough to hold the text representation including its finalizing byte 0, the function returns a positive value. If the buffer is smaller than needed, the function returns 0. On failure, the function returns a negative error code. Currently, the function can return the following error codes.

QSMM_ERR_INVAL

The argument bufsz is positive, but bufp is NULL.

QSMM_ERR_ILSEQ

Unable to convert the message object to its text representation according to a current locale.

QSMM_ERR_NOMEM

There was not enough memory to perform the operation.

The description of a structure for specifying the parameters of converting a message object to its text representation is below. The structure has a field for storing the length of this representation by the function qsmm_msg_str.

Structure: qsmm_dump_msg_desc_s

This structure specifies input and output parameters of converting a message object to its text representation. The structure contains the following fields.

Field: char is_compile

If this field is not 0, the function qsmm_msg_str considers an application program that has generated the message as a compiler (or assembler), or a process the application program is carrying out as compiling (or assembling). In this case, if the message object contains source location information specifying the name of a source file and a line number in it, qsmm_msg_str does not prepend the text representation with the name of this application program specified in the field prg_name_p of this structure.

If this field is 0, qsmm_msg_str always prepends an application program name to the text representation provided that prg_name_p is not NULL.

By default, qsmm_msg_str considers the application program as a compiler, or a process the application program is carrying out as compiling.

Field: char do_print_type

If not 0, prepend to the text representation a message category defined by the macro QSMM_MSG_NOTE, QSMM_MSG_WARNING, or QSMM_MSG_ERROR.

The function qsmm_msg_create_f or qsmm_msg_create_fv sets the category of a message using the enumeration qsmm_msg_e when creating the message. The function qsmm_get_msg_type returns the category of a message. See Creating Messages, for more information about message categories.

By default, prepend a message category to the text representation.

Field: const char * prg_name_p

The name of an application program that has generated the message. The field is_compile of this structure and source location information in the message object determine whether or not that name precedes the text representation. If the field prg_name_p is NULL, the function qsmm_msg_str does not prepend an application program name to the text representation.

The default value is NULL.

Field: const char * fln_p

An associated file name if the message object does not have this file name in source location information. If the message object has a line number, including special line number 0, in the source location information (assigned by the function qsmm_set_msg_lineno), the function qsmm_msg_str prepends the associated file name to the text representation.

This field can contain the name of a top-level source file for use with message objects created while preprocessing the source text of an assembler program, parsing the source text of an assembler program, or loading a memory representation of an assembler program into a node. If such a message object has source location information specifying the name of a source file and a line number in it, this source location information references the source file directly or indirectly included in the top-level source file by the ‘include’ preprocessor directive. If the source location information specifies a line number but not a source file name, this line number pertains to the top-level source file. In the latter case, if this field is not NULL, qsmm_msg_str uses it for the name of that top-level source file and prepends it to the text representation.

The default value of this field is NULL.

Field: size_t out_sz

Output parameter. The number of bytes occupied by the text representation not counting finalizing byte 0. That number does not depend on buffer size passed to qsmm_msg_str.

To improve compatibility with future versions of QSMM library, zero by the function memset an instance of qsmm_dump_msg_desc_s structure before setting the fields of this instance passed to the function qsmm_msg_str.

The function qsmm_msg_str converts user-created message objects to their text representations in formats listed below. A label corresponding to the category of a message specified when creating the message object can precede a message text; see the description of do_print_type field of qsmm_dump_msg_desc_s structure for more information.

message text
program name: message text
input file name: message text
input file name:line number: message text
program name: input file name: message text
program name:input file name:line number: message text

The text representations of message objects created when preprocessing the source text of an assembler program, parsing the source text of an assembler program, or loading a memory representation of an assembler program into a node may have other formats. For example, the function qsmm_msg_str might prepend a stack of locations in assembler source files to an error message generated while parsing the source text of an assembler program. The stack might indicate the locations of ‘include’ preprocessor directives that included the content of an assembler source file with a syntax error.

Use the following function to dump a message list to a stream.

Function: int qsmm_msglist_dump (qsmm_msglist_t msglist, const char *prg_name_p, const char *fln_p, unsigned int flags, FILE *filep)

This function dumps to a stream filep all messages contained in a message list msglist. The argument prg_name_p specifies the name of an application program that has generated the messages. The argument fln_p specifies the name of a top-level file (usually input one) associated with the messages. The argument flags can contain a bitmask defined by the macro QSMM_MSG_DUMP_PRG_NAME_ALL.

If prg_name_p is not NULL, the function prepends the application program name prg_name_p to messages without associated line numbers and to messages with associated line number 0. If prg_name_p is not NULL, and flags contain the bitmask QSMM_MSG_DUMP_PRG_NAME_ALL, the function prepends the application program name to all messages.

If fln_p is not NULL, the function prepends the top-level file name fln_p to all messages with associated line numbers, including line number 0, but without associated file names.

To obtain the text representations of message objects contained in the message list, this function calls the function qsmm_msg_str. If after writing the text representation of a message object to the stream the function ferror reports a stream error, the function qsmm_msglist_dump aborts dumping the messages and reports success. A calling function can use ferror to test for this stream error condition.

On success or stream error, qsmm_msglist_dump returns a non-negative value. On other errors, this function returns a negative error code. Currently, the function can return the following error codes.

QSMM_ERR_ILSEQ

Unable to convert a message object contained in the message list to a text representation according to a current locale.

QSMM_ERR_NOMEM

There was not enough memory to perform the operation.

On these errors, the function aborts dumping remaining messages in the message list.


Previous: , Up: Messages and Message Lists   [Contents][Index]