ldlread, ldlinit, or ldlitem Subroutine

AIX Version 4.3 Base Operating System and Extensions Technical Reference, Volume 1

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

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.

Implementation Specifics

These subroutines are part of Base Operating System (BOS) Runtime.

Related Information

The ldahread subroutine, ldfhread subroutine, ldgetname subroutine, ldshread or ldnshread subroutine, ldtbread subroutine.

Subroutines Overview in AIX Version 4.3 General Programming Concepts: Writing and Debugging Programs.