1priv_str_to_set(3C) Standard C Library Functions priv_str_to_set(3C)
2
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
11 #include <priv.h>
12 priv_set_t *priv_str_to_set(const char *buf, const char *sep,
14 const char **endptr);
15 char *priv_set_to_str(const priv_set_t *set, char sep, int flag);
18 int priv_getbyname(const char *privname);
21 const char *priv_getbynum(int privnum);
24 int priv_getsetbyname(const char *privsetname);
27 const char *priv_getsetbynum(int privname);
30 char *priv_gettext(const char *privname);
33
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 The application is responsible for freeing the returned privilege set
46 using priv_freeset(3C).
47 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 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 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 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 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 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 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
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 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 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 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
126 The priv_str_to_set() and priv_set_to_str() functions will fail if:
127 ENOMEM The physical limits of the system are exceeded by the memory
129 allocation needed to hold a privilege set.
130 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 All of these functions will fail if:
139 EINVAL One or more of the arguments is invalid.
141
144 Example 1 List all the sets and privileges defined in the system.
145 The following example lists all the sets and privileges defined in the
148 system.
149 #include <priv.h>
152 #include <stdio.h>
153 /* list all the sets and privileges defined in the system */
155 const char *name;
157 int i;
158 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 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
169 See attributes(5) for descriptions of the following attributes:
170 ┌─────────────────────────────┬─────────────────────────────┐
175 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
176 ├─────────────────────────────┼─────────────────────────────┤
177 │Interface Stability │Evolving │
178 ├─────────────────────────────┼─────────────────────────────┤
179 │MT-Level │MT-Safe │
180 └─────────────────────────────┴─────────────────────────────┘
181
183 free(3C), priv_set(3C), attributes(5), privileges(5), priv_getby‐
184 name(9F)
185SunOS 5.11 6 Jan 2004 priv_str_to_set(3C)