[Cosm Logo]

File and Directory Functions

v3FileOpen

Syntax

 
#include "cosmfile.h"
s32 v3FileOpen( v3_FILE * file, const ascii * filename,
  u32 mode, u32 lock );

Description

Attempt to open the filename in the mode with the lock.

Paths are always in the Cosm "native|/path/path2/filename" format. This is important for the system because any platform that can will do a chroot() before running, non-chroot systems will tack addition path on the front at runtime. The 'other' slash is translated on the fly if needed, but internally, it's all stored in the same format. The native portion of the path (everything before and including the '|') is platform specific for devices/nodes on wierd OSes. e.g. "e:|/temp/a.txt"(win32), or "//4|/tmp/a.txt" (qnx). If paths are ever sent over the net, this native portion will be stripped.

File Modes:

V3_FILE_MODE_EXIST
Test for file existence only.
V3_FILE_MODE_READ
Open for reading.
V3_FILE_MODE_WRITE
Open for writing.
V3_FILE_MODE_APPEND
Open at end of file, write only.
V3_FILE_MODE_CREATE
Create the file if it doesn't exist.
V3_FILE_MODE_TRUNCATE
Truncate an existing file on open.
V3_FILE_MODE_SYNC
Write functions sync() before return.

Files Locks:

V3_FILE_LOCK_NONE
No file locking is needed, but other locks must be observed.
V3_FILE_LOCK_READ
Lock the file with a read lock. This means that other processes can read the file, even add other read locks, but none will be allowed to open the file for writing.
V3_FILE_LOCK_WRITE
Lock the file with a write lock. No other readers or writers will be allowed access to the file when this lock is set.

Return Values

V3_PASS on success, or an error code on failure.

Errors

V3_FILE_ERROR_DENIED
Access denied.
V3_FILE_ERROR_NOTFOUND
File/Handle not found.
V3_FILE_ERROR_WRITEMODE
Write access denied.
V3_FILE_ERROR_CLOSED
File is closed.
V3_FILE_ERROR_NAME
Invalid file name.
V3_FILE_ERROR_MODE
Open flags conflict.

Example

 
  v3_FILE * file;
  s32 result;

  file = v3MemAlloc( v3u64u32( sizeof(v3_FILE) ), V3_MEM_NORMAL );

  result = v3FileOpen( file, "/etc/fstab", V3_FILE_MODE_READ,
    V3_FILE_LOCK_NONE );

  if ( result == V3_PASS )
    v3PrintA( (ascii *) "/etc/fstab open for reading.\n" );
  else
    v3PrintA( (ascii *) "Unable to open /etc/fstab for reading.\n" );

v3FileRead

Syntax

 
#include "cosmfile.h"
s32 v3FileRead( void * buffer, u64 * bytes_read, v3_FILE * file,
  u64 length );

Description

Read length bytes from the file into the buffer. bytes_read is set to the number of bytes actually read.

Return Values

V3_PASS on success, or an error code on failure.

Errors

Upon failure last_error of file will be set to one of the following:

V3_FILE_ERROR_DENIED
Access denied.
V3_FILE_ERROR_NOTFOUND
File/Handle not found.
V3_FILE_ERROR_CLOSED
File is closed.

Example

 
  v3_FILE * file;
  char getbuff[31];
  u64 bytesread;
  s32 error;

  /* ... */

  error = v3FileRead( getbuff, &bytesread, file, v3u64u32( 30 ) );

  if ( error != V3_PASS )
  {
    v3PrintA( (ascii *) "We weren't able to read from the file.\n" );
  }
  else
  {
    *( (u8 *) v3MemOffset( getbuff, bytesread ) ) = 0;
    v3PrintA( (ascii *) "We read %u bytes: %.30s\n",
      bytesread, getbuff );
  }

v3FileWrite

Syntax

 
#include "cosmfile.h"
s32 v3FileWrite( v3_FILE * file, u64 * bytes_written,
  const void * const buffer, u64 length );

Description

Write length bytes to the file from the buffer. bytes_written is set to the number of bytes actually written.

Return Values

V3_PASS on success, or an error code on failure.

Errors

Upon failure last_error of file will be set to one of the following:

V3_FILE_ERROR_DENIED
Access denied.
V3_FILE_ERROR_NOTFOUND
File/Handle not found.
V3_FILE_ERROR_CLOSED
File is closed.

