EN JA
LIBGEOM(3)
LIBGEOM(3) FreeBSD Library Functions Manual LIBGEOM(3)

名称

geom_stats_open, geom_stats_close, geom_stats_resync, geom_stats_snapshot_get, geom_stats_snapshot_free, geom_stats_snapshot_timestamp, geom_stats_snapshot_reset, geom_stats_snapshot_next, gctl_get_handle, gctl_ro_param, gctl_rw_param, gctl_issue, gctl_free, gctl_dump, g_open, g_close, g_mediasize, g_sectorsize, g_stripeoffset, g_stripesize, g_flush, g_delete, g_device_path, g_get_ident, g_get_name, g_open_by_ident, g_providernameカーネル GEOM サブシステムのためのユーザランド API ライブラリ

ライブラリ

Userland API Library for Kernel GEOM subsystem (libgeom, -lgeom)

書式

#include < libgeom.h>

統計関数

void
geom_stats_close( void);

int
geom_stats_open( void);

void
geom_stats_resync( void);

void *
geom_stats_snapshot_get( void);

void
geom_stats_snapshot_free( void *arg);

void
geom_stats_snapshot_timestamp( void *arg, struct timespec *tp);

void
geom_stats_snapshot_reset( void *arg);

struct devstat *
geom_stats_snapshot_next( void *arg);

制御関数

struct gctl_req *
gctl_get_handle( void);

void
gctl_ro_param( struct gctl_req *req, const char *name, int len, const void *value);

void
gctl_rw_param( struct gctl_req *req, const char *name, int len, void *value);

const char *
gctl_issue( struct gctl_req *req);

void
gctl_free( struct gctl_req *req);

void
gctl_dump( struct gctl_req *req, FILE *f);

ユーティリティ関数

int
g_open( const char *name, int dowrite);

int
g_close( int fd);

off_t
g_mediasize( int fd);

ssize_t
g_sectorsize( int fd);

ssize_t
g_stripeoffset( int fd);

ssize_t
g_stripesize( int fd);

int
g_flush( int fd);

int
g_delete( int fd, off_t offset, off_t length);

char *
g_device_path( const char *devpath);

int
g_get_ident( int fd, char *ident, size_t size);

int
g_get_name( const char *ident, char *name, size_t size);

int
g_open_by_ident( const char *ident, int dowrite, char *name, size_t size);

char *
g_providername( int fd);

解説

geom ライブラリは、カーネルで GEOM サブシステムと情報をやりとりするための公式に公表された API を含んでいます。

統計関数

GEOM は、すべての消費者とプロバイダのために統計データを集めますが、生データでなんらかの正規化またはプレゼンテーションも実行しません、これは、ユーザランドのプレゼンテーションユーティリティのための課題として残されます。

geom_stats_open() と geom_stats_close() 関数は、カーネルにおける生の統計情報にアクセスするために必要な経路をオープンしてクローズします。これらの関数は、たぶん 1 個以上のファイルをオープンして、局所的にファイル記述子をキャッシュに格納します。 geom_stats_open() 関数は、成功すれば 0 を返し、そうでなければ errno を設定します。

geom_stats_resync() 関数は、 geom_stats_open() または geom_stats_resync() への前の呼び出しのときから、より多くの統計収集ポイントがカーネルに追加されているかどうかチェックします。

geom_stats_snapshot_get() 関数は、カーネルから生データのスナップショットを取得し、このスナップショットをできるだけ不可分で一貫するようにするのを妥当な努力をしているとはいえ、それが実際にそうであるという保証は与えられません。スナップショットは、 geom_stats_snapshot_free() 関数を再び使用して解放しなければなりません。 geom_stats_snapshot_get() 関数は、失敗すれば NULL を返します。

geom_stats_snapshot_timestamp() 関数は、スナップショットで取得されたタイムスタンプへのアクセスを提供します。

geom_stats_snapshot_reset() と geom_stats_snapshot_next() 関数は、スナップショットの統計スロット上に繰返し子を提供します。 geom_stats_snapshot_reset() 関数は、最初の項目の前のスナップショットの内部のポインタに強制的に戻ります。 geom_stats_snapshot_next() 関数は、次の項目を返し、スナップショットでそれ以上の項目がなくなれば NULL を返します。

制御関数

gctl_*() 関数は、GEOM クラスに要求を送信するために使用されます。 GEOM のクラスが実際にこれらの要求を受信することができるように、 "ctlreq"メソッド (方法) を定義しなければなりません。

