OpenVMS System Services Reference Manual

Document revision date: 19 July 1999

OpenVMS System Services Reference Manual

Contents

Index

$CREATE_USER_PROFILE

Returns an encoded security profile for the specified user.

Format

SYS$CREATE_USER_PROFILE usrnam ,[itmlst] ,[flags] ,usrpro ,usrprolen ,[contxt]

C Prototype

int sys$create_user_profile (void *usrnam, void *itmlst, unsigned int flags, void *usrpro, unsigned int *usrprolen, unsigned int *contxt);

Arguments

usrnam

OpenVMS usage: char_string

type: character-coded text string

access: read only

mechanism: by descriptor

Name of the user whose security profile is to be returned. The usrnam argument is the address of a descriptor pointing to a text string containing the user name. The user name string can contain a maximum of 12 alphanumeric characters.
For more information about user names, refer to the OpenVMS Guide to System Security.
itmlst

OpenVMS usage: item_list_3

type: longword (unsigned)

access: read only

mechanism: by reference

Item list specifying the portions of the user's security profile to be replaced or augmented.
The item list is a standard format item list. The following figure depicts the general format of an item descriptor. See the Item Codes section for a list of valid item codes for $CREATE_USER_PROFILE.

The following table defines the item descriptor fields.

Descriptor Field Definition

Buffer length A word containing a user-supplied integer specifying the length (in bytes) of the buffer from which the service is to read the information. The length of the buffer needed depends on the item code specified in the item code field of the item descriptor.

Item code A word containing a user-supplied symbolic code specifying the item of information.

Buffer address A longword containing the user-supplied address of the buffer.

Return length address A longword that normally contains the user-supplied address of a word in which the service writes the length (in bytes) of the information it returned. This is not used by $CREATE_USER_PROFILE and should contain a 0.

Descriptor Field	Definition
Buffer length	A word containing a user-supplied integer specifying the length (in bytes) of the buffer from which the service is to read the information. The length of the buffer needed depends on the item code specified in the item code field of the item descriptor.
Item code	A word containing a user-supplied symbolic code specifying the item of information.
Buffer address	A longword containing the user-supplied address of the buffer.
Return length address	A longword that normally contains the user-supplied address of a word in which the service writes the length (in bytes) of the information it returned. This is not used by $CREATE_USER_PROFILE and should contain a 0.

flags

OpenVMS usage:	mask_longword
type:	longword (unsigned)
access:	read only
mechanism:	by value

The flags argument is used to control the behavior of the $CREATE_USER_PROFILE service. This argument does not accept ISS$ mask values; therefore, continue to use the CHP$ mask values for this argument. The following table describes each flag.

Symbol	Description
CHP$M_DEFCLASS	By default, $CREATE_USER_PROFILE initializes the security profile with the user's maximum authorized classification. When this flag is set, the service initializes the security profile from the user's default classification instead. This flag is reserved to Compaq.
CHP$M_DEFPRIV	By default, $CREATE_USER_PROFILE initializes the security profile with the user's authorized privilege mask. When this flag is set, the service initializes the security profile from the user's default privilege mask instead.
CHP$M_NOACCESS	Instructs the service not to access the user authorization file (SYSUAF.DAT) or rights database (RIGHTSLIST.DAT) to build the security profile. This flag can be used as an optimization when all the information necessary to build the security profile is known to the caller.

usrpro

OpenVMS usage:	char_string
type:	opaque byte stream
access:	write only
mechanism:	by reference

Buffer to receive the security profile. The usrpro argument is the address of a buffer to receive the encoded security profile. If an address of 0 is specified, $CREATE_USER_PROFILE returns the size of the buffer needed in the usrprolen argument.

usrprolen

OpenVMS usage:	word
type:	word (unsigned)
access:	read/write
mechanism:	by reference

