00001 /*
00002  *      Copyright 1996, University Corporation for Atmospheric Research
00003  *      See netcdf/COPYRIGHT file for copying and redistribution conditions.
00004  */
00005 
00006 #ifndef _NCIO_H_
00007 #define _NCIO_H_
00008 
00009 #include <stddef.h>     /* size_t */
00010 #include <sys/types.h>  /* off_t */
00011 #include "netcdf.h"
00012 
00013 typedef struct ncio ncio;       /* forward reference */
00014 
00015 /*
00016  * A value which is an invalid off_t
00017  */
00018 #define OFF_NONE  ((off_t)(-1))
00019 
00020 /*
00021  * Flags used by the region layer,
00022  *  'rflags' argument to ncio.rel() and ncio.get().
00023  */
00024 #define RGN_NOLOCK      0x1     /* Don't lock region.
00025                                  * Used when contention control handled
00026                                  * elsewhere.
00027                                  */
00028 #define RGN_NOWAIT      0x2     /* return immediate if can't lock, else wait */
00029 
00030 #define RGN_WRITE       0x4     /* we intend to modify, else read only */
00031 
00032 #define RGN_MODIFIED    0x8     /* we did modify, else, discard */
00033 
00034 
00035 /*
00036  * The next four typedefs define the signatures
00037  * of function pointers in struct ncio below.
00038  * They are not used outside of this file and ncio.h,
00039  * They just some casts in the ncio.c more readable.
00040  */
00041         /*
00042          * Indicate that you are done with the region which begins
00043          * at offset. Only reasonable flag value is RGN_MODIFIED.
00044          */
00045 typedef int ncio_relfunc(ncio *const nciop,
00046                  off_t offset, int rflags);
00047 
00048         /*
00049          * Request that the region (offset, extent)
00050          * be made available through *vpp.
00051          */
00052 typedef int ncio_getfunc(ncio *const nciop,
00053                         off_t offset, size_t extent,
00054                         int rflags,
00055                         void **const vpp);
00056 
00057         /*
00058          * Like memmove(), safely move possibly overlapping data.
00059          * Only reasonable flag value is RGN_NOLOCK.
00060          */
00061 typedef int ncio_movefunc(ncio *const nciop, off_t to, off_t from,
00062                         size_t nbytes, int rflags);
00063 
00064         /*
00065          * Write out any dirty buffers to disk and
00066          * ensure that next read will get data from disk.
00067          */
00068 typedef int ncio_syncfunc(ncio *const nciop);
00069 
00070         /*
00071          * Don't call this. 
00072          * Internal function called at close to
00073          * free up anything hanging off pvt;
00074          */
00075 typedef void ncio_freefunc(void *const pvt);
00076 
00077 /* Get around cplusplus "const xxx in class ncio without constructor" error */
00078 #if defined(__cplusplus)
00079 #define NCIO_CONST
00080 #else
00081 #define NCIO_CONST const
00082 #endif
00083 
00084 /*
00085  * netcdf i/o abstraction
00086  */
00087 struct ncio {
00088         /*
00089          * A copy of the ioflags argument passed in to ncio_open()
00090          * or ncio_create().
00091          */
00092         int ioflags;
00093 
00094         /*
00095          * The file descriptor of the netcdf file.
00096          * This gets handed to the user as the netcdf id.
00097          */
00098         NCIO_CONST int fd;
00099 
00100         /* member functions do the work */
00101 
00102         ncio_relfunc *NCIO_CONST rel;
00103 
00104         ncio_getfunc *NCIO_CONST get;
00105 
00106         ncio_movefunc *NCIO_CONST move;
00107 
00108         ncio_syncfunc *NCIO_CONST sync;
00109 
00110         ncio_freefunc *NCIO_CONST free; /* Implementation private */
00111 
00112         /*
00113          * A copy of the 'path' argument passed in to ncio_open()
00114          * or ncio_create(). Used by ncabort() to remove (unlink)
00115          * the file and by error messages.
00116          */
00117         const char *path;
00118 
00119         /* implementation private stuff */
00120         void *NCIO_CONST pvt;
00121 };
00122 
00123 #undef NCIO_CONST
00124 
00125 extern int
00126 ncio_create(const char *path, int ioflags,
00127         size_t initialsz,
00128         off_t igeto, size_t igetsz, size_t *sizehintp,
00129         ncio **nciopp, void **const igetvpp);
00130 
00131 extern int
00132 ncio_open(const char *path,
00133         int ioflags,
00134         off_t igeto, size_t igetsz, size_t *sizehintp,
00135         ncio **nciopp, void **const igetvpp);
00136 
00137 extern int 
00138 ncio_close(ncio *nciop, int doUnlink);
00139 
00140 #endif /* _NCIO_H_ */