filesys.h

picoos源码。The RTOS and the TCP/IP stack will be built automatically.

 * Tests if the file pointer has reached the end of the file.
 * @param file      Handle to an open file.
 * @return True (1) when the file pointer is at the end of the file,
 *         False (0) when there is more data available to be read from
 *         the file, or -1 when an error has happened.
 * @sa fsys_open, fsys_read, fsys_write
 */
sint_t  fsys_eof(const sint_t file);


/**
 * Set the file pointer to a new position.
 * This function is equivalent to the one from the runtime library.
 * @param file      Handle to an open file.
 * @param position  New position of the file pointer. Note that this value
 *                  denotes a relative position, based on the root position
 *                  described by the mode flag.
 * @param origin    Describes the position within the file that is used
 *                  as base for the calculation of the new file pointer
 *                  position. One of the following three flags must be used:
 *                    - FSSEEK_SET  The new position is calculated from
 *                                  the beginning of the file.
 *                    - FSSEEK_CUR  The new position is calculated from
 *                                  the current file pointer position.
 *                    - FSSEEK_END  The new position is calculated from
 *                                  the end of the file.
 * @return The new position withing the file on success, or -1 when
 *         the function failed. 
 * @sa fsys_open, fsys_read, fsys_write
 */
sint_t  fsys_seek(const sint_t file, const sint_t position,
                  const sint_t origin);


/* Get current file pointer position.
 * This function is equivalent to the one from the runtime library.
 * @param file      Handle to an open file.
 * @return The current file pointer position on success or -1 when the
 *         function failed.
 */
sint_t  fsys_tell(const sint_t file);


/**
 * Get some status information about a file.
 * This function is equivalent to the one from the runtime library.
 * @param fname     Filename of the file to return the status about.
 * @param stat      Pointer to a user provided structure that will
 *                  be filled with the status information.
 *                  See struct fsys_stat for details.
 * @return Zero on success, -1 denotes an error.
 */
sint_t  fsys_stat(const char *fname, struct fsys_stat *stat);


/**
 * Find the first file on the drive.
 * This function is equivalent to the one from the runtime library.
 * @param filespec  A mask specifying the filename that shall be searched
 *                  for. Only the asterisk wildcard is allowed.
 * @param fileinfo  Pointer to a user-provided structure that will be
 *                  filled with the information about the found file.
 * @return On success, when a matching file was found, a handle is returned
 *         that can be used for the subsequent call to ::fsys_findnext or
 *         to the final call to ::fsys_findclose. If no matching file was
 *         found, -1 is returned.
 * @note Do not forget to call ::fsys_findclose!
 * @sa fsys_findnext, fsys_findclose.
 */
sint_t  fsys_findfirst(char *filespec, struct fsys_finddata *fileinfo);


/**
 * Find the next file on the drive that matches the search mask
 * passed to the function ::fsys_findfirst.
 * This function is equivalent to the one from the runtime library.
 * @param handle    This is the value that was returned by the
 *                  function ::fsys_findfirst.
 * @param fileinfo  Pointer to a user-provided structure that will be
 *                  filled with the information about the found file.
 * @return On success, when a matching file was found, zero is returned.
 *         When no more files can be found, -1 is returned.
 * @note Do not forget to call ::fsys_findclose!
 * @sa fsys_findfirst, fsys_findclose.
 */
sint_t  fsys_findnext(sint_t handle, struct fsys_finddata *fileinfo);


/**
 * Closes the handle that was returned by ::fsys_findfirst.
 * This function is equivalent to the one from the runtime library.
 * @param handle    This is the value that was returned by the
 *                  function ::fsys_findfirst.
 * @return Zero when at least one more matching file was found,
 *         or -1 when no more files are matching. Note that -1
 *         does not denote an error.
 */
sint_t  fsys_findclose(sint_t handle);


/**
 * Delete a file from a writeable RAM-Drive.
 * @param filename  name of the file to delete,
 *                  wildcards are not allowed.
 * @return zero on success or -1 on error
 */
sint_t  fsys_remove(const char *filename);


/**
 * Rename a file in a writable RAM-Drive.
 * @param from      name of the file to rename,
 *                  wildcards are not allowed.
 * @param to        new name for the file
 * @return  returns zero on success
 */
sint_t  fsys_rename(const char *from, const char *to);


/**
 * Replace an old file by a new file.
 * This function can be used to replace a file by a new one,
 * while the old one is still in use. This allows the implementation
 * of http servers that use static and dynamic html pages:
 * A client can load the old dynamic page while the new one is
 * just writing to the drive. When the new file is fully written,
 * the old one is replaced by it. Then the data area of the old file
 * is freed as soon as the last file handle referencing the file is closed.
 * Please see also the function ::fsys_opent which can be used to create
 * a temporary file for the new dynamic html page.
 * In principle, this replace function does no more than 'rename' and
 * 'delete', but with the exception that it can be applyed on files that
 * are currently in use.
 * @param oldfile   name of the old file that shall be replaced by
 *                  the new one.
 * @param newfile   name of the new file. The new file will be renamed
 *                  to the name of the old file.
 * @return zero on success.
 * @sa fsys_opent
 */
