doc/ja_JP.eucJP/man/man3/libstand.3

.\" Copyright (c) Michael Smith
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR Ohttp://wafu.netgate.net/tama/unix/indexe.htmlTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" %FreeBSD: src/lib/libstand/libstand.3,v 1.5.2.10 2001/12/17 10:08:31 ru Exp %
.\"
.\" $FreeBSD$
.Dd June 22, 1998
.Dt LIBSTAND 3
.Os
.Sh 名称
.Nm libstand
.Nd スタンドアローン実行用サポートライブラリ
.Sh 書式
.In stand.h
.Sh 解説
.Nm libstand
は、スタンドアローンアプリケーションのサポート関数群と、
標準
.Bx
プログラミングが可能な模擬環境を備えています。
後のセクションでこれらの関数を種類分けしています。
ここに明確な定義がない場合は、指定の関数のセクション 3 の
マニュアルページの該当個所を参照して下さい。
.Sh 文字列関数
使用できる文字列関数は、
.Xr string 3
および
.Xr bstring 3
に書かれています。
.Sh メモリアロケーション
.Bl -hang -width 10n
.It Xo
.Ft "void *"
.Fn malloc "size_t size"
.Xc
.Pp
.Fa size
で指定した大きさのメモリを最適なアルゴリズムでヒープ領域から割り
当てます。
.It Xo
.Ft void
.Fn free "void *ptr"
.Xc
.Pp
.Fa ptr
に割り当てられたオブジェクトを解放します。
.It Xo
.Ft void
.Fn setheap "void *start" "void *limit"
.Xc
.Pp
ヒープ領域を初期化します。この関数は、
.Fn alloc
を最初に呼び出す前に実行しなければなりません。
.Fa start
と
.Fa limit
の間の領域がヒープ領域に使用されます。
これを越えて割り当てようとすると panic となります。
.It Xo
.Ft "char *"
.Fn sbrk "int junk"
.Xc
.Pp
.Fn sbrk 0
の性質を与えます。すなわちヒープ領域の最高位アドレスのポインタを
返します。この戻り値は、テスト時にヒープの実使用状況を判断するのに
使用できます。引数
.Fa junk
は無視されます。
.El
.Sh 環境
伝統的なシェルサポート環境と同様、フラットな変数空間操作のために
一群の関数が備わっています。主な拡張として、フック関数の設定／設定解除の
ためのサポートがあります。
.Bl -hang -width 10n
.It Xo
.Ft "char *"
.Fn getenv "const char *name"
.Xc
.It Xo
.Ft int
.Fn setenv "const char *name" "char *value" "int overwrite"
.Xc
.It Xo
.Ft int
.Fn putenv "const char *string"
.Xc
.It Xo
.Ft int
.Fn unsetenv "const char *name"
.Xc
.Pp
これらの関数は、標準ライブラリと類似の動作をします。
.It Xo
.Ft "struct env_var *"
.Fn env_getenv "const char *name"
.Xc
.Pp
その環境内での変数を検索し、すべてのデータ構造を返します。
.It Xo
.Ft int
.Fn env_setenv "const char *name" "int flags" "char *value" "ev_sethook_t sethook" "ev_unsethook_t unsethook"
.Xc
.Pp
.Fa name
という環境変数の新規作成または既存環境変数の設定を行います。
新規変数を生成する場合は、引数
.Fa sethook
および
.Fa unsethook
を指定することができます。
.Pp
EV_NOHOOK フラグが設定されていなければ、変数設定をしようとするとすると、
フックの設定が必ず起動されます。通常、引数
.Fa value
の確認を行ない、実際に値を保存するために EV_NOHOOK 変数をつけて、再度
.Fn env_setenv
呼び出しを行い設定します。すべての変数設定を拒否するために、定義済み関数
.Fn env_noset
を指定することができます。
.Pp
設定解除フックは、変数の設定解除が行われるときに起動されます。
戻り値が 0 のとき、変数の設定解除されています。定義済み関数
.Fa env_nounset
は、変数設定解除を抑制するのに使用します。
.El
.Sh 標準ライブラリサポート
.Bl -hang -width 10n
.It Xo
.Ft int
.Fn getopt "int argc" "char * const *argv" "cont char *optstring"
.Xc
.It Xo
.Ft long
.Fn strtol "const char *nptr" "char **endptr" "int base"
.Xc
.It Xo
.Ft void
.Fn srandom "unsigned long seed"
.Xc
.It Xo
.Ft "unsigned long"
.Fn random void
.Xc
.It Xo
.Ft "char *"
.Fn strerror "int error"
.Xc
.Pp
.Nm
でサポートされている errno のサブセット値に対応する
エラーメッセージを返します。
.It Fn assert expression
.Pp
.In assert.h
行が必要です。
.It Xo
.Ft int
.Fn setjmp "jmp_buf env"
.Xc
.It Xo
.Ft void
.Fn longjmp "jmp_buf env" "int val"
.Xc
.Pp
操作できるシグナル状態がないため、それぞれ
.Fn _setjmp
および
.Fn _lonjmp
として定義されています。
.In setjmp.h
行が必要です。
.El
.Sh キャラクタ I/O
.Bl -hang -width 10n
.It Xo
.Ft void
.Fn gets "char *buf"
.Xc
.Pp
キャラクタをコンソールから
.Fa buf
に読み込みます。標準的な注意事項が本関数に
対して適用されます。
.It Xo
.Ft void
.Fn ngets "char *buf" "size_t size"
.Xc
.Pp
.Fa size
-1 またはそれ以下の文字をコンソールから
.Fa buf
に読み込みます。行末文字は削除され、
バッファは常にヌルが終端文字になります。
.Fa size
が 1 以下の場合、関数は
.Fn gets
と同じ動作をします。
.It Xo
.Ft int
.Fn fgetstr "char *buf" "int size" "int fd"
.Xc
.Pp
一行を
.Fa size
文字以下の範囲で
.Fa buf
に読み込みます。行末のキャラクタは切り捨てられ、
バッファは常にヌルが終端となります。
正常終了のときは
.Fa buf
内の文字数を返し、読み込みエラーのときは -1 を返します。
.It Xo
.Ft int
.Fn printf "const char *fmt" "..."
.Xc
.It Xo
.Ft void
.Fn vprintf "const char *fmt" "va_list ap"
.Xc
.It Xo
.Ft int
.Fn sprintf "char *buf" "const char *fmt" "..."
.Xc
.It Xo
.Ft void
.Fn vsprintf "char *buf" "const char *fmt" "va_list ap"
.Xc
.Pp
*printf 関数は、標準
.Fn printf
ファミリのサブセット機能といくつかの拡張機能を備えています。
c,d,n,o,p,s,u,x の標準変換がサポートされています。
+,-,#,*,0, field width,precision,l の修飾子がサポートされています。
.Pp
エラーレジスタをデコードするために
.Li b
変換が備わっています。
使い方は以下の通りです。
.Pp
.Bd -ragged -offset indent
printf(
.Qq reg=%b\en ,
regval,
.Qq <base><arg>*
);
.Ed
.Pp
.Aq Pa base
は、制御キャラクタの出力を表現しています。例えば
\e10 は 10 進数を、\e20 は 16 進数を意味します。各
.Aq Pa arg
は、文字列で、最初の一文字は引数のビット数(始めが1)で、
ビットが設定されている場合、それ以降の文字列(32文字未満)は表示対象の
テキストです。つまり、
.Pp
.Bd -ragged -offset indent
printf(
.Qq reg=%b\en
3
.Qq \e10\e2BITTWO\e1BITONE\en
);
.Ed
.Pp
により出力表示されます。
.Pp
.Bd -ragged -offset indent
reg=3<BITTWO,BITONE>
.Ed
.Pp
.Li D
変換は、16 進数ダンプの機能を備えています。
たとえば、以下。
.Pp
.Bd -ragged -offset indent
printf(
.Qq %6D ,
ptr,
.Qq \&:
);  gives
.Qq XX:XX:XX:XX:XX:XX
.Ed
.Bd -ragged -offset indent
printf(
.Qq %*D ,
len,
ptr,
.Qq "\ "
);  gives
.Qq XX XX XX ...
.Ed
.El

