1 //
2 // Copyright (C) 2012 The Android Open Source Project
3 //
4 // Licensed under the Apache License, Version 2.0 (the "License");
5 // you may not use this file except in compliance with the License.
6 // You may obtain a copy of the License at
7 //
8 //      http://www.apache.org/licenses/LICENSE-2.0
9 //
10 // Unless required by applicable law or agreed to in writing, software
11 // distributed under the License is distributed on an "AS IS" BASIS,
12 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 // See the License for the specific language governing permissions and
14 // limitations under the License.
15 //
16 
17 #ifndef UPDATE_ENGINE_PAYLOAD_CONSUMER_FILE_DESCRIPTOR_H_
18 #define UPDATE_ENGINE_PAYLOAD_CONSUMER_FILE_DESCRIPTOR_H_
19 
20 #include <errno.h>
21 #include <sys/types.h>
22 #include <memory>
23 
24 #include <base/logging.h>
25 
26 // Abstraction for managing opening, reading, writing and closing of file
27 // descriptors. This includes an abstract class and one standard implementation
28 // based on POSIX system calls.
29 //
30 // TODO(garnold) this class is modeled after (and augments the functionality of)
31 // the FileWriter class; ultimately, the latter should be replaced by the former
32 // throughout the codebase.  A few deviations from the original FileWriter:
33 //
34 // * Providing two flavors of Open()
35 //
36 // * A FileDescriptor is reusable and can be used to read/write multiple files
37 //   as long as open/close preconditions are respected.
38 //
39 // * Write() returns the number of bytes written: this appears to be more useful
40 //   for clients, who may wish to retry or otherwise do something useful with
41 //   the remaining data that was not written.
42 
43 namespace chromeos_update_engine {
44 
45 class FileDescriptor;
46 using FileDescriptorPtr = std::shared_ptr<FileDescriptor>;
47 
48 // An abstract class defining the file descriptor API.
49 class FileDescriptor {
50  public:
FileDescriptor()51   FileDescriptor() {}
~FileDescriptor()52   virtual ~FileDescriptor() {}
53 
54   // Opens a file descriptor. The descriptor must be in the closed state prior
55   // to this call. Returns true on success, false otherwise. Specific
56   // implementations may set errno accordingly.
57   virtual bool Open(const char* path, int flags, mode_t mode) = 0;
58   virtual bool Open(const char* path, int flags) = 0;
59 
60   // Reads from a file descriptor up to a given count. The descriptor must be
61   // open prior to this call. Returns the number of bytes read, or -1 on error.
62   // Specific implementations may set errno accordingly.
63   virtual ssize_t Read(void* buf, size_t count) = 0;
64 
65   // Writes to a file descriptor. The descriptor must be open prior to this
66   // call. Returns the number of bytes written, or -1 if an error occurred and
67   // no bytes were written. Specific implementations may set errno accordingly.
68   virtual ssize_t Write(const void* buf, size_t count) = 0;
69 
70   // Seeks to an offset. Returns the resulting offset location as measured in
71   // bytes from the beginning. On error, return -1. Specific implementations
72   // may set errno accordingly.
73   virtual off64_t Seek(off64_t offset, int whence) = 0;
74 
75   // Return the size of the block device in bytes, or 0 if the device is not a
76   // block device or an error occurred.
77   virtual uint64_t BlockDevSize() = 0;
78 
79   // Runs a ioctl() on the file descriptor if supported. Returns whether
80   // the operation is supported. The |request| can be one of BLKDISCARD,
81   // BLKZEROOUT and BLKSECDISCARD to discard, write zeros or securely discard
82   // the blocks. These ioctls accept a range of bytes (|start| and |length|)
83   // over which they perform the operation. The return value from the ioctl is
84   // stored in |result|.
85   virtual bool BlkIoctl(int request,
86                         uint64_t start,
87                         uint64_t length,
88                         int* result) = 0;
89 
90   // Flushes any cached data. The descriptor must be opened prior to this
91   // call. Returns false if it fails to write data. Implementations may set
92   // errno accrodingly.
93   virtual bool Flush() = 0;
94 
95   // Closes a file descriptor. The descriptor must be open prior to this call.
96   // Returns true on success, false otherwise. Specific implementations may set
97   // errno accordingly.
98   virtual bool Close() = 0;
99 
100   // Indicates whether or not an implementation sets meaningful errno.
101   virtual bool IsSettingErrno() = 0;
102 
103   // Indicates whether the descriptor is currently open.
104   virtual bool IsOpen() = 0;
105 
106  private:
107   DISALLOW_COPY_AND_ASSIGN(FileDescriptor);
108 };
109 
110 // A simple EINTR-immune wrapper implementation around standard system calls.
111 class EintrSafeFileDescriptor : public FileDescriptor {
112  public:
EintrSafeFileDescriptor()113   EintrSafeFileDescriptor() : fd_(-1) {}
114 
115   // Interface methods.
116   bool Open(const char* path, int flags, mode_t mode) override;
117   bool Open(const char* path, int flags) override;
118   ssize_t Read(void* buf, size_t count) override;
119   ssize_t Write(const void* buf, size_t count) override;
120   off64_t Seek(off64_t offset, int whence) override;
121   uint64_t BlockDevSize() override;
122   bool BlkIoctl(int request,
123                 uint64_t start,
124                 uint64_t length,
125                 int* result) override;
126   bool Flush() override;
127   bool Close() override;
IsSettingErrno()128   bool IsSettingErrno() override { return true; }
IsOpen()129   bool IsOpen() override { return (fd_ >= 0); }
130 
131  protected:
132   int fd_;
133 };
134 
135 }  // namespace chromeos_update_engine
136 
137 #endif  // UPDATE_ENGINE_PAYLOAD_CONSUMER_FILE_DESCRIPTOR_H_
138