{"id":104024,"date":"2020-07-31T07:00:00","date_gmt":"2020-07-31T14:00:00","guid":{"rendered":"https:\/\/devblogs.microsoft.com\/oldnewthing\/?p=104024"},"modified":"2021-02-13T07:36:47","modified_gmt":"2021-02-13T15:36:47","slug":"20200731-00","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/oldnewthing\/20200731-00\/?p=104024","title":{"rendered":"What does the \/ALTERNATENAME linker switch do?"},"content":{"rendered":"

There’s an undocumented switch for the Microsoft Visual Studio linker known as \/ALTERNATENAME<\/code>. Despite being undocumented, people use it a lot. So what is it?<\/p>\n

This is effectively a command line switch version of the OLDNAMES.LIB<\/code> library<\/a>. When you say \/ALTERNATENAME:X=Y<\/code>, then this tells the linker that if it is looking for a symbol named X<\/code> and can’t find it, then before giving up, it should redirect it to the symbol Y<\/code> and try again.<\/p>\n

The C runtime library uses this mechanism for various sneaky purposes. For example, there’s a part that goes<\/p>\n

BOOL (WINAPI * const _pDefaultRawDllMain)(HANDLE, DWORD, LPVOID) = NULL;\r\n#if defined (_M_IX86)   \r\n#pragma comment(linker, \"\/alternatename:__pRawDllMain=__pDefaultRawDllMain\")   \r\n#elif defined (_M_IA64<\/a>) || defined (_M_AMD64)   \r\n#pragma comment(linker, \"\/alternatename:_pRawDllMain=_pDefaultRawDllMain\")   \r\n#else  \/* defined (_M_IA64) || defined (_M_AMD64) *\/   \r\n#error Unsupported platform   \r\n#endif  \/* defined (_M_IA64) || defined (_M_AMD64) *\/  \r\n<\/pre>\n
What this does is say, “If you need a symbol called _pRawDllMain<\/code>, but you can’t find it, then try again with _pDefaultRawDllMain<\/code>.” If an object file defines _pRawDllMain<\/code>, then that definition will be used. Otherwise _pDefaultRawDllMain<\/code> will be used.<\/p>\n
Note that \/ALTERNATENAME<\/code> is a linker feature and consequently operates on decorated names, since the linker doesn’t understand compiler-specific name-decoration algorithms. This means that you typically have to use different versions of the \/ALTERNATENAME<\/code> switch, depending on what architecture you are targeting. In the above example, the C runtime library knows that __cdecl<\/code> decoration prepends an underscore on x86, but not on any other platform.<\/p>\n
This use of \/ALTERNATENAME<\/code> here is a way for the compiler to generate hooks into the DLL startup process based on the code being compiled. If there is no _pRawDllMain<\/code> defined by an object file, then _pDefaultRawDllMain<\/code> will be used instead, and that version is just a null pointer, which means, “Don’t do anything special.”<\/p>\n
This pattern of using the \/ALTERNATENAME<\/code> switch lets you provide a default value for a function or variable, which others can override if they choose. For example, you might do something like this:<\/p>\n
void default_error_log() { \/* do nothing *\/ }\r\n\/\/ For expository simplification: assume x86 cdecl\r\n#pragma comment(linker, \"\/alternatename:_error_log=_default_error_log\")   \r\n<\/pre>\n
If nobody defines a custom error_log<\/code> function, then all references to error_log<\/code> are redirected to default_error_log<\/code>, and the default error log function does nothing.\u00b9<\/p>\n
The C++\/WinRT library uses \/ALTERNATENAME<\/code> for a different purpose. The C++\/WinRT library wants to support being used both with and without windows.h<\/code>, so it contains its own declarations for the Windows functions and structures that it needs.<\/p>\n
But now there’s a problem: If it is used with<\/i> windows.h<\/code>, then there are structure definition errors. Therefore, C++\/WinRT needs to give its equivalent declarations of Windows structures some other name, to avoid redefinition errors.<\/p>\n
But this in turn means that the function prototypes in the C++\/WinRT library need to use the renamed structures, rather than the original Windows structures, in case the C++\/WinRT library is used without<\/i> windows.h<\/code>. This declaration will in turn create a conflict if the C++\/WinRT library is used with<\/i> windows.h<\/code> when the real declarations are encountered in windows.h<\/code>.<\/p>\n
The solution is to rename the C++\/WinRT version of Windows functions, too. C++\/WinRT gives them a WINRT_IMPL_<\/code> prefix, so that there is no function declaration collision.<\/p>\n
We now have two parallel universes. There’s the windows.h<\/code> universe, and the C++\/WinRT universe, each with their own structures and functions. The two parallel universes are unified by the \/ALTERNATENAME<\/code> directive, which tells the linker, “If you find yourself looking for the function WINRT_IMPL_GetLastError<\/code>, try again with GetLastError<\/code>.” Since nobody defines WINRT_IMPL_GetLastError<\/code>, the “try again” kicks in, and all of the calls to WINRT_GetLastError<\/code> end up redirected to the operating system GetLastError<\/code> function, which is what we wanted in the first place.<\/p>\n
\u00b9 The more traditional way of doing this (that doesn’t rely on undocumented vendor-specific linker features) is to take advantage of  the classical model for linking<\/a>, specifically the part where you can let  an OBJ override a LIB<\/a>: What you do is define _pRawDllMain<\/code> in a separate OBJ file that defines nothing except that one variable, and put that OBJ in the C runtime LIB. If the module provides its own definition of _pRawDllMain<\/code> in an OBJ file, then that definition is used. Otherwise, the linker will search through the LIBs, and eventually it will find the one in the C runtime LIB and use that one.<\/p>\n
So why does \/ALTERNATENAME<\/code> exist if you could already get this effect via LIBs, and in way that all linkers support, not just the Microsoft C linker?<\/p>\n
C++\/WinRT is a header-only library. It has no LIB in which to put these default definitions. It therefore has to use the “command line switch version of a LIB”.<\/p>\n","protected":false},"excerpt":{"rendered":"
In case of emergency, go look for something else.<\/p>\n","protected":false},"author":1069,"featured_media":111744,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[1],"tags":[25,131],"class_list":["post-104024","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-oldnewthing","tag-code","tag-linker"],"acf":[],"blog_post_summary":"
In case of emergency, go look for something else.<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/posts\/104024","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/users\/1069"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/comments?post=104024"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/posts\/104024\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/media\/111744"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/media?parent=104024"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/categories?post=104024"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/tags?post=104024"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}