srcsbuf_r 子例程

用途

获取子服务器或子系统的状态，并返回要打印的状态文本。

库

系统资源控制器库 (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;

描述

srcsbuf_r 子例程获取子服务器或子系统的状态，并返回 StatusText 参数指向的地址中状态的可打印文本。 srcsbuf_r 子例程支持 srcbuf 子例程的所有函数，但 StatusFrom 参数除外。

当 StatusType 参数为 SHORTSTAT 且 Type 参数为 SUBSYSTEM时，将调用 srcstat_r 子例程以获取一个或多个子系统的状态。当 StatusType 参数为 LONGSTAT 且 Type 参数为 SUBSYSTEM时，将调用 srcrsqt_r 子例程以获取一个子系统的长状态。当 Type 参数不是 SUBSYSTEM时，将调用 srcsrqt_r 子例程以获取子服务器的长或短状态。

此例程是线程安全且可重入的例程。

参数

项	描述
主机	指定要求在其上进行状态操作的外部主机。如果主机为空，那么会将状态请求发送到本地主机上的系统资源控制器 (SRC)。
TYPE	指定状态请求是应用于子系统还是子服务器。如果 Type 参数设置为 SUBSYSTEM，那么状态请求针对子系统。如果没有，那么状态请求是针对子服务器的，而 Type 参数是子服务器代码点。
SubsystemName	指定要在其上获取状态的子系统的名称。要获取所有子系统的状态，请使用 SRCALLSUBSYS 常量。要获取子系统组的状态， SubsystemName 参数必须以 SRCGROUP 常量开头，后跟要为其附加状态的组的名称。如果指定空 SubsystemName 参数，那么必须指定 SubsystemPID 参数。
SubserverObject	指定子服务器对象。 SubserverObject 参数修改 Type 参数。如果 Type 参数设置为 SUBSYSTEM，那么将忽略 SubserverObject 参数。 SubserverObject 参数的使用由子系统和调用者确定。此参数将放置在`objname`传递到子系统的 subreq 结构的字段。
SubsystemPID	指定要在其上获取状态的子系统的进程标识，如 srcstrt 子例程所返回。如果子系统的多个实例处于活动状态并且您请求长子系统状态或子服务器状态，那么必须指定 SubsystemPID 参数。如果指定空 SubsystemPID 参数，那么必须指定 SubsystemName 参数。
StatusType	指定 LONGSTAT (对于长状态) 或 SHORTSTAT (对于短状态)。
StatusFrom	指定是将状态错误和消息打印到标准输出还是仅返回到调用者。当 StatusFrom 参数为 SSHELL时，会将错误打印到标准输出。在多线程环境中不建议使用 SSHELL 值，因为可能会以意外方式将错误消息交错到标准输出。
StatusText	为可打印文本分配内存，并将 StatusText 参数设置为指向此内存。在打印文本之后，调用进程必须释放为此缓冲区分配的内存。
已继续	指定对 srcsbuf_r 子例程的此调用是否是状态请求的延续。如果 Continued 参数设置为 NEWREQUEST，那么将发送状态请求，然后 srcsbuf_r 子例程等待应答。从 srcsbuf_r 子例程返回时， Continued 参数将更新为来自应答包的新的延续指示符。子系统将应答包中的连续指示符设置为 END 或 STAT续。如果将 Continued 参数设置为除 END以外的值，那么调用者不应更改该值; 否则，此函数将无法接收更多用于原始状态请求的信息包。调用进程不应将 Continued 参数的值设置为 NEWREQUEST以外的值。在正常处理中，当期望更多响应时，不应更改 Continued 参数。调用者必须继续调用 srcsbuf_r 子例程，直到接收到 END 为止。作为替代方法，使用 Continued=SRC_CLOSE 调用 srcsbuf_r 子例程以废弃剩余数据，关闭套接字并释放内部缓冲区。
SRCHandle	标识请求及其关联的响应。由 NEWREQUEST的调用者设置为 NULL。 srcsbuf_r 子例程在 SRCHandle 中保存值，以允许 srcsbuf_r 继续调用使用相同的套接字和内部缓冲区。除了 NEWREQUEST之外，调用者不应更改 SRCHandle 参数。

返回值

如果 srcsbuf_r 子例程成功，它将返回 StatusText 参数所指向的可打印文本的大小 (以字节计)。

错误代码

如果检测到下列其中一个错误情况，那么 srcsbuf_r 子例程将失败并返回相应的错误代码:

项	描述
SRC_BADSOCK	由于某些套接字故障，无法将请求传递到子系统。
SRC_CONT	子系统使用信号。请求无法完成。
SRC_DMNA	SRC 守护程序未处于活动状态。
src_inet_authorized_host	本地主机不在远程 /etc/hosts.equiv 文件中。
src_inet_invalid_host	在远程主机上，本地主机未知。
src_invalid_user	用户不是 root 用户或组系统。
SRC_MMRY	SRC 组件无法分配它所需的内存。
SRC_NOCONTINUE	Continued 参数未设置为 NEWREQUEST，并且当前没有活动的延续。
SRC_NORPLY	请求等待响应时超时。
SRC_NSVR	该子系统不是活动的。
SRC_SOCK	SRC 套接字通信存在问题。
SRC_STPG	该请求未传递到子系统。子系统正在停止。
SRC_UDP	在 /etc/services 文件中未定义 SRC 端口。
SRC_UHOST	外部主机未知。
SRC_WICH	有多个子系统实例处于活动状态。

示例

要获取子系统的状态，请输入:

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

这将获得简短的状态srctest子系统MaryC并将格式化状态打印到标准输出。

注意: 在多线程环境中，调用者必须管理线程之间的标准输出共享。将 StatusFrom 参数设置为 SDAEMON ，以防止将意外错误消息打印到标准输出。

要获取子服务器的状态，请输入:
```
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...
}
  
```
这将获取属于子系统的特定子服务器的长状态srctest. 子服务器是具有代码点的子服务器12345. 此请求在本地机器上进行处理。格式化状态将打印到标准输出。

警告：
在多线程环境中，调用者必须管理线程之间标准输出的共享。将 StatusFrom 参数设置为 SDAEMON ，以防止将意外错误消息打印到标准输出。