名称

libstand — スタンドアローン (独立型) 実行のためのサポートライブラリ

書式

#include < stand.h>

解説

libstand ライブラリは、標準 BSD プログラミング環境をできるだけ模擬する、スタンドアローンアプリケーションのサポート関数のセットを提供します。次のセクションでこれらの関数の種類をグループ化します。ここに明確な記述がない場合は、与えられた関数の対応するセクション 3 のマニュアルページを参照して下さい。

文字列関数

文字列関数は、 string(3) および bstring(3) で文書化されるように利用可能です。

メモリ割り付け

void * malloc( size_t size)

best-fit アルゴリズムを使ってヒープ (領域) からメモリを size バイト割り付けます。

void free( void *ptr)

ptr に割り付けられたオブジェクトを解放します。

void setheap( void *start, void *limit)

ヒープ (領域) を初期化します。この関数は、最初に alloc() を呼び出す前に呼び出さなければなりません。 start と limit の間の領域がヒープ (領域) に使用されます。これを越えて割り付ける試みは、panic となります。

char * sbrk( int junk)

sbrk( 0) の振る舞いを提供します。すなわちヒープ (領域) が到達する最高位のポイント (アドレス) を返します。この値は、テスト中に実際のヒープ利用を判断するために使用できます。 junk 引数は、無視されます。

環境

ひとそろいの関数は、伝統的なシェルサポート環境に似た、フラットな変数空間を操作のために提供されます。主な拡張は、フック関数の設定／設定解除のためのサポートです。

char * getenv( const char *name)

int setenv( const char *name, const char *value, int overwrite)

int putenv( const char *string)

int unsetenv( const char *name)

これらの関数は、標準ライブラリに対応する類似の動作をします。

struct env_var * env_getenv( const char *name)

環境中の変数を検索し、すべてのデータ構造を返します。

int env_setenv( const char *name, int flags, const void *value, ev_sethook_t sethook, ev_unsethook_t unsethook)

name と呼ばれる環境変数を新規作成するか、既存の環境変数を設定します。新規の変数を作成する場合は、 sethook および unsethook 引数を指定できます。

EV_NOHOOK フラグが設定されていなければ、変数を設定する試みが行なわれる場合は、常に、フックの設定が呼び出されます。通常、フックの設定は、 value 引数の正当性を確認し、実際に値を保存するために EV_NOHOOK 設定をつけて、再度 env_setenv() 呼び出します。定義済み関数 env_noset() は、変数設定のすべての試みを拒絶するために指定できます。

設定解除フックは、変数の設定解除の試みが行われるときに呼び出されます。 0 を返すとき、変数は、設定解除されます。定義済み関数 env_nounset は、設定解除されている変数を防止するために使用できます。

標準ライブラリサポート

int getopt( int argc, char * const *argv, const char *optstring)

long strtol( const char *nptr, char **endptr, int base)

void srandom( unsigned long seed)

unsigned long random( void)

char * strerror( int error)

libstand でサポートされている errno 値のサブセットのためのエラーメッセージを返します。

assert( expression)

< assert.h> が必要です。

int setjmp( jmp_buf env)

void longjmp( jmp_buf env, int val)

操作できるシグナル状態がないため、それぞれ _setjmp() および _longjmp() として定義されています。 < setjmp.h> が必要です。

文字 I/O (入出力)

void gets( char *buf)

文字をコンソールから buf に読み込みます。標準の注意は、すべてこの関数に当てはまります。

void ngets( char *buf, int size)

多くても size -1 文字をコンソールから buf に読み込みます。 size が 1 以下の場合、関数の振る舞いは、 gets() と同じです。

int fgetstr( char *buf, int size, int fd)

一行を多くても size 文字を buf に読み込みます。行末の文字は、切り捨てられ、バッファは、常に ヌル文字 が終端となります。成功すれば、 buf の中の文字数を返し、エラーが生じれば -1 を返します。

int printf( const char *fmt, ...)

void vprintf( const char *fmt, va_list ap)

int sprintf( char *buf, const char *fmt, ...)

void vsprintf( char *buf, const char *fmt, va_list ap)

