path.h File Reference

Path manipulation functions. More...

#include <stdbool.h>
#include <stdio.h>

Include dependency graph for path.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Functions
bool	mutt_path_abbr_folder (struct Buffer *path, const char *folder)
	Create a folder abbreviation.
const char *	mutt_path_basename (const char *path)
	Find the last component for a pathname.
bool	mutt_path_canon (struct Buffer *path, const char *homedir, bool is_dir)
	Create the canonical version of a path.
char *	mutt_path_concat (char *dest, const char *dir, const char *file, size_t dlen)
	Join a directory name and a filename.
char *	mutt_path_dirname (const char *path)
	Return a path up to, but not including, the final '/'.
char *	mutt_path_escape (const char *src)
	Escapes single quotes in a path for a command string.
const char *	mutt_path_getcwd (struct Buffer *cwd)
	Get the current working directory.
bool	mutt_path_parent (struct Buffer *path)
	Find the parent of a path.
bool	mutt_path_pretty (struct Buffer *path, const char *homedir, bool is_dir)
	Tidy a filesystem path.
size_t	mutt_path_realpath (struct Buffer *path)
	Resolve path, unraveling symlinks.
bool	mutt_path_tidy (struct Buffer *path, bool is_dir)
	Remove unnecessary parts of a path.
bool	mutt_path_tidy_dotdot (char *buf)
	Remove dot-dot-slash from a path.
bool	mutt_path_tidy_slash (char *buf, bool is_dir)
	Remove unnecessary slashes and dots.
bool	mutt_path_tilde (struct Buffer *path, const char *homedir)
	Expand '~' in a path.
bool	mutt_path_to_absolute (char *path, const char *reference)
	Convert relative filepath to an absolute path.

Detailed Description

Path manipulation functions.

Authors

• Richard Russon

Copyright

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 2 of the License, or (at your option) any later version.

This program 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 General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.

Definition in file path.h.

Function Documentation

mutt_path_abbr_folder()

bool mutt_path_abbr_folder	(	struct Buffer *	path,
		const char *	folder
	)

Create a folder abbreviation.

Parameters

path	Path to modify
folder	Base path for '=' substitution

Return values

true	Path was abbreviated

Abbreviate a path using '=' to represent the 'folder'. If the folder path is passed, it won't be abbreviated to just '='

Definition at line 494 of file path.c.

