Mistake on this page?
Report an issue in GitHub or email us
FileHandle.h
1 /* mbed Microcontroller Library
2  * Copyright (c) 2017-2019 ARM Limited
3  * SPDX-License-Identifier: Apache-2.0
4  *
5  * Licensed under the Apache License, Version 2.0 (the "License");
6  * you may not use this file except in compliance with the License.
7  * You may obtain a copy of the License at
8  *
9  * http://www.apache.org/licenses/LICENSE-2.0
10  *
11  * Unless required by applicable law or agreed to in writing, software
12  * distributed under the License is distributed on an "AS IS" BASIS,
13  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14  * See the License for the specific language governing permissions and
15  * limitations under the License.
16  */
17 #ifndef MBED_FILEHANDLE_H
18 #define MBED_FILEHANDLE_H
19 
20 typedef int FILEHANDLE;
21 
22 #include <cstdio>
23 #include "platform/Callback.h"
24 #include "platform/mbed_poll.h"
25 #include "platform/platform.h"
26 #include "platform/NonCopyable.h"
27 
28 namespace mbed {
29 
30 /**
31  * \defgroup platform_FileHandle FileHandle functions
32  * \ingroup platform-public-api-file
33  * @{
34  */
35 
36 
37 /** Class FileHandle
38  *
39  * An abstract interface that represents operations on a file-like
40  * object. The core functions are read, write and seek, but only
41  * a subset of these operations can be provided.
42  *
43  * @note to create a file, @see File
44  * @note Synchronization level: Set by subclass
45  */
46 class FileHandle : private NonCopyable<FileHandle> {
47 public:
48  virtual ~FileHandle() {}
49 
50  /** Read the contents of a file into a buffer
51  *
52  * Devices acting as FileHandles should follow POSIX semantics:
53  *
54  * * if no data is available, and nonblocking set, return -EAGAIN
55  * * if no data is available, and blocking set, wait until some data is available
56  * * If any data is available, call returns immediately
57  *
58  * @param buffer The buffer to read in to
59  * @param size The number of bytes to read
60  * @return The number of bytes read, 0 at end of file, negative error on failure
61  */
62  virtual ssize_t read(void *buffer, size_t size) = 0;
63 
64  /** Write the contents of a buffer to a file
65  *
66  * Devices acting as FileHandles should follow POSIX semantics:
67  *
68  * * if blocking, block until all data is written
69  * * if no data can be written, and nonblocking set, return -EAGAIN
70  * * if some data can be written, and nonblocking set, write partial
71  *
72  * @param buffer The buffer to write from
73  * @param size The number of bytes to write
74  * @return The number of bytes written, negative error on failure
75  */
76  virtual ssize_t write(const void *buffer, size_t size) = 0;
77 
78  /** Move the file position to a given offset from from a given location
79  *
80  * @param offset The offset from whence to move to
81  * @param whence The start of where to seek
82  * SEEK_SET to start from beginning of file,
83  * SEEK_CUR to start from current position in file,
84  * SEEK_END to start from end of file
85  * @return The new offset of the file, negative error code on failure
86  */
87  virtual off_t seek(off_t offset, int whence = SEEK_SET) = 0;
88 
89  /** Close a file
90  *
91  * @return 0 on success, negative error code on failure
92  */
93  virtual int close() = 0;
94 
95  /** Flush any buffers associated with the file
96  *
97  * @return 0 on success, negative error code on failure
98  */
99  virtual int sync()
100  {
101  return 0;
102  }
103 
104  /** Check if the file in an interactive terminal device
105  *
106  * @return True if the file is a terminal
107  * @return False if the file is not a terminal
108  * @return Negative error code on failure
109  */
110  virtual int isatty()
111  {
112  return false;
113  }
114 
115  /** Get the file position of the file
116  *
117  * @note This is equivalent to seek(0, SEEK_CUR)
118  *
119  * @return The current offset in the file, negative error code on failure
120  */
121  virtual off_t tell()
122  {
123  return seek(0, SEEK_CUR);
124  }
125 
126  /** Rewind the file position to the beginning of the file
127  *
128  * @note This is equivalent to seek(0, SEEK_SET)
129  */
130  virtual void rewind()
131  {
132  seek(0, SEEK_SET);
133  }
134 
135  /** Get the size of the file
136  *
137  * @return Size of the file in bytes
138  */
139  virtual off_t size();
140 
141  /** Truncate or extend a file.
142  *
143  * The file's length is set to the specified value. The seek pointer is
144  * not changed. If the file is extended, the extended area appears as if
145  * it were zero-filled.
146  *
147  * @param length The requested new length for the file
148  *
149  * @return Zero on success, negative error code on failure
150  */
151  virtual int truncate(off_t length)
152  {
153  return -EINVAL;
154  }
155 
156  /** Move the file position to a given offset from a given location.
157  *
158  * @param offset The offset from whence to move to
159  * @param whence SEEK_SET for the start of the file, SEEK_CUR for the
160  * current file position, or SEEK_END for the end of the file.
161  *
162  * @returns
163  * new file position on success,
164  * -1 on failure or unsupported
165  * @deprecated Replaced by `off_t FileHandle::seek(off_t offset, int whence = SEEK_SET)'
166  *
167  */
168  MBED_DEPRECATED_SINCE("mbed-os-5.4", "Replaced by FileHandle::seek")
169  virtual off_t lseek(off_t offset, int whence)
170  {
171  return seek(offset, whence);
172  }
173 
174  /** Flush any buffers associated with the FileHandle, ensuring it
175  * is up to date on disk
176  *
177  * @returns
178  * 0 on success or un-needed,
179  * -1 on error
180  * @deprecated Replaced by `int FileHandle::sync()'
181  */
182  MBED_DEPRECATED_SINCE("mbed-os-5.4", "Replaced by FileHandle::sync")
183  virtual int fsync()
184  {
185  return sync();
186  }
187 
188  /** Find the length of the file
189  *
190  * @returns
191  * Length of the file
192  * @deprecated Replaced by `off_t FileHandle::size()'
193  */
194  MBED_DEPRECATED_SINCE("mbed-os-5.4", "Replaced by FileHandle::size")
195  virtual off_t flen()
196  {
197  return size();
198  }
199 
200  /** Set blocking or nonblocking mode of the file operation like read/write.
201  * Definition depends on the subclass implementing FileHandle.
202  * The default is blocking.
203  *
204  * @param blocking true for blocking mode, false for nonblocking mode.
205  *
206  * @return 0 on success
207  * @return Negative error code on failure
208  */
209  virtual int set_blocking(bool blocking)
210  {
211  return blocking ? 0 : -ENOTTY;
212  }
213 
214  /** Check current blocking or nonblocking mode for file operations.
215  *
216  * @return true for blocking mode, false for nonblocking mode.
217  */
218  virtual bool is_blocking() const
219  {
220  return true;
221  }
222 
223  /** Enable or disable input
224  *
225  * Control enabling of device for input. This is primarily intended
226  * for temporary power-saving; the overall ability of the device to operate for
227  * input and/or output may be fixed at creation time, but this call can
228  * allow input to be temporarily disabled to permit power saving without
229  * losing device state.
230  *
231  * @param enabled true to enable input, false to disable.
232  *
233  * @return 0 on success
234  * @return Negative error code on failure
235  */
236  virtual int enable_input(bool enabled)
237  {
238  return -EINVAL;
239  }
240 
241  /** Enable or disable output
242  *
243  * Control enabling of device for output. This is primarily intended
244  * for temporary power-saving; the overall ability of the device to operate for
245  * input and/or output may be fixed at creation time, but this call can
246  * allow output to be temporarily disabled to permit power saving without
247  * losing device state.
248  *
249  * @param enabled true to enable output, false to disable.
250  *
251  * @return 0 on success
252  * @return Negative error code on failure
253  */
254  virtual int enable_output(bool enabled)
255  {
256  return -EINVAL;
257  }
258 
259  /** Check for poll event flags
260  * You can use or ignore the input parameter. You can return all events
261  * or check just the events listed in events.
262  * Call is nonblocking - returns instantaneous state of events.
263  * Whenever an event occurs, the derived class should call the sigio() callback).
264  *
265  * @param events bitmask of poll events we're interested in - POLLIN/POLLOUT etc.
266  *
267  * @returns bitmask of poll events that have occurred.
268  */
269  virtual short poll(short events) const
270  {
271  // Possible default for real files
272  return POLLIN | POLLOUT;
273  }
274 
275  /** Definition depends on the subclass implementing FileHandle.
276  * For example, if the FileHandle is of type Stream, writable() could return
277  * true when there is ample buffer space available for write() calls.
278  *
279  * @returns true if the FileHandle is writable.
280  */
281  bool writable() const
282  {
283  return poll(POLLOUT) & POLLOUT;
284  }
285 
286  /** Definition depends on the subclass implementing FileHandle.
287  * For example, if the FileHandle is of type Stream, readable() could return
288  * true when there is something available to read.
289  *
290  * @returns true when there is something available to read.
291  */
292  bool readable() const
293  {
294  return poll(POLLIN) & POLLIN;
295  }
296 
297  /** Register a callback on state change of the file.
298  *
299  * The specified callback will be called on state changes such as when
300  * the file can be written to or read from.
301  *
302  * The callback may be called in an interrupt context and should not
303  * perform expensive operations.
304  *
305  * Note! This is not intended as an attach-like asynchronous API, but rather
306  * as a building block for constructing such functionality.
307  *
308  * The exact timing of when the registered function
309  * is called is not guaranteed and is susceptible to change. It should be used
310  * as a cue to make read/write/poll calls to find the current state.
311  *
312  * @param func Function to call on state change
313  */
314  virtual void sigio(Callback<void()> func)
315  {
316  //Default for real files. Do nothing for real files.
317  }
318 };
319 
320 /**@}*/
321 
322 } // namespace mbed
323 
324 #endif
virtual off_t size()
Get the size of the file.
virtual void sigio(Callback< void()> func)
Register a callback on state change of the file.
Definition: FileHandle.h:314
bool readable() const
Definition depends on the subclass implementing FileHandle.
Definition: FileHandle.h:292
virtual int set_blocking(bool blocking)
Set blocking or nonblocking mode of the file operation like read/write.
Definition: FileHandle.h:209
virtual ssize_t write(const void *buffer, size_t size)=0
Write the contents of a buffer to a file.
virtual int enable_output(bool enabled)
Enable or disable output.
Definition: FileHandle.h:254
virtual int close()=0
Close a file.
virtual int fsync()
Flush any buffers associated with the FileHandle, ensuring it is up to date on disk.
Definition: FileHandle.h:183
virtual int isatty()
Check if the file in an interactive terminal device.
Definition: FileHandle.h:110
Class FileHandle.
Definition: FileHandle.h:46
virtual off_t lseek(off_t offset, int whence)
Move the file position to a given offset from a given location.
Definition: FileHandle.h:169
Prevents generation of copy constructor and copy assignment operator in derived classes.
Definition: NonCopyable.h:169
virtual off_t seek(off_t offset, int whence=SEEK_SET)=0
Move the file position to a given offset from from a given location.
virtual ssize_t read(void *buffer, size_t size)=0
Read the contents of a file into a buffer.
virtual int sync()
Flush any buffers associated with the file.
Definition: FileHandle.h:99
virtual off_t flen()
Find the length of the file.
Definition: FileHandle.h:195
virtual short poll(short events) const
Check for poll event flags You can use or ignore the input parameter.
Definition: FileHandle.h:269
virtual int truncate(off_t length)
Truncate or extend a file.
Definition: FileHandle.h:151
virtual int enable_input(bool enabled)
Enable or disable input.
Definition: FileHandle.h:236
virtual void rewind()
Rewind the file position to the beginning of the file.
Definition: FileHandle.h:130
virtual off_t tell()
Get the file position of the file.
Definition: FileHandle.h:121
bool writable() const
Definition depends on the subclass implementing FileHandle.
Definition: FileHandle.h:281
Callback class based on template specialization.
Definition: Callback.h:39
virtual bool is_blocking() const
Check current blocking or nonblocking mode for file operations.
Definition: FileHandle.h:218
#define MBED_DEPRECATED_SINCE(D, M)
MBED_DEPRECATED("message string") Mark a function declaration as deprecated, if it used then a warnin...
Important Information for this Arm website

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.