Filesystem functions


"Please use these functions for standard input/output operations. SEAL is still in process so it may change something in latewr versions and by these functions you will keep compatibility with them".



io_rename ()
     Description:
       Renames a file or directory.

     Syntax:
       l_int  io_rename ( l_text nameold, l_text namenew );

     Parameters:
       nameold     Old name of file/directory.
       namenew     The new name.

     Returns:
       True if successful. False otherwise.



_io_removefile ()
     Description:
       Removes a file or directory. This only removes empty
       directories. Use io_removefile() instead.

     Syntax:
       l_int  _io_removefile ( l_text src );

     Parameters:
       src         Path to the file or directory to remove.

     Returns:
       True if successful. False otherwise.



_io_copyfile ()
     Description:
       Copies a file or directory. This only copies empty
       directories. Use io_copyfile() for full copying.

     Syntax:
       l_int  _io_copyfile ( l_text dst, l_text src );

     Parameters:
       dst         Path of the new copy.
       src         Path of the original.

     Returns:
       True if successful. False otherwise.



io_realpath ()
     Description:
       Gets the real name of a file that is in a path. This
       function determines wether the path ends with a "\",
       and if it doesn't a "\" is added.

     Syntax:
       l_text  io_realpath ( l_text path, l_text file );

     Parameters:
       path        The path to check.
       file        Name of the file.

     Returns:
       A string with the real path.


     Example:
       If we write:

          l_text all1path = io_realpath("c:/seal/", "seal.exe");
          l_text all2path = io_realpath("c:/seal", "seal.exe");

       then both the variables will contain "c:/seal/seal.exe".



io_mkdir ()
     Description:
       Same as "mkdir(dir)" but keeps compability.

     Syntax:
       l_bool  io_mkdir ( l_text dir );

     Parameters:
       dir         Directory to be created.

     Returns:
       True if successful. False otherwise.



