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;
}
