PreviousNext

rdacl_get_printstring(3sec)

Returns printable ACL strings

Synopsis

#include <dce/rdaclif.h>

void rdacl_get_printstring(

handle_t h,
uuid_t *
manager_type,
unsigned32
size_avail,
uuid_t *
manager_type_chain,
sec_acl_printstring_t *
manager_info,
boolean32 *
tokenize,
unsigned32 *
total_num_printstrings,
unsigned32 *
size_used,
sec_acl_printstring_t
printstrings[ ],
error_status_t *
status);

Parameters

Input

h
A handle referring to the target object.

manager_type
A pointer to the UUID identifying the type of the ACL manager in question. There may be more than one type of ACL manager protecting the object whose ACL is bound to the input handle. Use this parameter to distinguish them. Use rdacl_get_manager_types( ) to acquire a list of the manager types protecting a given object.

size_avail
An unsigned 32-bit integer containing the allocated length of the printstrings[ ] array.

Output

manager_type_chain
If the target object ACL contains more than 32 permission bits, multiple manager types are used, one for each 32-bit wide slice of permissions. The UUID returned in manager_type_chain refers to the next ACL manager in the chain. If there are no more ACL managers for this ACL, uuid_nil is returned.

manager_info
Provides a name and help string for the given ACL manager.

tokenize
When FALSE, this variable indicates that the returned permission printstrings are unambiguous and therefore may be concatenated when printed without confusion. When TRUE, however, this property does not hold, and the strings need to be separated when printed or passed.

total_num_printstrings
An unsigned 32-bit integer containing the total number of permission printstrings supported by this ACL manager type.

size_used
An unsigned 32-bit integer containing the number of permission entries returned in the printstrings[ ] array.

printstrings[ ]
An array of permission printstrings of type sec_acl_printstring_t. Each entry of the array is a structure containing three components:

printstring
A character string of maximum length sec_acl_printstring_len containing the printable representation of a specified permission.

helpstring
A character string of maximum length sec_acl_printstring_help_len containing some text that can be used to describe the specified permission.

permissions
A sec_acl_permset_t permission set describing the permissions that are to be represented with the companion printstring.

The array consists of one such entry for each permission supported by the ACL manager identified by manager_type.

status
A pointer to the completion status. On successful completion, the routine returns error_status_ok. Otherwise, it returns an error.

Description
The rdacl_get_printstring( ) routine returns an array of printable representations (called printstrings) for each permission bit or combination of permission bits the specified ACL manager will support. The ACL manager type specified must be one of the types indicated by the ACL handle.

In addition to returning the printstrings, this routine also returns instructions about how to print the strings. When the tokenize variable is set to FALSE, a print string might be r or w, which could be concatenated in the display as rw without any confusion. However, when the tokenize variable is TRUE, it implies the printstrings might be of a form like read or write, which must be displayed separated by spaces or colons or something.

In any list of permission printstrings, there may appear to be some redundancy. ACL managers often define aliases for common permission combinations. By convention, however, simple entries need to appear at the beginning of the printstrings[ ] array, and combinations need to appear at the end.

Notes
This call is not intended to be used by application programs. The sec_acl Application Programming Interface (API) provides all the functionality necessary to use the ACL facility. This reference page is provided for programmers who wish to write an ACL manager. In order to write an ACL manager, a programmer must implement the entire rdacl interface.

This network interface is called on the client side via the sec_acl local interface. Developers are responsible for implementing the server side of this interface. Test server code is included as a sample implementation.

Files

/usr/include/dce/rdaclif.idl
The idl file from which dce/rdaclif.h was derived.

Errors

The following describes a partial list of errors that might be returned. Refer to the OSF DCE Problem Determination Guide for complete descriptions of all error messages.

sec_acl_unknown_manager_type
The manager type selected is not among those referenced by the input handle.

error_status_ok
The call was successful.

Related Information
Functions:

sec_intro(3sec)

sec_acl_bind(3sec)

rdacl_get_manager_types(3sec)