Contiki-NG
cfs.h
Go to the documentation of this file.
1 /*
2  * Copyright (c) 2004, Swedish Institute of Computer Science.
3  * All rights reserved.
4  *
5  * Redistribution and use in source and binary forms, with or without
6  * modification, are permitted provided that the following conditions
7  * are met:
8  * 1. Redistributions of source code must retain the above copyright
9  * notice, this list of conditions and the following disclaimer.
10  * 2. Redistributions in binary form must reproduce the above copyright
11  * notice, this list of conditions and the following disclaimer in the
12  * documentation and/or other materials provided with the distribution.
13  * 3. Neither the name of the Institute nor the names of its contributors
14  * may be used to endorse or promote products derived from this software
15  * without specific prior written permission.
16  *
17  * THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND
18  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
19  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
20  * ARE DISCLAIMED. IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE
21  * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
22  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
23  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
24  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
25  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
26  * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
27  * SUCH DAMAGE.
28  *
29  * This file is part of the Contiki operating system.
30  *
31  * Author: Adam Dunkels <adam@sics.se>
32  *
33  */
34 
35 /**
36  * \file
37  * CFS header file.
38  * \author
39  * Adam Dunkels <adam@sics.se>
40  *
41  */
42 
43 /**
44  * \addtogroup sys
45  * @{
46  */
47 
48 /**
49  * \defgroup cfs The Contiki file system interface
50  *
51  * The Contiki file system interface (CFS) defines an abstract API for
52  * reading directories and for reading and writing files. The CFS API
53  * is intentionally simple. The CFS API is modeled after the POSIX
54  * file API, and slightly simplified.
55  *
56  * @{
57  */
58 
59 #ifndef CFS_H_
60 #define CFS_H_
61 
62 #include "contiki.h"
63 
64 #ifndef CFS_CONF_OFFSET_TYPE
65 typedef int cfs_offset_t;
66 #else
67 typedef CFS_CONF_OFFSET_TYPE cfs_offset_t;
68 #endif
69 
70 struct cfs_dir {
71  /* Iteration state, which is implementation-defined and should not be
72  accessed externally. */
73  char state[32];
74 };
75 
76 struct cfs_dirent {
77  char name[32];
78  cfs_offset_t size;
79 };
80 
81 /**
82  * Specify that cfs_open() should open a file for reading.
83  *
84  * This constant indicates to cfs_open() that a file should be opened
85  * for reading. CFS_WRITE should be used if the file is opened for
86  * writing, and CFS_READ + CFS_WRITE indicates that the file is opened
87  * for both reading and writing.
88  *
89  * \sa cfs_open()
90  */
91 #ifndef CFS_READ
92 #define CFS_READ 1
93 #endif
94 
95 /**
96  * Specify that cfs_open() should open a file for writing.
97  *
98  * This constant indicates to cfs_open() that a file should be opened
99  * for writing. CFS_READ should be used if the file is opened for
100  * reading, and CFS_READ + CFS_WRITE indicates that the file is opened
101  * for both reading and writing.
102  *
103  * \sa cfs_open()
104  */
105 #ifndef CFS_WRITE
106 #define CFS_WRITE 2
107 #endif
108 
109 /**
110  * Specify that cfs_open() should append written data to the file rather than overwriting it.
111  *
112  * This constant indicates to cfs_open() that a file that should be
113  * opened for writing gets written data appended to the end of the
114  * file. The default behaviour (without CFS_APPEND) is that the file
115  * is overwritten with the new data.
116  *
117  * \sa cfs_open()
118  */
119 #ifndef CFS_APPEND
120 #define CFS_APPEND 4
121 #endif
122 
123 /**
124  * Specify that cfs_seek() should compute the offset from the beginning of the file.
125  *
126  * \sa cfs_seek()
127  */
128 #ifndef CFS_SEEK_SET
129 #define CFS_SEEK_SET 0
130 #endif
131 
132 /**
133  * Specify that cfs_seek() should compute the offset from the current position of the file pointer.
134  *
135  * \sa cfs_seek()
136  */
137 #ifndef CFS_SEEK_CUR
138 #define CFS_SEEK_CUR 1
139 #endif
140 
141 /**
142  * Specify that cfs_seek() should compute the offset from the end of the file.
143  *
144  * \sa cfs_seek()
145  */
146 #ifndef CFS_SEEK_END
147 #define CFS_SEEK_END 2
148 #endif
149 
150 /**
151  * \brief Open a file.
152  * \param name The name of the file.
153  * \param flags CFS_READ, or CFS_WRITE/CFS_APPEND, or both.
154  * \return A file descriptor, if the file could be opened, or -1 if
155  * the file could not be opened.
156  *
157  * This function opens a file and returns a file
158  * descriptor for the opened file. If the file could not
159  * be opened, the function returns -1. The function can
160  * open a file for reading or writing, or both.
161  *
162  * An opened file must be closed with cfs_close().
163  *
164  * \sa CFS_READ
165  * \sa CFS_WRITE
166  * \sa cfs_close()
167  */
168 #ifndef cfs_open
169 int cfs_open(const char *name, int flags);
170 #endif
171 
172 /**
173  * \brief Close an open file.
174  * \param fd The file descriptor of the open file.
175  *
176  * This function closes a file that has previously been
177  * opened with cfs_open().
178  */
179 #ifndef cfs_close
180 void cfs_close(int fd);
181 #endif
182 
183 /**
184  * \brief Read data from an open file.
185  * \param fd The file descriptor of the open file.
186  * \param buf The buffer in which data should be read from the file.
187  * \param len The number of bytes that should be read.
188  * \return The number of bytes that was actually read from the file.
189  *
190  * This function reads data from an open file into a
191  * buffer. The file must have first been opened with
192  * cfs_open() and the CFS_READ flag.
193  */
194 #ifndef cfs_read
195 int cfs_read(int fd, void *buf, unsigned int len);
196 #endif
197 
198 /**
199  * \brief Write data to an open file.
200  * \param fd The file descriptor of the open file.
201  * \param buf The buffer from which data should be written to the file.
202  * \param len The number of bytes that should be written.
203  * \return The number of bytes that was actually written to the file.
204  *
205  * This function reads writes data from a memory buffer to
206  * an open file. The file must have been opened with
207  * cfs_open() and the CFS_WRITE flag.
208  */
209 #ifndef cfs_write
210 int cfs_write(int fd, const void *buf, unsigned int len);
211 #endif
212 
213 /**
214  * \brief Seek to a specified position in an open file.
215  * \param fd The file descriptor of the open file.
216  * \param offset A position, either relative or absolute, in the file.
217  * \param whence Determines how to interpret the offset parameter.
218  * \return The new position in the file, or (cfs_offset_t)-1 if the seek failed.
219  *
220  * This function moves the file position to the specified
221  * position in the file. The next byte that is read from
222  * or written to the file will be at the position given
223  * determined by the combination of the offset parameter
224  * and the whence parameter.
225  *
226  * \sa CFS_SEEK_CUR
227  * \sa CFS_SEEK_END
228  * \sa CFS_SEEK_SET
229  */
230 #ifndef cfs_seek
231 cfs_offset_t cfs_seek(int fd, cfs_offset_t offset, int whence);
232 #endif
233 
234 /**
235  * \brief Remove a file.
236  * \param name The name of the file.
237  * \retval 0 If the file was removed.
238  * \return -1 If the file could not be removed or if it doesn't exist.
239  */
240 #ifndef cfs_remove
241 int cfs_remove(const char *name);
242 #endif
243 
244 /**
245  * \brief Open a directory for reading directory entries.
246  * \param dirp A pointer to a struct cfs_dir that is filled in by the function.
247  * \param name The name of the directory.
248  * \return 0 or -1 if the directory could not be opened.
249  *
250  * \sa cfs_readdir()
251  * \sa cfs_closedir()
252  */
253 #ifndef cfs_opendir
254 int cfs_opendir(struct cfs_dir *dirp, const char *name);
255 #endif
256 
257 /**
258  * \brief Read a directory entry
259  * \param dirp A pointer to a struct cfs_dir that has been opened with cfs_opendir().
260  * \param dirent A pointer to a struct cfs_dirent that is filled in by cfs_readdir()
261  * \retval 0 If a directory entry was read.
262  * \retval -1 If no more directory entries can be read.
263  *
264  * \sa cfs_opendir()
265  * \sa cfs_closedir()
266  */
267 #ifndef cfs_readdir
268 int cfs_readdir(struct cfs_dir *dirp, struct cfs_dirent *dirent);
269 #endif
270 
271 /**
272  * \brief Close a directory opened with cfs_opendir().
273  * \param dirp A pointer to a struct cfs_dir that has been opened with cfs_opendir().
274  *
275  * \sa cfs_opendir()
276  * \sa cfs_readdir()
277  */
278 #ifndef cfs_closedir
279 void cfs_closedir(struct cfs_dir *dirp);
280 #endif
281 
282 #endif /* CFS_H_ */
283 
284 /** @} */
285 /** @} */
int cfs_open(const char *name, int flags)
Open a file.
Definition: cfs-sdcard.c:41
int cfs_remove(const char *name)
Remove a file.
Definition: cfs-cooja.c:150
cfs_offset_t cfs_seek(int fd, cfs_offset_t offset, int whence)
Seek to a specified position in an open file.
Definition: cfs-sdcard.c:94
int cfs_write(int fd, const void *buf, unsigned int len)
Write data to an open file.
Definition: cfs-sdcard.c:86
int cfs_opendir(struct cfs_dir *dirp, const char *name)
Open a directory for reading directory entries.
Definition: cfs-sdcard.c:129
void cfs_close(int fd)
Close an open file.
Definition: cfs-sdcard.c:69
int cfs_readdir(struct cfs_dir *dirp, struct cfs_dirent *dirent)
Read a directory entry.
Definition: cfs-sdcard.c:145
int cfs_read(int fd, void *buf, unsigned int len)
Read data from an open file.
Definition: cfs-sdcard.c:78
void cfs_closedir(struct cfs_dir *dirp)
Close a directory opened with cfs_opendir().
Definition: cfs-sdcard.c:184