file.c File Reference

File management functions. More...

#include "config.h"
#include <errno.h>
#include <fcntl.h>
#include <limits.h>
#include <stdbool.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <sys/stat.h>
#include <time.h>
#include <unistd.h>
#include <utime.h>
#include <wchar.h>
#include "file.h"
#include "buffer.h"
#include "charset.h"
#include "ctype2.h"
#include "date.h"
#include "logging2.h"
#include "memory.h"
#include "message.h"
#include "path.h"
#include "pool.h"
#include "string2.h"

Include dependency graph for file.c:

Go to the source code of this file.

Macros
#define	MAX_LOCK_ATTEMPTS   5
	Maximum number of attempts to lock a file.

Functions
static bool	stat_equal (struct stat *st_old, struct stat *st_new)
	Compare the struct stat's of two files/dirs.
int	mutt_file_fclose_full (FILE **fp, const char *file, int line, const char *func)
	Close a FILE handle (and NULL the pointer)
int	mutt_file_fsync_close (FILE **fp)
	Flush the data, before closing a file (and NULL the pointer)
void	mutt_file_unlink (const char *s)
	Delete a file, carefully.
int	mutt_file_copy_bytes (FILE *fp_in, FILE *fp_out, size_t size)
	Copy some content from one file to another.
int	mutt_file_copy_stream (FILE *fp_in, FILE *fp_out)
	Copy the contents of one file into another.
int	mutt_file_symlink (const char *oldpath, const char *newpath)
	Create a symlink.
int	mutt_file_safe_rename (const char *src, const char *target)
	NFS-safe renaming of files.
int	mutt_file_rmtree (const char *path)
	Recursively remove a directory.
const char *	mutt_file_rotate (const char *path, int count)
	Rotate a set of numbered files.
int	mutt_file_open (const char *path, uint32_t flags, mode_t mode)
	Open a file.
DIR *	mutt_file_opendir (const char *path, enum MuttOpenDirMode mode)
	Open a directory.
FILE *	mutt_file_fopen_full (const char *path, const char *mode, const mode_t perms, const char *file, int line, const char *func)
	Call fopen() safely.
void	mutt_file_sanitize_filename (char *path, bool slash)
	Replace unsafe characters in a filename.
int	mutt_file_sanitize_regex (struct Buffer *dest, const char *src)
	Escape any regex-magic characters in a string.
bool	mutt_file_seek (FILE *fp, LOFF_T offset, int whence)
	Wrapper for fseeko with error handling.
char *	mutt_file_read_line (char *line, size_t *size, FILE *fp, int *line_num, ReadLineFlags flags)
	Read a line from a file.
bool	mutt_file_iter_line (struct MuttFileIter *iter, FILE *fp, ReadLineFlags flags)
	Iterate over the lines from an open file pointer.
bool	mutt_file_map_lines (mutt_file_map_t func, void *user_data, FILE *fp, ReadLineFlags flags)
	Process lines of text read from a file pointer.
void	buf_quote_filename (struct Buffer *buf, const char *filename, bool add_outer)
	Quote a filename to survive the shell's quoting rules.
int	mutt_file_mkdir (const char *path, mode_t mode)
	Recursively create directories.
time_t	mutt_file_decrease_mtime (const char *fp, struct stat *st)
	Decrease a file's modification time by 1 second.
void	mutt_file_set_mtime (const char *from, const char *to)
	Set the modification time of one file from another.
void	mutt_file_touch_atime (int fd)
	Set the access time to current time.
bool	mutt_file_touch (const char *path)
	Make sure a file exists.
int	mutt_file_chmod_add (const char *path, mode_t mode)
	Add permissions to a file.
int	mutt_file_chmod_add_stat (const char *path, mode_t mode, struct stat *st)
	Add permissions to a file.
int	mutt_file_chmod_rm_stat (const char *path, mode_t mode, struct stat *st)
	Remove permissions from a file.
int	mutt_file_lock (int fd, bool excl, bool timeout)
	(Try to) Lock a file using fcntl()
int	mutt_file_unlock (int fd)
	Unlock a file previously locked by mutt_file_lock()
void	mutt_file_unlink_empty (const char *path)
	Delete a file if it's empty.
int	mutt_file_rename (const char *oldfile, const char *newfile)
	Rename a file.
char *	mutt_file_read_keyword (const char *file, char *buf, size_t buflen)
	Read a keyword from a file.
int	mutt_file_check_empty (const char *path)
	Is the mailbox empty.
void	buf_file_expand_fmt_quote (struct Buffer *dest, const char *fmt, const char *src)
	Replace s in a string with a filename.
void	mutt_file_expand_fmt (struct Buffer *dest, const char *fmt, const char *src)
	Replace s in a string with a filename.
long	mutt_file_get_size (const char *path)
	Get the size of a file.
long	mutt_file_get_size_fp (FILE *fp)
	Get the size of a file.
int	mutt_file_timespec_compare (struct timespec *a, struct timespec *b)
	Compare to time values.
void	mutt_file_get_stat_timespec (struct timespec *dest, struct stat *st, enum MuttStatType type)
	Read the stat() time into a time value.
int	mutt_file_stat_timespec_compare (struct stat *st, enum MuttStatType type, struct timespec *b)
	Compare stat info with a time value.
int	mutt_file_stat_compare (struct stat *st1, enum MuttStatType st1_type, struct stat *st2, enum MuttStatType st2_type)
	Compare two stat infos.
void	mutt_file_resolve_symlink (struct Buffer *buf)
	Resolve a symlink in place.
size_t	mutt_file_save_str (FILE *fp, const char *str)
	Save a string to a file.

Variables
static const char	RxSpecialChars [] = "^.[$()|*+?{\\"
	These characters must be escaped in regular expressions.
const char	FilenameSafeChars [] = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+@{}._-:%/"
	Set of characters <=0x7F that are safe to use in filenames.

Detailed Description

File management functions.

Authors

