XrdSfsInterface.hh

Go to the documentation of this file.

#ifndef __SFS_INTERFACE_H__
#define __SFS_INTERFACE_H__
/******************************************************************************/
/*                                                                            */
/*                    X r d S f s I n t e r f a c e . h h                     */
/*                                                                            */
/* (c) 2010 by the Board of Trustees of the Leland Stanford, Jr., University  */
/*   Produced by Andrew Hanushevsky for Stanford University under contract    */
/*              DE-AC02-76-SFO0515 with the Department of Energy              */
/*                                                                            */
/* This file is part of the XRootD software suite.                            */
/*                                                                            */
/* XRootD is free software: you can redistribute it and/or modify it under    */
/* the terms of the GNU Lesser General Public License as published by the     */
/* Free Software Foundation, either version 3 of the License, or (at your     */
/* option) any later version.                                                 */
/*                                                                            */
/* XRootD is distributed in the hope that it will be useful, but WITHOUT      */
/* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or      */
/* FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public       */
/* License for more details.                                                  */
/*                                                                            */
/* You should have received a copy of the GNU Lesser General Public License   */
/* along with XRootD in a file called COPYING.LESSER (LGPL license) and file  */
/* COPYING (GPL license).  If not, see <http://www.gnu.org/licenses/>.        */
/*                                                                            */
/* The copyright holder's institutional names and contributor's names may not */
/* be used to endorse or promote products derived from this software without  */
/* specific prior written permission of the institution or contributor.       */
/******************************************************************************/

#include <string.h>      // For strlcpy()
#include <errno.h>
#include <sys/types.h>
#include <sys/stat.h>

#include "XrdOuc/XrdOucErrInfo.hh"
#include "XrdOuc/XrdOucIOVec.hh"
#include "XrdOuc/XrdOucSFVec.hh"

/******************************************************************************/
/*                            O p e n   M o d e s                             */
/******************************************************************************/

#define SFS_O_RDONLY           0         // open read/only
#define SFS_O_WRONLY           1         // open write/only
#define SFS_O_RDWR             2         // open read/write
#define SFS_O_CREAT        0x100         // used for file creation
#define SFS_O_TRUNC        0x200         // used for file truncation
#define SFS_O_MULTIW       0x400         // used for multi-write locations
#define SFS_O_POSC     0x0100000         // persist on successful close
#define SFS_O_FORCE    0x0200000         // used for locate only
#define SFS_O_HNAME    0x0400000         // used for locate only
#define SFS_O_LOCAL    0x0800000         // used for locate only (local cmd)
#define SFS_O_NOWAIT  0x01000000         // do not impose operational delays
#define SFS_O_RAWIO   0x02000000         // allow client-side decompression
#define SFS_O_RESET   0x04000000         // Reset any cached information
#define SFS_O_REPLICA 0x08000000         // Open for replication

// The following flag may be set in the access mode arg for open() & mkdir()
// Note that on some systems mode_t is 16-bits so we use a careful value!
//
#define SFS_O_MKPTH   0x00004000         // Make directory path if missing

// The following options are here to provide a uniform clustering interface.
// They may be passed through open/locate/stat, as applicable.
//
#define SFS_O_LOCATE  0x10000000         // This request generated by locate()
#define SFS_O_STAT    0x20000000         // This request generated by stat()
#define SFS_O_META    0x40000000         // This request generated by metaop

/******************************************************************************/
/*                               D e f i n e s                                */
/******************************************************************************/

// Common fctl  command values (0 to 255)
//
#define SFS_FCTL_GETFD    1 // Return file descriptor if possible
#define SFS_FCTL_STATV    2 // Return visa information
#define SFS_FCTL_SPEC1    3 // Return implementation defined information

#define SFS_SFIO_FDVAL 0x80000000 // Use SendData() method GETFD response value

// Common fsctl command values (0 to 255)
//
#define SFS_FSCTL_CMD   255

