1/* Licensed to the Apache Software Foundation (ASF) under one or more
2 * contributor license agreements.  See the NOTICE file distributed with
3 * this work for additional information regarding copyright ownership.
4 * The ASF licenses this file to You under the Apache License, Version 2.0
5 * (the "License"); you may not use this file except in compliance with
6 * the License.  You may obtain a copy of the License at
7 *
8 *     http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17#ifndef APR_USER_H
18#define APR_USER_H
19
20/**
21 * @file apr_user.h
22 * @brief APR User ID Services
23 */
24
25#include "apr.h"
26#include "apr_errno.h"
27#include "apr_pools.h"
28
29#ifdef __cplusplus
30extern "C" {
31#endif /* __cplusplus */
32
33/**
34 * @defgroup apr_user User and Group ID Services
35 * @ingroup APR
36 * @{
37 */
38
39/**
40 * Structure for determining user ownership.
41 */
42#ifdef WIN32
43typedef PSID                      apr_uid_t;
44#else
45typedef uid_t                     apr_uid_t;
46#endif
47
48/**
49 * Structure for determining group ownership.
50 */
51#ifdef WIN32
52typedef PSID                      apr_gid_t;
53#else
54typedef gid_t                     apr_gid_t;
55#endif
56
57#if APR_HAS_USER
58
59/**
60 * Get the userid (and groupid) of the calling process
61 * @param userid   Returns the user id
62 * @param groupid  Returns the user's group id
63 * @param p The pool from which to allocate working space
64 * @remark This function is available only if APR_HAS_USER is defined.
65 */
66APR_DECLARE(apr_status_t) apr_uid_current(apr_uid_t *userid,
67                                          apr_gid_t *groupid,
68                                          apr_pool_t *p);
69
70/**
71 * Get the user name for a specified userid
72 * @param username Pointer to new string containing user name (on output)
73 * @param userid The userid
74 * @param p The pool from which to allocate the string
75 * @remark This function is available only if APR_HAS_USER is defined.
76 */
77APR_DECLARE(apr_status_t) apr_uid_name_get(char **username, apr_uid_t userid,
78                                           apr_pool_t *p);
79
80/**
81 * Get the userid (and groupid) for the specified username
82 * @param userid   Returns the user id
83 * @param groupid  Returns the user's group id
84 * @param username The username to look up
85 * @param p The pool from which to allocate working space
86 * @remark This function is available only if APR_HAS_USER is defined.
87 */
88APR_DECLARE(apr_status_t) apr_uid_get(apr_uid_t *userid, apr_gid_t *groupid,
89                                      const char *username, apr_pool_t *p);
90
91/**
92 * Get the home directory for the named user
93 * @param dirname Pointer to new string containing directory name (on output)
94 * @param username The named user
95 * @param p The pool from which to allocate the string
96 * @remark This function is available only if APR_HAS_USER is defined.
97 */
98APR_DECLARE(apr_status_t) apr_uid_homepath_get(char **dirname,
99                                               const char *username,
100                                               apr_pool_t *p);
101
102/**
103 * Compare two user identifiers for equality.
104 * @param left One uid to test
105 * @param right Another uid to test
106 * @return APR_SUCCESS if the apr_uid_t structures identify the same user,
107 * APR_EMISMATCH if not, APR_BADARG if an apr_uid_t is invalid.
108 * @remark This function is available only if APR_HAS_USER is defined.
109 */
110#if defined(WIN32)
111APR_DECLARE(apr_status_t) apr_uid_compare(apr_uid_t left, apr_uid_t right);
112#else
113#define apr_uid_compare(left,right) (((left) == (right)) ? APR_SUCCESS : APR_EMISMATCH)
114#endif
115
116/**
117 * Get the group name for a specified groupid
118 * @param groupname Pointer to new string containing group name (on output)
119 * @param groupid The groupid
120 * @param p The pool from which to allocate the string
121 * @remark This function is available only if APR_HAS_USER is defined.
122 */
123APR_DECLARE(apr_status_t) apr_gid_name_get(char **groupname,
124                                             apr_gid_t groupid, apr_pool_t *p);
125
126/**
127 * Get the groupid for a specified group name
128 * @param groupid Pointer to the group id (on output)
129 * @param groupname The group name to look up
130 * @param p The pool from which to allocate the string
131 * @remark This function is available only if APR_HAS_USER is defined.
132 */
133APR_DECLARE(apr_status_t) apr_gid_get(apr_gid_t *groupid,
134                                      const char *groupname, apr_pool_t *p);
135
136/**
137 * Compare two group identifiers for equality.
138 * @param left One gid to test
139 * @param right Another gid to test
140 * @return APR_SUCCESS if the apr_gid_t structures identify the same group,
141 * APR_EMISMATCH if not, APR_BADARG if an apr_gid_t is invalid.
142 * @remark This function is available only if APR_HAS_USER is defined.
143 */
144#if defined(WIN32)
145APR_DECLARE(apr_status_t) apr_gid_compare(apr_gid_t left, apr_gid_t right);
146#else
147#define apr_gid_compare(left,right) (((left) == (right)) ? APR_SUCCESS : APR_EMISMATCH)
148#endif
149
150#endif  /* ! APR_HAS_USER */
151
152/** @} */
153
154#ifdef __cplusplus
155}
156#endif
157
158#endif  /* ! APR_USER_H */
159