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