dsstate
Purpose
Controls the kernel operations related to Distributed
Services.
Syntax
#include <sys/dsstate.h>
int dsstate (buf)
struct dsstate *buf;
Description
The dsstate system call controls the kernel operations
related to Distributed Services. A process with an
effective user ID of superuser can use the dsstate system
call to change the state of the kernel, while a process
that does not have superuser privileges can use it to
query the state of the kernel. The buf parameter is a
pointer to a structure of type ds_state. This structure
is defined in the sys/dsstate.h header file, and it con-
tains the following members:
short i_state; /* input state */
short i_kprocs; /* input number of kprocs */
short r_state; /* result state */
short r_kprocs; /* result number of kprocs */
int reserved[4| /* reserved */
/* each element must be zero */
The following bits are valid in the i_state bit field:
DS_START_SERV_SYNC Causes updates to all files for
which this node is a server to be
written directly to the server,
rather than to storage at the
client node. All writes to files
are sent to this file server, and
all reads from files are provided
by the server.
DS_END_SERV_SYNC Allows clients of this node to
store data instead of forcing all
storage to take place on the
server node.
DS_START_CLIENT_SYNC Causes updates to all files for
which this node is a client to be
written directly to the server,
rather than to local storage. All
writes to files are sent to the
file server, and all reads from
files are provided by the server.
When CLIENT_SYNC is first started,
all data stored at the client
(local node) is written to the
server where each remote file
resides, and dsstate does not
return until these writes are fin-
ished.
DS_END_CLIENT_SYNC Allows some data to be stored at
the local node, rather than proc-
essing all reads and writes
through the server.
DS_BLOCK_SERV Causes this server to reject all
requests for file services,
including both new requests and
requests for files already in use.
When BLOCK_SERV is entered, this
server forces any data stored on
client nodes to be written to the
server before any server requests
are rejected.
DS_ALLOW_SERV Allows this server to accept
requests for file services from
other nodes.
DS_BLOCK_ALL Causes all data from this client
node to be written to the appro-
priate server, then breaks all
existing connections with remote
nodes and rejects new remote
requests. DS_BLOCK_ALL sets the
number of kernel processes to 0.
DS_ALLOW_ALL Allows remote requests. Con-
nections with remote nodes can
then be established as needed.
DS_STARTK Starts the kernel processes for
Distributed Services. DS_STARTK
must be set the first time the
dsstate system call is used, and
other fields can either be set at
the same time or with later calls.
The i_kprocs field sets the number of active Distributed
Services kernel processes. If the value of i_kprocs
exceeds the number of kernel processes allocated to Dis-
tributed Services when the system was initialized, then
only the available processes are started. If i_kprocs is
0 or negative, then the number of active kernel processes
is not changed. (To alter the state bits without
changing the number of kernel processes, set i_kprocs to
0.) If i_kprocs is greater than 0, either DS_STARTK must
be set with this dsstate system call or must have been
set by an earlier dsstate call.
The bits of the r_state field are set to indicate the
state of the kernel after the dsstate system call has
taken effect. The following bits are returned:
ALLOW_ALL When set, this node can make file service
requests of other nodes.
ALLOW_SERV When set, this node can accept requests for
file services from other nodes.
CLIENT_SYNC When set, all files for which this node is
a client are written directly to the
server, rather than stored locally.
SERVER_SYNC When set, all data for which this node is a
server is written directly to the server,
rather than stored at the client node.
STARTK When set, the Distributed Services kernel
processes, if any were specified in
i_kprocs, are started.
DSINITED When set, the Distributed Services kernel
processes have been started. The setting
of this bit is always the same as the
STARTK bit.
If i_state does not have either bit set for a given pair
of values (such as DS_BLOCK_ALL and DS_ALLOW_ALL), then
the current state of that pair is not altered and is
returned in r_state. Otherwise, r_state contains the
value that was set on the last call to dsstate.
The default state for the BLOCK/ALLOW pairs is to ALLOW
requests, while the default for the START_SYNC/END_SYNC
pairs is END_SYNC.
The r_kprocs field is set to indicate the number of
kernel processes after the dsstate system call has taken
effect.
If the effective user ID of the calling process is not
superuser, then dsstate ignores i_state and i_kprocs, and
the current state remains unaltered. A process without
superuser privileges can, however, determine the current
kernel state by examining the contents of r_state and
r_kprocs at the end of a dsstate system call.
Return Value
Upon successful completion, the dsstate system call
returns a value of 0. If the dsstate system call fails,
a value of -1 is returned, and errno is set to indicate
the error.
Diagnostics
The dsstate system call fails and the state and number of
kernel processes remain unchanged if the following is
true:
EINVAL Invalid input data (such as mutually exclusive
parameters).
ENOMEM Not enough kernel processes are available to
run Distributed Services.
Related Information
In this book: "master."
Managing the AIX Operating System.