etcFiles.H
Go to the documentation of this file.
1 /*---------------------------------------------------------------------------*\
2  ========= |
3  \\ / F ield | OpenFOAM: The Open Source CFD Toolbox
4  \\ / O peration |
5  \\ / A nd | www.openfoam.com
6  \\/ M anipulation |
7 -------------------------------------------------------------------------------
8  Copyright (C) 2016 OpenFOAM Foundation
9  Copyright (C) 2018 OpenCFD Ltd.
10 -------------------------------------------------------------------------------
11 License
12  This file is part of OpenFOAM.
13 
14  OpenFOAM is free software: you can redistribute it and/or modify it
15  under the terms of the GNU General Public License as published by
16  the Free Software Foundation, either version 3 of the License, or
17  (at your option) any later version.
18 
19  OpenFOAM is distributed in the hope that it will be useful, but WITHOUT
20  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
21  FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
22  for more details.
23 
24  You should have received a copy of the GNU General Public License
25  along with OpenFOAM. If not, see <http://www.gnu.org/licenses/>.
26 
27 InNamespace
28  Foam
29 
30 Description
31  Functions to search 'etc' directories for configuration files etc.
32 
33 SourceFiles
34  etcFiles.C
35 
36 \*---------------------------------------------------------------------------*/
37 
38 #ifndef etcFiles_H
39 #define etcFiles_H
40 
41 #include "fileNameList.H"
42 
43 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
44 
45 namespace Foam
46 {
47 
48 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
49 
50 //- The etc search directories in the normal search order.
51 //
52 // \param test false to disable the default test for directory existence.
53 //
54 // \return The list of directories
55 fileNameList etcDirs(bool test=true);
56 
57 
58 //- Search for files or directories from user/group/other etc locations.
59 //
60 // The search hierarchy corresponds to that of the \c foamEtcFile script,
61 // which allows for version-specific and version-independent files.
62 //
63 // -# \b user settings (\c location=0700)
64 // - ~/.OpenFOAM/{PROJECT_API}
65 // - ~/.OpenFOAM/
66 // -# \b group settings (\c location=0070)
67 // - $WM_PROJECT_SITE/{PROJECT_API}/etc/
68 // - $WM_PROJECT_SITE/etc/
69 // -# \b other (shipped) settings (\c location=0007)
70 // - $WM_PROJECT_DIR/etc/
71 //
72 // Where {PROJECT_API} corresponds to the foamVersion::api value.
73 // When \c \$WM_PROJECT_SITE is unset, uses \c $WM_PROJECT_DIR/site
74 //
75 // \param name The entry to search for. For a FILE search,
76 // this should be non-empty. For a DIRECTORY search or a general
77 // (UNDEFINED) search, this can be an empty string.
78 // \param location The search locations as a numerical mode.
79 // The default (0777) searches user/group/other locations.
80 // \param typeRequired restricts the search to the specified type.
81 // The default (UNDEFINED) accepts FILE or DIRECTORY entries.
82 // \param findFirst Optionally stop after locating the first entry.
83 //
84 // \return The list of full paths of all the matching files or directories
85 // or an empty list if the name cannot be resolved.
87 (
88  const fileName& name,
89  unsigned short location=0777,
90  const fileName::Type typeRequired = fileName::Type::UNDEFINED,
91  const bool findFirst=false
92 );
93 
94 
95 //- Search for directories from user/group/other etc locations.
96 // The search hierarchy corresponds to that of the \c foamEtcFile script,
97 // which allows for version-specific and version-independent files.
98 //
99 // This function corresponds to using Foam::findEtcEntries()
100 // with (DIRECTORY) for the type required.
101 //
102 // \param name The directory to search for. This can be an empty string.
103 // \param location The search locations as a numerical mode.
104 // The default (0777) searches user/group/other locations.
105 // \param findFirst Optionally stop after locating the first entry.
106 //
107 // \return The list of full paths of all the matching directories or
108 // an empty list if the name cannot be found.
110 (
111  const fileName& name,
112  unsigned short location=0777,
113  const bool findFirst=false
114 );
115 
116 //- Search for files from user/group/other etc locations.
117 // The search hierarchy corresponds to that of the \c foamEtcFile script,
118 // which allows for version-specific and version-independent files.
119 //
120 // This function corresponds to using Foam::findEtcEntries()
121 // with (FILE) for the type required, but has an additional
122 // check for mandatory files.
123 //
124 // \param name The file to search for. If this is an empty string,
125 // nothing will be matched.
126 // \param mandatory Abort if the mandatory file cannot be found.
127 // \param location The search locations as a numerical mode.
128 // The default (0777) searches user/group/other locations.
129 // \param findFirst Optionally stop after locating the first entry.
130 //
131 // \return The list of full paths of all the matching files or
132 // an empty list if the name cannot be found.
134 (
135  const fileName& name,
136  const bool mandatory=false,
137  unsigned short location=0777,
138  const bool findFirst=false
139 );
140 
141 
142 //- Search for a single FILE or DIRECTORY within the etc directories
143 //
144 // \param name The entry to search for. For a FILE search,
145 // this should be non-empty. For a DIRECTORY search or a general
146 // (UNDEFINED) search, this can be an empty string.
147 // \param location The search locations as a numerical mode.
148 // The default (0777) searches user/group/other locations.
149 // \param typeRequired restricts the search to the specified type.
150 // The default (UNDEFINED) accepts FILE or DIRECTORY entries.
151 //
152 // \return The full path name of the first entry found in the
153 // search hierarchy or an empty fileName if the name cannot be found.
154 //
155 // \sa Foam::findEtcEntries()
156 fileName findEtcEntry
157 (
158  const fileName& name,
159  unsigned short location=0777,
160  const fileName::Type typeRequired = fileName::Type::UNDEFINED
161 );
162 
163 
164 //- Search for a single FILE within the etc directories
165 //
166 // \return The full path name of the first directory found in the
167 // search hierarchy or an empty fileName if the name cannot be found.
168 //
169 // \sa Foam::findEtcEntries(), Foam::findEtcDirs()
170 fileName findEtcDir
171 (
172  const fileName& name,
173  unsigned short location=0777
174 );
175 
176 //- Search for a single FILE within the etc directories
177 //
178 // \return The full path name of the first file found in the
179 // search hierarchy or an empty fileName if the name cannot be found.
180 //
181 // \sa Foam::findEtcEntries(), Foam::findEtcFiles()
182 fileName findEtcFile
183 (
184  const fileName& name,
185  const bool mandatory=false,
186  unsigned short location=0777
187 );
188 
189 
190 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
191 
192 } // End namespace Foam
193 
194 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
195 
196 #endif
197 
198 // ************************************************************************* //
Foam::etcDirs
fileNameList etcDirs(bool test=true)
The etc search directories in the normal search order.
Definition: etcFiles.C:243
Foam::findEtcDirs
fileNameList findEtcDirs(const fileName &name, unsigned short location=0777, const bool findFirst=false)
Search for directories from user/group/other etc locations.
Definition: etcFiles.C:381
Foam::findEtcEntry
fileName findEtcEntry(const fileName &name, unsigned short location=0777, const fileName::Type typeRequired=fileName::Type::UNDEFINED)
Search for a single FILE or DIRECTORY within the etc directories.
Definition: etcFiles.C:415
Foam::fileName::Type
Type
Enumerations to handle directory entry types.
Definition: fileName.H:76
Foam::findEtcFile
fileName findEtcFile(const fileName &name, const bool mandatory=false, unsigned short location=0777)
Search for a single FILE within the etc directories.
Definition: etcFiles.C:446
Foam::findEtcDir
fileName findEtcDir(const fileName &name, unsigned short location=0777)
Search for a single FILE within the etc directories.
Definition: etcFiles.C:436
Foam::name
word name(const complex &c)
Return string representation of complex.
Definition: complex.C:76
Foam::findEtcFiles
fileNameList findEtcFiles(const fileName &name, const bool mandatory=false, unsigned short location=0777, const bool findFirst=false)
Search for files from user/group/other etc locations.
Definition: etcFiles.C:392
Foam
Namespace for OpenFOAM.
Definition: atmBoundaryLayer.C:33
Foam::fileNameList
List< fileName > fileNameList
A List of fileNames.
Definition: fileNameList.H:58
fileNameList.H
Foam::findEtcEntries
fileNameList findEtcEntries(const fileName &name, unsigned short location=0777, const fileName::Type typeRequired=fileName::Type::UNDEFINED, const bool findFirst=false)
Search for files or directories from user/group/other etc locations.
Definition: etcFiles.C:280