1priv_str_to_set(3C)      Standard C Library Functions      priv_str_to_set(3C)
2
3
4

NAME

6       priv_str_to_set,    priv_set_to_str,   priv_getbyname,   priv_getbynum,
7       priv_getsetbyname,  priv_getsetbynum,  priv_gettext  -  privilege  name
8       functions
9

SYNOPSIS

11       #include <priv.h>
12
13       priv_set_t *priv_str_to_set(const char *buf, const char *sep,
14            const char **endptr);
15
16
17       char *priv_set_to_str(const priv_set_t *set, char sep, int flag);
18
19
20       int priv_getbyname(const char *privname);
21
22
23       const char *priv_getbynum(int privnum);
24
25
26       int priv_getsetbyname(const char *privsetname);
27
28
29       const char *priv_getsetbynum(int privname);
30
31
32       char *priv_gettext(const char *privname);
33
34

DESCRIPTION

36       The  priv_str_to_set() function maps the privilege specification in buf
37       to a privilege set. It returns a privilege set on success  or  NULL  on
38       failure.  If  an error occurs when parsing the string, a pointer to the
39       remainder of the string is stored in the object pointed to  by  endptr,
40       provided  that  endptr  is  not a null pointer. If an error occurs when
41       allocating memory, errno is set and the object pointed to by endptr  is
42       set to the null pointer, provided that endptr is not a null pointer.
43
44
45       The  application  is responsible for freeing the returned privilege set
46       using priv_freeset(3C).
47
48
49       A privilege specification should contain one or more  privilege  names,
50       separated  by characters in sep using the same algorithm as strtok(3C).
51       Privileges can optionally be preceded by a dash (-) or  an  exclamation
52       mark  (!),  in which case they are excluded from the resulting set. The
53       special strings "none" for the empty set, "all"  for  the  set  of  all
54       privileges,  "zone"  for the set of all privileges available within the
55       caller's zone, and "basic" for the set of  basic  privileges  are  also
56       recognized. Set specifications are interpreted from left to right.
57
58
59       The priv_set_to_str() function converts the privilege set to a sequence
60       of privileges separated by sep, returning the a pointer to the  dynami‐
61       cally  allocated result. The application is responsible for freeing the
62       memory using free(3C).
63
64
65       To maintain future compatibility, the  "basic"  set  of  privileges  is
66       included  as  "basic,!missing_basic_priv1,...".  When further currently
67       unprivileged operations migrate to the basic privilege set, the conver‐
68       sion  back of the result with priv_str_to_set() includes the additional
69       basic privileges, guaranteeing that the resulting privilege set carries
70       the  same privileges. This behavior is the default and is equivalent to
71       specifying a flag argument of PRIV_STR_PORT.  When  specifying  a  flag
72       argument  of  PRIV_STR_LIT,  the result does not treat basic privileges
73       differently and the privileges present are all literally  presented  in
74       the output. A flag argument of PRIV_STR_SHORT attempts to arrive at the
75       shortest output, using the tokens "basic", "zone", "all",  and  negated
76       privileges. This output is most useful for trace output.
77
78
79       The  priv_getbyname()  and  priv_getsetbyname() functions map privilege
80       names and privilege set names to  numbers.  The  numbers  returned  are
81       valid for the current kernel instance only and could change at the next
82       boot. Only the privilege names should be committed to persistent  stor‐
83       age.  The  numbers  should not be committed to persistent storage. Both
84       functions return -1 on error, setting errno to EINVAL.
85
86
87       The priv_getbynum() and  priv_getsetbynum()  functions  map  privileges
88       numbers  to  names.  The  strings returned point to shared storage that
89       should not be modified and is valid for the lifetime  of  the  process.
90       Both functions return NULL on error, setting errno to EINVAL.
91
92
93       The priv_gettext() function returns a pointer to a string consisting of
94       one or more newline-separated lines of text describing  the  privilege.
95       The  text  is localized using {LC_MESSAGES}. The application is respon‐
96       sibe for freeing the memory returned.
97
98
99       These functions pick up privileges allocated during the lifetime of the
100       process using priv_getbyname(9F) by refreshing the internal data struc‐
101       tures when necessary.
102

RETURN VALUES

104       Upon successful  completion,  priv_str_to_set()  and  priv_set_to_str()
105       return  a  non-null pointer to allocated memory that should be freed by
106       the application using the appropriate functions when it  is  no  longer
107       referenced.
108
109
110       The  priv_getbynum()  and  priv_getsetbynum() functions return non-null
111       pointers to constant memory that should not be modified or freed by the
112       application.  Otherwise,  NULL is returned and errno is set to indicate
113       the error.
114
115
116       Upon successful completion,  priv_getbyname()  and  priv_getsetbyname()
117       return  a  non-negative integer. Otherwise, -1 is returned and errno is
118       set to indicate the error.
119
120
121       Upon successful completion, priv_gettext() returns a non-null value. It
122       returns  NULL  if an error occurs or no descriptive text for the speci‐
123       fied privilege can be found.
124

ERRORS

126       The priv_str_to_set() and priv_set_to_str() functions will fail if:
127
128       ENOMEM    The physical limits of the system are exceeded by the  memory
129                 allocation needed to hold a privilege set.
130
131
132       EAGAIN    There  is  not enough memory available to allocate sufficient
133                 memory to hold a privilege set, but the application could try
134                 again later.
135
136
137
138       All of these functions will fail if:
139
140       EINVAL    One or more of the arguments is invalid.
141
142

EXAMPLES

144       Example 1 List all the sets and privileges defined in the system.
145
146
147       The  following example lists all the sets and privileges defined in the
148       system.
149
150
151         #include <priv.h>
152         #include <stdio.h>
153
154         /* list all the sets and privileges defined in the system */
155
156         const char *name;
157         int i;
158
159         printf("Each process has the following privilege sets:\n");
160         for (i = 0; (name = priv_getsetbynum(i++)) != NULL; )
161                 printf("\t%s\n", name);
162
163         printf("Each set can contain the following privileges:\n");
164         for (i = 0; (name = priv_getbynum(i++)) != NULL; )
165                 printf("\t%s\n", name);
166
167

ATTRIBUTES

169       See attributes(5) for descriptions of the following attributes:
170
171
172
173
174       ┌─────────────────────────────┬─────────────────────────────┐
175       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
176       ├─────────────────────────────┼─────────────────────────────┤
177       │Interface Stability          │Evolving                     │
178       ├─────────────────────────────┼─────────────────────────────┤
179       │MT-Level                     │MT-Safe                      │
180       └─────────────────────────────┴─────────────────────────────┘
181

SEE ALSO

183       free(3C),  priv_set(3C),  attributes(5),   privileges(5),   priv_getby‐
184       name(9F)
185
186
187
188SunOS 5.11                        6 Jan 2004               priv_str_to_set(3C)
Impressum