common/path.h

   1 ///////////////////////////////////////////////////////////////////////////////
   2 // Copyright (c) 2000-2015 Ericsson Telecom AB
   3 // All rights reserved. This program and the accompanying materials
   4 // are made available under the terms of the Eclipse Public License v1.0
   5 // which accompanies this distribution, and is available at
   6 // http://www.eclipse.org/legal/epl-v10.html
   7 ///////////////////////////////////////////////////////////////////////////////
   8 #ifndef _Common_path_H
   9 #define _Common_path_H
  10
  11 #include "memory.h"
  12
  13 #ifdef __cplusplus
  14 extern "C" {
  15 #endif
  16
  17 /** Error handling function that shall be provided by the application
  18  * that uses this library. The meaning of argument(s) is the same as in
  19  * \c printf() */
  20 extern void path_error(const char *fmt, ...)
  21     __attribute__ ((__format__ (__printf__, 1, 2)));
  22
  23 /** Returns the current working directory of the process in canonical form.
  24  * The string returned shall be deallocated by the caller using \a Free(). */
  25 extern expstring_t get_working_dir(void);
  26
  27 /** Sets the current working directory of the process to \a new_dir.
  28  * Returns 0 on success, function \a path_error() is called and non-zero value
  29  * is returned in case of any error. If \a new_dir is NULL the unsuccessful
  30  * status code is simply returned, \a path_error() is not called. */
  31 extern int set_working_dir(const char *new_dir);
  32
  33 enum path_status_t {
  34     PS_FILE, /**< the pathname is a file */
  35     PS_DIRECTORY, /**< the pathname is a directory */
  36     PS_NONEXISTENT /**< the pathname does not exist */
  37 };
  38
  39 /** Returns the status of \a path_name. Symbolic links are followed.
  40  * In case of any problem other than non-existent file or directory
  41  * function \a path_error() is called. */
  42 extern enum path_status_t get_path_status(const char *path_name);
  43
  44 /** Returns the directory part of \a path_name. It is assumed that the
  45  * argument points to a file. NULL pointer is returned if \a path_name is a
  46  * simple file name without any slash. The string returned shall be
  47  * deallocated by the caller using \a Free(). */
  48 extern expstring_t get_dir_from_path(const char *path_name);
  49
  50 /** Returns the file name part of \a path_name. It is assumed that the
  51  * argument points to a file. NULL pointer is returned if \a path_name ends
  52  * with a slash. The string returned shall be deallocated by the caller using
  53  * \a Free(). */
  54 extern expstring_t get_file_from_path(const char *path_name);
  55
  56 /** Concatenates the given directory \a dir_name and file name \a file_name
  57  * to get a path name. If either \a dir_name or \a file_name is NULL or empty
  58  * string the resulting path name will contain only the other component. The
  59  * slash is inserted between \a dir_name and \a file_name only when necessary.
  60  * The string returned shall be deallocated by the caller using \a Free(). */
  61 extern expstring_t compose_path_name(const char *dir_name,
  62     const char *file_name);
  63
  64 /** Converts \a dir_name, which is relative to \a base_dir, to an absolute
  65  * directory path. If \a base_dir is NULL the current working directory of
  66  * the process is used. It is assumed that both \a dir_name and \a base_dir
  67  * are existing directories. The returned directory name is in canonical form
  68  * (i.e. symlinks in it are resolved). NULL pointer returned in case of error.
  69  * The string returned shall be deallocated by the caller using \a Free().
  70  * Note: The working directory of the current process might change during the
  71  * function call, but it is restored before the function returns. */
  72 extern expstring_t get_absolute_dir(const char *dir_name, const char *base_dir);
  73
  74 /** Converts \a dir_name to a relative path name based on \a working_dir. If
  75  * \a working_dir is NULL the current working directory of the process is used.
  76  * It is assumed that both \a dir_name and \a working_dir are existing
  77  * directories. NULL pointer is returned in case of any error.
  78  * The string returned shall be deallocated by the caller using \a Free().*/
  79 extern expstring_t get_relative_dir(const char *dir_name,
  80     const char *working_dir);
  81
  82 #ifdef __cplusplus
  83 } /* extern "C" */
  84 #endif
  85
  86 #endif /* _Common_path_H */