src/path.h

   1 /* $Id: path.h 23517 2007-08-07 17:07:59Z umoeller $ */
   2 /** @file
   3  * innotek Portable Runtime - RTPath Internal header.
   4  */
   5
   6 /*
   7  * Copyright (C) 2006-2007 innotek GmbH
   8  *
   9  * This file is part of VirtualBox Open Source Edition (OSE), as
  10  * available from http://www.virtualbox.org. This file is free software;
  11  * you can redistribute it and/or modify it under the terms of the GNU
  12  * General Public License as published by the Free Software Foundation,
  13  * in version 2 as it comes in the "COPYING" file of the VirtualBox OSE
  14  * distribution. VirtualBox OSE is distributed in the hope that it will
  15  * be useful, but WITHOUT ANY WARRANTY of any kind.
  16  */
  17
  18 #ifndef ___internal_path_h
  19 #define ___internal_path_h
  20
  21 #include "cdefs.h"
  22 #include "types.h"
  23 #include "const_defines.h"
  24
  25 /** @name RTPathRename, RTDirRename & RTFileRename flags.
  26  * @{ */
  27 /** This will replace attempt any target which isn't a directory. */
  28 #define RTPATHRENAME_FLAGS_REPLACE      RT_BIT(0)
  29 /** @} */
  30
  31 /** @def RTPATH_IS_SLASH
  32  * Checks if a character is a slash.
  33  *
  34  * @returns true if it's a slash and false if not.
  35  * @returns @param      ch      Char to check.
  36  */
  37 #if defined(RT_OS_OS2) || defined(RT_OS_WINDOWS)
  38 # define RTPATH_IS_SLASH(ch)    ( (ch) == '\\' || (ch) == '/' )
  39 #else
  40 # define RTPATH_IS_SLASH(ch)    ( (ch) == '/' )
  41 #endif
  42
  43 /** @def RTPATH_SLASH
  44  * The prefered slash character.
  45  *
  46  * @remark IPRT will always accept unix slashes. So, normally you would
  47  *         never have to use this define.
  48  */
  49 #if defined(RT_OS_OS2) || defined(RT_OS_WINDOWS)
  50 # define RTPATH_SLASH       '\\'
  51 #else
  52 # define RTPATH_SLASH       '/'
  53 #endif
  54
  55
  56 int rtPathPosixRename(const char *pszSrc, const char *pszDst, unsigned fRename, RTFMODE fFileType);
  57 int rtPathWin32MoveRename(const char *pszSrc, const char *pszDst, uint32_t fFlags, RTFMODE fFileType);
  58
  59
  60 /**
  61  * Converts a path from IPRT to native representation.
  62  *
  63  * This may involve querying filesystems what codeset they
  64  * speak and so forth.
  65  *
  66  * @returns IPRT status code.
  67  * @param   ppszNativePath  Where to store the pointer to the native path.
  68  *                          Free by calling rtPathFreeHost(). NULL on failure.
  69  * @param   pszPath         The path to convert.
  70  * @remark  This function is not available on hosts using something else than byte seqences as names. (eg win32)
  71  */
  72 int rtPathToNative(char **ppszNativePath, const char *pszPath);
  73
  74 /**
  75  * Converts a path from IPRT to native representation.
  76  *
  77  * This may involve querying filesystems what codeset they
  78  * speak and so forth.
  79  *
  80  * @returns IPRT status code.
  81  * @param   ppszNativePath  Where to store the pointer to the native path.
  82  *                          Free by calling rtPathFreeHost(). NULL on failure.
  83  * @param   pszPath         The path to convert.
  84  * @param   pszBasePath     What pszPath is relative to. If NULL the function behaves like rtPathToNative().
  85  * @remark  This function is not available on hosts using something else than byte seqences as names. (eg win32)
  86  */
  87 int rtPathToNativeEx(char **ppszNativePath, const char *pszPath, const char *pszBasePath);
  88
  89 /**
  90  * Frees a native path returned by rtPathToNative() or rtPathToNativeEx().
  91  *
  92  * @param   pszNativePath   The host path to free. NULL allowed.
  93  * @remark  This function is not available on hosts using something else than byte seqences as names. (eg win32)
  94  */
  95 void rtPathFreeNative(char *pszNativePath);
  96
  97 /**
  98  * Converts a path from the native to the IPRT representation.
  99  *
 100  * @returns IPRT status code.
 101  * @param   ppszPath        Where to store the pointer to the IPRT path.
 102  *                          Free by calling RTStrFree(). NULL on failure.
 103  * @param   pszNativePath   The native path to convert.
 104  * @remark  This function is not available on hosts using something else than byte seqences as names. (eg win32)
 105  */
 106 int rtPathFromNative(char **ppszPath, const char *pszNativePath);
 107
 108 /**
 109  * Converts a path from the native to the IPRT representation.
 110  *
 111  * @returns IPRT status code.
 112  * @param   ppszPath        Where to store the pointer to the IPRT path.
 113  *                          Free by calling RTStrFree(). NULL on failure.
 114  * @param   pszNativePath   The native path to convert.
 115  * @param   pszBasePath     What pszHostPath is relative to - in IPRT representation.
 116  *                          If NULL the function behaves like rtPathFromNative().
 117  * @remark  This function is not available on hosts using something else than byte seqences as names. (eg win32)
 118  */
 119 int rtPathFromNativeEx(char **ppszPath, const char *pszNativePath, const char *pszBasePath);
 120
 121 /**
 122  * Finds the filename in a path.
 123  *
 124  * @returns Pointer to filename within pszPath.
 125  * @returns NULL if no filename (i.e. empty string or ends with a slash).
 126  * @param   pszPath     Path to find filename in.
 127  */
 128 char* RTPathFilename(const char *pszPath);
 129
 130 /**
 131  * Strips the filename from a path.
 132  *
 133  * @param   pszPath     Path which filename should be stripped.
 134  *                      If only filename in the string a '.' will be returned.
 135  */
 136 void RTPathStripFilename(char *pszPath);
 137
 138 /**
 139  * Free string allocated by any of the non-UCS-2 string functions.
 140  *
 141  * @returns iprt status code.
 142  * @param   pszString      Pointer to buffer with string to free.
 143  *                         NULL is accepted.
 144  */
 145 void  RTStrFree(char *pszString);
 146
 147 /**
 148  * Allocates tmp buffer, translates pszString from UTF8 to current codepage.
 149  *
 150  * @returns iprt status code.
 151  * @param   ppszString      Receives pointer of allocated native CP string.
 152  *                          The returned pointer must be freed using RTStrFree().
 153  * @param   pszString       UTF-8 string to convert.
 154  */
 155 int  RTStrUtf8ToCurrentCP(char **ppszString, const char *pszString);
 156
 157 /**
 158  * Allocates tmp buffer, translates pszString from current codepage to UTF-8.
 159  *
 160  * @returns iprt status code.
 161  * @param   ppszString      Receives pointer of allocated UTF-8 string.
 162  *                          The returned pointer must be freed using RTStrFree().
 163  * @param   pszString       Native string to convert.
 164  */
 165 int  RTStrCurrentCPToUtf8(char **ppszString, const char *pszString);
 166
 167
 168 #endif
 169