Technical Reference: Base Operating System and Extensions, Volume 1

ldgetname Subroutine

Purpose

Retrieves symbol name for common object file symbol table entry.

Library

Object File Access Routine Library (libld.a)

Syntax

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

char *ldgetname ( ldPointer, Symbol)
LDFILE *ldPointer;
void *Symbol;

Description

The ldgetname subroutine returns a pointer to the name associated with Symbol as a string. The string is in a static buffer local to the ldgetname subroutine that is overwritten by each call to the ldgetname subroutine and must therefore be copied by the caller if the name is to be saved.

The common object file format handles arbitrary length symbol names with the addition of a string table. The ldgetname subroutine returns the symbol name associated with a symbol table entry for an XCOFF-format object file.

The calling routine to provide a pointer to a buffer large enough to contain a symbol table entry for the associated object file. Since the ldopen subroutine provides magic number information (via the HEADER(ldPointer).f_magic macro), the calling application can always determine whether the Symbol pointer should refer to a 32-bit SYMENT or 64-bit SYMENT_64 structure.

The maximum length of a symbol name is BUFSIZ, defined in the stdio.h file.

Parameters

Error Codes

The ldgetname subroutine returns a null value (defined in the stdio.h file) for a COFF-format object file if the name cannot be retrieved. This situation can occur if one of the following is true:

• The string table cannot be found.
• The string table appears invalid (for example, if an auxiliary entry is handed to the ldgetname subroutine wherein the name offset lies outside the boundaries of the string table).
• The name's offset into the string table is past the end of the string table.

Typically, the ldgetname subroutine is called immediately after a successful call to the ldtbread subroutine to retrieve the name associated with the symbol table entry filled by the ldtbread subroutine.

Examples

The following is an example of code that determines the object file type before making a call to the ldtbread and ldgetname subroutines.

#define __XCOFF32__
#define __XCOFF64__
 
#include <ldfcn.h>
 
 
SYMENT    Symbol32;
SYMENT_64 Symbol64;
void      *Symbol;
 
if ( HEADER(ldPointer).f_magic == U802TOCMAGIC )
    Symbol = &Symbol32;
else if ( HEADER(ldPointer).f_magic == U803XTOCMAGIC )
    Symbol = &Symbol64;
else
    Symbol = NULL;
 
if ( Symbol )
    /* for each symbol in the symbol table */
    for ( symnum = 0 ; symnum < HEADER(ldPointer).f_nsyms ; symnum++ )
    {
        if ( ldtbread(ldPointer,symnum,Symbol) == SUCCESS )
        {
            char *name = ldgetname(ldPointer,Symbol)
 
            if ( name )
            {
                /* Got the name... */
                .
                .
            }
 
            /* Increment symnum by the number of auxiliary entries */
            if ( HEADER(ldPointer).f_magic == U802TOCMAGIC )
                symnum += Symbol32.n_numaux;
            else if ( HEADER(ldPointer).f_magic == U803XTOCMAGIC )
                symnum += Symbol64.n_numaux;
        }
        else
        {
            /* Should have been a symbol...indicate the error */
                .
                .
        }
    }

Implementation Specifics

This subroutine is part of Base Operating System (BOS) Runtime.

Related Information

The ldahread (ldahread Subroutine) subroutine, ldfhread (ldfhread Subroutine) subroutine, ldlread, ldlinit, or ldlitem (ldlread, ldlinit, or ldlitem Subroutine)subroutine, ldshread or ldnshread (ldshread or ldnshread Subroutine) subroutine, ldtbread (ldtbread Subroutine) subroutine.

Subroutines Overview in AIX 5L Version 5.1 General Programming Concepts: Writing and Debugging Programs.