Skip to content

Commit 005ba1b

Browse files
author
Colin Robertson
authored
Merge pull request MicrosoftDocs#1870 from MicrosoftDocs/master637154038914970738
Fix git push error for protected CLA branch
2 parents 478a2f5 + 3dcf382 commit 005ba1b

4 files changed

Lines changed: 138 additions & 68 deletions

‎docs/build/reference/dependentloadflag.md‎

Lines changed: 28 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,21 @@
11
---
22
title: "/DEPENDENTLOADFLAG (Set default dependent load flags)"
3-
description: "The /DEPENDENTLOADFLAG option sets default flags for DLLs loaded using LoadLibrary"
4-
ms.date: "12/22/2018"
3+
description: "The /DEPENDENTLOADFLAG option sets default dependent load flags for DLLs loaded by this module."
4+
ms.date: "01/22/2020"
55
f1_keywords: ["dependentloadflag"]
66
helpviewer_keywords: ["LINK tool [C++], dependent load flags", "-DEPENDENTLOADFLAG linker option", "linker [C++], DEPENDENTLOADFLAG", "DEPENDENTLOADFLAG linker option", "/DEPENDENTLOADFLAG linker option"]
77
---
88
# /DEPENDENTLOADFLAG (Set default dependent load flags)
99

10-
Sets the default load flags used when `LoadLibrary` is used to load DLLs.
10+
::: moniker range="vs-2015"
11+
12+
The **/DEPENDENTLOADFLAG** option requires Visual Studio 2017 or later.
13+
14+
::: moniker-end
15+
16+
::: moniker range=">=vs-2017"
17+
18+
Sets the default load flags used when the operating system resolves the statically linked imports of a module.
1119

1220
## Syntax
1321

@@ -16,17 +24,23 @@ Sets the default load flags used when `LoadLibrary` is used to load DLLs.
1624
### Arguments
1725

1826
*load_flags*<br/>
19-
An optional "C"-style 16-bit integer value in decimal, octal with a leading zero, or hexadecimal with a leading `0x`, that specifies the dependent load flags to apply to all [LoadLibrary](/windows/win32/api/libloaderapi/nf-libloaderapi-loadlibraryexw) calls. The default value is 0.
27+
An optional integer value that specifies the load flags to apply when resolving statically linked import dependencies of the module. The default value is 0. For a list of supported flag values, see the `LOAD_LIBRARY_SEARCH_*` entries in [LoadLibraryEx](/windows/win32/api/libloaderapi/nf-libloaderapi-loadlibraryexw).
2028

2129
## Remarks
2230

