path.h File Reference

General file name and file path utility declarations. More...

#include <ctype.h>
#include "rnr/rnrconfig.h"

Go to the source code of this file.

Typedefs
typedef struct path_iter	PathIter_T

Functions
INLINE_IN_H bool_t	PathIsAbsolute (const char *sPath)
	Check if the given path is an absolute path. More...
char *	NewExpandTilde (const char *sTildeExpr)
	Expand tilde expression. More...
char *	NewSearchPathExpanded (const char *sSearchPath)
	Expands search path. More...
char *	NewSearchPathCanonicalized (const char *sSearchPath)
	Expands and canonicalizes a search path. More...
PathIter_T *	SearchPathIterNew (const char *sSearchPath)
	Allocates and initilized a new search path iterator. More...
void	SearchPathIterDelete (PathIter_T *pIter)
	Deletes search path iterator. More...
char *	SearchPathIterFirst (PathIter_T *pIter, const char *sSearchFile)
	Get the first concatenated file path. More...
char *	SearchPathIterNext (PathIter_T *pIter)
	Construct next file path from search path and search file name. More...
char *	NewNormPath (const char *sPath)
	Normalize path. More...
char *	NewRealPath (const char *sPath)
	Expands and canonicalizes a real path. More...
char *	NewJoinedPath (const char *sPath1, const char *sPath2)
	Join two file paths. More...

Detailed Description

General file name and file path utility declarations.

Boths posix (the world) and Microsoft's file and path syntax are supported.

Supported Search Path Backus-Naur Form:

* search_path ::=
*    path
*  | path path_sep search_path
*
* path ::=
*    root rel_path
*  | rel_path
*
* root :: =
*      std_dir_sep
*    | win_dir_sep
*    | win_drive win_dir_sep
*
* rel_path ::=
*      fname
*    | fname dir_sep rel_path
*
* fname ::=
*    '.'
*  | '.' '.'
*  | '~'
*  | '~' OSLEGAL_USERNAME
*  | '$' indentifier
*  | '$' '{' indentifier '}'
*  | OSLEGAL_FILENAME
*
* path_sep ::= std_path_sep | win_path_sep
*
* std_path_sep ::= ':'
* win_path_sep ::= ';'
*
* dir_sep ::= std_dir_sep | win_dir_sep
*
* std_dir_sep ::= '/' 
* win_dir_sep ::= '\\'
*
* win_drive ::= a-zA-Z ':'
* 

Package

RoadNarrows Robotics Common Library 1

Library

librnr

File

rnr/path.h

Author

Robin Knight (robin.nosp@m..kni.nosp@m.ght@r.nosp@m.oadn.nosp@m.arrow.nosp@m.s.co.nosp@m.m)

Copyright

© 2005-2018. RoadNarrows LLC..
http://www.roadnarrows.com
All Rights Reserved

License

MIT

EULA

See the README and EULA files for any copyright and licensing information.

—

Definition in file path.h.

Typedef Documentation

typedef struct path_iter PathIter_T

Search Path Iterator Structure

Definition at line 82 of file path.h.

Function Documentation

char* NewExpandTilde

(

const char *

sTildeExpr

)

Expand tilde expression.

Parameters

sTildeExpr

'~' [user]

Returns

Return allocated expanded tilde expression path on success.
If the expression has invalid syntax or the user does not exist, then NULL is returned.

Definition at line 157 of file path.c.

References DIR_SEP_CHAR, new_strdup(), NULL, and PATH_SEP_CHAR.

Referenced by NewSearchPathExpanded(), and PathIsAbsolute().

{
  char          *sUser;
  struct passwd *pPassEntry;
  uid_t          uid;
  char          *sExpanded = NULL;

  // expression must start with a tilde
  if( (sTildeExpr == NULL) || (*sTildeExpr != '~') )
  {
    return NULL;
  }

  // user name
  sUser = (char *)sTildeExpr + 1;

  // expand this user's home
  if( (*sUser == 0) || (*sUser == DIR_SEP_CHAR) || (*sUser == PATH_SEP_CHAR) )
  {
    if( (sExpanded = getenv("HOME")) == NULL )
    {
      uid = getuid();
      if( (pPassEntry = getpwuid(uid)) != NULL )
      {
        sExpanded = pPassEntry->pw_dir;
      }
    }
  }
  
  // expand other user's home
  else
  {
    if( (pPassEntry = getpwnam(sUser)) != NULL )
    {
      sExpanded = pPassEntry->pw_dir;
    }
  }

  if( sExpanded != NULL )
  {
    return new_strdup(sExpanded);
  }
  else
  {
    return NULL;
  }
}

