The documentation of “msg.h”

msg.h マニュアル

(The documentation of msg.h)

Last update: 2021/12/13

msg.hではメッセージの出力経路を設定・表示する関数が定義されている。
Functions to display message output routes are defined in msg.h.

メッセージ出力経路とは例えば

program.cの10行目(関数main)から sub1.h内の関数function1が呼ばれた
sub1.hの20行目(関数function1)から sub2.h内の関数function2が呼ばれた
sub2.hの30行目(関数function2)から sub3.h内の関数function3が呼ばれた
sub3.hの40行目(関数function3)からエラーメッセージが出力された

というような情報のことである。エラーメッセージの表示時にこうした情報を合わせて出力することでエラー箇所の特定が容易になる。
The message output routes are, for example, the information as below:

from line 10 of program.c (in function main), a function function1 in sub1.h was called;
from line 20 of sub1.h (in function function1), a function function2 in sub2.h was called;
from line 30 of sub2.h (in function function2), a function function3 in sub3.h was called; and finally
from line 40 of sub3.h (in function function3), an error message was displayed.

This kind of information facilitates identification of actual errors that caused the error message.

メッセージ出力経路を保存するため、 grobal.hにおいて以下の3つの配列(グローバル変数)が定義されている。

msgCallingFile : 関数呼び出し元のファイル名
msgCallingFunc : 関数呼び出し元の関数名
msgCallingLine : 関数呼び出し元のファイルにおける呼び出し箇所の行番号

これら3つの配列の値を変更し、表示するのがmsg.h内の関数である。
To preserve the message output routes, the following three arrays (grobal variables) are defined in grobal.h:

msgCallingFile : the name of a file from which each function was called;
msgCallingFunc : the name of a parent function from which each child function was called; and
msgCallingLine : the line number in the file of the parent function from which each child function was called.

Functions in msg.h modify and display the values of these three arrays.

上記の配列においては、経路の大元に近いものほど前の配列要素に入るように値が設定される。冒頭の例であれば下表のようになる。
The values of these arrays are set in an order that the origin side of the calling tree is in the earlier array component. The table below shows the case of the example explained at the head of this documentation.

配列要素番号 Array component index	msgCallingFile	msgCallingFunc	msgCallingLine
0	program.c	main	10
1	sub1.h	function1	20
2	sub2.h	function2	30

msgCallingFile, msgCallingFunc, msgCallingLineは固定長配列として宣言されている (配列長はマクロnMsgRoute (macro.h)で定義されている)。その中の何番目までが有効なメッセージ出力経路であるかを示すグローバル変数reserved_msgRoute_number (grobal.h)があり、その値についてもmsg.h内の関数において変更がなされる。
The arrays msgCallingFile, msgCallingFunc, and msgCallingLine are declared as fixed length arrays; the array length is defined by macro nMsgRoute (macro.h). The extent of the effective message output routes is indicated by a grobal variable reserved_msgRoute_number (grobal.h), the value of which is also modified by functions in msg.h.

このヘッダファイル内で定義されている関数を以下に示す。各関数の詳細は関数名をクリックしてリンク先を参照のこと。
Functions defined in this header file are listed below. For details of individual functions, click the links.

関数名 Function name	機能・用途 Purpose
setMsgRoute	関数呼び出し直前に用いてメッセージ出力経路に新しい要素を追加する。 Add a new component to message output routes; this function is used immediately before a function call.
removeMsgRoute	関数呼び出し直後に用いてメッセージ出力経路から最後の要素を削除する。 Remove the last component from message output routes; this function is used immediately after a function call.
printMsgRoute	メッセージ出力の直前に用いてメッセージ出力経路を表示する。 Display the message output routes; this function is used immediately before displaying a message.