/usr/include/glibmm-2.4/glibmm/miscutils.h is in libglibmm-2.4-dev 2.42.0-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 | // -*- c++ -*-
#ifndef _GLIBMM_MISCUTILS_H
#define _GLIBMM_MISCUTILS_H
/* $Id$ */
/* Copyright (C) 2002 The gtkmm Development Team
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
* version 2.1 of the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
* License along with this library; if not, write to the Free
* Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
*/
#include <glibmm/arrayhandle.h>
#include <glibmm/ustring.h>
namespace Glib
{
/** @defgroup MiscUtils Miscellaneous Utility Functions
* Miscellaneous Utility Functions -- a selection of portable utility functions.
* @{
*/
/** Gets a human-readable name for the application,
* as set by Glib::set_application_name().
* This name should be localized if possible, and is intended for display to
* the user. Contrast with Glib::get_prgname(), which gets a non-localized
* name. If Glib::set_application_name() has not been called, returns the
* result of Glib::get_prgname() (which may be empty if Glib::set_prgname()
* has also not been called).
*
* @return Human-readable application name. May return <tt>""</tt>.
*/
Glib::ustring get_application_name();
/** Sets a human-readable name for the application.
* This name should be localized if possible, and is intended for display to
* the user. Contrast with Glib::set_prgname(), which sets a non-localized
* name. Glib::set_prgname() will be called automatically by
* <tt>gtk_init()</tt>, but Glib::set_application_name() will not.
*
* Note that for thread safety reasons, this function can only be called once.
*
* The application name will be used in contexts such as error messages,
* or when displaying an application's name in the task list.
*
* @param application_name Localized name of the application.
*/
void set_application_name(const Glib::ustring& application_name);
/** Gets the name of the program.
* If you are using GDK or GTK+ the program name is set in <tt>gdk_init()</tt>,
* which is called by <tt>gtk_init()</tt>. The program name is found by taking
* the last component of <tt>argv[0]</tt>.
* @return The name of the program.
*/
std::string get_prgname();
/** Sets the name of the program.
* @param prgname The name of the program.
*/
void set_prgname(const std::string& prgname);
/** Returns the value of an environment variable. The name and value
* are in the GLib file name encoding. On Unix, this means the actual
* bytes which might or might not be in some consistent character set
* and encoding. On Windows, it is in UTF-8. On Windows, in case the
* environment variable's value contains references to other
* environment variables, they are expanded.
*
* @param variable The environment variable to get.
* @retval found <tt>true</tt> Whether the environment variable has been found.
* @return The value of the environment variable, or <tt>""</tt> if not found.
*/
std::string getenv(const std::string& variable, bool& found);
/** Returns the value of an environment variable. The name and value
* are in the GLib file name encoding. On Unix, this means the actual
* bytes which might or might not be in some consistent character set
* and encoding. On Windows, it is in UTF-8. On Windows, in case the
* environment variable's value contains references to other
* environment variables, they are expanded.
*
* @param variable The environment variable to get.
* @return The value of the environment variable, or <tt>""</tt> if not found.
*/
std::string getenv(const std::string& variable);
/** Sets an environment variable. Both the variable's name and value
* should be in the GLib file name encoding. On Unix, this means that
* they can be any sequence of bytes. On Windows, they should be in
* UTF-8.
*
* Note that on some systems, when variables are overwritten, the memory
* used for the previous variables and its value isn't reclaimed.
*
* @param variable The environment variable to set. It must not contain '='.
* @param value The value to which the variable should be set.
* @param overwrite Whether to change the variable if it already exists.
* @result false if the environment variable couldn't be set.
*/
bool setenv(const std::string& variable, const std::string& value, bool overwrite = true);
/** Removes an environment variable from the environment.
*
* Note that on some systems, when variables are overwritten, the memory
* used for the previous variables and its value isn't reclaimed.
* Furthermore, this function can't be guaranteed to operate in a
* threadsafe way.
*
* @param variable: the environment variable to remove. It must not contain '='.
**/
void unsetenv(const std::string& variable);
/** Gets the names of all variables set in the environment.
*
* Programs that want to be portable to Windows should typically use this
* function and getenv() instead of using the environ array from the C library
* directly. On Windows, the strings in the environ array are in system
* codepage encoding, while in most of the typical use cases for environment
* variables in GLib-using programs you want the UTF-8 encoding that this
* function and getenv() provide.
*
* @return Array of environment names (The generic ArrayHandle will be
* implicitly converted to any STL compatible container type).
*/
Glib::ArrayHandle<std::string> listenv();
/** Gets the user name of the current user.
* @return The name of the current user.
*/
std::string get_user_name();
/** Gets the real name of the user.
* This usually comes from the user's entry in the <tt>passwd</tt> file.
* @return The user's real name.
*/
std::string get_real_name();
/** Gets the current user's home directory.
* @return The current user's home directory or an empty string if not defined.
*/
std::string get_home_dir();
/** Gets the directory to use for temporary files.
* This is found from inspecting the environment variables <tt>TMPDIR</tt>,
* <tt>TMP</tt>, and <tt>TEMP</tt> in that order. If none of those are defined
* <tt>"/tmp"</tt> is returned on UNIX and <tt>"C:\\"</tt> on Windows.
* @return The directory to use for temporary files.
*/
std::string get_tmp_dir();
/** Gets the current directory.
* @return The current directory.
*/
std::string get_current_dir();
//TODO: We could create a C++ enum to wrap the C GUserDirectory enum,
//but we would have to either be very careful, or define the enum
//values in terms of the C enums anyway.
/** Returns the full path of a special directory using its logical id.
*
* On Unix this is done using the XDG special user directories.
*
* Depending on the platform, the user might be able to change the path
* of the special directory without requiring the session to restart; GLib
* will not reflect any change once the special directories are loaded.
*
* Return value: the path to the specified special directory.
* @param directory Te logical id of special directory
*
* @newin{2,14}
*/
std::string get_user_special_dir(GUserDirectory directory);
/** Returns a base directory in which to access application data such as icons
* that is customized for a particular user.
*
* On UNIX platforms this is determined using the mechanisms described in the
* XDG Base Directory Specification
*
* @newin{2,14}
*/
std::string get_user_data_dir();
/** Returns a base directory in which to store user-specific application
* configuration information such as user preferences and settings.
*
* On UNIX platforms this is determined using the mechanisms described in the
* XDG Base Directory Specification
*
* @newin{2,14}
*/
std::string get_user_config_dir();
/** Returns an ordered list of base directories in which to access system-wide application data.
* On Unix platforms this is determined using the mechanisms described in the XDG Base Directory Specification.
*
* @newin{2,18}
*/
std::vector<std::string> get_system_data_dirs();
/** Returns an ordered list of base directories in which to access system-wide configuration information.
* On Unix platforms this is determined using the mechanisms described in the XDG Base Directory Specification.
*
* @newin{2,18}
*/
std::vector<std::string> get_system_config_dirs();
/** Returns a base directory in which to store non-essential, cached data
* specific to particular user.
*
* On UNIX platforms this is determined using the mechanisms described in the
* XDG Base Directory Specification
*
* @newin{2,14}
*/
std::string get_user_cache_dir();
/** Returns @c true if the given @a filename is an absolute file name, i.e.\ it
* contains a full path from the root directory such as <tt>"/usr/local"</tt>
* on UNIX or <tt>"C:\\windows"</tt> on Windows systems.
* @param filename A file name.
* @return Whether @a filename is an absolute path.
*/
bool path_is_absolute(const std::string& filename);
/** Returns the remaining part of @a filename after the root component,
* i.e.\ after the <tt>"/"</tt> on UNIX or <tt>"C:\\"</tt> on Windows.
* If @a filename is not an absolute path, <tt>""</tt> will be returned.
* @param filename A file name.
* @return The file name without the root component, or <tt>""</tt>.
*/
std::string path_skip_root(const std::string& filename);
/** Gets the name of the file without any leading directory components.
* @param filename The name of the file.
* @return The name of the file without any leading directory components.
*/
std::string path_get_basename(const std::string& filename);
/** Gets the directory components of a file name.
* If the file name has no directory components <tt>"."</tt> is returned.
* @param filename The name of the file.
* @return The directory components of the file.
*/
std::string path_get_dirname(const std::string& filename);
/** Creates a filename from a series of elements using the correct
* separator for filenames.
* This function behaves identically to Glib::build_path(G_DIR_SEPARATOR_S,
* elements). No attempt is made to force the resulting filename to be an
* absolute path. If the first element is a relative path, the result will
* be a relative path.
* @param elements A container holding the elements of the path to build.
* Any STL compatible container type is accepted.
* @return The resulting path.
*/
std::string build_filename(const Glib::ArrayHandle<std::string>& elements);
/** Creates a filename from two elements using the correct separator for filenames.
* No attempt is made to force the resulting filename to be an absolute path.
* If the first element is a relative path, the result will be a relative path.
* @param elem1 First path element.
* @param elem2 Second path element.
* @return The resulting path.
*/
std::string build_filename(const std::string& elem1, const std::string& elem2);
/** Creates a filename from three elements using the correct separator for filenames.
* No attempt is made to force the resulting filename to be an absolute path.
* If the first element is a relative path, the result will be a relative path.
* @param elem1 First path element.
* @param elem2 Second path element.
* @param elem3 Third path element.
* @return The resulting path.
*
* @newin{2,28}
*/
std::string build_filename(const std::string& elem1, const std::string& elem2,
const std::string& elem3);
/** Creates a filename from four elements using the correct separator for filenames.
* No attempt is made to force the resulting filename to be an absolute path.
* If the first element is a relative path, the result will be a relative path.
* @param elem1 First path element.
* @param elem2 Second path element.
* @param elem3 Third path element.
* @param elem4 Fourth path element.
* @return The resulting path.
*
* @newin{2,28}
*/
std::string build_filename(const std::string& elem1, const std::string& elem2,
const std::string& elem3, const std::string& elem4);
/** Creates a filename from five elements using the correct separator for filenames.
* No attempt is made to force the resulting filename to be an absolute path.
* If the first element is a relative path, the result will be a relative path.
* @param elem1 First path element.
* @param elem2 Second path element.
* @param elem3 Third path element.
* @param elem4 Fourth path element.
* @param elem5 Fifth path element.
* @return The resulting path.
*/
std::string build_filename(const std::string& elem1, const std::string& elem2,
const std::string& elem3, const std::string& elem4,
const std::string& elem5);
/** Creates a filename from six elements using the correct separator for filenames.
* No attempt is made to force the resulting filename to be an absolute path.
* If the first element is a relative path, the result will be a relative path.
* @param elem1 First path element.
* @param elem2 Second path element.
* @param elem3 Third path element.
* @param elem4 Fourth path element.
* @param elem5 Fifth path element.
* @param elem6 Sixth path element.
* @return The resulting path.
*
* @newin{2,28}
*/
std::string build_filename(const std::string& elem1, const std::string& elem2,
const std::string& elem3, const std::string& elem4,
const std::string& elem5, const std::string& elem6);
/** Creates a filename from seven elements using the correct separator for filenames.
* No attempt is made to force the resulting filename to be an absolute path.
* If the first element is a relative path, the result will be a relative path.
* @param elem1 First path element.
* @param elem2 Second path element.
* @param elem3 Third path element.
* @param elem4 Fourth path element.
* @param elem5 Fifth path element.
* @param elem6 Sixth path element.
* @param elem7 Seventh path element.
* @return The resulting path.
*
* @newin{2,28}
*/
std::string build_filename(const std::string& elem1, const std::string& elem2,
const std::string& elem3, const std::string& elem4,
const std::string& elem5, const std::string& elem6,
const std::string& elem7);
/** Creates a filename from eight elements using the correct separator for filenames.
* No attempt is made to force the resulting filename to be an absolute path.
* If the first element is a relative path, the result will be a relative path.
* @param elem1 First path element.
* @param elem2 Second path element.
* @param elem3 Third path element.
* @param elem4 Fourth path element.
* @param elem5 Fifth path element.
* @param elem6 Sixth path element.
* @param elem7 Seventh path element.
* @param elem8 Eighth path element.
* @return The resulting path.
*
* @newin{2,28}
*/
std::string build_filename(const std::string& elem1, const std::string& elem2,
const std::string& elem3, const std::string& elem4,
const std::string& elem5, const std::string& elem6,
const std::string& elem7, const std::string& elem8);
/** Creates a filename from nine elements using the correct separator for filenames.
* No attempt is made to force the resulting filename to be an absolute path.
* If the first element is a relative path, the result will be a relative path.
* @param elem1 First path element.
* @param elem2 Second path element.
* @param elem3 Third path element.
* @param elem4 Fourth path element.
* @param elem5 Fifth path element.
* @param elem6 Sixth path element.
* @param elem7 Seventh path element.
* @param elem8 Eighth path element.
* @param elem9 Ninth path element.
* @return The resulting path.
*
* @newin{2,28}
*/
std::string build_filename(const std::string& elem1, const std::string& elem2,
const std::string& elem3, const std::string& elem4,
const std::string& elem5, const std::string& elem6,
const std::string& elem7, const std::string& elem8,
const std::string& elem9);
/** Creates a path from a series of elements using @a separator as the
* separator between elements.
*
* At the boundary between two elements, any trailing occurrences of
* @a separator in the first element, or leading occurrences of @a separator
* in the second element are removed and exactly one copy of the separator is
* inserted.
*
* Empty elements are ignored.
*
* The number of leading copies of the separator on the result is
* the same as the number of leading copies of the separator on
* the first non-empty element.
*
* The number of trailing copies of the separator on the result is the same
* as the number of trailing copies of the separator on the last non-empty
* element. (Determination of the number of trailing copies is done without
* stripping leading copies, so if the separator is <tt>"ABA"</tt>,
* <tt>"ABABA"</tt> has 1 trailing copy.)
*
* However, if there is only a single non-empty element, and there
* are no characters in that element not part of the leading or
* trailing separators, then the result is exactly the original value
* of that element.
*
* Other than for determination of the number of leading and trailing
* copies of the separator, elements consisting only of copies
* of the separator are ignored.
*
* @param separator A string used to separate the elements of the path.
* @param elements A container holding the elements of the path to build.
* Any STL compatible container type is accepted.
* @return The resulting path.
*/
std::string build_path(const std::string& separator,
const Glib::ArrayHandle<std::string>& elements);
/** Locates the first executable named @a program in the user's path, in the
* same way that <tt>execvp()</tt> would locate it.
* Returns a string with the absolute path name, or <tt>""</tt> if the program
* is not found in the path. If @a program is already an absolute path,
* returns a copy of @a program if @a program exists and is executable, and
* <tt>""</tt> otherwise.
*
* On Windows, if @a program does not have a file type suffix, tries to append
* the suffixes in the <tt>PATHEXT</tt> environment variable (if that doesn't
* exist, the suffixes .com, .exe, and .bat) in turn, and then look for the
* resulting file name in the same way as CreateProcess() would. This means
* first in the directory where the program was loaded from, then in the
* current directory, then in the Windows 32-bit system directory, then in the
* Windows directory, and finally in the directories in the <tt>PATH</tt>
* environment variable. If the program is found, the return value contains
* the full name including the type suffix.
*
* @param program A program name.
* @return An absolute path, or <tt>""</tt>.
*/
std::string find_program_in_path(const std::string& program);
/** @} group MiscUtils */
} // namespace Glib
#endif /* _GLIBMM_FILEUTILS_H */
|