{"id":5593,"date":"2013-01-10T07:00:00","date_gmt":"2013-01-10T07:00:00","guid":{"rendered":"https:\/\/blogs.msdn.microsoft.com\/oldnewthing\/2013\/01\/10\/understanding-the-classical-model-for-linking-sometimes-you-dont-want-a-symbol-to-come-along-for-a-ride\/"},"modified":"2013-01-10T07:00:00","modified_gmt":"2013-01-10T07:00:00","slug":"understanding-the-classical-model-for-linking-sometimes-you-dont-want-a-symbol-to-come-along-for-a-ride","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/oldnewthing\/20130110-00\/?p=5593","title":{"rendered":"Understanding the classical model for linking: Sometimes you don’t want a symbol to come along for a ride"},"content":{"rendered":"

Continuing our study of\n\nthe classical model for linking<\/A>,\nlet’s take another look at the trick of\n\ntaking symbols along for the ride<\/A>.\n<\/P>\n

\nThe technique of taking symbols along for the ride is quite handy\nif that’s what you want,\nbut sometimes you don’t actually want it.\nFor example, a symbol taken along for the ride may create\nconflicts or create unwanted dependencies.\n<\/P>\n

\nHere’s an example:\nSuppose you have a library called stuff.lib<\/CODE>\nwhere you put functions that are\nused by various modules in different projects.\nOne of the files in your library might look like this:\n<\/P>\n

\n\/\/ filedatestuff.cpp<\/p>\n
BOOL GetFileCreationTimeW(\n        LPCWSTR pszFile,\n        FILETIME *pft)\n{\n    WIN32_FILE_ATTRIBUTE_DATA wfad;\n    BOOL fSuccess = GetFileAttributesExW(pszFile,\n                             GetFileExInfoStandard,\n                             &wfad);\n    if (fSuccess) {\n        *pft = wfad.ftCreationTime;\n    } else {\n        pft->dwLowDateTime = 0;\n        pft->dwHighDateTime = 0;\n    }\n    return fSuccess;\n}<\/p>\n
BOOL GetFileCreationTimeAsStringW(\n         LPCWSTR pszFile,\n         LPWSTR pszBuf,\n         UINT cchBuf)\n{\n    FILETIME ft;\n    BOOL fSuccess = GetFileCreationTimeW(pszFile, &ft);\n    if (fSuccess) {\n        fSuccess = SHFormatDateTimeW(&ft, NULL,\n                                     pszBuf, cchBuf) > 0;\n    }\n    return fSuccess;\n}\n<\/PRE>\n
\nThings are working out great,\npeople like the helper functions in your library,\nand then you get a bug report:\n<\/P>\n
\nWhen my program calls the\nGet­File­Creation­TimeW<\/CODE>\nfunction,\nI get a linker error:\nunresolved external: __imp__SHFormat­Date­TimeW<\/TT>.\nIf I remove my call to \nGet­File­Creation­TimeW<\/CODE>,\nthen my program builds fine.\n<\/BLOCKQUOTE>\n
\nYou scratch your head.\n“The program is calling\nGet­File­Creation­TimeW<\/CODE>,\nbut that function doesn’t call\nSHFormat­Date­TimeW<\/CODE>,\nso why are we getting an unresolved external error?\nAny why hasn’t anybody else run into this problem before?”\n<\/P>\n
\nFirst question first.\nWhy are we getting an unresolved external error\nfor a nonexistent external dependency?\n<\/P>\n
\nBecause the\nGet­File­Creation­Time­As­StringW<\/CODE>\nfunction got taken along for the ride<\/I>.\nWhen the customer’s program called\nGet­File­Creation­TimeW<\/CODE>,\nthat pulled in the filedatestuff.obj<\/CODE> file,\nand that OBJ file contains both\nGet­File­Creation­TimeW<\/CODE>\nand<\/I>\nGet­File­Creation­Time­As­StringW<\/CODE>.\nSince they are in the same OBJ file,\npulling in one function pulls in all of them.\n<\/P>\n
\nThe fix is to split the filedatastuff.cpp<\/CODE> file\ninto two files,\none for each function.\nThat way, when you pull in one function,\nnobody else comes along for the ride.\n<\/P>\n
\nNow to the second half of the question:\nWhy did nobody run into this problem before?\n<\/P>\n
\nThe\nGet­File­Creation­TimeW<\/CODE>\nfunction has a dependency on\nGet­File­Attributes­ExW<\/CODE>,\nwhich is a function in KERNEL32.DLL<\/CODE>.\nOn the other hand, the\nGet­File­Creation­Time­As­StringW<\/CODE>\nfunction has a dependency on\nSHFormat­Date­TimeW<\/CODE>,\nwhich is a function in\nSHLWAPI.DLL<\/CODE>.\nIf somebody lists\nKERNEL32.LIB<\/CODE> as a dependent library\nin their project,\nbut they don’t include\nSHLWAPI.LIB<\/CODE> on that list,\nthen they will encounter this problem\nbecause the linker will pull in the reference to\nSHFormat­Date­TimeW<\/CODE>\nand have no way of resolving it.\n<\/P>\n
\nNobody ran into this before because SHLWAPI.LIB<\/CODE>\nhas lots of cute little functions in it,\nso most people include it in their project.\nOnly if somebody is being frugal and leaving\nSHLWAPI.LIB<\/CODE> out of their project\nwill they run into this problem.\n<\/P>\n
\nBonus chatter<\/B>:\nThe suggestion to split the file into two will work,\nbut if you are really clever, you can still do some consolidation.\nInstead of splitting up files by functional group\n(for example, “all FILETIME<\/CODE> functions”),\nyou need to split them up based on their dependencies\n(“functions that are dependent solely on SHLWAPI.LIB<\/CODE>“).\nOf course, this type of organization may make the code harder\nto follow (“Why did you put\nGet­File­Creation­Time­As­StringW<\/CODE>\nand\nHash­String<\/CODE>\nin the same file?”),\nso you have to balance this against maintainability and\nreadability.\nFor example, somebody who is not aware of the classical\nmodel for linking may add a function to the file that has\na dependency on SHELL32.DLL<\/CODE>,\nand now your careful separation has fallen apart.\n<\/P><\/p>\n","protected":false},"excerpt":{"rendered":"
Continuing our study of the classical model for linking, let’s take another look at the trick of taking symbols along for the ride. The technique of taking symbols along for the ride is quite handy if that’s what you want, but sometimes you don’t actually want it. For example, a symbol taken along for the […]<\/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-5593","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-oldnewthing","tag-code","tag-linker"],"acf":[],"blog_post_summary":"
Continuing our study of the classical model for linking, let’s take another look at the trick of taking symbols along for the ride. The technique of taking symbols along for the ride is quite handy if that’s what you want, but sometimes you don’t actually want it. For example, a symbol taken along for the […]<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/posts\/5593","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=5593"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/posts\/5593\/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=5593"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/categories?post=5593"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/tags?post=5593"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}