char* NewJoinedPath	(	const char *	sPath1,
		const char *	sPath2
	)

Join two file paths.

The paths are expanded and canonicalized. The paths do not have to exist. If the second, appended path is an absolute path, then the joined path is the second path.

Parameters

sPath1	Front absolute/relative path.
sPath2	Appended, back end path.

Returns

On success, an allocated, canonical joined path name is returned.
On failure, NULL is returned.

Definition at line 802 of file path.c.

References DIR_SEP_STR, LOGERROR, NewSearchPathCanonicalized(), NEWSTR, NULL, and PathIsAbsolute().

Referenced by PathIsAbsolute().

{
  char   *p1 = NULL;
  char   *p2 = NULL;
  char   *pj = NULL;

  // canonicalize path 2
  if( (p2 = NewSearchPathCanonicalized(sPath2)) == NULL )
  {
    LOGERROR("NewSearchPathCanonicalized(\"%s\") failed.", sPath2);
  }

  // if the second path is an absolute path, cannot join
  else if( PathIsAbsolute(p2) )
  {
    return p2;
  }

  // canonicalize path 1
  else if( (p1 = NewSearchPathCanonicalized(sPath1)) == NULL )
  {
    LOGERROR("NewSearchPathCanonicalized(\"%s\") failed.", sPath1);
  }

  // join
  else
  {
    pj = NEWSTR(strlen(p1)+strlen(DIR_SEP_STR)+strlen(p2));
    sprintf(pj, "%s%s%s", p1, DIR_SEP_STR, p2);
  }

  delete(p1);
  delete(p2);

  return pj;
}

char* NewNormPath

(

const char *

sPath

)

Normalize path.

Normalize path, eliminating double slashes and simplifying dot "." current and ".." parent directory references.

The path does not have to exist.

Returns

Returns allocated normalized path.

Definition at line 572 of file path.c.

References DIR_SEP_CHAR, DIR_SEP_STR, new_strdup(), NEWSTR, and PathIsAbsolute().

Referenced by NewSearchPathCanonicalized(), and PathIsAbsolute().