*printf 関数は、標準 printf() ファミリ機能といくつかの拡張のサブセットを実装しています。 c,d,n,o,p,s,u,x の標準変換がサポートされています。 +,-,#,*,0,フィールド幅,精度,l の修飾子がサポートされています。

b 変換は、エラーレジスタをデコード (解読) するために提供されます。使い方は、次の通りです。

printf( “reg=%b\n”, regval, “<base><arg>*” );

ここで、 <base>は、制御文字の出力を表現です。例えば、\10 は、8 進数を、\20 は、16 進数を意味します。各 <arg>は、文字の並びで、最初は、検査されるビット数 (始めが 1) で、ビットが設定されている場合、次の (複数の) 文字 (32文字未満) は、表示対象のテキストです。したがって、

printf( “reg=%b\n”, 3, “\10\2BITTWO\1BITONE\n” );

は、次の出力が得られます。

reg=3<BITTWO,BITONE>

D 変換は、16 進数ダンプの機能を提供します。たとえば、

printf( “%6D”, ptr, “:” ); は、“XX:XX:XX:XX:XX:XX”となります。

printf( “%*D”, len, ptr, “ ” ); は、“XX XX XX ...”となります。

文字テストと変換

int isupper( int c)

int islower( int c)

int isspace( int c)

int isdigit( int c)

int isxdigit( int c)

int isascii( int c)

int isalpha( int c)

int toupper( int c)

int tolower( int c)

ファイル I/O (入出力)

int open( const char *path, int flags)

ファイル生成がサポートされないことを除いて open(2) で記述される振る舞いに似ています。したがって、モードパラメータは、要求されません。 flags 引数は、O_RDONLY, O_WRONLY, O_RDWR (たとえ、現在書き込みをサポートするファイルシステムが無くても) の 1 つを指定できます。

int close( int fd)

void closeall( void)

すべてのオープンされているファイルをクローズします。

ssize_t read( int fd, void *buf, size_t len)

ssize_t write( int fd, void *buf, size_t len)

(現在書き込みをサポートしているファイルシステムはありません。)

off_t lseek( int fd, off_t offset, int whence)

読み込み最中に自動的に展開されるファイルは、現在の位置から後方にシークすることはできません。

int stat( const char *path, struct stat *sb)

int fstat( int fd, struct stat *sb)

stat() および fstat() 関数は、 sb 構造体のフィールド st_mode, st_nlink,st_uid,st_gid,st_size のみ書き込みます。 tftp ファイルシステムは、この呼び出しのために意味のある値を提供できません。また cd9660 ファイルシステムは、ファイルが 0 の uid/gid があると常に報告します。

ページャ

libstand ライブラリは、大きなコマンドの出力を読みやすくするために簡単な内部ページャを供給します。

void pager_open()

ページャを初期化し、次の行出力が表示の先頭になることを伝えます。環境変数 LINES は、停止の前に表示される行の数を決定するために調べられます。

void pager_close( void)

ページャをクローズします。

int pager_output( const char *lines)

lines で指定された、 ヌル文字 で終了するバッファの行がページャに送られます。改行文字は、出力される行数を決定するために数えられます (折り返し行は、計上されません)。すべての行が出力されると、 pager_output() 関数は、0 を返します。表示が停止し、ユーザが終了を選んたときは、0 以外の値を返します。

int pager_file( const char *fname)

ファイル fname をオープンし、表示を試みます。エラーのときは、-1 を返し、EOF のときは、0 を、ユーザが読み込み終了を選んだ場合は、1 を返します。

雑多 (ミスク)

void twiddle( void)

連続する呼び出しは、ユーザに安心を提供するために文字の並び |,/,-,\ にバックスペースを続けてキラキラさせます。

低レベルサポートの要求

スタック、ヒープ、コンソール、デバイスは、 libstand でよく使われるリソースです。

スタックは、 libstand 関数が呼び出されることができる前に構築しなければなりません。スタック要求は、関数や消費者 (ユーザ) で使用されるファイルシステム、および、後で詳述するサポートレイヤ関数に依存して変化します。

