dlopen(3c) 맨 페이지 - 윈디하나의 솔라나라

개요

섹션
맨 페이지 이름
검색(S)

dlopen(3c)

Standard C Library Functions                                        dlopen(3C)



NAME
       dlopen, dlmopen - gain access to an executable object file

SYNOPSIS
       #include <dlfcn.h>
       #include <link.h>

       void *dlopen(const char *pathname, int mode);


       void *dlmopen(Lmid_t lmid, const char *pathname, int mode);


DESCRIPTION
       The  dlopen()  function  makes an executable object file available to a
       running process. dlopen() returns to the  process  a  handle  that  the
       process   can   use  on  subsequent  calls  to  dlsym(3C),  dladdr(3C),
       dlinfo(3C), and dlclose(3C). The value of this  handle  should  not  be
       interpreted  in  any  way  by the process. The pathname argument is the
       path name of the object to be opened. A path name containing an  embed‐
       ded  '/'  is interpreted as an absolute path or relative to the current
       directory. Otherwise, the set of search paths currently  in  effect  by
       the runtime linker are used to locate the specified file. See NOTES.


       If the object file referenced by dlopen() is not already loaded as part
       of the process, then the object file is added to  the  process  address
       space.  A handle for this object is created and returned to the caller.
       If the object file is already part of the process,  a  handle  is  also
       returned  to  the caller. Multiple references to the same object result
       in returning the same handle. A reference count within the handle main‐
       tains  the  number  of  callers.  The  dlclose() of a handle results in
       decrementing the handles reference  count.  When  the  reference  count
       reaches  0  the object file is a candidate for unloading. Any init sec‐
       tion within an object is called once when the  object  is  loaded.  Any
       fini  section  within  an  object  is  called  once  when the object is
       unloaded.


       When dlopen() causes an object to be loaded, it also loads any non-lazy
       dependencies  that  are  recorded  within the object given by pathname.
       These dependencies are searched in the order in which the  dependencies
       were loaded to locate any additional dependencies. This process contin‐
       ues until all the dependencies of pathname are loaded. This  dependency
       tree is referred to as a group.


       If  the  value of pathname is 0, dlopen() provides a handle on a set of
       global symbol objects. These objects consist of  the  original  program
       image file, any dependencies loaded at program startup, and any objects
       loaded using dlopen() with the RTLD_GLOBAL flag. Because the latter set
       of  objects  can change during process execution, the set identified by
       handle can also change dynamically.


       The mode argument describes how  dlopen()  operates  on  pathname  with
       respect  to  the  processing  of  reference  relocations. The mode also
       affects the scope of visibility of the symbols provided by pathname and
       its  dependencies.  This visibility can affect how the resulting handle
       is used.


       When an object is loaded, the object can contain references to  symbols
       whose  addresses are not known until the object is loaded. These refer‐
       ences must be relocated before the symbols can be accessed.  References
       are  categorized  as either immediate or lazy. Immediate references are
       typically references to data items used by the object  code.  Immediate
       references  include  pointers  to functions and calls to functions made
       from position-dependent shared objects. Lazy references  are  typically
       calls  to  global  functions  that  are  made from position-independent
       shared objects.


       Lazy references can also be identified as deferred. See the -z deferred
       option  of  ld(1). Deferred dependencies are only loaded during process
       execution, when the first binding to  a  deferred  reference  is  made.
       These references are unaffected by the mode.


       The  mode argument governs when non-deferred references take place. The
       mode argument can be one of the following values.

       RTLD_LAZY

           Only immediate symbol references are relocated when the  object  is
           first loaded. Lazy references are not relocated until a given func‐
           tion is called for the first  time.  This  value  for  mode  should
           improve  performance,  since  a  process might not require all lazy
           references in any given object. This  behavior  mimics  the  normal
           loading of dependencies during process initialization. See NOTES.


       RTLD_NOW

           All non-deferred relocations are performed when the object is first
           loaded. This process might waste some processing if relocations are
           performed  for  lazy  references that are never used. However, this
           mode ensures that when an object is loaded, all  non-deferred  sym‐
           bols  that  are  referenced  during  execution  are available. This
           behavior mimics the loading of dependencies  when  the  environment
           variable LD_BIND_NOW is in effect.



       See  the  Oracle  Solaris  11.3 Linkers and Libraries         Guide for
       more information about symbol references.


       The visibility of symbols that are  available  for  relocation  can  be
       affected  by  mode. To specify the scope of visibility for symbols that
       are loaded with a dlopen() call, mode should be a bitwise-inclusive  OR
       with one of the following values:

       RTLD_GLOBAL

           The  object's  global symbols are made available for the relocation
           processing of any other object. In addition,  symbol  lookup  using
           dlopen(0,  mode)  and an associated dlsym() allows objects that are
           loaded with RTLD_GLOBAL to be searched.


       RTLD_LOCAL

           The object's globals symbols are only available for the  relocation
           processing of other objects that include the same group.



       The  program  image file and any objects loaded at program startup have
       the mode RTLD_GLOBAL. The mode RTLD_LOCAL is the default mode  for  any
       objects that are acquired with dlopen(). A local object can be a depen‐
       dency of more then one group. Any object of  mode  RTLD_LOCAL  that  is
       referenced as a dependency of an object of mode RTLD_GLOBAL is promoted
       to RTLD_GLOBAL. In other words, the RTLD_LOCAL mode is ignored.


       Any object loaded by dlopen() that requires relocations against  global
       symbols can reference the symbols in any RTLD_GLOBAL object. Objects of
       this mode are at least the program image file and any objects loaded at
       program  startup.  A  loaded  object  can  also  reference symbols from
       itself, and from any dependencies the object references.  However,  the
       mode  parameter can also be a bitwise-inclusive OR with one of the fol‐
       lowing values to affect the scope of symbol availability:

       RTLD_GROUP

           Only symbols from the associated group are made available for relo‐
           cation.  A group is established from the defined object and all the
           dependencies of that object. A group must be  completely  self-con‐
           tained.  All  dependency  relationships  between the members of the
           group must be sufficient to satisfy the relocation requirements  of
           each object that defines the group.


       RTLD_PARENT

           The  symbols  of  the  object initiating the dlopen() call are made
           available to the objects obtained by dlopen(). This option is  use‐
           ful  when  hierarchical dlopen() families are created. Although the
           parent object can supply symbols for the relocation of this object,
           the  parent object is not available to dlsym() through the returned
           handle.


       RTLD_WORLD

           Only symbols from RTLD_GLOBAL objects are made available for  relo‐
           cation.



       The  default  modes for dlopen() are both RTLD_WORLD and RTLD_GROUP. If
       an object is requires additional modes, the mode parameter can  be  the
       bitwise-inclusive  OR  of  the required modes together with the default
       modes.


       The following modes provide additional capabilities outside of  reloca‐
       tion processing:

       RTLD_NODELETE

           The  specified  object  is  tagged to prevent its deletion from the
           address space as part of a dlclose().


       RTLD_NOLOAD

           The specified object is not loaded as part of  the  dlopen().  How‐
           ever,  a  valid  handle is returned if the object already exists as
           part of the process address space. Additional modes can  be  speci‐
           fied  as a bitwise-inclusive OR with the present mode of the object
           and its dependencies. The RTLD_NOLOAD  mode  provides  a  means  of
           querying  the presence or promoting the modes of an existing depen‐
           dency.



       The default use of a handle with dlsym()  allows  a  symbol  search  to
       inspect  all objects that are associated with the group of objects that
       are loaded from dlopen(). The mode parameter can  also  be  a  bitwise-
       inclusive OR with the following value to restrict this symbol search:

       RTLD_FIRST

           Use of this handle with dlsym(), restricts the symbol search to the
           first object associated with the handle.



       An object can  be  accessed  from  a  process  both  with  and  without
       RTLD_FIRST. Although the object will only be loaded once, two different
       handles are created to provide for the different dlsym() requirements.


       The dlmopen() function is identical to dlopen(), except that an identi‐
       fying  link-map  ID  (lmid)  is  provided. This link-map ID informs the
       dynamic linking facilities upon which link-map list to load the object.
       See  the  Oracle  Solaris  11.3 Linkers and Libraries         Guide for
       details about link-maps.


       The lmid passed to dlmopen() identifies the link-map list on which  the
       object  is  loaded.  This parameter can be any valid Lmid_t returned by
       dlinfo() or one of the following special values:

       LM_ID_BASE

           Load the object on the applications link-map list.


       LM_ID_LDSO

           Load the object on the dynamic linkers (ld.so.1) link-map list.


       LM_ID_NEWLM

           Cause the object to create a new link-map list as part of  loading.
           Objects  that are opened on a new link-map list must express all of
           their dependencies.