23-
This option is new in Visual Studio 2017. It applies only to apps running on Windows 10 RS1 and later versions. This option is ignored by other operating systems that run the app.
31+
When the operating system resolves the statically linked imports of a module, it uses the [default search order](/windows/win32/dlls/dynamic-link-library-search-order). Use the **/DEPENDENTLOADFLAG** option to specify a *load_flags* value that changes the search path used to resolve these imports. On supported operating systems, it changes the static import resolution search order, similar to what [LoadLibraryEx](/windows/win32/api/libloaderapi/nf-libloaderapi-loadlibraryexa) does when using `LOAD_LIBRARY_SEARCH` parameters. For information on the search order set by *load_flags*, see [Search order using LOAD_LIBRARY_SEARCH flags](/windows/win32/dlls/dynamic-link-library-search-order#search-order-using-load_library_search-flags).
2432

25-
On supported operating systems, this option has the effect of changing calls to `LoadLibrary("dependent.dll")` to the equivalent of `LoadLibraryEx("dependent.dll", 0, load_flags)`. Calls to [LoadLibraryEx](/windows/win32/api/libloaderapi/nf-libloaderapi-loadlibraryexw) are unaffected. This option doesn't apply recursively to DLLs loaded by your app.
33+
This flag can be used to make one [DLL planting attack](/windows/win32/dlls/dynamic-link-library-security) vector more difficult. For example, consider an app that has statically linked a DLL:
2634

27-
This flag can be used to make [DLL planting attacks](/windows/win32/dlls/dynamic-link-library-security) more difficult. For example, if an app uses `LoadLibrary` to load a dependent DLL, an attacker could plant a DLL with the same name in the search path used by `LoadLibrary`, such as the current directory, which may be checked before system directories if safe DLL search mode is disabled. Safe DLL search mode places the user's current directory later in the search order, and is enabled by default on Windows XP SP2 and later versions. For more information, see [Dynamic-Link Library Search Order](/windows/win32/Dlls/dynamic-link-library-search-order).
35+
- An attacker could plant a DLL with the same name earlier in the import resolution search path, such as the application directory. Protected directories are more difficult - but not impossible - for an attacker to change.
2836

29-
If you specify the link option `/DEPENDENTLOADFLAG:0xA00` (the value of the combined flags `LOAD_LIBRARY_SEARCH_APPLICATION_DIR | LOAD_LIBRARY_SEARCH_SYSTEM32`), then even if safe DLL search mode is disabled on the user's computer, the DLL search path is limited to the application directory, followed by the %windows%\system32 directory. An option of `/DEPENDENTLOADFLAG:0x800` is even more restrictive, limiting search to the %windows%\system32 directory. Protected directories are more difficult - but not impossible - for an attacker to change. For information on the flags available, and their symbolic and numeric values, see the *dwFlags* parameter description in [LoadLibraryEx](/windows/win32/api/libloaderapi/nf-libloaderapi-loadlibraryexw). For information on the search order used when various dependent load flags are used, see [Search order using LOAD_LIBRARY_SEARCH flags](/windows/win32/dlls/dynamic-link-library-search-order#search-order-using-load_library_search-flags).
37+
- If the DLL is missing from the application, %windows%\system32, and %windows% directories, import resolution falls through to the current directory. An attacker could plant a DLL there.
38+
39+
In both cases, if you specify the link option `/DEPENDENTLOADFLAG:0x800` (the value of the flag `LOAD_LIBRARY_SEARCH_SYSTEM32`), then the module search path is limited to the %windows%\system32 directory. It offers some protection from planting attacks on the other directories. For more information, see [Dynamic-Link Library Security](/windows/win32/dlls/dynamic-link-library-security).
40+
41+
To see the value set by the **/DEPENDENTLOADFLAG** option in any DLL, use the [DUMPBIN](dumpbin-reference.md) command with the [/LOADCONFIG](loadconfig.md) option.
42+
43+
The **/DEPENDENTLOADFLAG** option is new in Visual Studio 2017. It applies only to apps running on Windows 10 RS1 and later versions. This option is ignored by other operating systems that run the app.
3044

3145
### To set the DEPENDENTLOADFLAG linker option in the Visual Studio development environment
3246

@@ -43,8 +57,11 @@ If you specify the link option `/DEPENDENTLOADFLAG:0xA00` (the value of the comb
4357
## See also
4458

4559
- [MSVC linker reference](linking.md)
46-
- [MSVC Linker Options](linker-options.md)
47-
- [Link an executable to a DLL](../linking-an-executable-to-a-dll.md#linking-implicitly)
48-
- [Link an executable to a DLL](../linking-an-executable-to-a-dll.md#determining-which-linking-method-to-use)
60+
- [MSVC linker options](linker-options.md)
61+
- [Link an executable to a DLL implicitly](../linking-an-executable-to-a-dll.md#linking-implicitly)
62+
- [Determine which linking method to use](../linking-an-executable-to-a-dll.md#determining-which-linking-method-to-use)
4963
- [LoadLibraryEx](/windows/win32/api/libloaderapi/nf-libloaderapi-loadlibraryexw)
5064
- [Dynamic-Link Library Search Order](/windows/win32/Dlls/dynamic-link-library-search-order)
65+
- [Dynamic-Link Library Security](/windows/win32/dlls/dynamic-link-library-security)
66+
67+
::: moniker-end

‎docs/porting/modifying-winver-and-win32-winnt.md‎

Lines changed: 46 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,23 +1,26 @@
11
---
22
title: "Update WINVER and _WIN32_WINNT"
3-
ms.date: "09/04/2017"
3+
description: "When and how to update WINVER and _WIN32_WINNT macros in upgraded Visual Studio C++ projects."
4+
ms.date: "01/22/2020"
45
helpviewer_keywords: ["WINVER in an upgraded Visual Studio C++ project", "_WIN32_WINNT in an upgraded Visual Studio C++ project"]
56
ms.assetid: 6a1f1d66-ae0e-48a7-81c3-524d8e8f3447
67
---
78
# Update WINVER and _WIN32_WINNT
89

9-
Visual C++ no longer supports targeting Windows 95, Windows 98, Windows ME, Windows NT or Windows 2000. If your **WINVER** or **_WIN32_WINNT** macros are assigned to one of these versions of Windows, you must modify the macros. When you upgrade a project that was created by using an earlier version of Visual C++, you may see compilation errors related to the **WINVER** or **_WIN32_WINNT** macros if they are assigned to a version of Windows that is no longer supported.
10+
When you use the Windows SDK, you can specify which versions of Windows your code can run on. The preprocessor macros **WINVER** and **_WIN32_WINNT** specify the minimum operating system version your code supports. Visual Studio and the Microsoft C++ compiler support targeting Windows 7 SP1 and later. Older toolsets include support for Windows XP SP4, Windows Server 2003 SP4, Vista, and Windows Server 2008. Windows 95, Windows 98, Windows ME, Windows NT, and Windows 2000 are unsupported.
11+
12+
When you upgrade an older project, you may need to update your **WINVER** or **_WIN32_WINNT** macros. If they're assigned values for an unsupported version of Windows, you may see compilation errors related to these macros.
1013

1114
## Remarks
1215

13-
To modify the macros, in a header file (for example, targetver.h which is included when you create a project that targets Windows), add the following lines.
16+
To modify the macros, in a header file (for example, in *targetver.h*, which is included by some project templates that target Windows), add the following lines.
1417

1518
```C
1619
#define WINVER 0x0A00
1720
#define _WIN32_WINNT 0x0A00
1821
```
1922
20-
This targets the Windows 10 operating system. These values are listed in the Windows header file SDKDDKVer.h, which also defines macros for each Windows version. You should add the #define statement before including SDKDDKVer.h. Here are the lines from the Windows 10 version of SDKDDKVer.h that encode the values for each version of Windows:
23+
The macros in the example are set to target every version of the Windows 10 operating system. The possible values are listed in the Windows header file *sdkddkver.h*, which defines macros for each major Windows version. To build your application to support a previous Windows platform, include *WinSDKVer.h*. Then, set the **WINVER** and **_WIN32_WINNT** macros to the oldest supported platform before including *sdkddkver.h*. Here are the lines from the Windows 10 SDK version of *sdkddkver.h* that encode the values for each major version of Windows:
2124
2225
```C
2326
//
@@ -38,7 +41,45 @@ This targets the Windows 10 operating system. These values are listed in the Win
3841
#define _WIN32_WINNT_WIN10 0x0A00 // Windows 10
3942
```
4043

41-
If you don't see all of these versions of Windows listed in a copy of SDKDDKVer.h that you're looking at, you probably are using an older version of the Windows SDK. By default, Win32 projects in Visual Studio 2017 use the Windows 10 SDK.
44+
For a more fine-grained approach to versioning, you can use the NTDDI version constants in *sdkddkver.h*. Here are some of the macros defined by *sdkddkver.h* in Windows 10 SDK version 10.0.18362.0:
45+
46+
```C
47+
//
48+
// NTDDI version constants
49+
//
50+
#define NTDDI_WIN7 0x06010000
51+
#define NTDDI_WIN8 0x06020000
52+
#define NTDDI_WINBLUE 0x06030000
53+
#define NTDDI_WINTHRESHOLD 0x0A000000 /* ABRACADABRA_THRESHOLD */
54+
#define NTDDI_WIN10 0x0A000000 /* ABRACADABRA_THRESHOLD */
55+
#define NTDDI_WIN10_TH2 0x0A000001 /* ABRACADABRA_WIN10_TH2 */
56+
#define NTDDI_WIN10_RS1 0x0A000002 /* ABRACADABRA_WIN10_RS1 */
57+
#define NTDDI_WIN10_RS2 0x0A000003 /* ABRACADABRA_WIN10_RS2 */
58+
#define NTDDI_WIN10_RS3 0x0A000004 /* ABRACADABRA_WIN10_RS3 */
59+
#define NTDDI_WIN10_RS4 0x0A000005 /* ABRACADABRA_WIN10_RS4 */
60+
#define NTDDI_WIN10_RS5 0x0A000006 /* ABRACADABRA_WIN10_RS5 */
61+
#define NTDDI_WIN10_19H1 0x0A000007 /* ABRACADABRA_WIN10_19H1*/
62+
63+
#define WDK_NTDDI_VERSION NTDDI_WIN10_19H1 /* ABRACADABRA_WIN10_19H1 */
64+
65+
//
66+
// masks for version macros
67+
//
68+
#define OSVERSION_MASK 0xFFFF0000
69+
#define SPVERSION_MASK 0x0000FF00
70+
#define SUBVERSION_MASK 0x000000FF
71+
72+
//
73+
// macros to extract various version fields from the NTDDI version
74+
//
75+
#define OSVER(Version) ((Version) & OSVERSION_MASK)
76+
#define SPVER(Version) (((Version) & SPVERSION_MASK) >> 8)
77+
#define SUBVER(Version) (((Version) & SUBVERSION_MASK) )
78+
```
79+
80+
The **OSVER**, **SPVER**, and **SUBVER** macros can be used in your code to control conditional compilation for different levels of API support.
81+
82+
You may not see all of these versions of Windows listed in the *sdkddkver.h* that you're looking at. That means you're probably using an older version of the Windows SDK. By default, new Windows projects in Visual Studio use the Windows 10 SDK.
4283
4384
> [!NOTE]
4485
> Values are not guaranteed to work if you include internal MFC headers in your application.

0 commit comments

Comments
 (0)