Word to receive the full size of the security profile. On input, the usrprolen argument specifies the length of the buffer pointed to by the usrpro argument. The usrprolen argument is the address of a word to which $CREATE_USER_PROFILE writes the actual length of the security profile. If the caller specifies a usrpro address of 0, $CREATE_USER_PROFILE returns the anticipated size, in bytes, of the buffer needed to hold the user's security profile in the usrprolen argument.

contxt

OpenVMS usage:	longword
type:	longword (unsigned)
access:	modify
mechanism:	by reference

Longword used to maintain authorization file context. The contxt argument is the address of a longword to receive a $GETUAI context value. On the initial call, this longword should contain the value --1. On subsequent calls, the value of the contxt argument from the previous call should be passed back in.

Using the contxt argument keeps the UAF open across all calls, thereby improving the performance of the system on subsequent calls. To close the UAF, you must run down the image.

The resulting context value from a $CREATE_USER_PROFILE call can also be used as the input contxt argument to the $GETUAI system service, and vice versa.

Item Codes

CHP$_ADDRIGHTS
A rights list segment containing additional identifiers to be appended to the set of identifiers held by the user. A rights list segment is a list of quadword identifier/attributes pairs, each containing a longword identifier value, followed by a longword mask identifying the attributes of the holder. The buflen argument should be set to the total size, in bytes, of the rights list segment. The bufadr argument points to a descriptor that points to the first byte in the rights list segment (that is, the first byte of the first identifier value).
This item code can be repeated to add up to 256 additional rights list segments. If more than 256 identifiers are granted to the user, $CREATE_USER_PROFILE returns SS$_INSFMEM.
CHP$_CLASS
The classification to be associated with the created security profile. This item code is reserved to Compaq.
CHP$_PRIV
A quadword privilege mask specifying the user's privileges. The $PRVDEF macro defines the list of available privileges.
CHP$_UIC
A longword describing the user identification code (UIC).
ISS$_ACCOUNT
Variable-length buffer containing the account name. The maximum size of this buffer is 32 bytes.
ISS$_ADD_RIGHTS
A rights list segment containing additional identifiers to be appended to the set of identifiers held by the user. A rights list segment is a list of quadword identifier/attributes pairs, each containing a longword identifier value, followed by a longword mask identifying the attributes of the holder. The buflen argument should be set to the total size, in bytes, of the rights list segment. The bufadr argument points to a descriptor that points to the first byte in the rights list segment (that is, the first byte of the first identifier value).
This item code can be repeated to add up to 256 additional rights list segments. If more than 256 identifiers are granted to the user, $CREATE_USER_PROFILE returns SS$_INSFMEM.
ISS$_AUTHPRIV
Quadword containing the authorized privileges. See $PRVDEF macro for definitions.
ISS$_FLAGS
Longword containing user flags. The following flag is supported:
ISS$M_FLAG_SECAUDIT - Mandatory audit flag.
ISS$_MAXCLASS
Buffer containing the maximum classification. The maximum size of this buffer is CLS$K_LENGTH. This item code is reserved to Compaq. See the $CLSDEF macro for definitions.
ISS$_MINCLASS
Buffer containing the minimum classification. The maximum size of this buffer is CLS$K_LENGTH. This item code is reserved to Compaq. See the $CLSDEF macro for definitions.
ISS$_MODE
Longword containing the access mode. See $PSLDEF macro for definitions.
ISS$_PERMPRIV
Quadword containing the permanent privileges. See $PRVDEF macro for definitions.
ISS$_RIGHTS
Descriptor pointing to a vector of quadwords containing identifier/attribute pairs used to initialize the rights identifier list. See the $KGBDEF macro for definitions. Any identifiers specified by the ISS$_ADD_RIGHTS item code will be added to this list.
The format of this vector is as follows:
31 0 +-------------------------+ | Identifier | +- - - - - - - - - - - - -+ | Attributes | +-------------------------+ | Identifier | +- - - - - - - - - - - - -+ | Attributes | +-------------------------+ | .... | +- - - - - - - - - - - - -+ | .... | +-------------------------+
ISS$_UIC
A longword describing the user identification code (UIC).
ISS$_WORKCLASS
The classification to be associated with the created security profile. This item code is reserved to Compaq.
ISS$_WORKPRIV
A quadword privilege mask specifying the user's privileges. The $PRVDEF macro defines the list of available privileges.

