home *** CD-ROM | disk | FTP | other *** search
/ PC World Komputer 1998 May / Pcwk5b98.iso / WEBSERVE / PI3 / PI3WEB.EXE / DEVEL / INCLUDE / PIFile.h < prev    next >
C/C++ Source or Header  |  1997-10-19  |  7KB  |  219 lines
  1. /*____________________________________________________________________________*\
  2.  *
  3.  
  4.  Copyright (c) 1997 John Roy. All rights reserved.
  5.  
  6.  These sources, libraries and applications are
  7.  FREE FOR COMMERCIAL AND NON-COMMERCIAL USE
  8.  as long as the following conditions are adhered to.
  9.  
  10.  Redistribution and use in source and binary forms, with or without
  11.  modification, are permitted provided that the following conditions
  12.  are met:
  13.  
  14.  1. Redistributions of source code must retain the above copyright
  15.     notice, this list of conditions and the following disclaimer. 
  16.  
  17.  2. Redistributions in binary form must reproduce the above copyright
  18.     notice, this list of conditions and the following disclaimer in
  19.     the documentation and/or other materials provided with the
  20.     distribution.
  21.  
  22.  3. Redistributions of any form whatsoever and all advertising materials 
  23.     mentioning features must contain the following
  24.     acknowledgment:
  25.     "This product includes software developed by John Roy
  26.     (http://www.johnroy.com/pi3/)."
  27.  
  28.  THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
  29.  WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  30.  OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  31.  IN NO EVENT SHALL THE AUTHORS OR ITS CONTRIBUTORS BE LIABLE FOR ANY
  32.  DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  33.  DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
  34.  GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  35.  HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
  36.  STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  37.  ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
  38.  OF THE POSSIBILITY OF SUCH DAMAGE.
  39.  
  40.  *____________________________________________________________________________*|
  41.  *
  42.  * $Source: PIFile.h$
  43.  * $Date: Sun Aug 10 06:29:37 1997$
  44.  *
  45.  Description:
  46. \*____________________________________________________________________________*/
  47. /* $HeaderTop:$ */
  48.  
  49. #ifndef PIFILE_H_
  50. #define PIFILE_H_
  51.  
  52. #include "PiAPI.h"
  53.  
  54. /*____________________________________________________________________________*\
  55.  *
  56.  Name:
  57.     PIFile_open
  58.  
  59.  Synopsis:
  60.     PIPLATFORM_FD PIFile_open( const char *pPath, const char *pFlags )
  61.  
  62.  Description:
  63.     Open a new platform specific file handle to the file identified
  64.     by the path pPath.
  65.  
  66.  
  67.     The value pFlags is a sequence of characters with the following
  68.     meanings. "W" - open file in write mode overwritting any 
  69.     previous file with the same path. "A" - open the file in write
  70.     mode appending to any file with the same path. "R" can be
  71.     specified for opening a file for reading. "N" indicates that the
  72.     file should not be opened if it already exists (must not alreadu exist).
  73.     In all cases
  74.     With the exception of when the "N" flag is present, 
  75.     a new file will be created if the it did not exist.
  76.     <P>
  77.     Flags are not case sensitive.
  78.  
  79.  Notes:
  80.     PIPLATFORM_FD, is an operating system specific handle or descriptor,
  81.     other operations may be performed on this object by casting this 
  82.     value to the type associated with operating system specific descriptors
  83.     and using system calls.
  84.  
  85.     PIFile_* functions are primarily intented for creating and appended
  86.     file optimally with synchronization amoungst write operations from
  87.     multiple threads and processes, however they may also be used for
  88.     simple unbuffering readonly access to existing files.
  89.  
  90.     The function PIFile_close() should be used to close a file handle when
  91.     it is no longer needed. File handles should be considered an
  92.     easily exhaustable resource, and omitting to match successful
  93.     PIFile_open() calls with calls to PIFile_close() is a serious
  94.     resource leak.
  95.  
  96.  Return Values:
  97.     The values returned from PIFile_open should be compared with
  98.     the PIPLATFORM_FD_INVALID to determine if an error occurred, i.e.
  99.  
  100. <CODE><PRE>
  101.         PIPLATFORM_FD tFD;
  102.         if ((tFD = PIFile_open( "/tmp/dummy.txt", "w" ))==PIPLATFORM_FD_INVALID)
  103.             {
  104.             /.* --- handle error --- *./
  105.             int iErrorCode = PiPlatform_getLastError();
  106.  
  107.             ...
  108.  
  109.             }
  110.         else
  111.             {
  112.             /.* --- tFD is a valid file handle --- *./
  113.  
  114.             ...
  115.  
  116.             PIFile_close( tFD );
  117.             };
  118. </PRE></CODE>
  119.  
  120.  Errors:
  121.     More specific error information can be retrieved using
  122.     PIPlatform_getLastError().
  123.         
  124.  See Also:
  125.     PIFile_close().
  126. \*____________________________________________________________________________*/
  127. PUBLIC_PIAPI int PIFile_open( const char *pPath, const char *pFlags );
  128.  
  129. /*____________________________________________________________________________*\
  130.  *
  131.  Name:
  132.     PIFile_close
  133.  
  134.  Synopsis:
  135.     int PIFile_close( PIPLATFORM_FD tFD )
  136.  
  137.  Description:
  138.     Closes a platform specific file descriptor opened by PIFile_open().
  139.  
  140.  Notes:
  141.  Return Values:
  142.     On success PIFile_delete() returns zero (PIAPI_COMPLETED).
  143.  
  144.  Errors:
  145.     On error PIFile_close() does not return PIAPI_COMPLETED. The function
  146.     PIPlatform_getLastError() can be used to retrieve more specific
  147.     error information.
  148.  
  149.  See Also:
  150.     PIFile_open().
  151. \*____________________________________________________________________________*/
  152. PUBLIC_PIAPI int PIFile_close( PIPLATFORM_FD tFD );
  153.  
  154. /*____________________________________________________________________________*\
  155.  *
  156.  Name:
  157.     PIFile_write
  158.  
  159.  Synopsis:
  160.     int PIFile_write( PIPLATFORM_FD tFD, int iLength, const void *pData )
  161.  
  162.  Description:
  163.     Write the data block if Length bytes to the file referenced by
  164.     the descriptor tFD.
  165.     
  166.  Notes:
  167.     The function PIPlatform_PollFD() may to used yield processing to
  168.     another thread if the write operation would block.
  169.  
  170.  Return Values:
  171.     On success PIFile_write() returns zero (PIAPI_COMPLETED).
  172.  
  173.  Errors:
  174.     On error, the function PIPlatform_getLastError() can be used to get 
  175.     more specific error information.
  176.         
  177.  See Also:
  178.     PIFile_writeAtomic()
  179. \*____________________________________________________________________________*/
  180. PUBLIC_PIAPI int PIFile_write( PIPLATFORM_FD tFD, int iLength, const 
  181.     void *pData );
  182.  
  183. /*____________________________________________________________________________*\
  184.  *
  185.  Name:
  186.     PIFile_writeAtomic
  187.  
  188.  Synopsis:
  189.     int PIFile_writeAtomic( PIPLATFORM_FD tFD, int iLength, const void *pData )
  190.  
  191.  Description:
  192.     Write the data block if Length bytes to the file referenced by
  193.     the descriptor tFD. The write operation is atomic, meaning that 
  194.     descriptor will be locked using a platform specific method to ensure
  195.     the block of a data is written correctly in an environment where
  196.     multiple processes and threads are competing to write to the file. 
  197.     
  198.  Notes:
  199.     This function will only gaurentee synchronized writes amoungst
  200.     processes on POSIX compliant platforms. On other platforms only
  201.     thread synchronization is performed.
  202.  
  203.  
  204.  Return Values:
  205.     On success PIFile_writeAtomic() returns zero (PIAPI_COMPLETED).
  206.  
  207.  Errors:
  208.     On error, the function PIPlatform_getLastError() can be used to get 
  209.     more specific error information.
  210.         
  211.  See Also:
  212.     PIFile_write()
  213. \*____________________________________________________________________________*/
  214. PUBLIC_PIAPI int PIFile_writeAtomic( PIPLATFORM_FD tFD, int iLength, const 
  215.     void *pData );
  216.  
  217. #endif /* PIFILE_H_ */
  218.  
  219.