## Files and Folders

### FUNCTIONS

      FILE *open_file(char *filepath, char *mode);
      int   close_file(FILE *f);
      int   remove_file(char *filepath);
      int   rename_file(char *oldpath, char *newpath);

      Folder *open_folder(char *foldername);
      char *  read_folder(Folder *f);
      int     close_folder(Folder *f);
      int     make_folder(char *folderpath, int mode);
      int     remove_folder(char *folderpath);
      int     rename_folder(char *oldpath, char *newpath);
      char *  current_folder(void);
      int     set_current_folder(char *folderpath);

      int   file_info(char *filepath);
      long  file_size(char *filepath);
      long  file_time(char *filepath);

      char *form_file_path(char *foldername, char *filename);
      char *get_file_name(char *filepath);

### CONSTANTS

      enum FileInfo {
        IS_APP    = 1,
        IS_WRITE  = 2,
        IS_READ   = 4,
        IS_FOLDER = 8,
        IS_FILE   = 16
      };

### NOTES

Operating systems often differ when it comes to accessing files and directories (folders). There are many differences, but two of the main differences are the directory separator character (which is '/' in Unix), and the way to up one directory level (which is '..' in Unix).

The functions in this section have been provided to allow all code to access files and folders using the Unix-style notation.

Ordinarily, a standard C function such as `fopen` accepts a platform-specific C string to use to locate a file. On a Linux platform this might be a string such as "../manual/folders.htm" while on Windows this would be "..\manual\folders.htm" and on some Macintosh systems might be written as "::manual:folders.htm". These differences cause difficulties when porting C source code.

The open_file function can be used as a cross-platform replacement for fopen. It translates the given Unix-style file path string into whatever style the operating system requires. On Windows, for instance, it exchanges '/' for '\' in a copy of the file path string, then calls fopen, then frees the temporary string. Using open_file instead of fopen allows code to assume Unix-style file and directory names everywhere.

Correspondingly, close_file replaces fclose, except that it returns 1 for success, and 0 for failure. Passing a NULL file pointer to this function is valid and returns 1.

The remove_file function attempts to delete the named file, returning 1 for success, 0 for failure. The name is given in Unix-style notation.

The rename_file function renames a file on the file system from the old path name to the new, both given in Unix-style notation. This can be used to rename a file, and/or move a file to a new folder. It returns 1 for success, 0 for failure.

The open_folder function opens a directory for reading, using a Unix-style directory specifier. The ".." path component causes a textual removal of the previous path component, if any, and "." components are removed, since they represent the same directory. Again, '/' represents the directory path separator on all platforms, but is internally substituted with the platform-specific separator.

The read_folder function reads one file or directory name from the open folder, returning a pointer to a static zero-terminated string which contains the name, or NULL if there are no more names listed in that directory. The names "." and ".." will usually be present as the first items on the list. The list of names will not be sorted into alphabetic order.

The close_folder function closes an open folder, returning 1 for success, 0 if there is an error. Passing a NULL folder pointer to this function is valid and returns 1.

Use make_folder to create a new folder with the given name and mode, if possible. The name is given in Unix-style notation. The mode is a bit-field, consisting of three groups of three permission bits, in the order `rwxrwxrwx` where 'r' means read access, 'w' means write access, and 'x' means execute or search access. The first (highest) group of bits refers to user-level access, the next to group access, and the last to world access. The mode is often written as an octal constant, such as 0755 (which is `rwxr-xr-x` mode), or 0700 (which is `rwx------` mode, or user access only). The mode may be ignored by some implementations if the operating system cannot support such access modes. The function returns 1 for success, 0 for failure.

The remove_folder function attempts to delete the named folder from the file system, returning 1 for success, 0 for failure. The name is given in Unix-style notation. The operation will fail if there are any files or folders contained within the folder which is being deleted.

The rename_folder function renames a folder on the file system from the old path name to the new, both given in Unix-style notation. This can be used to rename a folder, and/or move a folder into a new folder. It returns 1 for success, 0 for failure.

Use current_folder to discover the current working directory, given using Unix-style notation.

The set_current_folder function changes the current working directory to the specified path, given in Unix-style notation. It returns 1 for success, 0 for failure.

The file_info function is a cross-platform version of the standard C function fstat, which returns some flags yielding information about the given file or directory. The returned integer is a bit-field with the following possible values:

- `IS_APP` is set if the executable flag is present on the file or folder.
- `IS_WRITE` is set if the file or folder can be written to.
- `IS_READ` is set if the file or folder can be read.
- `IS_FOLDER` is set if the path refers to a directory.
- `IS_FILE` is set if the path refers to a file.

The file_size function reports the size in bytes of the specified file. The path uses Unix-style notation.

The file_time function returns the last modification time of the specified file, represented in seconds since the start of the epoch (the current epoch is from Jan 1, 1970). The path uses Unix-style notation.

The form_file_path function joins a Unix-style directory path name and a file name, to produce a new correct Unix-style path name. The string is created using alloc, and so should later be freed using free. The function inserts a '/' between the path and the file name if necessary.

The get_file_name function returns a pointer to the start of just the file name from a full path name, discarding the folder information. Because this is just a pointer to the first character in the file name, the returned string should not be freed.