safmgr.h File Reference

ESF Manager Startup and Control definitions. More...

Data Structures
struct	SafInit
	ESF Manager Initialization Control Block. More...
Defines
#define	SafMGR_H
#define	SafESM_MAX 8
	Maximum number of ESM Modules.
#define	SafMGR_API_VER 1
	Current API version.
#define	SafENV_CAS 0
	Executing under CAS w/o MTO.
#define	SafENV_MFDS (1<< 0)
	Executing under MFDS.
#define	SafENV_CICS (1<< 1)
	Executing under CAS w/ CICS.
#define	SafENV_IMS (1<< 2)
	Executing under CAS w/ IMS.
#define	SafENV_JES (1<< 3)
	Executing under CAS w/ IMS.
#define	SafENV_SOLO (1ul<<31)
	Executing standalone.
#define	SafENV_MTOMASK 0x0eul
	Mask for MTO personalities.
#define	SafMGR_FAIL_NONE 0
	No failure.
#define	SafMGR_FAIL_GENERAL 1
	Error with no specific code.
#define	SafMGR_FAIL_RESOURCE 2
	Resource allocation failed.
#define	SafMGR_FAIL_MGRCFG 3
	Bad ESF Manager configuration.
#define	SafMGR_FAIL_LOAD 4
	Failure loading ESM Module.
#define	SafMGR_FAIL_ESMCFG 5
	Bad ESM Module configuration.
#define	SafMGR_FAIL_ESMENTRY 100
	Bad ESM Module entry.
#define	SafMGR_FAIL_ESM 101
	Error reported by ESM Module.
#define	SafMGR_FAIL_ENV 200
	Environment init failure.
#define	SafINIT_OK 0
	Initialization succeeded.
#define	SafINIT_NULL 1
	Null pointer passed for the SafInit parameter.
#define	SafINIT_VER 2
	Incorrect SafInit::Version value.
#define	SafINIT_BAD_CB 3
	SafInit structure appears to be invalid.
#define	SafINIT_ENV 4
	Illegal SafInit::Environment value.
#define	SafINIT_CFG 5
	Null SafInit::Config pointer.
#define	SafINIT_CNT 6
	Invalid SafInit::ESMCnt value (> SafESM_MAX).
#define	SafINIT_ESMCFG 7
	Null pointer in SafInit::ESMCfg array.
#define	SafINIT_RESRCE 8
	Resource unavailable.
#define	SafINIT_OTHER 15
	Other failure.
#define	SafINIT_FAIL 16
	Initialization failed; see SafInit::Reason.
#define	SafINIT_BADENV 128
	Invalid environment.
#define	SafINIT_INTERNAL 129
	Internal error.
#define	SafINIT_MODNAME 130
	Problem with ESM Module name.
#define	SafINIT_MODLOAD 131
	Failure loading ESM Module.
#define	SafINIT_ENVFUNC 132
	Failure resolving environment function.
#define	SafINIT_EXTERNAL 133
	An external service (eg auditing) failed.
#define	SafTERM_THREAD 0
	Thread is terminating.
#define	SafTERM_PROCESS 1
	Process is terminating.
#define	SafTERM_ESF 2
	ESF is being terminated but may be restarted.
#define	SafSTRCMP(s1, op, s2) (strcmp((s1),(s2)) op 0)
	Wrapper for strcmp that inlines the operator.
#define	SafSTRCMP_N(s1, op, s2, n) (strncmp((s1),(s2),(n)) op 0)
	Wrapper for strncmp that inlines the operator.
#define	SafSTRCMP_CI(s1, op, s2) (SafStrcmpCI((s1),(s2)) op 0)
	Wrapper for SafStrcmpCI that inlines the operator.
#define	SafSTRCMP_CIN(s1, op, s2, n) (SafStrcmpCIN((s1),(s2),(n)) op 0)
	Wrapper for SafStrcmpCIN that inlines the operator.
#define	SafDO_STR(x) #x
#define	SafSTRING(x) SafDO_STR(x)
	Macro to convert argument to string.