RETURN VALUES
       The dlopen() function returns NULL if pathname cannot be found,  cannot
       be  opened  for  reading,  or  is  not a shared object or a relocatable
       object. dlopen() also returns  NULL  if  an  error  occurs  during  the
       process  of loading pathname or relocating its symbolic references. See
       NOTES. Additional diagnostic information  is  available  through  dler‐
       ror().

USAGE
       The  dlopen()  and dlmopen() functions are members of a family of func‐
       tions that give the user direct access to the dynamic  linking  facili‐
       ties.  This family of functions is available only to dynamically-linked
       processes.  See  the  Oracle  Solaris  11.3   Linkers   and   Libraries
       Guide.

ATTRIBUTES
       See attributes(5) for descriptions of the following attributes:




       tab()   box;   cw(2.75i)  |cw(2.75i)  lw(2.75i)  |lw(2.75i)  ATTRIBUTE
       TYPEATTRIBUTE VALUE _ Interface StabilityCommitted _ MT−LevelMT−Safe
       _ StandardSee standards(5).


SEE ALSO
       ld(1),  ld.so.1(1),  dladdr(3C),  dlclose(3C), dldump(3C), dlerror(3C),
       dlinfo(3C), dlsym(3C), attributes(5), standards(5)


       Oracle Solaris 11.3 Linkers and Libraries         Guide

