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;
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. |