#define	SafLOG_ALL 0
Enumerations
enum	SafRet { SafR_OK = 0, SafR_PARAM = 1, SafR_RESOURCE = 2, SafR_EXFAIL = 3, SafR_STATE = 4, SafR_INTERNAL = 5, SafR_NOTFOUND = 6, SafR_TRUNCATED = 7, SafR_NOMORE = 8, SafR_INVALID = 9, SafR_ESM = 10, SafR_END = 11, SafR_NOTIMPL = 12, SafR_Invalid, SafR_Sizer = (1<<30) }
	ESF Manager API Return Codes. More...
Functions
mf_uns32	safmgr (struct SafInit *Init)
	ESF Manager Initialization.
mf_uns32	safterm (mf_uns32 What, void *Reserved)
	ESF Manager Termination.
mf_uns32	safcfg (struct SafInit Init, void Reserved)
	ESF Manager Reconfiguration.
mf_uns32	safcfgesm (int Index, struct cas_esm_config_internal Config, void Reserved)
	ESM Reconfiguration.
int	SafStrcmpCI (const char , const char )
	Case-insensitive string comparison.
int	SafStrcmpCIN (const char , const char , size_t)
	Case-insensitive string comparison (length-limited).
char *	SafDupStr (const char *)
	Duplicate a string.
mf_uns32	SafNative32u (mf_uns32 NetValue)
int	SafState (void)
	ESF Manager Run State.
SafRet	SafQueryCfg (const char Class, const char Name, char **ValueP)
	Query ESF Manager Custom Configuration.

Detailed Description

ESF Manager Startup and Control definitions.

Data structures and other definitions for the ESF Manager API, used to initialize and control the ESF Manager.

See also:: safmgr.c

Define Documentation

#define SafESM_MAX 8

Maximum number of ESM Modules.

The ESF Manager supports multiple ESM Modules. Up to this many may be configured for an application (ES region or MFDS).

Referenced by SafAdmin(), and safmgr().

#define SafSTRCMP	(	s1,
		op,
		s2	)	(strcmp((s1),(s2)) op 0)

Wrapper for strcmp that inlines the operator.

Invoke as eg

 if (SafSTRCMP(foo, !=, bar))

Referenced by SafModLoad(), SafModUnload(), and SafVerify().

#define SafSTRCMP_N	(	s1,
		op,
		s2,
		n	)	(strncmp((s1),(s2),(n)) op 0)

Wrapper for strncmp that inlines the operator.

Like SafSTRCMP(), but with a maximum comparison length as per strncmp().

#define SafSTRCMP_CI	(	s1,
		op,
		s2	)	(SafStrcmpCI((s1),(s2)) op 0)

Wrapper for SafStrcmpCI that inlines the operator.

Like SafSTRCMP(), but case-insensitive.

Referenced by SafCacheInit(), SafStoreIterate(), and SafVerify().

#define SafSTRCMP_CIN	(	s1,
		op,
		s2,
		n	)	(SafStrcmpCIN((s1),(s2),(n)) op 0)

Wrapper for SafStrcmpCIN that inlines the operator.

Like SafSTRCMP_N(), but case-insensitive.

Enumeration Type Documentation

enum SafRet

ESF Manager API Return Codes.

These return codes are used by the public functions in the ESF Manager API. Zero is success and positive values are used for various error conditions.

Enumerator:

SafR_OK	Success.
SafR_PARAM	Invalid parameter value.
SafR_RESOURCE	Required resource not available.
SafR_EXFAIL	External facility (eg OS, RTS) failed.
SafR_STATE	Wrong state for performing operation.
SafR_INTERNAL	Unexpected internal error.
SafR_NOTFOUND	Requested object not found.
SafR_TRUNCATED	Data was truncated.
SafR_NOMORE	End of data reached.
SafR_INVALID	Invalid data encountered.
SafR_ESM	ESM Module or ESM failed.
SafR_END	An operation is being terminated.
SafR_NOTIMPL	Requested operation is not implemented.

Function Documentation