Example

 
  ascii to_write[30];
  v3_FILE * file;
  u64 written;
  u64 length;
  s32 error;

  /* ... */

  v3StrCopyA( to_write, "Hello World!\n", v3u64u32( 30 ) );
  length = v3StrLengthA( to_write );

  error = v3FileWrite( file, &written, to_write, length );

  if ( v3u64Eq( length, written ) )
  {
    v3PrintA( (ascii *) "Success! %v bytes written.\n", written );
  }
  else
  {
    /* do stuff with error */
    /* ... */
    v3PrintA( (ascii *) "Wrote only %v bytes (of %v)\n", written,
      length );
  }

v3FileSeek

Syntax

 
#include "cosmfile.h"
s32 v3FileSeek( v3_FILE * file, u64 offset );

Description

Move the current file offset (in bytes). If the file is open in mode V3_FILE_MODE_APPEND, you can't seek.

Return Values

V3_PASS on success, or an error code on failure.

Errors

V3_FILE_ERROR_CLOSED
File is closed.
V3_FILE_ERROR_SEEK
Seek error.
V3_FILE_ERROR_DENIED
Access Denied.
V3_FILE_ERROR_NOTFOUND
File/Handle not found.

Example

 
  v3_FILE * file;
  s32 result;

  /* ... */

  result = v3FileSeek( file, v3u64u32( 4096 ) );

  if ( result == V3_PASS )
    v3PrintA( (ascii *) "Now at byte position 4096 in the file.\n" );
  else
    v3PrintA( (ascii *) "Seek failed.\n" );

v3FileTell

Syntax

 
#include "cosmfile.h"
s32 v3FileTell( u64 * offset, v3_FILE * file );

Description

Get the current file offset.

Return Values

V3_PASS on success, or an error code on failure.

Errors

V3_FILE_ERROR_CLOSED
File is closed.
V3_FILE_ERROR_NOTFOUND
File/Handle not found.
V3_FILE_ERROR_TELL
Tell error.

Example

 
  v3_FILE * file;
  u64 offset;
  s32 result;

  /* ... */

  result = v3FileTell( &offset, file );

  if ( result == V3_PASS )
    v3PrintA( (ascii *) "Currently at byte offset %v in the file.\n",
      offset );
  else
    v3PrintA( (ascii *) "Unable to read position in file.\n" );

v3FileEOF

Syntax

 
#include "cosmfile.h"
s32 v3FileEOF( v3_FILE * file );

Description

Test EOF (End Of File) state.

Return Values

V3_PASS if there is more to read, V3_FILE_ERROR_EOF if EOF, or an error code on failure.

Errors

V3_FILE_ERROR_EOF
End of file.
V3_FILE_ERROR_CLOSED
File is closed.
V3_FILE_ERROR_TELL
Tell error.
V3_FILE_ERROR_LENGTH
Unable to discover file length.

Example

 
  v3_FILE * file;

  /* ... */

  if ( !v3FileEOF( file ) )
    v3PrintA( (ascii *) "There is more data to read.\n" );
  else
  {
    v3PrintA( (ascii *) "No more data to be read.\n" );
    return( 0 );
  }

v3FileLength

Syntax

 
#include "cosmfile.h"
s32 v3FileLength( u64 * length, v3_FILE * file );

Description

Set length to the length of the open file.

Return Values

V3_PASS on success, or an error code on failure.

Errors

V3_FILE_ERROR_CLOSED
File is closed.
V3_FILE_ERROR_LENGTH
Unable to discover file length.

Example

 
  v3_FILE * file;
  u64 length;
  s32 result;

  /* ... */

  result = v3FileLength( &length, file );

  if ( result == V3_PASS )
    v3PrintA( (ascii *) "The length of the file is %v bytes.\n",
      length);
  else if ( result == V3_FILE_ERROR_CLOSED )
    v3PrintA( (ascii *)
      "The file is closed. Can not read length.\n" );
  else
    v3PrintA( (ascii *) "Error. Unable to read file length.\n" );

v3FileTruncate

Syntax

 
#include "cosmfile.h"
s32 v3FileTruncate( v3_FILE * file, u64 length );

Description

Truncate the file at length bytes. Current offset will be moved to the end of the file.

Return Values

V3_PASS on success, or an error code on failure.

Errors

V3_FILE_ERROR_DENIED
Access denied.
V3_FILE_ERROR_NOTFOUND
File/Handle not found.
V3_FILE_ERROR_WRITEMODE
Write access denied.
V3_FILE_ERROR_CLOSED
File is closed.

