__must_stay_clean() — Enable or query clean
Standards
Standards / Extensions | C or C++ | Dependencies |
---|---|---|
z/OS® UNIX |
both | Z/OS V1R8 |
Format
#define _OPEN_SYS
#include <unistd.h>
int __must_stay_clean(int request);
General description
The __must_stay_clean() function queries or enables the "must stay clean" state for a process. A process that must stay clean is prohibited from doing an exec(), spawn(), or other load of a non-program controlled executable. Only a program controlled executable can enable the must stay clean state. The must stay clean state of a process is propagated to its children created using fork or spawn. Once the must stay clean state is enabled, it cannot be changed. All processes in the address space will be forced to stay clean until they have all terminated. The query support allows a process to determine if it was created in a trusted environment. The BPX.DAEMON class profile must be defined to use the enable function.
- Argument
- Description
- request
- Specify the value _MSC_QUERY to query the state. Specify the value _MSC_ENABLE to enable "must stay clean" for the process.
Returned value
If successful, __must_stay_clean() returns the current "must stay clean" state of the process. The following state values are possible:
- _MSC_NOT_ENABLED
- The "must stay clean" state is not enabled.
- _MSC_ENABLED
- The "must stay clean" state is enabled, meaning that it was set using this function, and that it will continue to be enabled even after an exec() that causes job step termination.
- _MSC_ENABLED_COND
- The "must stay clean" state is enabled conditionally, meaning that a prior call to a security service, such as __passwd(), implicitly enabled the must stay clean state, and that the state will be reset to "not enabled" at the next exec() that causes job step termination. This state value can only be returned using the query request.
- Error Code
- Description
- EINVAL
- A parameter was not valid.
- EMVSERR
- An MVS™ environmental error occurred. One possible cause is that a 'dirty' process attempted to enable the must stay clean attribute. Another cause could be that the BPX.DAEMON class profile is not defined.
- EMVSSAF2ERR
- An error occurred in the security product.
Example
/* celebm22.c */
/* This example shows how to use __must_stay_clean() to request */
/* the environment is to "stay clean" until all processes in the */
/* address space are terminated. */
/* Requirements: */
/* 1. The environment must already be clean, noting that the */
/* program issuing the request must be program-controlled */
/* 2. BPX.DAEMON must be defined */
#define _OPEN_SYS
#include <unistd.h>
#include <errno.h>
#include <stdio.h>
#include <stdlib.h>
int main(void){
int rc;
rc = __must_stay_clean(_MSC_ENABLE); /* Stay Clean! */
if (rc == __MSC_FAILED){
perror("could not enable must stay clean");
printf("errno=%d errno2=%08x\n",errno,__errno2());
exit(1);
}
return 0;
}