---
name: "Config::Find"
section: "3pm"
platform: "linux"
package: "libconfig-find-perl"
version: "0.31-3"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/Config::Find"
---

# Config::Find(3pm)

Find configuration files in the native OS fashion

## NAME

Config::Find - Find configuration files in the native OS fashion

## SYNOPSIS

```
  use Config::Find;
  my $filename=Config::Find->find;
  ...
  my $fn_foo=Config::Find->find( name => 'my_app/foo',
                                 mode => 'write',
                                 scope => 'user' );
  my $fn_bar=Config::Find->find( names => [qw(my_app/bar appbar)] );
  my $fh=Config::Find->open( name => 'foo',
                             scope => 'global',
                             mode => 'w' )
  my $fn=Config::Find->install( 'original/config/file.conf',
                                name => 'foo' );
  my $fn=Config::Find->find( file => $opt_c,
                             name => foo );
```

## ABSTRACT

Config::Find searches for configuration files using OS dependent heuristics.

## DESCRIPTION

Every OS has different rules for configuration files placement, this module allows one to easily find and create your app configuration files following those rules.

Config::Find references configuration files by the application name or by the application name and the configuration file name when the app uses several application files, i.e `"emacs"`, `"profile"`, `"apache/httpd"`, `"apache/ssl"`.

By default the `$0` value is used to generate the configuration file name. To define it explicitly the keywords `"name"` or `"names"` have to be used:

- name =\> "name" or "app/file"

  picks the first configuration file matching that name.

- names =\> \[qw(foo bar foo/bar)\]

  picks the first configuration file matching any of the names passed.

Alternatively, the exact position for the file can be specified with the `"file"` keyword:

- file =\> "/config/file/name.conf"

  explicit position of the configuration file.

  If undef is passed this entry is ignored and the search for the configuration file continues with the appropriate OS rules. This allows for:

  ```
    use Config::Find;
    use Getopt::Std;
    our $opt_c;
    getopts('c:');
    my $fn=Config::Find->find(file => $opt_c)
  ```

Methods in this package also accept the optional arguments `"scope"` and `"mode"`:

- scope =\> "user" or "global"

  Configuration files can be private to the application user or global to the OS, i.e. in unix there is the global `"/etc/profile"` and the user `"~/.profile"`.

- mode =\> "read" or "write"

  In `"read"` mode already existent file names are returned, in `"write"` mode the file names point to where the configuration file has to be stored.

### METHODS

All the methods in this package are class methods (you don't need an object to call them).

- $fn=Config::Find-\>find(%opts)

  returns the name of the configuration file.

- $fh=Config::Find-\>open(%opts)

  returns a open file handle for the configuration file. In write mode, the file and any nonexistent parent directories are created.

- $fn=Config::Find-\>install($original, %opts)

  copies a configuration file to a convenient place.

## BUGS

Some Win32 operating systems are not completely implemented and default to inferior modes, but hey, this is a work in progress!!!

Contributions, bug reports, feedback and any kind of comments are welcome.

## SEE ALSO

Config::Find::Unix, Config::Find::Win32 for descriptions of the heuristics used to find the configuration files.

Config::Find::Any for information about adding support for a new OS.

Config::Auto give me the idea for this module.

## AUTHOR

Salvador Fandiño García, \<sfandino@yahoo.com\>

## CONTRIBUTORS

Barbie, \<barbie@missbarbell.co.uk\> (some bug fixes and documentation)

## COPYRIGHT AND LICENSE

Copyright 2003-2015 by Salvador Fandiño García (sfandino@yahoo.com) Copyright 2015 by Barbie (barbie@missbarbell.co.uk)

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.