.Pp
.Sh 文字テストと変換
.Bl -hang -width 10n
.It Xo
.Ft int
.Fn isupper "int c"
.Xc
.It Xo
.Ft int
.Fn islower "int c"
.Xc
.It Xo
.Ft int
.Fn isspace "int c"
.Xc
.It Xo
.Ft int
.Fn isdigit "int c"
.Xc
.It Xo
.Ft int
.Fn isxdigit "int c"
.Xc
.It Xo
.Ft int
.Fn isascii "int c"
.Xc
.It Xo
.Ft int
.Fn isalpha "int c"
.Xc
.It Xo
.Ft int
.Fn toupper "int c"
.Xc
.It Xo
.Ft int
.Fn tolower "int c"
.Xc
.El
.Sh ファイル入出力
.Bl -hang -width 10n
.It Xo
.Ft int
.Fn open "const char *path" "int flags"
.Xc
.Pp
.Xr open 2
の動作に似ています。ただし、ファイル作成機能がサポート
されていないため、モードパラメータは不要です。引数
.Fa flags
には、O_RDONLY, O_WRONLY, O_RDWR のどれかを指定できます。
(たとえ、現在書込みをサポートするファイルシステムが無いとしても)
.It Xo
.Ft int
.Fn close "int fd"
.Xc
.It Xo
.Ft void
.Fn closeall void
.Xc
.Pp
すべての open されているファイルを閉じます。
.It Xo
.Ft ssize_t
.Fn read "int fd" "void *buf" "size_t len"
.Xc
.It Xo
.Ft ssize_t
.Fn write "int fd" "void *buf" "size_t len"
.Xc
.Pp
(現在書き込みをサポートしているファイルシステムはありません)
.It Xo
.Ft off_t
.Fn lseek "int fd" "off_t offset" "int whence"
.Xc
.Pp
読み込みの最中に自動的に解凍されるファイルは、現在の位置から後方に
seek することはできません。
.It Xo
.Ft int
.Fn stat "const char *path" "struct stat *sb"
.Xc
.It Xo
.Ft int
.Fn fstat "int fd" "struct stat *sb"
.Xc
.Pp
関数
.Fn stat
および
.Fn fstat
は、
.Fa sb
構造体のフィールド : st_mode, st_nlink,st_uid,st_gid,st_size
への書き込みだけをします。
.Nm tftp
ファイルシステムでは、この関数の呼び出しは
意味のある値になりません。また
.Nm cd9660
ファイルシステムは、ファイルの uid/gid が常に 0 であると
報告して来ます。
.El
.Sh ページャ
.Nm libstand
は簡単な内部ページャを提供し、大きなコマンドの出力を読みやすくします。
.Bl -hang -width 10n
.It Xo
.Ft void
.Fn pager_open
.Xc
.Pp
ページャを初期化し、次の出力行が表示装置の先頭であることを知らせます。
環境変数 LINES は、一度に表示可能な行数を決める際に参照されます。
.It Xo
.Ft void
.Fn pager_close void
.Xc
.Pp
ページャを閉じます
.It Xo
.Ft int
.Fn pager_output "char *lines"
.Xc
.Pp
.Fa lines
で指定された、ヌルで終了するバッファの行がページャに送られます。
改行文字を数えることで、出力される行数が決まります。
(折り返しは含みません)
すべての行が出力されると、
.Fn pager_output
は 0 を返します。画面表示が停止し、ユーザが途中終了を
選択したときは 0 以外の値を返します。
.It Xo
.Ft int
.Fn pager_file "char *fname"
.Xc
.Pp
ファイル
.Fa fname
を開き、画面表示します。エラーのときは
-1 を返し、EOF のときは 0 を、ユーザが読み込みを途中終了する場合は
1 を返します。
.El
.Sh その他
.Bl -hang -width 10n
.It Xo
.Ft void
.Fn twiddle void
.Xc
.Pp
連続呼び出しの場合、ユーザが確認できるように、
文字列 |,/,-,\\ の後にバックスペースを付けて出力します。
.El
.Sh 低レベルサポートの要求
スタック、ヒープ、コンソール、デバイスは、
.Nm libstand
でよく使われるリソースです。
.Pp
スタックは、
.Nm libstand
関数が起動される前に構築する必要があります。
スタック要求は、関数や使われているファイルシステム、および、後で詳述する
サポートレイヤ関数によって変化します。
.Pp
ヒープは、
.Fn alloc
関数や
.Fn open
関数の呼び出しの前に、
.Fn setheap
呼び出しを行なって構築しなければなりません。ヒープの使用法は、クライアントの
動作と同様、同時に open するファイルの数によって変化します。自動解凍をす
ると、ファイルを open する度に 64K 以上のデータが割り当てられます。
.Pp
コンソールアクセスは、後述の関数
.Fn getchar  ,
.Fn putchar ,
.Fn ischar
によって行われます。
.Pp
デバイスアクセスは
.Fn devopen
によって初期化され、
.Fn devopen
が返すデバイススイッチ構造体の関数
.Fn dv_strategy ,
.Fn dv_ioctl ,
.Fn dv_close
によって実行されます。
.Pp
ユーザは次のサポート関数を用意する必要があります。
.Bl -hang -width 10n
.It Xo
.Ft int
.Fn getchar void
.Xc
.Pp
コンソールから、関数
.Fn gets  ,
.Fn ngets
やページャ関数によって使われる文字を返します。
.It Xo
.Ft int
.Fn ischar void
.Xc
.Pp
コンソールから入力待ちの状態のとき、0 でない値を返します。
.It Xo
.Ft void
.Fn putchar int
.Xc
.Pp
コンソールに、
.Fn gets ,
.Fn ngets ,
.Fn *printf ,
.Fn panic ,
.Fn twiddle
および
他の多くのデバッグ、情報通知用の関数が使用する文字を書き出します。
.It Xo
.Ft int
.Fn devopen "struct open_file *of" "const char *name" "char **file"
.Xc
.Pp
.Fa name
という名前のファイル用の適当なデバイスを開き、デバイスを参照しない
ファイルの残りの部分の
.Fa name
を指すポインタを、
.Fa file
に返します。
.Fa of
の構造体フィールド
.Va f_dev
は、正常終了した場合、open したデバイスの
.Vt devsw
構造体を指すようにセットされます。
デバイス識別子は、常にパス構成の先頭に来る
必要がありますが、それ以外は自由にフォーマットされています。
.Fn open
や
デバイス関連の I/O で使用されます。
.It Xo
.Ft int
.Fn devclose "struct open_file *of"
.Xc
.Fa of
に割り当てられたデバイスを閉じます。
デバイスドライバ自身はクローズ処理のためにすでに呼び出しが行われており、
この呼び出しは、
.Fn devopen
による割り当てを解除するだけです。
.It Xo
.Ft void
.Fn panic "const char *msg" "..."
.Xc
.Pp
致命的で回復不能なエラー状態を通知します。引数
.Fa msg ...
は、
.Fn printf
のものと同様です。
.El
.Sh 内部ファイルシステム
内部ファイルシステムでは、
.Vt struct fs_ops *file_system[]
の構造体の配列を、ユーザ
がエクスポートでき、配列は構造体
.Vt struct fs_ops
へのポインタで初期化されます。
以下のファイルシステムハンドラが
.Nm
に
備わっていますが、ユーザは自分で別のファイルシステムを
提供することができます。
.Bl -hang -width ".Va cd9660_fsops"
.It Va ufs_fsops
.Bx
の UFS
.It Va ext2fs_fsops
Linux の ext2fs ファイルシステム
.It tftp_fsops
TFTP 経由のファイルアクセス
.It Va nfs_fsops
NFS 経由のファイルアクセス
.It Va cd9660_fsops
ISO 9660 (CD-ROM) ファイルシステム
.It Va zipfs_fsops
ファイルをサポートしているファイルシステムの
gzip されたファイルをサポートするスタック
されたファイルシステムで、zipfs ファイルシステムを使おうとすると、
.Nm libstand
はファイル名の後に
.Li .gz
を付加し、更に別のファイルシステムを使用してファイルの位置を決めます。
このファイルシステムの、配列
.Va file_system[]
での配置によって、
non-gzipped ファイルを参照している gzipped ファイルが
open されるかどうかが決められます。
gzip されたファイルは前方へ seek することだけができ、gzip されたファイルへの
.Fn stat
および
.Fn fstat
は、長さの不正を報告します。
.It Va bzipfs_fsops
.Va zipfs_fsops
と同様ですが、
.Xr bzip2
で圧縮されたファイルを使用します。
.El
.Pp
構造体
.Vt struct fs_ops
のポインタ配列はヌルで終了しなければなりません。
.Sh デバイス
デバイスは、ヌルで終了するデバイススイッチ構造体のポインタ配列である、
.Vt struct devsw *devsw[]
経由のサポートコードによってエクスポートされます。
.Sh バグ
詳細なメモリ使用データがないのは不親切です。
.Pp
.Sh 歴史
.Nm libstand
は多くのソースを利用しています。すなわち、
.Bl -bullet -compact
.It
.Nx
からの
.Nm libsa
.It
.Fx 3.0
からの
.Nm libc
と
.Nm libkern
.It
.An Matthew Dillon Aq dillon@backplane.com
からの
.Nm zalloc
.El
.Pp
再構成と
.Fx 3.0
へのポート、環境変数関係の関数、このマニュアルページは
.An Mike Smith Aq msmith@FreeBSD.org
が作成しました。