Description

The Create User Profile service returns a security profile for a user. This profile can be generated in two ways.

If the caller does not specify the CHP$_NOACCESS flag in the flags argument, $CREATE_USER_PROFILE accesses the system authorization database (SYSUAF.DAT) or the rights database (RIGHTSLIST.DAT) for the specified user name and builds a representation of the privileges and rights granted to that user. The security profile is returned as an opaque byte stream.
$CREATE_USER_PROFILE returns a representation of the security profile that the user would have when logged in at the highest authorized classification with all authorized privileges enabled.
When the caller specifies the CHP$M_NOACCESS flag in the flags argument, $CREATE_USER_PROFILE creates a security profile without accessing the user authorization file (SYSUAF.DAT) or the rights database (RIGHTSLIST.DAT). When CHP$M_NOACCESS is specified, all of the information is obtained from the item list. The caller must supply the CHP$_PRIV and CHP$_UIC items. In addition, an address of 0 can be specified for the usrnam argument.

In either case, the newly created security profile can be passed as input to the $CHKPRO and $CHECK_ACCESS system services using the usrpro argument.
$CREATE_USER_PROFILE returns the set of identifiers associated with the user's owner identifier. The CHP$_ADDRIGHTS item code can be used to add additional identifiers to this set.
Required Access or Privileges

Access to SYSUAF.DAT and RIGHTSLIST.DAT is required unless you are constructing the security profile for your own user name.
Required Quota

None
Related Services

$CHECK_ACCESS, $CHKPRO, $FIND_HELD, $FINISH_RDB, $GETUAI

Condition Values Returned

SS$_NORMAL The service completed successfully.

SS$_ACCVIO Parameter or item list buffer not accessible.

SS$_BADPARAM Item code invalid.

SS$_INSFARG A required item code or parameter is missing.

SS$_INSFMEM Insufficient process memory to construct profile.

$CREATE_USER_PROFILE can also return any error returned by the $GETUAI or $FIND_HELD services.

$CRELNM

Creates a logical name and specifies its equivalence names.
On Alpha systems, this service accepts 64-bit addresses.

Format

SYS$CRELNM [attr] ,tabnam ,lognam ,[acmode] ,[itmlst]

C Prototype

int sys$crelnm (unsigned int *attr, void *tabnam, void *lognam, unsigned char *acmode, void *itmlst);

Arguments

attr

OpenVMS usage: mask_longword

type: longword (unsigned)

access: read only

mechanism: by 32- or 64-bit reference (Alpha)

mechanism: by 32-bit reference (VAX)

Attributes to be associated with the logical name. The attr argument is the 32-bit address (on VAX systems) or the 32- or 64-bit address (on Alpha systems) of a longword bit mask specifying these attributes.
Each bit in the longword corresponds to an attribute and has a symbolic name. These symbolic names are defined by the $LNMDEF macro. To specify an attribute, specify its symbolic name or set its corresponding bit. The longword bit mask is the logical OR of all desired attributes. All undefined bits in the longword must be 0.
If you do not specify this argument or specify it as 0 (no bits set), no attributes are associated with the logical name.
The attributes are as follows.

Attribute Description

LNM$M_CONFINE If set, the logical name is not copied from the process to its spawned subprocesses. You create a subprocess with the DCL command SPAWN or the LIB$SPAWN Run-Time Library routine. If the logical name is placed into a process-private table that has the CONFINE attribute, the CONFINE attribute is automatically associated with the logical name. This applies only to process-private logical names.

LNM$M_NO_ALIAS If set, the logical name cannot be duplicated in this table at an outer access mode. If another logical name with the same name already exists in the table at an outer access mode, it is deleted.

