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 <memory>
22#include <sys/types.h>
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// * Provides a Reset() method, which will force to abandon a currently open
44//   file descriptor and allow opening another file, without necessarily
45//   properly closing the old one. This may be useful in cases where a "closer"
46//   class does not care whether Close() was successful, but may need to reuse
47//   the same file descriptor again.
48
49namespace chromeos_update_engine {
50
51class FileDescriptor;
52using FileDescriptorPtr = std::shared_ptr<FileDescriptor>;
53
54// An abstract class defining the file descriptor API.
55class FileDescriptor {
56 public:
57  FileDescriptor() {}
58  virtual ~FileDescriptor() {}
59
60  // Opens a file descriptor. The descriptor must be in the closed state prior
61  // to this call. Returns true on success, false otherwise. Specific
62  // implementations may set errno accordingly.
63  virtual bool Open(const char* path, int flags, mode_t mode) = 0;
64  virtual bool Open(const char* path, int flags) = 0;
65
66  // Reads from a file descriptor up to a given count. The descriptor must be
67  // open prior to this call. Returns the number of bytes read, or -1 on error.
68  // Specific implementations may set errno accordingly.
69  virtual ssize_t Read(void* buf, size_t count) = 0;
70
71  // Writes to a file descriptor. The descriptor must be open prior to this
72  // call. Returns the number of bytes written, or -1 if an error occurred and
73  // no bytes were written. Specific implementations may set errno accordingly.
74  virtual ssize_t Write(const void* buf, size_t count) = 0;
75
76  // Seeks to an offset. Returns the resulting offset location as measured in
77  // bytes from the beginning. On error, return -1. Specific implementations
78  // may set errno accordingly.
79  virtual off64_t Seek(off64_t offset, int whence) = 0;
80
81  // Return the size of the block device in bytes, or 0 if the device is not a
82  // block device or an error occurred.
83  virtual uint64_t BlockDevSize() = 0;
84
85  // Runs a ioctl() on the file descriptor if supported. Returns whether
86  // the operation is supported. The |request| can be one of BLKDISCARD,
87  // BLKZEROOUT and BLKSECDISCARD to discard, write zeros or securely discard
88  // the blocks. These ioctls accept a range of bytes (|start| and |length|)
89  // over which they perform the operation. The return value from the ioctl is
90  // stored in |result|.
91  virtual bool BlkIoctl(int request,
92                        uint64_t start,
93                        uint64_t length,
94                        int* result) = 0;
95
96  // Closes a file descriptor. The descriptor must be open prior to this call.
97  // Returns true on success, false otherwise. Specific implementations may set
98  // errno accordingly.
99  virtual bool Close() = 0;
100
101  // Resets the file descriptor, abandoning a currently open file and returning
102  // the descriptor to the closed state.
103  virtual void Reset() = 0;
104
105  // Indicates whether or not an implementation sets meaningful errno.
106  virtual bool IsSettingErrno() = 0;
107
108  // Indicates whether the descriptor is currently open.
109  virtual bool IsOpen() = 0;
110
111 private:
112  DISALLOW_COPY_AND_ASSIGN(FileDescriptor);
113};
114
115// A simple EINTR-immune wrapper implementation around standard system calls.
116class EintrSafeFileDescriptor : public FileDescriptor {
117 public:
118  EintrSafeFileDescriptor() : fd_(-1) {}
119
120  // Interface methods.
121  bool Open(const char* path, int flags, mode_t mode) override;
122  bool Open(const char* path, int flags) override;
123  ssize_t Read(void* buf, size_t count) override;
124  ssize_t Write(const void* buf, size_t count) override;
125  off64_t Seek(off64_t offset, int whence) override;
126  uint64_t BlockDevSize() override;
127  bool BlkIoctl(int request,
128                uint64_t start,
129                uint64_t length,
130                int* result) override;
131  bool Close() override;
132  void Reset() override;
133  bool IsSettingErrno() override {
134    return true;
135  }
136  bool IsOpen() override {
137    return (fd_ >= 0);
138  }
139
140 protected:
141  int fd_;
142};
143
144}  // namespace chromeos_update_engine
145
146#endif  // UPDATE_ENGINE_PAYLOAD_CONSUMER_FILE_DESCRIPTOR_H_
147