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

shl_load_ia(3X)						       shl_load_ia(3X)

NAME
       shl_load_ia:  shl_load(),  shl_definesym(),  shl_findsym(),  shl_get(),
       shl_get_r(),  shl_gethandle(),	shl_gethandle_r(),   shl_getsymbols(),
       shl_unload() - explicit load of shared libraries for Integrity systems

SYNOPSIS
   Remarks
       This manpage describes routines for Integrity systems.  For routines on
       PA-RISC systems, see shl_load_pa(3X).

DESCRIPTION
       These routines can be used to programmatically load and	unload	shared
       libraries,  and	to obtain information about the libraries (such as the
       addresses of symbols defined within them).  The routines themselves are
       accessed	 by specifying the option on the command line with the command
       (see ld(1)).  See In addition, the option to the command can be used to
       ensure  that  all  symbols  defined in the program are available to the
       loaded libraries.

       Shared libraries are created by compiling source files and linking  the
       resultant object files with the (create shared library) option.

       Attaches the shared library named by
	    path the shared library name that is constructed by using the path
	    part of path plus the shared library basename followed by the suf‐
	    fix (e.g.  to the process, along with all its dependent libraries.
	    A version is looked for first for those shared libraries  that  do
	    not	 have  internal	 names.	 See ld(1)).  The library is mapped at
	    the specified address.  If address is the system chooses an appro‐
	    priate  address for the library.  This is the recommended practice
	    because the system has the most complete knowledge of the  address
	    space;  currently, the address field is ignored, and assumed to be
	    If the shared library contains thread local storage and was	 built
	    with  static TLS model, you cannot load it with this routine.  See
	    "Thread Local Storage" in dld.so(5)	 for  more  information.   The
	    flags argument is made up of several fields.  One of the following
	    must be specified:

		 Resolve symbol references when the library is loaded.

		 Delay code symbol resolution until actual reference.

	    Zero or more of the following can be specified by doing a  bitwise
	    OR operation:

		 Place the library at the head of the symbol search order.
		      In default mode, the library and its dependent libraries
		      are bound independently of each other (see

		 Default
		      behavior is to treat all unsatisfied symbols  as	fatal.
		      This  flag allows binding of unsatisfied code symbols to
		      be deferred until use.

		 Do not call the initializers for the shared library
		      when the library is loaded, nor on a future call	to  or
		      by  default,  all	 the  initializers registered with the
		      specified library are invoked upon loading.

		 Print verbose messages concerning possible  unsatisfied  sym‐
		 bols.

		 Restrict symbols visible to the library
		      to those present at the time the library is loaded.

		 Allow the loader to dynamically search for the library speci‐
		 fied by the
		      path argument.   The  directories	 to  be	 searched  are
		      determined  by  the and options of the command used when
		      the program was linked.  This is enabled by  default  if
		      was not specified.

		 When used with
		      the  library  being  mapped  and its dependent libraries
		      will be bound together.  This is	the  default  behavior
		      for all requests not using

		 Causes the dependent libraries to be loaded breadth first.
		      By default, loads dependent libraries depth-first.

	    If	successful,  returns  a handle which can be used in subsequent
	    calls to or otherwise NULL is returned.  The handle	 can  also  be
	    used in subsequent calls to or

	    Use	 caution  when building shared libraries with external library
	    dependencies.  Any library	that  contains	Thread	Local  Storage
	    (TLS)  and	uses  static  TLS model should not be used as a depen‐
	    dency.  See "Thread Local Storage" in dld.so(5) for more  informa‐
	    tion.   If a dependent library contains TLS, was built with static
	    TLS model, and it is not loaded during program startup  (that  is,
	    not	 linked	 against  the executable), the dynamic loader fails to
	    perform the operation.

       Obtains the address of an exported symbol
	    sym from a shared  library.	  The  handle  argument	 should	 be  a
	    pointer to the handle of a loaded shared library that was returned
	    from a previous call to or You can also get handle from a call  to
	    If	a  pointer  to	NULL is passed for this argument, searches all
	    user defined symbols (those defined by all currently loaded shared
	    libraries  and  the program to find the symbol; otherwise searches
	    only the specified shared library.	The  return  value  of	handle
	    will  be  NULL if the symbol found was generated via Otherwise the
	    handle of the library where the symbol was found is returned.  The
	    special handle can be used to refer to the program itself, so that
	    symbols exported from the program can  also	 be  accessed  dynami‐
	    cally.  The type argument specifies the expected type for the sym‐
	    bol, and should be one of the  defined  constants  or  The	latter
	    value  suppresses  type  checking.	 The  address of the symbol is
	    returned in the variable pointed to by value.  If the symbol is  a
	    thread  local  storage  symbol,  the  address of the symbol is the
	    value of the thread pointer + the starting address of  the	shared
	    library  +	the offset of the symbol in the library.  This routine
	    returns 0 if successful; otherwise −1 is returned.	See for	 errno
	    settings.

       Adds a symbol to the user hash table for the current process.
	    If	value  falls  in  the  range of a currently loaded library, an
	    association will be made and the  symbol  is  undefined  once  the
	    associated	library	 is unloaded.  The defined symbol can be over‐
	    ridden by a subsequent call to this routine or by loading  a  more
	    visible library that provides a definition.	 Symbols overridden in
	    this manner may become visible again if the overriding  definition
	    is removed.

	    Possible symbol types include:

		 Symbol is a function.

		 Symbol is data.

	    Possible  flag  values  include: None defined at the present time.
	    Zero should be passed in to prevent conflicts with future uses  of
	    this  flag.	  You cannot use this routine to define a thread local
	    storage symbol.  will not search for any user defined symbol.

       Provides an array of symbol records,
	    allocated using the supplied memory allocator, that are associated
	    with the library specified by handle.  If the handle argument is a
	    pointer to NULL, symbols defined using are returned.  If  multiple
	    versions  of  the same symbol have been defined with only the ver‐
	    sion from the specified symbol information source  that  would  be
	    considered	for  symbol binding is returned.  The type argument is
	    used to restrict the return information to a specific type.	  Val‐
	    ues	 of and can be used to limit the returned symbols to be either
	    code or data respectively.	The value cause	 both  data,  storage,
	    and	 tstorage symbols to be returned.  The constant can be used to
	    return all symbols, regardless of type.  The flags	argument  must
	    have one of the following values:

		 Return symbols found on the import list.

		 Return symbols found on the export list.
		      All symbols defined by are export symbols.

		 Return	 symbols that are specified as the initializers of the
		 library.

	    Zero or more of the following can be specified by doing a  bitwise
	    OR operation:

		 Only makes sense when combined with
		      or Do not calculate the value field in the return struc‐
		      ture to avoid symbol binding by the  loader  to  resolve
		      symbol  dependencies.   If  only a few symbol values are
		      needed, can be used to find the  values  of  interesting
		      symbols.	This is not to be used with

		 Only makes sense when combined with
		      or Use the name and type information of each return sym‐
		      bol and find the most visible occurrence using all  sym‐
		      bol information sources.	The value and handle fields in
		      the symbol return structure reflect where the most visi‐
		      ble occurrence was found.	 Not to be used with

	    The	 memory	 argument  should  point  to  a function with the same
	    interface as (see malloc(3C)).

	    The return information consists  of	 an  array  of	the  following
	    records (defined in

	    The	 type field in the return structure can have the values or The
	    value and handle fields are	 only  valid  if  export  symbols  are
	    requested and the flag is not specified.  The value field contains
	    the address of the symbol, while the handle field is the handle of
	    the	 library  that defined the symbol, or NULL for symbols defined
	    via the routine and is useful in conjunction with the flag.

	    If successful, returns the number of symbols found;	 otherwise  it
	    returns −1.

       Can be used to detach a shared library from the process.
	    The	 handle argument should be the handle returned from a previous
	    call to You can also get the handle from a call to	returns	 0  if
	    successful; otherwise −1 is returned.  Any initializers registered
	    with the library are called	 before	 detachment.   All  explicitly
	    loaded  libraries  are  detached automatically on process termina‐
	    tion.

	    The same shared library can be opened multiple times.  A reference
	    counter  is kept for each loaded shared library, like the behavior
	    of dlopen(3C) and dlclose(3C).  does not remove the shared library
	    from the address space until all references to that shared library
	    have been removed.

       Returns information about currently loaded libraries,
	    including those loaded implicitly  at  startup  time.   The	 index
	    argument  is  the  ordinal	position  of the shared library in the
	    shared library search list for the process.	 A subsequent call  to
	    or	decrements  the	 index values of all libraries having an index
	    greater than the unloaded library.	The index value −1  refers  to
	    the	 dynamic  loader  and the index value −2 refers to the program
	    itself.  The desc argument is used to return a pointer to a stati‐
	    cally  allocated  buffer  containing  a  descriptor for the shared
	    library.  The format of the descriptor  is	implementation	depen‐
	    dent; to examine its format, look at the contents of file Informa‐
	    tion common to all implementations includes	 the  library  handle,
	    pathname,  and  the	 range of addresses the library occupies.  The
	    buffer for the descriptor used by is static; the  contents	should
	    be	copied elsewhere before a subsequent call to the routine.  The
	    routine returns 0 normally, or −1 if an invalid index is given.

       Returns information about the library specified by the handle argument.
	    The special handle can be used to refer  to	 the  program  itself.
	    The	 descriptor  returned  is  the same as the one returned by the
	    routine.  The buffer for the descriptor used  by  is  static;  the
	    contents  should  be  copied elsewhere before a subsequent call to
	    the routine.  The routine returns 0 normally, or −1 on error.

       This is a reentrant version of
	    The desc argument must point to a buffer  of  enough  user-defined
	    storage  to be filled with the library descriptor described in Its
	    semantics are otherwise identical to

       This is a reentrant version of
	    The desc argument must point to a buffer  of  enough  user-defined
	    storage  to be filled with the library descriptor described in Its
	    semantics are otherwise identical to

MULTITHREAD USAGE
       These routines are safe to be called from multithreaded applications.

DIAGNOSTICS
       If a library cannot be loaded, returns NULL and sets  to	 indicate  the
       error.  This includes trying to a library containing thread local stor‐
       age.  All other functions return −1 on error and set

       If cannot find the indicated symbol, is set to zero.  On PA-RISC 32-bit
       compatibility  mode  only,  if  finds  the  indicated symbol but cannot
       resolve all the symbols it depends on, is set to

ERRORS
       Possible values for include:

	      The specified file is not a shared library, or  a	 format	 error
	      was detected.

	      Some symbol required by the shared library could not be found.

	      The specified handle or index is not valid
			     or	 an  attempt  was made to load a library at an
			     invalid address.

	      There is insufficient room in the	 address  space	 to  load  the
	      library.

	      The  specified  path  does not exist, or the specified handle is
	      invalid.

	      The specified shared library is currently in use and  cannot  be
	      unloaded.

	      Read or execute permission is denied for the specified library.

WARNINGS
       detaches	 the  library  from the process and frees the memory allocated
       for it, but does not break existing symbolic linkages into the library.
       In  this	 respect,  an  unloaded shared library is much like a block of
       memory deallocated via (see malloc(3C)).

       Some implementations may not, by default, export all symbols defined by
       a  program (instead exporting only those symbols that are imported by a
       shared library seen at link  time).   Therefore	the  option  to	 ld(1)
       should be used when using these routines if the loaded libraries are to
       refer to program symbols.

       All symbol information returned by including  the  name	field,	become
       invalid once the associated library is unloaded by This is also true if
       a library is unloaded by a call to

       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 "Thread Local
       Storage"	 in  dld.so(5)	for  more information.	If a dependent library
       contains TLS, was built with static TLS model and it is not loaded dur‐
       ing  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.

       When  a	routine	 or  flag  is  used  which may not be supported in the
       future, the dynamic loader can display a warning message.  See the sec‐
       tion in dld.sl(5) for further details.

       Future  HP-UX  environments may not support these routines and flags or
       may only support a subset of them.  Instead, they  will	use  the  SVR4
       dynamic	loading API.  Users are encouraged to migrate to the family of
       dynamic linking routines.  See the dlclose(3C), dlerror(3C), dlget(3C),
       dlgetname(3C),  dlmodinfo(3C),  dlopen(3C), and dlsym(3C) man pages for
       more information.

AUTHOR
       shl_load(3X) and related functions were developed by HP.

SEE ALSO
   System Tools
       ld(1)		 invoke the link editor

   Miscellaneous
       dld.so(5)	 dynamic loader
       dlclose(3C)	 unload a shared library previously loaded by
       dlerror(3C)	 print the last error message recorded by
       dlget(3C)	 return information about a loaded module
       dlgetname(3C)	 return the name of the storage containing a load mod‐
			 ule
       dlmodinfo(3C)	 return information about a loaded module
       dlopen(3C)	 load a shared library
       dlsym(3C)	 get the address of a symbol in a shared library

   Texts and Tutorials
       (See the		 option to ld(1))

       (See		 manuals(5) for ordering information)

Integrity Systems Only					       shl_load_ia(3X)
[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