elf_begin.3e (2010 09)

e
elf_begin(3E) elf_begin(3E)
NAME
elf_begin() - make file descriptor for ELF file
SYNOPSIS
Command:
cc [flag]... file...
-lelf [library ]...
#include <libelf.h>
Elf *elf_begin(
int fildes,
Elf_Cmd cmd,
Elf *ref
);
DESCRIPTION
elf_begin(), elf_next(), elf_rand(), and elf_end()
work together to process ELF object
files, either individually or as members of archives. After obtaining an ELF descriptor from
elf_begin(), the program may read an existing file, update an existing file, or create a new file. fildes
is an open file descriptor that
elf_begin() uses for reading or writing. The initial file offset (see
lseek (2)) is unconstrained, and the resulting file offset is undefined. cmd may have the following values.
ELF_C_NULL When a program sets cmd to this value, elf_begin() returns a null pointer,
without opening a new descriptor. ref is ignored for this command. See
elf_next (3E) and the examples below for more information.
ELF_C_READ When a program wishes to examine the contents of an existing file, it should set
cmd to this value. Depending on the value of ref, this command examines archive
members or entire files. Three cases can occur.
First, if ref is a null pointer,
elf_begin() allocates a new ELF descriptor and
prepares to process the entire file. If the file being read is an archive,
elf_begin() also prepares the resulting descriptor to examine the initial archive
member on the next call to elf_begin(), as if the program had used
elf_next() or elf_rand() to "move" to the initial member.
Second, if ref is a nonnull descriptor associated with an archive file,
elf_begin()
lets a program obtain a separate ELF descriptor associated with an individual
member. The program should have used elf_next() or elf_rand() to posi-
tion ref appropriately (except for the initial member, which
elf_begin()
prepares; see the example below). In this case, fildes should be the same file
descriptor used for the parent archive.
Finally, if ref is a nonnull ELF descriptor that is not an archive,
elf_begin()
increments the number of activations for the descriptor and returns ref, without
allocating a new descriptor and without changing the descriptor’s read/write permis-
sions. To terminate the descriptor for ref , the program must call elf_end() once
for each activation. See elf_next (3E) and the examples below for more information.
ELF_C_RDWR This command duplicates the actions of ELF_C_READ and additionally allows the
program to update the file image (see elf_update (3E)). That is, using ELF_C_READ
gives a read-only view of the file, while ELF_C_RDWR lets the program read and
write the file. ELF_C_RDWR is not valid for archive members. If ref is nonnull, it
must have been created with the ELF_C_RDWR command.
ELF_C_WRITE If the program wishes to ignore previous file contents, presumably to create a new
file, it should set cmd to this value. ref is ignored for this command.
elf_begin() "works" on all files (including files with zero bytes), providing it can allocate memory for
its internal structures and read any necessary information from the file. Programs reading object files
thus may call elf_kind() or elf_getehdr() to determine the file type (only object files have an
ELF header). If the file is an archive with no more members to process, or an error occurs,
elf_begin() returns a null pointer. Otherwise, the return value is a nonnull ELF descriptor. Before
the first call to elf_begin(), a program must call elf_version() to coordinate versions.
System Services
When processing a file, the library decides when to read or write the file, depending on the program’s
requests. Normally, the library assumes the file descriptor remains usable for the life of the ELF descrip-
tor. If, however, a program must process many files simultaneously and the underlying operating system
HP-UX 11i Version 3: September 2010 − 1 − Hewlett-Packard Company 1