Gets status for a subserver or a subsystem and returns status text to be printed.
System Resource Controller Library (libsrc.a)
#include <spc.h>
int srcsbuf_r(Host, Type, SubsystemName, SubserverObject, SubsystemPID,
StatusType, StatusFrom, StatusText, Continued, SRCHandle)
char * Host, * SubsystemName;
char * SubserverObject, ** StatusText;
short Type, StatusType;
pid_t SubsystemPID;
int StatusFrom * Continued;
char ** SRCHandle;
The srcsbuf_r subroutine gets the status of a subserver or subsystem and returns printable text for the status in the address pointed to by the StatusText parameter. The srcsbuf_r subroutine supports all the functions of the srcbuf subroutine except the StatusFrom parameter.
When the StatusType parameter is SHORTSTAT and the Type parameter is SUBSYSTEM, the srcstat_r subroutine is called to get the status of one or more subsystems. When the StatusType parameter is LONGSTAT and the Type parameter is SUBSYSTEM, the srcrsqt_r subroutine is called to get the long status of one subsystem. When the Type parameter is not SUBSYSTEM, the srcsrqt_r subroutine is called to get the long or short status of a subserver.
This routine is threadsafe and reentrant.
Item | Description |
---|---|
Host | Specifies the foreign host on which this status action is requested. If the host is null, the status request is sent to the System Resource Controller (SRC) on the local host. |
Type | Specifies whether the status request applies to the subsystem or subserver. If the Type parameter is set to SUBSYSTEM, the status request is for a subsystem. If not, the status request is for a subserver and the Type parameter is a subserver code point. |
SubsystemName | Specifies the name of the subsystem on which to get status. To get the status of all subsystems, use the SRCALLSUBSYS constant. To get the status of a group of subsystems, the SubsystemName parameter must start with the SRCGROUP constant, followed by the name of the group for which you want status appended. If you specify a null SubsystemName parameter, you must specify a SubsystemPID parameter. |
SubserverObject | Specifies a subserver object. The SubserverObject parameter modifies the Type parameter. The SubserverObject parameter is ignored if the Type parameter is set to SUBSYSTEM. The use of the SubserverObject parameter is determined by the subsystem and the caller. This parameter will be placed in the objname field of the subreq structure that is passed to the subsystem. |
SubsystemPID | Specifies the process ID of the subsystem on which to get status, as returned by the srcstrt subroutine. You must specify the SubsystemPID parameter if multiple instances of the subsystem are active and you request a long subsystem status or subserver status. If you specify a null SubsystemPID parameter, you must specify a SubsystemName parameter. |
StatusType | Specifies LONGSTAT for long status or SHORTSTAT for short status. |
StatusFrom | Specifies whether status errors and messages are to be printed to standard output or just returned to the caller. When the StatusFrom parameter is SSHELL, the errors are printed to standard output. The SSHELL value is not recommended in a multithreaded environment since error messages to standard output may be interleaved in an unexpected manner. |
StatusText | Allocates memory for the printable text and sets the StatusText parameter to point to this memory. After it prints the text, the calling process must free the memory allocated for this buffer. |
Continued | Specifies whether this call to the srcsbuf_r subroutine is a continuation of a status request. If the Continued parameter is set to NEWREQUEST, a request for status is sent and the srcsbuf_r subroutine then waits for a reply. On return from the srcsbuf_r subroutine, the Continued parameter is updated to the new continuation indicator from the reply packet. The continuation indicator in the reply packet will be set to END or STATCONTINUED by the subsystem. If the Continued parameter is set to something other than END, the caller should not change that value; otherwise, this function will not be able to receive any more packets for the original status request. The calling process should not set the value of the Continued parameter to a value other than NEWREQUEST. In normal processing, the Continued parameter should not be changed while more responses are expected. The caller must continue to call the srcsbuf_r subroutine until END is received. As an alternative, call the srcsbuf_r subroutine with Continued=SRC_CLOSE to discard the remaining data, close the socket, and free the internal buffers. |
SRCHandle | Identifies a request and its associated responses. Set to NULL by the caller for a NEWREQUEST. The srcsbuf_r subroutine saves a value in SRCHandle to allow srcsbuf_r continuation calls to use the same socket and internal buffers. The SRCHandle parameter should not be changed by the caller except for NEWREQUESTs. |
If the srcsbuf_r subroutine succeeds, it returns the size (in bytes) of printable text pointed to by the StatusText parameter.
The srcsbuf_r subroutine fails and returns the corresponding error code if one of the following error conditions is detected:
Item | Description |
---|---|
SRC_BADSOCK | The request could not be passed to the subsystem because of some socket failure. |
SRC_CONT | The subsystem uses signals. The request cannot complete. |
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_NOCONTINUE | The Continued parameter was not set to NEWREQUEST, and no continuation is currently active. |
SRC_NORPLY | The request timed out waiting for a response. |
SRC_NSVR | The subsystem is not active. |
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_UDP | The SRC port is not defined in the /etc/services file. |
SRC_UHOST | The foreign host is not known. |
SRC_WICH | There are multiple instances of the subsystem active. |
char *status;
int continued=NEWREQUEST;
int rc;
char *handle
do {
rc=srcsbuf_r("MaryC", SUBSYSTEM, "srctest", "", 0,
SHORTSTAT, SDAEMON, &status, continued, &handle);
if (status!=0)
{
printf(status);
free(status);
status=0;
}
} while (rc>0);
if (rc<0)
{
...handle error from srcsbuf_r...
}
This gets short status of the srctest subsystem on the MaryC machine and prints the formatted status to standard output.
Caution: In a multithreaded environment, the caller must manage the sharing of standard output between threads. Set the StatusFrom parameter to SDAEMON to prevent unexpected error messages from being printed to standard output.
char *status;
int continued=NEWREQUEST;
int rc;
char *handle
do {
rc=srcsbuf_r("", 12345, "srctest", "", 0,
LONGSTAT, SDAEMON, &status, continued, &handle);
if (status!=0)
{
printf(status);
free(status);
status=0;
}
} while (rc>0);
if (rc<0)
{
...handle error from srcsbuf_r...
}
This gets long status for a specific subserver belonging to subsystem srctest. The subserver is the one having code point 12345. This request is processed on the local machine. The formatted status is printed to standard output.