1 /*
2  * Copyright (C) 2015-2017 Alibaba Group Holding Limited
3  */
4 
5 #ifndef VFS_API_H
6 #define VFS_API_H
7 
8 #define VFS_OK               0
9 #define VFS_ERR_NOMEM       -10000
10 #define VFS_ERR_INVAL       -10001
11 #define VFS_ERR_NOENT       -10002
12 #define VFS_ERR_NAMETOOLONG -10003
13 #define VFS_ERR_NOSYS       -10004
14 #define VFS_ERR_ENFILE      -10005
15 #define VFS_ERR_NODEV       -10006
16 #define VFS_ERR_LOCK        -10007
17 #define VFS_ERR_BUSY        -10008
18 #define VFS_ERR_GENERAL     -10009
19 
20 #ifdef __cplusplus
21 extern "C" {
22 #endif
23 
24 /**
25  * @brief Initialize the vfs module
26  *
27  * @return 0 on success, negative error on failure
28  *
29  */
30 int32_t vfs_init(void);
31 
32 /**
33  * @brief Open the file or device by path
34  *
35  * @param[in] path  the path of the file or device to open
36  * @param[in] flags the mode of the open operation
37  *
38  * @return the new file descriptor, negative error on failure
39  *
40  */
41 int32_t vfs_open(const char *path, int32_t flags);
42 
43 /**
44  * @brief Close the file or device by file descriptor
45  *
46  * @param[in] fd the file descriptor of the file ot device
47  *
48  * @return 0 on success, negative error on failure
49  *
50  */
51 int32_t vfs_close(int32_t fd);
52 
53 /**
54  * @brief Read the contents of a file or device into a buffer
55  *
56  * @param[in]  fd     the file descriptor of the file or device
57  * @param[out] buf    the buffer to read into
58  * @param[in]  nbytes the number of bytes to read
59  *
60  * @return the number of bytes read, 0 at end of file, negative error on failure
61  *
62  */
63 int32_t vfs_read(int32_t fd, void *buf, uint32_t nbytes);
64 
65 /**
66  * @brief Write the contents of a buffer to file or device
67  *
68  * @param[in] fd     the file descriptor of the file or device
69  * @param[in] buf    the buffer to write from
70  * @param[in] nbytes the number of bytes to write
71  *
72  * @return the number of bytes written, negative error on failure
73  *
74  */
75 int32_t vfs_write(int32_t fd, const void *buf, uint32_t nbytes);
76 
77 /**
78  * @brief This is a wildcard API for sending specific commands
79  *
80  * @param[in] fd  the file descriptor of the file or device
81  * @param[in] cmd a specific command
82  * @param[in] arg argument to the command, interpreted according to the cmd
83  *
84  * @return any return from the command
85  *
86  */
87 int32_t vfs_ioctl(int32_t fd, int32_t cmd, uint32_t arg);
88 
89 /**
90  * @brief This is a wildcard API for executing the particular poll by fd
91  *
92  * @param[in] fd     the file descriptor of the file or device
93  * @param[in] flag   the flag of the polling
94  * @param[in] notify the polling notify callback
95  * @param[in] fds    a pointer to the array of pollfd
96  * @param[in] arg    the arguments of the polling
97  *
98  * @return 0 on success, negative error on failure
99  *
100  */
101 int32_t vfs_do_pollfd(int32_t fd, int32_t flag, vfs_poll_notify_t notify,
102                       void *fds, void *arg);
103 
104 /**
105  * @brief Move the file position to a given offset from a given location
106  *
107  * @param[in] fd     the file descriptor of the file
108  * @param[in] offset the offset from whence to move to
109  * @param[in] whence the start of where to seek
110  *                   SEEK_SET to start from beginning of the file
111  *                   SEEK_CUR to start from current position in file
112  *                   SEEK_END to start from end of file
113  *
114  * @return the new offset of the file
115  *
116  */
117 uint32_t vfs_lseek(int32_t fd, int64_t offset, int32_t whence);
118 
119 /**
120  * @brief Flush any buffers associated with the file
121  *
122  * @param[in] fd the file descriptor of the file
123  *
124  * @return 0 on success, negative error on failure
125  *
126  */
127 int32_t vfs_sync(int32_t fd);
128 
129 /**
130  * @brief Flush all information in memory that updates file systems to be
131  * be written to the file systems
132  *
133  * @return none
134  *
135  */
136 void vfs_allsync(void);
137 
138 /**
139  * Store information about the file in a vfs_stat structure
140  *
141  * @param[in]  path the path of the file to find information about
142  * @param[out] st   the vfs_stat buffer to write to
143  *
144  * @return 0 on success, negative error on failure
145  *
146  */
147 int32_t vfs_stat(const char *path, vfs_stat_t *st);
148 
149 /**
150  * Store information about the file in a vfs_stat structure
151  *
152  * @param[in]  fd the file descriptor of the file
153  * @param[out] st the vfs_stat buffer to write to
154  *
155  * @return 0 on success, negative error on failure
156  *
157  */
158 int32_t vfs_fstat(int fd, vfs_stat_t *st);
159 
160 #ifdef AOS_PROCESS_SUPPORT
161 /**
162  * Map memory to process address space to share memory between
163  * kernel and process.
164  *
165  * @note Currently only support input arg @len to tell kernel the
166  *       size of shared memory.
167  *
168  * @return shared memory virtual address on success, NULL on failure
169  */
170 void *vfs_mmap(void *start, size_t len, int prot, int flags, int fd, off_t offset);
171 
172 /**
173  * @brief unmap shared memory area
174  *
175  * @param[in] start The address of the shared memory area
176  * @param[in] len   The size of the shared memory area
177  *
178  * @return 0 on success, negative error on failure
179  */
180 int vfs_munmap(void *start, size_t len);
181 #endif
182 /**
183  * @brief link path2 to path1
184  *
185  * @param[in] path1 the path to be linked
186  * @param[in] path2 the path to link
187  *
188  * @return 0 on success, negative error on failure
189  *
190  */
191 int32_t vfs_link(const char *oldpath, const char *newpath);
192 
193 /**
194  * @brief Remove a file from the filesystem
195  *
196  * @param[in] path the path of the file to remove
197  *
198  * @return 0 on success, negative error on failure
199  *
200  */
201 int32_t vfs_unlink(const char *path);
202 
203 /**
204  * @brief Remove a file from the filesystem
205  *
206  * @param[in] path the path of the file to remove
207  *
208  * @return 0 on success, negative error on failure
209  *
210  */
211 int32_t vfs_remove(const char *path);
212 
213 /**
214  * @brief Rename a file in the filesystem
215  *
216  * @param[in] oldpath the path of the file to rename
217  * @param[in] newpath the path to rename it to
218  *
219  * @return 0 on success, negative error on failure
220  *
221  */
222 int32_t vfs_rename(const char *oldpath, const char *newpath);
223 
224 /**
225  * @brief Open a directory on the filesystem
226  *
227  * @param[in] path the path of the directory to open
228  *
229  * @return a pointer of directory stream on success, NULL on failure
230  *
231  */
232 vfs_dir_t *vfs_opendir(const char *path);
233 
234 /**
235  * @brief Close a directory
236  *
237  * @param[in] dir the pointer of the directory to close
238  *
239  * @return 0 on success, negative error on failure
240  *
241  */
242 int32_t vfs_closedir(vfs_dir_t *dir);
243 
244 /**
245  * @brief Read the next directory entry
246  *
247  * @param[in] dir the pointer of the directory to read
248  *
249  * @return a pointer to a vfs_dirent structure
250  *
251  */
252 vfs_dirent_t *vfs_readdir(vfs_dir_t *dir);
253 
254 /**
255  * @brief Create the directory, if ther do not already exist
256  *
257  * @param[in] path the path of the directory to create
258  *
259  * @return 0 on success, negative error on failure
260  *
261  */
262 int32_t vfs_mkdir(const char *path);
263 
264 /**
265  * @brief Remove a directory
266  *
267  * @param[in] path the path of the directory to remove
268  *
269  * @return 0 on success, negative error on failure
270  *
271  */
272 int32_t vfs_rmdir(const char *path);
273 
274 /**
275  * @brief Reset the position of a directory stream to the beginning of a directory
276  *
277  * @param[in] dir the pointer of the directory to rewind
278  *
279  * @return none
280  *
281  */
282 void vfs_rewinddir(vfs_dir_t *dir);
283 
284 /**
285  * @brief Obtain the current location associated with the directory
286  *
287  * @param[in] dir the pointer of the directory to tell
288  *
289  * @return the current location of the directory, negative error on failure
290  *
291  */
292 int32_t vfs_telldir(vfs_dir_t *dir);
293 
294 /**
295  * @brief Move the directory position to a given location
296  *
297  * @param[in] dir the pointer of the directory to seek
298  * @param[in] loc the location of the directory
299  *
300  * @return none
301  */
302 void vfs_seekdir(vfs_dir_t *dir, int32_t loc);
303 
304 /**
305  * @brief Store information about the filesystem in a vfs_statfs structure
306  *
307  * @param[in]  path the path of the filesystem to find information about
308  * @param[out] buf  the vfs_statfs buffer to write to
309  *
310  * @return 0 on success, negative error on failure
311  *
312  */
313 int32_t vfs_statfs(const char *path, vfs_statfs_t *buf);
314 
315 /**
316  * @brief Get access information
317  *
318  * @param[in] path  the path of the file to access
319  * @param[in] amode the access information to get
320  *
321  * @return 0 on success, negative error on failure
322  *
323  */
324 int32_t vfs_access(const char *path, int32_t amode);
325 
326 
327 /**
328  * @brief  Manipulate file descriptor
329  * @param[in]  fd   the file descriptor of the file
330  * @param[in]  cmd  A controller specific command
331  * @param[val] val  Argument to the command
332  *
333  * @return 0 on success, negative error on failure
334  *
335  */
336 int vfs_fcntl(int fd, int cmd, int val);
337 
338 /**
339  * set the pathname of the current working directory
340  *
341  * @param path The path to set.
342  *
343  * @return 0 on success, negative error code on failure.
344  *
345  */
346 int vfs_chdir(const char *path);
347 
348 /**
349  * get the pathname of the current working directory.
350  *
351  * @param buf  The buffer to save the current working directory.
352  * @param size The size of buf.
353  *
354  * @return NULL if error occured, buf if succeed.
355  *
356  */
357 char *vfs_getcwd(char *buf, size_t size);
358 
359 /**
360  * @brief Get path conf
361  *
362  * @param[in] path the path conf to get from
363  * @param[in] name the kind of path conf to get
364  *
365  * @return value of path info
366  */
367 int32_t vfs_pathconf(const char *path, int name);
368 
369 /**
370  * @brief Get path info
371  *
372  * @param[in]  name the path info to get
373  *
374  * @return value of path info
375  */
376 int32_t vfs_fpathconf(int fd, int name);
377 
378 /**
379  * @brief Set the access and modification times
380  *
381  * @param[in] path the path conf to get from
382  * @param[in] times the buffer to store time info
383  *
384  * @return 0 on success, negative error code on failure
385  */
386 int vfs_utime(const char *path, const vfs_utimbuf_t *times);
387 
388 /**
389  * @brief Get file descriptor offset
390  *
391  * @return the vfs file descriptor offset
392  *
393  */
394 int32_t vfs_fd_offset_get(void);
395 
396 /**
397  * @brief Bind driver to the file or device
398  *
399  * @param[in] path the path of the file or device
400  * @param[in] ops the driver operations to bind
401  * @param[in] arg  the arguments of the driver operations
402  *
403  * @return 0 on success, negative error on failure
404  *
405  */
406 int32_t vfs_register_driver(const char *path, vfs_file_ops_t *ops, void *arg);
407 
408 /**
409  * @brief Unbind driver from the file or device
410  *
411  * @param[in] path the path of the file or device
412  *
413  * @return 0 on success, negative error on failure
414  *
415  */
416 int32_t vfs_unregister_driver(const char *path);
417 
418 /**
419  * @brief Mount filesystem to the path
420  *
421  * @param[in] path the mount point path
422  * @param[in] ops the filesystem operations
423  * @param[in] arg  the arguments of the filesystem operations
424  *
425  * @return 0 on success, negative error on failure
426  *
427  */
428 int32_t vfs_register_fs(const char *path, vfs_filesystem_ops_t* ops, void *arg);
429 
430 /**
431  * @brief Unmount the filesystem
432  *
433  * @param[in] path the mount point path
434  *
435  * @return 0 on success, negative error on failure
436  *
437  */
438 int32_t vfs_unregister_fs(const char *path);
439 
440 /**
441  * @brief  open vfs file dump
442  *
443  */
444 void vfs_dump_open();
445 
446 /**
447  * @brief vfs list
448  *
449  * @param[in] t vfs list type:fs or device
450  *
451  * @return 0 on success, negative error on failure
452  *
453  */
454 int32_t vfs_list(vfs_list_type_t t);
455 
456 /**
457  * @brief get fs node name for current path.
458  *
459  * @param[in] path           current dir path.
460  * @param[out] names         fs node names which mounted under current path.
461  * @param[out] size          names count.
462  * @return    0 on success, negative error on failure.
463  */
464 int32_t vfs_get_node_name(const char *path, char names[][64], uint32_t* size);
465 
466 /**
467  * @brief set detach state of the node.
468  *
469  * @param[in] name           the name of the node.
470  * @return    0 on success, negative error on failure.
471  */
472 int32_t vfs_inode_detach_by_name(const char *name);
473 
474 /**
475  * @brief the node is busy or not
476  *
477  * @param[in] name           the name of the node.
478  * @return    0 on success, negative error on failure.
479  */
480 int32_t vfs_inode_busy_by_name(const char *name);
481 
482 /**
483  * @brief copy the file descriptor
484  *
485  * @param[in] oldfd  the file descriptor to copy.
486  * @return    0 on success, negative error on failure.
487  */
488 int vfs_dup(int oldfd);
489 
490 /**
491  * @brief copy the file descriptor to new file decriptor
492  *
493  * @param[in] oldfd           the file descriptor to copy.
494  * @param[in] newfd           the new file decriptor.
495  * @return    0 on success, negative error on failure.
496  */
497 int vfs_dup2(int oldfd, int newfd);
498 
499 #ifdef __cplusplus
500 }
501 #endif
502 
503 #endif /* VFS_API_H */
504