'\" te
.\" Copyright (c) 2005, Sun Microsystems, Inc.  All Rights Reserved.
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH GETEXECATTR 3SECDB "Mar 31, 2005"
.SH NAME
getexecattr, free_execattr, setexecattr, endexecattr, getexecuser, getexecprof,
match_execattr \- get execution profile entry
.SH SYNOPSIS
.LP
.nf
cc [ \fIflag\fR... ] \fIfile\fR... -lsecdb  -lsocket  -lnsl  [ \fIlibrary\fR... ]
#include <exec_attr.h>
#include <secdb.h>

\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_flag\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_flag\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.
.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              *type;   /* type of profile */
char              *policy; /* policy under which the attributes are */
                           /* relevant*/
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. 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
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. The \fB\fR
search_flag controls whether the function returns the first match
(\fBGET_ONE\fR), setting the \fBnext\fR pointer to \fINULL\fR or all matching
entries (\fBGET_ALL\fR), using the \fBnext\fR pointer to create a linked list
of all entries that meet the search criteria. See  \fBEXAMPLES\fR.
.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(3SECDB) 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(3SECDB) 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_ONE)) == 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_ALL))==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
.na
\fB\fB/etc/nsswitch.conf\fR\fR
.ad
.RS 29n
configuration file lookup information for the name server switch
.RE

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

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

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

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

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
MT-Level	MT-Safe
.TE

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