#define SFS_FSCTL_LOCATE  1 // Locate a file
#define SFS_FSCTL_STATFS  2 // Return FS data
#define SFS_FSCTL_STATLS  3 // Return LS data
#define SFS_FSCTL_STATXA  4 // Return XA data
#define SFS_FSCTL_STATCC  5 // Return Cluster Config status
#define SFS_FSCTL_PLUGIN  8 // Return Implementation Dependent Data
#define SFS_FSCTL_PLUGIO 16 // Return Implementation Dependent Data

// Return values for integer & XrdSfsXferSize returning XrdSfs methods
//
#define SFS_STALL         1 // Return value -> Seconds to stall client
#define SFS_OK            0 // ErrInfo code -> All is well
#define SFS_ERROR        -1 // ErrInfo code -> Error occurred
#define SFS_REDIRECT   -256 // ErrInfo code -> Port number to redirect to
#define SFS_STARTED    -512 // ErrInfo code -> Estimated seconds to completion
#define SFS_DATA      -1024 // ErrInfo code -> Length of data
#define SFS_DATAVEC   -2048 // ErrInfo code -> Num iovec elements in msgbuff

// The following macros are used for dealing with special local paths
//
#define SFS_LCLPRFX    "/=/"
#define SFS_LCLPLEN    3
#define SFS_LCLPATH(x) !strncmp(x, SFS_LCLPRFX, SFS_LCLPLEN)
#define SFS_LCLPRFY    "/="
#define SFS_LCLROOT(x) !strncmp(x, SFS_LCLPRFX, SFS_LCLPLEN-1) \
                       && (*(x+SFS_LCLPLEN-1) == '/' || *(x+SFS_LCLPLEN-1) == 0)

/******************************************************************************/
/*                 S t r u c t u r e s   &   T y p e d e f s                  */
/******************************************************************************/

typedef long long     XrdSfsFileOffset;
typedef int           XrdSfsFileOpenMode;
typedef int           XrdSfsMode;
typedef int           XrdSfsXferSize;

enum XrdSfsFileExistence 
{
     XrdSfsFileExistNo,
     XrdSfsFileExistIsFile,
     XrdSfsFileExistIsDirectory,
     XrdSfsFileExistIsOffline,
     XrdSfsFileExistIsOther
};
//------------------------------------------------

#define Prep_PRTY0 0
#define Prep_PRTY1 1
#define Prep_PRTY2 2
#define Prep_PRTY3 3
#define Prep_PMASK 3
#define Prep_SENDAOK 4
#define Prep_SENDERR 8
#define Prep_SENDACK 12
#define Prep_WMODE   16
#define Prep_STAGE   32
#define Prep_COLOC   64
#define Prep_FRESH  128

class XrdOucTList;

struct XrdSfsFSctl 
{
 const char            *Arg1;      
       int              Arg1Len;   
       int              Arg2Len;   
 const char            *Arg2;      
};

struct XrdSfsPrep  
{
       char            *reqid;     
       char            *notify;    
       int              opts;      
       XrdOucTList     *paths;     
       XrdOucTList     *oinfo;     
};

/******************************************************************************/
/*                      A b s t r a c t   C l a s s e s                       */
/******************************************************************************/

class  XrdSfsFile;
class  XrdSfsDirectory;
class  XrdOucEnv;
class  XrdOucTList;
class  XrdSecEntity;

/******************************************************************************/
/*                      X r d S f s F i l e S y s t e m                       */
/******************************************************************************/
  
//-----------------------------------------------------------------------------
//-----------------------------------------------------------------------------