mf_uns32 safmgr ( struct SafInit * Init )

ESF Manager Initialization.

This function must be invoked before any other ESF Manager functions are used.

After successful initialization, a subsequent initialization has no effect. If initialization fails, it can be retried after the problem has been corrected.

Warning:: This function is not thread-safe. It must not be called by multiple threads until after initialization has completed successfully (at which point it will have no further effect).

Parameters:

Init

A pointer to struct SafInit. On entry the following fields must be set:

Version Set to SafMGR_API_VER.
Environment Set to one of the predefined values.
Config Pointing to the ESF Manager configuration block.
ESMCnt Set to the number of configured ESM Modules.
ESMCfg Pointing to configuration blocks for ESM Modules.

On return, ESF Manager will have set Reason and Detail. They will be zero for success, non-zero for error. If a failure occurred in an ESM Module's initialization (see the description for SafInit::Detail), ESMCnt will be set to the index (from 0) of the ESM Module that reported the error.

Returns:: An integer value, zero for success and non-zero if initialization failed. See ESF Manager Initialization Return Codes.

References SafInit::Config, SafInit::Detail, SafInit::ESMCfg, SafInit::ESMCnt, SafInit::Reason, SafAllocStore(), SafCacheInit(), SafEnvInit(), SafESM_MAX, SafEsmInit(), SafINIT_BAD_CB, SafINIT_BADENV, SafINIT_CFG, SafINIT_CNT, SafINIT_ENVFUNC, SafINIT_ESMCFG, SafINIT_EXTERNAL, SafINIT_FAIL, SafINIT_NULL, SafINIT_OK, SafINIT_OTHER, SafINIT_RESRCE, SafINIT_VER, SafInitAuditing(), SafLog(), SafMGR_API_VER, SafMGR_FAIL_ENV, SafMGR_FAIL_RESOURCE, SafMsgCRIT, SafProcInit(), SafQueryCfg(), SafR_EXFAIL, SafR_INTERNAL, SafR_NOTFOUND, SafR_PARAM, SafR_RESOURCE, SafR_STATE, SafR_TRUNCATED, SafRaiseAuditEvent(), SafStoreAdd(), SafStoreLoad(), SafThrLock(), SafThrUnlock(), and SafInit::Version.

mf_uns32 safterm	(	mf_uns32	What,
		void *	Reserved
	)

ESF Manager Termination.

This function should be called when a thread or process that has used ESF is terminating. It will inform the ESM Modules (currently for process exit only), and will perform any necessary cleanup for the Manager itself, including environment-specific cleanup.

Parameters:

`[in]`	What	Indicates what is terminating; see "What" Codes for safterm()
	Reserved	Reserved for future use (pass a null pointer)

Returns:: An integer value, zero for success, non-zero for error. Currently no specific error codes are defined.

References SafCacheTerminate(), SafEsmExit(), SafEsmUnload(), SafR_PARAM, SafRaiseAuditEvent(), SafTERM_ESF, SafTERM_PROCESS, SafThrLock(), and SafThrUnlock().

mf_uns32 safcfg	(	struct SafInit *	Init,
		void *	Reserved
	)

ESF Manager Reconfiguration.

This function will be provided in the future to reconfigure ESF without stopping and restarting it. Reconfigurable aspects will probably include options such as auditing, configuration text, and so on.

Currently it's not implemented and will return SafR_NOTIMPL.

Parameters:

	Init	A pointer to struct SafInit. See safinit() for details.
	Reserved	Reserved for future use (pass a null pointer)

Returns:: An integer value, zero for success and non-zero if initialization failed. See ESF Manager API Return Codes.

References SafR_NOTIMPL, and SafR_PARAM.

mf_uns32 safcfgesm	(	int	Index,
		struct cas_esm_config_internal *	Config,
		void *	Reserved
	)

ESM Reconfiguration.

This function lets the caller request that one of the ESMs that was configured in the call to safinit() be asked to update its configuration. If the module does not accept reconfiguration requests, or if it returns an error, safcfgesm will return SafR_ESM.

