Jump to content United States-English
HP.com Home Products and Services Support and Drivers Solutions How to Buy
» Contact HP
More options
HP.com home
HP-UX Reference > D

dlgetfileinfo(3C)

HP-UX 11i Version 3: February 2007
» 

Technical documentation

» Feedback
Content starts here

 » Table of Contents

 » Index

NAME

dlgetfileinfo() — return file information for a library prior to loading it

SYNOPSIS

cc [flag... ] file... -ldl [library]...

#include <dlfcn.h>

uint64_t dlgetfileinfo(const char *file, size_t info_size, struct dlfileinfo *info);

Multithread Usage

This routine is thread-safe.

DESCRIPTION

dlgetfileinfo() is one of a family of routines that give the user direct access to the dynamic linking facilities (using the -ldl option on the compiler or ld command line). dlgetfileinfo() returns file information for a library prior to loading it. This information can be used to allocate load segments before calling dlopene().

file is used to construct a path name to the library. The dynamic loader searches for the library using the standard search rules used by dlopen() and dlopene(). If the library is found and is a valid shared library, dlgetfileinfo returns information about the library through the info parameter.

info_size is the size in bytes of the info buffer.

info is a pointer to a buffer allocated by the user program. The dynamic loader fills this buffer with file information.

A dlfileinfo structure has the following members:

struct dlfileinfo { size_t text_size; size_t data_size; char *filename; }

text_size is the size in bytes of a shared library's text segment.

data_size is the size in bytes of a shared library's data segment.

filename is the path to the shared library. This path may be passed to a subsequent dlopen() or dlopene() call to avoid searching for the library a second time. The caller of dlgetfileinfo() must copy the value of filename to insure that it is not corrupted.

EXAMPLES

The following example illustrates the use of dlgetfileinfo() to allocate memory for mapping a shared library's data segment. For simplicity, error checking has been omitted.

#include <dlfcn.h> #include <string.h> /* allocate_data is a user-supplied routine that allocates a * a memory buffer of at least "data_size" bytes and returns * a pointer to the buffer. */ extern char *allocate_data(size_t data_size); int main() { void *handle; int status; char *pathname; struct dlfileinfo info; struct dlopen_opts opts; /* Locate library and get file information */ status = dlgetfileinfo("mylib.so", sizeof(info), &info); if (status == 0) { /* Make a copy of the library pathname returned by * dlgetfileinfo(). */ pathname = strdup(info.filename); /* Allocate data segment */ opts.data_addr = allocate_data(info.data_size); /* Not preallocating text segment */ opts.text_addr = 0; /* Set dlopene() flags to indicate the data segment * has been preallocated. */ opts.flags = RTLD_EXT_DATA_ADDR; /* Call dlopene() to load the library using the path * where dlgetfileinfo found the library and the * preallocated memory buffer for mapping the library's * data segment. */ handle = dlopene(pathname, RTLD_LAZY, &opts); /* Remove copy of library pathname */ free(pathname); /* Insert code here to use library */ /* Close library */ status = dlclose(handle); /* Insert code here to free storage allocated by * allocate_data(). */ } }

RETURN VALUE

If successful, dlgetfileinfo() returns 0, otherwise a non-0 value is returned. More detailed diagnostic information is available through dlerror() or dlerrno().

ERRORS

If dlgetfileinfo() fails, a subsequent call to dlerrno() returns one of the following values:

RTLD_ERR_BAD_ELF_VER

Unknown ELF version in library.

RTLD_ERR_LIB_OPEN

Unable to find library.

RTLD_ERR_NO_MEMORY

Cannot allocate dynamic memory.

RTLD_ERR_INTERNAL_ERROR

Internal error encountered in dlgetfileinfo().

RTLD_ERR_CANT_APPLY_RELOC

Failed to apply relocation while resolving call to dlgetfileinfo().

RTLD_ERR_SIGINHIBIT_FAILED

siginhibit call failed on entry to dlgetfileinfo().

RTLD_ERR_SIGENABLE_FAILED

sigenable call failed on exit from dlgetfileinfo().

RTLD_ERR_BAD_ABI1

ABI mismatch because a 64-bit program found a 32-bit shared library.

RTLD_ERR_BAD_ABI2

ABI mismatch because a 32-bit program found a 64-bit shared library.

RTLD_ERR_BAD_DLL_MAGIC_NUM

The library is invalid due to a bad magic number.

RTLD_ERR_BAD_DLL_BAD_MACHINE

The library is invalid due to a bad machine type.

RTLD_ERR_BAD_DLL_BAD_OBJFILE

The library is invalid due to a bad object file type.

RTLD_ERR_SETCANCELSTATE_FAILED

__thread_setcancelstate failed on entry to or exit from dlgetfileinfo().

RTLD_ERR_DLGETFILEINFO_MTEXT

Cannot return file information because the library has multiple text segments.

RTLD_ERR_DLGETFILEINFO_MDATA

Cannot return file information because the library has multiple data segments.

RTLD_ERR_INV_DLGETFILEINFO_ARGUMENT

Invalid argument in call to dlgetfileinfo().

RTLD_ERR_DLGETFILEINFO_IO

An IO error occurred while reading the file information.

SEE ALSO

dlerrno(3C), dlerror(3C), dlopen(3C), dlopene(3C), dlsetlibpath(3C).

Texts and Tutorials:

HP-UX Linker and Libraries Online User Guide

(See the +help option)

HP-UX Linker and Libraries User's Guide

(See manuals(5) for ordering information)

Printable version
Privacy statement Using this site means you accept its terms Feedback to webmaster
© 1983-2007 Hewlett-Packard Development Company, L.P.