dlopen_pa 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_pa(3C)							 dlopen_pa(3C)

       dlopen_pa:  dlopen(),  dlopene() - open an HP 9000 shared library; open
       an HP 9000 64-bit shared library with explicit load address

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

       This manpage describes on HP 9000 systems.  For on  Integrity  systems,
       see dlopen_ia(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.

       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

	 ·  For	 ELF applications, any directories specified by a entry in the
	    section of the original program object.

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

	 ·  The current working directory.

       The use of is static.  This means that when  the	 program  starts,  the
       dynamic	loader	uses  the  value in environment variable Any change to
       during the program execution has no effect.  The function removes  this
       constraint.   With you can change the value (using and call to cause to
       read current value.  You can use this new value for subsequent  library

       You  can	 use while loading shared libraries using or As described ear‐
       lier, you should enable searching using the option.   In	 case  of  you
       should use the flag.

       The following example demonstrates the function:

       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‐

       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‐

       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

       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

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

       The modes and are presently supported only for 64-bit applications.

       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.

       Under this	   mode, verbose messages concerning possible unsatis‐
			   fied symbols can be printed.	 This is equivalent to
			   the flag of the routine.  This feature can also  be
			   turned  on for all invocations by setting the envi‐
			   ronment variable to contain the option.

			   Currently, this is applicable only for PA32.

       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 ambiguities such a situation might present, the  resolu‐
       tion  of a symbol reference 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)).

   HP 9000 64-bit dlopene()
       The dlopen_opts structure has the following members:

       flags contains the load option, defined by the logical OR of  the  fol‐
       lowing 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

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

	 ·  READ and WRITE (RW) permission for data_addr.

       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 (64-bit only).

       If or fails, a subsequent call to returns one of the following values:
       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: program header not found.

       Invalid library: bad object file type.

       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

       Shared library missing execution permission

       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

       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.

       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,
					      -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);

       In  64-bit  mode, the environment variables 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's 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)).

       In  64-bit  mode,  with	the  option  specified,	 and embedded path are
       ignored while searching for dependent libraries.

       Use caution when building shared libraries with external library depen‐
       dencies.	  Any  library that contains Thread Local Storage (TLS) should
       not be used as a dependency.  If a dependent library contains TLS,  and
       it  is  not  loaded during program startup (that is, not linked against
       the executable), the dynamic loader fails to perform the operation.

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

   Texts and Tutorials
       (See the


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]
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