ldlread, ldlinit, or ldlitem Subroutine

Purpose

Manipulates line number entries of a common object file function.

Library

Object File Access Routine Library (libld.a)

Syntax

#include <stdio.h>
#include <ldfcn.h>

int ldlread ( ldPointer,  FunctionIndex,  LineNumber,  LineEntry)
LDFILE *ldPointer;
int FunctionIndex;
unsigned short LineNumber;
void *LineEntry;

int ldlinit (ldPointer, FunctionIndex)
LDFILE *ldPointer;
int FunctionIndex;

int ldlitem (ldPointer, LineNumber, LineEntry)
LDFILE *ldPointer;
unsigned short LineNumber;
void *LineEntry;

Description

The ldlread subroutine searches the line number entries of the XCOFF file currently associated with the ldPointer parameter. The ldlread subroutine begins its search with the line number entry for the beginning of a function and confines its search to the line numbers associated with a single function. The function is identified by the FunctionIndex parameter, the index of its entry in the object file symbol table. The ldlread subroutine reads the entry with the smallest line number equal to or greater than the LineNumber parameter into the memory beginning at the LineEntry parameter. It is the responsibility of the calling routine to provide a pointer to a buffer large enough to contain the line number entry for the associated object file type. Since the ldopen subroutine provides magic number information (via the HEADER(ldPointer).f_magic macro), the calling application can always determine whether the LineEntry pointer should refer to a 32-bit LINENO or 64-bit LINENO_64 structure.

The ldlinit and ldlitem subroutines together perform the same function as the ldlread subroutine. After an initial call to the ldlread or ldlinit subroutine, the ldlitem subroutine may be used to retrieve successive line number entries associated with a single function. The ldlinit subroutine simply locates the line number entries for the function identified by the FunctionIndex parameter. The ldlitem subroutine finds and reads the entry with the smallest line number equal to or greater than the LineNumber parameter into the memory beginning at the LineEntry parameter.

Parameters

Item Description
ldPointer Points to the LDFILE structure that was returned as the result of a successful call to the ldopen , lddopen,or ldaopen subroutine.
LineNumber Specifies the index of the first LineNumber parameter entry to be read.
LineEntry Points to a buffer that will be filled in with a LINENO structure from the object file.
FunctionIndex Points to the symbol table index of a function.

Return Values

The ldlread, ldlinit, and ldlitem subroutines return a SUCCESS or FAILURE value.

Error Codes

The ldlread subroutine fails if there are no line number entries in the object file, if the FunctionIndex parameter does not index a function entry in the symbol table, or if it finds no line number equal to or greater than the LineNumber parameter. The ldlinit subroutine fails if there are no line number entries in the object file or if the FunctionIndex parameter does not index a function entry in the symbol table. The ldlitem subroutine fails if it finds no line number equal to or greater than the LineNumber parameter.