File.h

Go to the documentation of this file.

/*
 * Copyright (C) 1996-2025 The Squid Software Foundation and contributors
 *
 * Squid software is distributed under GPLv2+ license and includes
 * contributions from numerous individuals and organizations.
 * Please see the COPYING and CONTRIBUTORS files for details.
 */
 
#ifndef SQUID_SRC_BASE_FILE_H
#define SQUID_SRC_BASE_FILE_H
 
#include "sbuf/SBuf.h"
 
#if HAVE_SYS_FILE_H
#include <sys/file.h>
#endif
 
class FileOpeningConfig
{
public:
    static FileOpeningConfig ReadOnly(); // shared reading
    static FileOpeningConfig ReadWrite(); // exclusive creation and/or reading/writing
 
    /* adjustment methods; named to work well with the File::Be::X shorthand */
 
    FileOpeningConfig &locked(unsigned int attempts = 5);
 
    FileOpeningConfig &createdIfMissing();
 
    FileOpeningConfig &openedByRoot() { openByRoot = true; return *this; }
 
    /* add more mode adjustment methods as needed */
 
private:
    friend class File;
 
    /* file opening parameters */
#if _SQUID_WINDOWS_ || _SQUID_MINGW_
    DWORD desiredAccess = 0; 
    DWORD shareMode = 0; 
    DWORD creationDisposition = OPEN_EXISTING; 
#else
    mode_t creationMask = 0; 
    int openFlags = 0; 
    mode_t openMode = 0644; 
#endif
 
    /* file locking (disabled unless lock(n) sets positive lockAttempts) */
#if _SQUID_WINDOWS_ || _SQUID_MINGW_
    DWORD lockFlags = 0; 
#elif _SQUID_SOLARIS_
    int lockType = F_UNLCK; 
#else
    int flockMode = LOCK_UN; 
#endif
    const unsigned int retryGapUsec = 500000; 
    unsigned int lockAttempts = 0; 
    bool openByRoot = false;
};
 
class File
{
public:
    typedef FileOpeningConfig Be; 
 
    static File *Optional(const SBuf &aName, const FileOpeningConfig &cfg);
 
    File(const SBuf &aFilename, const FileOpeningConfig &cfg); 
    ~File(); 
 
    /* can move but cannot copy */
    File(const File &) = delete;
    File &operator = (const File &) = delete;
    File(File &&other);
    File &operator = (File &&other);
 
    const SBuf &name() const { return name_; }
 
    /* system call wrappers */
 
    void truncate();
    SBuf readSmall(SBuf::size_type minBytes, SBuf::size_type maxBytes); 
    void writeAll(const SBuf &data); 
    void synchronize(); 
 
protected:
    bool isOpen() const {
#if _SQUID_WINDOWS_ || _SQUID_MINGW_
        return fd_ != InvalidHandle;
#else
        return fd_ >= 0;
#endif
    }
 
    void open(const FileOpeningConfig &cfg);
    void lock(const FileOpeningConfig &cfg);
    void lockOnce(const FileOpeningConfig &cfg);
    void close();
 
    SBuf sysCallFailure(const char *callName, const SBuf &error) const;
    SBuf sysCallError(const char *callName, const int savedErrno) const;
 
private:
    SBuf name_; 
 
    // Windows-specific HANDLE is needed because LockFileEx() does not take POSIX FDs.
#if _SQUID_WINDOWS_ || _SQUID_MINGW_
    typedef HANDLE Handle;
    static const Handle InvalidHandle;
#else
    typedef int Handle;
    static const Handle InvalidHandle = -1;
#endif
    Handle fd_ = InvalidHandle; 
};
 
#endif /* SQUID_SRC_BASE_FILE_H */