.\" .\" 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 おそらく関数には名前が不適切なものや、名前が不十分なものがあります。