Mistake on this page?
Report an issue in GitHub or email us
FileHandle.h
1 /* mbed Microcontroller Library
2  * Copyright (c) 2017 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 "Callback.h"
24 #include "platform/mbed_poll.h"
25 #include "platform/platform.h"
26 #include "platform/NonCopyable.h"
27 
28 namespace mbed {
29 /** \addtogroup platform */
30 /** @{*/
31 /**
32  * \defgroup platform_FileHandle FileHandle functions
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  /** Move the file position to a given offset from a given location.
142  *
143  * @param offset The offset from whence to move to
144  * @param whence SEEK_SET for the start of the file, SEEK_CUR for the
145  * current file position, or SEEK_END for the end of the file.
146  *
147  * @returns
148  * new file position on success,
149  * -1 on failure or unsupported
150  * @deprecated Replaced by `off_t FileHandle::seek(off_t offset, int whence = SEEK_SET)'
151  *
152  */
153  MBED_DEPRECATED_SINCE("mbed-os-5.4", "Replaced by FileHandle::seek")
154  virtual off_t lseek(off_t offset, int whence)
155  {
156  return seek(offset, whence);
157  }
158 
159  /** Flush any buffers associated with the FileHandle, ensuring it
160  * is up to date on disk
161  *
162  * @returns
163  * 0 on success or un-needed,
164  * -1 on error
165  * @deprecated Replaced by `int FileHandle::sync()'
166  */
167  MBED_DEPRECATED_SINCE("mbed-os-5.4", "Replaced by FileHandle::sync")
168  virtual int fsync()
169  {
170  return sync();
171  }
172 
173  /** Find the length of the file
174  *
175  * @returns
176  * Length of the file
177  * @deprecated Replaced by `off_t FileHandle::size()'
178  */
179  MBED_DEPRECATED_SINCE("mbed-os-5.4", "Replaced by FileHandle::size")
180  virtual off_t flen()
181  {
182  return size();
183  }
184 
185  /** Set blocking or nonblocking mode of the file operation like read/write.
186  * Definition depends on the subclass implementing FileHandle.
187  * The default is blocking.
188  *
189  * @param blocking true for blocking mode, false for nonblocking mode.
190  *
191  * @return 0 on success
192  * @return Negative error code on failure
193  */
194  virtual int set_blocking(bool blocking)
195  {
196  return blocking ? 0 : -ENOTTY;
197  }
198 
199  /** Check current blocking or nonblocking mode for file operations.
200  *
201  * @return true for blocking mode, false for nonblocking mode.
202  */
203  virtual bool is_blocking() const
204  {
205  return true;
206  }
207 
208  /** Check for poll event flags
209  * You can use or ignore the input parameter. You can return all events
210  * or check just the events listed in events.
211  * Call is nonblocking - returns instantaneous state of events.
212  * Whenever an event occurs, the derived class should call the sigio() callback).
213  *
214  * @param events bitmask of poll events we're interested in - POLLIN/POLLOUT etc.
215  *
216  * @returns bitmask of poll events that have occurred.
217  */
218  virtual short poll(short events) const
219  {
220  // Possible default for real files
221  return POLLIN | POLLOUT;
222  }
223 
224  /** Definition depends on the subclass implementing FileHandle.
225  * For example, if the FileHandle is of type Stream, writable() could return
226  * true when there is ample buffer space available for write() calls.
227  *
228  * @returns true if the FileHandle is writable.
229  */
230  bool writable() const
231  {
232  return poll(POLLOUT) & POLLOUT;
233  }
234 
235  /** Definition depends on the subclass implementing FileHandle.
236  * For example, if the FileHandle is of type Stream, readable() could return
237  * true when there is something available to read.
238  *
239  * @returns true when there is something available to read.
240  */
241  bool readable() const
242  {
243  return poll(POLLIN) & POLLIN;
244  }
245 
246  /** Register a callback on state change of the file.
247  *
248  * The specified callback will be called on state changes such as when
249  * the file can be written to or read from.
250  *
251  * The callback may be called in an interrupt context and should not
252  * perform expensive operations.
253  *
254  * Note! This is not intended as an attach-like asynchronous API, but rather
255  * as a building block for constructing such functionality.
256  *
257  * The exact timing of when the registered function
258  * is called is not guaranteed and is susceptible to change. It should be used
259  * as a cue to make read/write/poll calls to find the current state.
260  *
261  * @param func Function to call on state change
262  */
263  virtual void sigio(Callback<void()> func)
264  {
265  //Default for real files. Do nothing for real files.
266  }
267 };
268 
269 /**@}*/
270 
271 /**@}*/
272 
273 
274 } // namespace mbed
275 
276 #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:263
bool readable() const
Definition depends on the subclass implementing FileHandle.
Definition: FileHandle.h:241
virtual int set_blocking(bool blocking)
Set blocking or nonblocking mode of the file operation like read/write.
Definition: FileHandle.h:194
virtual ssize_t write(const void *buffer, size_t size)=0
Write the contents of a buffer to a file.
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:168
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:154
Prevents generation of copy constructor and copy assignment operator in derived classes.
Definition: NonCopyable.h:168
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:180
virtual short poll(short events) const
Check for poll event flags You can use or ignore the input parameter.
Definition: FileHandle.h:218
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:230
Callback class based on template specialization.
Definition: Callback.h:39
Definition: AnalogIn.h:28
virtual bool is_blocking() const
Check current blocking or nonblocking mode for file operations.
Definition: FileHandle.h:203
#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.