{
  char *sTopDir;
  char *sNew;
  int   i, j, k;
  int   slashes;

  // Degenerative empty string case.
  if( *sPath == 0 )
  {
    return new_strdup(".");
  }

  // Normalization results in a smaller length string, except in the
  // degenerative case above.
  sNew = NEWSTR(strlen(sPath));

  // The (implicit) top directory is either the root or current directory.
  if( PathIsAbsolute(sPath) )
  {
    sTopDir = DIR_SEP_STR;
  }
  else
  {
    sTopDir = ".";
  }

  //
  // Normalize the path.
  //
  for(i=0, j=0; sPath[i]!=0; )
  {
    switch( sPath[i] )
    {
      // 
      // Potential current dot or parent dotdot directory path component.
      //
      case '.':
        // "filename." or "filename.."
        if( (j > 0) && (sNew[j-1] != DIR_SEP_CHAR) )
        {
          sNew[j++] = sPath[i++];
        }

        // "../[path]" or ".."
        else if( (sPath[i+1] == '.') && 
                ((sPath[i+2] == DIR_SEP_CHAR) || (sPath[i+2] == 0)) )
        {
          // 
          // Try to backup to parent directory.
          // example 1: "path1/pdir/cdir/../path2" -> "pathl/pdir/path2"
          // example 2: "pdir/cdir/../path2"       -> "pdir/path2"
          // example 3: "cdir/../path2"            -> "path2"
          // example 4: "/cdir/../path2"           -> "/path2"
          // example 5: " cdir/../../path2"        -> "../path2"
          // example 6: "/cdir/../../path2"        -> "/path2"
          // example 7: "dir/../cdir/.."           -> "."
          //
          for(k=j-1, slashes=0; k>=0 && slashes<2; --k)
          {
            if( sNew[k] == DIR_SEP_CHAR )
            {
              ++slashes;
            }
          }
          ++k;

          //                   i                             i
          //             k     j                         k   j
          // "[path/]pdir/cdir/..[/path]" or "[path/]pdir/../..[/path]"
          //
          if( slashes == 2 )
          {
            // if current directory is "..", then "../.."
            if( (sNew[k+1] == '.') &&
                (sNew[k+2] == '.') &&
                (sNew[k+3] == DIR_SEP_CHAR) )
            {
              sNew[j++] = '.';
              sNew[j++] = '.';
            }
            // "[path]/pdir"
            else
            {
              j = k;
              sNew[j] = 0;
            }
          }

          //   i                   i
          //  kj              k    j
          // "/..[/path]" or "cdir/..[/path]"
          //
          else if( slashes == 1 )
          {
            // relative
            if( sNew[0] != DIR_SEP_CHAR )
            {
              j = 0;
              sNew[j++] = '.';
              sNew[j] = 0;
            }
            // absolute
            else
            {
              j = 0;
              sNew[j++] = DIR_SEP_CHAR;
              sNew[j] = 0;
            }
          }

          //  i
          //  j
          //  k
          // "..[/path]"
          //
          else  // slashes == 0
          {
            j = 0;
            sNew[j++] = '.';
            sNew[j++] = '.';
            sNew[j] = 0;
          }

          i += 2;
        }

        // current dot directory "./[path]" or "."
        else if( (sPath[i+1] == DIR_SEP_CHAR) || (sPath[i+1] == 0) )
        {
          i += sPath[i+1] == DIR_SEP_CHAR? 2: 1;
        }

        // dot filename ".filename"
        else
        {
          sNew[j++] = sPath[i++];
        }
        break;

      //
      // Directory component.
      //
      case DIR_SEP_CHAR:
        // directory separator that's not superfluous "[path1]/path2"
        if( (sPath[i+1] != DIR_SEP_CHAR) && (sPath[i+1] != 0) )
        {
          // "/[path]"
          if( j == 0 )
          {
            sNew[j++] = sPath[i++];
          }
          // "//path}
          else if( sNew[j-1] == DIR_SEP_CHAR )
          {
            ++i;
          }
          // "[path1/]./[path2]"
          else if((sNew[j-1] == '.') && 
                  ((j == 1) || (sNew[j-2] == DIR_SEP_CHAR)) )
          {
            --j;
            ++i;
          }
          // "[path1]/path2"
          else
          {
            sNew[j++] = sPath[i++];
          }
        }
        // ignore extra or ending separator "//" or "/"
        else
        {
          ++i;
        }
        break;

      // 
      // Non-special file character.
      //
      default:
        sNew[j++] = sPath[i++];
        break;
    }
  }

  sNew[j] = 0;

  if( *sNew == 0 )
  {
    strcpy(sNew, sTopDir);
  }

  return sNew;
}

char* NewRealPath

(

const char *

sPath

)

Expands and canonicalizes a real path.

The expanded path must exist.

Parameters

sPath

Path file name.

Returns

Return allocated canonical path on success, NULL if path doest not exist.

Definition at line 778 of file path.c.

References NewSearchPathCanonicalized(), and NULL.

Referenced by PathIsAbsolute().

{
  char  *s, *t;

  s = NewSearchPathCanonicalized(sPath);
  t = realpath(s, NULL);
  delete(s);
  return t;
}

char* NewSearchPathCanonicalized

(

const char *

sSearchPath

)

Expands and canonicalizes a search path.

The path does not have to exist.

A canonical search path has:

• any beginning or ending path separators stipped
• any contiguous sequence of path separators replaced with a single separator
• any contiguous sequence of directory separators replaced with a single separator
• any terminating directory separator stripped from each path component

Parameters

sSearchPath

Search path of form: path [path_sep path...]

Returns

Return allocated canonical search path on success, NULL if search path is is not specified. If the search path is too long, a truncated version will be returned.

