src/usd/usd.h

   1 /*
   2  * Copyright 2000, International Business Machines Corporation and others.
   3  * All Rights Reserved.
   4  *
   5  * This software has been released under the terms of the IBM Public
   6  * License.  For details, see the LICENSE file in the top-level source
   7  * directory or online at http://www.openafs.org/dl/license10.html
   8  */
   9
  10 #ifndef TRANSARC_USD_H
  11 #define TRANSARC_USD_H
  12
  13 /* Define I/O functions that operate on both device and regular files.
  14  *
  15  * Essentially, this is a mechanism for dealing with systems (such as NT)
  16  * that do not allow devices to be accessed via POSIX-equivalent
  17  * open()/read()/write()/close() functions.
  18  */
  19
  20 /* The Unix common code is implemented by usd/usd_file.c and the WinNT
  21  * code is in usd/usd_nt.c. */
  22
  23 /* The device handle "usd_handle_t" is returned by the function usd_Open.
  24  * This object includes function pointers for all the other operations,
  25  * which are accessed by macros, e.g. USD_READ(usd_handle_t, ...).  In
  26  * general, this handle is entirely opaque to outside callers.
  27  *
  28  * Because of WinNT restrictions on dealing with devices, it is not possible
  29  * to lock devices independently from opening them.  A flag bit is specified
  30  * at open time requesting a read (shared) or write (exclusive) lock or
  31  * neither.  The device remains locked until the handle is closed.
  32  *
  33  * An application can not open a device multiple times.  This is because on
  34  * WinNT the holder of the lock is the handle not the process as on Unix.
  35  *
  36  * All the "usd_" function return an error status as an "(int)" converted
  37  * into the errno domain, with zero meaning no error.
  38  *
  39  * As a consequence of this method of reporting errors, output values are
  40  * returned in reference parameters instead of being encoded in the return
  41  * value.  Also, offsets and lengths use the afs_hyper_t type. */
  42
  43 /* NOTE -- this module is preempt safe.  It assume it is being called from a
  44  *     preemptive environment.  Treat all calls as if they had an "_r"
  45  *     suffix. */
  46
  47 typedef struct usd_handle * usd_handle_t;
  48
  49 struct usd_handle {
  50     int (*read)(usd_handle_t usd, char *buf, afs_uint32 nbyte, afs_uint32 *xferdP);
  51     int (*write)(usd_handle_t usd, char *buf, afs_uint32 nbyte, afs_uint32 *xferdP);
  52     int (*seek)(usd_handle_t usd,
  53                 afs_hyper_t inOff, int whence, afs_hyper_t *outOffP);
  54     int (*ioctl)(usd_handle_t usd, int req, void *arg);
  55     int (*close)(usd_handle_t usd);
  56
  57     /* private members */
  58     void *handle;
  59     char *fullPathName;
  60     int openFlags;
  61     void *privateData;
  62 };
  63
  64 #define USD_READ(usd, buf, nbyte, xferP) \
  65     ((*(usd)->read)(usd, buf, nbyte, xferP))
  66 #define USD_WRITE(usd, buf, nbyte, xferP) \
  67     ((*(usd)->write)(usd, buf, nbyte, xferP))
  68 #define USD_SEEK(usd, inOff, w, outOff) ((*(usd)->seek)(usd, inOff, w, outOff))
  69
  70 /* USD_IOCTL -- performs various query and control operations.
  71  *
  72  * PARAMETERS --
  73  *     req -- is one of the constants, defined below, starting with
  74  *         USD_IOCTL_... which specify the desired operation.
  75  *     arg -- is a (void *) pointer whose purpose depends on "req". */
  76
  77 #define USD_IOCTL(usd, req, arg) ((*(usd)->ioctl)(usd, req, arg))
  78
  79 /* USD_CLOSE -- closes and deallocates the specified device handle.
  80  *
  81  * CAUTIONS -- The handle is deallocated *even if an error occurs*. */
  82
  83 #define USD_CLOSE(usd) ((*(usd)->close)(usd))
  84
  85 extern int usd_Open(const char *path, int oflag, int mode, usd_handle_t *usdP);
  86 extern int usd_StandardInput(usd_handle_t *usdP);
  87 extern int usd_StandardOutput(usd_handle_t *usdP);
  88
  89 /* Open flag bits */
  90
  91 #define USD_OPEN_RDONLY         0       /* read only */
  92 #define USD_OPEN_RDWR           1       /* writable */
  93 #define USD_OPEN_SYNC           2       /* do I/O synchronously to disk */
  94 #define USD_OPEN_RLOCK          4       /* obtain a read lock on device */
  95 #define USD_OPEN_WLOCK          8       /* obtain a write lock on device */
  96 #define USD_OPEN_CREATE      0x10       /* create file if doesn't exist */
  97
  98 /* I/O Control requests */
  99
 100 /* GetType(int *arg) -- returns an integer like the st_mode field masked with
 101  *     S_IFMT.  It can be decoded using the S_ISxxx macros. */
 102
 103 #define USD_IOCTL_GETTYPE       1
 104
 105 /* GetFullName(char *arg) -- returns a pointer to the fully qualified pathname
 106  *     to the opened device.  This string is stored with the open handle and
 107  *     can be used as long as the handle is open.  If the string is required
 108  *     longer, the string must be copied before the handle is closed. */
 109
 110 #define USD_IOCTL_GETFULLNAME   2
 111
 112 /* GetDev(dev_t *arg) -- returns a dev_t representing the device number of open
 113  *     device.  If the handle does not represent a device the return value is
 114  *     ENODEV. */
 115
 116 #define USD_IOCTL_GETDEV        3
 117
 118 /* GetSize(afs_hyper_t *sizeP) -- returns the size of the file.  Doesn't work
 119  *     on BLK or CHR devices. */
 120
 121 #define USD_IOCTL_GETSIZE       6
 122
 123 /* SetSize(afs_hyper_t *sizeP) -- sets the size of the file.  Doesn't work
 124  *     on BLK or CHR devices. */
 125
 126 #define USD_IOCTL_SETSIZE       7
 127
 128 /* TapeOperation(usd_tapeop_t *tapeOpp) -- perform tape operation specified
 129  *     in tapeOpp->tp_op.
 130  */
 131
 132 #define USD_IOCTL_TAPEOPERATION 8
 133
 134 /* GetBlkSize(long *sizeP) -- returns blocksize used by filesystem for a file.
 135  *     Doesn't work on BLK or CHR devices. */
 136
 137 #define USD_IOCTL_GETBLKSIZE    9
 138
 139 typedef struct {
 140     int  tp_op;       /* tape operation */
 141     int  tp_count;    /* tape operation count argument */
 142 } usd_tapeop_t;
 143
 144 #define USDTAPE_WEOF     0  /* write specified number of tape marks */
 145 #define USDTAPE_REW      1  /* rewind tape */
 146 #define USDTAPE_FSF      2  /* forward-space specified number of tape marks */
 147 #define USDTAPE_BSF      3  /* back-space specified number of tape marks*/
 148 #define USDTAPE_PREPARE  4  /* ready tape drive for operation */
 149 #define USDTAPE_SHUTDOWN 5  /* decommission tape drive after operation */
 150
 151 #endif /* TRANSARC_USD_H */