srcstop Subroutine

Purpose

Stops a System Resource Controller (SRC) subsystem.

Library

System Resource Controller Library (libsrc.a)

Syntax

#include <spc.h>

srcstop(Host, SubsystemName, SubsystemPID, StopType)
srcstop(ReplyLength, ServerReply, StopFrom)
char * Host, * SubsystemName;
int  SubsystemPID,  StopFrom;
short  StopType, * ReplyLength;
struct srcrep * ServerReply;

Description

The srcstop subroutine sends a stop subsystem request to a subsystem and waits for a stop reply from the System Resource Controller (SRC) or the subsystem. The srcstop subroutine can only stop a subsystem that was started by the SRC.

Parameters

Item Description
Host Specifies the foreign host on which this stop action is requested. If the host is the null value, the request is sent to the SRC on the local host. The local user must be running as "root". The remote system must be configured to accept remote System Resource Controller requests. That is, the srcmstr daemon (see /etc/inittab) must be started with the -r flag and the /etc/hosts.equiv or .rhosts file must be configured to allow remote requests.
SubsystemName Specifies the name of the subsystem to stop.
SubsystemPID Specifies the process ID of the system to stop as returned by the srcstrt subroutine. If you specify a null SubsystemPID parameter, you must specify a SubsystemName parameter.
StopType Specifies the type of stop requested of the subsystem. If this parameter is null, a normal stop is assumed. The StopType parameter must be one of the following values:
CANCEL
Requires a quick stop of the subsystem. The subsystem is sent a SIGTERM signal. After the wait time defined in the subsystem object, the SRC issues a SIGKILL signal to the subsystem. This waiting period allows the subsystem to clean up all its resources and terminate. The stop reply is returned by the SRC.
FORCE
Requests a quick stop of the subsystem and all its subservers. The stop reply is returned by the SRC for subsystems that use signals and by the subsystem for other communication types.
NORMAL
Requests the subsystem to terminate after all current subsystem activity has completed. The stop reply is returned by the SRC for subsystems that use signals and by the subsystem for other communication types.
ReplyLength Specifies the maximum length, in bytes, of the stop reply. On return from the srcstop subroutine, this field is set to the actual length of the subsystem reply packet received.
ServerReply Points to an svrreply structure that will receive the subsystem stop reply.
StopFrom Specifies whether the srcstop subroutine is to display stop results to standard output. If the StopFrom parameter is set to SSHELL, the stop results are displayed to standard output and the srcstop subroutine returns successfully. If the StopFrom parameter is set to SDAEMON, the stop results are not displayed to standard output, but are passed back to the caller.

Return Values

Upon successful completion, the srcstop subroutine returns SRC_OK or SRC_STPOK.

Error Codes

The srcstop subroutine fails if one or more of the following are true:

Item Description
SRC_BADFSIG The stop force signal is an invalid signal.
SRC_BADNSIG The stop normal signal is an invalid signal.
SRC_BADSOCK The stop request could not be passed to the subsystem on its communication socket.
SRC_DMNA The SRC daemon is not active.
SRC_INET_AUTHORIZED_HOST The local host is not in the remote /etc/hosts.equiv file.
SRC_INET_INVALID_HOST On the remote host, the local host is not known.
SRC_INVALID_USER The user is not root or group system.
SRC_MMRY An SRC component could not allocate the memory it needs.
SRC_NORPLY The request timed out waiting for a response.
SRC_NOTROOT The SRC daemon is not running as root.
SRC_SOCK There is a problem with SRC socket communications.
SRC_STPG The request was not passed to the subsystem. The subsystem is stopping.
SRC_SVND The subsystem is unknown to the SRC daemon.
SRC_UDP The remote SRC port is not defined in the /etc/services file.
SRC_UHOST The foreign host is not known.
SRC_PARM Invalid parameter passed.

Examples

  1. To stop all instances of a subsystem, enter: 
    int rc;
struct svrreply svrreply;
short replen=sizeof(svrreply);
 
rc=srcstop("MaryC","srctest",0,FORCE,&replen,&svrreply,SDAEMON);

    This request stops a subsystem with a stop type of FORCE for all instances of the subsystem srctest on the MaryC machine and does not print a message to standard output about the status of the stop.

  2. To stop a single instance of a subsystem, enter: 
    struct svrreply svrreply;
short replen=sizeof(svrreply);
 
rc=srcstop("","",999,CANCEL,&replen,&svrreply,SSHELL);
    This request stops a subsystem with a stop type of CANCEL, with the process ID of 999 on the local machine and prints a message to standard output about the status of the stop.

Files

Item Description
/etc/services Defines sockets and protocols used for Internet services.
/dev/SRC Specifies the AF_UNIX socket file.
/dev/.SRC-unix Specifies the location for temporary socket files.