<?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_d0e264555_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_d0e264846_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>