tabnam

OpenVMS usage: logical_name

type: character-coded text string

access: read only

mechanism: by 32- or 64-bit descriptor--fixed-length string descriptor (Alpha)

mechanism: by 32-bit descriptor--fixed-length string descriptor (VAX)

Name of the table in which to create the logical name. The tabnam argument is the 32-bit address (on VAX systems) or the 32- or 64-bit address (on Alpha systems) of a descriptor that points to the name of this table. This argument is required and must be specified in uppercase.
The name must be entered in uppercase letters. (This requirement differs from the $CRELNT system service, which automatically changes tabnam to uppercase.)
If tabnam is not the name of a logical name table, it is assumed to be a logical name and is translated iteratively until either the name of a logical name table is found or the number of translations allowed by the system has been performed. If tabnam translates to a list of logical name tables, the logical name is entered into the first table in the list.
lognam

OpenVMS usage: logical_name

type: character-coded text string

access: read only

mechanism: by 32- or 64-bit descriptor--fixed-length string descriptor (Alpha)

mechanism: by 32-bit descriptor--fixed-length string descriptor (VAX)

Name of the logical name to be created. The lognam argument is the 32-bit address (on VAX systems) or the 32- or 64-bit address (on Alpha systems) of a descriptor that points to the logical name string. Logical name strings of logical names created within either the system or process directory table must consist of uppercase alphanumeric characters, dollar signs ($), and underscores (_); the maximum length is 31 characters. The maximum length of logical name strings created within other tables is 255 characters with no restrictions on the types of characters that can be used. This argument is required.
acmode

OpenVMS usage: access_mode

type: byte (unsigned)

access: read only

mechanism: by 32- or 64-bit reference (Alpha)

mechanism: by 32-bit reference (VAX)

Access mode to be associated with the logical name. The acmode argument is the 32-bit address (on VAX systems) or the 32- or 64-bit address (on Alpha systems) of a byte that specifies the access mode.
The access mode associated with the logical name is determined by maximizing the access mode of the caller with the access mode specified by the acmode argument, which means that the less privileged of the two is used. Symbols for the four access modes are defined by the $PSLDEF macro.
You cannot specify an access mode more privileged than that of the containing table. However, if the caller has SYSNAM privilege, then the specified access mode is associated with the logical name regardless of the access mode of the caller.
If you omit this argument or specify it as 0, the access mode of the caller is associated with the logical name.
itmlst

OpenVMS usage: 32-bit item_list_3 or 64-bit item_list 64b

type: longword (unsigned) for 32-bit; quadword (unsigned) for 64-bit

access: read only

mechanism: by 32- or 64-bit reference (Alpha)

mechanism: by 32-bit reference (VAX)

Item list describing the equivalence names to be defined for the logical name and information to be returned to the caller. The itmlst argument is the 32-bit address (on VAX systems) or the 32- or 64-bit address (on Alpha systems) of a list of item descriptors, each of which specifies information about an equivalence name. An item list in 32-bit format is terminated by a longword of 0; an item list in 64-bit format is terminated by a quadword of 0. All items in an item list must be of the same format---either 32-bit or 64-bit.
Note that it is possible to create a logical that has no equivalence names. This is done by either omitting the itmlst argument to $CRELNM, or by not including the LNM$_STRING item code to the itmlst data structure that is passed into $CRELNM. It is not possible to create this kind of logical using DCL.
The following diagram depicts the 32-bit format of a single item descriptor.

Attribute	Description
LNM$M_CONFINE	If set, the logical name is not copied from the process to its spawned subprocesses. You create a subprocess with the DCL command SPAWN or the LIB$SPAWN Run-Time Library routine. If the logical name is placed into a process-private table that has the CONFINE attribute, the CONFINE attribute is automatically associated with the logical name. This applies only to process-private logical names.
LNM$M_NO_ALIAS	If set, the logical name cannot be duplicated in this table at an outer access mode. If another logical name with the same name already exists in the table at an outer access mode, it is deleted.

