<?xml version="1.0" encoding="utf-8"?>
<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->
<!-- This component and the accompanying materials are made available under the terms of the License 
"Eclipse Public License v1.0" which accompanies this distribution, 
and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->
<!-- Initial Contributors:
    Nokia Corporation - initial contribution.
Contributors: 
-->
<!DOCTYPE concept
  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
<concept id="GUID-D8837969-74D0-5E17-AD42-3F10DD1FD5BF" xml:lang="en"><title>Loader
Search Rules</title><shortdesc>This topic provides a summary of the rules that the loader follows
to search for EXEs and DLLs.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
<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&gt;M or (N==M and n&gt;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_d0e269418_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_d0e269709_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&gt;M or (N==M and n&gt;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>