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

Technical Reference: Base Operating System and Extensions, Volume 1


loadquery Subroutine

The loadquery subroutine includes information for loadquery on a POWER-based platform and an loadquery on an Itanium-based platform.

loadquery subroutine on POWER-based Platform

Purpose

Returns error information from the load or exec subroutine; also provides a list of object files loaded for the current process.

Syntax


int loadquery( Flags Buffer, BufferLength)
int Flags;
void *Buffer;
unsigned int BufferLength;

Description

The loadquery subroutine obtains detailed information about an error reported on the last load or exec subroutine executed by a calling process. The loadquery subroutine may also be used to obtain a list of object file names for all object files that have been loaded for the current process, or the library path that was used at process exec time.

Parameters


Buffer Points to a Buffer in which to store the information.
BufferLength Specifies the number of bytes available in the Buffer parameter.
Flags Specifies the action of the loadquery subroutine as follows:

L_GETINFO
Returns a list of all object files loaded for the current process, and stores the list in the Buffer parameter. The object file information is contained in a sequence of LD_INFO structures as defined in the sys/ldr.h file. Each structure contains the module location in virtual memory and the path name that was used to load it into memory. The file descriptor field in the LD_INFO structure is not filled in by this function.

L_GETMESSAGE
Returns detailed error information describing the failure of a previously invoked load or exec function, and stores the error message information in Buffer. Upon successful return from this function the beginning of the Buffer contains an array of character pointers. Each character pointer points to a string in the buffer containing a loader error message. The character array ends with a null character pointer. Each error message string consists of an ASCII message number followed by zero or more characters of error-specific message data. Valid message numbers are listed in the sys/ldr.h file.

You can format the error messages returned by the L_GETMESSAGE function and write them to standard error using the standard system command /usr/sbin/execerror as follows:

char *buffer[1024];
buffer[0] = "execerror";
buffer[1] ="name of program that failed\  to 
load";
loadquery(L_GETMESSAGES, &buffer[2],\
  sizeof buffer -8);
execvp("/usr/sbin/execerror",buffer);

This sample code causes the application to terminate after the messages are written to standard error.

L_GETLIBPATH
Returns the library path that was used at process exec time. The library path is a null terminated character string.

Return Values

Upon successful completion, loadquery returns the requested information in the caller's buffer specified by the Buffer and BufferLength parameters.

Error Codes

The loadquery subroutine returns with a return code of -1 and the errno global variable is set to one of the following when an error condition is detected:

ENOMEM Indicates that the caller's buffer specified by the Buffer and BufferLength parameters is too small to return the information requested. When this occurs, the information in the buffer is undefined.
EINVAL Indicates the function specified in the Flags parameter is not valid.
EFAULT Indicates the address specified in the Buffer parameter is not valid.

Implementation Specifics

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

Related Information

The exec (exec: execl, execle, execlp, execv, execve, execvp, or exect Subroutine) subroutine, load (load Subroutine) subroutine, loadbind (loadbind Subroutine) subroutine, unload subroutine.

The ld command.

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

loadquery subroutine on Itanium-based Platform

Purpose

Returns error information from the loadsubroutine; also provides a list of object files loaded for the current process.

Syntax


int loadquery( Flags Buffer, BufferLength)
int Flags;
void *Buffer;
unsigned int BufferLength;

Description

The loadquery subroutine obtains detailed information about an error reported on the last load subroutine executed by a calling process. The loadquery subroutine may also be used to obtain a list of object file names for all object files that have been loaded for the current process, or the library path that was used at process exec time.

Parameters


Buffer Points to a Buffer in which to store the information.
BufferLength Specifies the number of bytes available in the Buffer parameter.
Flags Specifies the action of the loadquery subroutine as follows:

L_GETINFO
Returns a list of all object files loaded for the current process, and stores the list in the Buffer parameter. The object file information is contained in a sequence of ld_info structures as defined in the sys/ldr.h file. Each structure contains the module location in virtual memory and the path name that was used to load it into memory. The file descriptor field in the ld_info structure is not filled in by this function.

L_GETMESSAGE
Returns detailed error information describing the failure of a previously invoked load function, and stores the error message information in Buffer. Upon successful return from this function the beginning of the Buffer contains an array of character pointers. Each character pointer points to a string in the buffer containing a loader error message. The character array ends with a null character pointer. Each error message string consists of an ASCII message number followed by zero or more characters of error-specific message data. Valid message numbers are listed in the sys/ldr.h file.

You can format the error messages returned by the L_GETMESSAGE function and write them to standard error using the standard system command /usr/sbin/execerror as follows:

char *buffer[1024];
buffer[0] = "execerror";
buffer[1] ="name of program that failed \
  to  load";
loadquery(L_GETMESSAGES, &buffer[2],\
  sizeof buffer -sizeof(int));
execvp("/usr/sbin/execerror",buffer);

This sample code causes the application to terminate after the messages are written to standard error.

Return Values

Upon successful completion, loadquery returns the requested information in the caller's buffer specified by the Buffer and BufferLength parameters.

Error Codes

The loadquery subroutine returns with a return code of -1 and the errno global variable is set to one of the following when an error condition is detected:

ENOMEM Indicates that the caller's buffer specified by the Buffer and BufferLength parameters is too small to return the information requested. When this occurs, the information in the buffer is undefined.
EINVAL Indicates the function specified in the Flags parameter is not valid.
EFAULT Indicates the address specified in the Buffer parameter is not valid.

Related Information

The exec (exec: execl, execle, execlp, execv, execve, execvp, or exect Subroutine) subroutine, load (load Subroutine) subroutine, loadbind (loadbind Subroutine) subroutine, unload subroutine.

The ld command.

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


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