名前 | 形式 | 機能説明 | 戻り値 | 使用法 | ファイル | 属性 | 関連項目
#include <libintl.h>char *gettext(const char *msgid);
#include <libintl.h> #include <locale.h>char *dcgettext(const char *domainname, const char *msgid, int category);
gettext()、dgettext()、dcgettext() 関数は、特定のドメイン内において、また、現在のロケールにおいて、指定の msgid 引数に基づいたターゲット文字列を取得します。gettext()、dgettext()、dcgettext() から返される文字列の長さは、これらの関数が呼び出されるまでは未定です。msgid 引数は、NULL で終わる文字列です。
環境変数 NLSPATH (environ(5) を参照) が、最初に LC_MESSAGES カタログの位置として検索されます。現在のロケールの LC_MESSAGES カテゴリの設定によって、gettext() および dgettext() が文字列取得に使用するロケールが決まります。category 引数は dcgettext() の使用するロケールを決めます。NLSPATH が定義されておらず、現在のロケールが C ロケールの場合、gettext()、gettext()、dcgettext() は、渡されたメッセージ文字列をそのまま返します。C ロケール以外のロケールでは、NLSPATH が定義されていないか、メッセージカタログが NLSPATH で指定した構成要素のどれにもない場合、ルーチンは bindtextdomain() を呼び出して、戻り値として dirname を取得したあと、dirname/locale/category/domainname.mo メッセージカタログを検索します。
gettext() の場合は、使用されるドメインは、最後に行なった textdomain() の有効な呼び出しによって設定されます。textdomain() の有効な呼び出しが行われていない場合は、デフォルト時のドメイン (messages) が使用されます。
dgettext() および dcgettext() の場合は、使用されるドメインは domainname 引数で指定されます。この domainname 引数は、構文と意味の上では、textdomain() の domainname 引数と同じですが、このドメイン選択が dgettext() または dcgettext() 関数の呼び出しの間だけ有効であるという点のみ異なります。
textdomain() 関数は、アクティブな LC_MESSAGES ロケールカテゴリの現在のドメイン名の設定 または照会を行います。domainname 引数は、正当なファイル名に使用できる文字のみからなる、NULL で終わる文字列です。
domainname 引数は、システム内の、一意のドメイン名です。1 つのシステム内に、同一ドメインのバージョンが 複数存在する場合は、bindtextdomain() を使用して名前空間の衝突を回避することができます。textdomain() を呼び出さない場合には、デフォルト時のドメインが選択されます。最後に行なった textdomain() の有効な呼び出しによるドメインの設定は、このあとに行う setlocale(3C) および gettext() の呼び出しにおいても有効です。
domainname 引数は、現在アクティブな、LC_MESSAGES ロケールに適用されます。
domainname に NULL ポインタを設定して textdomain() を呼び出すことによって、ドメインの現在の状態に影響することなく、ドメインの現在の設定を照会することができます。domainname 引数に NULL 文字列を設定して textdomain() を呼び出すと、ドメインの設定は、デフォルト時のドメイン (messages) になります。
bindtextdomain() 関数は、メッセージドメインのパス部分 domainname と、dirname に入っている値を結合します。domainname が空文字列ではなく、まだ結合されていない場合には、bindtextdomain() は、domainname と dirname を結合します。
domainname が空文字列ではなく、すでに結合されている場合には、bindtextdomain() は、事前に行われていた結合部分を dirname に置き換えます。dirname 引数に使用できるのは、gettext()、dgettext()、または dcgettext() が呼び出されたときに解決される、絶対パス名または相対パス名です。domainname が NULL ポインタまたは空文字列の場合は、bindtextdomain() は NULL を返します。ユーザー定義のドメイン名は、SYS_ で始めることはできません。この文字列で始まるドメイン名は、システムで使用するために予約されています。
gettext()、dgettext()、または dcgettext() が返す文字列の個々のバイトには、NULL 以外のあらゆる値が入ります。msgid が NULL ポインタである場合の戻り値は未定義です。返される文字列は、プログラムで修正してはならず、この後で gettext()、dgettext()、dcgettext()、または setlocale(3C) を呼び出すことにより、無効になることがあります。dgettext() の domainname 引数が NULL ポインタの場合の結果は未定義です。
現在のロケールおよび選択したドメインでターゲット文字列が見つからない場合、gettext()、dgettext()、および dcgettext() は msgid を返します。
textdomain() の正常な戻り値は、ドメインの現在の設定が入っている文字列へのポインタです。domainname が NULL ポインタの場合は、textdomain() は現在のドメインが入っている文字列へのポインタを返します。textdomain() を先に呼び出していない場合に domainname を NULL 文字列にすると、デフォルト時のドメイン名が返されます。デフォルト時のドメイン名は、messages です。
bindtextdomain() からの戻り値は、dirname が入った NULL で終わる文字列です。dirname が NULL の場合は、domainname と結び付けられたディレクトリバインディングです。何も結合されていない場合には、デフォルトの戻り値は /usr/lib/locale になります。domainname が NULL ポインタまたは空文字列の場合、bindtextdomain() は何も行わず、NULL ポインタを返します。返された文字列を呼び出し側で変更してはなりません。
これらのルーチンでは、メッセージの長さに制限はありません。ただし、テキスト domainname は、TEXTDOMAINMAX (256) バイト以内に制限されています。
ロケール変更のために setlocale(3C) が呼び出されていない限り、マルチスレッドアプリケーションにおいて gettext()、dgettext()、dcgettext()、textdomain()、および bindtextdomain() を安全に使うことができます。
メッセージ・ドメイン・ファイルのデフォルトパス部分
言語 locale および domainname 用メッセージの入っているファイルのシステムデフォルト位置
LC_XXX が LC_CTYPE、LC_NUMERIC、LC_TIME、LC_COLLATE、LC_MONETARY、または LC_MESSAGES である場合に、dcgettext() 呼び出し用の言語 locale および domainname メッセージの入っているファイルのシステムデフォルト位置
bindtextdomain() の正常な呼び出し後の、ドメイン domainname およびパス部分 dirname 用メッセージが入っているファイルの位置
bindtextdomain() の正常な呼び出し後の LC_XXX が、LC_CTYPE、LC_NUMERIC、LC_TIME、LC_COLLATE、LC_MONETARY、または LC_MESSAGES のいずれかである場合 dcgettext() 呼び出し用のドメイン domainname、言語 locale、およびパス部分 dirname メッセージが入っているファイルの位置
次の属性については attributes(5) のマニュアルページを参照してください。
属性タイプ | 属性値 |
---|---|
MT レベル | 例外付き MT-Safe |