fscntl Subroutine

Purpose

Controls file system control operations.

Library

Standard C Library (libc.a)

Syntax

#include <sys/types.h>
#include <j2/j2_cntl.h>
#include <sys/vmount.h>

int fscntl ( vfs_id,  Command,  Argument,   ArgumentSize)
int vfs_id;
int Command;
char *Argument;
int ArgumentSize;

Description

The fscntl subroutine performs a variety of file system-specific functions. These functions typically require root user authority.

The Enhanced Journaled File System (JFS2) supports several Command values that can be used by applications. Each of these Command values requires root authority.
FSCNTL_FREEZE
The file system specified by vfs_id is "frozen" for a specified amount of time. The act of freezing a file system produces a nearly consistent on-disk image of the file system, and writes all dirty file system metadata and user data to the disk. In its frozen state, the file system is read-only, and anything that attempts to modify the file system or its contents must wait for the freeze to end. The Argument is treated as an integral timeout value in seconds (instead of a pointer). The file system is thawed by FSCNTL_THAW or when the timeout expires. The timeout, which must be a positive value, can be renewed using FSCNTL_REFREEZE. The ArgumentSize must be 0.
Note: For all applications using this interface, use FSCNTL_THAW to thaw the file system rather than waiting for the timeout to expire. If the timeout expires, an error log entry is generated as an advisory.
FSCNTL_REFREEZE
The file system specified by vfs_id, which must be already frozen, has its timeout value reset. If the command is used on a file system that is not frozen, an error is returned. The Argument is treated as an integral timeout value in seconds (instead of a pointer). The file system is thawed by FSCNTL_THAW or when the new timeout expires. The timeout must be a positive value. The ArgumentSize must be 0.
FSCNTL_THAW
The file system specified by vfs_id is thawed. Modifications to the file system are still allowed after it is thawed, and the file system image might no longer be consistent after the thaw occurs. If the file system is not frozen at the time of the call, an error is returned. The Argument and ArgumentSize must both be 0.

The Journaled File System (JFS) supports only internal fscntl interfaces. Application programs should not call this function on a JFS file system, because fscntl is reserved for system management commands, such as the chfs command.

Parameters

Item Description
vfs_id Identifies the file system to be acted upon. This information is returned by the stat subroutine in the st_vfs field of the stat.h file.
Command Identifies the operation to be performed.
Argument Specifies a pointer to a block of file system specific information that defines how the operation is to be performed.
ArgumentSize Defines the size of the buffer pointed to by the Argument parameter.

Return Values

Upon successful completion, the fscntl subroutine returns a value of 0. Otherwise, a value of -1 is returned and the errno global variable is set to indicate the error.

Error Codes

The fscntl subroutine fails if any of the following errors are true:

Item Description
EINVAL The vfs_id parameter does not identify a valid file system.
EINVAL The Command parameter is not recognized by the file system.
EINVAL The timeout specified to FSCNTL_FREEZE or FSCNTL_REFREEZE is invalid.
EALREADY The Command parameter was FSCNTL_FREEZE and the file system specified was already frozen.
EALREADY The Command parameter was FSCNTL_REFREEZE or FSCNTL_THAW and the file system specified was not frozen.