LdrQueryImageFileExecutionOptions

The LdrQueryImageFileExecutionOptions function queries one value in the Image File Execution Options key for a named image file.

Declaration

NTSTATUS 
LdrQueryImageFileExecutionOptions (
    PUNICODE_STRING lpImageFile, 
    PCWSTR lpszOption, 
    ULONG dwType, 
    PVOID lpData, 
    ULONG cbData, 
    ULONG *lpcbData);

Parameters

The lpImageFile argument names the executable image for which the option is sought. This can be NULL in version 6.0 and higher to query for global options.

The lpszOption argument names the one option whose value is sought.

The dwType argument specifies the type for the value as produced in the output buffer. This is typically also, but need not be, the required type for the value as stored in the registry.

The optional lpData and cbData arguments are respectively the address and size of the output buffer that is to receive the value. These arguments can be NULL and zero to query for the option’s existence or size.

The optional lpcbData argument provides the address of a variable that is to receive the size, in bytes, of the value that the successful function has put into the buffer and which may receive the size that the failed function might have put into the buffer (had the buffer been large enough). This argument can be NULL if the caller does not want to know how much data is produced or is available.

Return Value

The function returns STATUS_SUCCESS if successful, else a negative error code.

Of particular importance is STATUS_BUFFER_OVERFLOW, which is the function’s indication that the buffer, if any, is too small for the whole value and that a size that would have sufficed has been set into the variable, if any, that was specified through the lpcbData argument.

Availability

The LdrQueryImageFileExecutionOptions function is exported by name from NTDLL.DLL in all known Windows versions, i.e., 3.10 and higher.

Documentation Status

The LdrQueryImageFileExecutionOptions function is not documented. Neither is it declared in any C-language header that Microsoft is known to have published in any development kit for either user-mode or kernel-mode software. While Microsoft’s names and types for the function’s arguments are not known, this article uses inventions.

Behaviour

Starting with version 5.2, except on one point for version 10.0, the LdrQueryImageFileExecutionOptions is implemented as LdrQueryImageFileExecutionOptionsEx with FALSE for the latter’s extra argument. Starting with version 6.1, there is effectively no difference since the newer function ignores its extra argument.

The exception for version 10.0 is that this older function fails trivially for secure processes. The error code is STATUS_OBJECT_NAME_NOT_FOUND. A secure process has the 0x80000000 bit set in the Flags member of the process’s RTL_USER_PROCESS_PARAMETERS when the process initialised.

Early History

Before version 5.2, the LdrQueryImageFileExecutionOptions function behaves differently from the later LdrQueryImageFileExecutionOptionsEx in several respects, all of which may reasonably be disregarded nowadays as ancient coding errors. If they ever are written up for this website, they will be immediately below. For modern behaviour, look to the separate documentation of LdrQueryImageFileExecutionOptionsEx and read as if the new function had existed earlier.