strtoacl(3C)

名称

strtoacl(), strtoaclpatt(), aclentrystart[] ― 文字列形式の変換

構文

#include <acllib.h>

int strtoacl(
    const char *string,
    int nentries,
    int maxentries,
    struct acl_entry *acl,
    uid_t fuid,
    gid_t fgid);

int strtoaclpatt(
    const char *string,
    int maxentries,
    struct acl_entry_patt *acl);

廃止インタフェース

int strtoacl_r(
    const char *string,
    int nentries,
    int maxentries,
    struct acl_entry *acl,
    uid_t fuid,
    gid_t fgid,
    char *entrystart[]);

int strtoaclpatt_r(
    const char *string,
    int maxentries,
    struct acl_entry_patt *acl
    char *entrystart[]);

説明

strtoacl() は、厳密なシンボリック (文字列) 表現のアクセス制御リストを構造体形式に変換します。この関数は、入力文字列を解析し、その妥当性を確認します。さらに文字列中のエントリーを変更内容として、すでに存在している ACL に付け加えることもできます。

strtoaclpatt() は、シンボリック (文字列) 表現のアクセス制御リストパターンを構造体形式に変換します。この関数は、入力文字列を解析し、その妥当性を確認します。

外部配列 aclentrystart[] は、上の２つのいずれかのルーチンが次に呼ばれるまで有効で、エラーの報告に用いられます。以下の「エラー」の項を参照してください。

入力文字列として、「演算子形式」および「ショート形式」の ACL および ACL パターン acl(5) の中で説明されています) が使用できます。 string 中の最初の空白以外の文字が ( ならば、 ACL あるいは ACL パターンの場合はショート形式でなければなりません。それ以外の場合は演算子形式として解釈されます。

strtoacl() は、変換される文字列を指すポインターと、 ACL エントリーの配列 (acl[]) の先頭の要素を指すポインターが必要です。この配列は、はじめは nentries で表示される個数 (０以上) の有効なエントリーを含んでいて、また maxentries で表示される個数までのエントリーを収容することが可能です。さらに strtoacl() は、 string 中の@ 文字との置換をするために、また acl[] 中の最終的なエントリー数を返すために、ファイルのユーザー ID fuid) とグループ ID fgid) が必要です。

冗長なエントリー (@ 文字を処理した結果、同一のユーザー ID とグループ ID となったもの) は１つにまとめられ、 acl[] 中には一意なエントリーが、登録された順序で入れられます。新しいエントリーがあるときは、 acl 配列の最後に付け加えられます。

strtoaclpatt()

strtoaclpatt() は、 ACL の代わりに ACL パターンを処理する点が strtoacl() と異なります。すでに存在している最初の ACL の修正は無意味なので、サポートされていません。

ユーザー ID およびグループ ID がマッチするエントリーを１つにまとめることはしません。各エントリーの入力は、返される配列中の１つのエントリーを与えます。

ユーザー ID およびグループ ID に置換される@ 文字 (acl(5) 参照) は、呼び出し時に与えた特定のユーザー名あるいはグループ名ではなく、特別な値 (ACL_FILEOWNER あるいは ACL_FILEGROUP。これらは <acllib.h> 中で定義されています) に変換されます。したがって、各ファイルに対して ACL パターンを再解析するために strtoaclpatt() を呼び出す必要はありません。しかし ACL パターンを ACL と比較する場合は、呼び出し側でこの特別な値を処理しなければなりません。

ユーザー名、グループ名、モード値にワイルドカードが使用できます。モード値に使用した場合、モード値に使用した部分がないものとして扱われます。詳しくは acl(5) を参照してください。

strtoaclpatt() は strtoacl() とは異なった構造体を返します。 acl_entry_patt 構造体は、１つの mode 値ではなく、 onmode および offmode のマスクを持っています。

演算子形式の入力において、演算子は strtoaclpatt() には異なった効果を示します。

`=`		`onmode` および `offmode` フィールド中のビットを、エントリー中のすでに存在しているビットと置換して、あるいはこれより前にある演算子の指定を無視して、指定されたとおり設定します。
`+`		`onmode` のビットを設定し、 `offmode` のビットを解除します。
`-`		`offmode` のビットを設定し、 `onmode` のビットを解除します。

ショート形式の入力において、モードは演算子形式の = 演算子と同様に扱われます。

２つのルーチンとも、任意のユーザー ID およびグループ ID を表す % は、それぞれ ACL_NSUSER と ACL_NSGROUP に変換されます。また strtoaclpatt() では、ユーザー ID およびグループ ID のワイルドカード * は、それぞれ ACL_ANYUSER と ACL_ANYGROUP に変換されます。これらの値は <acllib.h> の中で定義されています。