{
  if (buf_is_empty(path) || !folder)
    return false;
 
  size_t flen = mutt_str_len(folder);
  if (flen < 2)
    return false;
 
  if (folder[flen - 1] == '/')
    flen--;
 
  if (!mutt_strn_equal(buf_string(path), folder, flen))
    return false;
 
  if (buf_at(path, flen + 1) == '\0') // Don't abbreviate to '=/'
    return false;
 
  size_t rlen = mutt_str_len(path->data + flen + 1);
 
  path->data[0] = '=';
  memmove(path->data + 1, path->data + flen + 1, rlen + 1);
  buf_fix_dptr(path);
 
  return true;
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_path_basename()

const char * mutt_path_basename

(

const char *

path

)

Find the last component for a pathname.

Parameters

path	String to be examined

Return values

ptr	Part of pathname after last '/' character

Note

Basename of / is /

Definition at line 314 of file path.c.

{
  if (!path)
    return NULL;
 
  const char *p = strrchr(path, '/');
  if (p)
  {
    if (p[1] == '\0')
      return path;
 
    return p + 1;
  }
 
  return path;
}

Here is the caller graph for this function:

mutt_path_canon()

bool mutt_path_canon	(	struct Buffer *	path,
		const char *	homedir,
		bool	is_dir
	)

Create the canonical version of a path.

Parameters

path	Path to modify
homedir	Home directory for '~' substitution
is_dir	Is the path a directory?

Return values

true

Success

Remove unnecessary dots and slashes from a path and expand '~'.

Definition at line 280 of file path.c.

{
  if (buf_is_empty(path))
    return false;
 
  if (buf_at(path, 0) == '~')
  {
    mutt_path_tilde(path, homedir);
  }
  else if (buf_at(path, 0) != '/')
  {
    char cwd[PATH_MAX] = { 0 };
    if (!getcwd(cwd, sizeof(cwd)))
    {
      mutt_debug(LL_DEBUG1, "getcwd failed: %s (%d)\n", strerror(errno), errno); // LCOV_EXCL_LINE
      return false; // LCOV_EXCL_LINE
    }
 
    size_t cwd_len = mutt_str_len(cwd);
    cwd[cwd_len] = '/';
    cwd[cwd_len + 1] = '\0';
    buf_insert(path, 0, cwd);
  }
 
  return mutt_path_tidy(path, is_dir);
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_path_concat()

char * mutt_path_concat	(	char *	dest,
		const char *	dir,
		const char *	file,
		size_t	dlen
	)

Join a directory name and a filename.

Parameters

dest	Buffer for the result
dir	Directory name
file	File name
dlen	Length of buffer

Return values

ptr	Destination buffer

If both dir and file are supplied, they are separated with '/'. If either is missing, then the other will be copied exactly.

Definition at line 342 of file path.c.

{
  if (!dest || (!dir && !file))
    return NULL;
 
  if (dir && (!file || (file[0] == '\0')))
  {
    strncpy(dest, dir, dlen);
    return dest;
  }
 
  if (file && (!dir || (dir[0] == '\0')))
  {
    strncpy(dest, file, dlen);
    return dest;
  }
 
  const char *fmt = "%s/%s";
 
  if (dir[strlen(dir) - 1] == '/')
    fmt = "%s%s";
 
  snprintf(dest, dlen, fmt, dir, file);
  return dest;
}

Here is the caller graph for this function:

mutt_path_dirname()

char * mutt_path_dirname

(

const char *

path

)

Return a path up to, but not including, the final '/'.

Parameters

path

Path

Return values

ptr	The directory containing p

Unlike the IEEE Std 1003.1-2001 specification of dirname(3), this implementation does not modify its parameter, so callers need not manually copy their paths into a modifiable buffer prior to calling this function.

Note

Dirname of / is /

The caller must free the returned string

Definition at line 381 of file path.c.

{
  if (!path)
    return NULL;
 
  char buf[PATH_MAX] = { 0 };
  mutt_str_copy(buf, path, sizeof(buf));
  return mutt_str_dup(dirname(buf));
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_path_escape()

char * mutt_path_escape

(

const char *

src

)

Escapes single quotes in a path for a command string.

Parameters

src	the path to escape

Return values

ptr	The escaped string

Note

Do not free the returned string

Definition at line 528 of file path.c.

{
  if (!src)
    return NULL;
 
  static char dest[STR_COMMAND];
  char *destp = dest;
  int destsize = 0;
 
  while (*src && (destsize < sizeof(dest) - 1))
  {
    if (*src != '\'')
    {
      *destp++ = *src++;
      destsize++;
    }
    else
    {
      /* convert ' into '\'' */
      if ((destsize + 4) < sizeof(dest))
      {
        *destp++ = *src++;
        *destp++ = '\\';
        *destp++ = '\'';
        *destp++ = '\'';
        destsize += 4;
      }
      else
      {
        break; // LCOV_EXCL_LINE
      }
    }
  }
  *destp = '\0';
 
  return dest;
}

Here is the caller graph for this function:

mutt_path_getcwd()

const char * mutt_path_getcwd

(

struct Buffer *

cwd

)

Get the current working directory.

Parameters

cwd	Buffer for the result

Return values

ptr	String of current working directory

Definition at line 571 of file path.c.

{
  if (!cwd)
    return NULL;
 
  buf_alloc(cwd, PATH_MAX);
  char *rc = getcwd(cwd->data, cwd->dsize);
  while (!rc && (errno == ERANGE))
  {
    buf_alloc(cwd, cwd->dsize + 256);   // LCOV_EXCL_LINE
    rc = getcwd(cwd->data, cwd->dsize); // LCOV_EXCL_LINE
  }
  if (rc)
    buf_fix_dptr(cwd);
  else
    buf_reset(cwd); // LCOV_EXCL_LINE
 
  return rc;
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_path_parent()

bool mutt_path_parent

(

struct Buffer *

path

)

Find the parent of a path.

Parameters

path	Buffer for the result

Return values

true

Success

Definition at line 461 of file path.c.

{
  if (buf_is_empty(path))
    return false;
 
  int n = buf_len(path);
  if (n < 2)
    return false;
 
  if (buf_at(path, n - 1) == '/')
    n--;
 
  // Find the previous '/'
  for (n--; ((n >= 0) && (buf_at(path, n) != '/')); n--)
    ; // do nothing
 
  if (n == 0) // Always keep at least one '/'
    n++;
 
  path->data[n] = '\0';
  buf_fix_dptr(path);
  return true;
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_path_pretty()

bool mutt_path_pretty	(	struct Buffer *	path,
		const char *	homedir,
		bool	is_dir
	)

Tidy a filesystem path.

Parameters

path	Path to modify
homedir	Home directory for '~' substitution
is_dir	Is the path a directory?

Return values

true

Success

Tidy a path and replace a home directory with '~'

Definition at line 188 of file path.c.

{
  if (buf_is_empty(path))
    return false;
 
  mutt_path_tidy(path, is_dir);
 
  size_t len = mutt_str_startswith(path->data, homedir);
  if (len == 0)
    return false;
 
  if ((buf_at(path, len) != '/') && (buf_at(path, len) != '\0'))
    return false;
 
  path->data[0] = '~';
  if (buf_len(path) == len)
  {
    path->data[1] = '\0';
    buf_fix_dptr(path);
    return true;
  }
 
  mutt_str_copy(path->data + 1, path->data + len, buf_len(path) + 1 - len);
  buf_fix_dptr(path);
  return true;
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_path_realpath()

size_t mutt_path_realpath

(

struct Buffer *

path

)

Resolve path, unraveling symlinks.

Parameters

path	Buffer containing path

Return values

num	String length of resolved path
0	Error, buf is not overwritten

Resolve and overwrite the path in buf.

Definition at line 443 of file path.c.

{
  if (buf_is_empty(path))
    return 0;
 
  char s[PATH_MAX] = { 0 };
 
  if (!realpath(buf_string(path), s))
    return 0;
 
  return buf_strcpy(path, s);
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_path_tidy()

bool mutt_path_tidy	(	struct Buffer *	path,
		bool	is_dir
	)

Remove unnecessary parts of a path.

Parameters

[in,out]	path	Path to modify
[in]	is_dir	Is the path a directory?

Return values

true

Success

Remove unnecessary dots and slashes from a path

Definition at line 165 of file path.c.

{
  if (buf_is_empty(path) || (buf_at(path, 0) != '/'))
    return false;
 
  if (!mutt_path_tidy_slash(path->data, is_dir))
    return false; // LCOV_EXCL_LINE
 
  mutt_path_tidy_dotdot(path->data);
  buf_fix_dptr(path);
 
  return true;
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_path_tidy_dotdot()

bool mutt_path_tidy_dotdot

(

char *

buf

)

Remove dot-dot-slash from a path.

Parameters

[in,out]

buf

Path to modify

Return values

true

Success

Collapse dot-dot patterns, like '/dir/../'

Definition at line 105 of file path.c.

{
  if (!buf || (buf[0] != '/'))
    return false;
 
  char *dd = buf;
 
  mutt_debug(LL_DEBUG3, "Collapse path: %s\n", buf);
  while ((dd = strstr(dd, "/..")))
  {
    if (dd[3] == '/') /* paths follow dots */
    {
      char *dest = NULL;
      if (dd != buf) /* not at start of string */
      {
        dd[0] = '\0';
        dest = strrchr(buf, '/');
      }
      if (!dest)
        dest = buf;
 
      memmove(dest, dd + 3, strlen(dd + 3) + 1);
    }
    else if (dd[3] == '\0') /* dots at end of string */
    {
      if (dd == buf) /* at start of string */
      {
        dd[1] = '\0';
      }
      else
      {
        dd[0] = '\0';
        char *s = strrchr(buf, '/');
        if (s == buf)
          s[1] = '\0';
        else if (s)
          s[0] = '\0';
      }
    }
    else
    {
      dd += 3; /* skip over '/..dir/' */
      continue;
    }
 
    dd = buf; /* restart at the beginning */
  }
 
  mutt_debug(LL_DEBUG3, "Collapsed to:  %s\n", buf);
  return true;
}

Here is the caller graph for this function:

mutt_path_tidy_slash()

bool mutt_path_tidy_slash	(	char *	buf,
		bool	is_dir
	)

Remove unnecessary slashes and dots.

Parameters

[in,out]	buf	Path to modify
[in]	is_dir	Should a trailing / be removed?

Return values

true

Success

Collapse repeated '//' and '/./'

Definition at line 54 of file path.c.

{
  if (!buf)
    return false;
 
  char *r = buf;
  char *w = buf;
 
  while (*r != '\0')
  {
    *w++ = *r++;
 
    if (r[-1] == '/') /* After a '/' ... */
    {
      for (; (r[0] == '/') || (r[0] == '.'); r++)
      {
        if (r[0] == '/') /* skip multiple /s */
          continue;
        if (r[0] == '.')
        {
          if (r[1] == '/') /* skip /./ */
          {
            r++;
            continue;
          }
          else if (r[1] == '\0') /* skip /.$ */
          {
            r[0] = '\0';
          }
          break; /* dot-anything-else isn't special */
        }
      }
    }
  }
 
  /* Strip a trailing / as long as it's not the only character */
  if (is_dir && (w > (buf + 1)) && (w[-1] == '/'))
    w--;
 
  *w = '\0';
 
  return true;
}

Here is the caller graph for this function:

mutt_path_tilde()

bool mutt_path_tilde	(	struct Buffer *	path,
		const char *	homedir
	)

Expand '~' in a path.

Parameters

path	Path to modify
homedir	Home directory for '~' substitution

Return values

true

Success

Behaviour:

• ~/dir (~ expanded)
• ~realuser/dir (~realuser expanded)
• ~nonuser/dir (~nonuser not changed)

Definition at line 226 of file path.c.

{
  if (buf_is_empty(path) || (buf_at(path, 0) != '~'))
    return false;
 
  char result[PATH_MAX] = { 0 };
  char *dir = NULL;
  size_t len = 0;
 
  if ((buf_at(path, 1) == '/') || (buf_at(path, 1) == '\0'))
  {
    if (!homedir)
    {
      mutt_debug(LL_DEBUG3, "no homedir\n");
      return false;
    }
 
    len = mutt_str_copy(result, homedir, sizeof(result));
    dir = path->data + 1;
  }
  else
  {
    char user[128] = { 0 };
    dir = strchr(path->data + 1, '/');
    if (dir)
      mutt_str_copy(user, path->data + 1, MIN(dir - path->data, (unsigned) sizeof(user)));
    else
      mutt_str_copy(user, path->data + 1, sizeof(user));
 
    struct passwd *pw = getpwnam(user);
    if (!pw || !pw->pw_dir)
    {
      mutt_debug(LL_DEBUG1, "no such user: %s\n", user);
      return false;
    }
 
    len = mutt_str_copy(result, pw->pw_dir, sizeof(result));
  }
 
  mutt_str_copy(result + len, dir, sizeof(result) - len);
  buf_strcpy(path, result);
 
  return true;
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_path_to_absolute()

bool mutt_path_to_absolute	(	char *	path,
		const char *	reference
	)

Convert relative filepath to an absolute path.

Parameters

path	Relative path
reference	Absolute path that path is relative to

Return values

true	Success
false	Failure

Use POSIX functions to convert a path to absolute, relatively to another path

Note

path should be at least of PATH_MAX length

Definition at line 402 of file path.c.

{
  if (!path || !reference)
    return false;
 
  char abs_path[PATH_MAX] = { 0 };
  int path_len;
 
  /* if path is already absolute, don't do anything */
  if ((strlen(path) > 1) && (path[0] == '/'))
  {
    return true;
  }
 
  char *dirpath = mutt_path_dirname(reference);
  mutt_str_copy(abs_path, dirpath, sizeof(abs_path));
  FREE(&dirpath);
  mutt_strn_cat(abs_path, sizeof(abs_path), "/", 1); /* append a / at the end of the path */
 
  path_len = sizeof(abs_path) - strlen(path);
 
  mutt_strn_cat(abs_path, sizeof(abs_path), path, (path_len > 0) ? path_len : 0);
 
  path = realpath(abs_path, path);
  if (!path && (errno != ENOENT))
  {
    mutt_perror(_("Error: converting path to absolute"));
    return false;
  }
 
  return true;
}

Here is the call graph for this function:

Here is the caller graph for this function: