libstand(3)

libstand − スタンドアローン実行用サポートライブラリ

#include <stand.h>

libstand は、スタンドアローンアプリケーションのサポート関数群と、標準 BSD プログラミングが可能な模擬環境を備えています。後のセクションでこれらの関 数を種類分けしています。ここに明確な定義がない場合は、指定の関数のセク ション 3 のマニュアルページの該当個所を参照して下さい。

使用できる文字列関数は、 string(3) および bstring(3) に書かれています。

void free(void *ptr)

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

void setheap(void *start, void *limit)

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

char * sbrk(int junk)

sbrk(0) の性質を与えます。すなわちヒープ領域の最高位アドレス のポインタを返します。この戻り値は、テスト時にヒープの実使用 状況を判断するのに使用できます。引数 junk は無視されます。

環境

伝統的なシェルサポート環境と同様、フラットな変数空間操作のために一群の関 数が備わっています。主な拡張として、フック関数の設定／設定解除のためのサ ポートがあります。

int setenv(const char *name, 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, char *value, ev_sethook_t sethook, ev_unsethook_t unsethook)

name という環境変数の新規作成または既存環境変数の設定を行いま す。新規変数を生成する場合は、引数 sethook および unsethook を指定することができます。

EV_NOHOOK フラグが設定されていなければ、変数設定をしようとす るとすると、フックの設定が必ず起動されます。通常、引数 value の確認を行ない、実際に値を保存するために EV_NOHOOK 変数をつけ て、再度 env_setenv() 呼び出しを行い設定します。すべての変数 設定を拒否するために、定義済み関数 env_noset() を指定すること ができます。

設定解除フックは、変数の設定解除が行われるときに起動されま す。戻り値が 0 のとき、変数の設定解除されています。定義済み関 数 env_nounset は、変数設定解除を抑制するのに使用します。

標準ライブラリサポート

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() および _lonjmp() として定義されています。 <setjmp.h> 行が必要です。

キャラクタ I/O

void ngets(char *buf, size_t 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, field width,precision,l の修 飾子がサポートされています。

エラーレジスタをデコードするために b 変換が備わっています。使 い方は以下の通りです。

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

⟨base⟩ は、制御キャラクタの出力を表現しています。例えば \10 は 10 進数を、\20 は 16 進数を意味します。各 ⟨arg⟩ は、文字列 で、最初の一文字は引数のビット数(始めが1)で、ビットが設定され ている場合、それ以降の文字列(32文字未満)は表示対象のテキスト です。つまり、

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

により出力表示されます。

reg=3<BITTWO,BITONE>

D 変換は、16 進数ダンプの機能を備えています。たとえば、以下。

printf( "%6D", ptr, ":" ); gives "XX:XX:XX:XX:XX:XX"

printf( "%*D", len, ptr, " " ); gives "XX XX XX ..."

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)

ファイル入出力

int close(int fd)

void closeall(void)

すべての open されているファイルを閉じます。

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)

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

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 ファイルシステムは、ファイル の uid/gid が常に 0 であると報告して来ます。

ページャ

libstand は簡単な内部ページャを提供し、大きなコマンドの出力を読みやすくし ます。

void pager_close(void)

ページャを閉じます

int pager_output(char *lines)

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

int pager_file(char *fname)

ファイル fname を開き、画面表示します。エラーのときは -1 を返 し、EOF のときは 0 を、ユーザが読み込みを途中終了する場合は 1 を返します。

その他

低レベルサポートの要求

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

スタックは、 libstand 関数が起動される前に構築する必要があります。スタッ ク要求は、関数や使われているファイルシステム、および、後で詳述するサポー トレイヤ関数によって変化します。

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

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

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

ユーザは次のサポート関数を用意する必要があります。

int ischar(void)

コンソールから入力待ちの状態のとき、0 でない値を返します。

void putchar(int)

コンソールに、 gets(), ngets(), *printf(), panic(), twiddle() および他の多くのデバッグ、情報通知用の関数が使用する文字を書 き出します。

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

name という名前のファイル用の適当なデバイスを開き、デバイスを 参照しないファイルの残りの部分の name を指すポインタを、 file に返します。 of の構造体フィールド f_dev は、正常終了した場 合、open したデバイスの 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 に備わっています が、ユーザは自分で別のファイルシステムを提供することができます。

ext2fs_fsopsLinux の ext2fs ファイルシステム

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

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

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

zipfs_fsops ファイルをサポートしているファイルシステムの gzip された ファイルをサポートするスタックされたファイルシステム で、zipfs ファイルシステムを使おうとすると、 libstand は ファイル名の後に .gz を付加し、更に別のファイルシステムを使 用してファイルの位置を決めます。このファイルシステムの、配 列 file_system[] での配置によって、 non-gzipped ファイルを 参照している gzipped ファイルが open されるかどうかが決めら れます。 gzip されたファイルは前方へ seek することだけがで き、gzip されたファイルへの stat() および fstat() は、長さ の不正を報告します。

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

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

デバイス

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

詳細なメモリ使用データがないのは不親切です。

libstand は多くのソースを利用しています。すなわち、

• FreeBSD 3.0 からの libc と libkern
• Matthew Dillon ⟨dillon@backplane.com⟩ からの zalloc

再構成と FreeBSD 3.0 へのポート、環境変数関係の関数、このマニュアルページ は Mike Smith ⟨msmith@FreeBSD.org⟩ が作成しました。

FreeBSD 10.0 June 22, 1998 FreeBSD 10.0