class XrdSfsFileSystem
{
public:

//-----------------------------------------------------------------------------
//-----------------------------------------------------------------------------

virtual XrdSfsDirectory *newDir(char *user=0, int MonID=0)  = 0;

//-----------------------------------------------------------------------------
//-----------------------------------------------------------------------------

virtual XrdSfsFile      *newFile(char *user=0, int MonID=0) = 0;

//-----------------------------------------------------------------------------
//-----------------------------------------------------------------------------

enum    csFunc {csCalc = 0, csGet, csSize};

virtual int            chksum(      csFunc            Func,
                              const char             *csName,
                              const char             *path,
                                    XrdOucErrInfo    &eInfo,
                              const XrdSecEntity     *client = 0,
                              const char             *opaque = 0)
{
  (void)Func; (void)csName; (void)path; (void)eInfo; (void)client;
  (void)opaque;
  eInfo.setErrInfo(ENOTSUP, "Not supported.");
  return SFS_ERROR;
}

//-----------------------------------------------------------------------------
//-----------------------------------------------------------------------------

virtual int            chmod(const char             *path,
                                   XrdSfsMode        mode,
                                   XrdOucErrInfo    &eInfo,
                             const XrdSecEntity     *client = 0,
                             const char             *opaque = 0) = 0;

//-----------------------------------------------------------------------------
//-----------------------------------------------------------------------------

virtual void           Disc(const XrdSecEntity     *client = 0)
{
  (void)client;
}

//-----------------------------------------------------------------------------
//-----------------------------------------------------------------------------

virtual void           EnvInfo(XrdOucEnv *envP)
{
  (void)envP;
}

//-----------------------------------------------------------------------------
//-----------------------------------------------------------------------------

virtual int            FSctl(const int               cmd,
                                   XrdSfsFSctl      &args,
                                   XrdOucErrInfo    &eInfo,
                             const XrdSecEntity     *client = 0)
{
  (void)cmd; (void)args; (void)eInfo; (void)client;
  return SFS_OK;
}

//-----------------------------------------------------------------------------
//-----------------------------------------------------------------------------

virtual int            fsctl(const int               cmd,
                             const char             *args,
                                   XrdOucErrInfo    &eInfo,
                             const XrdSecEntity     *client = 0) = 0;

//-----------------------------------------------------------------------------
//-----------------------------------------------------------------------------

virtual int            getStats(char *buff, int blen) = 0;

//-----------------------------------------------------------------------------
//-----------------------------------------------------------------------------

virtual const char    *getVersion() = 0;

//-----------------------------------------------------------------------------
//-----------------------------------------------------------------------------

virtual int            exists(const char                *path,
                                    XrdSfsFileExistence &eFlag,
                                    XrdOucErrInfo       &eInfo,
                              const XrdSecEntity        *client = 0,
                              const char                *opaque = 0) = 0;

//-----------------------------------------------------------------------------
//-----------------------------------------------------------------------------

virtual int            mkdir(const char              *path,
                                   XrdSfsMode         mode,
                                   XrdOucErrInfo     &eInfo,
                             const XrdSecEntity      *client = 0,
                             const char              *opaque = 0) = 0;

//-----------------------------------------------------------------------------
//-----------------------------------------------------------------------------

virtual int            prepare(      XrdSfsPrep      &pargs,
                                     XrdOucErrInfo   &eInfo,
                               const XrdSecEntity    *client = 0) = 0;

//-----------------------------------------------------------------------------
//-----------------------------------------------------------------------------

virtual int            rem(const char                *path,
                                 XrdOucErrInfo       &eInfo,
                           const XrdSecEntity        *client = 0,
                           const char                *opaque = 0) = 0;

//-----------------------------------------------------------------------------
//-----------------------------------------------------------------------------

virtual int            remdir(const char             *path,
                                    XrdOucErrInfo    &eInfo,
                              const XrdSecEntity     *client = 0,
                              const char             *opaque = 0) = 0;

//-----------------------------------------------------------------------------
//-----------------------------------------------------------------------------

virtual int            rename(const char             *oPath,
                              const char             *nPath,
                                    XrdOucErrInfo    &eInfo,
                              const XrdSecEntity     *client = 0,
                              const char             *opaqueO = 0,
                              const char             *opaqueN = 0) = 0;

//-----------------------------------------------------------------------------
//-----------------------------------------------------------------------------

virtual int            stat(const char               *Name,
                                  struct stat        *buf,
                                  XrdOucErrInfo      &eInfo,
                            const XrdSecEntity       *client = 0,
                            const char               *opaque = 0) = 0;

//-----------------------------------------------------------------------------
//-----------------------------------------------------------------------------

virtual int            stat(const char               *path,
                                  mode_t             &mode,
                                  XrdOucErrInfo      &eInfo,
                            const XrdSecEntity       *client = 0,
                            const char               *opaque = 0) = 0;

//-----------------------------------------------------------------------------
//-----------------------------------------------------------------------------

virtual int            truncate(const char             *path,
                                      XrdSfsFileOffset  fsize,
                                      XrdOucErrInfo    &eInfo,
                                const XrdSecEntity     *client = 0,
                                const char             *opaque = 0) = 0;

//-----------------------------------------------------------------------------
//-----------------------------------------------------------------------------