The following table defines the item descriptor fields for 32-bit item list entries.

Descriptor Field Definition

Buffer length A word specifying the number of bytes in the buffer pointed to by the buffer address field. The length of the buffer needed depends on the item code specified in the item code field of the item descriptor. If the value of buffer length is too small, the service truncates the data.

Item code A word containing a symbolic code that describes the information in the buffer or the information to be returned to the buffer, pointed to by the buffer address field. The item codes are listed in the Item Codes section.

Buffer address A longword containing the 32-bit address of the buffer that receives or passes information.

Return length address A longword containing the 32-bit address of a word specifying the actual length in bytes of the information returned by $CRELNM in the buffer pointed to by the buffer address field. The return length address field is used only when the item code specified is LNM$_TABLE. Although this field is ignored for all other item codes, it must nevertheless be present as a placeholder in each item descriptor.

Descriptor Field	Definition
Buffer length	A word specifying the number of bytes in the buffer pointed to by the buffer address field. The length of the buffer needed depends on the item code specified in the item code field of the item descriptor. If the value of buffer length is too small, the service truncates the data.
Item code	A word containing a symbolic code that describes the information in the buffer or the information to be returned to the buffer, pointed to by the buffer address field. The item codes are listed in the Item Codes section.
Buffer address	A longword containing the 32-bit address of the buffer that receives or passes information.
Return length address	A longword containing the 32-bit address of a word specifying the actual length in bytes of the information returned by $CRELNM in the buffer pointed to by the buffer address field. The return length address field is used only when the item code specified is LNM$_TABLE. Although this field is ignored for all other item codes, it must nevertheless be present as a placeholder in each item descriptor.

The following diagram depicts the 64-bit format of a single item descriptor.

The following table defines the item descriptor fields for 64-bit item list entries.

Descriptor Field Definition

MBO The field must contain a 1. The MBO and MBMO fields are used to distinguish 32-bit and 64-bit item list entries.

Item code A word containing a symbolic code that describes the information in the buffer or the information to be returned to the buffer, pointed to by the buffer address field. The item codes are listed in the Item Codes section.

MBMO The field must contain a --1. The MBMO and MBO fields are used to distinguish 32-bit and 64-bit item list entries.

Buffer length A quadword specifying the number of bytes in the buffer pointed to by the buffer address field. The length of the buffer needed depends on the item code specified in the item code field of the item descriptor. If the value of buffer length is too small, the service truncates the data.

Buffer address A quadword containing the 64-bit address of the buffer that receives or passes information.

Return length address A quadword containing the 64-bit address of a word specifying the actual length in bytes of the information returned by $CRELNM in the buffer pointed to by the buffer address field. The return length address field is used only when the item code specified is LNM$_TABLE. Although this field is ignored for all other item codes, it must nevertheless be present as a placeholder in each item descriptor.

Descriptor Field	Definition
MBO	The field must contain a 1. The MBO and MBMO fields are used to distinguish 32-bit and 64-bit item list entries.
Item code	A word containing a symbolic code that describes the information in the buffer or the information to be returned to the buffer, pointed to by the buffer address field. The item codes are listed in the Item Codes section.
MBMO	The field must contain a --1. The MBMO and MBO fields are used to distinguish 32-bit and 64-bit item list entries.
Buffer length	A quadword specifying the number of bytes in the buffer pointed to by the buffer address field. The length of the buffer needed depends on the item code specified in the item code field of the item descriptor. If the value of buffer length is too small, the service truncates the data.
Buffer address	A quadword containing the 64-bit address of the buffer that receives or passes information.
Return length address	A quadword containing the 64-bit address of a word specifying the actual length in bytes of the information returned by $CRELNM in the buffer pointed to by the buffer address field. The return length address field is used only when the item code specified is LNM$_TABLE. Although this field is ignored for all other item codes, it must nevertheless be present as a placeholder in each item descriptor.

