490 lines
10 KiB
Groff
490 lines
10 KiB
Groff
.\"
|
|
.\" Copyright (c) 1998 Kenneth D. Merry.
|
|
.\" 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.
|
|
.\" 3. The name of the author may not be used to endorse or promote products
|
|
.\" derived from this software without specific prior written permission.
|
|
.\"
|
|
.\" 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 OTHERWISE) ARISING IN ANY WAY
|
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
|
.\" SUCH DAMAGE.
|
|
.\"
|
|
.\" %FreeBSD: src/lib/libcam/cam.3,v 1.5.2.6 2001/12/17 10:08:28 ru Exp %
|
|
.\"
|
|
.\" $FreeBSD$
|
|
.Dd October 10, 1998
|
|
.Os
|
|
.Dt CAM 3
|
|
.Sh 名称
|
|
.Nm cam_open_device ,
|
|
.Nm cam_open_spec_device ,
|
|
.Nm cam_open_btl ,
|
|
.Nm cam_open_pass ,
|
|
.Nm cam_close_device ,
|
|
.Nm cam_close_spec_device ,
|
|
.Nm cam_getccb ,
|
|
.Nm cam_send_ccb ,
|
|
.Nm cam_freeccb ,
|
|
.Nm cam_path_string ,
|
|
.Nm cam_device_dup ,
|
|
.Nm cam_device_copy ,
|
|
.Nm cam_get_device
|
|
.Nd CAM ユーザライブラリ
|
|
.Sh ライブラリ
|
|
.Lb libcam
|
|
.Sh 書式
|
|
.In stdio.h
|
|
.In camlib.h
|
|
.Ft struct cam_device *
|
|
.Fo cam_open_device
|
|
.Fa "const char *path"
|
|
.Fa "int flags"
|
|
.Fc
|
|
.Ft struct cam_device *
|
|
.Fo cam_open_spec_device
|
|
.Fa "const char *dev_name"
|
|
.Fa "int unit"
|
|
.Fa "int flags"
|
|
.Fa "struct cam_device *device"
|
|
.Fc
|
|
.Ft struct cam_device *
|
|
.Fo cam_open_btl
|
|
.Fa "path_id_t path_id"
|
|
.Fa "target_id_t target_id"
|
|
.Fa "lun_id_t target_lun"
|
|
.Fa "int flags"
|
|
.Fa "struct cam_device *device"
|
|
.Fc
|
|
.Ft struct cam_device *
|
|
.Fo cam_open_pass
|
|
.Fa "const char *path"
|
|
.Fa "int flags"
|
|
.Fa "struct cam_device *device"
|
|
.Fc
|
|
.Ft void
|
|
.Fo cam_close_device
|
|
.Fa "struct cam_device *dev"
|
|
.Fc
|
|
.Ft void
|
|
.Fo cam_close_spec_device
|
|
.Fa "struct cam_device *dev"
|
|
.Fc
|
|
.Ft union ccb *
|
|
.Fo cam_getccb
|
|
.Fa "struct cam_device *dev"
|
|
.Fc
|
|
.Ft int
|
|
.Fo cam_send_ccb
|
|
.Fa "struct cam_device *device"
|
|
.Fa "union ccb *ccb"
|
|
.Fc
|
|
.Ft void
|
|
.Fo cam_freeccb
|
|
.Fa "union ccb *ccb"
|
|
.Fc
|
|
.Ft char *
|
|
.Fo cam_path_string
|
|
.Fa "struct cam_device *dev"
|
|
.Fa "char *str"
|
|
.Fa "int len"
|
|
.Fc
|
|
.Ft struct cam_device *
|
|
.Fo cam_device_dup
|
|
.Fa "struct cam_device *device"
|
|
.Fc
|
|
.Ft void
|
|
.Fo cam_device_copy
|
|
.Fa "struct cam_device *src"
|
|
.Fa "struct cam_device *dst"
|
|
.Fc
|
|
.Ft int
|
|
.Fo cam_get_device
|
|
.Fa "const char *path"
|
|
.Fa "char *dev_name"
|
|
.Fa "int devnamelen"
|
|
.Fa "int *unit"
|
|
.Fc
|
|
.Sh 解説
|
|
CAM
|
|
ライブラリは、
|
|
CAM
|
|
システムでのプログラミングを補助するよう
|
|
設計されたいくつかの関数で構成されています。
|
|
このマニュアルページは、
|
|
ライブラリ関数の基本セットについて説明してあります。
|
|
次にリストする
|
|
マニュアルページにさらに多くの関数が記載してあります。
|
|
.Pp
|
|
多数の
|
|
CAM
|
|
ライブラリ関数が
|
|
.Va cam_device
|
|
構造体を使用します。
|
|
.Bd -literal
|
|
struct cam_device {
|
|
char device_path[MAXPATHLEN+1];/*
|
|
* ユーザが指定した
|
|
* デバイスのパス名。
|
|
* ユーザがデバイス名
|
|
* とユニット番号を
|
|
* 別々に記述すると
|
|
* これは NULL に
|
|
* なることがあります。
|
|
*/
|
|
char given_dev_name[DEV_IDLEN+1];/*
|
|
* ユーザが指定した
|
|
* デバイス名。
|
|
*/
|
|
u_int32_t given_unit_number; /*
|
|
* ユーザが指定した
|
|
* ユニット番号。
|
|
*/
|
|
char device_name[DEV_IDLEN+1];/*
|
|
* デバイス名。
|
|
* たとえば 'pass'
|
|
*/
|
|
u_int32_t dev_unit_num; /* この特定のデバイスに
|
|
* 対応する通過デバイスの
|
|
* ユニット番号。
|
|
*/
|
|
char sim_name[SIM_IDLEN+1];/*
|
|
* コントローラ名。
|
|
* たとえば 'ahc'
|
|
*/
|
|
u_int32_t sim_unit_number; /* コントローラユニット番号 */
|
|
u_int32_t bus_id; /* コントローラバス番号 */
|
|
lun_id_t target_lun; /* 論理ユニット番号 */
|
|
target_id_t target_id; /* ターゲット ID */
|
|
path_id_t path_id; /* システム SCSI バス番号 */
|
|
u_int16_t pd_type; /* 周辺装置のタイプ */
|
|
struct scsi_inquiry_data inq_data; /* SCSI 照会データ */
|
|
u_int8_t serial_num[252]; /* デバイスシリアル番号 */
|
|
u_int8_t serial_num_len; /* シリアル番号の長さ */
|
|
u_int8_t sync_period; /* 調整された同期周期 */
|
|
u_int8_t sync_offset; /* 調整された同期オフセット */
|
|
u_int8_t bus_width; /* 調整されたバス幅 */
|
|
int fd; /* デバイスのファイル記述子 */
|
|
};
|
|
.Ed
|
|
.Pp
|
|
.Fn cam_open_device
|
|
は、引数として、開こうとしているデバイスを記述する文字列、
|
|
および
|
|
.Xr open 2
|
|
に渡すのに適切な
|
|
.Ar flags
|
|
を取ります。
|
|
渡される「パス」は、
|
|
実際には、開くデバイス名とユニット番号が入った任意のタイプの
|
|
文字列です。
|
|
文字列は
|
|
.Fn cam_get_device
|
|
によって解釈されて、
|
|
デバイス名とユニット番号になります。デバイス名とユニット番号が
|
|
決定されると、ルックアップが実行されて、指定のデバイスに対応する通過
|
|
デバイスを決定します。
|
|
.Fn cam_open_device
|
|
は使用法はかなり簡単ですが、
|
|
現実には一般的な使用に適していません。動作が必ずしも
|
|
決定的ではないからです。新しいアプリケーションを作成しているプログラマは、
|
|
以下に説明する他のオープンルーチンの
|
|
1 つを使用するようにしてください。
|
|
.Pp
|
|
.Fn cam_open_spec_device
|
|
は、渡されたデバイス名とユニット番号に対応する
|
|
.Xr pass 4
|
|
デバイスを開きます。
|
|
.Ar flags
|
|
は、
|
|
.Xr open 2
|
|
に渡すのに適切なフラグである
|
|
必要があります。
|
|
.Ar device
|
|
引数はオプションです。
|
|
ユーザは、
|
|
.Va cam_device
|
|
構造体に
|
|
割り振り済みの空間を指定できます。
|
|
.Ar device
|
|
引数が
|
|
.Va NULL
|
|
の場合、
|
|
.Fn cam_open_spec_device
|
|
は、
|
|
.Xr malloc 3
|
|
を使用して
|
|
.Va cam_device
|
|
構造体用の空間を
|
|
割り振ります。
|
|
.Pp
|
|
.Fn cam_open_btl
|
|
は、
|
|
.Fn cam_open_spec_device
|
|
に類似していますが、引数として、
|
|
デバイス名とユニット番号の代わりに
|
|
.Tn SCSI
|
|
バス、ターゲット、および論理
|
|
ユニットを取る点が異なります。
|
|
.Va path_id
|
|
引数は、
|
|
.Tn SCSI
|
|
バス番号の
|
|
CAM
|
|
の
|
|
同等のものです。これはシステム内の論理バス番号を表します。
|
|
.Ar flags
|
|
は、
|
|
.Xr open 2
|
|
に渡すのに適切なフラグである必要があります。
|
|
.Fn cam_open_spec_device
|
|
と同じように、
|
|
.Fa device
|
|
引数はオプションです。
|
|
.Pp
|
|
.Fn cam_open_pass
|
|
は、引数として、開く
|
|
.Xr pass 4
|
|
デバイスの
|
|
.Fa path
|
|
を取ります。
|
|
変換もルックアップも行われないので、
|
|
渡されるパスは CAM
|
|
.Xr pass 4
|
|
デバイスの
|
|
パスでなければなりません。
|
|
.Fa flags
|
|
は、
|
|
.Xr open 2
|
|
に渡すのに適したフラグである
|
|
必要があります。
|
|
.Fa device
|
|
引数は、ユーザが
|
|
CAM
|
|
ライブラリに
|
|
.Va cam_device
|
|
構造体用の空間を割り振りさせたい場合は、
|
|
.Fn cam_open_spec_device
|
|
および
|
|
.Fn cam_open_btl
|
|
と同じように、
|
|
NULL
|
|
である必要があります。
|
|
.Fn cam_close_device
|
|
は、上記の open() 呼び出しの
|
|
1 つが割り振った
|
|
.Va cam_device
|
|
構造体を解放し、通過デバイスへのファイル記述子を閉じます。
|
|
ユーザが
|
|
.Va cam_device
|
|
構造体用の空間を割り振っている場合は、このルーチンを呼び
|
|
出してはなりません。
|
|
代わりに、ユーザは
|
|
.Fn cam_close_spec_device
|
|
を呼び出すべきです。
|
|
.Pp
|
|
.Fn cam_close_spec_device
|
|
は、上記の open() ルーチンの
|
|
1 つで開かれた
|
|
ファイル記述子を閉じるだけです。この関数は、
|
|
.Va cam_device
|
|
が
|
|
CAM
|
|
ライブラリ
|
|
ではなく、呼び出し元によって割り振られたときに呼び出す必要があります。
|
|
.Pp
|
|
.Fn cam_getccb
|
|
は、
|
|
.Xr malloc 3
|
|
を使用して
|
|
CCB
|
|
を割り振り、
|
|
.Va cam_device
|
|
構造の値を使用して
|
|
CCB
|
|
ヘッダ内にフィールドを設定します。
|
|
.Pp
|
|
.Fn cam_send_ccb
|
|
は、指定の
|
|
.Va ccb
|
|
を、
|
|
.Va cam_device
|
|
構造体内で記述された
|
|
.Fa device
|
|
に
|
|
送信します。
|
|
.Pp
|
|
.Fn cam_freeccb
|
|
は、
|
|
.Fn cam_getccb
|
|
が割り振った
|
|
CCB
|
|
を解放します。
|
|
.Pp
|
|
.Fn cam_path_string
|
|
は、引数として、
|
|
.Va cam_device
|
|
構造体、および長さが
|
|
.Fa len
|
|
のストリングを取ります。
|
|
この関数は、カーネルが使用するのと類似した、コロンで
|
|
終了する印刷接頭語ストリングを作成します。
|
|
たとえば、"(cd0:ahc1:0:4:0): " です。
|
|
.Fn cam_path_string
|
|
は、多くとも
|
|
.Fa len Ns \-1
|
|
キャラクタを
|
|
.Ar str
|
|
に設定します。
|
|
.Fa len
|
|
番めのキャラクタは、終了を示す
|
|
.Ql \e0
|
|
です。
|
|
.Pp
|
|
.Fn cam_device_dup
|
|
は、
|
|
.Xr strdup 3
|
|
と同じように方法で動作します。
|
|
.Va cam_device
|
|
構造体用に空間を割り当て、渡された
|
|
.Fa device
|
|
構造体の内容を、新たに割り振られた
|
|
構造体にコピーします。
|
|
.Pp
|
|
.Fn cam_device_copy
|
|
は
|
|
.Fa src
|
|
構造体を
|
|
.Fa dst
|
|
にコピーします。
|
|
.Pp
|
|
.Fn cam_get_device
|
|
は、デバイス名にユニット番号が続いたストリングの入った
|
|
.Fa path
|
|
引数を取ります。次に、ストリングをデバイス名とユニット名に分解し、
|
|
それぞれ
|
|
.Fa dev_name
|
|
と
|
|
.Fa unit
|
|
に戻します。
|
|
.Fn cam_get_device
|
|
は、少なくとも次の
|
|
形式のストリングを処理できます。
|
|
.Pp
|
|
.Bl -tag -width 1234 -compact
|
|
.It /dev/foo0a
|
|
.It /dev/foo1s2c
|
|
.It foo0
|
|
.It foo0a
|
|
.It nfoo0
|
|
.El
|
|
.Pp
|
|
.Fn cam_get_device
|
|
は、
|
|
.Fn cam_open_device
|
|
に類似した機能を準備する必要がある
|
|
アプリケーション用の便利な関数として備えられています。プログラマは、
|
|
可能であれば、デバイス名とユニット番号を得るもっと決定的な方式を
|
|
使用することをお勧めします。
|
|
.Sh 戻り値
|
|
.Fn cam_open_device
|
|
、
|
|
.Fn cam_open_spec_device
|
|
、
|
|
.Fn cam_open_btl
|
|
、および
|
|
.Fn cam_open_pass
|
|
は、
|
|
.Va cam_device
|
|
構造を指すポインタを返します。または、
|
|
エラーがあった場合は
|
|
NULL
|
|
を返します。
|
|
.Pp
|
|
.Fn cam_getccb
|
|
は、割り振り済みで部分的に初期化済みの
|
|
CCB
|
|
を返します。また、
|
|
CCB
|
|
の割り振りが処理失敗した場合は
|
|
NULL
|
|
を返します。
|
|
.Pp
|
|
.Fn cam_send_ccb
|
|
は、エラーが発生した場合、値 -1 を返し、
|
|
.Va errno
|
|
がエラーを
|
|
示すように設定されます。
|
|
.Pp
|
|
.Fn cam_path_string
|
|
は、便宜として記入された印刷接頭語を返します。これは、
|
|
.Fn cam_path_string
|
|
に渡されるのと同じ
|
|
.Fa str
|
|
です。
|
|
.Pp
|
|
.Fn cam_device_dup
|
|
は、渡された
|
|
.Va device
|
|
のコピーを返します。または、エラーが
|
|
発生した場合は
|
|
NULL
|
|
を返します。
|
|
.Pp
|
|
.Fn cam_get_device
|
|
は、処理成功の場合は 0 を返し、
|
|
処理失敗を示す場合は -1 を返します。
|
|
.Pp
|
|
ここで説明した基本 CAM ライブラリ関数の 1 つから
|
|
エラーが返された場合は、
|
|
エラーの理由が一般にグローバルストリング
|
|
.Va cam_errbuf
|
|
に印刷されます。
|
|
これの長さは
|
|
.Dv CAM_ERRBUF_SIZE
|
|
キャラクタです。
|
|
.Sh 関連項目
|
|
.Xr cam_cdbparse 3 ,
|
|
.Xr pass 4 ,
|
|
.Xr camcontrol 8
|
|
.Pp
|
|
.Sh 歴史
|
|
CAM ライブラリは
|
|
.Fx 3.0
|
|
ではじめて登場しました。
|
|
.Sh 作者
|
|
.An Kenneth Merry Aq ken@FreeBSD.org
|
|
.Sh バグ
|
|
.Fn cam_open_device
|
|
は、渡された
|
|
.Fa path
|
|
が何かへの
|
|
symlink
|
|
であるかどうか
|
|
チェックしません。渡された
|
|
.Fa path
|
|
が実際の
|
|
.Xr pass 4
|
|
デバイスであるかどうかも
|
|
チェックしません。前のチェックを実現するのはかなり簡単でしょうが、後の
|
|
チェックを実行するためには、
|
|
.Xr pass 4
|
|
デバイスとしてデバイスノードを識別する
|
|
決定的な方法が必要でしょう。
|
|
.Pp
|
|
おそらく関数には名前が不適切なものや、名前が不十分なものがあります。
|