cam(3)

cam_open_device, cam_open_spec_device, cam_open_btl, cam_open_pass, cam_close_device, cam_close_spec_device, cam_getccb, cam_send_ccb, cam_freeccb, cam_path_string, cam_device_dup, cam_device_copy, cam_get_device − CAM ユーザライブラリ

Common Access Method User Library (libcam, −lcam)

#include <stdio.h>
#include <camlib.h>

struct cam_device *

cam_open_spec_device(const char *dev_name, int unit, int flags, struct cam_device *device);

struct cam_device *
cam_open_btl(path_id_t path_id, target_id_t target_id, lun_id_t target_lun, int flags, struct cam_device *device);

struct cam_device *
cam_open_pass(const char *path, int flags, struct cam_device *device);

void
cam_close_device(struct cam_device *dev);

void
cam_close_spec_device(struct cam_device *dev);

union ccb *
cam_getccb(struct cam_device *dev);

int
cam_send_ccb(struct cam_device *device, union ccb *ccb);

void
cam_freeccb(union ccb *ccb);

char *
cam_path_string(struct cam_device *dev, char *str, int len);

struct cam_device *
cam_device_dup(struct cam_device *device);

void
cam_device_copy(struct cam_device *src, struct cam_device *dst);

int
cam_get_device(const char *path, char *dev_name, int devnamelen, int *unit);

解説

CAM ライブラリは、 CAM システムでのプログラミングを補助するよう設計された いくつかの関数で構成されています。このマニュアルページは、ライブラリ関数 の基本セットについて説明してあります。次にリストするマニュアルページにさ らに多くの関数が記載してあります。

多数の CAM ライブラリ関数が cam_device 構造体を使用します。

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;

/* デバイスのファイル記述子 */

};

cam_open_device() は、引数として、開こうとしているデバイスを記述する文字 列、および open(2) に渡すのに適切な flags を取ります。渡される「パス」 は、実際には、開くデバイス名とユニット番号が入った任意のタイプの文字列で す。文字列は cam_get_device() によって解釈されて、デバイス名とユニット番 号になります。デバイス名とユニット番号が決定されると、ルックアップが実行 されて、指定のデバイスに対応する通過デバイスを決定します。 cam_open_device() は使用法はかなり簡単ですが、現実には一般的な使用に適し ていません。動作が必ずしも決定的ではないからです。新しいアプリケーション を作成しているプログラマは、以下に説明する他のオープンルーチンの 1 つを使 用するようにしてください。

cam_open_spec_device() は、渡されたデバイス名とユニット番号に対応する pass(4) デバイスを開きます。 flags は、 open(2) に渡すのに適切なフラグで ある必要があります。 device 引数はオプションです。ユーザは、 cam_device 構造体に割り振り済みの空間を指定できます。 device 引数が NULL の場合、 cam_open_spec_device() は、 malloc(3) を使用して cam_device 構造体用の空 間を割り振ります。

cam_open_btl() は、 cam_open_spec_device() に類似していますが、引数とし て、デバイス名とユニット番号の代わりに SCSI バス、ターゲット、および論理 ユニットを取る点が異なります。 path_id 引数は、 SCSI バス番号の CAM の同 等のものです。これはシステム内の論理バス番号を表します。 flags は、 open(2) に渡すのに適切なフラグである必要があります。 cam_open_spec_device() と同じように、 device 引数はオプションです。

cam_open_pass() は、引数として、開く pass(4) デバイスの path を取ります。 変換もルックアップも行われないので、渡されるパスは CAM pass(4) デバイスの パスでなければなりません。 flags は、 open(2) に渡すのに適したフラグであ る必要があります。 device 引数は、ユーザが CAM ライブラリに cam_device 構 造体用の空間を割り振りさせたい場合は、 cam_open_spec_device() および cam_open_btl() と同じように、 NULL である必要があります。 cam_close_device() は、上記の open() 呼び出しの 1 つが割り振った cam_device 構造体を解放し、通過デバイスへのファイル記述子を閉じます。ユー ザが cam_device 構造体用の空間を割り振っている場合は、このルーチンを呼び 出してはなりません。代わりに、ユーザは cam_close_spec_device() を呼び出す べきです。