Example

 
  v3_FILE * file;
  s32 result;

  /* ... */

  result = v3FileTruncate( file, v3u64u32( 10000 ) );

  if ( result == V3_PASS )
    v3PrintA((ascii *)
      "File truncated to exactly 10000 bytes in length.\n" );
  else
    v3PrintA( (ascii *) "Could not truncate file.\n" );

v3FileClose

Syntax

 
#include "cosmfile.h"
s32 v3FileClose( v3_FILE * file );

Description

Close the file.

Return Values

V3_PASS on success, or an error code on failure.

Errors

V3_FILE_ERROR_NOTFOUND
File/Handle not found.
V3_FILE_ERROR_CLOSED
File is closed.

Example

 
  v3_FILE * file;

  /* ... */

  v3FileClose( file );
  v3ProcessEnd( 0 );

v3FileDelete

Syntax

 
#include "cosmfile.h"
s32 v3FileDelete( const ascii * filename );

Description

Attempt to delete the file specified by filename. See v3FileOpen for how to specify the path and file name. Deletion will involve a full wipe of the file data.

Return Values

V3_PASS on success, or an error code on failure.

Errors

V3_FILE_ERROR_DENIED
Access denied.
V3_FILE_ERROR_NOTFOUND
File/Handle not found.
V3_FILE_ERROR_NAME
Invalid file name.

Example

 
  s32 result;

  result = v3FileDelete( "/tmp/file" );
  if ( result == V3_PASS )
    v3PrintA( "File /tmp/file was successfully removed.\n" );
  else
  {
    if ( result == V3_FILE_ERROR_DENIED )
      v3PrintA( (ascii *)
        "Unable to delete /tmp/file: Access denied.\n" );
    else
      v3PrintA( (ascii *)
        "Unable to delete /tmp/file: File doesn't exist.\n" );
  }

v3FileInfo

Syntax

 
#include "cosmfile.h"
s32 v3FileInfo( v3_FILE_INFO * info, const ascii * filename );

Description

Get Information about a file. The v3_FILE_INFO struct has the following structure. 

typedef struct
{
  u64 length;
  u32 type;
  u32 rights;
  v3_time create;
  v3_time modify;
  v3_time access;
} v3_FILE_INFO;

Return Values

V3_PASS on success, or an error code on failure.

Errors

Example

 



    


    
    

      v3DirOpen
    


    
Syntax



#include "cosmfile.h"
s32 v3DirOpen( v3_DIR * dir, const ascii * dirname, u32 mode );




    
Description

    

      Attempt to open the dirname in the specified mode.
      See v3FileOpen for how to
      specify the path.
    

    

      Directory Modes:
    

    

      
V3_DIR_MODE_EXIST
      
Test for directory existence only.
      
V3_DIR_MODE_READ
      
Open for reading only.
      
V3_DIR_MODE_CREATE
      
Create the directory if it doesn't exist. Parent directories
        will be created if needed.

    


    
Return Values

    

      V3_PASS on success, or an error code on failure.
    


    
Errors

    

      
V3_DIR_ERROR_DENIED
      
Access denied.
      
V3_DIR_ERROR_NOTFOUND
      
Directory not found.
      
V3_DIR_ERROR_CREATE
      
Unable to create new directory.
      
V3_DIR_ERROR_MODE
      
Open flags conflict.
      
V3_DIR_ERROR_CLOSED
      
Attempted to reopen an already open directory.
      
V3_DIR_ERROR_NAME
      
Invalid directory name.
    


    
Example



  v3_DIR * dir;
  s32 result;

  dir = v3MemAlloc( v3u64u32( sizeof( v3_DIR ) ), V3_MEM_NORMAL );

  result = v3DirOpen( dir, "/var/", V3_DIR_MODE_READ );
  if ( result == V3_PASS )
    v3PrintA( (ascii *)
      "Call to v3DirOpen passed. /var is open.\n" );
  else {
    v3PrintA( (ascii *) "Call to v3DirOpen failed. Dying.\n" );
    return( 1 );
  }




    


    
    

      v3DirRead
    


    
Syntax



#include "cosmfile.h"
s32 v3DirRead( v3_FILENAME * buffer, u64 * names_read, u64 length,
  v3_DIR * dir );




    
Description

    

      Read length file names from the dir into the
      buffer. Set names_read to the number of
      filenames read, zero on error.
    


    
Return Values

    

      V3_PASS on success, or an error code on failure.
    


    
