|
1 <?xml version="1.0" encoding="utf-8"?> |
|
2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. --> |
|
3 <!-- This component and the accompanying materials are made available under the terms of the License |
|
4 "Eclipse Public License v1.0" which accompanies this distribution, |
|
5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". --> |
|
6 <!-- Initial Contributors: |
|
7 Nokia Corporation - initial contribution. |
|
8 Contributors: |
|
9 --> |
|
10 <!DOCTYPE concept |
|
11 PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> |
|
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_d0e268263_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_d0e268554_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> |