• Reis Radomil
• Richard Russon
• Pietro Cerutti
• Federico Kircheis
• Ian Zimmerman
• наб
• Thomas Klausner

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 file.c.

Macro Definition Documentation

MAX_LOCK_ATTEMPTS

#define MAX_LOCK_ATTEMPTS   5

Maximum number of attempts to lock a file.

Definition at line 74 of file file.c.

Function Documentation

stat_equal()

static bool stat_equal ( struct stat * st_old, struct stat * st_new )

static

Compare the struct stat's of two files/dirs.

Parameters

st_old	struct stat of the first file/dir
st_new	struct stat of the second file/dir

Return values

true	They match

This compares the device id (st_dev), inode number (st_ino) and special id (st_rdev) of the files/dirs.

Definition at line 85 of file file.c.

{
  return (st_old->st_dev == st_new->st_dev) && (st_old->st_ino == st_new->st_ino) &&
         (st_old->st_rdev == st_new->st_rdev);
}

Here is the caller graph for this function:

mutt_file_fclose_full()

int mutt_file_fclose_full	(	FILE **	fp,
		const char *	file,
		int	line,
		const char *	func )

Close a FILE handle (and NULL the pointer)

Parameters

[out]	fp	FILE handle to close
[in]	file	Source file
[in]	line	Source line number
[in]	func	Source function

Return values

0	Success
EOF	Error, see errno

Definition at line 100 of file file.c.

{
  if (!fp || !*fp)
    return 0;
 
  int fd = fileno(*fp);
  int rc = fclose(*fp);
 
  if (rc == 0)
  {
    MuttLogger(0, file, line, func, LL_DEBUG2, "File closed (fd=%d)\n", fd);
  }
  else
  {
    MuttLogger(0, file, line, func, LL_DEBUG2, "File close failed (fd=%d), errno=%d, %s\n",
               fd, errno, strerror(errno));
  }
 
  *fp = NULL;
  return rc;
}

mutt_file_fsync_close()

int mutt_file_fsync_close

(

FILE **

fp

)

Flush the data, before closing a file (and NULL the pointer)

Parameters

[out]

fp

FILE handle to close

Return values

0	Success
EOF	Error, see errno

Definition at line 128 of file file.c.

{
  if (!fp || !*fp)
    return 0;
 
  int rc = 0;
 
  if (fflush(*fp) || fsync(fileno(*fp)))
  {
    int save_errno = errno;
    rc = -1;
    mutt_file_fclose(fp);
    errno = save_errno;
  }
  else
  {
    rc = mutt_file_fclose(fp);
  }
 
  return rc;
}

Here is the caller graph for this function:

mutt_file_unlink()

void mutt_file_unlink

(

const char *

s

)

Delete a file, carefully.

Parameters

s

Filename

This won't follow symlinks.

Definition at line 156 of file file.c.

{
  if (!s)
    return;
 
  struct stat st = { 0 };
  /* Defend against symlink attacks */
 
  const bool is_regular_file = (lstat(s, &st) == 0) && S_ISREG(st.st_mode);
  if (!is_regular_file)
    return;
 
  const int fd = open(s, O_RDWR | O_NOFOLLOW);
  if (fd < 0)
    return;
 
  struct stat st2 = { 0 };
  if ((fstat(fd, &st2) != 0) || !S_ISREG(st2.st_mode) ||
      (st.st_dev != st2.st_dev) || (st.st_ino != st2.st_ino))
  {
    close(fd);
    return;
  }
 
  unlink(s);
  close(fd);
}

Here is the caller graph for this function:

mutt_file_copy_bytes()

int mutt_file_copy_bytes	(	FILE *	fp_in,
		FILE *	fp_out,
		size_t	size )

Copy some content from one file to another.

Parameters

fp_in	Source file
fp_out	Destination file
size	Maximum number of bytes to copy

Return values

0	Success
-1	Error, see errno

Definition at line 192 of file file.c.

{
  if (!fp_in || !fp_out)
    return -1;
 
  while (size > 0)
  {
    char buf[2048] = { 0 };
    size_t chunk = (size > sizeof(buf)) ? sizeof(buf) : size;
    chunk = fread(buf, 1, chunk, fp_in);
    if (chunk < 1)
      break;
    if (fwrite(buf, 1, chunk, fp_out) != chunk)
      return -1;
 
    size -= chunk;
  }
 
  if (fflush(fp_out) != 0)
    return -1;
  return 0;
}

Here is the caller graph for this function:

mutt_file_copy_stream()

int mutt_file_copy_stream	(	FILE *	fp_in,
		FILE *	fp_out )

Copy the contents of one file into another.

Parameters

fp_in	Source file
fp_out	Destination file

Return values

num	Success, number of bytes copied
-1	Error, see errno

Definition at line 222 of file file.c.

{
  if (!fp_in || !fp_out)
    return -1;
 
  size_t total = 0;
  size_t l;
  char buf[1024] = { 0 };
 
  while ((l = fread(buf, 1, sizeof(buf), fp_in)) > 0)
  {
    if (fwrite(buf, 1, l, fp_out) != l)
      return -1;
    total += l;
  }
 
  if (fflush(fp_out) != 0)
    return -1;
  return total;
}

Here is the caller graph for this function:

mutt_file_symlink()

int mutt_file_symlink	(	const char *	oldpath,
		const char *	newpath )

Create a symlink.

Parameters

oldpath	Existing pathname
newpath	New pathname

Return values

0	Success
-1	Error, see errno

Definition at line 250 of file file.c.

