LdrLockLoaderLock

This function enters (or tries to enter) the special critical section known as the loader lock.

Declaration

NTSTATUS
LdrLockLoaderLock (
    ULONG Flags,
    ULONG *State,
    ULONG *Cookie);

Parameters

The Flags argument supplies bit flags to vary the function’s behaviour. There are two supported values:

The State argument is the address of a variable that is to receive an explanation of whether the function entered the loader lock or returned without waiting. This argument is needed only if the 0x02 bit is set in the Flags, and may otherwise be NULL. The value produced at the given address can be one of the following:

The Cookie argument is the address of a variable that is to receive a cookie for use with LdrUnlockLoaderLock.

Return Value

The function returns zero for success, else an error code.

If the 0x01 bit is set in the Flags, then all errors are reported as exceptions. If the function returns at all, it is successful. Indeed, the point to the 0x01 bit is surely that the function may be treated as returning void.

Behaviour

The function distinguishes several cases of invalid parameter:

Except for invalid parameters, the function can fail only if an exception occurs while trying to enter the loader lock or return data at the addresses given by the State and Cookie arguments. If the 0x01 bit is clear, such exceptions are caught within the function, so that the exception code becomes the returned value. A message may be written to the debugger:

LDR: LdrLockLoaderLock - caught exception status

The function succeeds trivially, i.e., without trying to enter the loader lock, if called while NTDLL is initialising a process.

If the 0x02 bit is clear in the Flags, the function enters the loader lock, waiting as long as needed.

If the 0x02 bit is set in the Flags, the function tries to enter the loader lock. If this fails, i.e., because the critical section is already owned, the function succeeds. The variable at the address given by the State argument is set to 0x02 to indicate that the loader lock is not entered. No cookie is produced in this case.

Whether the 0x02 bit is set or not, if the function enters the loader lock, it does two things. First, to indicate that it has entered the loader lock, it sets the State variable to 0x01. This step is skipped if the 0x02 bit is clear in the Flags and the State argument is NULL. Second, the function stores a cookie at the address given by the Cookie argument. This cookie is to be passed back to NTDLL when releasing the loader lock. The cookie is surely intended not to be interpreted. If only at present, the low word is a serial number and the high word is the low 12 bits of the thread ID.

Availability

The LdrLockLoaderLock function is exported by name from NTDLL.DLL in version 5.1 and higher.