                       XrdSfsFileSystem() {}
virtual               ~XrdSfsFileSystem() {}
};

/******************************************************************************/
/*              F i l e   S y s t e m   I n s t a n t i a t o r               */
/******************************************************************************/

//-----------------------------------------------------------------------------
typedef XrdSfsFileSystem *(*XrdSfsFileSystem_t) (XrdSfsFileSystem *nativeFS,
                                                 XrdSysLogger     *Logger,
                                                 const char       *configFn);

typedef XrdSfsFileSystem *(*XrdSfsFileSystem2_t)(XrdSfsFileSystem *nativeFS,
                                                 XrdSysLogger     *Logger,
                                                 const char       *configFn,
                                                 XrdOucEnv        *envP);

//-----------------------------------------------------------------------------
  
//------------------------------------------------------------------------------
//------------------------------------------------------------------------------

/******************************************************************************/
/*                            X r d S f s F i l e                             */
/******************************************************************************/

//------------------------------------------------------------------------------
//------------------------------------------------------------------------------

class XrdSfsAio;
class XrdSfsDio;
class XrdSfsXio;
  
class XrdSfsFile
{
public:

//-----------------------------------------------------------------------------
//-----------------------------------------------------------------------------

        XrdOucErrInfo  error;

//-----------------------------------------------------------------------------
//-----------------------------------------------------------------------------

virtual int            open(const char                *fileName,
                                  XrdSfsFileOpenMode   openMode,
                                  mode_t               createMode,
                            const XrdSecEntity        *client = 0,
                            const char                *opaque = 0) = 0;

//-----------------------------------------------------------------------------
//-----------------------------------------------------------------------------

virtual int            close() = 0;

//-----------------------------------------------------------------------------
//-----------------------------------------------------------------------------

virtual int            fctl(const int               cmd,
                            const char             *args,
                                  XrdOucErrInfo    &eInfo) = 0;

//-----------------------------------------------------------------------------
//-----------------------------------------------------------------------------

virtual int            fctl(const int               cmd,
                                  int               alen,
                                  const char       *args,
                            const XrdSecEntity     *client = 0)
{
  (void)cmd; (void)alen; (void)args; (void)client;
  return SFS_OK;
}

//-----------------------------------------------------------------------------
//-----------------------------------------------------------------------------

virtual const char    *FName() = 0;


//-----------------------------------------------------------------------------
//-----------------------------------------------------------------------------

virtual int            getMmap(void **Addr, off_t &Size) = 0;

//-----------------------------------------------------------------------------
//-----------------------------------------------------------------------------

virtual XrdSfsXferSize read(XrdSfsFileOffset   offset,
                            XrdSfsXferSize     size) = 0;

//-----------------------------------------------------------------------------
//-----------------------------------------------------------------------------

virtual XrdSfsXferSize read(XrdSfsFileOffset   offset,
                            char              *buffer,
                            XrdSfsXferSize     size) = 0;

//-----------------------------------------------------------------------------
//-----------------------------------------------------------------------------

virtual XrdSfsXferSize read(XrdSfsAio *aioparm) = 0;

//-----------------------------------------------------------------------------
//-----------------------------------------------------------------------------

virtual XrdSfsXferSize readv(XrdOucIOVec      *readV,
                             int               rdvCnt)
                            {XrdSfsXferSize rdsz, totbytes = 0;
                             for (int i = 0; i < rdvCnt; i++)
                                 {rdsz = read(readV[i].offset,
                                              readV[i].data, readV[i].size);
                                  if (rdsz != readV[i].size)
                                     {if (rdsz < 0) return rdsz;
                                      error.setErrInfo(ESPIPE,"read past eof");
                                      return SFS_ERROR;
                                     }
                                  totbytes += rdsz;
                                 }
                             return totbytes;
                            }

//-----------------------------------------------------------------------------
//-----------------------------------------------------------------------------

virtual int            SendData(XrdSfsDio         *sfDio,
                                XrdSfsFileOffset   offset,
                                XrdSfsXferSize     size)
{
  (void)sfDio; (void)offset; (void)size;
  return SFS_OK;
}

//-----------------------------------------------------------------------------
//-----------------------------------------------------------------------------

virtual XrdSfsXferSize write(XrdSfsFileOffset  offset,
                             const char       *buffer,
                             XrdSfsXferSize    size) = 0;

//-----------------------------------------------------------------------------
//-----------------------------------------------------------------------------

virtual int            write(XrdSfsAio *aioparm) = 0;

//-----------------------------------------------------------------------------
//-----------------------------------------------------------------------------

virtual XrdSfsXferSize writev(XrdOucIOVec      *writeV,
                              int               wdvCnt)
                             {XrdSfsXferSize wrsz, totbytes = 0;
                              for (int i = 0; i < wdvCnt; i++)
                                  {wrsz = write(writeV[i].offset,
                                                writeV[i].data, writeV[i].size);
                                   if (wrsz != writeV[i].size)
                                      {if (wrsz < 0) return wrsz;
                                      error.setErrInfo(ESPIPE,"write past eof");
                                      return SFS_ERROR;
                                     }
                                  totbytes += wrsz;
                                 }
                             return totbytes;
                            }

//-----------------------------------------------------------------------------
//-----------------------------------------------------------------------------

virtual int            stat(struct stat *buf) = 0;

//-----------------------------------------------------------------------------
//-----------------------------------------------------------------------------

virtual int            sync() = 0;

//-----------------------------------------------------------------------------
//-----------------------------------------------------------------------------

virtual int            sync(XrdSfsAio *aiop) = 0;

//-----------------------------------------------------------------------------
//-----------------------------------------------------------------------------

virtual int            truncate(XrdSfsFileOffset fsize) = 0;

//-----------------------------------------------------------------------------
//-----------------------------------------------------------------------------

virtual int            getCXinfo(char cxtype[4], int &cxrsz) = 0;

//-----------------------------------------------------------------------------
//-----------------------------------------------------------------------------

virtual void           setXio(XrdSfsXio *xioP) { (void)xioP; }

//-----------------------------------------------------------------------------
//-----------------------------------------------------------------------------