{
  struct stat st_old = { 0 };
  struct stat st_new = { 0 };
 
  if (!oldpath || !newpath)
    return -1;
 
  if ((unlink(newpath) == -1) && (errno != ENOENT))
    return -1;
 
  if (oldpath[0] == '/')
  {
    if (symlink(oldpath, newpath) == -1)
      return -1;
  }
  else
  {
    struct Buffer *abs_oldpath = buf_pool_get();
 
    if (!mutt_path_getcwd(abs_oldpath))
    {
      buf_pool_release(&abs_oldpath);
      return -1;
    }
 
    buf_addch(abs_oldpath, '/');
    buf_addstr(abs_oldpath, oldpath);
    if (symlink(buf_string(abs_oldpath), newpath) == -1)
    {
      buf_pool_release(&abs_oldpath);
      return -1;
    }
 
    buf_pool_release(&abs_oldpath);
  }
 
  if ((stat(oldpath, &st_old) == -1) || (stat(newpath, &st_new) == -1) ||
      !stat_equal(&st_old, &st_new))
  {
    unlink(newpath);
    return -1;
  }
 
  return 0;
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_file_safe_rename()

int mutt_file_safe_rename	(	const char *	src,
		const char *	target )

NFS-safe renaming of files.

Parameters

src	Original filename
target	New filename

Return values

0	Success
-1	Error, see errno

Warning: We don't check whether src and target are equal.

Definition at line 306 of file file.c.

{
  struct stat st_src = { 0 };
  struct stat st_target = { 0 };
  int link_errno;
 
  if (!src || !target)
    return -1;
 
  if (link(src, target) != 0)
  {
    link_errno = errno;
 
    /* It is historically documented that link can return -1 if NFS
     * dies after creating the link.  In that case, we are supposed
     * to use stat to check if the link was created.
     *
     * Derek Martin notes that some implementations of link() follow a
     * source symlink.  It might be more correct to use stat() on src.
     * I am not doing so to minimize changes in behavior: the function
     * used lstat() further below for 20 years without issue, and I
     * believe was never intended to be used on a src symlink.  */
    if ((lstat(src, &st_src) == 0) && (lstat(target, &st_target) == 0) &&
        (stat_equal(&st_src, &st_target) == 0))
    {
      mutt_debug(LL_DEBUG1, "link (%s, %s) reported failure: %s (%d) but actually succeeded\n",
                 src, target, strerror(errno), errno);
      goto success;
    }
 
    errno = link_errno;
 
    /* Coda does not allow cross-directory links, but tells
     * us it's a cross-filesystem linking attempt.
     *
     * However, the Coda rename call is allegedly safe to use.
     *
     * With other file systems, rename should just fail when
     * the files reside on different file systems, so it's safe
     * to try it here. */
    mutt_debug(LL_DEBUG1, "link (%s, %s) failed: %s (%d)\n", src, target,
               strerror(errno), errno);
 
    /* FUSE may return ENOSYS. VFAT may return EPERM. FreeBSD's
     * msdosfs may return EOPNOTSUPP.  ENOTSUP can also appear. */
    if ((errno == EXDEV) || (errno == ENOSYS) || errno == EPERM
#ifdef ENOTSUP
        || errno == ENOTSUP
#endif
#ifdef EOPNOTSUPP
        || errno == EOPNOTSUPP
#endif
    )
    {
      mutt_debug(LL_DEBUG1, "trying rename\n");
      if (rename(src, target) == -1)
      {
        mutt_debug(LL_DEBUG1, "rename (%s, %s) failed: %s (%d)\n", src, target,
                   strerror(errno), errno);
        return -1;
      }
      mutt_debug(LL_DEBUG1, "rename succeeded\n");
 
      return 0;
    }
 
    return -1;
  }
 
  /* Remove the stat_equal() check, because it causes problems with maildir
   * on filesystems that don't properly support hard links, such as sshfs.  The
   * filesystem creates the link, but the resulting file is given a different
   * inode number by the sshfs layer.  This results in an infinite loop
   * creating links.  */
#if 0
  /* Stat both links and check if they are equal. */
  if (lstat(src, &st_src) == -1)
  {
    mutt_debug(LL_DEBUG1, "#1 can't stat %s: %s (%d)\n", src, strerror(errno), errno);
    return -1;
  }
 
  if (lstat(target, &st_target) == -1)
  {
    mutt_debug(LL_DEBUG1, "#2 can't stat %s: %s (%d)\n", src, strerror(errno), errno);
    return -1;
  }
 
  /* pretend that the link failed because the target file did already exist. */
 
  if (!stat_equal(&st_src, &st_target))
  {
    mutt_debug(LL_DEBUG1, "stat blocks for %s and %s diverge; pretending EEXIST\n", src, target);
    errno = EEXIST;
    return -1;
  }
#endif
 
success:
  /* Unlink the original link.
   * Should we really ignore the return value here? XXX */
  if (unlink(src) == -1)
  {
    mutt_debug(LL_DEBUG1, "unlink (%s) failed: %s (%d)\n", src, strerror(errno), errno);
  }
 
  return 0;
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_file_rmtree()

int mutt_file_rmtree

(

const char *

path

)

Recursively remove a directory.

Parameters

path	Directory to delete

Return values

0	Success
-1	Error, see errno

Definition at line 421 of file file.c.

{
  if (!path)
    return -1;
 
  struct dirent *de = NULL;
  struct stat st = { 0 };
  int rc = 0;
 
  DIR *dir = mutt_file_opendir(path, MUTT_OPENDIR_NONE);
  if (!dir)
  {
    mutt_debug(LL_DEBUG1, "error opening directory %s\n", path);
    return -1;
  }
 
  /* We avoid using the buffer pool for this function, because it
   * invokes recursively to an unknown depth. */
  struct Buffer *cur = buf_pool_get();
 
  while ((de = readdir(dir)))
  {
    if ((mutt_str_equal(".", de->d_name)) || (mutt_str_equal("..", de->d_name)))
      continue;
 
    buf_printf(cur, "%s/%s", path, de->d_name);
    /* XXX make nonrecursive version */
 
    if (stat(buf_string(cur), &st) == -1)
    {
      rc = 1;
      continue;
    }
 
    if (S_ISDIR(st.st_mode))
      rc |= mutt_file_rmtree(buf_string(cur));
    else
      rc |= unlink(buf_string(cur));
  }
  closedir(dir);
 
  rc |= rmdir(path);
 
  buf_pool_release(&cur);
  return rc;
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_file_rotate()

const char * mutt_file_rotate	(	const char *	path,
		int	count )

Rotate a set of numbered files.

Parameters

path	Template filename
count	Maximum number of files

Return values

ptr	Name of the 0'th file

Given a template 'temp', rename files numbered 0 to (count-1).

Rename:

• ...
• temp1 -> temp2
• temp0 -> temp1

Definition at line 481 of file file.c.

{
  if (!path)
    return NULL;
 
  struct Buffer *old_file = buf_pool_get();
  struct Buffer *new_file = buf_pool_get();
 
  /* rotate the old debug logs */
  for (count -= 2; count >= 0; count--)
  {
    buf_printf(old_file, "%s%d", path, count);
    buf_printf(new_file, "%s%d", path, count + 1);
    (void) rename(buf_string(old_file), buf_string(new_file));
  }
 
  path = buf_strdup(old_file);
  buf_pool_release(&old_file);
  buf_pool_release(&new_file);
 
  return path;
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_file_open()

int mutt_file_open	(	const char *	path,
		uint32_t	flags,
		mode_t	mode )

Open a file.

Parameters

path	Pathname to open
flags	Flags, e.g. O_EXCL
mode	Permissions of the file (Relevant only when writing or appending)

Return values

>0	Success, file handle
-1	Error

Definition at line 512 of file file.c.

{
  if (!path)
    return -1;
 
  int fd = open(path, flags & ~O_EXCL, 0600);
  if (fd < 0)
    return -1;
 
  /* make sure the file is not symlink */
  struct stat st = { 0 };
  if ((lstat(path, &st) < 0) || S_ISLNK(st.st_mode))
  {
    close(fd);
    return -1;
  }
 
  return fd;
}

Here is the caller graph for this function:

mutt_file_opendir()

DIR * mutt_file_opendir	(	const char *	path,
		enum MuttOpenDirMode	mode )

Open a directory.

Parameters

path	Directory path
mode	See MuttOpenDirMode

Return values

ptr	DIR handle
NULL	Error, see errno

Definition at line 539 of file file.c.

{
  if ((mode == MUTT_OPENDIR_CREATE) && (mutt_file_mkdir(path, S_IRWXU) == -1))
  {
    return NULL;
  }
  errno = 0;
  return opendir(path);
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_file_fopen_full()

FILE * mutt_file_fopen_full	(	const char *	path,
		const char *	mode,
		const mode_t	perms,
		const char *	file,
		int	line,
		const char *	func )

Call fopen() safely.

Parameters

path	Filename
mode	Mode e.g. "r" readonly; "w" write-only; "a" append; "w+" read-write
perms	Permissions of the file (Relevant only when writing or appending)
file	Source file
line	Source line number
func	Source function

Return values

ptr	FILE handle
NULL	Error, see errno

Definition at line 560 of file file.c.

{
  if (!path || !mode)
    return NULL;
 
  FILE *fp = fopen(path, mode);
  if (fp)
  {
    MuttLogger(0, file, line, func, LL_DEBUG2, "File opened (fd=%d): %s\n",
               fileno(fp), path);
  }
  else
  {
    MuttLogger(0, file, line, func, LL_DEBUG2, "File open failed (errno=%d, %s): %s\n",
               errno, strerror(errno), path);
  }
 
  return fp;
}

Here is the caller graph for this function:

mutt_file_sanitize_filename()

void mutt_file_sanitize_filename	(	char *	path,
		bool	slash )

Replace unsafe characters in a filename.

Parameters

path	Filename to make safe
slash	Replace '/' characters too

Definition at line 586 of file file.c.

{
  if (!path)
    return;
 
  size_t size = strlen(path);
 
  wchar_t c;
  mbstate_t mbstate = { 0 };
  for (size_t consumed; size && (consumed = mbrtowc(&c, path, size, &mbstate));
       size -= consumed, path += consumed)
  {
    switch (consumed)
    {
      case ICONV_ILLEGAL_SEQ:
        mbstate = (mbstate_t) { 0 };
        consumed = 1;
        memset(path, '_', consumed);
        break;
 
      case ICONV_BUF_TOO_SMALL:
        consumed = size;
        memset(path, '_', consumed);
        break;
 
      default:
        if ((slash && (c == L'/')) || ((c <= 0x7F) && !strchr(FilenameSafeChars, c)))
        {
          memset(path, '_', consumed);
        }
        break;
    }
  }
}

Here is the caller graph for this function:

mutt_file_sanitize_regex()

int mutt_file_sanitize_regex	(	struct Buffer *	dest,
		const char *	src )

Escape any regex-magic characters in a string.

Parameters

dest	Buffer for result
src	String to transform

Return values

0	Success
-1	Error

Definition at line 628 of file file.c.

{
  if (!dest || !src)
    return -1;
 
  buf_reset(dest);
  while (*src != '\0')
  {
    if (strchr(RxSpecialChars, *src))
      buf_addch(dest, '\\');
    buf_addch(dest, *src++);
  }
 
  return 0;
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_file_seek()

bool mutt_file_seek	(	FILE *	fp,
		LOFF_T	offset,
		int	whence )

Wrapper for fseeko with error handling.

Parameters

[in]	fp	File to seek
[in]	offset	Offset
[in]	whence	Seek mode

Return values

true	Seek was successful
false	Seek failed

Definition at line 652 of file file.c.

{
  if (!fp)
  {
    return false;
  }
 
  if (fseeko(fp, offset, whence) != 0)
  {
    mutt_perror(_("Failed to seek file: %s"), strerror(errno));
    return false;
  }
 
  return true;
}

Here is the caller graph for this function:

mutt_file_read_line()

char * mutt_file_read_line	(	char *	line,
		size_t *	size,
		FILE *	fp,
		int *	line_num,
		ReadLineFlags	flags )

Read a line from a file.

Parameters

[out]	line	Buffer allocated on the head (optional)
[in]	size	Length of buffer
[in]	fp	File to read
[out]	line_num	Current line number (optional)
[in]	flags	Flags, e.g. MUTT_RL_CONT

Return values

ptr	The allocated string

Read a line from "fp" into the dynamically allocated "line", increasing "line" if necessary. The ending "\n" or "\r\n" is removed. If a line ends with "\", this char and the linefeed is removed, and the next line is read too.

Definition at line 682 of file file.c.

{
  if (!size || !fp)
    return NULL;
 
  size_t offset = 0;
  char *ch = NULL;
 
  if (!line)
  {
    *size = 256;
    line = MUTT_MEM_MALLOC(*size, char);
  }
 
  while (true)
  {
    if (!fgets(line + offset, *size - offset, fp))
    {
      FREE(&line);
      return NULL;
    }
    ch = strchr(line + offset, '\n');
    if (ch)
    {
      if (line_num)
        (*line_num)++;
      if (flags & MUTT_RL_EOL)
        return line;
      *ch = '\0';
      if ((ch > line) && (*(ch - 1) == '\r'))
        *--ch = '\0';
      if (!(flags & MUTT_RL_CONT) || (ch == line) || (*(ch - 1) != '\\'))
        return line;
      offset = ch - line - 1;
    }
    else
    {
      int c;
      c = getc(fp); /* This is kind of a hack. We want to know if the
                        char at the current point in the input stream is EOF.
                        feof() will only tell us if we've already hit EOF, not
                        if the next character is EOF. So, we need to read in
                        the next character and manually check if it is EOF. */
      if (c == EOF)
      {
        /* The last line of fp isn't \n terminated */
        if (line_num)
          (*line_num)++;
        return line;
      }
      else
      {
        ungetc(c, fp); /* undo our damage */
        /* There wasn't room for the line -- increase "line" */
        offset = *size - 1; /* overwrite the terminating 0 */
        *size += 256;
        MUTT_MEM_REALLOC(&line, *size, char);
      }
    }
  }
}

Here is the caller graph for this function:

mutt_file_iter_line()

bool mutt_file_iter_line	(	struct MuttFileIter *	iter,
		FILE *	fp,
		ReadLineFlags	flags )

Iterate over the lines from an open file pointer.

Parameters

iter	State of iteration including ptr to line
fp	File pointer to read from
flags	Same as mutt_file_read_line()

Return values

true	Data read
false	On eof

This is a slightly cleaner interface for mutt_file_read_line() which avoids the eternal C loop initialization ugliness. Use like this:

struct MuttFileIter iter = { 0 };
while (mutt_file_iter_line(&iter, fp, flags))
{
  do_stuff(iter.line, iter.line_num);
}

Definition at line 763 of file file.c.

{
  if (!iter)
    return false;
 
  char *p = mutt_file_read_line(iter->line, &iter->size, fp, &iter->line_num, flags);
  if (!p)
    return false;
  iter->line = p;
  return true;
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_file_map_lines()

bool mutt_file_map_lines	(	mutt_file_map_t	func,
		void *	user_data,
		FILE *	fp,
		ReadLineFlags	flags )

Process lines of text read from a file pointer.

Parameters

func	Callback function to call for each line, see mutt_file_map_t
user_data	Arbitrary data passed to "func"
fp	File pointer to read from
flags	Same as mutt_file_read_line()

Return values

true	All data mapped
false	"func" returns false

Definition at line 784 of file file.c.

{
  if (!func || !fp)
    return false;
 
  struct MuttFileIter iter = { 0 };
  while (mutt_file_iter_line(&iter, fp, flags))
  {
    if (!(*func)(iter.line, iter.line_num, user_data))
    {
      FREE(&iter.line);
      return false;
    }
  }
  return true;
}

Here is the call graph for this function:

Here is the caller graph for this function:

buf_quote_filename()

void buf_quote_filename	(	struct Buffer *	buf,
		const char *	filename,
		bool	add_outer )

Quote a filename to survive the shell's quoting rules.

Parameters

buf	Buffer for the result
filename	String to convert
add_outer	If true, add 'single quotes' around the result

Definition at line 807 of file file.c.

{
  if (!buf || !filename)
    return;
 
  buf_reset(buf);
  if (add_outer)
    buf_addch(buf, '\'');
 
  for (; *filename != '\0'; filename++)
  {
    if ((*filename == '\'') || (*filename == '`'))
    {
      buf_addch(buf, '\'');
      buf_addch(buf, '\\');
      buf_addch(buf, *filename);
      buf_addch(buf, '\'');
    }
    else
    {
      buf_addch(buf, *filename);
    }
  }
 
  if (add_outer)
    buf_addch(buf, '\'');
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_file_mkdir()

int mutt_file_mkdir	(	const char *	path,
		mode_t	mode )

Recursively create directories.

Parameters

path	Directories to create
mode	Permissions for final directory

Return values

0	Success
-1	Error (errno set)

Create a directory, creating the parents if necessary. (like mkdir -p)

Note

The permissions are only set on the final directory. The permissions of any parent directories are determined by the umask. (This is how "mkdir -p" behaves)

Definition at line 848 of file file.c.

{
  if (!path || (*path == '\0'))
  {
    errno = EINVAL;
    return -1;
  }
 
  errno = 0;
  char tmp_path[PATH_MAX] = { 0 };
  const size_t len = strlen(path);
 
  if (len >= sizeof(tmp_path))
  {
    errno = ENAMETOOLONG;
    return -1;
  }
 
  struct stat st = { 0 };
  if ((stat(path, &st) == 0) && S_ISDIR(st.st_mode))
    return 0;
 
  /* Create a mutable copy */
  mutt_str_copy(tmp_path, path, sizeof(tmp_path));
 
  for (char *p = tmp_path + 1; *p; p++)
  {
    if (*p != '/')
      continue;
 
    /* Temporarily truncate the path */
    *p = '\0';
 
    if ((mkdir(tmp_path, S_IRWXU | S_IRWXG | S_IRWXO) != 0) && (errno != EEXIST))
      return -1;
 
    *p = '/';
  }
 
  if ((mkdir(tmp_path, mode) != 0) && (errno != EEXIST))
    return -1;
 
  return 0;
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_file_decrease_mtime()

time_t mutt_file_decrease_mtime	(	const char *	fp,
		struct stat *	st )

Decrease a file's modification time by 1 second.

Parameters

fp	Filename
st	struct stat for the file (optional)

Return values

num	Updated Unix mtime
-1	Error, see errno

If a file's mtime is NOW, then set it to 1 second in the past.

Definition at line 902 of file file.c.

{
  if (!fp)
    return -1;
 
  struct utimbuf utim = { 0 };
  struct stat st2 = { 0 };
  time_t mtime;
 
  if (!st)
  {
    if (stat(fp, &st2) == -1)
      return -1;
    st = &st2;
  }
 
  mtime = st->st_mtime;
  if (mtime == mutt_date_now())
  {
    mtime -= 1;
    utim.actime = mtime;
    utim.modtime = mtime;
    int rc;
    do
    {
      rc = utime(fp, &utim);
    } while ((rc == -1) && (errno == EINTR));
 
    if (rc == -1)
      return -1;
  }
 
  return mtime;
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_file_set_mtime()

void mutt_file_set_mtime	(	const char *	from,
		const char *	to )

Set the modification time of one file from another.

Parameters

from	Filename whose mtime should be copied
to	Filename to update

Definition at line 942 of file file.c.

{
  if (!from || !to)
    return;
 
  struct utimbuf utim = { 0 };
  struct stat st = { 0 };
 
  if (stat(from, &st) != -1)
  {
    utim.actime = st.st_mtime;
    utim.modtime = st.st_mtime;
    utime(to, &utim);
  }
}

Here is the caller graph for this function:

mutt_file_touch_atime()

void mutt_file_touch_atime

(

int

fd

)

Set the access time to current time.

Parameters

fd	File descriptor of the file to alter

This is just as read() would do on !noatime. Silently ignored if futimens() isn't supported.

Definition at line 965 of file file.c.

{
#ifdef HAVE_FUTIMENS
  struct timespec times[2] = { { 0, UTIME_NOW }, { 0, UTIME_OMIT } };
  futimens(fd, times);
#endif
}

Here is the caller graph for this function:

mutt_file_touch()

bool mutt_file_touch

(

const char *

path

)

Make sure a file exists.

Parameters

path

Filename

Return values

true	if succeeded

Definition at line 978 of file file.c.

{
  FILE *fp = mutt_file_fopen(path, "w");
  if (!fp)
  {
    return false;
  }
  mutt_file_fclose(&fp);
  return true;
}

Here is the caller graph for this function:

mutt_file_chmod_add()

int mutt_file_chmod_add	(	const char *	path,
		mode_t	mode )

Add permissions to a file.

Parameters

path	Filename
mode	the permissions to add

Return values

num	Same as chmod(2)

Adds the given permissions to the file. Permissions not mentioned in mode will stay as they are. This function resembles the chmod ugoa+rwxXst command family. Example:

mutt_file_chmod_add(path, S_IWUSR | S_IWGRP | S_IWOTH);

will add write permissions to path but does not alter read and other permissions.

See also

mutt_file_chmod_add_stat()

Definition at line 1006 of file file.c.

{
  return mutt_file_chmod_add_stat(path, mode, NULL);
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_file_chmod_add_stat()

int mutt_file_chmod_add_stat	(	const char *	path,
		mode_t	mode,
		struct stat *	st )

Add permissions to a file.

Parameters

path	Filename
mode	the permissions to add
st	struct stat for the file (optional)

Return values

num	Same as chmod(2)

Same as mutt_file_chmod_add() but saves a system call to stat() if a non-NULL stat structure is given. Useful if the stat structure of the file was retrieved before by the calling code. Example:

struct stat st;
stat(path, &st);
// ... do something else with st ...
mutt_file_chmod_add_stat(path, S_IWUSR | S_IWGRP | S_IWOTH, st);

See also

mutt_file_chmod_add()

Definition at line 1029 of file file.c.

{
  if (!path)
    return -1;
 
  struct stat st2 = { 0 };
 
  if (!st)
  {
    if (stat(path, &st2) == -1)
      return -1;
    st = &st2;
  }
  return chmod(path, st->st_mode | mode);
}

Here is the caller graph for this function:

mutt_file_chmod_rm_stat()

int mutt_file_chmod_rm_stat	(	const char *	path,
		mode_t	mode,
		struct stat *	st )

Remove permissions from a file.

Parameters

path	Filename
mode	the permissions to remove
st	struct stat for the file (optional)

Return values

num	Same as chmod(2)

Same as mutt_file_chmod_rm() but saves a system call to stat() if a non-NULL stat structure is given. Useful if the stat structure of the file was retrieved before by the calling code. Example:

struct stat st;
stat(path, &st);
// ... do something else with st ...
mutt_file_chmod_rm_stat(path, S_IWUSR | S_IWGRP | S_IWOTH, st);

See also

mutt_file_chmod_rm()

Definition at line 1063 of file file.c.

{
  if (!path)
    return -1;
 
  struct stat st2 = { 0 };
 
  if (!st)
  {
    if (stat(path, &st2) == -1)
      return -1;
    st = &st2;
  }
  return chmod(path, st->st_mode & ~mode);
}

Here is the caller graph for this function:

mutt_file_lock()

int mutt_file_lock	(	int	fd,
		bool	excl,
		bool	timeout )

(Try to) Lock a file using fcntl()

Parameters

fd	File descriptor to file
excl	If true, try to lock exclusively
timeout	If true, Retry MAX_LOCK_ATTEMPTS times

Return values

0	Success
-1	Failure

Use fcntl() to lock a file.

Use mutt_file_unlock() to unlock the file.

Definition at line 1092 of file file.c.

{
  struct stat st = { 0 }, prev_sb = { 0 };
  int count = 0;
  int attempt = 0;
 
  struct flock lck = { 0 };
  lck.l_type = excl ? F_WRLCK : F_RDLCK;
  lck.l_whence = SEEK_SET;
 
  while (fcntl(fd, F_SETLK, &lck) == -1)
  {
    mutt_debug(LL_DEBUG1, "fcntl errno %d\n", errno);
    if ((errno != EAGAIN) && (errno != EACCES))
    {
      mutt_perror("fcntl");
      return -1;
    }
 
    if (fstat(fd, &st) != 0)
      st.st_size = 0;
 
    if (count == 0)
      prev_sb = st;
 
    /* only unlock file if it is unchanged */
    if ((prev_sb.st_size == st.st_size) && (++count >= (timeout ? MAX_LOCK_ATTEMPTS : 0)))
    {
      if (timeout)
        mutt_error(_("Timeout exceeded while attempting fcntl lock"));
      return -1;
    }
 
    prev_sb = st;
 
    mutt_message(_("Waiting for fcntl lock... %d"), ++attempt);
    sleep(1);
  }
 
  return 0;
}

Here is the caller graph for this function:

mutt_file_unlock()

int mutt_file_unlock

(

int

fd

)

Unlock a file previously locked by mutt_file_lock()

Parameters

fd	File descriptor to file

Return values

0

Always

Definition at line 1139 of file file.c.

{
  struct flock unlockit = { 0 };
  unlockit.l_type = F_UNLCK;
  unlockit.l_whence = SEEK_SET;
  (void) fcntl(fd, F_SETLK, &unlockit);
 
  return 0;
}

Here is the caller graph for this function:

mutt_file_unlink_empty()

void mutt_file_unlink_empty

(

const char *

path

)

Delete a file if it's empty.

Parameters

path	File to delete

Definition at line 1225 of file file.c.

{
  if (!path)
    return;
 
  struct stat st = { 0 };
 
  int fd = open(path, O_RDWR);
  if (fd == -1)
    return;
 
  if (mutt_file_lock(fd, true, true) == -1)
  {
    close(fd);
    return;
  }
 
  if ((fstat(fd, &st) == 0) && (st.st_size == 0))
    unlink(path);
 
  mutt_file_unlock(fd);
  close(fd);
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_file_rename()

int mutt_file_rename	(	const char *	oldfile,
		const char *	newfile )

Rename a file.

Parameters

oldfile	Old filename
newfile	New filename

Return values

0	Success
1	Old file doesn't exist
2	New file already exists
3	Some other error

Note

on access(2) use No dangling symlink problems here due to mutt_file_fopen().

Definition at line 1261 of file file.c.

{
  if (!oldfile || !newfile)
    return -1;
  if (access(oldfile, F_OK) != 0)
    return 1;
  if (access(newfile, F_OK) == 0)
    return 2;
 
  FILE *fp_old = mutt_file_fopen(oldfile, "r");
  if (!fp_old)
    return 3;
  FILE *fp_new = mutt_file_fopen(newfile, "w");
  if (!fp_new)
  {
    mutt_file_fclose(&fp_old);
    return 3;
  }
  mutt_file_copy_stream(fp_old, fp_new);
  mutt_file_fclose(&fp_new);
  mutt_file_fclose(&fp_old);
  mutt_file_unlink(oldfile);
  return 0;
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_file_read_keyword()

char * mutt_file_read_keyword	(	const char *	file,
		char *	buf,
		size_t	buflen )

Read a keyword from a file.

Parameters

file	File to read
buf	Buffer to store the keyword
buflen	Length of the buf

Return values

ptr	Start of the keyword

Read one line from the start of a file. Skip any leading whitespace and extract the first token.

Definition at line 1296 of file file.c.

{
  FILE *fp = mutt_file_fopen(file, "r");
  if (!fp)
    return NULL;
 
  buf = fgets(buf, buflen, fp);
  mutt_file_fclose(&fp);
 
  if (!buf)
    return NULL;
 
  SKIPWS(buf);
  char *start = buf;
 
  while ((*buf != '\0') && !mutt_isspace(*buf))
    buf++;
 
  *buf = '\0';
 
  return start;
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_file_check_empty()

int mutt_file_check_empty

(

const char *

path

)

Is the mailbox empty.

Parameters

path	Path to mailbox

Return values

1	Mailbox is empty
0	Mailbox is not empty
-1	Error

Definition at line 1326 of file file.c.

{
  if (!path)
    return -1;
 
  struct stat st = { 0 };
  if (stat(path, &st) == -1)
    return -1;
 
  return st.st_size == 0;
}

Here is the caller graph for this function:

buf_file_expand_fmt_quote()

void buf_file_expand_fmt_quote	(	struct Buffer *	dest,
		const char *	fmt,
		const char *	src )

Replace s in a string with a filename.

Parameters

dest	Buffer for the result
fmt	printf-like format string
src	Filename to substitute

This function also quotes the file to prevent shell problems.

Definition at line 1346 of file file.c.

{
  struct Buffer *tmp = buf_pool_get();
 
  buf_quote_filename(tmp, src, true);
  mutt_file_expand_fmt(dest, fmt, buf_string(tmp));
  buf_pool_release(&tmp);
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_file_expand_fmt()

void mutt_file_expand_fmt	(	struct Buffer *	dest,
		const char *	fmt,
		const char *	src )

Replace s in a string with a filename.

Parameters

dest	Buffer for the result
fmt	printf-like format string
src	Filename to substitute

Definition at line 1361 of file file.c.

{
  if (!dest || !fmt || !src)
    return;
 
  const char *p = NULL;
  bool found = false;
 
  buf_reset(dest);
 
  for (p = fmt; *p; p++)
  {
    if (*p == '%')
    {
      switch (p[1])
      {
        case '%':
          buf_addch(dest, *p++);
          break;
        case 's':
          found = true;
          buf_addstr(dest, src);
          p++;
          break;
        default:
          buf_addch(dest, *p);
          break;
      }
    }
    else
    {
      buf_addch(dest, *p);
    }
  }
 
  if (!found)
  {
    buf_addch(dest, ' ');
    buf_addstr(dest, src);
  }
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_file_get_size()

long mutt_file_get_size

(

const char *

path

)

Get the size of a file.

Parameters

path	File to measure

Return values

num	Size in bytes
0	Error

Definition at line 1409 of file file.c.

{
  if (!path)
    return 0;
 
  struct stat st = { 0 };
  if (stat(path, &st) != 0)
    return 0;
 
  return st.st_size;
}

Here is the caller graph for this function:

mutt_file_get_size_fp()

long mutt_file_get_size_fp

(

FILE *

fp

)

Get the size of a file.

Parameters

fp	FILE* to measure

Return values

num	Size in bytes
0	Error

Definition at line 1427 of file file.c.

{
  if (!fp)
    return 0;
 
  struct stat st = { 0 };
  if (fstat(fileno(fp), &st) != 0)
    return 0;
 
  return st.st_size;
}

Here is the caller graph for this function:

mutt_file_timespec_compare()

int mutt_file_timespec_compare	(	struct timespec *	a,
		struct timespec *	b )

Compare to time values.

Parameters

a	First time value
b	Second time value

Return values

-1	a precedes b
0	a and b are identical
1	b precedes a

Definition at line 1447 of file file.c.

{
  if (!a || !b)
    return 0;
  if (a->tv_sec < b->tv_sec)
    return -1;
  if (a->tv_sec > b->tv_sec)
    return 1;
 
  if (a->tv_nsec < b->tv_nsec)
    return -1;
  if (a->tv_nsec > b->tv_nsec)
    return 1;
  return 0;
}

Here is the caller graph for this function:

mutt_file_get_stat_timespec()

void mutt_file_get_stat_timespec	(	struct timespec *	dest,
		struct stat *	st,
		enum MuttStatType	type )

Read the stat() time into a time value.

Parameters

dest	Time value to populate
st	stat info
type	Type of stat info to read, e.g. MUTT_STAT_ATIME

Definition at line 1469 of file file.c.

{
  if (!dest || !st)
    return;
 
  dest->tv_sec = 0;
  dest->tv_nsec = 0;
 
  switch (type)
  {
    case MUTT_STAT_ATIME:
      dest->tv_sec = st->st_atime;
#ifdef HAVE_STRUCT_STAT_ST_ATIM_TV_NSEC
      dest->tv_nsec = st->st_atim.tv_nsec;
#endif
      break;
    case MUTT_STAT_MTIME:
      dest->tv_sec = st->st_mtime;
#ifdef HAVE_STRUCT_STAT_ST_MTIM_TV_NSEC
      dest->tv_nsec = st->st_mtim.tv_nsec;
#endif
      break;
    case MUTT_STAT_CTIME:
      dest->tv_sec = st->st_ctime;
#ifdef HAVE_STRUCT_STAT_ST_CTIM_TV_NSEC
      dest->tv_nsec = st->st_ctim.tv_nsec;
#endif
      break;
  }
}

Here is the caller graph for this function:

mutt_file_stat_timespec_compare()

int mutt_file_stat_timespec_compare	(	struct stat *	st,
		enum MuttStatType	type,
		struct timespec *	b )

Compare stat info with a time value.

Parameters

st	stat info
type	Type of stat info, e.g. MUTT_STAT_ATIME
b	Time value

Return values

-1	a precedes b
0	a and b are identical
1	b precedes a

Definition at line 1509 of file file.c.

{
  if (!st || !b)
    return 0;
 
  struct timespec a = { 0 };
 
  mutt_file_get_stat_timespec(&a, st, type);
  return mutt_file_timespec_compare(&a, b);
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_file_stat_compare()

int mutt_file_stat_compare	(	struct stat *	st1,
		enum MuttStatType	st1_type,
		struct stat *	st2,
		enum MuttStatType	st2_type )

Compare two stat infos.

Parameters

st1	First stat info
st1_type	Type of first stat info, e.g. MUTT_STAT_ATIME
st2	Second stat info
st2_type	Type of second stat info, e.g. MUTT_STAT_ATIME

Return values

-1	a precedes b
0	a and b are identical
1	b precedes a

Definition at line 1531 of file file.c.

{
  if (!st1 || !st2)
    return 0;
 
  struct timespec a = { 0 };
  struct timespec b = { 0 };
 
  mutt_file_get_stat_timespec(&a, st1, st1_type);
  mutt_file_get_stat_timespec(&b, st2, st2_type);
  return mutt_file_timespec_compare(&a, &b);
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_file_resolve_symlink()

void mutt_file_resolve_symlink

(

struct Buffer *

buf

)

Resolve a symlink in place.

Parameters

buf	Input/output path

Definition at line 1549 of file file.c.

{
  struct stat st = { 0 };
  int rc = lstat(buf_string(buf), &st);
  if ((rc != -1) && S_ISLNK(st.st_mode))
  {
    char path[PATH_MAX] = { 0 };
    if (realpath(buf_string(buf), path))
    {
      buf_strcpy(buf, path);
    }
  }
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_file_save_str()

size_t mutt_file_save_str	(	FILE *	fp,
		const char *	str )

Save a string to a file.

Parameters

fp	Open file to save to
str	String to save

Return values

num	Bytes written to file

Definition at line 1569 of file file.c.

{
  if (!fp)
    return 0;
 
  size_t len = mutt_str_len(str);
  if (len == 0)
    return 0;
 
  return fwrite(str, 1, len, fp);
}

Here is the call graph for this function:

Here is the caller graph for this function:

Variable Documentation

RxSpecialChars

const char RxSpecialChars[] = "^.[$()|*+?{\\"

static

These characters must be escaped in regular expressions.

Definition at line 68 of file file.c.

FilenameSafeChars

const char FilenameSafeChars[] = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+@{}._-:%/"

Set of characters <=0x7F that are safe to use in filenames.

Definition at line 71 of file file.c.