前へ
目次
索引
DocHome
次へ
|
| iPlanet Web Server, Enterprise Edition NSAPI プログラマーズガイド |
第 5 章 NSAPI 関数のリファレンス
この章では、NSAPI (Netscape Server Applications Programming Interface) の公開されているすべての C 言語の関数およびマクロをアルファベット順に示します。これらの関数は、独自のサーバアプリケーション関数 (Server Application Functions: SAF) を作成するときに使用することができます。事前定義された Init SAF のリストは、第 7 章「magnus.conf の構文と使用法」を参照してください。Init SAF 以外の事前定義された SAF のリストは、第 3 章「事前定義済みの SAF および要求処理プロセス」を参照してください。
関数ごとに、名称、構文、パラメータ、戻り値、関数の用途の説明を提供し、また関数の使用例や関連する関数を示している場合もあります。
データ構造体については、付録 A「データ構造体のリファレンス」、また iPlanet Web Server 6.0 のビルドの include ディレクトリ内の nsapi.h ヘッダーファイルを参照してください。
NSAPI 関数 (アルファベット順)
アルファベット順の関数名のリストは、付録 G「NSAPI 関数とマクロのアルファベット順リスト」を参照してください。
CALLOC マクロは、C ライブラリルーチンの calloc の、プラットフォームに依存しないものです。CALLOC は、要求のメモリープールから num*size バイトを割り当てます。プールされたメモリーが (組み込み SAF の pool-init を使って) 構成ファイルで無効に設定されている場合は、PERM_CALLOC および CALLOC はシステムヒープからメモリーを取得します。
構文
void *CALLOC(int num, int size)
戻り値
メモリーのブロックへの void 型のポインタを返します。
例
/* 100 個の char 型のポインタの配列に領域を割り当てる */
char *name;
name = (char *) CALLOC(100, sizeof(char *));
関連項目
FREE、REALLOC、STRDUP、PERM_MALLOC、PERM_FREE、PERM_REALLOC、PERM_STRDUP
cinfo_find() 関数は、MIME タイプ情報を使って、URI (Universal Resource Identifier) またはローカルファイル名の拡張子に基づいてタイプ、コード化方法、または言語を判別します。この情報を使って、サーバから受け取るデータの content-type、content-encoding、および content-language を示すヘッダー (rq->srvhdrs) をクライアントへ送ります。
使われる名前は、最後のスラッシュ (/) 後のすべての文字、またはスラッシュがない場合は文字列全体になります。ファイル名拡張子には、大文字 ‐ 小文字の区別がありません。名前には、タイプ、コード化方法、または言語を示すために、ピリオド (.) で区切られた複数の拡張子を含むことができます。たとえば、URI の a/b/filename.jp.txt.zip は、日本語で、タイプが text/plain であり、zip でコード化されたファイルを表します。
構文
cinfo *cinfo_find(char *uri);
戻り値
内容情報が見つかった場合は、新しく割り当てられた cinfo 構造体へのポインタを返し、内容が見つからない場合は NULL を返します。割り当てられ、返された cinfo 構造体には、見つかった場合は、content-type、content-encoding、および content-language へのポインタが含まれています。それぞれ、types データベース内の static データへのポインタ情報であり、見つからない場合は NULL になります。これらのポインタを解放してはなりません。cinfo 構造体については、使い終わったら解放する必要があります。
パラメータ
char *uri は、URI またはローカルファイルの名前です。複数のファイル名拡張子は、ピリオド (.) で区切る必要があります。
condvar_init 関数は、指定されたクリティカルセクション変数に関連する新しい条件変数を初期化して返す、クリティカルセクション関数です。条件変数を使って、実行される 2 つのスレッドが干渉し合うのを防止できます。
構文
CONDVAR condvar_init(CRITICAL id);
戻り値
新しく割り当てられた条件変数 (CONDVAR) を返します。
パラメータ
CRITICAL id は、クリティカルセクション変数です。
関連項目
condvar_notify、condvar_terminate、condvar_wait、crit_init、crit_enter、crit_exit、crit_terminate
condvar_notify 関数は、指定されたクリティカルセクション変数でブロックされたスレッドを呼び起こす、クリティカルセクション関数です。特定のクリティカルセクションの実行のスレッドを呼び起こすには、この関数を使います。まず、crit_enter を使って、クリティカルセクションの所有権を得ます。次に、返されたクリティカルセクション変数を使って condvar_notify を呼び出して、スレッドを呼び起こします。最後に、condvar_notify から復帰したら、crit_exit を呼び出してクリティカルセクションの所有権を返します。
構文
void condvar_notify(CONDVAR cv);
関連項目
condvar_init、condvar_terminate、condvar_wait、crit_init、crit_enter、crit_exit、crit_terminate
condvar_terminate 関数は、条件変数を解放するクリティカルセクション関数です。前に割り当てた条件変数を解放するには、この関数を使います。
警告
使用中の条件変数を終了させると、予期しない結果をまねくことがあります。
構文
void condvar_terminate(CONDVAR cv);
関連項目
condvar_init、condvar_notify、condvar_wait、crit_init、crit_enter、crit_exit、crit_terminate
指定された条件変数でブロックするクリティカルセクション関数です。クリティカルセクション (条件変数引数で指定された) が利用できるようになるまで待つようにするには、この関数を使います。呼び出し元スレッドは、同じ条件変数引数で別のスレッドが condvar_notify を呼び出すまで、ブロックされます。呼び出し元は、condvar_wait を呼び出す前に、この条件変数に関連付けられたクリティカルセクションに入っている必要があります。
構文
void condvar_wait(CONDVAR cv);
関連項目
condvar_init、condvar_notify、condvar_terminate、crit_init、crit_enter、crit_exit、crit_terminate
クリティカルセクションへ入ることを試みるクリティカルセクション関数です。クリティカルセクションの所有権を得るには、この関数を使います。ほかのスレッドがすでにそのクリティカルセクションを所有している場合は、呼び出し元スレッドは、crit_exit の呼び出しによって最初のスレッドが所有権を返すまで、ブロックされます。
構文
void crit_enter(CRITICAL crvar);
パラメータ
CRITICAL crvar は、クリティカルセクション変数です。
関連項目
crit_init、crit_exit、crit_terminate
クリティカルセクションの所有権を返すクリティカルセクション関数です。クリティカルセクションの所有権を返すには、この関数を使います。ほかのスレッドがブロックされクリティカルセクションを待っている場合は、ブロックは取り除かれ、待機していたスレッドにそのクリティカルセクションの所有権が与えられます。
構文
void crit_exit(CRITICAL crvar);
パラメータ
CRITICAL crvar は、クリティカルセクション変数です。
関連項目
crit_init、crit_enter、crit_terminate
新しいクリティカルセクション変数 (型が CRITICAL の変数) を作成し、返すクリティカルセクション関数です。実行される 2 つのスレッド間の干渉の防止の管理に使う、型が CRITICAL (クリティカルセクション変数) の変数の新しいインスタンスを取得するには、この関数を使います。スレッドの作成時には、どのスレッドもクリティカルセクションを所有していません。
警告
crit_terminate が呼び出される時は、スレッドがクリティカルセクションを所有していたり待機してはなりません。
戻り値
新しく割り当てられたクリティカルセクション変数 (CRITICAL) を返します。
関連項目
crit_enter、crit_exit、crit_terminate
前に割り当てたクリティカルセクション変数 (型が CRITICAL の変数) を削除する、クリティカルセクション関数です。crit_init を呼び出して前に取得したクリティカルセクション変数を解放するには、この関数を使います。
構文
void crit_terminate(CRITICAL crvar);
パラメータ
CRITICAL crvar は、クリティカルセクション変数です。
関連項目
crit_init、crit_enter、crit_exitdaemon_atrestart 関数を使って、サーバの終了時に使う、fn で指定されたコールバック関数を登録できます。初期化関数が割り当てたリソースをコールバック関数で割り当て解除する必要がある場合に、この関数を使います。daemon_atrestart 関数は、magnus_atrestart 関数を汎用化したものです。
magnus.conf 指令の TerminateTimeout と ChildRestartCallback も、NSAPI 関数のコールバックに影響します。
構文
void daemon_atrestart(void (*fn)(void *), void *data);
パラメータ
void (* fn) (void *) は、コールバック関数です。void *data は、サーバの再起動時にコールバック関数に渡されるパラメータです。
例
/* log_close 関数を登録し、サーバの再起動またはシャットダウン時に */
/* *ログファイルを閉じるために、*/
/* log_close に NULL を渡す */
daemon_atrestart(log_close, NULL);
NSAPI_PUBLIC void log_close(void *parameter)
{
system_fclose(global_logfd);
}fc_close 関数は、fc_open を使って開いたファイルを閉じます。この関数は、fc_open を使って開いたファイルでのみ呼び出す必要があります。
構文
void fc_close(PRFileDesc *fd, FcHdl *hDl);
パラメータ
PRFileDesc *fd fc_open への前への呼び出しから返された有効なポインタです。FcHdl *hDl は、型が FcHdl の構造体への有効なポインタです。このポインタは、 fc_open への前の呼び出しで初期化されている必要があります。
fc_open 関数は、開いているファイル (fileName) を指す PRFileDesc へのポインタを返します。fileName は、既存のファイルの絶対パス名である必要があります。ファイルは、読み取りモードでのみ開きます。この関数を呼び出すアプリケーションは、DUP_FILE_DESC もこの関数に渡される場合以外は、PRFileDesc * でポイントされるファイルの現在の位置を変更してはなりません。つまり、アプリケーションは (少なくとも)、PRFileDesc * の現在の位置を変更する、このポインタに基づいた読み取り操作を発行してはなりません。そのような読み取り操作 (PRFileDesc * の現在の位置を変更することがある) が必要な場合は、アプリケーションは、DUP_FILE_DESC 引数を指定してこの関数を呼び出す必要があります。
この関数への呼び出しが成功すると、PRFileDesc への有効なポインタが返され、ハンドル「FcHdl」が適切に初期化されます。ファイルのサイズの情報は、ハンドルの「fileSize」メンバーに格納されます。
構文
PRFileDesc *fc_open(const char *fileName, FcHdl *hDl,PRUint32 flags, Session *sn, Request *rq);
戻り値
PRFileDesc へのポインタを返し、失敗した場合は NULL を返します。
パラメータ
const char *fileName は、開くファイルの絶対パス名です。FcHdl*hDl は、型 FcHdl の構造体への有効なポインタです。
PRUint32 flags は、0 または DUP_FILE_DESC になります。
filebuf_buf2sd 関数は、ファイルバッファをソケット (記述子) に送信し、送信したバイト数を返します。
ファイル全体の内容をクライアントへ送信するには、この関数を使います。
構文
int filebuf_buf2sd(filebuf *buf, SYS_NETFD sd);
戻り値
成功した場合は、ソケットへ送信したバイトを返し、ファイルバッファを送信できなかった場合は、定数 IO_ERROR を返します。
パラメータ
filebuf *buf は、すでに開かれている必要がある、ファイルバッファです。SYS_NETFD sd は、プラットフォームに依存しないソケット記述子です。通常、このソケット記述子は、sn (Session: セッション) 構造体の csd (client socket descriptor: クライアントソケット記述子) フィールドから得られます。
例
if (filebuf_buf2sd(buf, sn->csd) == IO_ERROR)
return(REQ_EXIT);
関連項目
filebuf_close、filebuf_open、filebuf_open_nostat、filebuf_getc
filebuf_close 関数は、ファイルバッファの割り当てを解除し、関連するファイルを閉じます。
通常は、まず filebuf_open を使ってファイルバッファを開き、次に filebuf_getc を使ってファイル内の情報にアクセスします。ファイルバッファを使用し終わったら、filebuf_close を使って閉じます。
構文
void filebuf_close(filebuf *buf);
パラメータ
filebuf *buf は、filebuf_open で前に開いたファイルバッファです。
関連項目
filebuf_open、filebuf_open_nostat、filebuf_buf2sd、filebuf_getc
filebuf_getc 関数は、現在のファイル位置から文字を取得し、その文字を整数として返します。次に、現在のファイルの位置を増分します。
バッファ化されたファイルから文字を順番に読み取るには、filebuf_getc を使います。
戻り値
取得した文字が含まれる整数を返し、ファイルの終わりまたはエラーの場合は定数の IO_EOF または IO_ERROR を返します。
パラメータ
filebuf b は、ファイルバッファの名前です。
関連項目
filebuf_close、filebuf_buf2sd、filebuf_open、filebuf_open_nostat
filebuf_open 関数は、前に開いたファイルに対して新しいファイルバッファを開きます。新しいバッファ構造体を返します。バッファ化されたファイルは、オペレーティングシステムがバッファによる入出力をサポートしていない環境で、バッファによるファイルの入出力を可能にし、ファイルアクセスをより効率的にします。
構文
filebuf *filebuf_open(SYS_FILE fd, int sz);
戻り値
成功した場合はデータを入れる新しいバッファ構造体へのポインタを返し、バッファを開くことができない場合は NULL を返します。
パラメータ
SYS_FILE fd は、すでに開かれているファイルのプラットフォームに依存しないファイル記述子です。int sz は、バッファに使用される、バイト単位のサイズです。
例
filebuf *buf = filebuf_open(fd, FILE_BUFFERSIZE);
if (!buf) {
system_fclose(fd);
}
関連項目
filebuf_getc、filebuf_buf2sd、filebuf_close、filebuf_open_nostat
filebuf_open_nostat 関数は、前に開いたファイルに対して新しいファイルバッファを開きます。新しいバッファ構造体を返します。バッファ化されたファイルは、オペレーティングシステムがバッファによる入出力をサポートしていない環境で、バッファによるファイルの入出力を可能にし、ファイルアクセスをより効率的にします。
この関数は、filebuf_open と同じですが、request_stat_path 関数を呼び出す必要がないので、より効率的です。この関数には、stat 情報を渡す必要があります。
構文
filebuf* filebuf_open_nostat(SYS_FILE fd, int sz,
struct stat *finfo);
戻り値
成功した場合はデータを入れる新しいバッファ構造体へのポインタを返し、バッファを開くことができない場合は NULL を返します。
パラメータ
SYS_FILE fd は、すでに開かれているファイルのプラットフォームに依存しないファイル記述子です。int sz は、バッファに使用されるバイト単位のサイズです。
struct stat *finfo は、ファイルのファイル情報です。filebuf_open_nostat 関数を呼び出す前に、request_stat_path 関数を呼び出してファイル情報を取得する必要があります。
例
filebuf *buf = filebuf_open_nostat(fd, FILE_BUFFERSIZE, &finfo);
if (!buf) {
system_fclose(fd);
}
関連項目
filebuf_close、filebuf_open、filebuf_getc、filebuf_buf2sd
FREE マクロは、C ライブラリルーチンの free のプラットフォームに依存しないものです。この関数は、MALLOC、CALLOC、または STRDUP によって前に割り当てられた領域を、要求のメモリープールから割り当て解除します。
パラメータ
void *ptr は、メモリーのブロックへの (void *) ポインタです。このポインタが MALLOC、CALLOC、または STRDUP で作成されたものでない場合は、動作は定義されていません。
例
char *name;
name = (char *) MALLOC(256);
...
FREE(name);
関連項目
MALLOC、CALLOC、REALLOC、STRDUP、PERM_MALLOC、PERM_FREE、PERM_REALLOC、PERM_STRDUP
func_exec 関数は、指定された pblock 内の fn エントリで指定された関数を実行します。関数名が見つからない場合は、エラーをログに記録し、REQ_ABORTED を返します。
pblock 内に組み込み SAF を指定すると、この関数を使って、その SAF を実行できます。
構文
int func_exec(pblock *pb, Session *sn, Request *rq);
戻り値
実行された関数が返す値を返し、または関数が実行されなかった場合は定数の REQ_ABORTED を返します。
パラメータ
pblock *pb は、関数名 (function name: fn) とパラメータが入っている pblock です。Session および Request パラメータは、カスタム SAF に渡されるものと同じです。
func_find 関数は、name で指定された関数へのポインタを返します。関数が存在しない場合は、NULL を返します。
構文
FuncPtr func_find(char *name);
戻り値
間接参照に適した、選択した関数へのポインタを返します。関数が見つからない場合は、NULL を返します。
例
/* このコードブロックは、func_exec と同じことを実行する */
char *afunc = pblock_findval("afunction", pb);
FuncPtr afnptr = func_find(afunc);
if (afnptr)
return (afnptr)(pb, sn, rq);log_error 関数は、エラーログにエントリを作成し、日付、重要度、および指定されたテキストを記録します。
構文
int log_error(int degree, char *func, Session *sn, Request *rq, char *fmt, ...);
戻り値
ログエントリが作成された場合は 0、ログエントリが作成されなかった場合は -1 を返します。
パラメータ
int degree は、エラーの重要度を指定します。このパラメータは、次のいずれかの定数にする必要があります。LOG_WARN警告
LOG_MISCONFIG構文エラーまたはアクセス権違反
LOG_SECURITY認証の失敗またはホストからの 403 エラー
LOG_FAILURE内部の問題
LOG_CATASTROPHEサーバ回復不能のエラー
LOG_INFORM情報メッセージSession および Request パラメータは、SAF に渡されたものと同じです。
char *fmt は、メッセージを配信する printf 関数用の書式を指定します。
... は、printf 関数の一連のパラメータを表します。
例
log_error(LOG_WARN, "send-file", sn, rq,
"error opening buffer from %s (%s)", path,
system_errmsg(fd));MALLOC マクロは、C ライブラリルーチンの malloc のプラットフォームに依存しないものです。MALLOC は、通常、要求のメモリープールから割り当てます。プールされたメモリーが構成ファイルで (組み込み SAF の pool-init を使って) 無効に設定されている場合は、PERM_MALLOC および MALLOC はどちらもシステムヒープからメモリーを取得します。
戻り値
メモリーのブロックへの void 型のポインタを返します。
例
/* name に 256 バイトを割り当てる */
char *name;
name = (char *) MALLOC(256);
関連項目
FREE、CALLOC、REALLOC、STRDUP、PERM_MALLOC、PERM_FREE、PERM_CALLOC、PERM_REALLOC、PERM_STRDUPnet_ip2host 関数は、テキスト形式の IP アドレスを絶対パスによるドメイン名に変換して返します。
注 この関数は、magnus.conf ファイルで DNS 指令が有効になっている場合にだけ機能します。詳細は、第 7 章「magnus.conf の構文と使用法」を参照してください。
構文
char *net_ip2host(char *ip, int verify);
戻り値
変換できた場合は、絶対パスによるドメイン名が含まれる新しい文字列を返し、変換できなかった場合は NULL を返します。
パラメータ
char *ip は、ドット付き 10 進表記の文字列形式nnn.nnn.nnn.nnn の IP (Internet Protocol) アドレスです。int verify は、ゼロでない場合、関数が絶対パスによるドメイン名を検証する必要があることを示します。これには、さらに照会が必要になりますが、アクセス制御を確認するときには使用する必要があります。
net_read 関数は、指定されたソケットから指定されたバッファにバイトを読み込みます。この関数は、ソケットで少なくとも 1 バイトが利用可能になるまで、または指定された期間が過ぎるまで、ソケットからのデータの受信を待ちます。
構文
int net_read (SYS_NETFD sd, char *buf, int sz, int timeout);
戻り値
読み込まれたバイト数を返し、この数は最大サイズの sz を超えません。エラーが発生した場合は負の値が返され、その場合、timeout 秒が経過する前に操作が完了しなかった場合は、定数 ETIMEDOUT に errno が設定されます。
パラメータ
SYS_NETFD sd は、プラットフォームに依存しないソケット記述子です。int timeout は、復帰する前に読み込み操作に許可される秒数です。timeout の目的は、与えられた時間内に十分なバイトが読み込まれなかったために復帰することではなく、データを受け取るまで待つ時間を制限することです。
net_write 関数は、指定されたバイト数を指定されたバッファから指定されたソケットに書き込みます。書き込まれたバイト数を返します。
構文
int net_write(SYS_NETFD sd, char *buf, int sz);
戻り値
書き込まれたバイト数を返し、エラーが発生した場合は要求されたサイズよりも小さいことがあります。
パラメータ
SYS_NETFD sd は、プラットフォームに依存しないソケット記述子です。
例
if (net_write(sn->csd, FIRSTMSG, strlen(FIRSTMSG)) == IO_ERROR)
return REQ_EXIT;
netbuf_buf2sd 関数は、バッファをソケットへ送信します。この関数を使って、データを IPC パイプからクライアントへ送信することができます。
構文
int netbuf_buf2sd(netbuf *buf, SYS_NETFD sd, int len);
戻り値
成功した場合はソケットへ転送されたバイトの数を返し、失敗した場合は定数の IO_ERROR を返します。
パラメータ
netbuf *buf は、送信するバッファです。SYS_NETFD sd は、プラットフォームに依存しないソケット識別子です。
関連項目
netbuf_close、netbuf_getc, netbuf_grab、netbuf_open
netbuf_close 関数は、ネットワークバッファを割り当て解除し、関連するファイルを閉じます。ネットワークバッファを割り当て解除し、ソケットを閉じる必要があるときに、この関数を使います。
Session 構造体内の netbuf パラメータは閉じてはなりません。
構文
void netbuf_close(netbuf *buf);
パラメータ
netbuf *buf は、閉じるバッファです。
関連項目
netbuf_buf2sd、netbuf_getc, netbuf_grab、netbuf_open
netbuf_getc 関数は、b で指定されたネットワークバッファのカーソル位置から文字を取得します。
戻り値
文字を取得できた場合はその文字を表す整数を返し、ファイルの終わりまたはエラーの場合は定数の IO_EOF または IO_ERROR を返します。
パラメータ
netbuf b は、1 つの文字の取得先のバッファです。
関連項目
netbuf_buf2sd、netbuf_close、netbuf_grab、netbuf_open
netbuf_grab 関数は、ネットワークバッファ (buf) のソケットからネットワークバッファへ sz 個のバイトを読み込みます。バッファの大きさが十分でない場合は、大きさが調整されます。成功した場合、buf->inbuf からデータを取得できます。
構文
int netbuf_grab(netbuf *buf, int sz);
戻り値
操作が成功した場合は実際に読み込んだバイトの数 (1 〜 sz) を返し、ファイルの終わりまたはエラーの場合は定数の IO_EOF または IO_ERROR を返します。
パラメータ
netbuf *buf は、データを読み込むバッファです。
関連項目
netbuf_buf2sd、netbuf_close、netbuf_getc、netbuf_open
netbuf_open 関数は、新しいネットワークバッファを開いて返します。netbuf_open を使って、netbuf 構造体を作成し、ソケットに対してバッファを利用した入出力の使用を開始できます。
構文
netbuf* netbuf_open(SYS_NETFD sd, int sz);
戻り値
新しい netbuf 構造体 (ネットワークバッファ) へのポインタを返します。
パラメータ
SYS_NETFD sd は、プラットフォームに依存しないソケット識別子です。int sz は、ネットワークバッファに割り当てる文字の数です。
関連項目
netbuf_buf2sd、netbuf_close、netbuf_getc、netbuf_grabparam_create 関数は、指定された名前と値が含まれる pb_param 構造体を作成します。名前と値はコピーされます。pblock_pinsert などのように、 pblock ルーチンへの呼び出しに使うために、この関数を使って pb_param 構造体を準備します。
構文
pb_param *param_create(char *name, char *value);
戻り値
新しい pb_param 構造体へのポインタを返します。
パラメータ
char *name は、名前が含まれる文字列です。
例
pb_param *newpp = param_create("content-type","text/plain");
pblock_pinsert(newpp, rq->srvhdrs);
関連項目
param_free、pblock_pinsert、pblock_remove
param_free 関数は、pp で指定された pb_param 構造体とこの構造体に関連する構造体を解放します。pblock_remove で pblock から削除した後に pb_param を廃棄するには、param_free 関数を使います。
構文
int param_free(pb_param *pp);
戻り値
パラメータが解放された場合は 1、パラメータが NULL の場合は 0 を返します。
パラメータ
pb_param *pp は、pblock に格納された名前 - 値のペアです。
例
if (param_free(pblock_remove("content-type", rq-srvhdrs)))
return; /* 削除した */
関連項目
param_create、pblock_pinsert、pblock_remove
pblock_copy 関数は、コピー元の pblock のエントリをコピーし、コピー先の pblock に追加します。コピー先の pblock に前からあるエントリは、影響を受けません。
構文
void pblock_copy(pblock *src, pblock *dst);
パラメータ
pblock *src は、コピー元である pblock です。pblock *dst は、コピー先の pblock です。
元の pblock を解放したり、または元の pblock に影響を与えずに新しい pblock を変更したりできるように、名前と値が新たに割り当てられます。
関連項目
pblock_create、pblock_dup、pblock_free、pblock_find、pblock_findval、pblock_remove、pblock_nvinsert
pblock_create 関数は、新しい pblock を作成します。pblock は、名前 - 値ペアのより早い検索のために内部にハッシュテーブルを維持します。
構文
pblock *pblock_create(int n);
戻り値
新たに割り当てられた pblock へのポインタを返します。
パラメータ
int n は、pblock 用のハッシュテーブルのサイズ (名前 - 値ペアの数) です。
関連項目
pblock_copy、pblock_dup、pblock_find、pblock_findval、pblock_free、pblock_nvinsert、pblock_remove
pblock_dup 関数は、pblock を複製します。この関数は、pblock_create に pblock_copy を続けて実行する場合と同じことを行ないます。
構文
pblock *pblock_dup(pblock *src);
戻り値
新たに割り当てられた pblock へのポインタを返します。
パラメータ
pblock *src は、コピー元の pblock です。
関連項目
pblock_create、pblock_find、pblock_findval、pblock_free、pblock_find、pblock_remove、pblock_nvinsert
pblock_find 関数は、pblock 内の指定された名前 - 値ペアのエントリを検索し、pb_param 構造体を返します。名前に関連する値だけが必要な場合は、pblock_findval 関数を使います。
構文
pb_param *pblock_find(char *name, pblock *pb);
戻り値
見つかった場合は pb_param 構造体へのポインタを返し、名前が見つからなかった場合は NULL を返します。
パラメータ
char *name は、名前 - 値ペアの名前です。
関連項目
pblock_copy、pblock_dup、pblock_findval、pblock_free、pblock_nvinsert、pblock_remove
pblock_findval 関数は、pblock 内に指定された名前の値を検索します。pblock の pb_param 構造体だけが必要な場合は、pblock_find 関数を使います。
返されるポインタは、pblock へのポインタです。このポインタを解放してはなりません。変更する必要がある場合は、STRDUP を実行し、コピーを変更します。
構文
char *pblock_findval(char *name, pblock *pb);
戻り値
名前に関連付けられた値が含まれる文字列を返し、一致するものが見つからなかった場合は NULL を返します。
パラメータ
char *name は、名前 - 値ペアの名前です。
関連項目
pblock_create、pblock_copy、pblock_find、pblock_free、pblock_nvinsert、pblock_remove、request_header
pblock_free 関数は、指定された pblock とその中のすべてのエントリを解放します。その pblock 中の変数を保存する必要がある場合は、pblock_remove 関数を使ってその変数を削除し、その結果のポインタを保存します。
構文
void pblock_free(pblock *pb);
パラメータ
pblock *pb は、解放する pblock です。
関連項目
pblock_copy、pblock_create、pblock_dup、pblock_find、pblock_findval、pblock_nvinsert、pblock_remove
pblock_nninsert 関数は、指定された pblock に指定された名前と数値で新しいエントリを作成します。数値は、最初に文字列に変換されます。名前と値のパラメータがコピーされます。
構文
pb_param *pblock_nninsert(char *name, int value, pblock *pb);
戻り値
新しい pb_param 構造体へのポインタを返します。
パラメータ
char *name は、新しいエントリの名前です。int value は、pblock に挿入される数値です。このパラメータは、整数である必要があります。割り当てた値が数値でない場合は、代わりに pblock_nvinsert 関数を使ってパラメータを作成します。
関連項目
pblock_copy、pblock_create、pblock_find、pblock_free、pblock_nvinsert、pblock_remove、pblock_str2pblock
pblock_nvinsert 関数は、指定された pblock に指定された名前と文字値で新しいエントリを作成します。名前と値のパラメータがコピーされます。
構文
pb_param *pblock_nvinsert(char *name, char *value, pblock *pb);
戻り値
新たに割り当てられた pb_param 構造体へのポインタを返します。
パラメータ
char *name は、新しいエントリの名前です。
例
pblock_nvinsert("content-type", "text/html", rq->srvhdrs);
関連項目
pblock_copy、pblock_create、pblock_find、pblock_free、pblock_nninsert、pblock_remove、pblock_str2pblock
pblock_pb2env 関数は、指定された pblock を指定された環境にコピーします。この関数は、pblock 内の名前 - 値のペアごとに、1 つ新しい環境エントリを作成します。この関数を使って、実行するプログラムに pblock エントリを送信します。
構文
char **pblock_pb2env(pblock *pb, char **env);
パラメータ
pblock *pb は、コピーする pblock です。char **env は、pblock のコピー先の環境です。
関連項目
pblock_copy、pblock_create、pblock_find、pblock_free、pblock_nvinsert、pblock_remove、pblock_str2pblock
pblock_pblock2str 関数は、指定された pblock のすべてのパラメータを指定された文字列にコピーします。この関数は、必要に応じて、その文字列に対してヒープでない追加領域を割り当てます。
保存およびその他の目的でpblock をストリーミングするには、この関数を使います。
構文
char *pblock_pblock2str(pblock *pb, char *str);
戻り値
str パラメータの新しいバージョンです。str が NULL の場合は、新しい文字列です。NULL でない場合は、再度割り当てられた文字列です。どちらの場合も、要求のメモリープールから割り当てられます。
パラメータ
pblock *pb は、コピーされる pblock です。char *str は、pblock のコピー先の文字列です。これは、PERM_MALLOC または PERM_REALLOC (システムヒープから割り当てられる) ではなく、MALLOC または REALLOC で割り当てられている必要があります。
文字列内の各名前 - 値ペアは、ほかのペアとは空白文字で区切られ、name="value" の形式になります。
関連項目
pblock_copy、pblock_create、pblock_find、pblock_free、pblock_nvinsert、pblock_remove、pblock_str2pblock
pblock_pinsert 関数は、pb_param 構造体を pblock に挿入します。
構文
void pblock_pinsert(pb_param *pp, pblock *pb);
パラメータ
pb_param *pp は、挿入する pb_param 構造体です。
関連項目
pblock_copy、pblock_create、pblock_find、pblock_free、pblock_nvinsert、pblock_remove、pblock_str2pblock
pblock_remove 関数は、指定された pblock から指定された名前 - 値エントリを削除します。この関数を使う場合は、pb_param 構造体が使ったメモリーの割り当てを解除するために最終的に param_free を呼び出す必要があります。
構文
pb_param *pblock_remove(char *name, pblock *pb);
戻り値
見つかった場合は指定された pb_param 構造体へのポインタを返し、指定された pb_param が見つからなかった場合は NULL を返します。
パラメータ
char *name は、削除する pb_param の名前です。pblock *pb は、名前 - 値エントリが削除される pblock です。
関連項目
pblock_copy、pblock_create、pblock_find、pblock_free、pblock_nvinsert、param_create、param_free
pblock_str2pblock 関数は、文字列でパラメータペアを走査し、見つかったペアを pblock に追加して、追加したパラメータの数を返します。
構文
int pblock_str2pblock(char *str, pblock *pb);
戻り値
追加されたものがある場合はpblock に追加されたパラメータペアの数を返し、エラーが発生した場合は -1 を返します。文字列内の名前 - 値ペアの形式は、 name=value または name="value" です。
バックスラッシュ (\) にはすべて、リテラル文字を続ける必要があります。文字列値にアンエスケープされた = 記号がない (name=がない) 場合、この関数は文字列内の位置により名前が 1、2、3 などになるとみなします。たとえば、pblock_str2pblock は、"some strings together" を見つけると、この関数はこの文字列が 1="some" 2="strings" 3="together" の名前 - 値ペアとして現れたかのように扱います。
pblock *pb は、名前 - 値ペアが格納される pblock です。
関連項目
pblock_copy、pblock_create、pblock_find、pblock_free、pblock_nvinsert、pblock_remove、pblock_pblock2str
PERM_CALLOC マクロは、C ライブラリルーチンの calloc のプラットフォームに依存しないものです。この関数は、要求の処理の完了後も持続する、num*size バイトのメモリーを割り当てます。プールされたメモリーが構成ファイルで (組み込み SAF の pool-init を使って) 無効にされている場合は、PERM_CALLOC および CALLOC はどちらもシステムヒープからメモリーを取得します。
構文
void *PERM_CALLOC(int num, int size)
戻り値
メモリーのブロックへの void 型のポインタを返します。
例
/* 100 個の char 型のポインタの配列に領域を割り当てる */
char *name;
name = (char *) PERM_CALLOC(100, sizeof(char *));
関連項目
PERM_FREE、PERM_STRDUP、PERM_MALLOC、PERM_REALLOC、MALLOC、FREE、CALLOC、STRDUP、REALLOC
PERM_FREE マクロは、C ライブラリルーチンの free のプラットフォームに依存しないものです。この関数は、PERM_MALLOC、PERM_CALLOC、または PERM_STRDUP で前に割り当てられた持続領域の割り当てを解除します。プールされたメモリーが構成ファイルで (組み込み SAF の pool-init を使って) 無効にされている場合は、PERM_FREE および FREE はシステムヒープ内のメモリーの割り当てを解除します。
パラメータ
void *ptr は、メモリーのブロックへの (void *) ポインタです。ポインタが PERM_MALLOC、PERM_CALLOC、または PERM_STRDUP で作成されたものでない場合は、動作は定義されていません。
例
char *name;
name = (char *) PERM_MALLOC(256);
...
PERM_FREE(name);
関連項目
FREE、MALLOC、CALLOC、REALLOC、STRDUP、PERM_MALLOC、PERM_CALLOC、PERM_REALLOC、PERM_STRDUP
PERM_MALLOC マクロは、C ライブラリルーチンの malloc のプラットフォームに依存しないものです。この関数は、要求の処理の完了後も持続する、メモリーの割り当てを可能にします。プールされたメモリーが構成ファイルで (組み込み SAF の pool-init を使って) 無効にされている場合は、PERM_MALLOC および MALLOC はどちらもシステムヒープからメモリーを取得します。
構文
void *PERM_MALLOC(int size)
戻り値
メモリーのブロックへの void 型のポインタを返します。
例
/* name に 256 バイトを割り当てる */
char *name;
name = (char *) PERM_MALLOC(256);
関連項目
PERM_FREE、PERM_STRDUP、PERM_CALLOC、PERM_REALLOC、MALLOC、FREE、CALLOC、STRDUP、REALLOC
PERM_REALLOC マクロは、C ライブラリルーチンの realloc のプラットフォームに依存しないものです。もともと PERM_MALLOC、PERM_CALLOC、または PERM_STRDUP で作成された、指定されたメモリーブロックのサイズを変更します。オブジェクトの内容は、古いサイズと新しいサイズのどちらか小さい方まで、変わりません。新しいサイズの方が大きい場合は、新しい領域は初期化されていません。
警告
MALLOC、CALLOC、または STRDUP で割り当てられたブロックに対して、PERM_REALLOC を呼び出しても動作しません。
構文
void *PERM_REALLOC(void *ptr, int size)
戻り値
メモリーのブロックへの void 型のポインタを返します。
パラメータ
void *ptr は、PERM_MALLOC、PERM_CALLOC、または PERM_STRDUP で作成されたメモリーのブロックへの void 型のポインタです。int size は、メモリーのブロックの大きさをそれへ変更する、バイト数です。
例
char *name;
name = (char *) PERM_MALLOC(256);
if (NotBigEnough())
name = (char *) PERM_REALLOC(name, 512);
関連項目
PERM_MALLOC、PERM_FREE、PERM_CALLOC、PERM_STRDUP、MALLOC、FREE、STRDUP、CALLOC、REALLOC
PERM_STRDUP マクロは、C ライブラリルーチンの strdup のプラットフォームに依存しないものです。この関数は、要求の処理の完了後も持続する、メモリー内の文字列の新しいコピーを作成します。プールされたメモリーが構成ファイルで (組み込み SAF の pool-init を使って) 無効にされている場合は、PERM_STRDUP および STRDUP はどちらもシステムヒープからメモリーを取得します。
PERM_STRDUP ルーチンの機能は、次の関数のシーケンスを実行する場合と同じです。
newstr = (char *) PERM_MALLOC(strlen(str) + 1); strcpy(newstr, str); PERM_STRDUP で作成した文字列は、PERM_FREE で破棄する必要があります。
構文
char *PERM_STRDUP(char *ptr);
パラメータ
char *ptr は、文字列へのポインタです。
関連項目
PERM_MALLOC、PERM_FREE、PERM_CALLOC、PERM_REALLOC、MALLOC、FREE、STRDUP、CALLOC、REALLOC
prepare_nsapi_thread 関数は、サーバが作成していないスレッドが、サーバが作成したスレッドのように動作できるようにします。サーバが作成していないスレッドから 他の NSAPI 関数を呼び出す前に、この関数を呼び出す必要があります。
構文
void prepare_nsapi_thread(Request *rq, Session *sn);
パラメータ
Request *rq は、Request です。Request および Session パラメータは、カスタム SAF に渡されるものと同じです。
protocol_dump822 関数は、ヘッダーを指定された pblock から、特定のバッファへ、指定された位置に指定されたサイズでプリントします。たとえばメールメッセージなど、ヘッダーを直列化して送ることができるようにする場合は、この関数を使います。
構文
char *protocol_dump822(pblock *pb, char *t, int *pos, int tsz);
戻り値
必要に応じて再割り当てされる、バッファへのポインタを返します。また、この関数は、バッファ内でヘッダーの終わりまで *pos を変更します。
パラメータ
pblock *pb は、pblock 構造体です。char *t は、MALLOC、CALLOC、または STRDUP で割り当てられたバッファです。
int *pos は、ヘッダーがダンプされる、バッファ内の位置です。
関連項目
protocol_start_response、protocol_status
protocol_set_finfo 関数は、指定された stat 構造体から content-length および last-modified 日付を取得し、応答ヘッダー (rq->srvhdrs) に追加します。protocol_start_response を呼び出す前に、protocol_set_finfo を呼び出します。
構文
int protocol_set_finfo(Session *sn, Request *rq, struct stat *finfo);
戻り値
要求の処理を正しく進めることができる場合は定数の REQ_PROCEED を返し、関数が要求を正しく処理する必要があるが、出力をクライアントへ送ってはならない場合は定数の REQ_ABORTED を返します。
パラメータ
Session *sn は、Session です。Session および Request パラメータは、カスタム SAF に渡されるものと同じです。
stat *finfo は、ファイルの stat 構造体です。
stat 構造体には、ファイルシステムからのファイルについての情報が入っています。request_stat_path を使って、stat 構造体の情報を取得できます。
関連項目
protocol_start_response、protocol_status
protocol_start_response 関数は、指定されたセッションおよび要求に対して HTTP 応答を開始します。プロトコルのバージョンが HTTP/0.9 である場合は、この関数は何もしません。これは、このバージョンにはステータスの概念がないためです。プロトコルのバージョンが HTTP/1.0 である場合は、この関数はステータス行に応答ヘッダーを続けて送信します。この関数を使って、HTTP を設定し、クライアントおよびサーバが応答の本体 (つまり、データ) を受信できるように準備します。
構文
int protocol_start_response(Session *sn, Request *rq);
戻り値
操作が成功した場合は定数の REQ_PROCEED を返し、この場合は送信のために準備したデータを送信する必要があります。操作が成功したが要求メソッドが HEAD であったため、データをクライアントに送らない場合は、定数の REQ_NOACTION を返します。
操作が失敗した場合は、定数の REQ_ABORTED を返します。
パラメータ
Session *sn は、Session です。Session および Request パラメータは、カスタム SAF に渡されるものと同じです。
例
/* この関数からの noaction 応答は、要求が HEAD であったことを示す */
if (protocol_start_response(sn, rq) == REQ_NOACTION) {
filebuf_close(groupbuf); /* ファイルを閉じる*/
return REQ_PROCEED;
}
protocol_status 関数は、エラー状態が発生したかどうかを示すセッションの状態を設定します。原因を示す文字列が NULL である場合は、サーバは、指定された状態コードに対する原因を示す文字列の検索を試みます。原因を示す文字列が見つからない場合は、"Unknown reason" を返します。原因を示す文字列は、HTTP 応答行でクライアントへ送られます。protocol_start_response 関数を呼び出す前に、この関数を使って、応答の状態を設定します。
すべての有効な状態コードの定数のリストは、サーバに付属するnsapi.hファイルを参照してください。
構文
void protocol_status(Session *sn, Request *rq, int n, char *r);
戻り値
void を返します。しかし、この関数は状態コードと原因を示す文字列用の sn/rq で指定された Session/Request に値を設定します。
パラメータ
Session *sn は、Session です。Session および Request パラメータは、カスタム SAF に渡されるものと同じです。
例
/* 余分なパス情報が見つかった場合は、URL が適切でなかったため、 */
/* ブラウザに URL が見つからなかったと通知する */
if (t = pblock_findval("path-info", rq->vars)) {
protocol_status(sn, rq, PROTOCOL_NOT_FOUND, NULL);
log_error(LOG_WARN, "function-name", sn, rq, "%s not found",
path);
return REQ_ABORTED;
}
protocol_uri2url 関数は、指定された URI 接頭辞および URI 接尾辞が含まれている文字列を受け取り、http://(server):(port)(prefix)(suffix) の形式で新たに割り当てられる絶対パスによる URL を作成します。protocol_uri2url_dynamic を参照してください。
URI 接頭辞または接尾辞のどちらかを省略する場合は、どちらかのパラメータの値として NULL ではなく "" を使います。
構文
char *protocol_uri2url(char *prefix, char *suffix);
関連項目
protocol_start_response、protocol_status、pblock_nvinsert、protocol_uri2url_dynamic
protocol_uri2url_dynamic 関数は、指定された URI 接頭辞および URI 接尾辞が含まれている文字列を受け取り、http://(server):(port)(prefix)(suffix) の形式で新たに割り当てられる絶対パスによる URL を作成します。
URI 接頭辞または接尾辞のどちらかを省略する場合は、どちらかのパラメータの値として NULL ではなく "" を使います。
protocol_uri2url_dynamic 関数は、protocol_uri2url 関数に似ていますが、Session および Request 構造体が利用できるときには常に使う必要があります。これにより、この関数が構築する URL が、確実にクライアントが指定したホストを参照するようになります。
構文
char *protocol_uri2url(char *prefix, char *suffix, Session *sn, Request *rq);Session および Request パラメータは、カスタム SAF に渡されるものと同じです。
関連項目
protocol_start_response、protocol_status、protocol_uri2urlREALLOC マクロは、C ライブラリルーチンの realloc のプラットフォームに依存しないものです。もともと MALLOC、CALLOC、または STRDUP で作成された、指定されたメモリーのブロックのサイズを変更します。オブジェクトの内容は、古いサイズと新しいサイズのどちらか小さい方まで、変わりません。新しいサイズの方が大きい場合は、新しい領域は初期化されていません。
警告
PERM_MALLOC、PERM_CALLOC、または PERM_STRDUP で割り当てられたブロックに対して、REALLOC を呼び出しても動作しません。
構文
void *REALLOC(void *ptr, int size);
戻り値
要求を満たすことができる場合は、新しい領域へのポインタを返します。
パラメータ
void *ptr は、メモリーのブロックへの (void *) ポインタです。ポインタが MALLOC、CALLOC、または STRDUP で作成されたものでない場合は、動作は定義されていません。
例
char *name;
name = (char *) MALLOC(256);
if (NotBigEnough())
name = (char *) REALLOC(name, 512);
関連項目
MALLOC、FREE、STRDUP、CALLOC、PERM_MALLOC、PERM_FREE、PERM_REALLOC、PERM_CALLOC、PERM_STRDUP
request_get_vs 関数は、要求の送信先の VirtualServer* を検索します。
返される VirtualServer* は、現在の要求に対してだけ有効です。すべての要求に有効な仮想サーバ ID を取得するには、vs_get_id を使います。
構文
const VirtualServer* request_get_vs(Request* rq);
戻り値
要求の送信先の VirtualServer* を返します。
パラメータ
Request *rq は、VirtualServer* が返される Request です。
関連項目
vs_get_id
request_header 関数は、クライアントの HTTP 要求ヘッダー (rq->headers) が含まれている pblock 内のエントリを検索します。クライアントのヘッダーにアクセスする場合は、pblock_findval ではなく、この関数を使う必要があります。これは、サーバが、ヘッダーがすべて読み込まれる前に要求の処理を開始することがあるためです。
構文
int request_header(char *name, char **value, Session *sn, Request *rq);
戻り値
ヘッダーが見つかった場合は REQ_PROCEED、ヘッダーが見つからない場合は REQ_ABORTED、クライアントからの読み込みでエラーが発生した場合は REQ_EXIT の結果コードを返します。char **value は、この関数が指定されたヘッダーの値を配置する場所のアドレスです。ヘッダーが見つからない場合は、NULL を格納します。
Session および Request パラメータは、カスタム SAF に渡されるものと同じです。
関連項目
request_create、request_free
request_stat_path 関数は、指定されたパスのファイル情報構造体を返し、パスが指定されない場合は、指定された Request 構造体内の vars pblock 内の path エントリを返します。結果のファイル名が、サーバが読み取ることができるファイルを指している場合は、request_stat_path は新しいファイル情報構造体を返します。この構造体には、ファイルのサイズ、所有者、作成日時、および最終更新の日時の情報が含まれています。
現在アクセスしているファイルの情報を取得するには、(直接 stat を呼び出す代わりに) request_stat_path を使う必要があります。これは、この関数が、同じパスに対する前の呼び出しを追跡し、キャッシュに書き込んでおいた情報を返すからです。
構文
struct stat *request_stat_path(char *path, Request *rq);
戻り値
path パラメータで指定されたファイルのファイル情報構造体へのポインタを返します。この構造体を解放してはなりません。ファイルが無効、またはサーバがファイルを読み取ることができない場合は、NULL を返します。この場合、問題を説明するエラーメッセージを rq->staterr に残します。
パラメータ
char *path は、パスの名前が含まれる文字列です。path の値が NULL である場合は、この関数は rq が示す Request 構造体内の vars pblock 内の path エントリを使います。Request *rq は、サーバアプリケーションの関数呼び出しに対する要求識別子です。
例
fi = request_stat_path(path, rq);
関連項目
request_create、request_free、request_header
request_translate_uri 関数は、指定されたセッションで指定された URI を仮想から物理へマッピングします。指定された URI がアクセスされたときに、どのファイルを送り返すべきか判断する際に、この関数を使います。
構文
char *request_translate_uri(char *uri, Session *sn);
戻り値
マッピングを実行した場合はパスの文字列を返し、マッピングを実行できなかった場合は NULL を返します。Session *sn は、カスタム SAF に渡される Session パラメータです。
関連項目
request_create、request_free、request_headersession_dns 関数は、指定されたセッションに関連するクライアントの IP アドレスを DNS 名に解釈処理します。この関数は、新たに割り当てられた文字列を返します。session_dns を使って、数字の IP アドレスを読みやすいものに変えることができます。
session_maxdns 関数は、クライアントが、本当に表明しているクライアントであるかを検証します。session_dns 関数は、この検証を実行しません。
注 この関数は、magnus.conf ファイルで DNS 指令が有効になっている場合にだけ機能します。詳細は、第 7 章「magnus.conf の構文と使用法」を参照してください。
構文
char *session_dns(Session *sn);
戻り値
ホスト名が含まれる文字列を返し、IP アドレスに対応する DNS 名が見つからない場合は NULL を返します。
パラメータ
Session *sn は、Session です。Session は、カスタム SAF に渡されるものと同じです。
session_maxdns 関数は、指定されたセッションに関連するクライアントの IP アドレスを DNS 名に解釈処理します。この関数は、新たに割り当てられた文字列を返します。session_maxdns を使って、数字の IP アドレスを読みやすい形式に変えることができます。
注 この関数は、magnus.conf ファイルで DNS 指令が有効になっている場合にだけ機能します。詳細は、第 7 章「magnus.conf の構文と使用法」を参照してください。
構文
char *session_maxdns(Session *sn);
戻り値
ホスト名が含まれる文字列を返し、IP アドレスに対応する DNS 名が見つからない場合は NULL を返します。
パラメータ
Session *sn は、Session です。Session は、カスタム SAF に渡されるものと同じです。
shexp_casecmp 関数は、指定されたシェル表現を検証し、指定された文字列と比較します。この関数は、一致、一致するものなし、および無効な比較を表す 3 つの値のどれか 1 つを返します。この比較では、 (shexp_cmp 関数とは異なり) 大文字 ‐ 小文字は区別されません。
*.netscape.com のようなシェル表現があり、foo.netscape.com などの文字列がそれに一致することを確認したい場合に、この関数を使います。
構文
int shexp_casecmp(char *str, char *exp);比較の結果、表現が無効とみなされた場合は、-1 を返します。
char *exp は、それに照らして比較されるシェル表現 (ワイルドカードパターン) です。
関連項目
shexp_cmp、shexp_match、shexp_valid
shexp_cmp 関数は、指定されたシェル表現を検証し、指定された文字列と比較します。この関数は、一致、一致するものなし、および無効な比較を表す 3 つの値のどれか 1 つを返します。この比較では、 (shexp_casecmp 関数とは異なり) 大文字 ‐ 小文字が区別されます。
*.netscape.com のようなシェル表現があり、foo.netscape.com などの文字列がそれに一致することを確認したい場合に、この関数を使います。
構文
int shexp_cmp(char *str, char *exp);比較の結果、表現が無効とみなされた場合は、-1 を返します。
char *exp は、それに照らして比較されるシェル表現 (ワイルドカードパターン) です。
例
/* このパスが必要としているパスであるかどうかを確認するために、ワイルドカードによるマッチングを使用する */
char *path;
char *match = "/usr/netscape/*";
if (shexp_cmp(path, match) != 0)
return REQ_NOACTION; /* 一致するものなし */
関連項目
shexp_casecmp、shexp_match、shexp_valid
shexp_match 関数は、指定された事前検証済みのシェル表現を指定された文字列と比較します。この関数は、一致、一致するものなし、および無効な比較を表す 3 つの値のどれか 1 つを返します。この比較では、 (shexp_casecmp 関数とは異なり) 大文字 ‐ 小文字が区別されます。
shexp_match 関数は、シェル表現の検証は実行しません。代わりに、この関数は、すでに shexp_valid が呼び出されたものとみなします。
*.netscape.com のようなシェル表現があり、foo.netscape.com などの文字列がそれに一致することを確認したい場合に、この関数を使います。
構文
int shexp_match(char *str, char *exp);比較の結果、表現が無効とみなされた場合は、-1 を返します。
char *exp は、それに照らして比較される、事前検証済みのシェル表現 (ワイルドカードパターン) です。
関連項目
shexp_casecmp、shexp_cmp、shexp_valid
shexp_valid 関数は、exp で指定された、指定されたシェル表現を検証します。shexp_match 関数を使って表現を文字列と比較する前に、この関数を使ってシェル表現を検証します。
構文
int shexp_valid(char *exp);
戻り値
exp が標準の文字列である場合は、定数の NON_SXP を返します。exp がシェル表現であるが無効な場合は、定数の INVALID_SXP を返します。
exp が有効なシェル表現である場合は、定数の VALID_SXP を返します。
パラメータ
char *exp は、それに照らして検証されるシェル表現 (ワイルドカードパターン) です。
関連項目
shexp_casecmp、shexp_match、shexp_valid
STRDUP マクロは、C ライブラリルーチンの strdup のプラットフォームに依存しないものです。この関数は、要求のメモリープールに文字列の新しいコピーを作成します。
STRDUP ルーチンの機能は、次の関数のシーケンスを実行する場合と同じです。
newstr = (char *) MALLOC(strlen(str) + 1);
strcpy(newstr, str);STRDUP で作成された文字列は、FREE で破棄する必要があります。
パラメータ
char *ptr は、文字列へのポインタです。
例
char *name1 = "MyName";
char *name2 = STRDUP(name1);
関連項目
MALLOC、FREE、CALLOC、REALLOC、PERM_MALLOC、PERM_FREE、PERM_CALOC、PERM_REALLOC、PERM_STRDUP
system_errmsg 関数は、最後のシステムコールから発生した最後のエラーを返します。この関数は、グローバル配列 sys_errlist からのエントリを返すマクロとして実装されています。このマクロは、入出力エラーの診断に役立ちます。
構文
char *system_errmsg(int param1);
戻り値
システムコールの結果である最後のエラーメッセージのテキストが入っている文字列を返します。この文字列を解放してはなりません。
パラメータ
int param1 は予約済みであり、値は常に 0 である必要があります。
関連項目
system_fopenRO、system_fopenRW、system_fopenWA、system_lseek、system_fread、system_fwrite、system_fwrite_atomic、system_flock、system_ulock、system_fclose
system_fclose 関数は、指定されたファイル記述子を閉じます。system_fopen 関数で開いたすべてのファイル記述子に対して、system_fclose 関数を呼び出す必要があります。
構文
int system_fclose(SYS_FILE fd);
戻り値
閉じるのに成功した場合は 0、閉じるのに失敗した場合は定数の IO_ERROR を返します。
パラメータ
SYS_FILE fd は、プラットフォームに依存しないファイル記述子です。
例
SYS_FILE logfd;
system_fclose(logfd);
関連項目
system_errmsg、system_fopenRO、system_fopenRW、system_fopenWA、system_lseek、system_fread、system_fwrite、system_fwrite_atomic、system_flock、system_ulock
system_flock 関数は、ほかのプロセスからの干渉を防止するために、指定されたファイルをロックします。現在開いてるファイルをほかのプロセスが使うことがないようにする場合は、system_flock を使います。ファイルロックを使いすぎると、パフォーマンスが低下し、デッドロックが生じることがあります。
構文
int system_flock(SYS_FILE fd);
戻り値
ロックが成功した場合は定数の IO_OKAY、ロックが失敗した場合は定数の IO_ERROR を返します。
パラメータ
SYS_FILE fd は、プラットフォームに依存しないファイル記述子です。
関連項目
system_errmsg、system_fopenRO、system_fopenRW、system_fopenWA、system_lseek、system_fread、system_fwrite、system_fwrite_atomic、system_ulock、system_fclose
system_fopenRO 関数は、path で示されたファイルを読み取り専用モードで開き、有効なファイル記述子を返します。ユーザのプログラムで変更されないファイルを開くには、この関数を使います。また、system_fopenRO を使って、filebuf_open を使用する新しいファイルバッファ構造体を開くことができます。
構文
SYS_FILE system_fopenRO(char *path);
戻り値
開くことに成功した場合はシステムに依存しないファイル記述子 (SYS_FILE)、開くことに失敗した場合は 0 を返します。
関連項目
system_errmsg、system_fopenRW、system_fopenWA、system_lseek、system_fread、system_fwrite、system_fwrite_atomic、system_flock、system_ulock、system_fclose
system_fopenRW 関数は、path で示されたファイルを読み込み - 書き込みモードで開き、有効なファイル記述子を返します。ファイルがすでに存在する場合は、system_fopenRW はそれを切り捨てません。ユーザのプログラムでの読み込み - 書き込みの対象になるファイルを開くには、この関数を使います。
構文
SYS_FILE system_fopenRW(char *path);
戻り値
開くことに成功した場合はシステムに依存しないファイル記述子 (SYS_FILE)、開くことに失敗した場合は 0 を返します。
例
SYS_FILE fd;
fd = system_fopenRO(pathname);
if (fd == SYS_ERROR_FD)
break;
関連項目
system_errmsg、system_fopenRO、system_fopenWA、system_lseek、system_fread、system_fwrite、system_fwrite_atomic、system_flock、system_ulock、system_fclose
system_fopenWA 関数は、path で示されたファイルを書き込み ‐ 付加モードで開き、有効なファイル記述子を返します。ユーザのプログラムがデータを付加するファイルを開くには、この関数を使います。
構文
SYS_FILE system_fopenWA(char *path);
戻り値
開くことに成功した場合はシステムに依存しないファイル記述子 (SYS_FILE)、開くことに失敗した場合は 0 を返します。
関連項目
system_errmsg、system_fopenRO、system_fopenRW、system_lseek、system_fread、system_fwrite、system_fwrite_atomic、system_flock、system_ulock、system_fclose
system_fread 関数は、指定されたバイトの数を指定されたファイルから指定されたバッファに読み込みます。読み込んだバイトの数を返します。system_fopenWA 以外のいずれかの system_fopen 関数を使ってファイルを開いてからでなければ、system_fread を使うことはできません。
構文
int system_fread(SYS_FILE fd, char *buf, int sz);
戻り値
読み込まれたバイトの数を返します。その数の文字を取得する前にエラーが発生したかファイルの終わりに達した場合は、要求されたサイズよりも小さいことがあります。
パラメータ
SYS_FILE fd は、プラットフォームに依存しないファイル記述子です。
関連項目
system_errmsg、system_fopenRO、system_fopenRW、system_fopenWA、system_lseek、system_fwrite、system_fwrite_atomic、system_flock、system_ulock、system_fclose
system_fwrite 関数は、指定されたバイトの数を指定されたバッファから指定されたファイルに書き込みます。
system_fopenRO 以外のいずれかの system_fopen 関数を使ってファイルを開いてからでなければ、system_fwrite を使うことはできません。
構文
int system_fwrite(SYS_FILE fd, char *buf, int sz);
戻り値
書き込みが成功した場合は定数の IO_OKAY、書き込みが失敗した場合は定数の IO_ERROR を返します。
パラメータ
SYS_FILE fd は、プラットフォームに依存しないファイル記述子です。char *buf は、書き込み対象のバイトが入っているバッファです。
関連項目
system_errmsg、system_fopenRO、system_fopenRW、system_fopenWA、system_lseek、system_fread、system_fwrite_atomic、system_flock、system_ulock、system_fclose
system_fwrite_atomic 関数は、指定されたバイトの数を指定されたバッファから指定されたファイルに書き込みます。この関数は、書き込みの前にファイルをロックし、書き込みが完了したらロックを解除して、同時の書き込み操作による干渉を防止します。system_fopenRO 以外のいずれかの system_fopen 関数を使ってファイルを開いてからでなければ、system_fwrite_atomic を使うことはできません。
構文
int system_fwrite_atomic(SYS_FILE fd, char *buf, int sz);
戻り値
書き込み / ロックが成功した場合は定数の IO_OKAY、書き込み / ロックが失敗した場合は定数の IO_ERROR を返します。
パラメータ
SYS_FILE fd は、プラットフォームに依存しないファイル記述子です。char *buf は、書き込み対象のバイトが入っているバッファです。
char *logmsg = "An error occurred.";
system_fwrite_atomic(logfd, logmsg, strlen(logmsg));
関連項目
system_errmsg、system_fopenRO、system_fopenRW、system_fopenWA、system_lseek、system_fread、system_fwrite、system_flock、system_ulock、system_fclose
system_gmtime 関数は、標準の gmtime 関数をスレッド安全にしたものです。グリニッチ標準時 (Greenwich Mean Time : GMT)に調整した現在の時刻を返します。
構文
struct tm *system_gmtime(const time_t *tp, const struct tm *res);
戻り値
GMT 時間を含む暦時間 (tm) 構造体へのポインタを返します。 使用しているシステムにより、このポインタは、2 番目のパラメータが表すデータ項目を指すか、または静的に割り当てられた項目を指すことがあります。可搬性のためには、どちらか一方の状況のみを想定してはなりません。tm *res は、暦時間 (tm) 構造体へのポインタです。
例
time_t tp;
struct tm res, *resp;
tp = time(NULL);
resp = system_gmtime(&tp, &res);
関連項目
system_localtime、util_strftime
system_localtime 関数は、標準の localtime 関数をスレッド安全にしたものです。現在の時間を現地時間で返します。
構文
struct tm *system_localtime(const time_t *tp, const struct tm *res);
戻り値
現地時間が含まれている暦時間 (tm) 構造体へのポインタを返します。 使用しているシステムにより、このポインタは、2 番目のパラメータが表すデータ項目を指すか、または静的に割り当てられた項目を指すことがあります。可搬性のためには、どちらか一方の状況のみを想定してはなりません。tm *res は、暦時間 (tm) 構造体へのポインタです。
関連項目
system_gmtime、util_strftime
system_lseek 関数は、ファイルのファイル位置を設定します。これは、system_fread または system_fwrite からのデータが読み込まれるか、または書き込まれる位置に影響します。
構文
int system_lseek(SYS_FILE fd, int offset, int whence);
戻り値
操作が成功した場合は、ファイルの先頭からの新しい位置のバイト単位のオフセット、操作が失敗した場合は -1 を返します。
パラメータ
SYS_FILE fd は、プラットフォームに依存しないファイル記述子です。int offset は、whence に相対するバイトの数です。負数の場合もあります。
関連項目
system_errmsg、system_fopenRO、system_fopenRW、system_fopenWA、system_fread、system_fwrite、system_fwrite_atomic、system_flock、system_ulock、system_fclose
system_rename 関数は、ファイルの名前を変更します。古いディレクトリと新しいディレクトリが異なるファイルシステムにある場合、そのディレクトリでは、この関数が機能しないことがあります。
構文
int system_rename(char *old, char *new);
戻り値
操作が成功した場合は 0、操作が失敗した場合は -1 を返します。
パラメータ
char *old は、ファイルの古い名前です。
system_ulock 関数は、system_flock 関数でロックされた、指定されたファイルのロックを解除します。ロックについての詳細は、system_flock を参照してください。
構文
int system_ulock(SYS_FILE fd);
戻り値
操作が成功した場合は定数の IO_OKAY、操作が失敗した場合は定数の IO_ERROR を返します。
パラメータ
SYS_FILE fd は、プラットフォームに依存しないファイル記述子です。
関連項目
system_errmsg、system_fopenRO、system_fopenRW、system_fopenWA、system_fread、system_fwrite、system_fwrite_atomic、system_flock、system_fclose
system_unix2local 関数は、指定された UNIX 形式のパス名をローカルファイルシステムのパス名に変換します。ファイル名が UNIX 形式 (スラッシュが含まれているものなど) になっている場合に、Windows NT などの別のシステム上のファイルにアクセスする必要があるときに、この関数を使います。system_unix2local を使って、UNIX 形式のファイル名を Windows NT が受け入れる形式に変換できます。UNIX 環境では、この関数は何も実行しませんが、可搬性のために呼び出すことができます。
構文
char *system_unix2local(char *path, char *lp);
戻り値
ローカルファイルシステムのパスの文字列へのポインタを返します。
パラメータ
char *path は、変換される、 UNIX 形式のパス名です。パラメータ lp を割り当てる必要があり、このパラメータにはローカルパス名を入れるのに十分な領域が必要です。
関連項目
system_fclose、system_flock、system_fopenRO、system_fopenRW、system_fopenWA、system_fwrite
systhread_attach 関数は、既存のスレッドをプラットフォームに依存しないスレッドにします。
構文
SYS_THREAD systhread_attach(void);
戻り値
プラットフォームに依存しないスレッドへの SYS_THREAD ポインタを返します。
関連項目
systhread_current、systhread_getdata、systhread_init、systhread_newkey、systhread_setdata、systhread_sleep、systhread_start、systhread_timerset
systhread_current 関数は、現在のスレッドへのポインタを返します。
構文
SYS_THREAD systhread_current(void);
戻り値
現在のスレッドへの SYS_THREAD ポインタを返します。
関連項目
systhread_getdata、systhread_newkey、systhread_setdata、systhread_sleep、systhread_start、systhread_timerset
systhread_getdata 関数は、現在のスレッド内で指定された鍵に関連付けられたデータを取得します。
構文
void *systhread_getdata(int key);
戻り値
呼び出しが成功した場合は、key の同じ値を使って、現在のスレッドからの、 systhread_setkey 関数で前に使ったデータへのポインタを返します。たとえば、systhread_setkey 関数が、このセッション中に指定された鍵で呼び出されることがなかった場合など、呼び出しが失敗した場合は、NULL を返します。
パラメータ
int key は、systhread_setdata 関数で格納されたデータに関連付けられた値です。鍵は、systhread_newkey 関数で割り当てられます。
関連項目
systhread_current、systhread_newkey、systhread_setdata、systhread_sleep、systhread_start、systhread_timerset
systhread_newkey 関数は、スレッド専用データに新しい整数鍵 (識別子) を割り当てます。この鍵を使って、現在のスレッドにローカライズしたい変数を識別します。次に、systhread_setdata 関数を使って、 値を鍵に関連付けます。
構文
int systhread_newkey(void);
関連項目
systhread_current、systhread_getdata、systhread_setdata、systhread_sleep、systhread_start、systhread_timerset
systhread_setdata 関数は、データに現在のスレッドの指定された鍵番号を関連付けます。鍵は、systhread_newkey 関数で割り当てられます。
構文
void systhread_setdata(int key, void *data);void *data は、key の値に関連付けられるデータの文字列へのポインタです。
関連項目
systhread_current、systhread_getdata、systhread_newkey、systhread_sleep、systhread_start、systhread_timerset
systhread_sleep 関数は、呼び出し元スレッドを指定された期間休眠させます。
構文
void systhread_sleep(int milliseconds);
パラメータ
int milliseconds は、スレッドを休眠させるミリ秒単位の期間です。
関連項目
systhread_current、systhread_getdata、systhread_newkey、systhread_setdata、systhread_start、systhread_timerset
systhread_start 関数は、指定された優先順位でスレッドを作成し、指定されたバイト数のスタックを割り当て、指定された引数で指定された関数を呼び出します。
構文
SYS_THREAD systhread_start(int prio, int stksz,
void (*fn)(void *), void *arg);
戻り値
呼び出しが成功した場合は新しい SYS_THREAD ポインタ、呼び出しが失敗した場合は定数の SYS_THREAD_ERROR を返します。
パラメータ
int prio は、スレッドの優先順位です。優先順位は、システムに依存します。int stksz は、バイト単位のスタックのサイズです。stksz が 0 の場合は、この関数はデフォルトのサイズを割り当てます。
void (*fn)(void *) は、呼び出す関数です。
関連項目
systhread_current、systhread_getdata、systhread_newkey、systhread_setdata、systhread_sleep、systhread_timerset
systhread_timerset 関数は、スレッドシステムに対する割り込みタイマー間隔を開始またはリセットします。
ほとんどのシステムではタイマー間隔の変更は許可されていないので、この関数は、必ず実行しなければならないものではなく、提案とみなしてください。
構文
void systhread_timerset(int usec);
関連項目
systhread_current、systhread_getdata、systhread_newkey、systhread_setdata、systhread_sleep、systhread_start
UNIX のみ
util_can_exec 関数は、指定されたファイルを実行できるかどうかを調べ、1 (実行可能) または 0 を返します。この関数は、指定されたユーザおよびグループ ID でユーザがファイルを実行できるかどうかを調べます。exec システムコールを使ってプログラムを実行する前に、この関数を使います。
構文
int util_can_exec(struct stat *finfo, uid_t uid, gid_t gid);
戻り値
ファイルが実行可能である場合は 1、ファイルが実行可能でない場合は 0 を返します。
パラメータ
stat *finfo は、ファイルに関連付けられた stat 構造体です。gid_t gid は、UNIX のグループ ID です。uid とともに、gid_t gid は、UNIX ユーザのアクセス権を判定します。
関連項目
util_env_create、util_getline、util_hostname
util_chdir2path 関数は、現在のディレクトリを、ファイルにアクセスする指定されたディレクトリに変更します。
Windows NT 下で実行する場合は、クリティカルセクションを使って、複数のスレッドがこの関数を同時に呼び出すことがないようにします。
ファイルアクセスを若干速くしたい場合は、絶対パスを使う必要がないので、util_chdir2path を使います。
構文
int util_chdir2path(char *path);
戻り値
ディレクトリを変更した場合は 0、ディレクトリを変更できなかった場合は -1 を返します。
パラメータ
char *path は、ディレクトリの名前です。このパラメータは、書き込み可能な文字列である必要があります。
util_cookie_find 関数は、cookie 文字列で特定の cookie を検索し、その値を返します。
構文
char *util_cookie_find(char *cookie, char *name);
戻り値
成功した場合、cookie の NULL で終わっている値へのポインタを返します。失敗した場合は、NULL を返します。この関数は、名前と値を NULL で終わらせて、cookie 文字列パラメータを変更します。
パラメータ
char *cookie は、Cookie: 要求ヘッダーの値です。char *name は、値が取得対象の cookie の名前です。
util_env_find 関数は、名前で示された文字列を指定された環境で探し、関連付けられた値を返します。環境内のエントリを探すには、この関数を使います。
構文
char *util_env_find(char **env, char *name);
戻り値
見つかった場合は環境変数の値、文字列が見つからない場合は NULL を返します。
関連項目
util_env_replace、util_env_str、util_env_free、util_env_create
util_env_free 関数は、指定された環境を解放します。util_env_create 関数を使って作成した環境の割り当てを解除するには、この関数を使います。
構文
void util_env_free(char **env);
関連項目
util_env_replace、util_env_str、util_env_find、util_env_create
util_env_replace 関数は、指定された環境内にある名前で示される変数を、指定された値で置き換えます。環境内の設定の値を変更するには、この関数を使います。
構文
void util_env_replace(char **env, char *name, char *value);
関連項目
util_env_str、util_env_free、util_env_find、util_env_create
util_env_str 関数は、環境エントリを作成し、そのエントリを返します。この関数は、名前に含まれる英数字でない記号 (等号 = など) を検査しません。この関数を使って、新しい環境エントリを作成できます。
構文
char *util_env_str(char *name, char *value);
戻り値
名前 - 値ペアが入っている新しく割り当てられた文字列を返します。
パラメータ
char *name は、名前 - 値ペアの名前です。
関連項目
util_env_replace、util_env_free、util_env_find、util_env_create
util_getline 関数は、改行、またはキャリッジリターン / 改行で終わる文字列を検索するために、指定されたファイルバッファを走査します。文字列が指定されたバッファにコピーされ、 NULL で終わらせます。この関数は、文字列がバッファに格納されたか、エラーが検出されたか、またはファイルの終わりに達したかどうかを示す値を返します。
構成ファイルなどのテキストファイルからの行を走査するには、この関数を使います。
構文
int util_getline(filebuf *buf, int lineno, int maxlen, char *line);
戻り値
成功した場合は、0 を返します。line に文字列が入っています。ファイルの終わりに達した場合は、1 を返します。line に文字列が入っています。
エラーが発生した場合は -1 を返します。line には、エラーの説明が入っています。
パラメータ
filebuf *buf は、走査されるファイルバッファです。int lineno は、エラーが発生したときに、エラーメッセージに行番号をインクルードする_ために使います。呼び出し元は、行番号が確実に正しくなるようにする必要があります。
int maxlen は、line に書き込むことのできる文字の最大個数です。
char *line は、文字列を格納するバッファです。line の割り当てと割り当て解除は、ユーザの責任において行ないます。
関連項目
util_can_exec、util_env_create、util_hostname
util_hostname 関数は、ローカルホスト名を取得し、そのホスト名を文字列として返します。この関数は、絶対パスによるドメイン名を見つけることができなかった場合は、NULL を返します。この文字列を割り当て直すか、または解放できます。使用しているシステムの名前を調べるには、この関数を使います。
戻り値
絶対パスによるドメイン名が見つかった場合は、その名前が入っている文字列を返し、見つからなかった場合は NULL を返します。
util_is_mozilla 関数は、指定されたユーザ - エージェントのヘッダー文字列が、指定されたバージョン以上の Netscape ブラウザであるかどうかを調べ、そうである場合は 1、そうでない場合は 0 を返します。この関数は、1.56 > 1.5 のような曖昧さを避けるために、バージョンを指定するために文字列を使います。
構文
int util_is_mozilla(char *ua, char *major, char *minor);
戻り値
ユーザ - エージェントが Netscape ブラウザである場合は 1、そうでない場合は 0 を返します。
パラメータ
char *ua は、要求ヘッダーからのユーザ - エージェント文字列です。char *major は、メジャーリリース番号 (小数点の左側) です。
char *minor は、マイナーリリース番号 (小数点の右側) です。
関連項目
util_is_url、util_later_than
util_is_url 関数は、文字列が URL であるかどうかを調べ、そうである場合は 1 を、そうでない場合は 0 を返します。英字で始まり後にコロンが続く場合は、文字列は URL です。
構文
int util_is_url(char *url);
戻り値
url で指定された文字列が URL である場合は 1、url で指定された文字列が URL でない場合は 0 を返します。
関連項目
util_is_mozilla、util_later_than
util_itoa 関数は、指定された整数を文字列に変換し、文字列の長さを返します。数のテキスト表現を作成するには、この関数を使います。
構文
int util_itoa(int i, char *a);char *a は、値を表す ASCII 文字列です。a の割り当てと割り当て解除はユーザの責任において行ない、また a の長さは少なくとも 32 バイトである必要があります。
util_later_than 関数は、time 構造体に指定された日付を、文字列内に指定された日付と比較します。文字列中の日付が time 構造体内の日付に等しいかそれ以降である場合は、この関数は 1 を返します。この関数は、RFC 822、RFC 850、および ctime 書式を処理するために使います。
構文
int util_later_than(struct tm *lms, char *ims);
戻り値
ims で表された日付が lms で表された日付と等しいかそれ以降である場合は 1、ims で表された日付が lms で表された日付よりも前の日付である場合は 0 を返します。
パラメータ
tm *lms は、日付が含まれている time 構造体です。
util_sh_escape 関数は、指定された文字列を構文解析し、シェル特殊文字の前にバックスラッシュ (\) を置き、その結果の文字列を返します。クライアントからの文字列が、シェルに予想外のことをさせないことを確実にするには、この関数を使います。
構文
char *util_sh_escape(char *s);
util_snprintf 関数は、printf 形式の構文を使い、範囲の確認を実行して、指定された文字列を指定された形式でフォーマットして、指定されたバッファに入れます。フォーマットされたバッファ内の文字の数を返します。
詳細は、使用しているコンパイラの実行時ライブラリの printf 関数についてのマニュアルを参照してください。
構文
int util_snprintf(char *s, int n, char *fmt, ...);
戻り値
フォーマットされバッファに入れられた文字の数を返します。
パラメータ
char *s は、フォーマットされた文字列を受け取るバッファです。char *fmt は、書式文字列です。この関数は、%d および %s 文字列のみを処理します。幅や精度の文字列は処理しません。
... は、printf 関数の一連のパラメータを表します。
関連項目
util_sprintf、util_vsnprintf、util_vsprintf
util_sprintf 関数は、printf 形式の構文を使い、範囲の確認を実行しないで、指定された文字列を指定された形式でフォーマットして、指定されたバッファに入れます。フォーマットされたバッファ内の文字の数を返します。
util_sprintf は範囲の確認を実行しないので、文字列がバッファに収まることが確かな場合にのみ、この関数を使います。そうでない場合は、util_snprintf 関数を使います。詳細は、使用しているコンパイラの実行時ライブラリの printf 関数についてのマニュアルを参照してください。
構文
int util_sprintf(char *s, char *fmt, ...);
戻り値
フォーマットされバッファに入れられた文字の数を返します。
パラメータ
char *s は、フォーマットされた文字列を受け取るバッファです。char *fmt は、書式文字列です。この関数は、%d および %s 文字列のみを処理します。幅や精度の文字列は処理しません。
... は、printf 関数の一連のパラメータを表します。
logmsg = (char *) MALLOC(256);
len = util_sprintf(logmsg, "%s %s %s\n", ip, method, uri);
関連項目
util_snprintf、util_vsnprintf、util_vsprintf
util_strcasecmp 関数は、2 つの英数字文字列を比較し、どちらが大きいか、または同一であるかを示す -1、0、または 1 を返します。
構文
int util_strcasecmp(const char *s1, const char *s2);
戻り値
s1 が s2 よりも大きい場合は、1 を返します。
util_strftime 関数は、システム時間を記述する構造体である tm 型の構造体をテキスト表現に変換します。この関数は、標準の strftime 関数をスレッド安全にしたものです。
構文
int util_strftime(char *s, const char *format, const struct tm *t);
戻り値
s に入れられた文字の数を返します。終わりの NULL 文字は、この数には含まれません。
パラメータ
char *s は、テキストを入れる文字列バッファです。範囲の確認は行なわれないので、必ずバッファが日付のテキストを入れるのに十分な大きさであるようにします。const char *format は書式文字列であり、特定の %x 部分文字列付きのテキストから構成されているという点で、少し printf 文字列に似ています。定数の HTTP_DATE_FMT を使って、標準のインターネット形式で日付文字列を作成できます。詳細は、使用しているコンパイラの実行時ライブラリの printf 関数についてのマニュアルを参照してください。時刻形式の詳細は、付録 D「時刻の書式」を参照してください。
const struct tm *t は、暦時間 (tm) 構造体へのポインタであり、この構造体は通常、関数 system_localtime または system_gmtime で作成されたものです。
関連項目
system_localtime、system_gmtime
util_strncasecmp 関数は、英数字文字列内の最初の n 文字を比較し、どちらが大きいか、または同一であるかを示す -1、0、または 1 を返します。
構文
int util_strncasecmp(const char *s1, const char *s2, int n);
戻り値
s1 が s2 よりも大きい場合は、1 を返します。
util_uri_escape 関数は、URI に含まれている特殊文字を URI 形式 (%XX、ここで XX は ASCII 文字に対応する 16 進数) に変換し、エスケープされた文字列を返します。特殊文字には、%?#:+&*"<>、空白文字、キャリッジリターン、および改行があります。
URI をクライアントへ送り返す前に、util_uri_escape を使います。
構文
char *util_uri_escape(char *d, char *s);
戻り値
エスケープされた文字で置き換えられた文字列 (おそらく新たに割り当てられたもの) を返します。
パラメータ
char *d は、文字列です。d が NULL でない場合は、この関数はフォーマットされた文字列を d にコピーしてそれを返します。d が NULL である場合は、この関数は適切なサイズにされた文字列を割り当て、フォーマットされた特殊文字を新しい文字列にコピーしてそれを返します。util_uri_escape 関数は、パラメータ d に対する範囲を確認しません。したがって、d が NULL でない場合、d は文字列 s の少なくとも 3 倍の大きさである必要があります。
char *s は、もとのエスケープされていない URI が含まれている文字列です。
関連項目
util_uri_is_evil、util_uri_parse、util_uri_unescape
util_uri_is_evil 関数は、指定された URI に不確実なパス文字が含まれていないかを調べます。不確実なパス文字には、URI の終わりにある //、/./、/../ および /.、/.. (また NT の場合は ./) などがあります。クライアントが要求した URI が不確実でないかどうかを確認するには、この関数を使います。
構文
int util_uri_is_evil(char *t);
戻り値
URI が不確実な場合は 1、URI が OK である場合は 0 を返します。
関連項目
util_uri_escape、util_uri_parse
util_uri_parse 関数は、指定された URI に含まれている //、/./、および /*/../ ( * は / 以外の任意の文字) を、/ に変換します。 この関数を使って、URI の不良シーケンスを有効なシーケンスに変換できます。まず、util_uri_is_evil 関数を使って、その関数に不良シーケンスがあるかどうかを調べます。
構文
void util_uri_parse(char *uri);
パラメータ
char *uri は、変換される URI です。
関連項目
util_uri_is_evil、util_uri_unescape
util_uri_unescape 関数は、URI のコード化された文字を対応する ASCII の文字に変換します。コード化された文字は %XX として現れます。ここで XX は、その文字に対応する 16 進数です。
注 NSAPI 関数は、NULL は文字列の終わりであるとみなすので、文字列中に NULL を埋め込むことはできません。したがって、NSAPI プラグインで Unicode でコード化された内容を渡しても動作しません。
構文
void util_uri_unescape(char *uri);
パラメータ
char *uri は、変換される URI です。
関連項目
util_uri_escape、util_uri_is_evil、util_uri_parse
util_vsnprintf 関数は、vprintf 形式の構文を使い、範囲の確認を実行して、指定された文字列を指定された形式でフォーマットして、指定されたバッファに入れます。フォーマットされたバッファ内の文字の数を返します。
詳細は、使用しているコンパイラの実行時ライブラリの vprintf 関数についてのマニュアルを参照してください。
構文
int util_vsnprintf(char *s, int n, register char *fmt, va_list args);
戻り値
フォーマットされバッファに入れられた文字の数を返します。
パラメータ
char *s は、フォーマットされた文字列を受け取るバッファです。register char *fmt は、書式文字列です。この関数は、%d および %s 文字列のみを処理します。幅や精度の文字列は処理しません。
va_list args は、前の va_start の呼び出しで取得した STD 引数変数です。
関連項目
util_sprintf、util_vsprintf
util_vsprintf 関数は、vprintf 形式の構文を使い、範囲の確認を実行しないで、指定された文字列を指定された形式でフォーマットして、指定されたバッファに入れます。フォーマットされたバッファ内の文字の数を返します。
詳細は、使用しているコンパイラの実行時ライブラリの vprintf 関数についてのマニュアルを参照してください。
構文
int util_vsprintf(char *s, register char *fmt, va_list args);
戻り値
フォーマットされバッファに入れられた文字の数を返します。
パラメータ
char *s は、フォーマットされた文字列を受け取るバッファです。register char *fmt は、書式文字列です。この関数は、%d および %s 文字列のみを処理します。幅や精度の文字列は処理しません。
va_list args は、前の va_start の呼び出しで取得した STD 引数変数です。
関連項目
util_snprintf、util_vsnprintfvs_alloc_slot 関数は、特定の VirtualServer* に固有のデータへのポインタを格納するための新しいスロットを割り当てます。返されるスロット番号は、この後の vs_set_data および vs_get_data の呼び出しで使うことができます。返されるスロット番号は、どの VirtualServer* にも有効です。
ポインタの値 (vs_set_data への呼び出しで返される) は、どのVirtualServer* の場合も、デフォルトで NULL になります。
戻り値
成功した場合はスロット番号、失敗した場合は -1 を返します。
関連項目
vs_get_data、vs_set_data
vs_get_data 関数は、指定された VirtualServer* と slot のデータへのポインタの値を検索します。slot は、vs_alloc_slot または vs_set_data から返されたスロット番号である必要があります。
構文
void* vs_get_data(const VirtualServer* vs, int slot);
戻り値
vs_set_data が前に格納したポインタの値を返し、失敗した場合は NULL を返します。
パラメータ
const VirtualServer* vs は、ポインタを照会検索する仮想サーバを表します。
関連項目
vs_set_data、vs_alloc_slot
vs_get_default_httpd_object 関数は、仮想サーバの httpd_objset (仮想サーバクラスの obj.conf ファイルで定義された構成) から、デフォルト (またはルート) の httpd_object へのポインタを取得します。デフォルトのオブジェクトの名前は、通常、default です。プラグインは、httpd_object を VSInitFunc 時にのみ変更できます (VSInitFunc 時については、vs_register_cb を参照してください)。
構文
httpd_object* vs_get_default_httpd_object(VirtualServer* vs);
戻り値
デフォルトの httpd_object へのポインタを返し、失敗した場合は NULL を返します。このオブジェクトを解放してはなりません。
パラメータ
VirtualServer* vs は、仮想サーバを表し、このサーバのためにデフォルトのオブジェクトを検索します。
関連項目
vs_get_httpd_objset、 vs_register_cb
vs_get_doc_root 関数は、仮想サーバのためにドキュメントルートを検索します。返される文字列は、ドキュメントルートへのオペレーティングシステムの絶対パスです。
呼び出し元は、返された文字列を使い終わったら解放する必要があります。
構文
char* vs_get_doc_root(const VirtualServer* vs);
戻り値
ドキュメントルートへのオペレーティングシステムの絶対パスを表す文字列へのポインタを返します。この文字列の解放は、呼び出し元の責任において行ないます。
パラメータ
const VirtualServer* vs は、仮想サーバを表し、このサーバのためにドキュメントのルートを検索します。
vs_get_httpd_objset 関数は、指定された仮想サーバのhttpd_objset (仮想サーバクラスの obj.conf ファイルで定義された構成) へのポインタを取得します。プラグインは、httpd_objset を VSInitFunc 時にのみ変更できます(VSInitFunc 時については、vs_register_cb を参照してください)。
構文
httpd_objset* vs_get_httpd_objset(VirtualServer* vs);
戻り値
httpd_objset へのポインタを返し、失敗した場合は NULL を返します。この objset を解放してはなりません。
パラメータ
VirtualServer* vs は、仮想サーバを表し、このサーバの objset を検索します。
関連項目
vs_get_default_httpd_object、vs_register_cb
vs_get_id 関数は、VirtualServer* の ID を検索します。
仮想サーバの ID は、構成間で一定の、一意の NULL で終わる文字列です。ID は構成間で一定ですが、VirtualServer* ポインタの値は変わります。
仮想サーバの ID 文字列を解放してはなりません。要求の処理中に呼び出された場合は、その文字列は現在の要求の間、有効です。VSInitFunc 処理中に呼び出された場合は、この文字列は対応する VSDestroyFunc 関数が復帰するまで有効です (vs_register_cbを参照)。
現在の要求にだけ有効な VirtualServer* を取得するには、request_get_vs を使います。
構文
const char* vs_get_id(const VirtualServer* vs);
戻り値
仮想サーバ ID を表す文字列へのポインタを返します。この文字列を解放してはなりません。
パラメータ
const VirtualServer* vs は、目的の仮想サーバを表します。
関連項目
vs_register_cb、 request_get_vs
vs_get_mime_type 関数は、指定された URI 内の Content-type: ヘッダー内に返される MIME タイプを判別します。
呼び出し元は、返された文字列を使い終わったら解放する必要があります。
構文
char* vs_get_mime_type(const VirtualServer* vs, const char* uri);
戻り値
MIME タイプを表す文字列へのポインタを返します。この文字列の解放は、呼び出し元の責任において行ないます。
パラメータ
const VirtualServer* vs は、目的の仮想サーバを表します。const char* uri は、MIME タイプが判別対象である URI です。
vs_lookup_config_var 関数は、指定された仮想サーバの構成変数の値を検索します。
構文
const char* vs_lookup_config_var(const VirtualServer* vs, const char* name);
戻り値
成功した場合は変数名の値を表す文字列へのポインタ、変数名が見つからない場合は NULL を返します。この文字列を解放してはなりません。
パラメータ
const VirtualServer* vs は、目的の仮想サーバを表します。
vs_register_cb 関数は、仮想サーバの初期化イベントおよび廃棄イベントの通知を受ける関数をプラグインが登録できるようにします。vs_register_cb 関数は、通常、magnus.conf 内の Init SAF から呼び出されます。
新しい構成が読み込まれると、新しい構成から要求がサービスを受ける前に、登録されたすべての VSInitFunc (仮想サーバの初期化) コールバックが、各仮想サーバに対して呼び出されます。VSInitFunc コールバックは、登録された順序と同じ順序で呼び出されます。つまり、最初に登録されたコールバックが、最初に呼び出されます。
最後の要求が古い構成からサービスを受けたら、仮想サーバが廃棄される前に、各仮想サーバに対してすべての登録された VSDestroyFunc (仮想サーバの廃棄) コールバックが呼び出されます。VSDestroyFunc コールバックは、逆の順序で呼び出されます。つまり、最初に登録されたコールバックが、最後に呼び出されます。
呼び出し元が初期化または廃棄のためのコールバックを必要としない場合は、それぞれに対応する initfn または destroyfn を NULL にすることができます。
構文
int vs_register_cb(VSInitFunc* initfn, VSDestroyFunc* destroyfn);
戻り値
操作が成功した場合は、定数の REQ_PROCEED を返します。操作が失敗した場合は、定数の REQ_ABORTED を返します。
パラメータ
VSInitFunc* initfn は、仮想サーバの初期化時に呼び出す関数へのポインタです。呼び出し元が仮想サーバの初期化イベントを必要としない場合は NULL です。VSDestroyFunc* destroyfn は、仮想サーバの廃棄時に呼び出す関数へのポインタです。呼び出し元が仮想サーバの廃棄イベントを必要としない場合は NULL です。
vs_set_data 関数は、指定された仮想サーバおよびスロットのデータへのポインタの値を設定します。*slot は、-1、または vs_alloc_slot から返されるスロット番号でなければなりません。*slot が -1 の場合は、vs_set_data は vs_alloc_slot を暗黙に呼び出し、新しいスロット番号を *slot に返します。
格納されたポインタは、ID ごとではなく、VirtualServer* ごとに維持されます。異なる構成からの、異なる VirtualServer* が同じ仮想サーバ ID で同時に存在できます。ただし、それらは異なる VirtualServer* であるため、それぞれに専用の VirtualServer* 固有のデータがあります。その結果、一般に、vs_set_data を VSInitFunc 処理外で呼び出してはなりません(VSInitFunc 処理については、vs_register_cb を参照してください)。
構文
void* vs_set_data(const VirtualServer* vs, int* slot, void* data);
戻り値
成功した場合はデータ、失敗した場合は NULL を返します。
パラメータ
const VirtualServer* vs は、仮想サーバを表し、このサーバのためにポインタを設定します。
関連項目
vs_get_data、 vs_alloc_slot、vs_register_cb
vs_translate_uri 関数は、特定の仮想サーバに対する要求の一部であるかのように URI を変換します。返される文字列は、オペレーティングシステムの絶対パスです。
呼び出し元は、返された文字列を使い終わったら解放する必要があります。
構文
char* vs_translate_uri(const VirtualServer* vs, const char* uri);
戻り値
指定された URI に対するオペレーティングシステムの絶対パスを表す文字列へのポインタを返します。この文字列を解放するのは、呼び出し元の責任です。
パラメータ
const VirtualServer* vs は、仮想サーバを表し、このサーバのために URI を変換します。const char* uri は、オペレーティングシステムのパスに変換する URI です。
前へ 目次 索引 DocHome 次へ
Copyright © 2000 Sun Microsystems, Inc. Some preexisting portions Copyright © 2000 Netscape Communications Corp. All rights reserved.
Last Updated September 24, 2001