1  /* Provide relocatable packages.
       2     Copyright (C) 2003, 2005, 2008-2023 Free Software Foundation, Inc.
       3     Written by Bruno Haible <bruno@clisp.org>, 2003.
       4  
       5     This file is free software: you can redistribute it and/or modify
       6     it under the terms of the GNU Lesser General Public License as
       7     published by the Free Software Foundation; either version 2.1 of the
       8     License, or (at your option) any later version.
       9  
      10     This file is distributed in the hope that it will be useful,
      11     but WITHOUT ANY WARRANTY; without even the implied warranty of
      12     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
      13     GNU Lesser General Public License for more details.
      14  
      15     You should have received a copy of the GNU Lesser General Public License
      16     along with this program.  If not, see <https://www.gnu.org/licenses/>.  */
      17  
      18  #ifndef _RELOCATABLE_H
      19  #define _RELOCATABLE_H
      20  
      21  /* This file uses _GL_ATTRIBUTE_MALLOC, HAVE_VISIBILITY.  */
      22  #if !_GL_CONFIG_H_INCLUDED
      23   #error "Please include config.h first."
      24  #endif
      25  
      26  #include <stdlib.h>
      27  
      28  #ifdef __cplusplus
      29  extern "C" {
      30  #endif
      31  
      32  
      33  /* This can be enabled through the configure --enable-relocatable option.  */
      34  #if ENABLE_RELOCATABLE
      35  
      36  /* When building a shared library, we must export some functions.
      37     Note that because this is a private .h file, we don't need to use
      38     __declspec(dllimport) in any case.  */
      39  #if HAVE_VISIBILITY && BUILDING_DLL
      40  # define RELOCATABLE_SHLIB_EXPORTED __attribute__((__visibility__("default")))
      41  #elif defined _MSC_VER && BUILDING_DLL
      42  /* When building with MSVC, exporting a symbol means that the object file
      43     contains a "linker directive" of the form /EXPORT:symbol.  This can be
      44     inspected through the "objdump -s --section=.drectve FILE" or
      45     "dumpbin /directives FILE" commands.
      46     The symbols from this file should be exported if and only if the object
      47     file gets included in a DLL.  Libtool, on Windows platforms, defines
      48     the C macro DLL_EXPORT (together with PIC) when compiling for a shared
      49     library (called DLL under Windows) and does not define it when compiling
      50     an object file meant to be linked statically into some executable.  */
      51  # if defined DLL_EXPORT
      52  #  define RELOCATABLE_SHLIB_EXPORTED __declspec(dllexport)
      53  # else
      54  #  define RELOCATABLE_SHLIB_EXPORTED
      55  # endif
      56  #else
      57  # define RELOCATABLE_SHLIB_EXPORTED
      58  #endif
      59  
      60  /* Sets the original and the current installation prefix of the package.
      61     Relocation simply replaces a pathname starting with the original prefix
      62     by the corresponding pathname with the current prefix instead.  Both
      63     prefixes should be directory names without trailing slash (i.e. use ""
      64     instead of "/").  */
      65  extern RELOCATABLE_SHLIB_EXPORTED void
      66         set_relocation_prefix (const char *orig_prefix,
      67                                const char *curr_prefix);
      68  
      69  /* Returns the pathname, relocated according to the current installation
      70     directory.
      71     The returned string is either PATHNAME unmodified or a freshly allocated
      72     string that you can free with free() after casting it to 'char *'.  */
      73  extern const char * relocate (const char *pathname);
      74  
      75  /* Returns the pathname, relocated according to the current installation
      76     directory.
      77     This function sets *ALLOCATEDP to the allocated memory, or to NULL if
      78     no memory allocation occurs.  So that, after you're done with the return
      79     value, to reclaim allocated memory, you can do: free (*ALLOCATEDP).  */
      80  extern const char * relocate2 (const char *pathname, char **allocatedp);
      81  
      82  /* Memory management: relocate() potentially allocates memory, because it has
      83     to construct a fresh pathname.  If this is a problem because your program
      84     calls relocate() frequently or because you want to fix all potential memory
      85     leaks anyway, you have three options:
      86     1) Use this idiom:
      87          const char *pathname = ...;
      88          const char *rel_pathname = relocate (pathname);
      89          ...
      90          if (rel_pathname != pathname)
      91            free ((char *) rel_pathname);
      92     2) Use this idiom:
      93          char *allocated;
      94          const char *rel_pathname = relocate2 (..., &allocated);
      95          ...
      96          free (allocated);
      97     3) Think about caching the result.  */
      98  
      99  /* Convenience function:
     100     Computes the current installation prefix, based on the original
     101     installation prefix, the original installation directory of a particular
     102     file, and the current pathname of this file.
     103     Returns it, freshly allocated.  Returns NULL upon failure.  */
     104  extern char * compute_curr_prefix (const char *orig_installprefix,
     105                                     const char *orig_installdir,
     106                                     const char *curr_pathname)
     107    _GL_ATTRIBUTE_MALLOC _GL_ATTRIBUTE_DEALLOC_FREE;
     108  
     109  #else
     110  
     111  /* By default, we use the hardwired pathnames.  */
     112  #define relocate(pathname) (pathname)
     113  #define relocate2(pathname,allocatedp) (*(allocatedp) = NULL, (pathname))
     114  
     115  #endif
     116  
     117  
     118  #ifdef __cplusplus
     119  }
     120  #endif
     121  
     122  #endif /* _RELOCATABLE_H */