/* Copyright (c) 2011, 2015, Oracle and/or its affiliates. 
All rights reserved.*/
 
/* 
   NAME 
     acfslib.h - <one-line expansion of the name> 

   DESCRIPTION 
     ACFS library public header file

*/

#ifndef ACFSLIB_ORACLE
#define ACFSLIB_ORACLE

#ifndef ORATYPES
#include <oratypes.h>
#endif

#ifdef __cplusplus
extern "C"
{
#endif

#define ACFS_API_SUCCESS          0
#define ACFS_API_EINVAL           1
#define ACFS_API_ENOINIT          2 
#define ACFS_API_ENOTACFS         3
#define ACFS_API_ENOMEM           4
#define ACFS_API_RETRY            5
#define ACFS_API_EOPEN            6
#define ACFS_API_EDONE            7
#define ACFS_API_ESNAPEXIST       8
#define ACFS_API_ESNAPNAME        9
#define ACFS_API_ESNAPPARENT     10
#define ACFS_API_ENOSNAPPARENT   11
#define ACFS_API_ENOSNAPEXIST    12
#define ACFS_API_ENOTSUP         13
#define ACFS_API_EROLLING        14
#define ACFS_API_EREMOTE         15
#define ACFS_API_EREPLSNAP       16
#define ACFS_API_EOSVERS         17
#define ACFS_API_ETOOMANYSNAPS   18
#define ACFS_API_ECOMPAT         19
#define ACFS_API_ESNAPCOMPAT     20
#define ACFS_API_OK_WARN_STOR    21
#define ACFS_API_EINVALVERS      22
#define ACFS_API_FAIL            -1

#define ACFS_TAG_SUCCESS ACFS_API_SUCCESS
#define ACFS_TAG_FAIL    ACFS_API_FAIL

#define ACFS_FIXED_TAG_VALUE      "0"
#define ACFS_FIXED_TAG_VALUE_SIZE  1

#define ACFS_PLUGIN_SUCCESS         ACFS_API_SUCCESS
#define ACFS_PLUGIN_MORE_AVAIL      1
#define ACFS_PLUGIN_NO_NEW_METRICS  2
#define ACFS_PLUGIN_FAIL            ACFS_API_FAIL

#define ACFS_FILEID_MAX_PATH_LEN 65536

/*---------------------------------------------------------------------------
                           EXPORT FUNCTIONS
  ---------------------------------------------------------------------------*/

/*--- ACFS Tagging API ------------------------------------------------------*/

/* acfsgettag: 
*   Use the acfsgettag() library call to retrieve the ACFS tag name's value
*   string. However, ACFS tag names currently use a fixed value string
*   of "0", the number zero character with a byte length of one. So
*   the value will be the same for all ACFS tag name entries.
*   The size of the value buffer can be determined by
*   calling acfsgettag() with a NULL value and 0 size. The library
*   call will return the byte size necessary to hold the tag name value
*   string. Acfsgettag() returns an ENODATA error when the tag name is not
*   set on the file.
*
*   path    - Pointer to file or directory path name.
*   tagname - Pointer to a NULL-terminated ACFS tag name in the format
*             of "tagname" for regular files and directories.
*   value   - Memory buffer to retrieve the ACFS tag value. 
*   size    - Byte size of the memory buffer that will hold the returned
*             ACFS tag value.
*   flags   - Reserved for future expansion. Must be set to 0.
*
*  Return value:
*  Greater than zero - Success with the return value indicating the
*                      byte length of the output value string.
*  ACFS_TAG_FAIL     - Failure with errno or WIN32 error set.
*
*   UNIX errno in case of failure:
*       EINVAL       - The tag name syntax is invalid or too long.
*       ENODATA      - Tag name does not exist for this file or directory.
*       ERANGE       - Value buffer is too small to hold the returned value.
*       EACCES       - Search permission denied for one of the directories
*                      in the path prefix of path; or the user does not
*                      have permission on the file to read tag names.
*       ENAMETOOLONG - File name too long.
*       ENOENT       - A component of path does not exist.
*
*   WIN32 error in case of failure:    
*       ERROR_INVALID_PARAMETER   - Tag name does not exist for this file or
*                                   directory or the tag name is syntactically
*                                   incorrect.
*       ERROR_INSUFFICIENT_BUFFER - Value buffer is too small to hold the
*                                   returned value.
*       ERROR_ACCESS_DENIED       - Search permission denied for one of the
*                                   directories in the path prefix of path; or
*                                   the user does not have permission on the
*                                   file to read tag names.
*       ERROR_FILE_NOT_FOUND      - The system cannot find the file specified.
*       ERROR_INVALID_NAME        - The file name or path name is too long or
*                                   is malformed.
*/

sb8 acfsgettag(const oratext *path, const oratext *tagname, oratext *value,
                   size_t size, ub4 flags);


/* acfssettag: 
*   Use the acfssettag() library call to set a tag name on an ACFS file.
*   Note that ACFS tag names currently use a fixed value string of "0", the
*   number zero character with a byte length of one. The value will be the same
*   for all ACFS tag name entries.
*   If the tag name already exists on the file, then acfssettag() returns
*   success.
* 
*   path    - Pointer to full file or directory path name.
*   tagname - Pointer to a NULL-terminated ACFS tag name in the name format of
*             "tagname" for regular files and directories.
*   value   - Memory buffer containing the ACFS tag value to set.
*             Currently set to a string containing only a zero character.
*   size    - Byte size of the ACFS tag name value string stored in the
*             value memory buffer.
*   flags   - Reserved for future expansion. Must be set to 0.
*
*  Return value:
*   ACFS_TAG_SUCCESS - Success.
*   ACFS_TAG_FAIL    - Failure with errno or WIN32 error set.
*
*   UNIX errno in case of failure:
*       EINVAL - Tag name syntax is invalid or too long; or tag value is
*                invalid.
*       EACCES - Search permission denied for one of the directories in the
*                path prefix of path; or the user does not have permission
*                on the file to set the tag name.
*       ENAMETOOLONG - File name too long.
*       ENOENT - A component of path does not exist.
*
*   WIN32 error in case of failure:    
*       ERROR_INVALID_PARAMETER   - The tag name is syntactically incorrect.
*                                   returned value.
*       ERROR_ACCESS_DENIED       - Search permission denied for one of the
*                                   directories in the path prefix of path or
*                                   the user does not have permission on the
*                                   file to set a tag name.
*       ERROR_FILE_NOT_FOUND      - The system cannot find the file specified.
*       ERROR_INVALID_NAME        - The file name or path name is too long or
*                                   is malformed.
*/

sb8 acfssettag(const oratext *path, const oratext *tagname,
               oratext *value, size_t size, ub4 flags);


/* acfsremovetag: 
*   Use the acfsremovetag() library call to remove a tag name on an ACFS file.
*   If the tag name does not exist on the file, then acfsremovetag() returns
*   success.
*
*   path    - Pointer to file or directory path name.
*   tagname - Pointer to a NULL-terminated ACFS tag name in the format of
*             "tagname" for regular files and directories.
*   flags   - Reserved for future expansion. Must be set to 0.
*
*  Return value:
*   ACFS_TAG_SUCCESS - Success.
*   ACFS_TAG_FAIL    - Failure with errno or WIN32 error set.
*
*   UNIX errno in case of failure:
*       EINVAL       - Tag name syntax is invalid or too long.
*       EACCES       - Search permission denied for one of the directories
*                      in the path prefix of path; or the user does not have
*                      permission on the file to remove the tag name.
*       ENAMETOOLONG - File name too long.
*       ENOENT       - A component of path does not exist.
*
*   WIN32 error in case of failure:    
*       ERROR_INVALID_PARAMETER   - The tag name is syntactically incorrect.
*       ERROR_ACCESS_DENIED       - Search permission denied for one of the
*                                   directories in the path prefix of path or
*                                   the user does not have permission on the
*                                   file to remove the tag name.
*       ERROR_FILE_NOT_FOUND      - The system cannot find the file specified.
*       ERROR_INVALID_NAME        - The file name or path name is too long or
*                                   is malformed.
*/

sb8 acfsremovetag(const oratext *path, const oratext *tagname, ub4 flags);


/* acfslistags: 
*   Use the acfslisttags() library call to retrieve all the tag name's
*   assigned to an ACFS file.  This library call returns a list of
*   tag names into the list memory buffer. Each tag name in the list
*   is terminated with a NULL.  If a file has no tag names then the
*   list will be empty. The memory buffer must be large enough to hold
*   all of the tag names assigned to an ACFS file. A program can obtain
*   the required buffer size by first calling acfslisttags() with a zero
*   value buffer size and NULL list buffer.  The return value contains
*   the memory buffer size required to support the full list. A second
*   acfslisttags() call can then be made with a memory buffer large
*   enough to support the list of names.
*
*   path  - Pointer to file or directory path name.
*
*   list  - Pointer to a memory buffer containing the list of ACFS tag names.
*   size  - Size of the memory buffer that will hold the returned ACFS
*           tag name list. 
*   flags - Reserved for future expansion. Must be set to 0.
*
*  Return value:
*   Zero or greater - Success where the return value is the byte size of the
*                     tag name list or 0 when the file has no tag names.
*   ACFS_TAG_FAIL   - Failure with errno or WIN32 error set.
*
*   UNIX errno in case of failure:
*       ERANGE       - List buffer is too small to hold the complete list
*                      of tag names.
*       EACCES       - Search permission denied for one of the directories
*                      in the path prefix of path; or the user does not
*                      have permission on the file to read tag names.
*       ENAMETOOLONG - File name too long.
*       ENOENT       - A component of path does not exist.
*
*   WIN32 error in case of failure:    
*       ERROR_INSUFFICIENT_BUFFER - List buffer is too small to hold the
*                                   returned data.
*       ERROR_ACCESS_DENIED       - Search permission denied for one of the
*                                   directories in the path prefix of path or
*                                   the user does not have permission on the
*                                   file to read tag names.
*       ERROR_FILE_NOT_FOUND      - The system cannot find the file specified.
*       ERROR_INVALID_NAME        - The file name or path name is too long or
*                                   is malformed.
*/

sb8 acfslisttags(const oratext *path, oratext *list, size_t size, ub4 flags);


/*--- ACFS Plug-in API ------------------------------------------------------*/

#define ACFS_PLUGIN_API_VERSION 1

#define ACFS_METRIC_TYPE1 (0x0001)
#define ACFS_METRIC_TYPE2 (0x0002)


typedef struct _ACFS_METRIC1 {
    ub2 acfs_version;
    ub2 acfs_type;
    ub4	acfs_seqno;
    ub8	acfs_nreads;
    ub8	acfs_nwrites;
    ub8	acfs_rcachehits;
    ub4	acfs_avgrsize;
    ub4	acfs_avgwsize;
    ub4	acfs_minrsize;
    ub4	acfs_maxrsize;
    ub4	acfs_minwsize;
    ub4	acfs_maxwsize;
    ub4 acfs_rbytes_per_sec;
    ub4 acfs_wbytes_per_sec;
    ub8 acfs_timestamp;
    ub8 acfs_elapsed_secs;
} ACFS_METRIC1;

typedef struct _ACFS_FILE_ID {
    ub8 acfs_fenum;
    ub4 acfs_genum;
    ub4 acfs_reserved1;
} ACFS_FILE_ID;

typedef struct _ACFS_METRIC2_REC {
    ACFS_FILE_ID acfs_file_id;
    ub8 acfs_start_offset;
    ub8 acfs_size;
    ub8 acfs_seq_num;
} ACFS_METRIC2_REC;

typedef struct _ACFS_METRIC2 {
    ub2 acfs_version;
    ub2 acfs_type;
    ub4	acfs_num_recs;
    ub4 acfs_buf_num;
    ub4 acfs_reserved1;
    ub8 acfs_timestamp;
    ACFS_METRIC2_REC acfs_recs[1];
} ACFS_METRIC2;


/* acfsplugin_metrics: 
*   Use the acfsplugin_metrics() library call to retrieve the metrics
*   collected for an ACFS file system.
*
*   metric_type - A flag indicating the desired ACFS metrics data; either
*                 ACFS_METRIC_TYPE1 or ACFS_METRIC_TYPE2.
*   metrics     - Pointer to a buffer which will contain the returned metrics
*                 or a value of NULL. NULL is valid only for
*                 ACFS_METRIC_TYPE2. See "Return value" below.
*   buf_len -     The length of the metrics buffer in bytes provided to
*                 retrieve metric data or zero.  Zero is valid only for
*                 ACFS_METRIC_TYPE2.  The buf_len of metrics buffer supplied
*                 under ACFS_METRIC_TYPE2 must be greater or equal to the value
*                 obtained from acfsplugin_metrics() with metrics set to a NULL
*                 pointer and buf_len equal to 0. See "Return value" below.
*   path -        Pointer to file or directory path name.
*
*   Return value - 
*       ACFS_PLUGIN_SUCCESS        - Success with nothing more to return
*       ACFS_PLUGIN_MORE_AVAIL     - Success with more metrics available
*       ACFS_PLUGIN_NO_NEW_METRICS - Success with no new metrics available
*       ACFS_PLUGIN_FAIL           - Error
*     
*     For ACFS_METRIC_TYPE2 only:
*       Greater than zero          - Success with the return value indicating
*                                    the required minimum byte length of the
*                                    ACFS_METRIC2 buffer when the following
*                                    input arguments are set as indicated
*                                    below:
*                                       - metrics = NULL
*                                       - buf_len = 0
*                                    Note: The returned buffer size is
*                                    fixed and thus only needs to be fetched
*                                    once.
*
*   UNIX errno in case of failure:
*       EINVAL - Invalid arguments to API (e.g. null path, invalid metric
*                type flag)
*       ERANGE -
*          ACFS_METRIC_TYPE1 - buf_len = 0 
*          ACFS_METRIC_TYPE2 - buf_len not equal to zero when metrics buffer
*                              pointer is specified as NULL.
*                            - buf_len of metrics buffer pointer is less than
*                              the value obtained from acfsplugin_metrics()
*                              with metrics set to a NULL pointer and buf_len
*                              equal to 0.
*       EBADF  - Fail to open mount path
*
*   WIN32 error in case of failure:    
*       ERROR_INVALID_PARAMETER   - Invalid arguments to API
*       ERROR_INSUFFICIENT_BUFFER
*          ACFS_METRIC_TYPE1 - buf_len = 0 
*          ACFS_METRIC_TYPE2 - buf_len not equal to zero when metrics buffer
*                              pointer is specified as NULL.
*                            - buf_len of metrics buffer pointer is less than
*                              the value obtained from acfsplugin_metrics()
*                              with metrics set to a NULL pointer and buf_len
*                              equal to 0.
*       ERROR_INVALID_HANDLE      - Fail to open mount path
*/

sb8 acfsplugin_metrics(ub4 metric_type, ub1 *metrics, ub4 buf_len,
                       oratext *path);


/* acfsfileid_lookup:
*   Use the acfsfileid() library call to translate an type ACFS_FILE_ID struct,
*   obtained using the acfsplugin_metrics call for type ACFS_METRIC2, 
*   into a full pathname to the corresponding ACFS file.
*
*   Note that the filesystem may change between between the time ACFS_METRIC2
*   data is recorded and acfsfileid_lookup() is called.  ACFS_FILE_ID includes
*   acfs_fenum (eg. inode) and a generation number, acfs_genum. acfs_genum
*   protect against filesystem name space changes which may re-use the same
*   acfs_fenum (eg. file is deleted, inode is re-used).  ENOENT or 
*   ERROR_FILE_NOT_FOUND is returned in these cases.
*
*   acfsfileid_lookup called on a fenum/genum pair which translates to a hard linked file
*   will resolve to one of the link pathnames.  Note that if some of the linked
*   files are deleted, the interface may not be able to resolve the fenum/genum pair
*   to one of the remaining links.  This may result in a return value of
*   ACFS_API_FAIL and error values of ENOENT or ERROR_FILE_NOT_FOUND. 
*
*   file_id     - Obtained using the acfsplugin_metrics call of type
*                 ACFS_METRIC2 and supplied to this call.
*   path        - Full path name returned. Only the first path will be
*                 returned if multiple hard links exist on the resolved file.
*   path_len    - Length of caller allocated memory pointed to by path for
*                 the returned full path name.  The required allocation size
*                 is exactly ACFS_FILEID_MAX_PATH_LEN.
*   mount_point - Mount point used to select the ACFS filesystem of interest.
*   flags       - Reserved for future expansion. Must be set to 0.
*
*   Return value - 
*       ACFS_API_SUCCESS - Success
*       ACFS_API_FAIL    - Error
*
*   UNIX errno in case of failure:
*       EINVAL - Invalid arguments to API (e.g. null buffer or path, bad
*                file_id, non-ACFS mount point, flags != 0).
*       ERANGE - path_len is not equal to ACFS_FILEID_MAX_PATH_LEN 
*       EBADF  - Failed to open mount path
*       ENOENT - file_id does not resolve to the expected instance of a 
*                file name or full path on the specifed ACFS mount point.
*                See this API'd desciption for further information.
*
*   WIN32 error in case of failure:    
*       ERROR_INVALID_PARAMETER   - Invalid arguments to API (e.g. null buffer
*                                   or path, bad file_id, non-ACFS mount point,
*                                   flags != 0).
*       ERROR_INSUFFICIENT_BUFFER - path_len is not equal to
*                                   ACFS_FILEID_MAX_PATH_LEN.
*       ERROR_INVALID_HANDLE      - Fail to open mount path
*       ERROR_FILE_NOT_FOUND      - file_id does not resolve to the expected
*                                   instance of a file name or full path on
*                                   the specifed ACFS mount point. See this
*                                   API call's desciption for further
*                                   information.
*/
sb8 acfsfileid_lookup(ACFS_FILE_ID file_id, oratext *path, ub4 path_len,
                      oratext *mount_point, ub4 flags);


/*--------------------- ACFS Snapshot APIs ---------------------------------*/


struct acfslibctx;

#define ACFSLIB_API_V1 ((ub4)0x00000001)                   /* API version 1 */

/* acfslib_version: 
*   Version handshake for ACFS library initialization. 
*
*   This call determines compatibility between the version of the ACFS 
*   library the caller linked with, and the version that is on the system.
*   The caller sets a bit for every version that it can support. If the
*   call succeeds, all but one of the version flags will have been cleared.
*   It is this returned version that will be passed to acfslib_init(). 
*   
*   version(IN/OUT)  - ACFS library API version number
*
*   Return value - 
*       ACFS_API_SUCCESS           - Success.
*                                    Version argument contains a single
*                                    version 
*       ACFS_API_EINVAL            - Invalid argument
*       ACFS_API_ECOMPAT           - No compatible version between client
*                                    and library
*/
sb8 acfslib_version(ub4 *version);

typedef sb8 (*acfslib_version_t)(ub4 *version);


/* acfslib_init: 
*   Initializes the ACFS library context. This call is required for ACFS
*   library APIs that require a context.
*   Contexts cannot be shared across processes or threads.
*   
*   pctx        - A pointer to a pointer of an acfslibctx structure.
*                 On success, this function will allocate a valid acfslibctx
*                 structure that can be used for later ACFS library calls.
*
*   version     - Interface version of the ACFS library API to use. 
*                 This argument must be the output of a succesful call to
*                 acfslib_version().
*
*   Return value - 
*       ACFS_API_SUCCESS           - Success
*       ACFS_API_EINVAL            - Invalid argument
*       ACFS_API_ENOMEM            - Insufficient memory
*/
sb8 acfslib_init(struct acfslibctx **pctx, ub4 version);

typedef sb8 (*acfslib_init_t)(struct acfslibctx **pctx, ub4 version);

/* acfslib_term: 
*  Terminates a valid ACFS library context that was initialized via a call
*  to acfslib_init().
*  
*   ctx         - Pointer to a valid acfslibctx structure.
*                 On success this context will be destroyed, any further use
*                 of this context will result in API errors.
*                 
*   Return value - 
*       ACFS_API_SUCCESS           - Success
*       ACFS_API_ENOINIT           - Context not initialized
*       ACFS_API_EOPEN             - Context has open references. Such as 
*                                    calls to acfssnapinfo_open() without a 
*                                    call to acfssnapinfo_close().
*/
sb8 acfslib_term(struct acfslibctx *ctx);

typedef sb8 (*acfslib_term_t)(struct acfslibctx *ctx);

/* acfslib_getlasterr: 
*  Gets the last OS dependent error that occurred. Returns the numeric form
*  of the error as well as a human readable translation of the error.
*  Typically, this information is available when ACFS_API_FAIL is returned
*  from an ACFS library call.
*    
*   ctx         - Pointer to a valid acfslibctx structure.
*   buf         - Pointer to a buffer where the human readable error
*                 message will be stored.              
*   bufsz       - Size of the buffer 'buf'.
*   errcode     - Pointer to numeric value were the OS dependent error
*                 number will be stored.
*   
*   Return value - 
*       ACFS_API_SUCCESS           - Success
*       ACFS_API_ENOINIT           - Context not initialized
*       ACFS_API_EINVAL            - Invalid arguments. See 'Notes' below.
*
*   Notes:
*   Minimally, a pointer to either a string buffer or an error code must be
*   supplied. If neither is supplied, or if an invalid buffer size is
*   supplied, EINVAL will be returned.
*/
sb8 acfslib_getlasterr(struct acfslibctx *ctx, oratext *buf, 
                       ub4 bufsz, ub4 *errcode);

typedef sb8 (*acfslib_getlasterr_t)(struct acfslibctx *ctx, 
                                    oratext *buf, ub4 bufsz, ub4 *errcode);

/* acfslib_geterrstr: 
*  Gets the human readable string associated with the error returned
*  from the acfslib API.
*  Typically this is used for logging ACFS library errors.
*    
*   ctx         - Pointer to a valid acfslibctx structure.
*   error       - Error code to translate into a string.              
*   
*   Return value - 
*    oratext *   - String respresenting the error number passed in,
*
*   Notes:
*     If an invalid error number is passed, a string describing this
*     error is returned.
*/
oratext *
acfslib_geterrstr(struct acfslibctx *ctx, sb8 error);

typedef oratext * (*acfslib_geterrstr_t)(struct acfslibctx *ctx, sb8 error);


/* acfssnap_create: 
*  Creates a snapshot on an ACFS file system.
*  Snapshots can be of the root file system, where 'parent_snap' is NULL, or 
*  another snapshot, where 'parent_snap' is the name of the snapshot from
*  which to take another snapshot.
*  Snapshots can be read-write or read-only.
*  
*   ctx         - Pointer to a valid acfslibctx structure.
*   snap_name   - Pointer to the snapshot name that will be created. 
*                 The snapshot name must be unique from all other snapshots
*                 in the file system.
*   parent_snap - If creating a snapshot from another snapshot, this will
*                 point to the name of the parent snapshot from which to create
*                 the new snapshot. This can be an absolute pathname to the
*                 parent snapshot, or the name of the parent snapshot.
*                 If the name of the snapshot is given, the mntpt argument
*                 must be supplied.
*   mntpt       - Mount point of the ACFS file system to create the snapshot on.
*                 This can be NULL if an absolute pathname is supplied in
*                 the 'parent snapshot' argument.
*   flags       - Flags:
*                 ACFS_SNAP_RW - Read-write snapshot
*                 ACFS_SNAP_RO - Read-only snapshot
*                 * One of the above flags must be specified.
*
*   Return value - 
*       ACFS_API_SUCCESS           - Success
*       ACFS_API_ENOINIT           - Context not initialized
*       ACFS_API_EINVAL            - Invalid arguments.
*       ACFS_API_RETRY             - Conflicting operation in progress. 
*                                    Retry the operation.
*       ACFS_API_ESNAPEXIST        - Snapshot name already exists.
*       ACFS_API_ESNAPNAME         - Invalid snapshot name 
*       ACFS_API_ESNAPPARENT       - Invalid parent snapshot
*       ACFS_API_ENOSNAPPARENT     - Parent snapshot does not exist
*       ACFS_API_ENOTSUP           - Snapshot of snapshot not supported with
*                                    compatible.advm < 12.1
*       ACFS_API_EROLLING          - Cannot create snapshots during rolling
*                                    migration
*       ACFS_API_ESNAPCOMPAT       - Incompatible snapshots exist on this
*                                    file system preventing this functionality
*       ACFS_API_EREMOTE           - Remote node failure. Check logs on
*                                    other nodes for more information.
*       ACFS_API_ETOOMANYSNAPS     - Too many snapshots exist on this file
*                                    system
*       ACFS_API_FAIL              - OS dependent failure. 
*                                    See acfslib_getlasterr()
*/
sb8 acfssnap_create(struct acfslibctx *ctx, const oratext *snap_name, 
                    const oratext *parent_snap,
                    const oratext *mntpt, ub8 flags);
#define ACFS_SNAP_RW 0x1
#define ACFS_SNAP_RO 0x2

typedef sb8 (*acfssnap_create_t)(struct acfslibctx *ctx, 
                                 const oratext *snap_name, 
                                 const oratext *parent_snap,
                                 const oratext *mntpt, ub8 flags);

/* acfssnap_delete: 
*  Delete an existing ACFS snapshot
*   
*   ctx         - Pointer to a valid acfslibctx structure.
*   snap_name   - Pointer to the snapshot name that will be deleted.
*                 This can point to the absolute pathname of the snapshot; 
*                 in which case the mntpt argument is not required.
*   mntpt       - Mountpoint of the ACFS file system from which the snapshot
*                 will be deleted. This argument must be supplied if the
*                 snap_name argument is not an absolute path.
*   flags       - Unused
*   
*   Return value - 
*       ACFS_API_SUCCESS           - Success
*       ACFS_API_OK_WARN_STOR      - Success. But some storage could not be
*                                    freed. Run FSCK/ACFSCHKDSK to free the
*                                    storage.
*       ACFS_API_ENOINIT           - Context not initialized
*       ACFS_API_EINVAL            - Invalid arguments.
*       ACFS_API_RETRY             - Conflicting operation in progress. 
*                                    Retry the operation.
*       ACFS_API_ESNAPNAME         - Invalid snapshot name
*       ACFS_API_ENOSNAPEXIST      - Snapshot name doesn't exist.
*       ACFS_API_EROLLING          - Cannot delete snapshots during rolling
*                                    migration
*       ACFS_API_EREMOTE           - Remote node failure. Check logs on
*                                    other nodes for more information.
*       ACFS_API_EOPEN             - Open references on the snapshot
*       ACFS_API_FAIL              - OS dependent failure. 
*                                    See acfslib_getlasterr()
*/
sb8 acfssnap_delete(struct acfslibctx *ctx, const oratext *snap_name, 
                    const oratext *mntpt, ub8 flags);

typedef sb8 (*acfssnap_delete_t)(struct acfslibctx *ctx, 
                                 const oratext *snap_name, 
                                 const oratext *mntpt, ub8 flags);

/* acfssnap_convert: 
*  Converts an existing ACFS snapshot between read-only and read-write.
*   
*   ctx         - Pointer to a valid acfslibctx structure.
*   snap_name   - Pointer to the snapshot name that will be converted. 
*   mntpt       - Mountpoint of the ACFS file system from which the snapshot
*                 will be converted
*   flags       - Flags:
*                 ACFS_SNAP_RW - Convert to a read-write snapshot
*                 ACFS_SNAP_RO - Convert to a read-only snapshot
*                 * One of the above flags must be specified.
*   
*   Return value - 
*       ACFS_API_SUCCESS           - Success
*       ACFS_API_ENOINIT           - Context not initialized
*       ACFS_API_EINVAL            - Invalid arguments
*       ACFS_API_ESNAPEXIST        - Snapshot is already at the specified
*                                    mode
*       ACFS_API_RETRY             - Conflicting operation in progress
*                                    Retry the operation
*       ACFS_API_EREPLSNAP         - Cannot convert snapshot used for
*                                    ACFS replication
*       ACFS_API_ESNAPNAME         - Invalid snapshot name
*       ACFS_API_ENOSNAPEXIST       - Snapshot name doesn't exist
*       ACFS_API_ENOTSUP           - Snapshot not supported with
*                                    compatible.advm < 12.1
*       ACFS_API_EOSVERS           - Not supported on this OS version
*       ACFS_API_EREMOTE           - Remote node failure. Check logs on
*                                    other nodes for more information.
*       ACFS_API_FAIL              - OS dependent failure. 
*                                    See acfslib_getlasterr()
*/
sb8 acfssnap_convert(struct acfslibctx *ctx, const oratext *snap_name, 
                     const oratext *mntpt, ub8 flags);

typedef sb8 (*acfssnap_convert_t)(struct acfslibctx *ctx,
                                  const oratext *snap_name, 
                                  const oratext *mntpt, ub8 flags);

/* acfssnap_rename: 
*  Renames an existing ACFS snapshot.
*   
*   ctx           - Pointer to a valid acfslibctx structure.
*   snap_name     - Pointer to the snapshot name that will be renamed. 
*   snap_new_name - Pointer to the new snapshot name. 
*   mntpt         - Mountpoint of the ACFS file system from which the snapshot
*                   will be converted
*   
*   Return value - 
*       ACFS_API_SUCCESS           - Success
*       ACFS_API_ENOINIT           - Context not initialized
*       ACFS_API_EINVAL            - Invalid arguments
*       ACFS_API_ESNAPEXIST        - Snapshot is already at the specified
*                                    mode
*       ACFS_API_RETRY             - Conflicting operation in progress
*                                    Retry the operation
*       ACFS_API_EREPLSNAP         - Cannot rename snapshot used for
*                                    ACFS replication
*       ACFS_API_ESNAPNAME         - Invalid snapshot name
*       ACFS_API_ENOSNAPEXIST      - Snapshot name doesn't exist
*       ACFS_API_EOSVERS           - Not supported on this OS version
*       ACFS_API_EREMOTE           - Remote node failure. Check logs on
*                                    other nodes for more information.
*       ACFS_API_FAIL              - OS dependent failure. 
*                                    See acfslib_getlasterr()
*/

sb8 acfssnap_rename(struct acfslibctx *ctx, const oratext *snap_name,
                     const oratext *snap_new_name,  
                     const oratext *mntpt_in);
typedef sb8 (*acfssnap_rename_t)(struct acfslibctx *ctx,
                                  const oratext *snap_name, 
                                  const oratext *snap_new_name, 
                                  const oratext *mntpt);

/*
 *  acfs_snapinfo (version 1):
 *  Structure returned by acfssnap_next() when opening the ACFS snapshot
 *  stream via acfssnapinfo_open(). Should this structure change, a new
 *  version will be created that indicates the proper information to return
 *  to the caller.
 */
#define ACFSNAPINFO_VERS_1 ((ub4)1)

typedef struct _acfs_snapinfo
{
    /* Snapshot name */
    oratext    *acfs_snapname;

    /* Parent snapshot name.
     * This will be the ACFS file system mount point if the snapshot
     * is not the child of another snapshot. */
    oratext    *acfs_parentsnapname;

    ub8         acfs_snapflags;

/* This snapshot is a read-write snapshot.
 * If this flag is not set, this snapshot is read-only. */
#define ACFS_SNAPFLG_RW               0x1

/* The snapshot is used for ACFS replication */
#define ACFS_SNAPFLG_REPLICATION      0x2

/* The snapshot is currently being deleted */
#define ACFS_SNAPFLG_DEL_IN_PROGRESS  0x4

/* The snapshot has open references on it and will be deleted when all
 * references are closed */
#define ACFS_SNAPFLG_OPEN_DELETE      0x8

   /* Time the snapshot was created. 
    * Represented as the number of seconds since Epoch 1/1/1970 */
    ub8         acfs_snapctime;
   /* Byte size of the storage allocated by the snap */
    ub8         acfs_snap_storageusage;
   /* Byte size of the storage allowed to be allocated by the snap */
    ub8         acfs_snap_quota;
    /* Unused padding */
    ub8         acfs_snappad[2];
} acfs_snapinfo;


/* acfssnapinfo_open: 
*  Opens an ACFS snapshot stream for the purpose of iterating through the
*  list of snapshots on a given ACFS file system.
*     
*   ctx         - Pointer to a valid acfslibctx structure.
*   mntpt       - Mountpoint of the ACFS file system from which to iterate
*                 through the list of snapshots
*   version     - Version of the ACFS snapinfo structure returned.
*                 Currently, only ACFSNAPINFO_VERS_1 is valid.
*   flags       - Unused
*      
*   Return value - 
*       ACFS_API_SUCCESS           - Success
*       ACFS_API_ENOINIT           - Context not initialized
*       ACFS_API_EINVALVERS        - Invalid version
*       ACFS_API_EINVAL            - Invalid arguments
*       ACFS_API_EOPEN             - A snapshot stream is already open.
*       ACFS_API_ENOMEM            - Insufficient memory
*       ACFS_API_RETRY             - Conflicting operation in progress
*                                    Retry the operation
*       ACFS_API_FAIL              - OS dependent failure. 
*                                    See acfslib_getlasterr()
*/
sb8 acfssnapinfo_open(struct acfslibctx *ctx, const oratext *mntpt, 
                      ub4 version, ub8 flags);

typedef sb8 (*acfssnapinfo_open_t)(struct acfslibctx *ctx, const oratext *mntpt,
                                   ub4 version, ub8 flags);


/* acfssnapinfo_next: 
*  Retrieves the next ACFS snapshot in the stream created by
*  acfssnap_open(). On success, the 'snap_info' structure will be filled in
*  with the snapshot information.
*      
*   ctx         - Pointer to a valid acfslibctx structure.
*   snap_info   - Pointer to a caller supplied buffer of the acfs_snapinfo
*                 structure. When ACFS_API_SUCCESS is returned, this will
*                 point to the next snapshot in the file system.
*
*   Return value - 
*       ACFS_API_SUCCESS           - Success
*       ACFS_API_EDONE             - All snapshots have been consumed
*       ACFS_API_ENOINIT           - Context not initialized
*       ACFS_API_EINVAL            - Invalid arguments
*/
sb8 acfssnapinfo_next(struct acfslibctx *ctx, void *snap_info);

typedef sb8 (*acfssnapinfo_next_t)(struct acfslibctx *ctx, void *snap_info);

/* acfssnapinfo_close: 
*  Close the ACFS snapshot stream created by acfssnap_create().
*
*   ctx         - Pointer to a valid acfslibctx structure.
*
*   Return value - 
*       ACFS_API_SUCCESS           - Success
*       ACFS_API_ENOINIT           - Context not initialized
*                                    or acfssnapinfo_open() not called 
*                                    successfully.
*/
sb8 acfssnapinfo_close(struct acfslibctx *ctx);

typedef sword (*acfssnapinfo_close_t)(struct acfslibctx *ctx);

/* acfssnap_quota: 
 * set a quota limit for an existing ACFS snapshot.
 *    
 *    ctx         - Pointer to a valid acfslibctx structure.
 *    snap_name   - Pointer to the snapshot name that will be converted. 
 *    mntpt       - Mountpoint of the ACFS file system from which the snapshot
 *                  will be converted
 *    snap_quota  - the quota value for the snap, in bytes. 
 *    flags       - Flags:
 *    
 *    Return value - 
 *        ACFS_API_SUCCESS           - Success
 *        ACFS_API_ENOINIT           - Context not initialized
 *        ACFS_API_EINVAL            - Invalid arguments
 *        ACFS_API_RETRY             - Conflicting operation in progress
 *                                     Retry the operation
 *        ACFS_API_ESNAPNAME         - Invalid snapshot name
 *        ACFS_API_ENOSNAPEXIST      - Snapshot name doesn't exist
 *        ACFS_API_ENOTSUP           - Snapshot not supported with
 *                                     compatible.advm < 12.1
 *                                     other nodes for more information.
 *        ACFS_API_FAIL              - OS dependent failure. 
 *                                     See acfslib_getlasterr()
 */
sb8 acfssnap_quota(struct acfslibctx *ctx, const oratext *snap_name,
                     const oratext *mntpt, const ub8 snap_quota, ub8 flags);

typedef sb8 (*acfssnap_quota_t)(struct acfslibctx *ctx,
                                  const oratext *snap_name,
                                  const oratext *mntpt, 
                                  const ub8 snap_quota, ub8 flags);

#ifdef __cplusplus
}
#endif

#endif                                              /* ACFSLIB_ORACLE */