fskv_reg Kernel Service

Purpose

Registers callout handlers for validation of file system operations.

Syntax


       #include <sys/xfops.h>

       int fskv_reg(fskv_t *fs_kv, ulong options);

       typedef struct fskv {
              int version_number;
              int (*kv_open)(struct xfid *xfp,
                                   long flags,
                                   cred_ext_t *crxp);
              int (*kv_setattr)(struct xfid *xfp,
                                   long op,
                                   long arg1,
                                   long arg2,
                                   long arg3,
                                   cred_ext_t *crxp);
       } fskv_t;

Parameters

fs_kv: Specifies an array of callout functions that are called to validate file system operations in the kernel.
options: Specifies a bit mask of registration options. The options parameter is not defined currently. The caller must set the options parameter to 0.

Description

The fskv_reg kernel service registers an array of functions that are called before the execution of file system-specific operations.

After a callout handler is registered, each of the affected operations is preceded by a call to the corresponding validation routine.

Only one callout array can be registered. After a callout array is registered with the fskv_reg kernel service, the subsequent invocation of the fskv_reg kernel service does not succeed until the fskv_unreg kernel service is called. The caller of the fskv_reg kernel service must have root authority.

Execution environment

The fskv_reg kernel service can be called only from the process environment.

Return values

On successful completion, the fskv_reg kernel service returns a value of 0.

The following error codes can be returned on failure:

EEXIST: The callout array is already registered.
EPERM: The caller does not have permission to invoke this function.
EINVAL: A parameter is invalid.

Callout handlers

Callouts can be specified for the open, chmod, chown, and utimes system calls. The chmod, chown, and utimes system calls are handled in a single operation in the kernel with the setattr call.

If the validation callout routine returns a nonzero value, the file system operation is stopped and the system call returns the EPERM value.

The validation routines are called only for local physical file systems (JFS2 and JFS) and network file system (NFS)-mounted file systems. The callout functions accept the following arguments. The xfid argument uniquely identifies the file within the current running system.

   typedef struct xfid {
          fsid_t x_fsid;
          fid_t x_fid;
   } xfid_t;

kv_open() callout function

The kv_open callout function contains the information that is available to the open routines of the file system to track and validate open calls.

Syntax

#include <sys/file.h>
#include <sys/cred.h>

int    (*kv_open)(struct xfid *xfp,
          long flags,
          void *nrp,
          cred_ext_t *crxp);

Parameters

xfp: Pointer to an xfid structure that identifies the file system and object.
nrp: Name resolution information. If the xfidToName kernel service is called, this parameter must be passed to it. This pointer is not valid after it is returned from the callout function.
flags: Open flags that are passed by the application.
crxp: Pointer to the credentials for the calling process.

Return values

Zero: Indicates that the validation completed successfully.
Nonzero: Indicates that the validation failed.

kv_setattr() callout function

The kv_setattr callout function contains the information that is available to the system call that initiated this function. The setattr function is called by the chown, chmod, and utimes system calls and the variants of those system calls (for example, fchown, fchmod, and futimens system calls).

Syntax

#include <sys/vattr.h>
#include <sys/cred.h>

int (*kv_setattr)(struct xfid *xfp,
          long op,
          long arg1,
          long arg2,
          long arg3,
          void *nrp,
          cred_ext_t *crxp);

Parameters

xfp

Pointer to an xfid structure that identifies the file system and object.

op

Specifies one of the following operations:

V_OWN: Sets file ownership.
V_MODE: Sets file mode.
V_UTIME: Sets the file time specified by the user.
V_STIME: Sets the file time requested by the system.

argn

Specifies the following values for each of the listed operations.

Table 1. kv_setattr() callout function: argn parameter values
Operations	arg1	arg2	arg3
V_OWN	flag: `T_OWNER_AS_IS T_GROUP_AS_IS` (For information about the file ownership changes, see chownx subroutine.)	`uid_t newuid`	`gid_t newgid`
V_MODE	`mode_t newmode`	Unused	Unused
V_UTIME	flag: `V_SETTIME` Ignore arguments and set time to the current time.	`timestruct_t *atime` Set the access time.	`timestruct_t *mtime` Set the modification time.
V_STIME	`NULL` or `timestruct_t *atime` Set the access time.	`NULL` or `timestruct_t *mtime` Set the modification time.	`NULL` or `timestruct_t *ctime` Set the change time.

nrp

Indicates the name resolution information. If the xfidToName kernel service is called, this parameter must be passed to it. This parameter is a pointer to temporary information that is not valid after it is returned from the validation routine.

crxp

Pointer to credentials for the calling process.

Return values

Zero: Indicates that the validation completed successfully.
Nonzero: Indicates that the validation failed.