Definition at line 331 of file path.c.

References NewNormPath(), NewSearchPathExpanded(), NEWSTR, NULL, and PATH_SEP_STR.

Referenced by NewJoinedPath(), NewRealPath(), NewSearchPathDList(), PathIsAbsolute(), and SearchPathIterFirst().

{
  char   *sExpPath;     // expanded search path
  char   *sPath;        // expanded path
  char   *sNorm;        // normalized path
  char   *sSep;         // path separator
  char   *sNew;         // canonical search path
  char   *sSave = NULL; // strtok() save pointer
  char   *s;            // working string
  size_t  k, m, n, len; // working sizes

  // expand any environment variables and '~''s listed in search path
  if( (sExpPath = NewSearchPathExpanded(sSearchPath)) == NULL )
  {
    return NULL;
  }

  len   = strlen(sExpPath);
  sNew  = NEWSTR(len);
  n     = 0;
  sSep  = "";
  k     = 0;

  for(sPath=strtok_r(sExpPath, PATH_SEP_STR, &sSave); 
      sPath!=NULL; 
      sPath=strtok_r(NULL, PATH_SEP_STR, &sSave))
  {
    sNorm = NewNormPath(sPath);
    m     = strlen(sNorm);

    // grow new search path
    if( n+k+m >= len )
    {
      len = (n + k + m) * 2;
      s = NEWSTR(len);
      strcpy(s, sNew);
      delete(sNew);
      sNew = s;
    }

    sprintf(sNew+n, "%s%s", sSep, sNorm);
    n += k + m;

    if( *sSep == 0 )
    {
      sSep  = PATH_SEP_STR;
      k     = strlen(sSep);
    }
  }

  delete(sExpPath);

  return sNew;
}

char* NewSearchPathExpanded

(

const char *

sSearchPath

)

Expands search path.

Expands any environment variables and tilde expressions in search path while building new search path.

The path does not have to exist.

Variable are specified as:
$<identifier> or ${<identifier>} where <identifier> is a legal shell variable name.

Tilde expressions are specified as:
~ or ~user

Parameters

sSearchPath

Search path of form: path [path_sep path...]

Returns

Return allocated expanded search path on success, NULL if search path is is not specified. If the search path is too long, a truncated version will be returned.

Definition at line 227 of file path.c.

References DIR_SEP_CHAR, isidentifier, LOGDIAG4, LOGERROR, LOGFUNCNAME, MAX_SEARCH_PATH, new_strndup(), NewExpandTilde(), NEWSTR, and NULL.

Referenced by NewSearchPathCanonicalized(), and PathIsAbsolute().

{
  char  *sExpPath;                    // expanded path
  const char  *s, *u;                 // working source char pointers
  char  *t;                           // working target char pointers
  char  *sName, *sVal;                // environment name=value strings
  size_t nExpLen = 0;                 // current length of expanded path
                                      //  (sans null character)
  size_t nMaxLen = MAX_SEARCH_PATH-1; // maximum length
  size_t nNameLen;                    // name length

  if( (sSearchPath == NULL) || (*sSearchPath == 0) )
  {
    return NULL;
  }

  sExpPath = NEWSTR(nMaxLen);

  for(s=sSearchPath, t=sExpPath; *s && nExpLen<nMaxLen; )
  {
    switch(*s)
    {
      case '$':
        ++s;
        if( *s == '{' )
        {
          ++s;
        }
        for(u=s; isidentifier(*s); ++s);
        sName = NULL;
        nNameLen = (size_t)(s - u);
        if( nNameLen > 0 )
        {
          sName = new_strndup(u, nNameLen);
          if( (sName != NULL) && ((sVal = getenv(sName)) != NULL) )
          {
            for(; *sVal && nExpLen<nMaxLen; ++nExpLen)
            {
              *t++ = *sVal++;
            }
          }
          delete(sName);
        }
        if( *s == '}' )
        {
          ++s;
        }
        break;
      case '~':
        for(u=s; (*s != DIR_SEP_CHAR) && (*s != 0); ++s);
        sName = NULL;
        nNameLen = (size_t)(s - u);
        if( nNameLen > 0 )
        {
          sName = new_strndup(u, nNameLen);
          if( (sName != NULL) && ((sVal = NewExpandTilde(sName)) != NULL) )
          {
            for(u=sVal; *u && nExpLen<nMaxLen; ++nExpLen)
            {
              *t++ = *u++;
            }
            delete(sVal);
          }
          delete(sName);
        }
        break;
      default:
        *t++ = *s++;
        ++nExpLen;
        break;
    }
  }
  *t = 0;

  if( nExpLen >= nMaxLen )
  {
    LOGERROR("Expanded search path truncated");
  }

  LOGDIAG4("'%s'=%s('%s')", sExpPath, LOGFUNCNAME, sSearchPath);

  return sExpPath;
}

