Mercurial > gnulib

annotate lib/relocatable.h @ 40057:b06060465f09

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
maint: Run 'make update-copyright'
author Paul Eggert <eggert@cs.ucla.edu>
date Tue, 01 Jan 2019 00:25:11 +0100
parents 10eb9086bea0
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
8265
20006894dae4 Infrastructure for relocatable installation, from GNU gettext.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
1 /* Provide relocatable packages.
40057
b06060465f09 maint: Run 'make update-copyright'
Paul Eggert <eggert@cs.ucla.edu>
parents: 19484
diff changeset
2 Copyright (C) 2003, 2005, 2008-2019 Free Software Foundation, Inc.
8265
20006894dae4 Infrastructure for relocatable installation, from GNU gettext.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
3 Written by Bruno Haible <bruno@clisp.org>, 2003.
20006894dae4 Infrastructure for relocatable installation, from GNU gettext.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
4
14858
dd10bbc31f53 Copyright: Use LGPL 2.1 instead of LGPL 2.0.
Bruno Haible <bruno@clisp.org>
parents: 14079
diff changeset
5 This program is free software: you can redistribute it and/or modify
19021
3f47303d5d8e relocatable: Make the license on the sources the GPL.
Reuben Thomas <rrt@sc3d.org>
parents: 18917
diff changeset
6 it under the terms of the GNU General Public License as published by
3f47303d5d8e relocatable: Make the license on the sources the GPL.
Reuben Thomas <rrt@sc3d.org>
parents: 18917
diff changeset
7 the Free Software Foundation; either version 3 of the License, or
14858
dd10bbc31f53 Copyright: Use LGPL 2.1 instead of LGPL 2.0.
Bruno Haible <bruno@clisp.org>
parents: 14079
diff changeset
8 (at your option) any later version.
8265
20006894dae4 Infrastructure for relocatable installation, from GNU gettext.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
9
20006894dae4 Infrastructure for relocatable installation, from GNU gettext.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
10 This program is distributed in the hope that it will be useful,
20006894dae4 Infrastructure for relocatable installation, from GNU gettext.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
11 but WITHOUT ANY WARRANTY; without even the implied warranty of
14858
dd10bbc31f53 Copyright: Use LGPL 2.1 instead of LGPL 2.0.
Bruno Haible <bruno@clisp.org>
parents: 14079
diff changeset
12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19021
3f47303d5d8e relocatable: Make the license on the sources the GPL.
Reuben Thomas <rrt@sc3d.org>
parents: 18917
diff changeset
13 GNU General Public License for more details.
8265
20006894dae4 Infrastructure for relocatable installation, from GNU gettext.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
14
19021
3f47303d5d8e relocatable: Make the license on the sources the GPL.
Reuben Thomas <rrt@sc3d.org>
parents: 18917
diff changeset
15 You should have received a copy of the GNU General Public License
19190
9759915b2aca all: prefer https: URLs
Paul Eggert <eggert@cs.ucla.edu>
parents: 19021
diff changeset
16 along with this program. If not, see <https://www.gnu.org/licenses/>. */
8265
20006894dae4 Infrastructure for relocatable installation, from GNU gettext.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
17
20006894dae4 Infrastructure for relocatable installation, from GNU gettext.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
18 #ifndef _RELOCATABLE_H
20006894dae4 Infrastructure for relocatable installation, from GNU gettext.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
19 #define _RELOCATABLE_H
20006894dae4 Infrastructure for relocatable installation, from GNU gettext.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
20
20006894dae4 Infrastructure for relocatable installation, from GNU gettext.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
21 #ifdef __cplusplus
20006894dae4 Infrastructure for relocatable installation, from GNU gettext.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
22 extern "C" {
20006894dae4 Infrastructure for relocatable installation, from GNU gettext.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
23 #endif
20006894dae4 Infrastructure for relocatable installation, from GNU gettext.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
24
20006894dae4 Infrastructure for relocatable installation, from GNU gettext.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
25
20006894dae4 Infrastructure for relocatable installation, from GNU gettext.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
26 /* This can be enabled through the configure --enable-relocatable option. */
20006894dae4 Infrastructure for relocatable installation, from GNU gettext.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
27 #if ENABLE_RELOCATABLE
20006894dae4 Infrastructure for relocatable installation, from GNU gettext.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
28
20006894dae4 Infrastructure for relocatable installation, from GNU gettext.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
29 /* When building a DLL, we must export some functions. Note that because
20006894dae4 Infrastructure for relocatable installation, from GNU gettext.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
30 this is a private .h file, we don't need to use __declspec(dllimport)
20006894dae4 Infrastructure for relocatable installation, from GNU gettext.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
31 in any case. */
20006894dae4 Infrastructure for relocatable installation, from GNU gettext.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
32 #if HAVE_VISIBILITY && BUILDING_DLL
20006894dae4 Infrastructure for relocatable installation, from GNU gettext.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
33 # define RELOCATABLE_DLL_EXPORTED __attribute__((__visibility__("default")))
20006894dae4 Infrastructure for relocatable installation, from GNU gettext.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
34 #elif defined _MSC_VER && BUILDING_DLL
20006894dae4 Infrastructure for relocatable installation, from GNU gettext.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
35 # define RELOCATABLE_DLL_EXPORTED __declspec(dllexport)
20006894dae4 Infrastructure for relocatable installation, from GNU gettext.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
36 #else
20006894dae4 Infrastructure for relocatable installation, from GNU gettext.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
37 # define RELOCATABLE_DLL_EXPORTED
20006894dae4 Infrastructure for relocatable installation, from GNU gettext.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
38 #endif
20006894dae4 Infrastructure for relocatable installation, from GNU gettext.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
39
20006894dae4 Infrastructure for relocatable installation, from GNU gettext.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
40 /* Sets the original and the current installation prefix of the package.
20006894dae4 Infrastructure for relocatable installation, from GNU gettext.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
41 Relocation simply replaces a pathname starting with the original prefix
20006894dae4 Infrastructure for relocatable installation, from GNU gettext.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
42 by the corresponding pathname with the current prefix instead. Both
20006894dae4 Infrastructure for relocatable installation, from GNU gettext.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
43 prefixes should be directory names without trailing slash (i.e. use ""
20006894dae4 Infrastructure for relocatable installation, from GNU gettext.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
44 instead of "/"). */
20006894dae4 Infrastructure for relocatable installation, from GNU gettext.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
45 extern RELOCATABLE_DLL_EXPORTED void
20006894dae4 Infrastructure for relocatable installation, from GNU gettext.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
46 set_relocation_prefix (const char *orig_prefix,
12421
e8d2c6fc33ad Use spaces for indentation, not tabs.
Bruno Haible <bruno@clisp.org>
parents: 9602
diff changeset
47 const char *curr_prefix);
8265
20006894dae4 Infrastructure for relocatable installation, from GNU gettext.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
48
20006894dae4 Infrastructure for relocatable installation, from GNU gettext.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
49 /* Returns the pathname, relocated according to the current installation
9599
895b5215b578 Make it possible to avoid all memory leaks when calling relocate().
Bruno Haible <bruno@clisp.org>
parents: 9576
diff changeset
50 directory.
895b5215b578 Make it possible to avoid all memory leaks when calling relocate().
Bruno Haible <bruno@clisp.org>
parents: 9576
diff changeset
51 The returned string is either PATHNAME unmodified or a freshly allocated
895b5215b578 Make it possible to avoid all memory leaks when calling relocate().
Bruno Haible <bruno@clisp.org>
parents: 9576
diff changeset
52 string that you can free with free() after casting it to 'char *'. */
8265
20006894dae4 Infrastructure for relocatable installation, from GNU gettext.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
53 extern const char * relocate (const char *pathname);
20006894dae4 Infrastructure for relocatable installation, from GNU gettext.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
54
18917
ba6683fbd710 relocate: Make it easier to reclaim allocated memory.
Bruno Haible <bruno@clisp.org>
parents: 18626
diff changeset
55 /* Returns the pathname, relocated according to the current installation
ba6683fbd710 relocate: Make it easier to reclaim allocated memory.
Bruno Haible <bruno@clisp.org>
parents: 18626
diff changeset
56 directory.
ba6683fbd710 relocate: Make it easier to reclaim allocated memory.
Bruno Haible <bruno@clisp.org>
parents: 18626
diff changeset
57 This function sets *ALLOCATEDP to the allocated memory, or to NULL if
ba6683fbd710 relocate: Make it easier to reclaim allocated memory.
Bruno Haible <bruno@clisp.org>
parents: 18626
diff changeset
58 no memory allocation occurs. So that, after you're done with the return
ba6683fbd710 relocate: Make it easier to reclaim allocated memory.
Bruno Haible <bruno@clisp.org>
parents: 18626
diff changeset
59 value, to reclaim allocated memory, you can do: free (*ALLOCATEDP). */
ba6683fbd710 relocate: Make it easier to reclaim allocated memory.
Bruno Haible <bruno@clisp.org>
parents: 18626
diff changeset
60 extern const char * relocate2 (const char *pathname, char **allocatedp);
ba6683fbd710 relocate: Make it easier to reclaim allocated memory.
Bruno Haible <bruno@clisp.org>
parents: 18626
diff changeset
61
9602
7a4db0f92545 Fix a comment.
Eric Blake <ebb9@byu.net>
parents: 9599
diff changeset
62 /* Memory management: relocate() potentially allocates memory, because it has
7a4db0f92545 Fix a comment.
Eric Blake <ebb9@byu.net>
parents: 9599
diff changeset
63 to construct a fresh pathname. If this is a problem because your program
18917
ba6683fbd710 relocate: Make it easier to reclaim allocated memory.
Bruno Haible <bruno@clisp.org>
parents: 18626
diff changeset
64 calls relocate() frequently or because you want to fix all potential memory
ba6683fbd710 relocate: Make it easier to reclaim allocated memory.
Bruno Haible <bruno@clisp.org>
parents: 18626
diff changeset
65 leaks anyway, you have three options:
ba6683fbd710 relocate: Make it easier to reclaim allocated memory.
Bruno Haible <bruno@clisp.org>
parents: 18626
diff changeset
66 1) Use this idiom:
ba6683fbd710 relocate: Make it easier to reclaim allocated memory.
Bruno Haible <bruno@clisp.org>
parents: 18626
diff changeset
67 const char *pathname = ...;
ba6683fbd710 relocate: Make it easier to reclaim allocated memory.
Bruno Haible <bruno@clisp.org>
parents: 18626
diff changeset
68 const char *rel_pathname = relocate (pathname);
ba6683fbd710 relocate: Make it easier to reclaim allocated memory.
Bruno Haible <bruno@clisp.org>
parents: 18626
diff changeset
69 ...
ba6683fbd710 relocate: Make it easier to reclaim allocated memory.
Bruno Haible <bruno@clisp.org>
parents: 18626
diff changeset
70 if (rel_pathname != pathname)
ba6683fbd710 relocate: Make it easier to reclaim allocated memory.
Bruno Haible <bruno@clisp.org>
parents: 18626
diff changeset
71 free ((char *) rel_pathname);
ba6683fbd710 relocate: Make it easier to reclaim allocated memory.
Bruno Haible <bruno@clisp.org>
parents: 18626
diff changeset
72 2) Use this idiom:
ba6683fbd710 relocate: Make it easier to reclaim allocated memory.
Bruno Haible <bruno@clisp.org>
parents: 18626
diff changeset
73 char *allocated;
ba6683fbd710 relocate: Make it easier to reclaim allocated memory.
Bruno Haible <bruno@clisp.org>
parents: 18626
diff changeset
74 const char *rel_pathname = relocate2 (..., &allocated);
ba6683fbd710 relocate: Make it easier to reclaim allocated memory.
Bruno Haible <bruno@clisp.org>
parents: 18626
diff changeset
75 ...
ba6683fbd710 relocate: Make it easier to reclaim allocated memory.
Bruno Haible <bruno@clisp.org>
parents: 18626
diff changeset
76 free (allocated);
ba6683fbd710 relocate: Make it easier to reclaim allocated memory.
Bruno Haible <bruno@clisp.org>
parents: 18626
diff changeset
77 3) Think about caching the result. */
8265
20006894dae4 Infrastructure for relocatable installation, from GNU gettext.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
78
20006894dae4 Infrastructure for relocatable installation, from GNU gettext.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
79 /* Convenience function:
20006894dae4 Infrastructure for relocatable installation, from GNU gettext.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
80 Computes the current installation prefix, based on the original
20006894dae4 Infrastructure for relocatable installation, from GNU gettext.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
81 installation prefix, the original installation directory of a particular
9576
8cae100b8cd1 Improve memory cleanup in 'relocatable' module.
Bruno Haible <bruno@clisp.org>
parents: 8265
diff changeset
82 file, and the current pathname of this file.
8cae100b8cd1 Improve memory cleanup in 'relocatable' module.
Bruno Haible <bruno@clisp.org>
parents: 8265
diff changeset
83 Returns it, freshly allocated. Returns NULL upon failure. */
8cae100b8cd1 Improve memory cleanup in 'relocatable' module.
Bruno Haible <bruno@clisp.org>
parents: 8265
diff changeset
84 extern char * compute_curr_prefix (const char *orig_installprefix,
12421
e8d2c6fc33ad Use spaces for indentation, not tabs.
Bruno Haible <bruno@clisp.org>
parents: 9602
diff changeset
85 const char *orig_installdir,
e8d2c6fc33ad Use spaces for indentation, not tabs.
Bruno Haible <bruno@clisp.org>
parents: 9602
diff changeset
86 const char *curr_pathname);
8265
20006894dae4 Infrastructure for relocatable installation, from GNU gettext.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
87
20006894dae4 Infrastructure for relocatable installation, from GNU gettext.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
88 #else
20006894dae4 Infrastructure for relocatable installation, from GNU gettext.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
89
20006894dae4 Infrastructure for relocatable installation, from GNU gettext.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
90 /* By default, we use the hardwired pathnames. */
20006894dae4 Infrastructure for relocatable installation, from GNU gettext.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
91 #define relocate(pathname) (pathname)
18917
ba6683fbd710 relocate: Make it easier to reclaim allocated memory.
Bruno Haible <bruno@clisp.org>
parents: 18626
diff changeset
92 #define relocate2(pathname,allocatedp) (*(allocatedp) = NULL, (pathname))
8265
20006894dae4 Infrastructure for relocatable installation, from GNU gettext.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
93
20006894dae4 Infrastructure for relocatable installation, from GNU gettext.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
94 #endif
20006894dae4 Infrastructure for relocatable installation, from GNU gettext.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
95
20006894dae4 Infrastructure for relocatable installation, from GNU gettext.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
96
20006894dae4 Infrastructure for relocatable installation, from GNU gettext.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
97 #ifdef __cplusplus
20006894dae4 Infrastructure for relocatable installation, from GNU gettext.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
98 }
20006894dae4 Infrastructure for relocatable installation, from GNU gettext.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
99 #endif
20006894dae4 Infrastructure for relocatable installation, from GNU gettext.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
100
20006894dae4 Infrastructure for relocatable installation, from GNU gettext.
Bruno Haible <bruno@clisp.org>
parents:
diff changeset
101 #endif /* _RELOCATABLE_H */