Mercurial Mercurial > oss > FCL > sftools > depl > docscontent / diff
summary | shortlog | changelog | graph | tags | bookmarks | branches | files | changeset | file | latest | revisions | annotate | diff | comparison | raw | help
Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Symbian3/SDK/Source/GUID-D8837969-74D0-5E17-AD42-3F10DD1FD5BF.dita
changeset 0 89d6a7a84779 
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Symbian3/SDK/Source/GUID-D8837969-74D0-5E17-AD42-3F10DD1FD5BF.dita	Thu Jan 21 18:18:20 2010 +0000
@@ -0,0 +1,12 @@
+<?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 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&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_d0e239986_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_d0e240271_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>
\ No newline at end of file
FCL/sftools/depl/docscontent