7 Nokia Corporation - initial contribution. |
7 Nokia Corporation - initial contribution. |
8 Contributors: |
8 Contributors: |
9 --> |
9 --> |
10 <!DOCTYPE concept |
10 <!DOCTYPE concept |
11 PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> |
11 PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> |
12 <concept xml:lang="en" id="GUID-D8837969-74D0-5E17-AD42-3F10DD1FD5BF"><title>Loader Search Rules</title><prolog><metadata><keywords/></metadata></prolog><conbody><p>A summary of the rules that the loader follows to search for EXEs and DLLs. </p> <ul><li id="GUID-D6BAD23C-005E-58E4-8418-16FFBE8AC052"><p> <xref href="GUID-D8837969-74D0-5E17-AD42-3F10DD1FD5BF.dita#GUID-D8837969-74D0-5E17-AD42-3F10DD1FD5BF/GUID-D9984B1D-8C7E-55B5-86AC-E90E244BDFB3">Search rules for an EXE</xref> </p> </li> <li id="GUID-373C451E-17C1-576C-8D00-6F15174CCD9D"><p> <xref href="GUID-D8837969-74D0-5E17-AD42-3F10DD1FD5BF.dita#GUID-D8837969-74D0-5E17-AD42-3F10DD1FD5BF/GUID-E026ABAD-D76E-51EF-886F-28F8E00185E5">Search rules for a DLL in the import table of an EXE or another DLL</xref> </p> </li> <li id="GUID-5FD789FB-95A3-51DF-9AD4-FD7474ED9088"><p> <xref href="GUID-D8837969-74D0-5E17-AD42-3F10DD1FD5BF.dita#GUID-D8837969-74D0-5E17-AD42-3F10DD1FD5BF/GUID-FA4768B2-A741-5601-990C-46B51DA77803">Search rules for a DLL loaded from a program</xref> </p> </li> </ul> <section id="GUID-D9984B1D-8C7E-55B5-86AC-E90E244BDFB3"><title>Search rules for an EXE</title> <p>To start a new process, call <xref href="GUID-9DD1EA2B-DC59-315C-8E9C-CE6D9461B695.dita#GUID-9DD1EA2B-DC59-315C-8E9C-CE6D9461B695/GUID-DD214BA3-907E-3C7F-93C6-924A9A115A02"><apiname>RProcess::Create()</apiname></xref>. </p> <p> <codeph>RProcess::Create()</codeph> loads the EXE specified in the input parameters. The function then looks through the import table of the EXE to get a list of DLLs that the EXE references. The loader uses the list of DLLs in the import table to load the DLLs. If DLLs reference other DLLS, the loader uses the same method to load those DLLs. See <xref href="GUID-D8837969-74D0-5E17-AD42-3F10DD1FD5BF.dita#GUID-D8837969-74D0-5E17-AD42-3F10DD1FD5BF/GUID-E026ABAD-D76E-51EF-886F-28F8E00185E5">Search rules for a DLL listed in the import table of an EXE</xref>. </p> <p>The result of a search for an EXE depends on: </p> <ul><li id="GUID-DC1D5577-2D85-5B9F-B4F4-B10F4208CA46"><p>the name of the EXE. You provide this information. </p> </li> <li id="GUID-7BBF1688-8013-5C4D-8C60-09CA0E22D6B5"><p>the UID type : you provide. This is optional </p> </li> <li id="GUID-351742AD-AAE3-5050-AF93-DA990309FF37"><p>the version of the EXEs on the device </p> </li> </ul> <p>You pass the name of the EXE in the first parameter of <codeph>RProcess::Create()</codeph>. You have a number of choices: </p> <ul><li id="GUID-30C6FEB3-DED9-5BAF-AF3F-700FA8EE58D0"><p>you can specify the file name only. The loader will assume a <filepath>.exe</filepath> file extension. For example: </p> <p> <filepath>efile</filepath> </p> </li> <li id="GUID-94CD2AC1-5FC5-52D8-893B-E6232522F494"><p>you can specify a filename and an extension. For example: </p> <p> <filepath>efile.exe</filepath> </p> </li> <li id="GUID-06F6A1CF-FD26-5402-983F-E32D2D1F8B90"><p>you can put a path in front of the file name. A path has limited use, because the loader can load EXEs only from the directory <filepath>\sys\bin</filepath>, or from subdirectories of <filepath>\sys\bin</filepath>. </p> </li> </ul> <p><b>The search procedure</b> </p> <p>The loader searches for EXEs with the given name and extension. More than one EXE with the given name and extension can exist on a device. </p> <ol id="GUID-16CF313D-BAB9-58BB-AB38-ED59BDF572D4"><li id="GUID-DE4AD994-9C84-5113-B2C7-9030DC08C22E"><p>If you do not provide a path, the loader searches the <filepath>\sys\bin</filepath> directory on all drives. The loader searches drives in the order <filepath>Y:</filepath>, <filepath>X:</filepath> ... <filepath> B:</filepath>, <filepath>A:</filepath>. The <filepath>Z:</filepath> drive is searched last. Subdirectories of <filepath>\sys\bin</filepath> are not searched. </p> <p>If you provide a path, there are only three useful cases: </p> <ul><li id="GUID-3D83CC05-0B68-5CA7-AB52-01A7858E2383"><p>to limit the search to a specific drive. For example: </p> <p> <filepath>X:\sys\bin</filepath> </p> <p>where <filepath>X:</filepath> can be one of the drives <filepath>A:</filepath> to <filepath>Z:</filepath>. </p> </li> <li id="GUID-821A186F-9DA4-51E6-9CAD-E833D9DEDF3F"><p>to limit the search to a subdirectory of <filepath>\sys\bin</filepath> on a specific drive. For example: </p> <p> <filepath>X:\sys\bin\aaa\bbb</filepath> </p> <p>The use of subdirectories in <filepath>\sys\bin</filepath> is not common. </p> <p>where <filepath>X</filepath>: can be one of the drives <filepath>A:</filepath> to <filepath>Z:</filepath>. </p> </li> <li id="GUID-63815160-C411-5BEB-AC8F-7224F33883BE"><p>to limit the search to a subdirectory of <filepath>\sys\bin</filepath> on all drives. For example: </p> <p> <filepath>\sys\bin\aaa\bbb</filepath> </p> <p>The loader searches all drives in the order <filepath>Y:</filepath>, <filepath>X:</filepath> ... <filepath> B:</filepath>, <filepath>A:</filepath>. The <filepath>Z:</filepath> drive is searched last. </p> <p>The use of subdirectories in <filepath>\sys\bin</filepath> is not common. </p> </li> </ul> <p>The loader cannot load EXEs from other directories, because system security prevents it. </p> </li> <li id="GUID-1AFA13C7-24B4-5598-94CA-448D05449BBA"><p>The loader compares the UID type (<xref href="GUID-B6D6B0AD-B15C-339A-8540-40540885089A.dita"><apiname>TUidType</apiname></xref>) of each EXE in the list with the UID type you specify in <xref href="GUID-9DD1EA2B-DC59-315C-8E9C-CE6D9461B695.dita#GUID-9DD1EA2B-DC59-315C-8E9C-CE6D9461B695/GUID-DD214BA3-907E-3C7F-93C6-924A9A115A02"><apiname>RProcess::Create()</apiname></xref>. The UID type is a set of three UIDs. Each UID in the UID type that you specify must match the same UID in the UID type of the EXE. If you specify <xref href="GUID-707A476C-1790-34DB-B1E5-5435578E01AA.dita"><apiname>KNullUid</apiname></xref> for any of the three UIDs in your UID type, a match is automatic. </p> </li> <li id="GUID-7F8E3D49-F2CB-5445-ACCC-F7967B4C745F"><p>If the search has found no EXEs, the load fails. </p> </li> <li id="GUID-1469E256-98FF-51B8-9936-78ED389EDCBE"><p>If the search has found one EXE only, the loader loads that EXE. </p> </li> <li id="GUID-90B5C4A5-A0E9-5ADD-B76A-3491C322C4B1"><p>If more than one EXE has been found, the loader loads the EXE with the highest version. A version <codeph>N.n</codeph> is higher than version <codeph>M.m</codeph> if <codeph>(N>M or (N==M and n>m))</codeph>. </p> </li> <li id="GUID-A4761946-0490-5887-9686-184B6BED556C"><p>If all EXEs have the same version, the loader loads the version found first. </p> </li> </ol> </section> <section id="GUID-E026ABAD-D76E-51EF-886F-28F8E00185E5"><title>Search rules for a DLL in the import table of an EXE or another DLL</title> <p>After the loader has selected the EXE, the loader loads all DLLs in the import table. This is also called static linkage. </p> <p>The import table contains the name and extension of each DLL. The import table also contains the version of each DLL and the 3rd UID that identifies each DLL. The version information is stored in the import table when the executable file is built. All DLLs have an ordered set of three UIDs. The third UID gives a unique identity to the DLL. See <xref href="GUID-C135B8D8-DA5A-5852-9C2D-18622404FE99.dita">UID protection</xref>. </p> <p><b>The search procedure</b> </p> <p>The search uses the following procedure for each DLL: </p> <ol id="GUID-FF01C553-8546-5A2C-B34B-8F85014631D6"><li id="GUID-42FD9744-4B2C-55D6-A7B0-73DE248861DE"><p>The loader searches the <filepath>\sys\bin</filepath> directory on all drives for all DLLs that have the filename and extension. The loader searches drives in the order <filepath>Y:</filepath>, <filepath>X:</filepath> ... <filepath> B:</filepath>, <filepath>A:</filepath>. The <filepath>Z:</filepath> drive is searched last. Subdirectories of <filepath>\sys\bin</filepath> are not searched. The loader searches for all versions of the DLL. If the loader finds the same version of a DLL on more than one drive, the loader only adds the first one to the set of possible DLLs. For example, if version 2.1 of a DLL is on drive <filepath>D:</filepath> and on drive <filepath>Z:</filepath>, only the version on drive <filepath>D:</filepath> is added to the set of possible DLLs. </p> <p>The loader cannot load DLLs from other directories, because system security prevents it. </p> <p>[Before December 2007, the loader had different behaviour. The loader searched the drive from which the EXE was loaded before the loader checked the other drives. For example, if the EXE was loaded from drive <filepath>Z:</filepath>, and version 2.1 of a DLL was on drive <filepath>D:</filepath> and drive <filepath>Z:</filepath>, the loader selected the version of the DLL that was on drive <filepath>Z:</filepath>.] </p> </li> <li id="GUID-BC036626-7461-5C4E-A710-09D693CE5A1E"><p>The loader then selects those DLLs that have the same 3rd UID from the set of possible DLLs. This operation can decrease the set of possible DLLs. If there are no DLLs in the set, the load fails. </p> </li> <li id="GUID-9AE6A749-4C72-557F-AB3A-5E33E246A8AE"><p>The loader then selects those DLLs that have platform security capabilities that match or exceed those of the EXE. This selection operation can decrease the set of possible DLLs. If there are no DLLs in the set the load fails. </p> <p>See also : <xref href="GUID-4BFEDD79-9502-526A-BA7B-97550A6F0601.dita">Platform security</xref>. </p> </li> <li id="GUID-7F083400-E8FB-52E0-A8CD-D96DDB093F39"><p>Each DLL in the import table of the EXE has a version number. This number is the version of the DLL to which the EXE is linked. The loader uses the version number in the import table to select the correct version of the DLL. The following flowchart shows how the loader selects the DLL from the set of possible DLLs. </p> <fig id="GUID-1F388A1E-BBB8-5481-8197-1F3C87BB2948"><image href="GUID-9D2752D1-4153-5978-A7B8-4C3F860B6B87_d0e356558_href.png" placement="inline"/></fig> </li> <li id="GUID-56B0AF9F-4D39-517B-A3A5-779B7D892CEF"><p>If there are no DLLs that meet the requirements, the load fails. </p> </li> </ol> </section> <section id="GUID-FA4768B2-A741-5601-990C-46B51DA77803"><title>Search rules for a DLL loaded from a program</title> <p>To load a DLL from a program, call <xref href="GUID-25327159-83D6-3507-B187-09EA4BB3727F.dita#GUID-25327159-83D6-3507-B187-09EA4BB3727F/GUID-4F1B2717-D34F-32A4-B6E6-03D0533186A3"><apiname>RLibrary::Load()</apiname></xref>. This is known as dynamic linking. </p> <p> <codeph>RLibrary::Load()</codeph> loads the DLL specified in the input parameters. The function then uses the import table to get a list of referred DLLs. The loader loads the DLLs in the list and uses the same search method that the loader uses for EXEs. See <xref href="GUID-D8837969-74D0-5E17-AD42-3F10DD1FD5BF.dita#GUID-D8837969-74D0-5E17-AD42-3F10DD1FD5BF/GUID-E026ABAD-D76E-51EF-886F-28F8E00185E5">Search rules for a DLL in the import table of an EXE</xref>. </p> <p>The result of a search for an DLL depends on: </p> <ul><li id="GUID-CBC9178F-D0CD-5558-9AA0-338F7CB52479"><p>the name of the DLL. You provide this information. </p> </li> <li id="GUID-E735C0C9-CFCE-5A37-8E41-313039AAD44B"><p>the UID type : you provide. This is optional. </p> </li> <li id="GUID-14168E41-7825-5546-BD2C-02BB107D2D3C"><p>the required version : you provide. This is optional. </p> </li> <li id="GUID-03ED4A5A-813A-5332-BCA5-8735793A4370"><p>the version of the DLLs on the device. </p> </li> </ul> <p>You pass the name of the DLL in the first parameter of <codeph>RLibrary::Load()</codeph>. You have a number of choices: </p> <ul><li id="GUID-D5C6F45B-0BCF-58E5-993A-999F96F24354"><p>you can specify the file name only. The loader will assume a <filepath>.dll</filepath> file extension. For example: </p> <p> <filepath>efsrv</filepath> </p> </li> <li id="GUID-63E96237-0DA1-502E-9C39-4562A31BF616"><p>you can specify a filename and an extension. For example: </p> <p> <filepath>efsrv.dll</filepath> </p> </li> <li id="GUID-B1FC4B22-267B-5B6B-8ADC-62C7012C7925"><p>you can put a path in front of the file name. A path has limited use, because the loader can load DLLs only from the directory <filepath>\sys\bin</filepath>, or from subdirectories of <filepath>\sys\bin</filepath>. </p> </li> </ul> <p>See <xref href="GUID-4A56B285-790E-5171-88F3-8C40B2AA9699.dita">Dynamically loading link libraries</xref> and <xref href="GUID-9E92EE30-F2E2-5F28-BB2A-391C09EC69D2.dita">Using ECom</xref>. </p> <p><b>The search procedure</b> </p> <p>The loader searches for DLLs with the given name and extension. More than one DLL with the given name and extension can exist on a device. </p> <ol id="GUID-5AA22DFB-F4D1-5358-96DE-D6B43BCB905E"><li id="GUID-60421212-8123-54A2-9A77-71C39E7EB4B6"><p>If you do not provide a path, the loader searches the <filepath>\sys\bin</filepath> directory on all drives. The loader searches drives in the order <filepath>Y:</filepath>, <filepath>X:</filepath> ... <filepath> B:</filepath>, <filepath>A:</filepath>. The <filepath>Z:</filepath> drive is searched last. Subdirectories of <filepath>\sys\bin</filepath> are not searched. </p> <p>If you provide a path, there are only three useful cases: </p> <ul><li id="GUID-693CCFBB-E1A7-50BD-AC89-95F73E0A569D"><p>to limit the search to a specific drive. For example: </p> <p> <filepath>X:\sys\bin</filepath> </p> <p>where <filepath>X:</filepath> can be one of the drives <filepath>A:</filepath> to <filepath>Z:</filepath>. </p> </li> <li id="GUID-F1B66565-1FC3-571D-9CD2-84AE8013F48E"><p>to limit the search to a subdirectory of <filepath>\sys\bin</filepath> on a specific drive. For example: </p> <p> <filepath>X:\sys\bin\aaa\bb</filepath> </p> <p>The use of subdirectories in <filepath>\sys\bin</filepath> is not common. </p> <p>where <filepath>X:</filepath> can be one of the drives <filepath>A:</filepath> to <filepath>Z:</filepath>. </p> </li> <li id="GUID-AADB293F-8945-5875-B3C2-9B77F938EDEF"><p>to limit the search to a subdirectory of <filepath>\sys\bin</filepath> on all drives. For example: </p> <p> <filepath>\sys\bin\aaa\bbb</filepath> </p> <p>The loader searches all drives in the order <filepath>Y:</filepath>, <filepath>X:</filepath> ... <filepath> B:</filepath>, <filepath>A:</filepath>. The <filepath>Z:</filepath> drive is searched last. </p> <p>The use of subdirectories in <filepath>\sys\bin</filepath> is not common. </p> </li> </ul> <p>System security prevents the loader from loading DLLs from any other directories. </p> </li> <li id="GUID-F0DD2783-C346-5F30-8691-7BC3F13D8F76"><p>The loader compares the UID type (<xref href="GUID-B6D6B0AD-B15C-339A-8540-40540885089A.dita"><apiname>TUidType</apiname></xref>) of each DLL in the list with the UID type you specify in <xref href="GUID-25327159-83D6-3507-B187-09EA4BB3727F.dita#GUID-25327159-83D6-3507-B187-09EA4BB3727F/GUID-4F1B2717-D34F-32A4-B6E6-03D0533186A3"><apiname>RLibrary::Load()</apiname></xref>. The UID type is a set of three UIDs. Each UID in the UID type that you specify must match the same UID in the UID type of the DLL. If you specify <xref href="GUID-707A476C-1790-34DB-B1E5-5435578E01AA.dita"><apiname>KNullUid</apiname></xref> for any of the three UIDs in your UID type, there is a match. </p> </li> <li id="GUID-F86E7050-500E-5C21-AA70-98DC95E8BB73"><p>If the search has found no DLLs, the load fails. </p> </li> <li id="GUID-27848CFE-3B37-5350-83B1-48A2B1E83705"><p>The loader then selects those DLLs that have platform security capabilities that match or exceed those of the process . This selection operation can decrease the set of possible DLLs. If there are no DLLs in the set the load fails. </p> </li> <li id="GUID-0A421D77-7BE4-5C9F-AB93-F6F0E06342A3"><p>If the search has found no DLLs, the load fails. </p> </li> <li id="GUID-A34E59F9-FAD4-54DB-86A6-C2A428710FB8"><p>If you specify a version number in <xref href="GUID-25327159-83D6-3507-B187-09EA4BB3727F.dita#GUID-25327159-83D6-3507-B187-09EA4BB3727F/GUID-4F1B2717-D34F-32A4-B6E6-03D0533186A3"><apiname>RLibrary::Load()</apiname></xref>, the loader selects a version of the DLL from the set. The following flowchart shows how the loader selects the DLL from the set of possible DLLs. </p> <fig id="GUID-9412E498-19E5-5D58-B913-DD55BBB79D4D"><image href="GUID-91224821-8094-59ED-A100-4174193A25EE_d0e356843_href.png" placement="inline"/></fig> </li> <li id="GUID-61AE1C0C-A698-5BEC-A5DA-E28CB5D807A3"><p>If there are no DLLs that meet the requirements, the load fails. </p> </li> <li id="GUID-D8791217-B11C-548A-9756-10476E843A51"><p>If you do not specify a version number in <xref href="GUID-25327159-83D6-3507-B187-09EA4BB3727F.dita#GUID-25327159-83D6-3507-B187-09EA4BB3727F/GUID-4F1B2717-D34F-32A4-B6E6-03D0533186A3"><apiname>RLibrary::Load()</apiname></xref>, the loader loads the DLL with the highest version. A version <codeph>N.n</codeph> is higher than version <codeph>M.m</codeph>, if <codeph>(N>M or (N==M and n>m))</codeph>. </p> </li> <li id="GUID-D43C380A-C315-5C7B-8508-0720EB1E1EEE"><p>If all DLLs have the same version, the loader loads the DLL found first. </p> </li> </ol> </section> </conbody></concept> |
12 <concept id="GUID-D8837969-74D0-5E17-AD42-3F10DD1FD5BF" xml:lang="en"><title>Loader |
|
13 Search Rules</title><shortdesc>This topic provides a summary of the rules that the loader follows |
|
14 to search for EXEs and DLLs.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
15 <ul> |
|
16 <li id="GUID-D6BAD23C-005E-58E4-8418-16FFBE8AC052"><p> <xref href="GUID-D8837969-74D0-5E17-AD42-3F10DD1FD5BF.dita#GUID-D8837969-74D0-5E17-AD42-3F10DD1FD5BF/GUID-D9984B1D-8C7E-55B5-86AC-E90E244BDFB3">Search rules for an EXE</xref> </p> </li> |
|
17 <li id="GUID-373C451E-17C1-576C-8D00-6F15174CCD9D"><p> <xref href="GUID-D8837969-74D0-5E17-AD42-3F10DD1FD5BF.dita#GUID-D8837969-74D0-5E17-AD42-3F10DD1FD5BF/GUID-E026ABAD-D76E-51EF-886F-28F8E00185E5">Search rules for a DLL in the import table of an EXE or another DLL</xref> </p> </li> |
|
18 <li id="GUID-5FD789FB-95A3-51DF-9AD4-FD7474ED9088"><p> <xref href="GUID-D8837969-74D0-5E17-AD42-3F10DD1FD5BF.dita#GUID-D8837969-74D0-5E17-AD42-3F10DD1FD5BF/GUID-FA4768B2-A741-5601-990C-46B51DA77803">Search rules for a DLL loaded from a program</xref> </p> </li> |
|
19 </ul> |
|
20 <section id="GUID-D9984B1D-8C7E-55B5-86AC-E90E244BDFB3"><title>Search rules |
|
21 for an EXE</title> <p>To start a new process, call <xref href="GUID-9DD1EA2B-DC59-315C-8E9C-CE6D9461B695.dita#GUID-9DD1EA2B-DC59-315C-8E9C-CE6D9461B695/GUID-DD214BA3-907E-3C7F-93C6-924A9A115A02"><apiname>RProcess::Create()</apiname></xref>. </p> <p> <codeph>RProcess::Create()</codeph> loads |
|
22 the EXE specified in the input parameters. The function then looks through |
|
23 the import table of the EXE to get a list of DLLs that the EXE references. |
|
24 The loader uses the list of DLLs in the import table to load the DLLs. If |
|
25 DLLs reference other DLLS, the loader uses the same method to load those DLLs. |
|
26 See <xref href="GUID-D8837969-74D0-5E17-AD42-3F10DD1FD5BF.dita#GUID-D8837969-74D0-5E17-AD42-3F10DD1FD5BF/GUID-E026ABAD-D76E-51EF-886F-28F8E00185E5">Search |
|
27 rules for a DLL listed in the import table of an EXE</xref>. </p> <p>The result |
|
28 of a search for an EXE depends on: </p> <ul> |
|
29 <li id="GUID-DC1D5577-2D85-5B9F-B4F4-B10F4208CA46"><p>the name of the EXE. |
|
30 You provide this information. </p> </li> |
|
31 <li id="GUID-7BBF1688-8013-5C4D-8C60-09CA0E22D6B5"><p>the UID type : you provide. |
|
32 This is optional </p> </li> |
|
33 <li id="GUID-351742AD-AAE3-5050-AF93-DA990309FF37"><p>the version of the EXEs |
|
34 on the device </p> </li> |
|
35 </ul> <p>You pass the name of the EXE in the first parameter of <codeph>RProcess::Create()</codeph>. |
|
36 You have a number of choices: </p> <ul> |
|
37 <li id="GUID-30C6FEB3-DED9-5BAF-AF3F-700FA8EE58D0"><p>you can specify the |
|
38 file name only. The loader will assume a <filepath>.exe</filepath> file extension. |
|
39 For example: </p> <p> <filepath>efile</filepath> </p> </li> |
|
40 <li id="GUID-94CD2AC1-5FC5-52D8-893B-E6232522F494"><p>you can specify a filename |
|
41 and an extension. For example: </p> <p> <filepath>efile.exe</filepath> </p> </li> |
|
42 <li id="GUID-06F6A1CF-FD26-5402-983F-E32D2D1F8B90"><p>you can put a path in |
|
43 front of the file name. A path has limited use, because the loader can load |
|
44 EXEs only from the directory <filepath>\sys\bin</filepath>, or from subdirectories |
|
45 of <filepath>\sys\bin</filepath>. </p> </li> |
|
46 </ul> <p><b>The |
|
47 search procedure</b> </p> <p>The loader searches for EXEs with the given name |
|
48 and extension. More than one EXE with the given name and extension can exist |
|
49 on a device. </p> <ol id="GUID-16CF313D-BAB9-58BB-AB38-ED59BDF572D4"> |
|
50 <li id="GUID-DE4AD994-9C84-5113-B2C7-9030DC08C22E"><p>If you do not provide |
|
51 a path, the loader searches the <filepath>\sys\bin</filepath> directory on |
|
52 all drives. The loader searches drives in the order <filepath>Y:</filepath>, <filepath>X:</filepath> ... <filepath> B:</filepath>, <filepath>A:</filepath>. The <filepath>Z:</filepath> drive is searched last. Subdirectories of <filepath>\sys\bin</filepath> are |
|
53 not searched. </p> <p>If you provide a path, there are only three useful cases: </p> <ul> |
|
54 <li id="GUID-3D83CC05-0B68-5CA7-AB52-01A7858E2383"><p>to limit the search |
|
55 to a specific drive. For example: </p> <p> <filepath>X:\sys\bin</filepath> </p> <p>where <filepath>X:</filepath> can |
|
56 be one of the drives <filepath>A:</filepath> to <filepath>Z:</filepath>. </p> </li> |
|
57 <li id="GUID-821A186F-9DA4-51E6-9CAD-E833D9DEDF3F"><p>to limit the search |
|
58 to a subdirectory of <filepath>\sys\bin</filepath> on a specific drive. For |
|
59 example: </p> <p> <filepath>X:\sys\bin\aaa\bbb</filepath> </p> <p>The use |
|
60 of subdirectories in <filepath>\sys\bin</filepath> is not common. </p> <p>where <filepath>X</filepath>: |
|
61 can be one of the drives <filepath>A:</filepath> to <filepath>Z:</filepath>. </p> </li> |
|
62 <li id="GUID-63815160-C411-5BEB-AC8F-7224F33883BE"><p>to limit the search |
|
63 to a subdirectory of <filepath>\sys\bin</filepath> on all drives. For example: </p> <p> <filepath>\sys\bin\aaa\bbb</filepath> </p> <p>The |
|
64 loader searches all drives in the order <filepath>Y:</filepath>, <filepath>X:</filepath> ... <filepath> B:</filepath>, <filepath>A:</filepath>. |
|
65 The <filepath>Z:</filepath> drive is searched last. </p> <p>The use of subdirectories |
|
66 in <filepath>\sys\bin</filepath> is not common. </p> </li> |
|
67 </ul> <p>The loader cannot load EXEs from other directories, because system |
|
68 security prevents it. </p> </li> |
|
69 <li id="GUID-1AFA13C7-24B4-5598-94CA-448D05449BBA"><p>The loader compares |
|
70 the UID type (<xref href="GUID-B6D6B0AD-B15C-339A-8540-40540885089A.dita"><apiname>TUidType</apiname></xref>) of each EXE in the list with the |
|
71 UID type you specify in <xref href="GUID-9DD1EA2B-DC59-315C-8E9C-CE6D9461B695.dita#GUID-9DD1EA2B-DC59-315C-8E9C-CE6D9461B695/GUID-DD214BA3-907E-3C7F-93C6-924A9A115A02"><apiname>RProcess::Create()</apiname></xref>. The UID type |
|
72 is a set of three UIDs. Each UID in the UID type that you specify must match |
|
73 the same UID in the UID type of the EXE. If you specify <xref href="GUID-707A476C-1790-34DB-B1E5-5435578E01AA.dita"><apiname>KNullUid</apiname></xref> for |
|
74 any of the three UIDs in your UID type, a match is automatic. </p> </li> |
|
75 <li id="GUID-7F8E3D49-F2CB-5445-ACCC-F7967B4C745F"><p>If the search has found |
|
76 no EXEs, the load fails. </p> </li> |
|
77 <li id="GUID-1469E256-98FF-51B8-9936-78ED389EDCBE"><p>If the search has found |
|
78 one EXE only, the loader loads that EXE. </p> </li> |
|
79 <li id="GUID-90B5C4A5-A0E9-5ADD-B76A-3491C322C4B1"><p>If more than one EXE |
|
80 has been found, the loader loads the EXE with the highest version. A version <codeph>N.n</codeph> is |
|
81 higher than version <codeph>M.m</codeph> if <codeph>(N>M or (N==M and n>m))</codeph>. </p> </li> |
|
82 <li id="GUID-A4761946-0490-5887-9686-184B6BED556C"><p>If all EXEs have the |
|
83 same version, the loader loads the version found first. </p> </li> |
|
84 </ol> </section> |
|
85 <section id="GUID-E026ABAD-D76E-51EF-886F-28F8E00185E5"><title>Search rules |
|
86 for a DLL in the import table of an EXE or another DLL</title> <p>After the |
|
87 loader has selected the EXE, the loader loads all DLLs in the import table. |
|
88 This is also called static linkage. </p> <p>The import table contains the |
|
89 name and extension of each DLL. The import table also contains the version |
|
90 of each DLL and the 3rd UID that identifies each DLL. The version information |
|
91 is stored in the import table when the executable file is built. All DLLs |
|
92 have an ordered set of three UIDs. The third UID gives a unique identity to |
|
93 the DLL. See <xref href="GUID-C135B8D8-DA5A-5852-9C2D-18622404FE99.dita">UID protection</xref>. </p> <p><b>The search procedure</b> </p> <p>The search uses the following procedure |
|
94 for each DLL: </p> <ol id="GUID-FF01C553-8546-5A2C-B34B-8F85014631D6"> |
|
95 <li id="GUID-42FD9744-4B2C-55D6-A7B0-73DE248861DE"><p>The loader searches |
|
96 the <filepath>\sys\bin</filepath> directory on all drives for all DLLs that |
|
97 have the filename and extension. The loader searches drives in the order <filepath>Y:</filepath>, <filepath>X:</filepath> ... <filepath> B:</filepath>, <filepath>A:</filepath>. The <filepath>Z:</filepath> drive is searched |
|
98 last. Subdirectories of <filepath>\sys\bin</filepath> are not searched. The |
|
99 loader searches for all versions of the DLL. If the loader finds the same |
|
100 version of a DLL on more than one drive, the loader only adds the first one |
|
101 to the set of possible DLLs. For example, if version 2.1 of a DLL is on drive <filepath>D:</filepath> and |
|
102 on drive <filepath>Z:</filepath>, only the version on drive <filepath>D:</filepath> is |
|
103 added to the set of possible DLLs. </p> <p>The loader cannot load DLLs from |
|
104 other directories, because system security prevents it. </p> <p>[Before December |
|
105 2007, the loader had different behaviour. The loader searched the drive from |
|
106 which the EXE was loaded before the loader checked the other drives. For example, |
|
107 if the EXE was loaded from drive <filepath>Z:</filepath>, and version 2.1 |
|
108 of a DLL was on drive <filepath>D:</filepath> and drive <filepath>Z:</filepath>, |
|
109 the loader selected the version of the DLL that was on drive <filepath>Z:</filepath>.] </p> </li> |
|
110 <li id="GUID-BC036626-7461-5C4E-A710-09D693CE5A1E"><p>The loader then selects |
|
111 those DLLs that have the same 3rd UID from the set of possible DLLs. This |
|
112 operation can decrease the set of possible DLLs. If there are no DLLs in the |
|
113 set, the load fails. </p> </li> |
|
114 <li id="GUID-9AE6A749-4C72-557F-AB3A-5E33E246A8AE"><p>The loader then selects |
|
115 those DLLs that have platform security capabilities that match or exceed those |
|
116 of the EXE. This selection operation can decrease the set of possible DLLs. |
|
117 If there are no DLLs in the set the load fails. </p> <p>See also : <xref href="GUID-4BFEDD79-9502-526A-BA7B-97550A6F0601.dita">Platform |
|
118 security</xref>. </p> </li> |
|
119 <li id="GUID-7F083400-E8FB-52E0-A8CD-D96DDB093F39"><p>Each DLL in the import |
|
120 table of the EXE has a version number. This number is the version of the DLL |
|
121 to which the EXE is linked. The loader uses the version number in the import |
|
122 table to select the correct version of the DLL. The following flowchart shows |
|
123 how the loader selects the DLL from the set of possible DLLs. </p> <fig id="GUID-1F388A1E-BBB8-5481-8197-1F3C87BB2948"> |
|
124 <image href="GUID-9D2752D1-4153-5978-A7B8-4C3F860B6B87_d0e377697_href.png" placement="inline"/> |
|
125 </fig> </li> |
|
126 <li id="GUID-56B0AF9F-4D39-517B-A3A5-779B7D892CEF"><p>If there are no DLLs |
|
127 that meet the requirements, the load fails. </p> </li> |
|
128 </ol> </section> |
|
129 <section id="GUID-FA4768B2-A741-5601-990C-46B51DA77803"><title>Search rules |
|
130 for a DLL loaded from a program</title> <p>To load a DLL from a program, call <xref href="GUID-25327159-83D6-3507-B187-09EA4BB3727F.dita#GUID-25327159-83D6-3507-B187-09EA4BB3727F/GUID-4F1B2717-D34F-32A4-B6E6-03D0533186A3"><apiname>RLibrary::Load()</apiname></xref>. |
|
131 This is known as dynamic linking. </p> <p> <codeph>RLibrary::Load()</codeph> loads |
|
132 the DLL specified in the input parameters. The function then uses the import |
|
133 table to get a list of referred DLLs. The loader loads the DLLs in the list |
|
134 and uses the same search method that the loader uses for EXEs. See <xref href="GUID-D8837969-74D0-5E17-AD42-3F10DD1FD5BF.dita#GUID-D8837969-74D0-5E17-AD42-3F10DD1FD5BF/GUID-E026ABAD-D76E-51EF-886F-28F8E00185E5">Search rules for a DLL in the import table of an EXE</xref>. </p> <p>The |
|
135 result of a search for an DLL depends on: </p> <ul> |
|
136 <li id="GUID-CBC9178F-D0CD-5558-9AA0-338F7CB52479"><p>the name of the DLL. |
|
137 You provide this information. </p> </li> |
|
138 <li id="GUID-E735C0C9-CFCE-5A37-8E41-313039AAD44B"><p>the UID type : you provide. |
|
139 This is optional. </p> </li> |
|
140 <li id="GUID-14168E41-7825-5546-BD2C-02BB107D2D3C"><p>the required version |
|
141 : you provide. This is optional. </p> </li> |
|
142 <li id="GUID-03ED4A5A-813A-5332-BCA5-8735793A4370"><p>the version of the DLLs |
|
143 on the device. </p> </li> |
|
144 </ul> <p>You pass the name of the DLL in the first parameter of <codeph>RLibrary::Load()</codeph>. |
|
145 You have a number of choices: </p> <ul> |
|
146 <li id="GUID-D5C6F45B-0BCF-58E5-993A-999F96F24354"><p>you can specify the |
|
147 file name only. The loader will assume a <filepath>.dll</filepath> file extension. |
|
148 For example: </p> <p> <filepath>efsrv</filepath> </p> </li> |
|
149 <li id="GUID-63E96237-0DA1-502E-9C39-4562A31BF616"><p>you can specify a filename |
|
150 and an extension. For example: </p> <p> <filepath>efsrv.dll</filepath> </p> </li> |
|
151 <li id="GUID-B1FC4B22-267B-5B6B-8ADC-62C7012C7925"><p>you can put a path in |
|
152 front of the file name. A path has limited use, because the loader can load |
|
153 DLLs only from the directory <filepath>\sys\bin</filepath>, or from subdirectories |
|
154 of <filepath>\sys\bin</filepath>. </p> </li> |
|
155 </ul> <p>See <xref href="GUID-4A56B285-790E-5171-88F3-8C40B2AA9699.dita">Dynamically |
|
156 loading link libraries</xref> and <xref href="GUID-9E92EE30-F2E2-5F28-BB2A-391C09EC69D2.dita">Using |
|
157 ECom</xref>. </p> <p><b>The |
|
158 search procedure</b> </p> <p>The loader searches for DLLs with the given name |
|
159 and extension. More than one DLL with the given name and extension can exist |
|
160 on a device. </p> <ol id="GUID-5AA22DFB-F4D1-5358-96DE-D6B43BCB905E"> |
|
161 <li id="GUID-60421212-8123-54A2-9A77-71C39E7EB4B6"><p>If you do not provide |
|
162 a path, the loader searches the <filepath>\sys\bin</filepath> directory on |
|
163 all drives. The loader searches drives in the order <filepath>Y:</filepath>, <filepath>X:</filepath> ... <filepath> B:</filepath>, <filepath>A:</filepath>. The <filepath>Z:</filepath> drive is searched last. Subdirectories of <filepath>\sys\bin</filepath> are |
|
164 not searched. </p> <p>If you provide a path, there are only three useful cases: </p> <ul> |
|
165 <li id="GUID-693CCFBB-E1A7-50BD-AC89-95F73E0A569D"><p>to limit the search |
|
166 to a specific drive. For example: </p> <p> <filepath>X:\sys\bin</filepath> </p> <p>where <filepath>X:</filepath> can |
|
167 be one of the drives <filepath>A:</filepath> to <filepath>Z:</filepath>. </p> </li> |
|
168 <li id="GUID-F1B66565-1FC3-571D-9CD2-84AE8013F48E"><p>to limit the search |
|
169 to a subdirectory of <filepath>\sys\bin</filepath> on a specific drive. For |
|
170 example: </p> <p> <filepath>X:\sys\bin\aaa\bb</filepath> </p> <p>The use |
|
171 of subdirectories in <filepath>\sys\bin</filepath> is not common. </p> <p>where <filepath>X:</filepath> can |
|
172 be one of the drives <filepath>A:</filepath> to <filepath>Z:</filepath>. </p> </li> |
|
173 <li id="GUID-AADB293F-8945-5875-B3C2-9B77F938EDEF"><p>to limit the search |
|
174 to a subdirectory of <filepath>\sys\bin</filepath> on all drives. For example: </p> <p> <filepath>\sys\bin\aaa\bbb</filepath> </p> <p>The |
|
175 loader searches all drives in the order <filepath>Y:</filepath>, <filepath>X:</filepath> ... <filepath> B:</filepath>, <filepath>A:</filepath>. |
|
176 The <filepath>Z:</filepath> drive is searched last. </p> <p>The use of subdirectories |
|
177 in <filepath>\sys\bin</filepath> is not common. </p> </li> |
|
178 </ul> <p>System security prevents the loader from loading DLLs from any other |
|
179 directories. </p> </li> |
|
180 <li id="GUID-F0DD2783-C346-5F30-8691-7BC3F13D8F76"><p>The loader compares |
|
181 the UID type (<xref href="GUID-B6D6B0AD-B15C-339A-8540-40540885089A.dita"><apiname>TUidType</apiname></xref>) of each DLL in the list with the |
|
182 UID type you specify in <xref href="GUID-25327159-83D6-3507-B187-09EA4BB3727F.dita#GUID-25327159-83D6-3507-B187-09EA4BB3727F/GUID-4F1B2717-D34F-32A4-B6E6-03D0533186A3"><apiname>RLibrary::Load()</apiname></xref>. The UID type |
|
183 is a set of three UIDs. Each UID in the UID type that you specify must match |
|
184 the same UID in the UID type of the DLL. If you specify <xref href="GUID-707A476C-1790-34DB-B1E5-5435578E01AA.dita"><apiname>KNullUid</apiname></xref> for |
|
185 any of the three UIDs in your UID type, there is a match. </p> </li> |
|
186 <li id="GUID-F86E7050-500E-5C21-AA70-98DC95E8BB73"><p>If the search has found |
|
187 no DLLs, the load fails. </p> </li> |
|
188 <li id="GUID-27848CFE-3B37-5350-83B1-48A2B1E83705"><p>The loader then selects |
|
189 those DLLs that have platform security capabilities that match or exceed those |
|
190 of the process . This selection operation can decrease the set of possible |
|
191 DLLs. If there are no DLLs in the set the load fails. </p> </li> |
|
192 <li id="GUID-0A421D77-7BE4-5C9F-AB93-F6F0E06342A3"><p>If the search has found |
|
193 no DLLs, the load fails. </p> </li> |
|
194 <li id="GUID-A34E59F9-FAD4-54DB-86A6-C2A428710FB8"><p>If you specify a version |
|
195 number in <xref href="GUID-25327159-83D6-3507-B187-09EA4BB3727F.dita#GUID-25327159-83D6-3507-B187-09EA4BB3727F/GUID-4F1B2717-D34F-32A4-B6E6-03D0533186A3"><apiname>RLibrary::Load()</apiname></xref>, the loader selects a version |
|
196 of the DLL from the set. The following flowchart shows how the loader selects |
|
197 the DLL from the set of possible DLLs. </p> <fig id="GUID-9412E498-19E5-5D58-B913-DD55BBB79D4D"> |
|
198 <image href="GUID-91224821-8094-59ED-A100-4174193A25EE_d0e377988_href.png" placement="inline"/> |
|
199 </fig> </li> |
|
200 <li id="GUID-61AE1C0C-A698-5BEC-A5DA-E28CB5D807A3"><p>If there are no DLLs |
|
201 that meet the requirements, the load fails. </p> </li> |
|
202 <li id="GUID-D8791217-B11C-548A-9756-10476E843A51"><p>If you do not specify |
|
203 a version number in <xref href="GUID-25327159-83D6-3507-B187-09EA4BB3727F.dita#GUID-25327159-83D6-3507-B187-09EA4BB3727F/GUID-4F1B2717-D34F-32A4-B6E6-03D0533186A3"><apiname>RLibrary::Load()</apiname></xref>, the loader loads |
|
204 the DLL with the highest version. A version <codeph>N.n</codeph> is higher |
|
205 than version <codeph>M.m</codeph>, if <codeph>(N>M or (N==M and n>m))</codeph>. </p> </li> |
|
206 <li id="GUID-D43C380A-C315-5C7B-8508-0720EB1E1EEE"><p>If all DLLs have the |
|
207 same version, the loader loads the DLL found first. </p> </li> |
|
208 </ol> </section> |
|
209 </conbody></concept> |