lib/relocatable.h

   1 /* Provide relocatable packages.
   2    Copyright (C) 2003, 2005, 2008-2019 Free Software Foundation, Inc.
   3    Written by Bruno Haible <bruno@clisp.org>, 2003.
   4
   5    This program is free software: you can redistribute it and/or modify
   6    it under the terms of the GNU General Public License as published by
   7    the Free Software Foundation; either version 3 of the License, or
   8    (at your option) any later version.
   9
  10    This program 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 General Public License for more details.
  14
  15    You should have received a copy of the GNU 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 #ifdef __cplusplus
  22 extern "C" {
  23 #endif
  24
  25
  26 /* This can be enabled through the configure --enable-relocatable option.  */
  27 #if ENABLE_RELOCATABLE
  28
  29 /* When building a DLL, we must export some functions.  Note that because
  30    this is a private .h file, we don't need to use __declspec(dllimport)
  31    in any case.  */
  32 #if HAVE_VISIBILITY && BUILDING_DLL
  33 # define RELOCATABLE_DLL_EXPORTED __attribute__((__visibility__("default")))
  34 #elif defined _MSC_VER && BUILDING_DLL
  35 # define RELOCATABLE_DLL_EXPORTED __declspec(dllexport)
  36 #else
  37 # define RELOCATABLE_DLL_EXPORTED
  38 #endif
  39
  40 /* Sets the original and the current installation prefix of the package.
  41    Relocation simply replaces a pathname starting with the original prefix
  42    by the corresponding pathname with the current prefix instead.  Both
  43    prefixes should be directory names without trailing slash (i.e. use ""
  44    instead of "/").  */
  45 extern RELOCATABLE_DLL_EXPORTED void
  46        set_relocation_prefix (const char *orig_prefix,
  47                               const char *curr_prefix);
  48
  49 /* Returns the pathname, relocated according to the current installation
  50    directory.
  51    The returned string is either PATHNAME unmodified or a freshly allocated
  52    string that you can free with free() after casting it to 'char *'.  */
  53 extern const char * relocate (const char *pathname);
  54
  55 /* Returns the pathname, relocated according to the current installation
  56    directory.
  57    This function sets *ALLOCATEDP to the allocated memory, or to NULL if
  58    no memory allocation occurs.  So that, after you're done with the return
  59    value, to reclaim allocated memory, you can do: free (*ALLOCATEDP).  */
  60 extern const char * relocate2 (const char *pathname, char **allocatedp);
  61
  62 /* Memory management: relocate() potentially allocates memory, because it has
  63    to construct a fresh pathname.  If this is a problem because your program
  64    calls relocate() frequently or because you want to fix all potential memory
  65    leaks anyway, you have three options:
  66    1) Use this idiom:
  67         const char *pathname = ...;
  68         const char *rel_pathname = relocate (pathname);
  69         ...
  70         if (rel_pathname != pathname)
  71           free ((char *) rel_pathname);
  72    2) Use this idiom:
  73         char *allocated;
  74         const char *rel_pathname = relocate2 (..., &allocated);
  75         ...
  76         free (allocated);
  77    3) Think about caching the result.  */
  78
  79 /* Convenience function:
  80    Computes the current installation prefix, based on the original
  81    installation prefix, the original installation directory of a particular
  82    file, and the current pathname of this file.
  83    Returns it, freshly allocated.  Returns NULL upon failure.  */
  84 extern char * compute_curr_prefix (const char *orig_installprefix,
  85                                    const char *orig_installdir,
  86                                    const char *curr_pathname);
  87
  88 #else
  89
  90 /* By default, we use the hardwired pathnames.  */
  91 #define relocate(pathname) (pathname)
  92 #define relocate2(pathname,allocatedp) (*(allocatedp) = NULL, (pathname))
  93
  94 #endif
  95
  96
  97 #ifdef __cplusplus
  98 }
  99 #endif
 100
 101 #endif /* _RELOCATABLE_H */