エントリーは、 string 中どのような順序でもかまいません。 string は冗長なエントリーを含んでいてもよく、また演算子形式では、 ACL エントリーのモードの修正 (厳密な形式の場合) あるいはモードビットの追加、削除 (パターンの場合) を行う + および - 演算子が冗長になっていてもかまいません。エントリーおよび修正は、左から右へという順序で適用されます。

推奨される使用法

strtoacl() (strtoaclpatt()) を用いて新しい ACL (ACL パターン) 配列を構築するときは、必要な数の acl[] を定義してください。これを strtoacl() (strtoaclpatt()) に渡すときには、 nentries に０を設定し (strtoacl() の場合だけです)、 maxentries に acl[] の要素数を設定してください。

strtoacl() で、ファイルのすでに存在している ACL を修正する場合は、エントリーの可能な数の最大数 (NACLENTRIES です。 <sys/acl.h> 参照) だけ、 acl[] を定義してください。ファイルの ACL を読み取るために getacl() (getacl(2) 参照) を呼び出し、またファイルの所有者とグループ ID を得るために stat() (stat(2) 参照) を呼び出します。そして、 maxentries に NACLENTRIES の値を設定して、現在のエントリー数、現在の ACL、および ID 値を strtoacl() に渡します。

strtoacl() が成功した場合、出力された ACL はすべての冗長部が解消されているため、問題なく setacl() (setacl(2) 参照) に渡すことができます。ただし、 strtoacl() と strtoaclpatt() はともにユーザー ID とグループ ID の妥当性を確認しないので、これらの値が無効なものである場合、 setacl() は失敗します。

効率化のための技法

通常 strtoacl() は、ユーザー名およびグループ名の@ を特定のユーザー ID およびグループ ID の値に置き換え、冗長なエントリーをまとめます。したがって、 ACL を適用しようとする一連のファイルの各々に stat() および strtoacl() を用いるのが、時間はかかりますが最も簡単な方法です。

string の中に@ 文字がない場合、あるいは単に ACL をもう１つの別な ACL と比較する場合 (そして特別な値自体を扱おうとする場合) は、 strtoacl() を１回呼び出すだけで十分で、各ファイルに対して stat() を呼び出すのは無意味です。この動作を行わせる場合、最初に fuid に ACL_FILEOWNER、 fgid に ACL_FILEGROUP を設定して strtoacl() を呼び出してください。ファイルを特定した fuid と fgid の値を渡して再びこの関数を呼び出す必要があるのは、 acl[] 中の fuid と fgid に特別な値が設定されていて、かつ各ファイルに厳密な ACL を設定する必要があるときだけです。下の例の項を参照してください。

string の中に@ があり、かつ acl[] を setacl() の呼び出しに使用しようとするときは、 ACL 文字列を解析するために各ファイルに対して strtoacl() を再び呼び出す必要があります。これは@ で表された名前が特定の ID に置き換えられないため、１回の実行ではすべての冗長なエントリーが結合されない可能性があるためです。このことは２つの ACL の比較においても同様になります。その上、演算子形式の入力の演算子の情報は失われてしまうので、呼び出し側で後にエントリーを結合することはできません。

廃止インタフェース

strtoacl_r() と strtoaclpatt_r() は、文字列形式をアクセス制御リスト (ACL) 構造体に変換します。

戻り値

strtoacl() (strtoaclpatt()) が成功すると、最終的な ACL (ACL パターン) のエントリーの数が返され、その値は常に nentries (0) 以上です。

さらに strtoaclpatt() は、前後に空白を含んでいる可能性のある string の中から解析された、各パターンエントリーの先頭を指すために、グローバル配列 aclentrystart[] に値を設定します。この時設定されるのは、戻り値より１個多いポインターです (決して NACLENTRIES + 1 個を超えません)。最後の有効な要素は、 string の末尾の null 文字を指します。 strtoaclpatt() を呼び出した後、エントリーパターンの該当する入力文字列は、一時的に string 中の次のエントリーパターンの先頭に null を挿入して、呼び出し側でエラーの報告のために使われます。

エラー

エラーが起こった場合、 strtoacl() と strtoaclpatt() は負の値を返し、 acl の内容は不定です (おそらく内容は変化しています)。この場合エラーの報告をわかりやすくするために、 aclentrystart[0] および aclentrystart[1] はそれぞれ、解析中にエラーが起こったエントリーと次のエントリーの先頭を指すように設定されます。そのエントリーが ( で始まっていない場合、 aclentrystart[1] は aclentrystart[0] 以後の、次の null 文字あるいはカンマを指します。それ以外の場合は、次の null、あるいは次の ) に引き続く文字を指します。

エラーの場合に返される値は次のとおりです。

