'\" te
.\" Copyright (c) 2005, 2013, 2013, Oracle and/or its affiliates. All rights reserved.
.TH getexecattr 3C "10 May 2011" "SunOS 5.11" "Standard C Library Functions"
.SH NAME
getexecattr, free_execattr, setexecattr, endexecattr, getexecuser, getexecprof, match_execattr \- get execution profile entry
.SH SYNOPSIS
.LP
.nf
\fBexecattr_t *\fR\fBgetexecattr\fR(\fBvoid\fR);
.fi

.LP
.nf
\fBvoid\fR \fBfree_execattr\fR(\fBexecattr_t *\fR\fIep\fR);
.fi

.LP
.nf
\fBvoid\fR \fBsetexecattr\fR(\fBvoid\fR);
.fi

.LP
.nf
\fBvoid\fR \fBendexecattr\fR(\fBvoid\fR);
.fi

.LP
.nf
\fBexecattr_t *\fR\fBgetexecuser\fR(\fBconst char *\fR\fIusername\fR, \fBconst char *\fR\fItype\fR,
     \fBconst char *\fR\fIid\fR, \fBint\fR \fIsearch_flags\fR);
.fi

.LP
.nf
\fBexecattr_t *\fR\fBgetexecprof\fR(\fBconst char *\fR\fIprofname\fR, \fBconst char *\fR\fItype\fR,
     \fBconst char *\fR\fIid\fR, \fBint\fR \fIsearch_flags\fR);
.fi

.LP
.nf
\fBexecattr_t *\fR\fBmatch_execattr\fR(\fBexecattr_t *\fR\fIep\fR, \fBchar *\fR\fIprofname\fR,
     \fBchar *\fR\fItype\fR, \fBchar *\fR\fIid\fR);
.fi

.SH DESCRIPTION
.sp
.LP
The \fBgetexecattr()\fR function returns a single \fBexec_attr\fR(4) entry. Entries can come from any of the sources specified in the \fBnsswitch.conf\fR(4) file. Only entries in the name service scope for which the corresponding profile entry is found in the \fBprof_attr\fR(4) database are returned.
.sp
.LP
Successive calls to \fBgetexecattr()\fR return either successive \fBexec_attr\fR entries or \fINULL\fR. Because \fBgetexecattr()\fR always returns a single entry, the \fBnext\fR pointer in the \fBexecattr_t\fR data structure points to \fINULL\fR.
.sp
.LP
The internal representation of an \fBexec_attr\fR entry is an \fBexecattr_t\fR structure defined in  <\fBexec_attr.h\fR> with the following members:
.sp
.in +2
.nf
char              *name;   /* name of the profile */
char              *policy; /* policy under which the attributes are */
                           /* relevant*/
char              *type;   /* type of profile */
char              *res1;   /* reserved for future use */
char              *res2;   /* reserved for future use */
char              *id;     /* unique identifier */
kva_t             *attr;   /* attributes */
struct execattr_s *next;   /* optional pointer to next profile */
.fi
.in -2