INLINE_IN_H bool_t PathIsAbsolute

(

const char *

sPath

)

Check if the given path is an absolute path.

Parameters

sPath

Path name.

Returns

Returnes true or false

Definition at line 91 of file path.h.

References C_DECLS_END, DIR_SEP_CHAR, NewExpandTilde(), NewJoinedPath(), NewNormPath(), NewRealPath(), NewSearchPathCanonicalized(), NewSearchPathExpanded(), NULL, SearchPathIterDelete(), SearchPathIterFirst(), SearchPathIterNew(), and SearchPathIterNext().

Referenced by NewJoinedPath(), and NewNormPath().

{
  if( sPath == NULL )
  {
    return false;
  }
  else if( *sPath == DIR_SEP_CHAR )
  {
    return true;
  }
#if defined(__windows__)
  else if( isalpha(*sPath) && (*(sPath+1) == ':') &&
            (*(sPath+2) == DIR_SEP_CHAR) )
  {
    return true;
  }
#endif // __windwos__
  else
  {
    return false;
  }
}

void SearchPathIterDelete

(

PathIter_T *

pIter

)

Deletes search path iterator.

Parameters

pIter

Search path iterator (invalid after return from this call).

Definition at line 422 of file path.c.

References path_iter::m_pSearchPaths, path_iter::m_sFileCanonical, path_iter::m_sFilePath, and NULL.

Referenced by PathIsAbsolute(), and SearchPathIterNew().

{
  if( pIter == NULL )
  {
    return;
  }

  if( pIter->m_pSearchPaths != NULL )
  {
    DListStrDelete(pIter->m_pSearchPaths);
  }

  delete(pIter->m_sFileCanonical);
  delete(pIter->m_sFilePath);
  
  delete(pIter);
}

char* SearchPathIterFirst	(	PathIter_T *	pIter,
		const char *	sSearchFile
	)

Get the first concatenated file path.

Initialize search path iterator from given search file and returns first concatenated file path.

Parameters

pIter	Path iterator.
sSearchFile	Search path.

Returns

Returns first file path on success, NULL if at end of search or on error.

Definition at line 452 of file path.c.

References DIR_SEP_STR, LOGDIAG4, LOGERROR, LOGFUNCNAME, path_iter::m_bIsEos, path_iter::m_iterPaths, path_iter::m_nFileLen, path_iter::m_pSearchPaths, path_iter::m_sFileCanonical, path_iter::m_sFilePath, NewSearchPathCanonicalized(), NEWSTR, and NULL.

Referenced by PathIsAbsolute().

