Symantec logo

fsckpt_cntl

NAME

fsckpt_cntl - perform control functions and Storage Checkpoint state changes

SYNOPSIS

#include <fsckpt.h>

int fsckpt_cntl(void *fshandle, char *ckptname, int op, int flags);

AVAILABILITY

VRTSvxfs

DESCRIPTION

fsckpt_cntl() performs control functions and state changes on the Storage Checkpoint specified by ckptname. fsckpt_cntl() allows the application to set or clear certain Storage Checkpoint state flags. The state flags that can be controlled are the same flags used when creating Storage Checkpoints with the fsckpt_create() function CC_NODATA , CC_NOMOUNT , and CC_REMOVE .

The op argument defines the CC_SET or CC_CLEAR action.

The flags argument specifies the Storage Checkpoint states and policies to be used in the case of ENOSPC conditions. The following flags are defined:

CC_NODATA

Converts a Storage Checkpoint to nodata. A nodata Storage Checkpoint is one that does not contain actual data. Instead, it contains a collection of markers indicating the location of all the changed blocks. After a Storage Checkpoint is CC_SET to nodata, the image at the time of creation is lost. Clearing the CC_NODATA flag is not allowed.

Conversion to nodata is asynchronous by default. Synchronous conversion waits for all files to be converted before returning to the caller. The caller can request synchronous conversion by specifying the CC_SYNC flag.

Multiple nodata Storage Checkpoints are allowed, however, the synchronous CC_SET operation fails with the EEXIST error if there is an older Storage Checkpoint which is not in the CC_NODATA state.

An asynchronous CC_SET operation will succeed and mark the Storage Checkpoint for a delayed conversion to nodata. The Storage Checkpoint will be in CC_NODATA and CC_DELAYED state. The actual conversion to nodata takes place after the Storage Checkpoint becomes the oldest existing Storage Checkpoint (all older Storage Checkpoints were removed), or if older Storage Checkpoints become nodata.

CC_NOMOUNT

Disallows mounting of Storage Checkpoints. CC_NOMOUNT also disallows a process to be in-context. The fsckpt_setcontext() function will fail on a Storage Checkpoint with the CC_NOMOUNT flag set.

CC_REMOVE

Removes a Storage Checkpoint to free up file system space and allow a writer to continue without getting ENOSPC errors. Storage Checkpoints are removed based on time of creation, with the older Storage Checkpoints being removed first. Storage Checkpoints are removed in this order until enough space is freed up to guarantee that applications do not receive an ENOSPC error.

CC_SYNC

When used with the CC_NODATA flag, CC_SYNC performs a synchronous conversion. It does not return to the caller until all of the Storage Checkpoint files are converted to nodata.

Nodata Storage Checkpoints are very useful for applications trying to retrieve data blocks changed in the file system rather than the Storage Checkpoint itself. By consulting the Storage Checkpoint for changed blocks, an application can open a primary file and read the blocks changed, thus generating a data stream containing current data which has changed since the Storage Checkpoint was created.

Nodata Storage Checkpoints are lightweight in nature, so the impact on applications and the overhead on the file system is minimal.

RETURN VALUES

fsckpt_cntl() returns zero on success, non-zero on failure.

ERRORS

EACCES

User does not have permission to perform the operation. Only privileged users can create Storage Checkpoints.

EEXIST

The Storage Checkpoint name ckptname already exists in the file system Storage Checkpoint name space.

EINVAL

The function is being used incorrectly, or the arguments to the function could not be validated. This may occur when an application tries to use an fshandle that was not created by the same process.

EIO

An I/O error occurred on the device. The Storage Checkpoint could not be loaded.

ENOENT

The specified Storage Checkpoint ckptname does not exist.

ENOSYS

The system does not have a valid license to perform the operation.

EROFS

The file system is mounted as read-only; no updates are allowed on the file system and the Storage Checkpoint cannot be modified.

SEE ALSO

fsckptadm(1M), fsckpt_create(3), fsckpt_createall(3), fsckpt_fsopen(3), fsckpt_intro(3)