cvs commit: apache-apr/docs fileio.txt

[rb...@hyperreal.org]

rbb         99/02/22 04:59:18

  Added:       docs     fileio.txt
  Log:
  I am breaking the spec into smaller files.  This makes them a bit more
  manageable, and lets me think I am getting somewhere in this project.
  This file begins to detail the fileio functions.  It will eventually give
  all the prototypes, as well as enough information to document to function.
  Currently, only apr_open is done.
  
  Revision  Changes    Path
  1.1                  apache-apr/docs/fileio.txt
  
  Index: fileio.txt
  ===================================================================
  <h2>File I/O</h2>
  
   APRFile *apr_open(char *, APRUInt32, APRFilePerms)
  	Open the specified file, and return a method for accessing that file.
       Arguments:
  	arg 1)  full path name to the file to be opened.
  	arg 2)  Note: this may become its own type with accessor methods
                  flags that determine how to open or create the file.  
  	        Or'ed value of:
  			APR_READ         Open for reading
  			APR_WRITE        Open for writing
  			APR_CREATE       Create the file if not there
  			APR_APPEND	The file ptr is set to end prior to 
  					write
  			APR_TRUNCATE	If the file is there, length is 
  					truncated to 0.
  			APR_BINARY      Not a text file.
  			APR_BUFFERED    buffer the data.
  			APR_EXCL        return error if APR_CREATE and file
  					exists.
  			APR_NONBLOCK    don't block on read or write.
  	arg 3)  Access permissions to set for the file if it is created with
  		APR_CREATE. We haven't decided how exactly we want this to
                  work, but it will support the set of Unix permissions at
                  minimum.
          return) The abstracted file descriptor for the file that was opened.  
  	        NULL on error
  
  Notes:  The values assigned when the file is opened is not kept current.  It is
          not garaunteed to be accurate after the file is opened.  It is intended
          for use in situations where the latency between opening and use a file
          is small, and a stat isn't required after opening the file. 
  
  
  APRStatus apr_close(APRFile);
  	Close the specified file descriptor
       Arguments:
  	arg 1)  file descriptor of file to be closed.
   APRStatus apr_read(APRFile, void *, APRUInt64, APRUInt64 *)
  	Read n bytes from file and store in buffer.
       Arguments:
  	arg 1)  File descriptor to read from
  	arg 2)  buffer to store data in
  	arg 3)  number of bytes to read
  	arg 4)  pointer to number of bytes read. (returned by APR)
   APRStatus apr_write(APRFile, void *, APRUInt64, APRUInt64 *)
  	Write n bytes of data from buffer to file
       Arguments:
  	arg 1)  File descriptor to write data to
  	arg 2)  buffer to read data from
  	arg 3)  number of bytes to write
  	arg 4)  pointer to number of bytes written. (returned by APR)
   APRStatus apr_writev(APRFile, APRIOVec *, APRUInt64, APUInt64 *)
  	Same as apr_write, except it gets the data from the APRIOVec array.
       Arguments:
  	arg 1)  File descriptor to write data to
  	arg 2)  Array from which to get the data to write to the file
  	arg 3)  Number of elements in the APRIOVec array.  Must be smaller
  		than apr_MAX_IOVEC_SIZE, if not function will fail with
  		apr_BUFFER_OVERFLOW_ERROR
  	arg 4) number of bytes written.  APR_FAILURE on failure.
       NOTES: apr_writev will write a complete entry from APRIOVec array before
  	    moving on to the next one.
   APRStatus apr_getfileinfo(char *, APRFileInfo *)  
  	Get information about the file with the given path name.
       Arguments:
  	arg 1)  path to file to get information about
  	arg 2)  Structure to store file's information in. (Returned by APR)
   APRStatus apr_seek(APRFile, APRInt64, APRSeekWhere, APRInt64 *)
  	Moves the read/write file offset pointer
       Arguments:
  	arg 1)  Pointer to File descriptor  
  	arg 2)  offset into file to move pointer to
  	arg 3)	How to move the pointer.  See APRSeekWhere def below.
  	arg 4)  Offset into file that the pointer was set to. (Returned by
                  APR)
   APRStatus apr_access(char *, APRFilePerms)
  	Determine the Accessibility of a file
       Arguments:
  	arg 1)  path to file 
  	arg 3)  Which access permissions to check for.
   APRStatus apr_opendir(char *, APRDir *)  
  	Opens the specified directory stream.		
       Arguments:
  	arg 1)  path of the directory to be opened.
  	arg 2) abstracted directory descriptor structure.
   APRStatus apr_closedir(APRDir *)  
  	Opens the specified directory stream.		
       Arguments:
  	arg 1) abstracted directory descriptor structure to be closed.
   APRStatus apr_readdir(APRDir *, APRDirent *)
  	Retrieve the next directory entry from the specified directory.
       Arguments:
  	arg 1) Abstracted directory descriptor to read from.
  	arg 2) the next directory entry.
  
  
  **************** IMPLEMENTATION DETAILS **************
  
  struct APRFile {
      int filedes;
      char * fname;
      int buffered;
      mode_t protection;
      uid_t user;
      gid_t group;
      off_t size;
      time_t atime;    
      time_t mtime;
      time_t ctime;
  }