dlopene man page on HP-UX

Man page or keyword search:  
man Server   10987 pages
apropos Keyword Search (all sections)
Output format
HP-UX logo
[printable version]

dlopen_ia(3C)							 dlopen_ia(3C)

NAME
       dlopen_ia:  dlopen(),  dlopene()	 -  open a shared library on Integrity
       systems

SYNOPSIS
       Command: [flag]... cfile... [library]...

   Remarks
       This manpage describes on Integrity systems.  For on HP	9000  systems,
       see dlopen_pa(3C).

   Multithread Usage
       These routines are thread-safe.

       Note: The dynamic loader serializes the loading and unloading of shared
       libraries in multithreaded applications using a recursive pthread mutex
       lock.  See the for more information.

DESCRIPTION
       and  are	 members  of  a	 family	 of routines that give the user direct
       access to the dynamic linking facilities (using the option on the  com‐
       piler or command line).

       makes  a	 shared	 object	 specified  by	a  file available to a running
       process.	 A shared object may specify other objects that it "needs"  in
       order to execute properly.  These dependencies are specified by entries
       in the section of the original object.	Each  needed  object  may,  in
       turn,  specify other needed objects.  All such objects are loaded along
       with the original object as a result of the call to

       is an extension to which allows the caller to  specify  explicitly  the
       placement  of a shared library's text and data segment when the library
       is dynamically loaded.

       A successful or call returns to the process a handle which the  process
       may use on subsequent calls to and This value should not be interpreted
       in any way by the process.

       file is used to construct a path name to the object file.  If file con‐
       tains  a	 slash character, the file argument itself is used as the path
       name.  Otherwise searches a series of  directories,  in	the  following
       order, for file:

	 ·  Any directories specified by the dynamic path set by calling

	 ·  Any directories specified by the environment variable

	 ·  Any directories specified by

	 ·  Any	 directories specified by a entry in the section of the origi‐
	    nal program object.

	 ·  The directories in 32-bit mode and in 64-bit mode.

	 ·  The current working directory.

       If the value of file is provides a handle on a "global symbol  object".
       This  object  provides  access  to  the	symbols from an ordered set of
       objects consisting of the original all of the objects that were	loaded
       at program startup along with the and all objects loaded using a opera‐
       tion along with the flag.  As the latter set of objects can change dur‐
       ing  execution,	the  set  identified by handle can also change dynami‐
       cally.

       Only a single copy of an object file is brought into the address space,
       even if is invoked multiple times in reference to the file, and even if
       different path names are used to reference the file.

       When a shared object is brought into the address space of a process, it
       may  contain  references to symbols whose addresses are not known until
       the object is loaded.  These references must be	relocated  before  the
       symbols can be accessed.	 The mode parameter governs when these reloca‐
       tions take place and may have the following values:

       Under this	   mode, the shared library loaded has its  text  seg‐
			   ment mapped private.	 This can be useful for debug‐
			   ging.

       Under this	   mode, only references to data symbols are relocated
			   when the object is loaded.  References to functions
			   are not relocated until a given function is invoked
			   for	the  first  time.   This mode should result in
			   better performance, since a process may not	refer‐
			   ence	 all  of  the  functions  in  any given shared
			   object.

       Under this	   mode, all necessary relocations are performed  when
			   the	object	is  first  loaded.  This may result in
			   some wasted effort, if  relocations	are  performed
			   for	functions  that	 are  never referenced, but is
			   useful for applications that need to know  as  soon
			   as  an object is loaded that all symbols referenced
			   during execution are available.

       Any object loaded by that requires relocations against  global  symbols
       can reference the symbols in the original any objects loaded at program
       startup, from the object itself as well as any other object included in
       the same invocation, and any objects that were loaded in any invocation
       that specified the flag.	 To determine the scope of visibility for  the
       symbols	loaded with a invocation, the mode parameter should be bitwise
       or'ed with one of the following values:

       The object's symbols are made available for the relocation processing
			   of any other object.	 In  addition,	symbol	lookup
			   using  and an associated allows objects loaded with
			   to be searched.

       The object's symbols are made available for relocation processing only
			   to objects loaded in the same invocation.

       If neither nor are specified, the default is

       If a file is specified in multiple invocations, mode is interpreted  at
       each  invocation.   Note,  however,  that  once has been specified, all
       relocations will have been completed, rendering any further  operations
       redundant and any further operations irrelevant.

       Similarly,  note that once has been specified, the object will maintain
       the status regardless of any previous or	 future	 specification	of  so
       long as the object remains in the address space (see dlclose(3C)).

       To  determine  the scope of symbols that are made available for reloca‐
       tion processing of objects loaded in a invocation, the  mode  parameter
       can be bitwise or'ed with one of the following values:

       Under this	   mode,  the  specified object, and its dependencies,
			   behave as if they  were  built  with	 (see  ld(1)).
			   Only	 symbols from objects loaded in the same invo‐
			   cation are made  available  for  relocation.	  This
			   ensures  that  all  relocations are satisfied using
			   symbol definitions from the same invocation.

       Under this	   mode, only symbols from global objects and from the
			   object itself are available for relocation process‐
			   ing.	 It does not use symbol definitions from other
			   objects  loaded  as	part  of the invocation.  This
			   flag has no	effect	on  objects  build  with  (see
			   ld(1)).

       Under this	   mode, symbols from the object that invoked are also
			   made available for relocation.

       The default modes for are These flags are OR'ed together when the  same
       object is loaded with different modes.

       The  following  flags  do  not affect relocation processing but provide
       other features:

       Under this	   mode, the specified	object	and  its  dependencies
			   behave  as if they were built with (see ld(1)).  An
			   explicit unload using or returns  success  silently
			   without  detaching  the  shared  library  from  the
			   process.  Subsequently, the shared  library	handle
			   is  valid  only  for It stays invalid for and until
			   the next explicit load using or

       Under this	   mode, the specified object is not loaded  into  the
			   process's  address  space,  but  a  valid handle is
			   returned  if	 the  object  already  exists  in  the
			   process  address  space.   If  the specified object
			   does not already exist, then an error is  returned.
			   can	be used to query the presence, or for overrid‐
			   ing the modes, of an existing object.

       Symbols introduced into a program through calls to may be used in relo‐
       cation activities.  Symbols so introduced may duplicate symbols already
       defined by the program or previous operations.  To resolve the ambigui‐
       ties  such a situation might present, the resolution of a symbol refer‐
       ence to a symbol definition is based on a symbol resolution order.

       Two such resolution orders are defined: load and dependency ordering.

       Load order establishes an ordering among symbol definitions  using  the
       temporal	 order	in  which  the objects containing the definitions were
       loaded, such that the definition first loaded has priority over defini‐
       tions added later.  Load ordering is used in relocation processing.

       Dependency  ordering uses a "breadth-first" order starting with a given
       object, then all of its dependencies, then  any	dependents  of	those,
       iterating  until all dependencies are satisfied.	 With the exception of
       the global symbol object obtained via a operation  on  a	 file  with  a
       value  dependency  ordering  is used by the function.  Load ordering is
       used in operations on the global symbol object.

       When an object is first	made  accessible  via  it  and	its  dependent
       objects	are  added  in	dependency order.  Once all objects are added,
       relocations are performed using load order.  Note that if an object and
       its  dependencies  have	been  loaded  by  a  previous invocation or on
       startup, the load and dependency order may yield different resolutions.

       The symbols introduced by operations and available  through  are	 those
       which  are  "exported"  as  symbols of global scope by the object.  For
       shared objects, such symbols are typically those that were specified in
       (for  example) C source code as having extern linkage.  For only a sub‐
       set of externally visible symbols are typically exported:  specifically
       those referenced by the shared objects with which the is linked.

       The  exact  set of exported symbols for any shared object or the can be
       controlled using the linker (see ld(1)).

       The dlopen_opts structure has the following members:

       flags contains the load option, defined by logical OR of the  following
       values:

       Indicates that an explicit base address for the shared library
			   text segment is provided.

       Indicates that an explicit base address for the shared library
			   private data segment is provided.

       If this flag is set,
			   does	 not  zero  fill the bss part of the data seg‐
			   ment.  This may improve  load  time	for  libraries
			   with	 large	bss  sections. This flag is only valid
			   with

       The dynamic loader only accesses the address fields that are  specified
       by the flags fields.

       text_addr  contains  the explicit base address for the shared library's
       text segment.

       data_addr contains the explicit base address for the  shared  library's
       data segment.

       Both the text_addr and data_addr must be aligned at a 16-byte boundary.

       The caller can invoke to obtain the information needed to allocate mem‐
       ory for the load segments.

       The caller of is responsible for allocating memory with the appropriate
       permission:

	 ·  READ, WRITE and EXECUTE (RWX) permission for text_addr.

	 ·  READ and WRITE (RW) permission for data_addr.

