Function
elf_begin() is used to open ELF files and
ar(1) archives for further processing by other APIs in the
elf(3) library. It is also used to access individual ELF members of an
ar(1) archive in combination with the
elf_next(3) and
elf_rand(3) APIs.
Argument
fd is an open file descriptor returned from an
open(2) system call. Function
elf_begin() uses argument
fd for reading or writing depending on the value of argument
cmd. Argument
elf is primarily used for iterating through archives.
The argument
cmd can have the following values:
ELF_C_NULL
Causes elf_begin() to return NULL. Arguments fd and elf are ignored, and no additional error is signalled.
ELF_C_READ
This value is to be when the application wishes to examine (but not modify) the contents of the file specified by argument
fd. It can be used for both
ar(1) archives and for regular ELF files.
Argument
fd should have been opened for reading. If argument
elf is NULL, the library will allocate a new ELF descriptor for the file being processed. If argument
elf is not NULL, and references a regular ELF file previously opened with
elf_begin(), then the activation count for
elf is incremented. If argument
elf is not NULL, and references a descriptor for an
ar(1) archive opened earlier with
elf_begin(), a descriptor for an element in the archive is returned as described in the section
Processing ar(1) archives below.
ELF_C_RDWR
The command is used to prepare an ELF file for reading and writing. It is not supported for archives.
Argument
fd should have been opened for reading and writing. If argument
elf is NULL, the library will allocate a new ELF descriptor for the file being processed. If the argument
elf is non-null, it should point to a descriptor previously allocated with
elf_begin() with the same values for arguments
fd and
cmd; in this case the library will increment the activation count for descriptor
elf and return the same descriptor. Changes to the in-memory image of the ELF file are written back to disk using the
elf_update(3) function.
This command is not valid for
ar(1) archives.
ELF_C_WRITE
This command is used when the application wishes to create a new ELF file. Argument fd should have been opened for writing. Argument elf is ignored, and the previous contents of file referenced by argument fd are overwritten.
Processing ar(1) archives
An
ar(1) archive may be opened in read mode (with argument
cmd set to
ELF_C_READ) using
elf_begin(). The returned ELF descriptor can be passed into to subsequent calls to
elf_begin() to access individual members of the archive.
Random access within an opened archive is possible using the
elf_next(3) and
elf_rand(3) functions.
The symbol table of the archive may be retrieved using
elf_getarsym(3).