io_uniquedir ()
     Description:
       Gets a unique name for a directory that does not 
       exist in the path.

     Syntax:
       l_text  io_uniquedir ( l_text path );

     Parameters:
       path        Path to directory to search for a name.

     Returns:
       The new directory name.


     Example:
          l_text d1 = io_uniquedir("c:/seal");
          io_mkdir(io_realpath("c:/seal", d1);
          l_text d2 = io_uniquedir("c:/seal");

          d1 = "DIR0"
          d2 = "DIR1"
          ...



io_exist ()
     Description:
       Finds out if a file or directory exists.

     Syntax:
       l_bool  io_exist ( l_text file );

     Parameters:
       file        The file or directory to test.

     Returns:
       True if it exists. False otherwise.



io_isas ()
     Description:
       Finds out if a file has a certain extension.

     Syntax:
       l_bool  io_isas ( l_text file, l_text ext );

     Parameters:
       file        Name of the file
       ext         The extension to compare with.

     Returns:
       True if the extension is the same. False otherwise.



io_isext ()
     Description:
       Checks if a name is an extension or not.

     Syntax:
       l_bool  io_isext ( l_text file );

     Parameters:
       file        The file to check.

     Returns:
       True if it is an extension. False otherwise.

     Example:
          l_bool ext = io_isext("file.*");
          l_bool file = io_isext("file.bmp");

          ext is true.
          file is false.



io_isfile ()
     Description:
       Finds out if a file exists and if it really is a file.

     Syntax:
       l_bool  io_isfile ( l_text file );

     Parameters:
       file        The file to check.

     Returns:
       True if the file exists. False otherwise.



io_isdir ()
     Description:
       Finds out if a directory exists and if it really is a 
       directory.

     Syntax:
       l_bool  io_isdir ( l_text file );

     Parameters:
       file        The directory to check.

     Returns:
       True if the directory exists. False otherwise.



io_filename ()
     Description:
       Gets only the name of the file from it's path.

     Syntax:
       l_text io_filename ( l_text filename );

     Parameters:
       filename    The path to the file.

     Returns:
       A new string with the name.


     Example:
        If we write:

          l_text onlyfile = io_file("c:/seal.exe");

       Then onlyfile will contain "seal.exe".



io_path ()
     Description:
       Gets only the path without the filename.

     Syntax:
       l_text io_path ( l_text filename );

     Parameters:
       filename    The path to remove the filename from.

     Returns:
       A new string with the path.


     Example:
        If we write:

          l_text onlypath = io_path("c:/seal.exe");

       Then onlypath will contain "c:/".



io_isfilename ()
     Description:
       Finds out if the string is a name of a directory or
       a file. Not ".", ".." etc.

     Syntax:
       l_bool  io_isfilename ( l_text file );

     Parameters:
       file        The filename to check.

     Returns:
       True if it is a file or directory name. False otherwise.



io_nicelink ()
     Description:
       Truncates the extension from a filename if it is 
       "*.ldv" or "*.lnk".

     Syntax:
       l_text  io_nicelink ( l_text filename );

     Parameters:
       filename    Name of the file to check.

     Returns:
       A new string containing the edited filename.


     Example:
          l_text link_to_directory = io_nicelink("hello.ldv");
          l_text link_to_file = io_nicelink("ciao.lnk");
          l_text file = io_nicelink("image.bmp");

          link_to_directory = "hello"
          link_to_file = "ciao"
          file = "image.bmp"



io_setlinkedpath ()
     Description:
       Sets a link to a directory.

     Syntax:
       void  io_set_linkedpath ( l_text file, l_text link );

     Parameters:
       file        File containing the link.
       link        The directory to link to.

     Returns:
       -



io_set_linkedfile ()
     Description:
       Sets a link to a file.

     Syntax:
       void  io_set_linkedfile ( l_text file, l_text link );

     Parameters:
       file        File containing the link.
       link        The file to link to.

     Returns:
       -



io_linkedpath ()
     Description:
       Returns the link from a "*.ldv" file that points
       to a directory.

     Syntax:
       l_text  io_linkedpath ( l_text file );

     Parameters:
       file        Linkfile to get link from.

     Returns:
       String containing the link.



     Example:
       If we write:

          l_text shpath = io_linkedpath("c:/seal/desktop/pc/hd-c.ldv");

       then shpath contains "c:/"



io_linkedfile ()
     Description:
       Returns the link from a "*.lnk" file that points
       to a file.

     Syntax:
       l_text  io_linkedfile ( l_text file );

     Parameters:
       file        Linkfile to get link from.

     Returns:
       String containing the link.


     Example:
       If we write:

          l_text shfile = io_linkedfile("c:/seal/desktop/hello.lnk");

       then shfile contains "c:/seal/image.exe" f.e.



new_tfile ()
     Description:
       Creates a new t_file structure. Allocates memory for it
       and sets its arguments. When "id" of {t_data or t_list or
       t_object[data_type]} is set to "DAT_FILE", it means that 
       some pointer will point to this structure. We will explain 
       more about the t_data structure and the DAT_XXXX types later.

     Syntax:
       t_file *new_tfile ( l_text path, l_text filename, l_int attrib,
                           l_word time, l_word date, l_dword size );

     Parameters:
       path        Path to the file.
       filename    Name of the file.
       attrib      File attributes.
       time        Time of creation. 
                   (hours, minutes, seconds)
       date        Date of creation.
                   (years-1980, month, day)
       size        Filesize.

     Returns:
       A new t_file structure.



The t_file structure

     typedef struct t_file {

        l_text       path; /* path to file */
        l_text       filename; /* filename of file */
        l_int        attrib; /* atributions of file */

        l_word       time;  /* hours:5, minutes:6, (seconds/2):5 */
        l_word       date;  /* (year-1980):7, month:4, day:5 */
        l_dword      size;  /* size of file */

        l_char       reserved[24]; /* for next vesrions */

     } t_file;



io_cleartfile ()
     Description:
       Clears memory for a t_file pointer. The same as
       using "clear_type(f, sizeof(t_file))" or 
       "memset(f, 0, sizeof(t_file))".

     Syntax:
       void  io_cleartfile ( t_file *f );

     Parameters:
       f           The pointer to clear.

     Returns:
       -



io_filetotfile ()
     Description:
       Converts a filename to a t_file structure.

     Syntax:
       t_file  io_filetotfile ( l_text filename );

     Parameters:
       filename    The real path to the file.
                   Looks like "path/filename".

     Returns:
       The new t_file structure.



io_tfiletofile ()
     Description:
       Converts a pointer to a t_file structure to a real
       filename. Same as "io_realpath(f->path, f->filename)".

     Syntax:
       l_text  io_tfiletofile ( t_file *f ); 

     Parameters:
       f           t_file structure to convert.

     Returns:
       A new string containing the filename.



free_tfile ()
     Description:
       Frees the context of the pointer and the pointer itself.

     Syntax:
       void  free_tfile ( void *p );

     Parameters:
       p           The pointer to free.

     Returns:
       -



io_findfirst ()
     Description:
       Finds the first occurence of a file with the defined attributes
       and puts the result in a t_ffblk structure. This function is 
       similar to the "findfirst()" function, but it support linkfiles 
       and it keeps compatility with future versions. Please use this 
       function for all file findings. 

     Syntax:
       int  io_findfirst(const char *pathname, struct t_ffblk *ffblk,
                         int attrib);

     Parameters:
       pathname    Name of the file to find.
       t_ffblk     The structure to put the result in.
       attrib      Attributes of the file to find.

     Returns:
       Return 0 if the file was found. Otherwise it returns non-zero. 



The t_ffblk structure
     Warning: t_ffblk is not the same as ffblk in C.


     typedef struct t_ffblk {


        struct ffblk info;      /* This is the ffblk status you will get 
                                   from the findfirst/findnext functions. */


        l_int   ff_reservedint;    /* Do not use! */

        l_char  ff_filename[260];  /* The real filename. */


        /*  WARNING: info.ff_name now contains a "nice file", which means 
                     that extensions like "*.ldv" and "*.lnk" are ignored. 
                     For real the filename use ff_filename variable.  */

             
        l_char  ff_reserved[24];   /* For future versions of Seal. */


     } t_ffblk;



io_findnext ()
     Description:
       Find the next occurence of a file previously defined with the
       io_findfirst() function. Use these functions together to keep 
       compatibility. 


     Syntax:
       int  io_findnext(struct t_ffblk *ffblk);

     Parameters:
       ffblk       The f_ffblk structure to find.

     Returns:
       Return non-zero if no next file found, or ZERO  in successful.



io_foreach_file_ex ()
     Description:
       Runs a callback function for each file in a directory and all
       it's subdirectories.

     Syntax:
       t_dirinfo io_foreach_file_ex ( l_text path, l_int flags,
                                      l_int (*callback)(), p_object o,
                                      l_dword *ind );

     Parameters:
       path        Path to directory to run the function.
       flags       May contain one of or a combination of:

                      DIF_SIZE - get size of directory.
                      DIF_HALT - process was halted not use for function, 
                                 it's only returned argument.
               DIF_DIRCALLBACK - callback function is also called for 
                                 directories, not only for files.                    

       callback()  The callback function to run.
       o           A pointer to the t_object structure that controls
                   the process. Doesn't have to be used, but it enables
                   halting of the process. If something destroys this
                   object, the process will be halted.
       ind         A pointer to a l_dword variable that contains the
                   number of files for which the function was run.

     Returns:
       A t_dirinfo structure with information.



The t_dirinfo structure

     typedef struct t_dirinfo {


       l_dword  dirs;  - contains number of all directories and 
                          its sub-directories in directory (path)
       l_dword  files; - contains all files.
       l_dword  size;  - contains size of all files. This       
                         variables is set only if flags is set to 
                         DIF_SIZE, else is set to zero.
       l_int  flags;   - return status. Now only ZERO if ok, else       
                         DIF_HALT, if p_object (o) was destroyed. 
       l_char reserved[24]; - used for later versions


     } t_dirinfo;



io_foreach_file_copy ()
     Description:
       Copies all files in a directory to another directory.

     Syntax:
       l_int   io_foreach_file_copy ( l_text dst, l_text path, p_object o,
                                      l_dword *ind );

     Parameters:
       dst         The directory to copy the files to.
       path        Path to directory containing files to be copied.
       o           A pointer to the t_object structure that controls
                   the process. Doesn't have to be used, but it enables
                   halting of the process. If something destroys this
                   object, the process will be halted.
       ind         A pointer to a l_dword variable that contains the
                   number of files for which the function was run.
       

     Returns:
       Non-zero if successful. Otherwise zero.



io_removefile ()
     Description:
       Removes (deletes) a file or directory. Please use this function
       for removing. It controls all!

     Syntax:
       l_int  io_removefile ( p_object ob, t_file *f, l_dword *ind );

     Parameters:
       ob          A pointer to the t_object structure that controls
                   the process. Doesn't have to be used, but it enables
                   halting of the process. If something destroys this
                   object, the process will be halted.
       f           The file or directory to remove.
       ind         A pointer to a l_dword variable that contains the
                   number of files for which the function was run.


     Returns:
       True if successful. False otherwise.



io_copyfile ()
     Description:
       Copies a file or directory. Use this for successful copying.

     Syntax:
       l_int   io_copyfile ( p_object ob, t_file *dst, t_file *src, 
                             l_dword *ind );

     Parameters:
       ob          A pointer to the t_object structure that controls
                   the process. Doesn't have to be used, but it enables
                   halting of the process. If something destroys this
                   object, the process will be halted.
       dst         Path to the new file or directory.
       src         Path to the original file or directory.
       ind         A pointer to a l_dword variable that contains the
                   number of files for which the function was run.

     Returns:
       Non-zero if successful. Otherwise zero.



io_numberfile ()
     Description:
       Gets the number of files in a file/directory.

     Syntax:
       l_int  io_numberfile ( p_object ob, t_file *dst, l_dword *ind );

     Parameters:
       ob          A pointer to the t_object structure that controls
                   the process. Doesn't have to be used, but it enables
                   halting of the process. If something destroys this
                   object, the process will be halted.
       dst         Path to the directory to count in.
       ind         A pointer to a l_dword variable that will contain 
                   the number of files found in the directory.

     Returns:
       Non-zero if successful. Otherwise zero.