File.h
Go to the documentation of this file.
1 /*
2  * Copyright (C) 1996-2017 The Squid Software Foundation and contributors
3  *
4  * Squid software is distributed under GPLv2+ license and includes
5  * contributions from numerous individuals and organizations.
6  * Please see the COPYING and CONTRIBUTORS files for details.
7  */
8 
9 #ifndef SQUID_BASE_FILE_H
10 #define SQUID_BASE_FILE_H
11 
12 #include "sbuf/SBuf.h"
13 
14 #if HAVE_SYS_FILE_H
15 #include <sys/file.h>
16 #endif
17 
20 {
21 public:
22  static FileOpeningConfig ReadOnly(); // shared reading
23  static FileOpeningConfig ReadWrite(); // exclusive creation and/or reading/writing
24 
25  /* adjustment methods; named to work well with the File::Be::X shorthand */
26 
28  FileOpeningConfig &locked(unsigned int attempts = 5);
29 
32 
34  FileOpeningConfig &openedByRoot() { openByRoot = true; return *this; }
35 
36  /* add more mode adjustment methods as needed */
37 
38 private:
39  friend class File;
40 
41  /* file opening parameters */
42 #if _SQUID_WINDOWS_
43  DWORD desiredAccess = 0;
44  DWORD shareMode = 0;
45  DWORD creationDisposition = OPEN_EXISTING;
46 #else
48  int openFlags = 0;
49  mode_t openMode = 0644;
50 #endif
51 
52  /* file locking (disabled unless lock(n) sets positive lockAttempts) */
53 #if _SQUID_WINDOWS_
54  DWORD lockFlags = 0;
55 #elif _SQUID_SOLARIS_
56  int lockType = F_UNLCK;
57 #else
58  int flockMode = LOCK_UN;
59 #endif
60  static const unsigned int RetryGapUsec = 500000;
61  unsigned int lockAttempts = 0;
62  bool openByRoot = false;
63 };
64 
66 class File
67 {
68 public:
70 
72  static File *Optional(const SBuf &aName, const FileOpeningConfig &cfg);
73 
74  File(const SBuf &aFilename, const FileOpeningConfig &cfg);
75  ~File();
76 
77  /* can move but cannot copy */
78  File(const File &) = delete;
79  File &operator = (const File &) = delete;
80  File(File &&other);
81  File &operator = (File &&other);
82 
83  const SBuf &name() const { return name_; }
84 
85  /* system call wrappers */
86 
88  void truncate();
89  SBuf readSmall(SBuf::size_type minBytes, SBuf::size_type maxBytes);
90  void writeAll(const SBuf &data);
91  void synchronize();
92 
93 protected:
94  bool isOpen() const {
95 #if _SQUID_WINDOWS_
96  return fd_ != InvalidHandle;
97 #else
98  return fd_ >= 0;
99 #endif
100  }
101 
102  void open(const FileOpeningConfig &cfg);
103  void lock(const FileOpeningConfig &cfg);
104  void lockOnce(const FileOpeningConfig &cfg);
105  void close();
106 
108  SBuf sysCallFailure(const char *callName, const char *error) const;
110  SBuf sysCallError(const char *callName, const int savedErrno) const;
111 
112 private:
114 
115  // Windows-specific HANDLE is needed because LockFileEx() does not take POSIX FDs.
116 #if _SQUID_WINDOWS_
117  typedef HANDLE Handle;
118  static const Handle InvalidHandle = INVALID_HANDLE_VALUE;
119 #else
120  typedef int Handle;
121  static const Handle InvalidHandle = -1;
122 #endif
124 };
125 
126 #endif
127 
static const Handle InvalidHandle
Definition: File.h:121
void truncate()
makes the file size (and the current I/O offset) zero
Definition: File.cc:214
int Handle
Definition: File.h:120
static File * Optional(const SBuf &aName, const FileOpeningConfig &cfg)
Definition: File.cc:123
Definition: SBuf.h:87
void error(char *format,...)
FileOpeningConfig & openedByRoot()
enter_suid() to open the file; leaves suid ASAP after that
Definition: File.h:34
How should a file be opened/created? Should it be locked?
Definition: File.h:19
const SBuf & name() const
Definition: File.h:83
File & operator=(const File &)=delete
void lockOnce(const FileOpeningConfig &cfg)
locks, blocking or returning immediately depending on the lock waiting mode
Definition: File.cc:338
FileOpeningConfig Be
convenient shorthand for File() callers
Definition: File.h:69
void const char HLPCB void * data
Definition: stub_helper.cc:16
void open(const FileOpeningConfig &cfg)
opens (or creates) the file
Definition: File.cc:170
a portable locking-aware exception-friendly file (with RAII API)
Definition: File.h:66
~File()
closes
Definition: File.cc:150
SBuf name_
location on disk
Definition: File.h:113
File(const SBuf &aFilename, const FileOpeningConfig &cfg)
opens
Definition: File.cc:134
bool openByRoot
Definition: File.h:62
SBuf sysCallFailure(const char *callName, const char *error) const
Definition: File.cc:361
SBuf sysCallError(const char *callName, const int savedErrno) const
Definition: File.cc:368
unsigned short mode_t
Definition: types.h:150
SBuf readSmall(SBuf::size_type minBytes, SBuf::size_type maxBytes)
read(2) for small files
Definition: File.cc:240
typedef DWORD
Definition: WinSvc.cc:73
mode_t creationMask
umask() parameter; the default is S_IWGRP|S_IWOTH
Definition: File.h:47
void writeAll(const SBuf &data)
write(2) with a "wrote everything" check
Definition: File.cc:278
void synchronize()
fsync(2)
Definition: File.cc:300
int flockMode
2nd flock(2) parameter
Definition: File.h:58
unsigned int lockAttempts
pause before each lock retry
Definition: File.h:61
int openFlags
opening flags; 2nd open(2) parameter
Definition: File.h:48
void close()
Definition: File.cc:195
static const unsigned int RetryGapUsec
Definition: File.h:60
MemBlob::size_type size_type
Definition: SBuf.h:90
mode_t openMode
access mode; 3rd open(2) parameter
Definition: File.h:49
static FileOpeningConfig ReadWrite()
Definition: File.cc:56
bool isOpen() const
Definition: File.h:94
FileOpeningConfig & createdIfMissing()
when opening a file for writing, create it if it does not exist
Definition: File.cc:89
FileOpeningConfig & locked(unsigned int attempts=5)
protect concurrent accesses by attempting to obtain an appropriate lock
Definition: File.cc:81
static FileOpeningConfig ReadOnly()
Definition: File.cc:31
Handle fd_
OS-specific file handle.
Definition: File.h:123
void lock(const FileOpeningConfig &cfg)
calls lockOnce() as many times as necessary (including zero)
Definition: File.cc:317

 

Introduction

Documentation

Support

Miscellaneous

Web Site Translations

Mirrors