.sp
.LP
The \fBfree_execattr()\fR function releases memory. It follows the \fBnext\fR pointers in the \fBexecattr_t\fR structure so that the entire linked list is released.
.sp
.LP
The \fBsetexecattr()\fR function "rewinds" to the beginning of the enumeration of \fBexec_attr\fR entries. Calls to \fBgetexecuser()\fR can leave the enumeration in an indeterminate state. Therefore, \fBsetexecattr()\fR should be called before the first call to \fBgetexecattr()\fR. 
.sp
.LP
The \fBendexecattr()\fR function can be called to indicate that \fBexec_attr\fR processing is complete; the library can then close any open \fBexec_attr\fR file, deallocate any internal storage, and so forth.
.sp
.LP
The \fBgetexecuser()\fR function returns a linked list of entries that match the \fItype\fR and \fIid\fR arguments and have a profile that has been assigned to the user specified by \fIusername\fR, as described in \fBpasswd\fR(4). Profiles for the user are obtained from the list of default profiles in \fB/etc/security/policy.conf\fR (see \fBpolicy.conf\fR(4)) and the \fBuser_attr\fR(4) database.
.sp
.LP
Two sets of profiles may be assigned to a user, an authenticated set for commands requiring user reauthentication, and another set for unauthenticated commands. Corresponding \fBsearch_flags\fR can be used to restrict the search to a single profile set. These two flags are mutually exclusive. If neither flag is set, both profile sets are searched, beginning with the authenticated set.
.sp
.LP
If \fBGET_AUTH_PROF\fR is specified, the database is searched for the user's profiles which require reauthentication, starting with the profiles assigned using the \fBauth_profiles\fR keyword in \fBuser_attr\fR(4) and the \fBAUTH_PROFS_GRANTED\fR keyword in \fBpolicy.conf\fR(4).
.sp
.LP
If \fBGET_PROF\fR is specified, the database is searched for the user's profiles which do not require reauthentication, starting with the profiles assigned using the profiles keyword in \fBuser_attr\fR(4) and the \fBPROFS_GRANTED\fR keyword in \fBpolicy.conf\fR(4).
.sp
.LP
The \fBgetexecprof()\fR function returns a linked list of entries that match the \fItype\fR and \fIid\fR arguments and have the profile specified by the \fIprofname\fR argument. Only entries in the name service scope for which the corresponding profile entry is found in the \fBprof_attr\fR database are returned.
.sp
.LP
Using \fBgetexecuser()\fR and \fBgetexecprof()\fR, programmers can search  for any \fItype\fR argument, such as the manifest constant \fBKV_COMMAND\fR. The arguments are logically AND-ed together so that only entries exactly matching all of the arguments are returned. Wildcard matching applies if there is no exact match for an \fBID\fR. Any argument can be assigned the \fINULL\fR value to indicate that it is not used as part of the matching criteria. Two \fBsearch_flags\fR controls whether these function return the first match or all matching entries.
.sp
.LP
If \fBGET_ONE\fR is specified, these functions return the first match, setting the next  pointer to  \fBNULL\fR. Use \fBGET_ONE\fR when searching for the attributes for one particular application.
.sp
.LP
If \fBGET_ALL\fR is specified, all matching entries are returned, using the next pointer to create a linked list. The entire database is searched, resulting in a much  slower operation.
.sp
.LP
Once a list of entries is returned by \fBgetexecuser()\fR or \fBgetexecprof()\fR, the convenience function \fBmatch_execattr()\fR can be used to identify an individual entry. It returns a pointer to the individual element with the same profile name ( \fIprofname\fR), type name ( \fItype\fR),  and \fIid\fR. Function parameters set to \fINULL\fR are not used as part of the matching criteria. In the event that multiple entries meet the matching criteria, only a pointer to the first entry is returned. The \fBkva_match\fR(3C) function can be used to look up a key in a key-value array.
.SH RETURN VALUES
.sp
.LP
Those functions returning data only return data related to the active policy. The \fBgetexecattr()\fR function returns a pointer to a  \fBexecattr_t\fR if it successfully enumerates an entry; otherwise it returns \fINULL\fR, indicating the end of the enumeration.
.SH USAGE
.sp
.LP
The \fBgetexecattr()\fR, \fBgetexecuser()\fR, and \fBgetexecprof()\fR functions all allocate memory for the pointers they return. This memory should be deallocated with the \fBfree_execattr()\fR call. The \fBmatch_execattr()\fR( function does not allocate any memory. Therefore, pointers returned by this function should not be deallocated.
.sp
.LP
Individual attributes may be referenced in the \fBattr\fR structure by calling the \fBkva_match\fR(3C) function.
.SH EXAMPLES
.LP
\fBExample 1 \fRFind all profiles that have the  \fBping\fR command.
.sp
.in +2
.nf
if ((execprof=getexecprof(NULL, KV_COMMAND, "/usr/sbin/ping", 
    GET_ALL)) == NULL) { 
        /* do error */
}
.fi
.in -2

.LP
\fBExample 2 \fRFind the entry for the \fBping\fR command in the Network Administration Profile.
.sp
.in +2
.nf
if ((execprof=getexecprof("Network Administration", KV_COMMAND, 
    "/usr/sbin/ping", GET_ONE))==NULL) {
        /* do error */
}
.fi
.in -2

.LP
\fBExample 3 \fRTell everything that can be done in the Filesystem Security profile.
.sp
.in +2
.nf
if ((execprof=getexecprof("Filesystem Security", KV_NULL, NULL, 
    GET_ALL))==NULL)) { 
        /* do error */
}
.fi
.in -2

.LP
\fBExample 4 \fRTell if the \fBtar\fR utility is in a profile assigned to user wetmore. If there is no exact profile entry, the wildcard (*), if defined, is returned.
.sp
.LP
The following tells if the \fBtar\fR utility is in a profile assigned to user wetmore. If there is no exact profile entry, the wildcard (*), if defined, is returned.

.sp
.in +2
.nf
if ((execprof=getexecuser("wetmore", KV_COMMAND, "/usr/bin/tar", 
    GET_ONE))==NULL) {
        /* do error */
}
.fi
.in -2

.SH FILES
.sp
.ne 2
.mk
.na
\fB\fB/etc/nsswitch.conf\fR\fR
.ad
.RS 29n
.rt  
configuration file lookup information for the name server switch
.RE

.sp
.ne 2
.mk
.na
\fB\fB/etc/user_attr\fR\fR
.ad
.RS 29n
.rt  
extended user attributes
.RE

.sp
.ne 2
.mk
.na
\fB\fB/etc/security/exec_attr\fR\fR
.ad
.RS 29n
.rt  
execution profiles
.RE

.sp
.ne 2
.mk
.na
\fB\fB/etc/security/policy.conf\fR\fR
.ad
.RS 29n
.rt  
policy definitions
.RE

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
tab() box;
cw(2.75i) |cw(2.75i) 
lw(2.75i) |lw(2.75i) 
.
ATTRIBUTE TYPEATTRIBUTE VALUE
_
MT-LevelMT-Safe
.TE

.SH SEE ALSO
.sp
.LP
\fBgetauthattr\fR(3C), \fBgetuserattr\fR(3C), \fBkva_match\fR(3C), \fBexec_attr\fR(4), \fBpasswd\fR(4), \fBpolicy.conf\fR(4), \fBprof_attr\fR(4), \fBuser_attr\fR(4), \fBattributes\fR(5)