RETURN VALUE
       If  file cannot be found, cannot be opened for reading, is not a shared
       object, or if an error occurs during the process	 of  loading  file  or
       relocating  its symbolic references, returns NULL.  More detailed diag‐
       nostic information is available through or

ERRORS
       If or fails, a subsequent call to returns one of the following values:

       Cannot load library because required  extensions	 not  present  in  the
       hardware.

       64-bit program found a 32-bit shared library.

       32-bit program found a 64-bit shared library.

       Not a valid library.

       Invalid library: bad alignment.

       Invalid library: bad machine type.

       Invalid library: bad object file type.

       Invalid library: program header not found.

       Invalid library: bad magic number.

       Invalid library: symbol table missing.

       Library needs a shared fixed address but has multiple data segments.

       Unknown elf version in library.

       Unknown relocation type.

       Cannot apply relocation in library.

       Unsatisfied code symbol in library.

       Unsatisfied data symbol in library.

       Library needs a shared fixed address but unable to obtain it from

       Invalid flags for

       Cannot			     library because it contains TLS data.

       Invalid load address for segment
				     only).

       Shared library missing execution permission
				     only).

       Library contains a static TLS reference to a symbol defined in a
				     dynamically loaded library.

       Cannot open filtered library: TLS size exceeds size recorded in filter.

       Internal error encountered in

       I/O error mapping library.

       Unable to find library.

       failed for library.

       failed for the library.

       Out of memory.

       Encounter error while loading library
				     only).

       Non-thread-specific relocation referencing TLS symbol.

       Unable to open library.

       Cannot use pre-allocated address for mapping library that requires
				     a fixed address only).

       failed on entry to or exit from dld API.

       failed on exit from dld API.

       failed on entry to dld API.

       TPREL relocation on non-TLS symbol.

