[Cosm Logo]

File and Directory Functions

CosmFileOpen

Syntax

 
#include "cosm/os_file.h"
s32 CosmFileOpen( cosm_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:

COSM_FILE_MODE_EXIST
Test for file existence only.
COSM_FILE_MODE_READ
Open for reading.
COSM_FILE_MODE_WRITE
Open for writing.
COSM_FILE_MODE_APPEND
Open at end of file, write only.
COSM_FILE_MODE_CREATE
Create the file if it doesn't exist.
COSM_FILE_MODE_TRUNCATE
Truncate an existing file on open.
COSM_FILE_MODE_SYNC
Write data to disk before return.
COSM_FILE_MODE_NOBUFFER
No read/write buffering. This will have performance negative consequences in most cases. It also requires sector and memory aligned read/writes on some platforms.

Files Locks:

COSM_FILE_LOCK_NONE
No file locking is needed, but other locks must be observed.
COSM_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.
COSM_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

COSM_PASS on success, or an error code on failure.

Errors

COSM_FILE_ERROR_DENIED
Access denied.
COSM_FILE_ERROR_NOTFOUND
File/Handle not found.
COSM_FILE_ERROR_WRITEMODE
Write access denied.
COSM_FILE_ERROR_CLOSED
File is closed.
COSM_FILE_ERROR_NAME
Invalid file name.
COSM_FILE_ERROR_MODE
Open flags conflict.

Example

 
  cosm_FILE * file;
  s32 result;

  file = CosmMemAlloc( sizeof( cosm_FILE ) );

  result = CosmFileOpen( file, "/etc/fstab", COSM_FILE_MODE_READ,
    COSM_FILE_LOCK_NONE );

  if ( result == COSM_PASS )
    CosmPrint( "/etc/fstab open for reading.\n" );
  else
    CosmPrint( "Unable to open /etc/fstab for reading.\n" );

CosmFileRead

Syntax

 
#include "cosm/os_file.h"
s32 CosmFileRead( void * buffer, u64 * bytes_read, cosm_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

COSM_PASS on success, or an error code on failure.

Errors

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

COSM_FILE_ERROR_DENIED
Access denied.
COSM_FILE_ERROR_NOTFOUND
File/Handle not found.
COSM_FILE_ERROR_CLOSED
File is closed.

Example

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

  /* ... */

  error = CosmFileRead( getbuff, &bytesread, file, 30LL );

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

CosmFileWrite

Syntax

 
#include "cosm/os_file.h"
s32 CosmFileWrite( cosm_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

COSM_PASS on success, or an error code on failure.

Errors

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

COSM_FILE_ERROR_DENIED
Access denied.
COSM_FILE_ERROR_NOTFOUND
File/Handle not found.
COSM_FILE_ERROR_CLOSED
File is closed.

Example

 
  utf8 to_write[30];
  cosm_FILE * file;
  u64 written;
  u64 length;
  s32 error;

  /* ... */

  CosmStrCopy( to_write, "Hello World!\n", 30LL );
  length = CosmStrBytes( to_write );

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

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

CosmFileSeek

Syntax

 
#include "cosm/os_file.h"
s32 CosmFileSeek( cosm_FILE * file, u64 offset );

Description

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

Return Values

COSM_PASS on success, or an error code on failure.

Errors

COSM_FILE_ERROR_CLOSED
File is closed.
COSM_FILE_ERROR_SEEK
Seek error.
COSM_FILE_ERROR_DENIED
Access Denied.
COSM_FILE_ERROR_NOTFOUND
File/Handle not found.

Example

 
  cosm_FILE * file;
  s32 result;

  /* ... */

  result = CosmFileSeek( file, 4096LL );

  if ( result == COSM_PASS )
    CosmPrint( "Now at byte position 4096 in the file.\n" );
  else
    CosmPrint( "Seek failed.\n" );

CosmFileTell

Syntax

 
#include "cosm/os_file.h"
s32 CosmFileTell( u64 * offset, cosm_FILE * file );

Description

Get the current file offset.

Return Values

COSM_PASS on success, or an error code on failure.

Errors

COSM_FILE_ERROR_CLOSED
File is closed.
COSM_FILE_ERROR_NOTFOUND
File/Handle not found.
COSM_FILE_ERROR_TELL
Tell error.

Example

 
  cosm_FILE * file;
  u64 offset;
  s32 result;

  /* ... */

  result = CosmFileTell( &offset, file );

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

CosmFileEOF

Syntax

 
#include "cosm/os_file.h"
s32 CosmFileEOF( cosm_FILE * file );

Description

Test EOF (End Of File) state.

Return Values

COSM_PASS if there is more to read, COSM_FILE_ERROR_EOF if EOF, or an error code on failure.

Errors

COSM_FILE_ERROR_EOF
End of file.
COSM_FILE_ERROR_CLOSED
File is closed.
COSM_FILE_ERROR_TELL
Tell error.
COSM_FILE_ERROR_LENGTH
Unable to discover file length.

Example

 
  cosm_FILE * file;

  /* ... */

  if ( !CosmFileEOF( file ) )
    CosmPrint( "There is more data to read.\n" );
  else
  {
    CosmPrint( "No more data to be read.\n" );
    return 0;
  }

CosmFileLength

Syntax

 
#include "cosm/os_file.h"
s32 CosmFileLength( u64 * length, cosm_FILE * file );

Description

Set length to the length of the open file.

Return Values

COSM_PASS on success, or an error code on failure.

Errors

COSM_FILE_ERROR_CLOSED
File is closed.
COSM_FILE_ERROR_LENGTH
Unable to discover file length.

Example

 
  cosm_FILE * file;
  u64 length;
  s32 result;

  /* ... */

  result = CosmFileLength( &length, file );

  if ( result == COSM_PASS )
    CosmPrint( "The length of the file is %v bytes.\n",
      length);
  else if ( result == COSM_FILE_ERROR_CLOSED )
    CosmPrint(
      "The file is closed. Can not read length.\n" );
  else
    CosmPrint( "Error. Unable to read file length.\n" );

CosmFileTruncate

Syntax

 
#include "cosm/os_file.h"
s32 CosmFileTruncate( cosm_FILE * file, u64 length );

Description

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

Return Values

COSM_PASS on success, or an error code on failure.

Errors

COSM_FILE_ERROR_DENIED
Access denied.
COSM_FILE_ERROR_NOTFOUND
File/Handle not found.
COSM_FILE_ERROR_WRITEMODE
Write access denied.
COSM_FILE_ERROR_CLOSED
File is closed.

Example

 
  cosm_FILE * file;
  s32 result;

  /* ... */

  result = CosmFileTruncate( file, 10000LL );

  if ( result == COSM_PASS )
    CosmPrint( "File truncated to exactly 10000 bytes in length.\n" );
  else
    CosmPrint( "Could not truncate file.\n" );

CosmFileClose

Syntax

 
#include "cosm/os_file.h"
s32 CosmFileClose( cosm_FILE * file );

Description

Close the file.

Return Values

COSM_PASS on success, or an error code on failure.

Errors

COSM_FILE_ERROR_NOTFOUND
File/Handle not found.
COSM_FILE_ERROR_CLOSED
File is closed.

Example

 
  cosm_FILE * file;

  /* ... */

  CosmFileClose( file );
  CosmProcessEnd( 0 );

CosmFileDelete

Syntax

 
#include "cosm/os_file.h"
s32 CosmFileDelete( const ascii * filename );

Description

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

Return Values

COSM_PASS on success, or an error code on failure.

Errors

COSM_FILE_ERROR_DENIED
Access denied.
COSM_FILE_ERROR_NOTFOUND
File/Handle not found.
COSM_FILE_ERROR_NAME
Invalid file name.

Example

 
  s32 result;

  result = CosmFileDelete( "/tmp/file" );
  if ( result == COSM_PASS )
    CosmPrint( "File /tmp/file was successfully removed.\n" );
  else
  {
    if ( result == COSM_FILE_ERROR_DENIED )
      CosmPrint(
        "Unable to delete /tmp/file: Access denied.\n" );
    else
      CosmPrint(
        "Unable to delete /tmp/file: File doesn't exist.\n" );
  }

CosmFileInfo

Syntax

 
#include "cosm/os_file.h"
s32 CosmFileInfo( cosm_FILE_INFO * info, const ascii * filename );

Description

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

typedef struct cosm_FILE_INFO
{
  u64 length;
  u32 type;
  u32 rights;
  cosmtime create;
  cosmtime modify;
  cosmtime access;
} cosm_FILE_INFO;

Return Values

COSM_PASS on success, or an error code on failure.

Errors

Example

 



    


    
    

      CosmDirOpen
    


    
Syntax



#include "cosm/os_file.h"
s32 CosmDirOpen( cosm_DIR * dir, const ascii * dirname, u32 mode );




    
Description

    

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

    

      Directory Modes:
    

    

      
COSM_DIR_MODE_EXIST
      
Test for directory existence only and return.
      
COSM_DIR_MODE_CREATE
      
Create the directory if it doesn't exist and return.
        Parent directories will be created if needed.

    


    
Return Values

    

      COSM_PASS on success, or an error code on failure.
    


    
Errors

    

      
COSM_DIR_ERROR_DENIED
      
Access denied.
      
COSM_DIR_ERROR_NOTFOUND
      
Directory not found.
      
COSM_DIR_ERROR_CREATE
      
Unable to create new directory.
      
COSM_DIR_ERROR_MODE
      
Open flags conflict.
      
COSM_DIR_ERROR_CLOSED
      
Attempted to reopen an already open directory.
      
COSM_DIR_ERROR_NAME
      
Invalid directory name.
    


    
Example



  cosm_DIR * dir;
  s32 result;

  dir = CosmMemAlloc( sizeof( cosm_DIR ) );

  result = CosmDirOpen( dir, "/var/", COSM_DIR_MODE_READ );
  if ( result == COSM_PASS )
    CosmPrint(
      "Call to CosmDirOpen passed. /var is open.\n" );
  else {
    CosmPrint( "Call to CosmDirOpen failed. Dying.\n" );
    return 1;
  }




    


    
    

      CosmDirRead
    


    
Syntax



#include "cosm/os_file.h"
s32 CosmDirRead( cosm_FILENAME * buffer, u64 * names_read, u64 length,
  cosm_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

    

      COSM_PASS on success, or an error code on failure.
    


    
Errors

    

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

    

      
COSM_DIR_ERROR_NOTFOUND
      
Directory not found.
      
COSM_DIR_ERROR_EOF
      
End of directory.
      
COSM_DIR_ERROR_CLOSED
      
Attempted to reopen an already open directory.
      
COSM_DIR_ERROR_NAME
      
Invalid directory name.
    


    
Example



  cosm_DIR * dir;
  cosm_FILENAME getbuff;
  u64 count;

  /* ... */

  while ( CosmDirRead( &getbuff, &count, (u64) 1, dir ) )
    == COSM_PASS )
  {
    CosmPrint( "File: %.256s\n", getbuff );
  }




    


    
    

      CosmDirDelete
    


    
Syntax



#include "cosm/os_file.h"
s32 CosmDirDelete( const ascii * dirname );




    
Description

    

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


    
Return Values

    

      COSM_PASS on success, or an error code on failure.
    


    
Errors

    

      
COSM_DIR_ERROR_DENIED
      
Access denied.
      
COSM_DIR_ERROR_NOTFOUND
      
Directory not found.
      
COSM_DIR_ERROR_NOTEMPTY
      
Directory is not empty (no delete).
      
COSM_DIR_ERROR_NAME
      
Invalid directory name.
    


    
Example



  s32 result;

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

  if ( result == COSM_PASS )
    CosmPrint( "/tmp/dir was successfully deleted.\n" );
  else
  {
    if ( result == COSM_DIR_ERROR_NOTFOUND )
      CosmPrint( "/tmp/dir doesn't exist.\n" );
    else
      CosmPrint( "/tmp/dir cannot be deleted.\n" );
  }




    


    
    

      CosmDirClose
    


    
Syntax



#include "cosm/os_file.h"
s32 CosmDirClose( cosm_DIR * dir );




    
Description

    

       Close the directory.
    


    
Return Values

    

      COSM_PASS on success, or an error code on failure.
    


    
Errors

    

      
COSM_DIR_ERROR_NOTFOUND
      
Directory not found.
      
COSM_DIR_ERROR_CLOSED
      
Attempted to reopen an already open directory.
    


    
Example



  cosm_DIR * dir;
  s32 result;

  /* ... */

  result = CosmDirClose( dir );

  if ( result == COSM_PASS )
    CosmPrint( "The directory was closed.\n" );
  else
    CosmPrint(
      "The directory was not open or doesn't exist.\n" );




    


    
    

      CosmLoad
    


    
Syntax



#include "cosm/os_file.h"
void CosmU16Load( u16 * num, void * bytes );
void CosmU32Load( u32 * num, void * bytes );
void CosmU64Load( u64 * num, void * bytes );
void CosmU128Load( u128 * num, 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 = CosmMemAlloc( 16LL );

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

  CosmU128Load( &num, bytes );




    


    
    

      CosmSave
    


    
Syntax



#include "cosm/os_file.h"
void CosmU16Save( void * bytes, u16 * num );
void CosmU32Save( void * bytes, u32 * num );
void CosmU64Save( void * bytes, u64 * num );
void CosmU128Save( void * bytes, 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 = CosmMemAlloc( 16LL );

  /* ... */

  CosmU128Save( bytes, &num );

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









  

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

    
    Document last modified: Jun 01, 2012