Errors

    

      Upon failure last_error of dir will be set to one of
      the following:
    

    

      
V3_DIR_ERROR_NOTFOUND
      
Directory not found.
      
V3_DIR_ERROR_EOF
      
End of directory.
      
V3_DIR_ERROR_CLOSED
      
Attempted to reopen an already open directory.
      
V3_DIR_ERROR_NAME
      
Invalid directory name.
    


    
Example



  v3_DIR * dir;
  v3_FILENAME * getbuff;
  u64 count;

  /* ... */

  while ( v3DirRead( getbuff, &count, v3u64u32( 1 ), dir ) )
    == V3_PASS )
  {
    v3PrintA( (ascii *) "File: %.256s\n", getbuff );
  }




    


    
    

      v3DirDelete
    


    
Syntax



#include "cosmfile.h"
s32 v3DirDelete( const ascii * dirname );




    
Description

    

      Attempt to delete the directory specified by dirname. Will
      only work if the directory is empty. See
      v3FileOpen for how to specify
      the path.
    


    
Return Values

    

      V3_PASS on success, or an error code on failure.
    


    
Errors

    

      
V3_DIR_ERROR_DENIED
      
Access denied.
      
V3_DIR_ERROR_NOTFOUND
      
Directory not found.
      
V3_DIR_ERROR_NOTEMPTY
      
Directory is not empty (no delete).
      
V3_DIR_ERROR_NAME
      
Invalid directory name.
    


    
Example



  s32 result;

  result = v3DirDelete( "/tmp/dir" );

  if ( result == V3_PASS )
    v3PrintA( (ascii *) "/tmp/dir was successfully deleted.\n" );
  else
  {
    if ( result == V3_DIR_ERROR_NOTFOUND )
      v3PrintA( (ascii *) "/tmp/dir doesn't exist.\n" );
    else
      v3PrintA( (ascii *) "/tmp/dir cannot be deleted.\n" );
  }




    


    
    

      v3DirClose
    


    
Syntax



#include "cosmfile.h"
s32 v3DirClose( v3_DIR * dir );




    
Description

    

       Close the directory.
    


    
Return Values

    

      V3_PASS on success, or an error code on failure.
    


    
Errors

    

      
V3_DIR_ERROR_NOTFOUND
      
Directory not found.
      
V3_DIR_ERROR_CLOSED
      
Attempted to reopen an already open directory.
    


    
Example



  v3_DIR * dir;
  s32 result;

  /* ... */

  result = v3DirClose( dir );

  if ( result == V3_PASS )
    v3PrintA( (ascii *) "The directory was closed.\n" );
  else
    v3PrintA( (ascii *)
      "The directory was not open or doesn't exist.\n" );




    


    
    

      v3Load
    


    
Syntax



#include "cosmfile.h"
void v3u16Load( u16 * num, const void * bytes );
void v3u32Load( u32 * num, const void * bytes );
void v3u64Load( u64 * num, const void * bytes );
void v3u128Load( u128 * num, const void * bytes );




    
Description

    

      Load the big endian bytes of specified type into the native
      num.
    


    
Return Values

    

      None.
    


    
Errors

    

      None. Note that if bytes or num is NULL, no action
      will be performed.
    


    
Example



  u8 * bytes;
  u128 num;

  bytes = v3MemAlloc( v3u64u32( 8 ), V3_MEM_NORMAL );

  /* ...'bytes' gets read from a file or from the net... */

  v3u128Load( &num, bytes );




    


    
    

      v3Save
    


    
Syntax



#include "cosmfile.h"
void v3u16Save( void * bytes, const u16 * num );
void v3u32Save( void * bytes, const u32 * num );
void v3u64Save( void * bytes, const u64 * num );
void v3u128Save( void * bytes, const u128 * num );




    
Description

    

      Save the native num of specified type into big endian
      bytes.
    


    
Return Values

    

      None.
    


    
Errors

    

      None. Note that if bytes or num is NULL, no action
      will be performed.
    


    
Example



  u8 * bytes;
  u128 num;

  bytes = v3MemAlloc( v3u64u32(8), V3_MEM_NORMAL );

  /* ... */

  v3u128Save( bytes, &num );

  /* 'bytes' is now safe to send to a file or over the net */









  

    © Copyright Mithral Communications & Design Inc.
    
    1995-2003.
    All rights reserved.
    Mithral® and Cosm® are trademarks of
    Mithral Communications & Design Inc.
    

    
    Document last modified: May 22, 2003