.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "File::ConfigDir 3pm" .TH File::ConfigDir 3pm "2022-12-06" "perl v5.36.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" File::ConfigDir \- Get directories of configuration files .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use File::ConfigDir \*(Aq:ALL\*(Aq; \& \& my @cfgdirs = config_dirs(); \& my @appcfgdirs = config_dirs(\*(Aqapp\*(Aq); \& \& # install support \& my $site_cfg_dir = (site_cfg_dir())[0]; \& my $vendor_cfg_dir = (site_cfg_dir()))[0]; .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This module is a helper for installing, reading and finding configuration file locations. It's intended to work in every supported Perl5 environment and will always try to Do The Right Thing(\s-1TM\s0). .PP \&\f(CW\*(C`File::ConfigDir\*(C'\fR is a module to help out when perl modules (especially applications) need to read and store configuration files from more than one location. Writing user configuration is easy thanks to File::HomeDir, but what when the system administrator needs to place some global configuration or there will be system related configuration (in \f(CW\*(C`/etc\*(C'\fR on \s-1UNIX\s0(\s-1TM\s0) or \f(CW$ENV{windir}\fR on Windows(\s-1TM\s0)) and some network configuration in \s-1NFS\s0 mapped \f(CW\*(C`/etc/p5\-app\*(C'\fR or \&\f(CW\*(C`$ENV{ALLUSERSPROFILE} . "\e\eApplication Data\e\ep5\-app"\*(C'\fR, respectively. .PP \&\f(CW\*(C`File::ConfigDir\*(C'\fR has no \*(L"do what I mean\*(R" mode \- it's entirely up to the user to pick the right directory for each particular application. .SH "EXPORT" .IX Header "EXPORT" Every function listed below can be exported, either by name or using the tag \f(CW\*(C`:ALL\*(C'\fR. .SH "SUBROUTINES/METHODS" .IX Header "SUBROUTINES/METHODS" All functions can take one optional argument as application specific configuration directory. If given, it will be embedded at the right (\s-1TM\s0) place of the resulting path. .SS "system_cfg_dir" .IX Subsection "system_cfg_dir" Returns the configuration directory where configuration files of the operating system resides. For Unices this is \f(CW\*(C`/etc\*(C'\fR, for MSWin32 it's the value of the environment variable \f(CW\*(C`%windir%\*(C'\fR. .SS "machine_cfg_dir" .IX Subsection "machine_cfg_dir" Alias for desktop_cfg_dir \- deprecated. .SS "xdg_config_dirs" .IX Subsection "xdg_config_dirs" Alias for desktop_cfg_dir .SS "desktop_cfg_dir" .IX Subsection "desktop_cfg_dir" Returns the configuration directory where configuration files of the desktop applications resides. For Unices this is \f(CW\*(C`/etc/xdg\*(C'\fR, for MSWin32 it's the value of the environment variable \f(CW\*(C`%ALLUSERSPROFILE%\*(C'\fR concatenated with the basename of the environment variable \f(CW\*(C`%APPDATA%\*(C'\fR. .SS "core_cfg_dir" .IX Subsection "core_cfg_dir" Returns the \f(CW\*(C`etc\*(C'\fR directory below \f(CW$Config{prefix}\fR. .SS "site_cfg_dir" .IX Subsection "site_cfg_dir" Returns the \f(CW\*(C`etc\*(C'\fR directory below \f(CW$Config{sitelib_stem}\fR or the common base directory of \f(CW$Config{sitelib}\fR and \f(CW$Config{sitebin}\fR. .SS "vendor_cfg_dir" .IX Subsection "vendor_cfg_dir" Returns the \f(CW\*(C`etc\*(C'\fR directory below \f(CW$Config{vendorlib_stem}\fR or the common base directory of \f(CW$Config{vendorlib}\fR and \f(CW$Config{vendorbin}\fR. .SS "singleapp_cfg_dir" .IX Subsection "singleapp_cfg_dir" Returns the configuration file for stand-alone installed applications. In Unix speak, installing \s-1JRE\s0 to \f(CW\*(C`/usr/local/jre\-\*(C'\fR means there is a \f(CW\*(C`/usr/local/jre\-/bin/java\*(C'\fR and going from it's directory name one above and into \f(CW\*(C`etc\*(C'\fR there is the \fIsingleapp_cfg_dir\fR. For a Perl module it means, we're assuming that \f(CW$FindBin::Bin\fR is installed as a stand-alone package somewhere, e.g. into \f(CW\*(C`/usr/pkg\*(C'\fR \- as recommended for pkgsrc . .SS "vendorapp_cfg_dir" .IX Subsection "vendorapp_cfg_dir" Returns the configuration file for vendor installed applications. In Unix speak, installing bacula to \f(CW\*(C`/opt/${vendor}\*(C'\fR means there is a \f(CW\*(C`/opt/${vendor}/bin/bacula\*(C'\fR and going from it's directory name one above and into \f(CW\*(C`etc\*(C'\fR there is the \fIvendorapp_cfg_dir\fR. For a Perl module it means, we're assuming that \f(CW$FindBin::Bin\fR is installed as a stand-alone package somewhere, e.g. into \f(CW\*(C`/usr/pkg\*(C'\fR \- as recommended for pkgsrc . .SS "local_cfg_dir" .IX Subsection "local_cfg_dir" Returns the configuration directory for distribution independent, 3rd party applications. While this directory doesn't exists for MSWin32, there will be only the path \f(CW\*(C`/usr/local/etc\*(C'\fR for Unices. .SS "locallib_cfg_dir" .IX Subsection "locallib_cfg_dir" Extracts the \f(CW\*(C`INSTALL_BASE\*(C'\fR from \f(CW$ENV{PERL_MM_OPT}\fR and returns the \&\f(CW\*(C`etc\*(C'\fR directory below it. .SS "here_cfg_dir" .IX Subsection "here_cfg_dir" Returns the path for the \f(CW\*(C`etc\*(C'\fR directory below the current working directory. .SS "user_cfg_dir" .IX Subsection "user_cfg_dir" Returns the users home folder using File::HomeDir. Without File::HomeDir, nothing is returned. .SS "xdg_config_home" .IX Subsection "xdg_config_home" Returns the user configuration directory for desktop applications. If \f(CW$ENV{XDG_CONFIG_HOME}\fR is not set, for MSWin32 the value of \f(CW$ENV{APPDATA}\fR is return and on Unices the \f(CW\*(C`.config\*(C'\fR directory in the users home folder. Without File::HomeDir, on Unices the returned list might be empty. .SS "config_dirs" .IX Subsection "config_dirs" .Vb 2 \& @cfgdirs = config_dirs(); \& @cfgdirs = config_dirs( \*(Aqappname\*(Aq ); .Ve .PP Tries to get all available configuration directories as described above. Returns those who exists and are readable. .SS "_plug_dir_source" .IX Subsection "_plug_dir_source" .Vb 2 \& my $dir_src = sub { return _better_config_dir(@_); } \& File::ConfigDir::_plug_dir_source($dir_src); \& \& my $pure_src = sub { return _better_config_plain_dir(@_); } \& File::ConfigDir::_plug_dir_source($pure_src, 1); # see 2nd arg is true .Ve .PP Registers more sources to ask for suitable directories to check or search for config files. Each \*(L"config_dirs\*(R" will traverse them in subsequent invocations, too. .PP Returns the number of directory sources in case of success. Returns nothing when \f(CW$dir_src\fR is not a code ref. .SH "AUTHOR" .IX Header "AUTHOR" Jens Rehsack, \f(CW\*(C`\*(C'\fR .SH "BUGS" .IX Header "BUGS" Please report any bugs or feature requests to \&\f(CW\*(C`bug\-File\-ConfigDir at rt.cpan.org\*(C'\fR, or through the web interface at . I will be notified, and then you'll automatically be notified of progress on your bug as I make changes. .SH "SUPPORT" .IX Header "SUPPORT" You can find documentation for this module with the perldoc command. .PP .Vb 1 \& perldoc File::ConfigDir .Ve .PP You can also look for information at: .IP "\(bu" 4 \&\s-1RT: CPAN\s0's request tracker .Sp .IP "\(bu" 4 AnnoCPAN: Annotated \s-1CPAN\s0 documentation .Sp .IP "\(bu" 4 \&\s-1CPAN\s0 Ratings .Sp .IP "\(bu" 4 Search \s-1CPAN\s0 .Sp .SH "ACKNOWLEDGEMENTS" .IX Header "ACKNOWLEDGEMENTS" Thanks are sent out to Lars Dieckow (daxim) for his suggestion to add support for the Base Directory Specification of the Free Desktop Group. Matthew S. Trout (mst) earns the credit to suggest \f(CW\*(C`singleapp_cfg_dir\*(C'\fR and remind about \f(CW\*(C`/usr/local/etc\*(C'\fR. .SH "LICENSE AND COPYRIGHT" .IX Header "LICENSE AND COPYRIGHT" Copyright 2010\-2018 Jens Rehsack. .PP This program is free software; you can redistribute it and/or modify it under the terms of either: the \s-1GNU\s0 General Public License as published by the Free Software Foundation; or the Artistic License. .PP See http://dev.perl.org/licenses/ for more information. .SH "SEE ALSO" .IX Header "SEE ALSO" File::HomeDir, File::ShareDir, File::BaseDir (Unices only)