gctl_get_handle(), で取得される struct gctl_req * は、(読み込み専用パラメータのために) gctl_ro_param() または (読み込み/書き込みパラメータのために) gctl_rw_param() で追加されなければならない、パラメータをいくつでも保持することができます。

gctl_ro_param() と gctl_rw_param() の両方は、パラメータを識別するために使用される、文字列 name と、読み込み専用の場合は、GEOM のクラスに渡されるデータ、または読み込み/書き込みの場合は、GEOM クラスが必要なデータで満たされるべきである前もって割り付けられたメモリへのポインタを含んでいる value を取ります。 len が負であるなら、 value が ASCII 文字列であると仮定され、実際の長さは、 value の文字列長から取られます。そうでなければ、 value のサイズを保持しなければなりません。

文字列“ class”を含む name パラメータは、各要求に必須です、対応する value は、要求が送信されるべきである GEOM クラスの名前を保持しなければなりません。

また、“ verb”と呼ばれる name パラメータは、各要求に必須で、対応する value は、GEOM のクラスが影響するべきであるコマンド文字列を保持する必要があります。

いったんすべての必要なパラメータが書き込まれると、成功すれば NULL を、失敗すれば、エラーメッセージを含む文字列を返す、 gctl_issue() で、要求を GEOM サブシステムに送信しなければなりません。

要求が終了した後に、割り付けられたメモリは、 gctl_free() で解放されるべきです。

gctl_dump() 関数は、デバッグ目的のために、 req の内容を f によって指されたオープンファイルハンドルへフォーマットするために使用することができます。

制御関数へのエラー操作は、成功すれば NULL を返すか、または、最初に起こったエラーに対応するエラーメッセージを返す、 gctl_issue() への呼び出しまで延期されます。

ユーティリティ関数

g_*() 関数は、GEOM プロバイダで通信するために使用されます。

g_open() 関数は、与えられたプロバイダをオープンして、他の関数で使用することができる、ファイル記述子番号を返します。 dowrite 引数は、 ( g_flush() または g_delete() のような) プロバイダを変更する操作が呼び出されているかどうかを示します。

g_close() 関数は、プロバイダをクローズします。

g_mediasize() 関数は、与えられたプロバイダのサイズを返します。

g_sectorsize() 関数は、与えられたプロバイダのセクターサイズを返します。

g_stripeoffset() 関数は、与えられたプロバイダのストライプのオフセットを返します。

g_stripesize() 関数は、与えれれたプロバイダのストライプのサイズを返します。

g_flush() 関数は、プロバイダの書き込みキャッシュをフラッシュするために BIO_FLUSH 要求を送ります。

g_delete() 関数は、与えられたデータ領域がもはや使用されないことをプロバイダに伝えます。

g_device_path() 関数は、プロバイダの与えらた部分へのフルパス、またはデバイスノードへのフルパスを返します。デバイスを見つけることがきないか、または、有効な geom プロバイダでないなら、 NULL が返されます。

g_get_ident() 関数は、プロバイダの固定されたユニークな識別子を返します。 ident 引数は、少なくとも DISK_IDENT_SIZE であるべきです。

g_get_name() 関数は、識別子が ident 文字列と等しい、プロバイダの名前を返します。

g_open_by_ident() 関数は、プロバイダの名前を使用する g_open() と異なって、ident を使用してプロバイダをオープンします。 name 引数が NULL でないなら、関数は、プロバイダの名前をそこに格納します。

g_providername() 関数は、オープンされたファイル記述子のプロバイダ名を返します。ファイル記述子が有効な geom プロバイダを指さないなら、NULL が返されます。

g_providername() と g_device_path() 以外のすべての関数は、成功すれば、 0 以上の値を返し、失敗すれば、 -1 を返します。

使用例

CCD クラスに送信されることになっている要求を作成し、特定 geom を破壊するよう伝えます:

H = gctl_get_handle(); 
gctl_ro_param(H, "verb", -1, "destroy geom"); 
gctl_ro_param(H, "class", -1, "CCD"); 
sprintf(buf, "ccd%d", ccd); 
gctl_ro_param(H, "geom", -1, buf); 
errstr = gctl_issue(H); 
if (errstr != NULL) 
    err(1, "could not destroy ccd: %s", errstr); 
gctl_free(H);

歴史

geom ライブラリは、 FreeBSD 5.1 で登場しました。

作者

Poul-Henning Kamp <phk@FreeBSD.org> Lukas Ertl <le@FreeBSD.org> Pawel Jakub Dawidek <pjd@FreeBSD.org>
December 4, 2010 FreeBSD