名称

elf_begin — ELF ファイルまたは ar(1) アーカイブをオープンする

ライブラリ

ELF Access Library (libelf, -lelf)

書式

#include < libelf.h>

Elf *
elf_begin( int fd, Elf_Cmd cmd, Elf *elf);

解説

関数 elf_begin() は、 elf(3) ライブラリの他の API によってさらなる処理のための ELF ファイルと ar(1) アーカイブをオープンするために使用されます。また、それは、 elf_next(3) と elf_rand(3) API と組み合わせて ar(1) アーカイブの個々の ELF メンバにアクセスするために使用されます。

引数 fd は、 open(2) システムコールから返されたオープンファイル記述子です。関数 elf_begin() は、引数 cmd の値によって読み込みまたは書き込みのための引数 fd を使用します。引数 elf は、アーカイブを通して繰り返しのために主として使用されます。

引数 cmd は、次の値を持つことができます:

ELF_C_NULL

elf_begin() は、NULL を返します。引数 fd と elf は、無視され、追加のエラーシグナルは生成されません。

ELF_C_READ

この値は、アプリケーションが、引数 fd によって指定されたファイルの内容を (変更しなで) 調べたいとき、存在します。 ar(1) アーカイブと通常の ELF ファイルの両方に、それを使用することができます。

引数 fd は、読み込みのためにオープンされるべきです。引数 elf が NULL であるなら、ライブラリは、処理されるファイルのために新しい ELF 記述子を割り付けます。引数 elf が NULL でなく、以前に elf_begin() でオープンされた通常の ELF ファイルを参照しているなら、 elf のための活性化 (activation) カウントは増加されます。引数 elf が NULL でなく、以前に elf_begin() でオープンされた ar(1) アーカイブのための記述子を参照しているなら、アーカイブの要素のための記述子は、以下のセクション ar(1) アーカイブの処理 で説明されているように返されます。

ELF_C_RDWR

コマンドは、読み込み書き込みのために ELF ファイルを準備するために使用されます。それはアーカイブのためにサポートされません。

引数 fd は、読み込み書き込み用にオープンされるべきです。引数 elf が NULL であるなら、ライブラリは、処理されるファイルのために新しい ELF 記述子を割り付けます。引数 elf が NULL でないなら、引数 fd と cmd と同じ値で以前に elf_begin() で割り付けられた記述子を示すべきです。この場合、ライブラリは、記述子 elf のために活性化 (activation) カウントを増加して、同じ記述子を返します。メモリ内の ELF ファイルイメージへの変更は、 elf_update(3) 関数を使用してディスクに書き戻されます。

このコマンドは、 ar(1) アーカイブでは有効ではありません。

ELF_C_WRITE

このコマンドは、アプリケーションが新しい ELF ファイルを作成したいとき、使用されます。引数 fd は、書き込みのためにオープンされるべきです。引数 elf は、無視され、引数 fd によって参照されたファイルの前の内容は、上書きされます。

戻り値

関数は、成功したなら、ELF 記述子へのポインタを返し、エラーが生じたなら、 NULL を返します。

使用例

ar(1) アーカイブのメンバを通して繰り返すためには、次を使用します:

Elf_Cmd c; 
Elf *ar_e, *elf_e; 
... 
c = ELF_C_READ; 
if ((ar_e = elf_begin(fd, c, (Elf *) 0)) == 0) { 
 ... handle error in opening the archive ... 
} 
while ((elf_e = elf_begin(fd, c, ar_e)) != 0) { 
 ... process member referenced by elf_e here ... 
 c = elf_next(elf_e); 
 elf_end(elf_e); 
}

新しい ELF ファイルを作成するために、次を使用します:

int fd; 
Elf *e; 
... 
if ((fd = open("filename", O_RDWR|O_TRUNC|O_CREAT, 0666)) < 0) { 
 ... handle the error from open(2) ... 
} 
if ((e = elf_begin(fd, ELF_C_WRITE, (Elf *) 0)) == 0) { 
 ... handle the error from elf_begin() ... 
} 
... create the ELF image using other elf(3) APIs ... 
elf_update(e, ELF_C_WRITE); 
elf_end(e);

エラー

関数 elf_begin() は、次のエラーで失敗します:

[ ELF_E_ARCHIVE]

引数 elf によって指示されたアーカイブが解析できませんでした。

[ ELF_E_ARGUMENT]

認識されていない値は、引数 cmd で指定されました。

[ ELF_E_ARGUMENT]

引数 elf の NULL でない値は、 cmd が ELF_C_RDWR に設定されたとき、指定されます。

[ ELF_E_ARGUMENT]

引数 fd の値が、ELF 記述子 elf が作成されたものと異なっています。

[ ELF_E_ARGUMENT]

引数 cmd は、ELF 記述子 elf が作成されたとき、指定された値と異なっています。

[ ELF_E_ARGUMENT]

ar(1) アーカイブは、 cmd に ELF_C_RDWR が設定された状態でオープンされました。

[ ELF_E_IO]

関数 elf_begin() は、 ELF_C_WRITE を使用して書き込みようにオープンされたファイルの先端を詰めることができませんでした。

[ ELF_E_RESOURCE]

メモリ不足の状態に遭遇しました。

[ ELF_E_SEQUENCE]

関数 elf_begin() は、動作するバージョンが elf_version(3) で確立される前に呼び出されました。

関連項目

elf(3), elf_end(3), elf_errno(3), elf_memory(3), elf_next(3), elf_rand(3), elf_update(3), gelf(3)