EXAMPLES
       The  following  example illustrates the use of to load a shared library
       with an explicit data segment address.  For simplicity, error  checking
       has been omitted.

       #include <dlfcn.h>
       #include <sys/mman.h>

       int main() {
	   struct dlfileinfo info;
	   void *handle;
	   struct dlopen_opts opts;
	   int status;

	   memset(&info, 0, sizeof(info));
	   memset(&opts, 0, sizeof(opts));

	   /* Get file info */
	   status = dlgetfileinfo("libfoo.so", sizeof(info), &info);

	   opts.flags = RTLD_EXT_DATA_ADDR;
	   /* allocate memory for the data segment */
	   opts.data_addr = (char*) mmap(0, info.data_size,
				       PROT_READ|PROT_WRITE,
				       MAP_SHARED|MAP_ANONYMOUS,
				       -1, 0);

	   /* call dlopene */
	   handle = dlopene("libfoo.so", RTLD_NOW|RTLD_GLOBAL, &opts);

	   /* Insert user code to use library */

	   /* close library */
	   status = dlclose(handle);

	   /* free memory */
	   munmap(opts.data_addr, info.data_size);
       }

WARNINGS
       The  environment	 variable and should contain a colon-separated list of
       directories, in the same format as the variable (see sh(1)).   and  are
       ignored	if  the	 process' real user id is different from its effective
       user id or its real group id is different from its effective  group  id
       (see exec(2)).

       With  the option specified, and embedded path are ignored while search‐
       ing for dependent libraries.

       Use caution when building shared libraries with external library depen‐
       dencies.	 Any library that contains Thread Local Storage (TLS) and uses
       static TLS model should not be used as a dependency.  See in  dld.so(5)
       for more information.

       If  a  dependent library contains TLS, was built with static TLS model,
       and was not loaded during program startup (that is, not linked  against
       the  executable),  the  dynamic	loader fails to perform the operation.
       You can use compiler option to re-compile the library to avoid errors.

SEE ALSO
       cc(1), ld(1), sh(1), exec(2),  dlclose(3C),  dlerrno(3C),  dlerror(3C),
       dlgetfileinfo(3C), dlsetlibpath(3C), dlsym(3C).

   Texts and Tutorials
       (See the		   option)

[top]

List of man pages available for HP-UX

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net