If the module does support reconfiguration, the aspects that can be updated depend on the module. The MLDAP ESM Module currently supports updating the tracing options that are controlled by the [Trace] section in its configuration text.

Note that the caller should pass the entire ESM configuration, including information that the module may not support updating, just as it was passed to safinit() except with the specific changes desired by the caller. That way, if a newer version of the module supports updating additional aspects, an update request won't unexpectedly change the ESM's behavior.

Parameters:

`[in]`	Index	Index of the ESM in the list originally passed to safinit(). The first ESM is 0.
`[in]`	Config	ESM module configuration block.
	Reserved	Reserved for future use (pass a null pointer)

Returns:: An integer value, zero for success and non-zero if reconfiguration failed. See ESF Manager API Return Codes.

References SafESM_RECONFIG, SafEsmCControl(), SafESMRC_EXTERNAL, SafESMRC_FAIL, SafESMRC_MGRFAIL, SafESMRC_NOTIMPL, SafESMRC_OK, SafESMRC_PARAM, SafESMRC_RESOURCE, SafR_ESM, SafR_EXFAIL, SafR_INTERNAL, SafR_NOTIMPL, SafR_OK, SafR_PARAM, and SafR_RESOURCE.

int SafStrcmpCI	(	const char *	Str1,
		const char *	Str2
	)

Case-insensitive string comparison.

Like strcmp, but case-insensitive (in the current locale). Can be used with the SafSTRCMP_CI macro.

Parameters:

`[in]`	Str1	First string to be compared.
`[in]`	Str2	Second string to be compared.

Returns:: One of {-1,0,1}, if Str1 is less than, equal to, or greater than Str2. Null pointers compare equal to each other and less than anything else (including an empty string).

int SafStrcmpCIN	(	const char *	Str1,
		const char *	Str2,
		size_t	Len
	)

Case-insensitive string comparison (length-limited).

Like strncmp, but case-insensitive (in the current locale). Can be used with the SafSTRCMP_CIN macro.

Parameters:

`[in]`	Str1	First string to be compared.
`[in]`	Str2	Second string to be compared.
`[in]`	Len	Maximum number of characters to compare.

Returns:: One of {-1,0,1}, if Str1 is less than, equal to, or greater than Str2. Null pointers compare equal to each other and less than anything else (including an empty string).

char* SafDupStr ( const char * Str )

Duplicate a string.

Attempts to duplicate a string, allocating the new area and copying the source to it. Returns null if allocation fails. A null input is treated as the empty string.

Freeing the data is the caller's responsibility.

Parameters:

[in] Str String to be copied.

Returns:: New string or null.

Referenced by SafCacheInit(), SafEnvInit(), SafModLoad(), SafStoreAdd(), and SafStoreLoad().

int SafState ( void )

ESF Manager Run State.

Returns the run state of ESF Manager (uninitialized, running, terminated).

No parameters

Returns:

An integer value:

0: ESF Manager has not been initialized
1: ESF Manager is running
2: ESF Manager has been terminated

Referenced by SafAdmin(), SafAuth(), SafUpdate(), SafVerify(), and SafXauth().

SafRet SafQueryCfg	(	const char *	Class,
		const char *	Name,
		char **	ValueP
	)

Query ESF Manager Custom Configuration.

MFDS provides a "Configuration Information" text area in each Security Manager configuration object. This area can be used to set custom configuration attributes in "ini" format, with name=value pairs grouped under section headings in square brackets.

This function can be used to query the value associated with a name in a given section.

Parameters:

`[in]`	Class	Section heading (without the brackets)
`[in]`	Name	Item name
`[out]`	ValueP	Returned pointer to value, if any

Returns:: Zero for success or a SafRet value for failure.

References SafStoreFind().

Referenced by EsmSafQuery(), SafAdmin(), SafCacheInit(), SafEsmInit(), safmgr(), SafProcInit(), and SafVerify().

safmgr.h File Reference

Data Structures

Defines

Enumerations

Functions

Detailed Description

Define Documentation

Enumeration Type Documentation

Function Documentation