{
  const char      *sPath;   // search path component
  size_t           nLen;    // string length

  // logistics to [re]set iterator
  delete(pIter->m_sFileCanonical);  // clear any old canonical serach file 
  pIter->m_sFileCanonical = NULL;
  delete(pIter->m_sFilePath);       // clear any old constructed file path
  pIter->m_sFilePath      = NULL;
  pIter->m_nFileLen       = 0;      // no file, no length
  pIter->m_bIsEos         = true;   // assume end-of-search condition until
                                    //   proven otherwise

  // no serach file specified
  if( (sSearchFile == NULL) || (*sSearchFile == 0) )
  {
    LOGERROR("%s(): no file specified", LOGFUNCNAME);
    return NULL;
  }

  // cannot canonicalize search file
  else if( (pIter->m_sFileCanonical = NewSearchPathCanonicalized(sSearchFile)) 
                                        == NULL )
  {
    LOGERROR("NewSearchPathCanonicalized() failed");
    return NULL;
  }

  // set canonical file name length - used to speed iteration
  pIter->m_nFileLen = strlen(pIter->m_sFileCanonical);

  // no search path - just return canonical file
  if( DListStrCount(pIter->m_pSearchPaths) == 0 )
  {
    LOGDIAG4("'%s'=%s()", pIter->m_sFileCanonical, LOGFUNCNAME);

    return pIter->m_sFileCanonical;
  }

  // construct first file path
  else if( (sPath = DListStrIterDataFirst(pIter->m_pSearchPaths,
                                          &(pIter->m_iterPaths))) != NULL )
  {
    pIter->m_bIsEos = false;

    nLen  = strlen(sPath) + strlen(DIR_SEP_STR) + pIter->m_nFileLen;

    pIter->m_sFilePath = NEWSTR(nLen);

    sprintf(pIter->m_sFilePath, "%s%s%s", 
      sPath, DIR_SEP_STR, pIter->m_sFileCanonical);

    LOGDIAG4("'%s'=%s()", pIter->m_sFilePath, LOGFUNCNAME);

    return pIter->m_sFilePath;
  }

  // shouldn't have gotten here - so terminate search
  else
  {
    return NULL;
  }
}

PathIter_T* SearchPathIterNew

(

const char *

sSearchPath

)

Allocates and initilized a new search path iterator.

This iterator can be reused multiple times with different search files by calling SearchPathIterFirst(). SearchPathIterDelete() must be called when finished with the iterator to clean up any allocated memory.

Parameters

sSearchPath

Search path of form: path [path_sep path...]

Returns

Returns pointer to search path iterator on success, NULL on error

Definition at line 398 of file path.c.

References LOGERROR, path_iter::m_bIsEos, path_iter::m_nFileLen, path_iter::m_pSearchPaths, path_iter::m_sFileCanonical, path_iter::m_sFilePath, NEW, NewSearchPathDList(), NULL, and SearchPathIterDelete().

Referenced by PathIsAbsolute().

{
  PathIter_T  *pIter = NEW(PathIter_T);

  if( (pIter->m_pSearchPaths = NewSearchPathDList(sSearchPath)) == NULL )
  {
    LOGERROR("NewSearchPathDlist() failed");
    SearchPathIterDelete(pIter);
    return NULL;
  }

  pIter->m_sFileCanonical = NULL;
  pIter->m_nFileLen       = 0;
  pIter->m_sFilePath      = NULL;
  pIter->m_bIsEos         = false;

  return pIter;
}

char* SearchPathIterNext

(

PathIter_T *

pIter

)

Construct next file path from search path and search file name.

Parameters

pIter

Path iterator.

Returns

Returns next constructed file path on success, NULL if at end of search or on error

Definition at line 526 of file path.c.

References DIR_SEP_STR, LOGDIAG4, LOGFUNCNAME, path_iter::m_bIsEos, path_iter::m_iterPaths, path_iter::m_nFileLen, path_iter::m_sFileCanonical, path_iter::m_sFilePath, NEWSTR, and NULL.

Referenced by PathIsAbsolute().

{
  const char      *sPath;   // search path component
  size_t           nLen;    // string length

  // end of search
  if( pIter->m_bIsEos )
  {
    return NULL;
  }

  // get the next search path component
  else if( (sPath = DListStrIterDataNext(&(pIter->m_iterPaths))) != NULL )
  {
    nLen  = strlen(sPath) + strlen(DIR_SEP_STR) + pIter->m_nFileLen;

    delete(pIter->m_sFilePath);         // clear any old constructed file path
    pIter->m_sFilePath = NEWSTR(nLen);  // allocate new file path
    
    sprintf(pIter->m_sFilePath, "%s%s%s", 
      sPath, DIR_SEP_STR, pIter->m_sFileCanonical);

    LOGDIAG4("'%s'=%s()", pIter->m_sFilePath, LOGFUNCNAME);

    return pIter->m_sFilePath;
  }

  // end of search
  else
  {
    pIter->m_bIsEos = true;
    return NULL;
  }
}