srcstop Subroutine

AIX Version 4.3 Base Operating System and Extensions Technical Reference, Volume 2

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

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:

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

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

Implementation Specifics

This subroutine is part of Base Operating System (BOS) Runtime.

Files

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

Related Information

The srcrrqs subroutine, srcsbuf subroutine, srcsrpy subroutine, srcsrqt subroutine, srcstat subroutine, srcstathdr subroutine, srcstattxt subroutine, srcstrt subroutine.

List of SRC Subroutines in AIX Version 4.3 General Programming Concepts: Writing and Debugging Programs.

Programming Subsystem Communication with the SRC in AIX Version 4.3 General Programming Concepts: Writing and Debugging Programs.

System Resource Controller (SRC) Overview for Programmers in AIX Version 4.3 General Programming Concepts: Writing and Debugging Programs.