ReBaseImage function (imagehlp.h)

Changes the load address for the specified image, which reduces the required load time for a DLL.

Alternatively, you can use the Rebase tool. This tool is available in Visual Studio and the Windows SDK.

Note that this function is implemented as a call to the ReBaseImage64 function.

Syntax

BOOL IMAGEAPI ReBaseImage(
  [in]      PCSTR     CurrentImageName,
  [in]      PCSTR     SymbolPath,
  [in]      BOOL      fReBase,
  [in]      BOOL      fRebaseSysfileOk,
  [in]      BOOL      fGoingDown,
  [in]      ULONG     CheckImageSize,
  [out]     ULONG     *OldImageSize,
  [out]     ULONG_PTR *OldImageBase,
  [out]     ULONG     *NewImageSize,
  [in, out] ULONG_PTR *NewImageBase,
  [in]      ULONG     TimeStamp
);

Parameters

[in] CurrentImageName

The name of the file to be rebased. You must specify the full path to the file unless the module is in the current working directory of the calling process.

[in] SymbolPath

The path used to find the corresponding symbol file. Specify this path for executable images that have symbolic information because when image addresses change, the corresponding symbol database file (PDB) may also need to be changed. Note that even if the symbol path is not valid, the function will succeed if it is able to rebases your image.

[in] fReBase

If this value is TRUE, the image is rebased. Otherwise, the image is not rebased.

[in] fRebaseSysfileOk

If this value is TRUE, the system image is rebased. Otherwise, the system image is not rebased.

[in] fGoingDown

If this value is TRUE, the image can be rebased below the given base; otherwise, it cannot.

[in] CheckImageSize

The maximum size that the image can grow to, in bytes, or zero if there is no limit.

[out] OldImageSize

A pointer to a variable that receives the original image size, in bytes.

[out] OldImageBase

A pointer to a variable that receives the original image base.

[out] NewImageSize

A pointer to a variable that receives the new image size after the rebase operation, in bytes.

[in, out] NewImageBase

The base address to use for rebasing the image. If the address is not available and the fGoingDown parameter is set to TRUE, the function finds a new base address and sets this parameter to the new base address. If fGoingDown is FALSE, the function finds a new base address but does not set this parameter to the new base address.

[in] TimeStamp

The new time date stamp for the image file header. The value must be represented in the number of seconds elapsed since midnight (00:00:00), January 1, 1970, Universal Coordinated Time, according to the system clock.

If this parameter is 0, the current file header time date stamp is incremented by 1 second.

Return value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To retrieve extended error information, call GetLastError.

Remarks

The ReBaseImage function changes the desired load address for the specified image. This operation involves reading the entire image and updating all fixups, debugging information, and checksum. You can rebase an image to reduce the required load time for its DLLs. If an application can rely on a DLL being loaded at the desired load address, then the system loader does not have to relocate the image. The image is simply loaded into the application's virtual address space and the DllMain function is called, if one is present.

All ImageHlp functions, such as this one, are single threaded. Therefore, calls from more than one thread to this function will likely result in unexpected behavior or memory corruption. To avoid this, you must synchronize all concurrent calls from more than one thread to this function.

You cannot rebase DLLs that link with /DYNAMICBASE or that reside in protected directories, such as the System32 folder.

As an alternative to using this function, see the /BASE linker option.

Requirements

Requirement Value
Minimum supported client Windows XP [desktop apps only]
Minimum supported server Windows Server 2003 [desktop apps only]
Target Platform Windows
Header imagehlp.h
Library Imagehlp.lib
DLL Imagehlp.dll

See also

DllMain

ImageHlp Functions