--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/Symbian3/SDK/Source/GUID-D8837969-74D0-5E17-AD42-3F10DD1FD5BF.dita Wed Mar 31 11:11:55 2010 +0100
@@ -0,0 +1,209 @@
+<?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>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_d0e268263_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_d0e268554_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>
\ No newline at end of file