HP-UX Reference (11i v2 07/12) - 3 Library Functions A-M (vol 6)

e
elf_begin(3E) elf_begin(3E)
NAME
elf_begin - make a file descriptor
SYNOPSIS
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 non-null 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 position 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 non-null ELF descriptor that is not an archive, elf_begin incre-
ments the number of activations for the descriptor and returns ref, without allocating a
new descriptor and without changing the descriptor’s read/write permissions. To ter-
minate 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 pro-
gram 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 non-null, 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 non-null 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
limits the number of open files, the program can use elf_cntl to let it reuse file descriptors. After cal-
ling elf_cntl with appropriate arguments, the program may close the file descriptor without interfering
with the library.
342 Hewlett-Packard Company − 1 − HP-UX 11i Version 2: December 2007 Update