home *** CD-ROM | disk | FTP | other *** search
/ Oracle Video Server 3.0.3.1 / OVS_3031_NT.iso / win32 / medianet / server / include / sysfp.h < prev    next >
Encoding:
C/C++ Source or Header  |  1998-03-12  |  12.2 KB  |  358 lines
  1. /* Copyright (c) 1995 by Oracle Corporation.  All Rights Reserved.
  2.  *
  3.  * sysfp.h - Oracle MOOSE Host File System I/O
  4.  *
  5.  * NOTE: In a threaded environment, this interface will be thread-safe
  6.  * and well-behaved (non-blocking to the process) if possible.
  7.  */
  8.  
  9. #ifndef SYSFP_ORACLE
  10. #define SYSFP_ORACLE
  11.  
  12. #ifndef ORALIMITS
  13. #include <limits.h>
  14. #define ORALIMITS
  15. #endif
  16. #ifndef ORASTDIO
  17. #include <stdio.h>
  18. #define ORASTDIO
  19. #endif
  20. #ifndef SYSX_ORACLE
  21. #include <sysx.h>
  22. #endif
  23. #ifndef YS_ORACLE
  24. #include <ys.h>
  25. #endif
  26.  
  27. /*
  28.  * sysfp - file handle
  29.  */
  30. typedef struct sysfp sysfp;
  31.  
  32. /*
  33.  * sysfpOpen - open a file
  34.  *
  35.  * DESCRIPTION
  36.  * sysfpOpen() opens file fn and associates a stream with it.  If the open
  37.  * succeeds, the routine returns a pointer to be used to identify this
  38.  * stream.  type is a character string having one of the values defined for
  39.  * the ANSI fopen() operation.  kind describes the kind of the file, and may
  40.  * be used by the routine as supplementary to determine how to open the file.
  41.  * Acceptable values for kind are
  42.  *
  43.  *   SYSFPKIND_BINARY - binary data file
  44.  *   SYSFPKIND_TEXT - text file
  45.  *
  46.  * All other values (possibly null) will be treated as SYSFPKIND_BINARY.
  47.  *
  48.  * If an error occurs, a null pointer is returned, and system-specific
  49.  * error text is returned.
  50.  */
  51. sysfp *sysfpOpen(CONST char *fn, CONST char *type, CONST char *kind,
  52.          CONST char **errtxt);
  53.  
  54. /*
  55.  * sysfpClose - close a file
  56.  *
  57.  * DESCRIPTION
  58.  * sysfpClose() closes a file stream previously opened with sysfpOpen().
  59.  */
  60. void   sysfpClose(sysfp *fp);
  61.  
  62. /*
  63.  * sysfpEof - returns true if at eof
  64.  *
  65.  * DESCRIPTION
  66.  * sysfpEof() returns true if EOF has been detected on this stream;
  67.  * false otherwise.
  68.  */
  69. boolean sysfpEof(sysfp *fp);
  70.  
  71. /*
  72.  * sysfpSeek, sysfpTell - random file access
  73.  *
  74.  * DESCRIPTION
  75.  * sysfpSeek() seeks to a byte offset position in the file.  The offset
  76.  * is expressed in bytes measured from the beginning of the file.  Note
  77.  * that on text files especially, arithmetic on offsets may not always
  78.  * be meaningful.  If the offset specifies a position past the end of
  79.  * the file, the results are unpredictable (e.g. the file may be extended,
  80.  * an error may be reported, etc.).  sysfpSeek() returns TRUE if the seek
  81.  * succeeded; FALSE otherwise.
  82.  *
  83.  * sysfpTell() reports the current byte offset in the file.  The result
  84.  * is written to offset.  Note that values returned from sysfpTell() are
  85.  * the only ones that may absolutely reliably be passed to sysfpSeek().
  86.  */
  87. boolean sysfpSeek(sysfp *fp, CONST sysb8 *offset);
  88. void sysfpTell(sysfp *fp, sysb8 *offset);
  89.  
  90. /*
  91.  * sysfpRead, sysfpWrite - file input & output
  92.  *
  93.  * DESCRIPTION
  94.  * sysfpRead() reads at most len bytes from the file stream fp into the
  95.  * buffer buf.  The number of bytes actually read is returned.  It may be
  96.  * less than len (possibly zero) if there is no more data in the file
  97.  * (or the file is not opened for reading).
  98.  *
  99.  * sysfpWrite() writes the buffer buf of len bytes to the file stream fp.
  100.  * The number of bytes actually written is returned.  It may be less than
  101.  * len if an error occurred during writing.
  102.  */
  103. size_t sysfpRead(sysfp *fp, dvoid *buf, size_t len);
  104. size_t sysfpWrite(sysfp *fp, dvoid *buf, size_t len);
  105.  
  106. /*
  107.  * sysfpFlush - flush output
  108.  *
  109.  * DESCRIPTION
  110.  * sysfpFlush() flushes buffered output without closing the stream.
  111.  * It returns TRUE on success; FALSE otherwise.
  112.  */
  113. boolean sysfpFlush(sysfp *fp);
  114.  
  115. /*
  116.  * sysfpPrint - print to file
  117.  *
  118.  * DESCRIPTION
  119.  * sysfpPrint() writes to the open file designated by fp.  The fmt and
  120.  * subsequent arguments are interpreted as for printf().  The file must
  121.  * have been opened with appropriate access.  If there is an error,
  122.  * sysfpPrint() returns FALSE.
  123.  */
  124. boolean sysfpPrint(sysfp *fp, CONST char *fmt, ...);
  125.  
  126. /*
  127.  * sysfpGets - get a line
  128.  *
  129.  * SYNOPSIS
  130.  * char *sysfpGets(sysfp *fp, char *buf, size_t maximum);
  131.  *
  132.  * DESCRIPTION
  133.  * sysfpGets() reads characters from the open file designated by fp into
  134.  * the array pointed to by buf, until maximum-1 characters are read, or
  135.  * a newline character is read and transferred to s, or an end-of-file
  136.  * condition is encountered.  The string is then terminated with a null
  137.  * character.  If an end-of-file is encountered and no characters have
  138.  * been read, a null pointer is returned; otherwise, buf is returned.
  139.  */
  140. #define sysfpGets(fp, b, m)  fgets((b), (m), (FILE *) (fp))
  141.  
  142. /*
  143.  * sysfpGetc - get a character
  144.  *
  145.  * SYNOPSIS
  146.  * boolean sysfpGetc(sysfp *fp, sword *ch);
  147.  *
  148.  * DESCRIPTION
  149.  * sysfpGetc() gets a character from the open file designated by fp.  If
  150.  * the end of the file is reached, sysfpGetc() returns TRUE; otherwise,
  151.  * *ch is set to the character that was read and the routine returns FALSE.
  152.  */
  153. #define sysfpGetc(fp, ch) ((*ch) = (sword) getc((FILE *) (fp)), (*ch) == EOF)
  154.  
  155. /*
  156.  * sysfpAccess - tests for access to a file
  157.  *
  158.  * DESCRIPTION
  159.  * sysfpAccess() tests the filename to see if it can be opened with the
  160.  * access specified in type.  type is a character string taking on the
  161.  * same set of values as for sysfpOpen().
  162.  */
  163. boolean sysfpAccess(CONST char *fn, CONST char *type);
  164.  
  165. /*
  166.  * sysfpIsDir - tests for a directory
  167.  *
  168.  * DESCRIPTION
  169.  * sysfpIsDir() tests the filename to see if it denotes a directory
  170.  * and returns TRUE if it does; FALSE otherwise.  (FALSE may indicate
  171.  * an access error).
  172.  */
  173. boolean sysfpIsDir(CONST char *fn);
  174.  
  175. /*
  176.  * sysfpGetDir - get directory 
  177.  *
  178.  * DESCRIPTION
  179.  * sysfpGetDir() retrieves the contents of a directory.  fn must be the
  180.  * name of a directory suitable for reading.  sysfpGetDir() should return
  181.  * a list where each element in the list is an allocated string containing
  182.  * the name of a file in the directory (that is, the element vaue should be
  183.  * castable to char *).  The list may be freed by the caller using
  184.  *
  185.  *    ysLstDestroy(lst, ysmFGlbFree);
  186.  *
  187.  * If there is an error (or the routine is not implemented on the platform),
  188.  * a null pointer is returned.  Errors include invalid filenames, access
  189.  * violations, and memory exhaustion.
  190.  */
  191. yslst *sysfpGetDir(CONST char *fn);
  192.  
  193.  
  194. /*
  195.  * sysfpSize - return the length of a file
  196.  *
  197.  * DESCRIPTION
  198.  * fn is the name of a file whose length in bytes is determined.  If
  199.  * no error occurs, sysfpSize() writes the result to sz and returns
  200.  * null.  Otherwise, a pointer to error text explaining the error is
  201.  * returned.
  202.  */
  203. CONST char *sysfpSize(CONST char *fn, sysb8 *sz);
  204.  
  205. /*
  206.  * sysfpLast - return last modification time of a file
  207.  *
  208.  * DESCRIPTION
  209.  * fn is the name of a file whose last modification time is to be determined.
  210.  * If no error occurs, sysfpLast() writes the result to mtime and returns
  211.  * null.  Otherwise, a pointer to error text explaining the error is returned.
  212.  * The modification time value is seconds since the epoch, the same epoch as
  213.  * used by systmGetClock().
  214.  */
  215. CONST char *sysfpLast(CONST char *fn, sysb8 *mtime);
  216.  
  217. /*
  218.  * sysfpRemove - remove a file
  219.  *
  220.  * DESCRIPTION
  221.  * sysfpRemove() removes a file named by fn.  On success, null is returned.
  222.  * Otherwise, a system-specific error message is returned.
  223.  */
  224. CONST char *sysfpRemove(CONST char *fn);
  225.  
  226. /*
  227.  * sysfpRename - rename a file
  228.  *
  229.  * DESCRIPTION
  230.  * sysfpRename() renames a file named by from to a file named by to.  On
  231.  * success, null is returned.  Otherwise, a system-specific error message
  232.  * is returned.  The system should attempt to ensure that if the rename
  233.  * fails, the original file remains intact under the original name.
  234.  */
  235. CONST char *sysfpRename(CONST char *from, CONST char *to);
  236.  
  237. /*
  238.  * sysfpForm - construct a filename
  239.  *
  240.  * DESCRIPTION
  241.  * sysfpForm() constructs a full filename (including path and suffix) from
  242.  * its constituent parts and writes the full name to result, a buffer which
  243.  * must be a minimum of SYSFP_MAX_PATHLEN bytes long.
  244.  *
  245.  * The filename is constructed as follows:
  246.  *   + if sfx is non-null, it is appended to the base (but only if the
  247.  *     basename does not already have a suffix present);
  248.  *   + if path is null or base is an absolute pathname (e.g. begins with
  249.  *     a "/" in Unix), path is ignored; otherwise, path is prepended to
  250.  *     the base
  251.  *
  252.  * The result is a single filename that fully denotes the path, the filename,
  253.  * and the suffix as appropriate for the host file system.  This result is
  254.  * written to result.
  255.  */
  256. #define SYSFP_MAX_PATHLEN     MAX_PATH
  257.  
  258. void sysfpForm(char *result, CONST char *path, CONST char *base,
  259.            CONST char *sfx);
  260.  
  261. /*
  262.  * sysfpExtractPath, sysfpExtractFile, sysfpExtractBase, sysfpExtractSuffix
  263.  *   - extract components
  264.  *
  265.  * DESCRIPTION
  266.  * sysfpExtractPath() extracts a pathname from a full filename and writes
  267.  * it to path.  path must be a minimum of SYSFP_MAX_PATHLEN bytes long.  If
  268.  * the filename does not contain any path information, a path that denotes
  269.  * the current directory is returned.
  270.  *
  271.  * sysfpExtractFile() extracts the base filename from a full filename.  This
  272.  * is the filename with the path stripped.  It is like sysfpExtractBase()
  273.  * except that it will not strip a suffix.
  274.  *
  275.  * sysfpExtractBase() extracts the basename from a full filename, stripping
  276.  * both a path (if any) and suffix (if any).
  277.  *
  278.  * sysfpExtractSuffix() extracts the suffix from a full filename, stripping
  279.  * both a path (if any) and basename.  If there is no suffix, a zero-length
  280.  * string is returned.
  281.  */
  282. void sysfpExtractPath(char *path, CONST char *fn);
  283. void sysfpExtractFile(char *file, CONST char *fn);
  284. void sysfpExtractBase(char *base, CONST char *fn);
  285. void sysfpExtractSuffix(char *sfx, CONST char *fn);
  286.  
  287.  
  288. /*
  289.  * sysfpTemp - construct a temporary filename
  290.  *
  291.  * DESCRIPTION
  292.  * sysfpTemp() constructs a temporary filename (including path and suffix).
  293.  * The platform will use any trick necessary to ensure that the name generated
  294.  * is relatively unique (this means that if you call this routine 50000 times,
  295.  * it may generate some duplicates, but not after 100 times, certainly.)
  296.  * The resulting name is written to result, a buffer which must be a minimum
  297.  * of SYSFP_MAX_PATHLEN bytes long.
  298.  *
  299.  * If path is not null, it is used as a the pathname where the file should
  300.  * be located.  If kind is a recognized kind of file, it will endeavor to
  301.  * do anything necessary when constructing the filename to meet the
  302.  * requirements implied by that kind.
  303.  */
  304. void sysfpTemp(char *result, CONST char *path, CONST char *sfx);
  305.  
  306. /*
  307.  * sysfpGetCwd - get current working directory
  308.  *
  309.  * DESCRIPTION
  310.  * sysfpGetCwd() gets the current working directory and writes it to result,
  311.  * a buffer which must be a minimum of SYSFP_MAX_PATHLEN bytes long.  On 
  312.  * success, null is returned.  Otherwise, a system-specific error message is
  313.  * returned and result is not changed.
  314.  */
  315. CONST char *sysfpGetCwd(char *result);
  316.  
  317. /*
  318.  * sysfpExtractPath, sysfpExtractFile, sysfpExtractBase, sysfpExtractKind
  319.  *   - extract components
  320.  *
  321.  * DESCRIPTION
  322.  * sysfpExtractPath() extracts a pathname from a full filename and writes
  323.  * it to path.  path must be a minimum of SYSFP_MAX_PATHLEN bytes long.  If
  324.  * the filename does not contain any path information, a path that denotes
  325.  * the current directory is returned.
  326.  *
  327.  * sysfpExtractFile() extracts the base filename from a full filename.  This
  328.  * is the filename with the path stripped.  It is like sysfpExtractBase()
  329.  * except that it will not strip a suffix.
  330.  *
  331.  * sysfpExtractBase() extracts the basename from a full filename, stripping
  332.  * both a path (if any) and suffix (if any).
  333.  *
  334.  * sysfpExtractKind() extracts the kind from a full filename, returning
  335.  * one of the SYSFPKIND values listed above, depending on the suffix and
  336.  * the name of the file.
  337.  */
  338. void   sysfpExtractPath(char *path, CONST char *fn);
  339. void   sysfpExtractFile(char *file, CONST char *fn);
  340. void   sysfpExtractBase(char *base, CONST char *fn);
  341. sword  sysfpExtractKind(CONST char *fn);
  342.  
  343. /*
  344.  * Kind Definitions
  345.  */
  346. #define SYSFPKIND_BINARY      (char *) 0
  347. externref CONST_DATA char SYSFPKIND_TEXT[];
  348.  
  349. /*
  350.  * The following kinds are obsolete.
  351.  */
  352. #define SYSFPKIND_NONE        (char *) 0
  353. #define SYSFPKIND_OTHER       (char *) 0
  354. #define SYSFPKIND_CHEADER     "h"
  355. #define SYSFPKIND_CSOURCE     "c"
  356.  
  357. #endif /* SYSFP_ORACLE */
  358.