common/path.h

   1 /******************************************************************************
   2  * Copyright (c) 2000-2016 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  * Contributors:
   9  *   Balasko, Jeno
  10  *   Raduly, Csaba
  11  *   Szabo, Bence Janos
  12  *   Szabo, Janos Zoltan – initial implementation
  13  *
  14  ******************************************************************************/
  15 #ifndef _Common_path_H
  16 #define _Common_path_H
  17
  18 #include "memory.h"
  19
  20 #ifdef __cplusplus
  21 extern "C" {
  22 #endif
  23
  24 /** Error handling function that shall be provided by the application
  25  * that uses this library. The meaning of argument(s) is the same as in
  26  * \c printf() */
  27 extern void path_error(const char *fmt, ...)
  28     __attribute__ ((__format__ (__printf__, 1, 2)));
  29
  30 /** Returns the current working directory of the process in canonical form.
  31  * The string returned shall be deallocated by the caller using \a Free(). */
  32 extern expstring_t get_working_dir(void);
  33
  34 /** Sets the current working directory of the process to \a new_dir.
  35  * Returns 0 on success, function \a path_error() is called and non-zero value
  36  * is returned in case of any error. If \a new_dir is NULL the unsuccessful
  37  * status code is simply returned, \a path_error() is not called. */
  38 extern int set_working_dir(const char *new_dir);
  39
  40 enum path_status_t {
  41     PS_FILE, /**< the pathname is a file */
  42     PS_DIRECTORY, /**< the pathname is a directory */
  43     PS_NONEXISTENT /**< the pathname does not exist */
  44 };
  45
  46 /** Returns the status of \a path_name. Symbolic links are followed.
  47  * In case of any problem other than non-existent file or directory
  48  * function \a path_error() is called. */
  49 extern enum path_status_t get_path_status(const char *path_name);
  50
  51 /** Returns the directory part of \a path_name. It is assumed that the
  52  * argument points to a file. NULL pointer is returned if \a path_name is a
  53  * simple file name without any slash. The string returned shall be
  54  * deallocated by the caller using \a Free(). */
  55 extern expstring_t get_dir_from_path(const char *path_name);
  56
  57 /** Returns the file name part of \a path_name. It is assumed that the
  58  * argument points to a file. NULL pointer is returned if \a path_name ends
  59  * with a slash. The string returned shall be deallocated by the caller using
  60  * \a Free(). */
  61 extern expstring_t get_file_from_path(const char *path_name);
  62
  63 /** Concatenates the given directory \a dir_name and file name \a file_name
  64  * to get a path name. If either \a dir_name or \a file_name is NULL or empty
  65  * string the resulting path name will contain only the other component. The
  66  * slash is inserted between \a dir_name and \a file_name only when necessary.
  67  * The string returned shall be deallocated by the caller using \a Free(). */
  68 extern expstring_t compose_path_name(const char *dir_name,
  69     const char *file_name);
  70
  71 /** Converts \a dir_name, which is relative to \a base_dir, to an absolute
  72  * directory path. If \a base_dir is NULL the current working directory of
  73  * the process is used. It is assumed that both \a dir_name and \a base_dir
  74  * are existing directories. The returned directory name is in canonical form
  75  * (i.e. symlinks in it are resolved). NULL pointer returned in case of error.
  76  * The string returned shall be deallocated by the caller using \a Free().
  77  * Note: The working directory of the current process might change during the
  78  * function call, but it is restored before the function returns.
  79  * If the with_error is true, then it won't sign error when set_working_dir
  80  * is called.*/
  81 extern expstring_t get_absolute_dir(const char *dir_name, const char *base_dir, const int with_error);
  82
  83 /** Converts \a dir_name to a relative path name based on \a working_dir. If
  84  * \a working_dir is NULL the current working directory of the process is used.
  85  * It is assumed that both \a dir_name and \a working_dir are existing
  86  * directories. NULL pointer is returned in case of any error.
  87  * The string returned shall be deallocated by the caller using \a Free().*/
  88 extern expstring_t get_relative_dir(const char *dir_name,
  89     const char *working_dir);
  90
  91 #ifdef __cplusplus
  92 } /* extern "C" */
  93 #endif
  94
  95 #endif /* _Common_path_H */