                       XrdSfsFile(const char *user=0, int MonID=0)
                                 : error(user, MonID) {}

//-----------------------------------------------------------------------------
//-----------------------------------------------------------------------------

virtual               ~XrdSfsFile() {}

}; // class XrdSfsFile

/******************************************************************************/
/*                       X r d S f s D i r e c t o r y                        */
/******************************************************************************/

//------------------------------------------------------------------------------
//------------------------------------------------------------------------------
  
class XrdSfsDirectory
{
public:

//-----------------------------------------------------------------------------
//-----------------------------------------------------------------------------

        XrdOucErrInfo error;

//-----------------------------------------------------------------------------
//-----------------------------------------------------------------------------

virtual int         open(const char              *path,
                         const XrdSecEntity      *client = 0,
                         const char              *opaque = 0) = 0;

//-----------------------------------------------------------------------------
//-----------------------------------------------------------------------------

virtual const char *nextEntry() = 0;

//-----------------------------------------------------------------------------
//-----------------------------------------------------------------------------

virtual int         close() = 0;

//-----------------------------------------------------------------------------
//-----------------------------------------------------------------------------

virtual const char *FName() = 0;

//-----------------------------------------------------------------------------
//-----------------------------------------------------------------------------

virtual int         autoStat(struct stat *buf)
                            {(void)buf;
                             error.setErrInfo(ENOTSUP, "Not supported.");
                             return SFS_ERROR;
                            }

//-----------------------------------------------------------------------------
//-----------------------------------------------------------------------------

                    XrdSfsDirectory(const char *user=0, int MonID=0)
                                   : error(user, MonID) {}

//-----------------------------------------------------------------------------
//-----------------------------------------------------------------------------

virtual            ~XrdSfsDirectory() {}

}; // class XrdSfsDirectory
#endif