ヒープは、 alloc() や open() の呼び出しの前に、 setheap() 呼び出しによって構築しなければなりません。ヒープの使用法は、クライアントの動作と同様、同時にオープンするファイルの数に依存して変化します。自動展開は、ファイルをオープンする毎に 64K 以上のデータが割り付けられます。

コンソールアクセスは、後述の getchar(), putchar(), ischar() 関数によって実行されます。

デバイスアクセスは、 devopen() によって初期化され、 devopen() が返すデバイススイッチ構造体中の dv_strategy(), dv_ioctl(), dv_close() 関数によって実行されます。

消費者 (ユーザ) は、次のサポート関数を用意しなければなりません。

int getchar( void)

gets(), ngets() やページャ関数によって使われるコンソールから文字を返します。

int ischar( void)

コンソールから文字を待っているとき、0 でない値を返します。

void putchar( int)

gets(), ngets(), *printf(), panic(), twiddle() によって使われ、したがって他の多くのデバッグ関数と情報出力に使われるコンソールに文字を書き込みます。

int devopen( struct open_file *of, const char *name, const char **file)

name で指定されたファイルのために適切なデバイスをオープンし、デバイスを参照しない name の残りの部分を指すポインタを file に返します。 of の中の f_dev フィールドは、成功した場合、オープンしたデバイスの devsw 構造体を指すように設定されます。デバイス識別子は、常にパス構成に先行しなければなりません。そうでなければ自由にフォーマットできます。 open() で使用され、したがってデバイス関連のすべての I/O で使用されます。

int devclose( struct open_file *of)

of に割り付けられたデバイスをクローズします。デバイスドライバ自身は、クローズのため呼び出しは、既に行われています。この呼び出しは、 devopen のみによって行なわれたどんな割り付も後片付けすべきです。

void panic( const char *msg, ...)

致命的で回復不能なエラー状態を示します。 msg ... 引数は、 printf() のものと同様です。

内部ファイルシステム

内部ファイルシステムは、配列 struct fs_ops *file_system[] を、消費者 (ユーザ) がエクスポートすることで可能になり、配列は、 struct fs_ops 構造体へのポインタで初期化すべきです。次のファイルシステムハンドラが libstand によって供給されます。消費者 (ユーザ) は、自分で別のファイルシステムを提供できます。

ufs_fsops

BSD の UFS。

ext2fs_fsops

Linux の ext2fs ファイルシステム。

tftp_fsops

TFTP 経由のファイルアクセス。

nfs_fsops

NFS 経由のファイルアクセス。

cd9660_fsops

ISO 9660 (CD-ROM) ファイルシステム。

gzipfs_fsops

gzip されたファイルをサポートするスタックファイルシステム。 gzipfs ファイルシステムを試みる場合、 libstand は、ファイル名の後に .gz を追加し、次に別のファイルシステムを使用してファイルの位置を見つけようと試みます。 file_system[] 配列中のこのファイルシステムの配置は、 gzip されたファイルが gzip されていないファイルに優先してオープンされるかどうか決定します。 gzip されたファイルは、前方へシークすることだけができ、 gzip されたファイルでの stat() および fstat() は、無効の長さを報告するでしょう。

bzipfs_fsops

gzipfs_fsops と同様ですが、 bzip2(1) で圧縮されたファイルを使用します。

構造体 struct fs_ops のポインタの配列は、NULL で終了しなければなりません。

デバイス

デバイスは、NULL で終了するデバイススイッチ構造体のポインタ配列である、 struct devsw *devsw[] 経由のサポートコードによってエクスポートされます。

歴史

libstand ライブラリは、次のものを含めて、多くのソースからのコントリビューション (寄贈) を含んでいます。

• NetBSD から libsa
• FreeBSD 3.0 から libc と libkern
• Matthew Dillon <dillon@backplane.com>から zalloc

再構成と FreeBSD 3.0 への移植、環境関数とこのマニュアルページは、 Mike Smith <msmith@FreeBSD.org>によって書かれました。

バグ

詳細なメモリ利用データの不足は、助けになりません。