Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
File::ConfigDir(3)    User Contributed Perl Documentation   File::ConfigDir(3)

NAME
       File::ConfigDir - Get directories of configuration files

SYNOPSIS
	   use File::ConfigDir ':ALL';

	   my @cfgdirs = config_dirs();
	   my @appcfgdirs = config_dirs('app');

	   # install support
	   my $site_cfg_dir = (site_cfg_dir())[0];
	   my $vendor_cfg_dir =	(site_cfg_dir()))[0];

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(TM).

       "File::ConfigDir" 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 "/etc" on UNIX(TM) or $ENV{windir} on Windows(TM)) and some network
       configuration in	NFS mapped "/etc/p5-app" or "$ENV{ALLUSERSPROFILE} .
       "\\Application Data\\p5-app"", respectively.

       "File::ConfigDir" has no	"do what I mean" mode -	it's entirely up to
       the user	to pick	the right directory for	each particular	application.

EXPORT
       Every function listed below can be exported, either by name or using
       the tag ":ALL".

SUBROUTINES/METHODS
       All functions can take one optional argument as application specific
       configuration directory.	If given, it will be embedded at the right
       (TM) place of the resulting path.

   system_cfg_dir
       Returns the configuration directory where configuration files of	the
       operating system	resides. For Unices this is "/etc", for	MSWin32	it's
       the value of the	environment variable "%windir%".

   machine_cfg_dir
       Alias for desktop_cfg_dir - deprecated.

   xdg_config_dirs
       Alias for desktop_cfg_dir

   desktop_cfg_dir
       Returns the configuration directory where configuration files of	the
       desktop applications resides. For Unices	this is	"/etc/xdg", for
       MSWin32 it's the	value of the environment variable "%ALLUSERSPROFILE%"
       concatenated with the basename of the environment variable "%APPDATA%".

   core_cfg_dir
       Returns the "etc" directory below $Config{prefix}.

   site_cfg_dir
       Returns the "etc" directory below $Config{sitelib_stem} or the common
       base directory of $Config{sitelib} and $Config{sitebin}.

   vendor_cfg_dir
       Returns the "etc" directory below $Config{vendorlib_stem} or the	common
       base directory of $Config{vendorlib} and	$Config{vendorbin}.

   singleapp_cfg_dir
       Returns the configuration file for stand-alone installed	applications.
       In Unix speak, installing JRE to	"/usr/local/jre-<version>" means there
       is a "/usr/local/jre-<version>/bin/java"	and going from it's directory
       name one	above and into "etc" there is the singleapp_cfg_dir. For a
       Perl module it means, we're assuming that $FindBin::Bin is installed as
       a stand-alone package somewhere,	e.g. into "/usr/pkg" - as recommended
       for pkgsrc <http://www.pkgsrc.org/>.

   vendorapp_cfg_dir
       Returns the configuration file for vendor installed applications. In
       Unix speak, installing bacula to	"/opt/${vendor}" means there is	a
       "/opt/${vendor}/bin/bacula" and going from it's directory name one
       above and into "etc" there is the vendorapp_cfg_dir. For	a Perl module
       it means, we're assuming	that $FindBin::Bin is installed	as a stand-
       alone package somewhere,	e.g. into "/usr/pkg" - as recommended for
       pkgsrc <http://www.pkgsrc.org/>.

   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 "/usr/local/etc" for	Unices.

   locallib_cfg_dir
       Extracts	the "INSTALL_BASE" from	$ENV{PERL_MM_OPT} and returns the
       "etc" directory below it.

   here_cfg_dir
       Returns the path	for the	"etc" directory	below the current working
       directory.

   user_cfg_dir
       Returns the users home folder using File::HomeDir. Without
       File::HomeDir, nothing is returned.

   xdg_config_home
       Returns the user	configuration directory	for desktop applications.  If
       $ENV{XDG_CONFIG_HOME} is	not set, for MSWin32 the value of
       $ENV{APPDATA} is	return and on Unices the ".config" directory in	the
       users home folder. Without File::HomeDir, on Unices the returned	list
       might be	empty.

   config_dirs
	   @cfgdirs = config_dirs();
	   @cfgdirs = config_dirs( 'appname' );

       Tries to	get all	available configuration	directories as described
       above.  Returns those who exists	and are	readable.

   _plug_dir_source
	   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

       Registers more sources to ask for suitable directories to check or
       search for config files.	Each "config_dirs" will	traverse them in
       subsequent invocations, too.

       Returns the number of directory sources in case of success. Returns
       nothing when $dir_src is	not a code ref.

AUTHOR
       Jens Rehsack, "<rehsack at cpan.org>"

BUGS
       Please report any bugs or feature requests to "bug-File-ConfigDir at
       rt.cpan.org", or	through	the web	interface at
       <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=File-ConfigDir>.	 I
       will be notified, and then you'll automatically be notified of progress
       on your bug as I	make changes.

SUPPORT
       You can find documentation for this module with the perldoc command.

	   perldoc File::ConfigDir

       You can also look for information at:

       o   RT: CPAN's request tracker

	   <http://rt.cpan.org/NoAuth/Bugs.html?Dist=File-ConfigDir>

       o   AnnoCPAN: Annotated CPAN documentation

	   <http://annocpan.org/dist/File-ConfigDir>

       o   CPAN	Ratings

	   <http://cpanratings.perl.org/d/File-ConfigDir>

       o   Search CPAN

	   <http://search.cpan.org/dist/File-ConfigDir/>

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 "singleapp_cfg_dir"
       and remind about	"/usr/local/etc".

LICENSE	AND COPYRIGHT
       Copyright 2010-2018 Jens	Rehsack.

       This program is free software; you can redistribute it and/or modify it
       under the terms of either: the GNU General Public License as published
       by the Free Software Foundation;	or the Artistic	License.

       See http://dev.perl.org/licenses/ for more information.

SEE ALSO
       File::HomeDir, File::ShareDir, File::BaseDir (Unices only)

perl v5.32.0			  2018-05-01		    File::ConfigDir(3)

NAME | SYNOPSIS | DESCRIPTION | EXPORT | SUBROUTINES/METHODS | AUTHOR | BUGS | SUPPORT | ACKNOWLEDGEMENTS | LICENSE AND COPYRIGHT | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=File::ConfigDir&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help