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