sint_t  fsys_replace(const char *oldfile, const char *newfile);


#if FS_SUBDIRECTORIES

/**
 * Make a new subdirectory.
 * @param pathname  Path and name of the new directory to create.
 * @return zero on success.
 * @note FS_SUBDIRECTORIES must be set to 1 to have this function
 *       compiled in.
 */
sint_t  fsys_mkdir(const char *pathname);


/**
 * Remove an existing but empty subdirectory.
 * @param pathname  Path and name of the directory to remove.
 * @return zero on success.
 * @note FS_SUBDIRECTORIES must be set to 1 to have this function
 *       compiled in.
 */
sint_t  fsys_rmdir(const char *pathname);


/**
 * Build a valid path string from pathname and filename.
 * @param outbuf    Pointer to a user provided buffer to which
 *                  the built string will be stored.
 * @param pathname  name of the path, may include '/..' or '/.'
 * @param filename  name of the file
 * @return the length of the generated path on success.
 *         -1 is returned when no valid path could be built.
 * @note FS_SUBDIRECTORIES must be set to 1 to have this function
 *       compiled in.
 */
sint_t  fsys_buildPathName(char *outbuf, const char *pathname,
                           const char *filename);

#endif /* FS_SUBDIRECTORIES */


/**
 * Formats the RAM-Disk, and erases all data stored in writeable RAM.
 * @param blocksize          Size in bytes of each data block. Can be set
 *                           to 0 to take the default value (= 512 bytes,
 *                           this is the recommended block size.)
 * @param maxFilenameLength  maximum length a filename can have.
 *                           This value should be big enough if
 *                           subdirectories are enabled. But this
 *                           value should not be greater than
 *                           3/4 of the block size. This value may
 *                           be set to zero to take a default value.
 * @return zero on success. This function may fail when no writable
 *         image is present or the given parameters are not valid in
 *         its combination.
 */
sint_t  fsys_format(u32_t blocksize, u32_t maxFilenameLength);


/**
 * Returns the free drive space in bytes.
 * @return free space on the drive (in bytes)
 */
u32_t   fsys_free(void);


/**
 * Shrink an image to the smallest possible size (remove all unused blocks
 * from the image). This function is useful when a small, ROM-able image
 * shall be generated. Note that this function works best with an
 * unfragmented image file.
 * @param image     pointer to the image
 * @return  new size of the image in bytes
 */
u32_t   fsys_shrinkImage(void *image);


/**
 * Add an filesystem image to the filesystem.
 * The image can be marked as readonly when the image resides in
 * a non writable (Flash-) ROM.
 * @param img       pointer to the filesystem image
 * @param readonly  set this flag to nonzero to add a non-writable image.
 * @return zero on success.
 * @note  The filesystem must be initialized before this function
 *        can be called. See function ::fsys_init.
 * @note  If more than one image is added to the filesystem, there
 *        might be a conflict with doubled file names. To prevent
 *        this issue, you should only add one image directly after
 *        calling ::fsys_init.
 * @sa fsys_init
 */
sint_t  fsys_addDriveImage(void *img, sint_t readonly);


/**
 * Initialize the file system.
 * This function must be called before all others.
 * @param size   If this parameter is nonzero, a new and empty RAM based
 *               drive image with this size will be created and added
 *               to the file system.
 * @param blocksize  This value is a don't care when size is zero.
 *                   Otherwise: cluster size (data block size).
 *                   512 bytes is the recommended value (this is the
 *                   default when blocksize is set to zero).
 * @param maxFilenameLength  This value is a don't care when size is zero.
 *                   Otherwise, it is the maximum length a filename can
 *                   have on the drive. When subdirectories are used,
 *                   this value should be big enough (this is the size
 *                   of the pathname and filename).
 * @return zero on success.
 * @sa fsys_term, fsys_addDriveImage
 */
sint_t  fsys_init(u32_t size, u32_t blocksize, u32_t maxFilenameLength);


/**
 * Terminate the filesystem.
 * All memory allocated by the filesystem will be freed.
 * @return zero on success.
 * @sa fsys_init
 */
sint_t  fsys_term(void);


/**
 * This function returns a pointer to the RAM based image in memory.
 * The image is locked after this operation, so no file operation will
 * change the image. After processing the image, the function
 * fsys_unlockImage must be called.
 * @param  size   Optional. When non NULL, pointer to a variable in which
 *                the size (in bytes) of the image will be stored.
 * @return pointer to the filesystem image on success, NULL on error.
 * @sa fsys_unlockImage, fsys_init
 */
void*  fsys_lockAndGetImage(u32_t *size);


/**
 * Unlock an image that was previously locked
 * by a call to the function fsys_lockAndGetImage().
 * @sa fsys_lockAndGetImage
 */
void   fsys_unlockImage(void);


/*@}*/
#endif