cam_close_spec_device() は、上記の open() ルーチンの 1 つで開かれたファイ ル記述子を閉じるだけです。この関数は、 cam_device が CAM ライブラリではな く、呼び出し元によって割り振られたときに呼び出す必要があります。

cam_getccb() は、 malloc(3) を使用して CCB を割り振り、 cam_device 構造の 値を使用して CCB ヘッダ内にフィールドを設定します。

cam_send_ccb() は、指定の ccb を、 cam_device 構造体内で記述された device に送信します。

cam_freeccb() は、 cam_getccb() が割り振った CCB を解放します。

cam_path_string() は、引数として、 cam_device 構造体、および長さが len の ストリングを取ります。この関数は、カーネルが使用するのと類似した、コロン で終了する印刷接頭語ストリングを作成します。たとえば、"(cd0:ahc1:0:4:0): " です。 cam_path_string() は、多くとも len−1 キャラクタを str に設定しま す。 len 番めのキャラクタは、終了を示す ‘\0’ です。

cam_device_dup() は、 strdup(3) と同じように方法で動作します。 cam_device 構造体用に空間を割り当て、渡された device 構造体の内容を、新たに割り振ら れた構造体にコピーします。

cam_device_copy() は src 構造体を dst にコピーします。

cam_get_device() は、デバイス名にユニット番号が続いたストリングの入った path 引数を取ります。次に、ストリングをデバイス名とユニット名に分解し、そ れぞれ dev_name と unit に戻します。 cam_get_device() は、少なくとも次の 形式のストリングを処理できます。

/dev/foo1s2c
foo0
foo0a
nfoo0

cam_get_device() は、 cam_open_device() に類似した機能を準備する必要があ るアプリケーション用の便利な関数として備えられています。プログラマは、可 能であれば、デバイス名とユニット番号を得るもっと決定的な方式を使用するこ とをお勧めします。

戻り値

cam_open_device() 、 cam_open_spec_device() 、 cam_open_btl() 、および cam_open_pass() は、 cam_device 構造を指すポインタを返します。または、エ ラーがあった場合は NULL を返します。

cam_getccb() は、割り振り済みで部分的に初期化済みの CCB を返します。ま た、 CCB の割り振りが処理失敗した場合は NULL を返します。

cam_send_ccb() は、エラーが発生した場合、値 -1 を返し、 errno がエラーを 示すように設定されます。

cam_path_string() は、便宜として記入された印刷接頭語を返します。これは、 cam_path_string() に渡されるのと同じ str です。

cam_device_dup() は、渡された device のコピーを返します。または、エラーが 発生した場合は NULL を返します。

cam_get_device() は、処理成功の場合は 0 を返し、処理失敗を示す場合は -1 を返します。

ここで説明した基本 CAM ライブラリ関数の 1 つからエラーが返された場合は、 エラーの理由が一般にグローバルストリング cam_errbuf に印刷されます。これ の長さは CAM_ERRBUF_SIZE キャラクタです。

cam_cdbparse(3), pass(4), camcontrol(8)

CAM ライブラリは FreeBSD 3.0 ではじめて登場しました。

Kenneth Merry ⟨ken@FreeBSD.org⟩

cam_open_device() は、渡された path が何かへの symlink であるかどうか チェックしません。渡された path が実際の pass(4) デバイスであるかどうかも チェックしません。前のチェックを実現するのはかなり簡単でしょうが、後の チェックを実行するためには、 pass(4) デバイスとしてデバイスノードを識別す る決定的な方法が必要でしょう。

おそらく関数には名前が不適切なものや、名前が不十分なものがあります。

FreeBSD 10.0 October 10, 1998 FreeBSD 10.0