lib/relocatable.h

   1 /* Provide relocatable packages.
   2    Copyright (C) 2003, 2005, 2008-2024 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 */