1File::ConfigDir(3) User Contributed Perl Documentation File::ConfigDir(3)
2
3
4
6 File::ConfigDir - Get directories of configuration files
7
9 use File::ConfigDir ':ALL';
10
11 my @cfgdirs = config_dirs();
12 my @appcfgdirs = config_dirs('app');
13
14 # install support
15 my $site_cfg_dir = (site_cfg_dir())[0];
16 my $vendor_cfg_dir = (site_cfg_dir()))[0];
17
19 This module is a helper for installing, reading and finding
20 configuration file locations. It's intended to work in every supported
21 Perl5 environment and will always try to Do The Right Thing(TM).
22
23 "File::ConfigDir" is a module to help out when perl modules (especially
24 applications) need to read and store configuration files from more than
25 one location. Writing user configuration is easy thanks to
26 File::HomeDir, but what when the system administrator needs to place
27 some global configuration or there will be system related configuration
28 (in "/etc" on UNIX(TM) or $ENV{windir} on Windows(TM)) and some network
29 configuration in NFS mapped "/etc/p5-app" or "$ENV{ALLUSERSPROFILE} .
30 "\\Application Data\\p5-app"", respectively.
31
32 "File::ConfigDir" has no "do what I mean" mode - it's entirely up to
33 the user to pick the right directory for each particular application.
34
36 Every function listed below can be exported, either by name or using
37 the tag ":ALL".
38
40 All functions can take one optional argument as application specific
41 configuration directory. If given, it will be embedded at the right
42 (TM) place of the resulting path.
43
44 system_cfg_dir
45 Returns the configuration directory where configuration files of the
46 operating system resides. For Unices this is "/etc", for MSWin32 it's
47 the value of the environment variable "%windir%".
48
49 machine_cfg_dir
50 Alias for desktop_cfg_dir - deprecated.
51
52 xdg_config_dirs
53 Alias for desktop_cfg_dir
54
55 desktop_cfg_dir
56 Returns the configuration directory where configuration files of the
57 desktop applications resides. For Unices this is "/etc/xdg", for
58 MSWin32 it's the value of the environment variable "%ALLUSERSPROFILE%"
59 concatenated with the basename of the environment variable "%APPDATA%".
60
61 core_cfg_dir
62 Returns the "etc" directory below $Config{prefix}.
63
64 site_cfg_dir
65 Returns the "etc" directory below $Config{sitelib_stem} or the common
66 base directory of $Config{sitelib} and $Config{sitebin}.
67
68 vendor_cfg_dir
69 Returns the "etc" directory below $Config{vendorlib_stem} or the common
70 base directory of $Config{vendorlib} and $Config{vendorbin}.
71
72 singleapp_cfg_dir
73 Returns the configuration file for stand-alone installed applications.
74 In Unix speak, installing JRE to "/usr/local/jre-<version>" means there
75 is a "/usr/local/jre-<version>/bin/java" and going from it's directory
76 name one above and into "etc" there is the singleapp_cfg_dir. For a
77 Perl module it means, we're assuming that $FindBin::Bin is installed as
78 a stand-alone package somewhere, e.g. into "/usr/pkg" - as recommended
79 for pkgsrc <http://www.pkgsrc.org/>.
80
81 vendorapp_cfg_dir
82 Returns the configuration file for vendor installed applications. In
83 Unix speak, installing bacula to "/opt/${vendor}" means there is a
84 "/opt/${vendor}/bin/bacula" and going from it's directory name one
85 above and into "etc" there is the vendorapp_cfg_dir. For a Perl module
86 it means, we're assuming that $FindBin::Bin is installed as a stand-
87 alone package somewhere, e.g. into "/usr/pkg" - as recommended for
88 pkgsrc <http://www.pkgsrc.org/>.
89
90 local_cfg_dir
91 Returns the configuration directory for distribution independent, 3rd
92 party applications. While this directory doesn't exists for MSWin32,
93 there will be only the path "/usr/local/etc" for Unices.
94
95 locallib_cfg_dir
96 Extracts the "INSTALL_BASE" from $ENV{PERL_MM_OPT} and returns the
97 "etc" directory below it.
98
99 here_cfg_dir
100 Returns the path for the "etc" directory below the current working
101 directory.
102
103 user_cfg_dir
104 Returns the users home folder using File::HomeDir. Without
105 File::HomeDir, nothing is returned.
106
107 xdg_config_home
108 Returns the user configuration directory for desktop applications. If
109 $ENV{XDG_CONFIG_HOME} is not set, for MSWin32 the value of
110 $ENV{APPDATA} is return and on Unices the ".config" directory in the
111 users home folder. Without File::HomeDir, on Unices the returned list
112 might be empty.
113
114 config_dirs
115 @cfgdirs = config_dirs();
116 @cfgdirs = config_dirs( 'appname' );
117
118 Tries to get all available configuration directories as described
119 above. Returns those who exists and are readable.
120
121 _plug_dir_source
122 my $dir_src = sub { return _better_config_dir(@_); }
123 File::ConfigDir::_plug_dir_source($dir_src);
124
125 my $pure_src = sub { return _better_config_plain_dir(@_); }
126 File::ConfigDir::_plug_dir_source($pure_src, 1); # see 2nd arg is true
127
128 Registers more sources to ask for suitable directories to check or
129 search for config files. Each "config_dirs" will traverse them in
130 subsequent invocations, too.
131
132 Returns the number of directory sources in case of success. Returns
133 nothing when $dir_src is not a code ref.
134
136 Jens Rehsack, "<rehsack at cpan.org>"
137
139 Please report any bugs or feature requests to "bug-File-ConfigDir at
140 rt.cpan.org", or through the web interface at
141 <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=File-ConfigDir>. I
142 will be notified, and then you'll automatically be notified of progress
143 on your bug as I make changes.
144
146 You can find documentation for this module with the perldoc command.
147
148 perldoc File::ConfigDir
149
150 You can also look for information at:
151
152 • RT: CPAN's request tracker
153
154 <http://rt.cpan.org/NoAuth/Bugs.html?Dist=File-ConfigDir>
155
156 • AnnoCPAN: Annotated CPAN documentation
157
158 <http://annocpan.org/dist/File-ConfigDir>
159
160 • CPAN Ratings
161
162 <http://cpanratings.perl.org/d/File-ConfigDir>
163
164 • Search CPAN
165
166 <http://search.cpan.org/dist/File-ConfigDir/>
167
169 Thanks are sent out to Lars Dieckow (daxim) for his suggestion to add
170 support for the Base Directory Specification of the Free Desktop Group.
171 Matthew S. Trout (mst) earns the credit to suggest "singleapp_cfg_dir"
172 and remind about "/usr/local/etc".
173
175 Copyright 2010-2018 Jens Rehsack.
176
177 This program is free software; you can redistribute it and/or modify it
178 under the terms of either: the GNU General Public License as published
179 by the Free Software Foundation; or the Artistic License.
180
181 See http://dev.perl.org/licenses/ for more information.
182
184 File::HomeDir, File::ShareDir, File::BaseDir (Unices only)
185
186
187
188perl v5.36.0 2022-07-22 File::ConfigDir(3)