[ Previous | Next | Table of Contents | Index | Library Home | Legal | Search ]

Technical Reference: Base Operating System and Extensions, Volume 1


ldopen or ldaopen Subroutine

Purpose

Opens an object or archive file for reading.

Library

Object File Access Routine Library (libld.a)

Syntax


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


LDFILE *ldopen( FileName, ldPointer)
char *FileName;
LDFILE *ldPointer;


LDFILE *ldaopen(FileName, ldPointer)
char *FileName;
LDFILE *ldPointer;


LDFILE *lddopen(FileDescriptor, type, ldPointer)
int FileDescriptor;
char *type;
LDFILE *ldPointer;

Description

The ldopen and ldclose subroutines provide uniform access to both simple object files and object files that are members of archive files. Thus, an archive of object files can be processed as if it were a series of ordinary object files.

If the ldPointer is null, the ldopen subroutine opens the file named by the FileName parameter and allocates and initializes an LDFILE structure, and returns a pointer to the structure.

If the ldPointer parameter is not null and refers to an LDFILE for an archive, the structure is updated for reading the next archive member. In this case, and if the value of the TYPE(ldPointer) macro is the archive magic number ARTYPE.

The ldopen and ldclose subroutines are designed to work in concert. The ldclose subroutine returns failure only when the ldPointer refers to an archive containing additional members. Only then should the ldopen subroutine be called with a num-null ldPointer argument. In all other cases, in particular whenever a new FileName parameter is opened, the ldopen subroutine should be called with a null ldPointer argument.

If the value of the ldPointer parameter is not null, the ldaopen subroutine opens the FileName parameter again and allocates and initializes a new LDFILE structure, copying the TYPE, OFFSET, and HEADER fields from the ldPointer parameter. The ldaopen subroutine returns a pointer to the new ldfile structure. This new pointer is independent of the old pointer, ldPointer. The two pointers may be used concurrently to read separate parts of the object file. For example, one pointer may be used to step sequentially through the relocation information, while the other is used to read indexed symbol table entries.

The lddopen function accesses the previously opened file referenced by the FileDescriptor parameter. In all other respects, it functions the same as the ldopen subroutine.

For AIX 4.3.2 and above, the functions transparently open both 32-bit and 64-bit object files, as well as both small format and large format archive files. Once a file or archive is successfully opened, the calling application can examine the HEADER(ldPointer).f_magic field to check the magic number of the file or archive member associated with ldPointer. (This is necessary due to an archive potentially containing members that are not object files.) The magic numbers U802TOCMAGIC and (for AIX 4.3.2 and above) U803XTOCMAGIC are defined in the ldfcn.h file. If the value of TYPE(ldPointer) is the archive magic numberARTYPE, the flags field can be checked for the archive type. Large format archives will have the flag bit AR_TYPE_BIG set in LDFLAGS(ldPointer). Large format archives are available on AIX 4.3 and later.

Parameters


FileName Specifies the file name of an object file or archive.
ldPointer Points to an LDFILE structure.
FileDescriptor Specifies a valid open file descriptor.
type Points to a character string specifying the mode for the open file. The fdopen function is used to open the file.

Error Codes

Both the ldopen and ldaopen subroutines open the file named by the FileName parameter for reading. Both functions return a null value if the FileName parameter cannot be opened, or if memory for the LDFILE structure cannot be allocated.

A successful open does not ensure that the given file is a common object file or an archived object file.

Examples

The following is an example of code that uses the ldopen and ldclose subroutines:

/* for each FileName to be processed */
 
 ldPointer = NULL;
 do
               
 if((ldPointer = ldopen(FileName, ldPointer)) != NULL)
                 
                      /* check magic number */
                      /* process the file */
                 "
                 " 
   while(ldclose(ldPointer) == FAILURE );

Implementation Specifics

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

Related Information

The ldclose or ldaclose (ldclose or ldaclose Subroutine) subroutine, fopen, fopen64, freopen, freopen64, or fdopen (fopen, fopen64, freopen, freopen64 or fdopen Subroutine) subroutine.

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


[ Previous | Next | Table of Contents | Index | Library Home | Legal | Search ]