dynload               package:rdyncall               R Documentation

_L_o_w-_l_e_v_e_l _l_o_a_d_i_n_g _a_n_d _u_n_l_o_a_d _o_f _s_h_a_r_e_d _l_i_b_r_a_r_i_e_s

_D_e_s_c_r_i_p_t_i_o_n:

     Low-level functions to load and unload shared libraries and to
     resolve symbols.

_U_s_a_g_e:

     .dynload(libname, auto.unload=TRUE)
     .dynsym(libhandle, symname, protect.lib=TRUE)
     .dynunload(libhandle)

_A_r_g_u_m_e_n_t_s:

 libname: A character string specifying the library file in short,
          relative- or absolute-path form.

libhandle: An external pointer representing a handle to an open
          library.

 symname: A character string specifying the symbolic name to lookup.

auto.unload: A logical indicating if a finalizer should be registered
          that will automatically unload the library

protect.lib: A logical indicating if the external pointer representing
          the symbol will protect the lib object

_D_e_t_a_i_l_s:

     The function '.dynload' searches for a library specified by
     'libname'.  It loads the library to the run-time process and
     returns its 'libhandle' (library handle)  as an external pointer.
     Function pointers can be resolved using '.dynsym' to lookup a
     symbol given by 'symname'  in a library specified by 'libhandle'. 
     '.dynunload' can be used to unload a library from the run-time
     process.

_V_a_l_u_e:

     '.dynload' returns an external pointer 'libhandle' on success.
     Otherwise NULL is returned, if the library is not found or the
     linkage failed. '.dynfind' returns an external pointer 'address'
     on sucess. Otherwise NULL is returned, if the address was invalid
     or the symbol has not been found. '.dynunload' always returns
     NULL.

_S_h_a_r_e_d _l_i_b_r_a_r_y:

     Shared libraries are single files that contain compiled code, data
     and meta-information. The code and data can be loaded and mapped
     to a process at run-time once. Operating system platforms have
     slightly different schemes for naming,  searching and linking
     options.

       *Platform*                            *Binary format*  *File Extension*
       Linux, BSD derivates and Sun Solaris  ELF format       'lib*.so'
       Darwin / Apple Mac OS X               Mach-O format    'lib*.dylib'
       Microsoft Windows                     PE format        '*.DLL'

_L_i_b_r_a_r_y _s_e_a_r_c_h _o_n _P_o_s_i_x _p_l_a_t_f_o_r_m_s (_L_i_n_u_x,_B_S_D,_S_u_n _S_o_l_a_r_i_s):

     These search rules will only be applied to path names that do not
     contain an embedded '/'. 

        *  If the 'LD_LIBRARY_PATH' environment variable is defined to
           contain a colon-separated list of directories, then these
           are searched.

        *  The cache file '/etc/ld.so.cache' is checked to see whether
           it contains an entry for filename.

        *  The directories '/lib' and '/usr/lib' are searched (in that
           order).

_L_i_b_r_a_r_y _s_e_a_r_c_h _o_n _D_a_r_w_i_n (_M_a_c _O_S _X) _p_l_a_t_f_o_r_m_s:

     dlopen() searches for a compatible Mach-O file in the directories
     specified by a set of environment variables and the process's
     current working directory.  When set, the environment variables
     must contain  a colon-separated list of directory paths, which can
     be absolute or relative to the current working directory. The
     environment variables are LD_LIBRARY_PATH, DYLD_LIBRARY_PATH, and
     DYLD_FALLBACK_LIBRARY_PATH.  The first two variables have no
     default value. The default value of DYLD_FALLBACK_LIBRARY_PATH is
     $HOME/lib;/usr/local/lib;/usr/lib.  dlopen() searches the
     directories specified in the environment variables in the order
     they are listed.

     When path doesn't contain a slash character (i.e. it is just a
     leaf name), dlopen() searches the fol-lowing following lowing the
     following until it finds a compatible Mach-O file:
     $LD_LIBRARY_PATH, $DYLD_LIBRARY_PATH, current working directory,
     $DYLD_FALLBACK_LIBRARY_PATH.

     When path contains a slash (i.e. a full path or a partial path)
     dlopen() searches the following the following until it finds a
     compatible Mach-O file: $DYLD_LIBRARY_PATH (with leaf name from
     path ), cur-rent current rent working directory (for partial
     paths), $DYLD_FALLBACK_LIBRARY_PATH (with leaf name from path ).

_L_i_b_r_a_r_y _s_e_a_r_c_h _o_n _M_i_c_r_o_s_o_f_t _W_i_n_d_o_w_s _p_l_a_t_f_o_r_m_s:

     If no file name extension is specified in the lpFileName
     parameter, the default library extension  .dll is appended.
     However, the file name string can include a trailing point
     character (.) to  indicate that the module name has no extension.
     When no path is specified, the function searches  for loaded
     modules whose base name matches the base name of the module to be
     loaded.  If the name matches, the load succeeds. Otherwise, the
     function searches for the file in the  following sequence:



        *  The directory from which the application loaded. 

        *  The current directory. 

        *  The system directory. Use the GetSystemDirectory function to
           get the path of this directory.

        *  The 16-bit system directory. There is no function that
           obtains the path of this directory, but it is searched.
           Windows Me/98/95:  This directory does not exist.

        *  The Windows directory. Use the GetWindowsDirectory function
           to get the path of this directory. 

        *  The directories that are listed in the PATH environment
           variable. 

     Windows Server 2003, Windows XP SP1:  The default value of
     HKLM\System\CurrentControlSet\Control\Session
     Manager\SafeDllSearchMode is 1 (current directory is searched
     after the system and Windows directories).

     Windows XP:  If HKLM\System\CurrentControlSet\Control\Session
     Manager\SafeDllSearchMode is 1, the current directory is searched
     after the system and Windows directories, but before the
     directories in the PATH environment variable. The default value is
     0 (current directory is searched before the system and Windows
     directories).

     The first directory searched is the one directory containing the
     image file used to create the calling process. Doing this allows
     private dynamic-link library (DLL) files associated with a process
     to be found without adding the process's installed directory to
     the PATH environment variable.

     The search path can be altered using the SetDllDirectory function.
     This solution is recommended instead of using SetCurrentDirectory
     or hard-coding the full path to the DLL.

     If a path is specified and there is a redirection file for the
     application, the function searches for the module in the
     application's directory. If the module exists in the application's
     directory, the LoadLibrary function ignores the specified path and
     loads the module from the application's directory. If the module
     does not exist in the application's directory, LoadLibrary loads
     the module from the specified directory. For more information, see
     Dynamic Link Library Redirection.