NOTES
       If pathname has dependencies on other objects, these objects are  auto‐
       matically  loaded  by  dlopen(). The directory search path used to find
       pathname and any dependencies can be affected by setting  the  environ‐
       ment variable LD_LIBRARY_PATH. Any LD_LIBRARY_PATH variable is analyzed
       once at process startup. The search path can also be  affected  from  a
       runpath setting within the object from which the call to dlopen() orig‐
       inates. These search rules will only be applied to path names  that  do
       not  contain  an  embedded '/'. Objects whose names resolve to the same
       absolute path name or relative path name can be opened  any  number  of
       times  using dlopen(). However, the object that is referenced will only
       be loaded once into the address space of the current process.


       When loading shared objects, the application  should  open  a  specific
       version  of the shared object. Do not rely on the version of the shared
       object pointed to by the symbolic link.


       When building objects to be loaded on a new link-map list, some precau‐
       tions  need  to be taken. In general, all dependencies must be included
       when  building  an  object.  Also,  include  /usr/lib/libmapmalloc.so.1
       before /lib/libc.so.1 when building an object.


       When an object is loaded on a new link-map list, the object is isolated
       from the main running program. Certain global resources are only usable
       from  one  link-map list. A few examples are the sbrk() based malloc(),
       libthread(), and the signal vectors. Care must be taken not to use  any
       of  these  resources  other  than from the primary link-map list. These
       issues are discussed in further detail in the Oracle Solaris 11.3 Link‐
       ers and Libraries         Guide.


       Some  symbols  defined in dynamic executables or shared objects can not
       be available to the runtime linker. The symbol table created by ld  for
       use  by  the  runtime linker might contain only a subset of the symbols
       that are defined in the object.


       As part of loading a new object, initialization code within the  object
       is  called  before  the  dlopen()  returns. This initialization is user
       code, and as such, can  produce  errors  that  can  not  be  caught  by
       dlopen().  For  example, an object loaded using RTLD_LAZY that attempts
       to call a function that can not be located results in process  termina‐
       tion.  Erroneous  programming  practices within the initialization code
       can also result in process termination. The runtime  linkers  debugging
       facility  can  offer  help  identifying  these  types of error. See the
       LD_DEBUG environment variable of ld.so.1(1).


       Loading relocatable objects is an  expensive  operation  that  requires
       converting  the  relocatable  object into a shared object memory image.
       This capability may be useful in a debugging environment,  but  is  not
       recommended for production software.



SunOS 5.11                       23 April 2014                      dlopen(3C)
맨 페이지 내용의 저작권은 맨 페이지 작성자에게 있습니다.
RSS ATOM XHTML 5 CSS3