EN JA
CAM(3)
CAM(3) FreeBSD Library Functions Manual 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_deviceCAM ユーザライブラリ

ライブラリ

Common Access Method User Library (libcam, -lcam)

書式

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

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

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];/* 
           * ユーザが指定した 
           * デバイス名。 
           */ 
 uint32_t given_unit_number;     /* 
           * ユーザが指定した 
           * ユニット番号。 
           */ 
 
 char  device_name[DEV_IDLEN+1];/* 
        * デバイス名。 
        * たとえば 'pass' 
        */ 
 uint32_t dev_unit_num; /* この特定のデバイスに 
      * 対応する通過デバイスの 
      * ユニット番号。 
      */ 
 char  sim_name[SIM_IDLEN+1];/* 
            * コントローラ名。 
            * たとえば 'ahc' 
            */ 
 uint32_t sim_unit_number; /* コントローラユニット番号 */ 
 uint32_t bus_id;   /* コントローラバス番号 */ 
 lun_id_t target_lun;  /* 論理ユニット番号 */ 
 target_id_t target_id;  /* ターゲット ID */ 
 path_id_t path_id;  /* システム SCSI バス番号 */ 
 uint16_t pd_type;  /* 周辺装置のタイプ */ 
 struct scsi_inquiry_data inq_data;  /* SCSI 照会データ */ 
 uint8_t  serial_num[252]; /* デバイスシリアル番号 */ 
 uint8_t  serial_num_len;  /* シリアル番号の長さ */ 
 uint8_t  sync_period;  /* 調整された同期周期 */ 
 uint8_t  sync_offset;  /* 調整された同期オフセット */ 
 uint8_t  bus_width;  /* 調整されたバス幅 */ 
 int  fd;   /* デバイスのファイル記述子 */ 
};

cam_open_device() は、引数として、オープンしようとしているデバイスを記述する文字列、および open(2) に渡すのに適切な flags を取ります。渡される「パス」は、実際には、オープンするデバイス名とユニット番号が入った任意のタイプの文字列です。文字列は、 cam_get_device() によって解釈されて、デバイス名とユニット番号になります。デバイス名とユニット番号が決定されると、ルックアップが実行されて、指定のデバイスに対応する通過デバイスを決定します。

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_nameunit に戻します。 cam_get_device() は、少なくとも次の形式の文字列を処理できます。

/dev/foo1
foo0
nsa2

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 ライブラリは、 FreeBSD 3.0 で登場しました。

作者

Kenneth Merry <ken@FreeBSD.org>

バグ

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

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

October 10, 1998 FreeBSD