Item Codes

LNM$_ATTRIBUTES
When you specify LNM$_ATTRIBUTES, the buffer address field of the item descriptor points to a longword bit mask that specifies the current translation attributes for the logical name. The current translation attributes are applied to all subsequently specified equivalence strings until another LNM$_ATTRIBUTES item descriptor is encountered in the item list. The symbolic names for these attributes are defined by the $LNMDEF macro. The symbolic name and description of each attribute are as follows.

Attribute Description

LNM$M_CONCEALED If set, OpenVMS RMS interprets the equivalence name as a device name or logical name with the LNM$M_CONCEALED attribute.

LNM$M_TERMINAL If set, further iterative logical name translation on the equivalence name is not to be performed.

LNM$_CHAIN
When you specify LNM$_CHAIN, the buffer address field of the item descriptor points to another item list that $CRELNM is to process immediately after it has processed the current item list.
If you specify the LNM$_CHAIN item code, it must be the last item code in the current item list.
You can chain together 32-bit and 64-bit item lists.
LNM$_STRING
When you specify LNM$_STRING, the buffer address field of the item descriptor points to a buffer containing a user-specified equivalence name for the logical name. The maximum length of the equivalence string is 255 characters.
When $CRELNM encounters an item descriptor with the item code LNM$_STRING, it creates an equivalence name entry for the logical name using the most recently specified values for LNM$_ATTRIBUTES. The equivalence name entry includes the following information:

Name specified by LNM$_STRING.
Next available index value. Each equivalence is assigned a unique value from 0 to 127.
Attributes specified by the most recently encountered item descriptor with item code LNM$_ATTRIBUTES (if these are present in the item list).

Therefore, you should construct the item list so that the LNM$_ATTRIBUTES item codes immediately precede the LNM$_STRING item code or codes to which they apply.
Note that it is possible to create a logical that has no equivalence names. This is done by either omitting the itmlst argument to $CRELNM, or by not including the LNM$_STRING item code to the itmlst data structure that is passed into $CRELNM. It is not possible to create this kind of logical using DCL.
LNM$_TABLE
When you specify LNM$_TABLE, the buffer address field of the item descriptor points to a buffer in which $CRELNM writes the name of the logical name table in which it entered the logical name. The return length address field points to a word that contains a buffer that specifies the length in bytes of the information returned by $CRELNM. The maximum length of the name of a logical name table is 31 characters.

Previous Next Contents Index

privacy and legal statement

4527PRO_014.HTML

OpenVMS usage:	item_list_3
type:	longword (unsigned)
access:	read only
mechanism:	by reference

SS$_NORMAL	The service completed successfully.
SS$_ACCVIO	Parameter or item list buffer not accessible.
SS$_BADPARAM	Item code invalid.
SS$_INSFARG	A required item code or parameter is missing.
SS$_INSFMEM	Insufficient process memory to construct profile.

OpenVMS usage:	logical_name
type:	character-coded text string
access:	read only
mechanism:	by 32- or 64-bit descriptor--fixed-length string descriptor (Alpha)
mechanism:	by 32-bit descriptor--fixed-length string descriptor (VAX)

OpenVMS usage:	access_mode
type:	byte (unsigned)
access:	read only
mechanism:	by 32- or 64-bit reference (Alpha)
mechanism:	by 32-bit reference (VAX)

OpenVMS usage:	32-bit item_list_3 or 64-bit item_list 64b
type:	longword (unsigned) for 32-bit; quadword (unsigned) for 64-bit
access:	read only
mechanism:	by 32- or 64-bit reference (Alpha)
mechanism:	by 32-bit reference (VAX)

Attribute	Description
LNM$M_CONCEALED	If set, OpenVMS RMS interprets the equivalence name as a device name or logical name with the LNM$M_CONCEALED attribute.
LNM$M_TERMINAL	If set, further iterative logical name translation on the equivalence name is not to be performed.