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 OPENAFS_USD_H
  11 #define OPENAFS_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_int64 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,
  51                  afs_uint32 * xferdP);
  52     int (*write) (usd_handle_t usd, char *buf, afs_uint32 nbyte,
  53                   afs_uint32 * xferdP);
  54     int (*seek) (usd_handle_t usd, afs_int64 inOff, int whence,
  55                  afs_int64 * outOffP);
  56     int (*ioctl) (usd_handle_t usd, int req, void *arg);
  57     int (*close) (usd_handle_t usd);
  58
  59     /* private members */
  60     void *handle;
  61     char *fullPathName;
  62     int openFlags;
  63     void *privateData;
  64 };
  65
  66 #define USD_READ(usd, buf, nbyte, xferP) \
  67     ((*(usd)->read)(usd, buf, nbyte, xferP))
  68 #define USD_WRITE(usd, buf, nbyte, xferP) \
  69     ((*(usd)->write)(usd, buf, nbyte, xferP))
  70 #define USD_SEEK(usd, inOff, w, outOff) ((*(usd)->seek)(usd, inOff, w, outOff))
  71
  72 /* USD_IOCTL -- performs various query and control operations.
  73  *
  74  * PARAMETERS --
  75  *     req -- is one of the constants, defined below, starting with
  76  *         USD_IOCTL_... which specify the desired operation.
  77  *     arg -- is a (void *) pointer whose purpose depends on "req". */
  78
  79 #define USD_IOCTL(usd, req, arg) ((*(usd)->ioctl)(usd, req, arg))
  80
  81 /* USD_CLOSE -- closes and deallocates the specified device handle.
  82  *
  83  * CAUTIONS -- The handle is deallocated *even if an error occurs*. */
  84
  85 #define USD_CLOSE(usd) ((*(usd)->close)(usd))
  86
  87 extern int usd_Open(const char *path, int oflag, int mode,
  88                     usd_handle_t * usdP);
  89 extern int usd_StandardInput(usd_handle_t * usdP);
  90 extern int usd_StandardOutput(usd_handle_t * usdP);
  91
  92 /* Open flag bits */
  93
  94 #define USD_OPEN_RDONLY         0       /* read only */
  95 #define USD_OPEN_RDWR           1       /* writable */
  96 #define USD_OPEN_SYNC           2       /* do I/O synchronously to disk */
  97 #define USD_OPEN_RLOCK          4       /* obtain a read lock on device */
  98 #define USD_OPEN_WLOCK          8       /* obtain a write lock on device */
  99 #define USD_OPEN_CREATE      0x10       /* create file if doesn't exist */
 100
 101 /* I/O Control requests */
 102
 103 /* GetType(int *arg) -- returns an integer like the st_mode field masked with
 104  *     S_IFMT.  It can be decoded using the S_ISxxx macros. */
 105
 106 #define USD_IOCTL_GETTYPE       1
 107
 108 /* GetFullName(char *arg) -- returns a pointer to the fully qualified pathname
 109  *     to the opened device.  This string is stored with the open handle and
 110  *     can be used as long as the handle is open.  If the string is required
 111  *     longer, the string must be copied before the handle is closed. */
 112
 113 #define USD_IOCTL_GETFULLNAME   2
 114
 115 /* GetDev(dev_t *arg) -- returns a dev_t representing the device number of open
 116  *     device.  If the handle does not represent a device the return value is
 117  *     ENODEV. */
 118
 119 #define USD_IOCTL_GETDEV        3
 120
 121 /* GetSize(afs_int64 *sizeP) -- returns the size of the file.  Doesn't work
 122  *     on BLK or CHR devices. */
 123
 124 #define USD_IOCTL_GETSIZE       6
 125
 126 /* SetSize(afs_int64 *sizeP) -- sets the size of the file.  Doesn't work
 127  *     on BLK or CHR devices. */
 128
 129 #define USD_IOCTL_SETSIZE       7
 130
 131 /* TapeOperation(usd_tapeop_t *tapeOpp) -- perform tape operation specified
 132  *     in tapeOpp->tp_op.
 133  */
 134
 135 #define USD_IOCTL_TAPEOPERATION 8
 136
 137 /* GetBlkSize(long *sizeP) -- returns blocksize used by filesystem for a file.
 138  *     Doesn't work on BLK or CHR devices. */
 139
 140 #define USD_IOCTL_GETBLKSIZE    9
 141
 142 typedef struct {
 143     int tp_op;                  /* tape operation */
 144     int tp_count;               /* tape operation count argument */
 145 } usd_tapeop_t;
 146
 147 #define USDTAPE_WEOF     0      /* write specified number of tape marks */
 148 #define USDTAPE_REW      1      /* rewind tape */
 149 #define USDTAPE_FSF      2      /* forward-space specified number of tape marks */
 150 #define USDTAPE_BSF      3      /* back-space specified number of tape marks */
 151 #define USDTAPE_PREPARE  4      /* ready tape drive for operation */
 152 #define USDTAPE_SHUTDOWN 5      /* decommission tape drive after operation */
 153
 154 #endif /* OPENAFS_USD_H */