-1		構文エラー、ショート形式で、エントリーが `(` で始まっていない場合
-2		構文エラー、ショート形式で、エントリーが `)` で終っていない場合
-3		構文エラー、ユーザー名がドットで終っていない場合
-4		(`strtoacl()` のみ) 構文エラー、演算子形式の入力においてグループ名が演算子で終っていないか、ショート形式の入力においてグループ名がカンマで終っていない場合
-5		構文エラー、ユーザー名が null の場合
-6		構文エラー、グループ名が null の場合
-7		無効なユーザー名 (`/etc/passwd` ファイル中にない、あるいは無効な番号) の場合
-8		無効なグループ名 (`/etc/group` ファイル中にない、あるいは無効な番号) の場合
-9		構文エラー、 `0`..`7`、 `r`、 `w`、 `x`、 `-` (ショート形式のみ)、 `` (パターン中のみ)、 `,` (演算子形式でエントリーを終了させる)、あるいは `)` (ショート形式でエントリーを終了させる) 以外の無効なモード文字の場合。もしくは `0`..`7` や `` とともに他のモード文字がある場合
-10		最終的な ACL が `maxentries` 以上のエントリーになってしまいます。

例

次のコードの一部は、ACL の文字列を、ファイルの所有者として 103 という番号を fuid に使い、ファイルのグループとして 45 という番号を fgid に使った、エントリーの配列へ変換します。

#include <acllib.h>

int nentries;
struct acl_entry acl [NACLENTRIES];

if ((nentries = strtoacl (string, 0, NACLENTRIES, acl, 103, 45)) < 0)
error (...);

次のコードは、 ../myfile ファイルに対する ACL, fuid, fgid を取得し、記述文字列を用いて ACL を修正し、さらに ../myfile2 ファイルに対する ACL を新しいバージョンに変更します。

#include <sys/types.h>
#include <sys/stat.h>
#include <acllib.h>

struct stat statbuf;
int nentries;
struct acl_entry acl [NACLENTRIES];

if (stat ("../myfile", & statbuf) < 0)
     error (...);

if ((nentries = getacl ("../myfile", NACLENTRIES, acl)) < 0)
     error (...);

if ((nentries = strtoacl (string, nentries, NACLENTRIES, acl,
    statbuf.st_uid, statbuf.st_gid)) < 0)
{
    error (...);
}

if (setacl ("../myfile2", nentries, acl) < 0)
     error (...);

次のコードの一部は、 fuid と fgid の特別な値を用いて strtoacl() を呼び出して、それが acl[] 中に現れるかどうかをチェックします。

#include <acllib.h>
int perfile = 0; /* need to stat() and reparse per file? */ int entry;
if ((nentries = strtoacl (string, 0, NACLENTRIES, acl, ACL_FILEOWNER, ACL_FILEGROUP)) < 0) { error (...); }
for (entry = 0; entry < nentries; entry++) { if ((acl [entry] . uid == ACL_FILEOWNER) || (acl [entry] . gid == ACL_FILEGROUP)) { perfile = 1; break; } }

次のコードの一部は、文字列中の ACL パターンを、パターンエントリーの配列へ変換します。

#include <acllib.h>
int nentries; struct acl_entry_patt acl [NACLENTRIES];
if ((nentries = strtoaclpatt (string, NACLENTRIES, acl)) < 0) error (...);

for ループ中のコードの一部は、ファイルの ACL (変数名は a* です) のエントリーを、そのファイルのユーザー ID およびグループ ID (変数名は f* です) を使用して、エントリーパターン (変数名は p*, onmask, offmask です) と比較します。

include <unistd.h> if (((puid == ACL_FILEOWNER) && (fuid != auid)) || ((puid != ACL_ANYUSER) && (puid != auid))) { continue; }
if (((pgid == ACL_FILEGROUP) && (fgid != agid)) || ((pgid != ACL_ANYGROUP) && (pgid != agid))) { continue; }
if (((( amode) & MODEMASK & onmask ) != onmask) || (((~ amode) & MODEMASK & offmask) != offmask)) { continue; }

警告

strtoacl_r() および strtoaclpatt_r() インタフェースは廃止され、現在では既存の DCE アプリケーションとの互換性を保つためにだけサポートされています。新しいマルチスレッドアプリケーションでは、 strtoacl() および strtoaclpatt() を使用してください。

著者

strtoacl() および strtoaclpatt() は、HP で開発されました。

ファイル

/etc/passwd
/etc/group

参照

getacl(2), setacl(2), acltostr(3C), cpacl(3C), chownacl(3C), setaclentry(3C), acl(5), thread_safety(5)

strtoacl(3C)

テクニカルドキュメント

≫ 目次

≫ 索引

名称

構文

廃止インタフェース

説明

strtoaclpatt()

推奨される使用法

効率化のための技法

廃止インタフェース

戻り値

エラー

例

警告

著者

ファイル

参照

strtoacl(3C)

テクニカル ドキュメント

≫ 目次

≫ 索引

名称

構文

廃止インタフェース

説明

strtoaclpatt()

推奨される使用法

効率化のための技法

廃止インタフェース

戻り値

エラー

例

警告

著者

ファイル

参照

テクニカルドキュメント