git.saurik.com Git - apple/xnu.git/blob

3 .\"

4 .\" Redistribution and use in source and binary forms, with or without

5 .\" modification, are permitted provided that the following conditions

6 .\" are met:

7 .\" 1. Redistributions of source code must retain the above copyright

8 .\" notice, this list of conditions and the following disclaimer.

9 .\" 2. Redistributions in binary form must reproduce the above copyright

10 .\" notice, this list of conditions and the following disclaimer in the

11 .\" documentation and/or other materials provided with the distribution.

12 .\" 4. Neither the name of the University nor the names of its contributors

13 .\" may be used to endorse or promote products derived from this software

14 .\" without specific prior written permission.

15 .\"

16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND

17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE

18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE

19 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE

20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL

21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS

22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)

23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT

24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY

25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF

26 .\" SUCH DAMAGE.

27 .\"

28 .\" @(#)access.2 8.2 (Berkeley) 4/1/94

29 .\" $FreeBSD$

30 .\"

31 .Dd September 15, 2014

32 .Dt ACCESS 2

33 .Os

34 .Sh NAME

35 .Nm access ,

36 .Nm faccessat

37 .Nd check accessibility of a file

38 .Sh SYNOPSIS

39 .In unistd.h

40 .Ft int

41 .Fn access "const char *path" "int mode"

42 .Ft int

43 .Fn faccessat "int fd" "const char *path" "int mode" "int flag"

44 .Sh DESCRIPTION

45 The

46 .Fn access

47 system call checks the accessibility of the

48 file named by

49 the

50 .Fa path

51 argument

52 for the access permissions indicated by

53 the

54 .Fa mode

55 argument.

56 The value of

57 .Fa mode

58 is either the bitwise-inclusive OR of the access permissions to be

59 checked

60 .Dv ( R_OK

61 for read permission,

62 .Dv W_OK

63 for write permission, and

64 .Dv X_OK

65 for execute/search permission),

66 or the existence test

67 .Pq Dv F_OK .

68 .Pp

69 For additional information, see the

70 .Sx "File Access Permission"

71 section of

72 .Xr intro 2 .

73 .Pp

74 The

75 .Fn access

76 system call uses

77 the real user ID in place of the effective user ID,

78 the real group ID in place of the effective group ID,

79 and the rest of the group access list.

80 .Pp

81 The

82 .Fn faccessat

83 system call is equivalent to

84 .Fn access

85 except in the case where

86 .Fa path

87 specifies a relative path.

88 In this case the file whose accessibility is to be determined is

89 located relative to the directory associated with the file descriptor

90 .Fa fd

91 instead of the current working directory.

92 If

93 .Fn faccessat

94 is passed the special value

95 .Dv AT_FDCWD

96 in the

97 .Fa fd

98 parameter, the current working directory is used and the behavior is

99 identical to a call to

100 .Fn access .

101 Values for

102 .Fa flag

103 are constructed by a bitwise-inclusive OR of flags from the following

104 list, defined in

105 .In fcntl.h :

106 .Bl -tag -width indent

107 .It Dv AT_EACCESS

108 The checks for accessibility are performed using the effective user and group

109 IDs instead of the real user and group ID as required in a call to

110 .Fn access .

111 .El

112 .Bl -tag -width indent

113 .It Dv AT_SYMLINK_NOFOLLOW

114 If

115 .Fa path

116 names a symbolic link, the status of the symbolic link is returned.

117 .El

118 .Pp

119 Even if a process has appropriate privileges and indicates success for

120 .Dv X_OK ,

121 the file may not actually have execute permission bits set.

122 Likewise for

123 .Dv R_OK

124 and

125 .Dv W_OK .

126 .Sh RETURN VALUES

127 .Rv -std

128 .Sh ERRORS

129 .Fn access

130 or

131 .Fn faccessat

132 will fail if:

133 .Bl -tag -width Er

134 .It Bq Er EINVAL

135 The value of the

136 .Fa mode

137 argument is invalid.

138 .It Bq Er ENOTDIR

139 A component of the path prefix is not a directory.

140 .It Bq Er ENAMETOOLONG

141 A component of a pathname exceeded

142 .Dv {NAME_MAX}

143 characters, or an entire path name exceeded

144 .Dv {PATH_MAX}

145 characters.

146 .It Bq Er ENOENT

147 The named file does not exist.

148 .It Bq Er ELOOP

149 Too many symbolic links were encountered in translating the pathname.

150 .It Bq Er EROFS

151 Write access is requested for a file on a read-only file system.

152 .It Bq Er ETXTBSY

153 Write access is requested for a pure procedure (shared text)

154 file presently being executed.

155 .It Bq Er EACCES

156 Permission bits of the file mode do not permit the requested

157 access, or search permission is denied on a component of the

158 path prefix.

159 .It Bq Er EFAULT

160 The

161 .Fa path

162 argument

163 points outside the process's allocated address space.

164 .It Bq Er EIO

165 An I/O error occurred while reading from or writing to the file system.

166 .El

167 .Pp

168 Also, the

169 .Fn faccessat

170 system call may fail if:

171 .Bl -tag -width Er

172 .It Bq Er EBADF

173 The

174 .Fa path

175 argument does not specify an absolute path and the

176 .Fa fd

177 argument is

178 neither

179 .Dv AT_FDCWD

180 nor a valid file descriptor.

181 .It Bq Er EINVAL

182 The value of the

183 .Fa flag

184 argument is not valid.

185 .It Bq Er ENOTDIR

186 The

187 .Fa path

188 argument is not an absolute path and

189 .Fa fd

190 is neither

191 .Dv AT_FDCWD

192 nor a file descriptor associated with a directory.

193 .El

194 .Sh SEE ALSO

195 .Xr chmod 2 ,

196 .Xr intro 2 ,

197 .Xr stat 2

198 .Sh STANDARDS

199 The

200 .Fn access

201 system call is expected to conform to

202 .St -p1003.1-90 .

203 The

204 .Fn faccessat

205 system call is expected to conform to POSIX.1-2008 .

206 .Sh HISTORY

207 The

208 .Fn access

209 function appeared in

210 .At v7 .

211 .Sh SECURITY CONSIDERATIONS

212 The result of

213 .Fn access

214 should not be used to make an actual access control decision, since its

215 response, even if correct at the moment it is formed, may be outdated at the

216 time you act on it.

217 .Fn access

218 results should only be used to pre-flight, such as when configuring user

219 interface elements or for optimization purposes. The actual access control

220 decision should be made by attempting to execute the relevant system call while

221 holding the applicable credentials, and properly handling any resulting errors;

222 and this must be done even though

223 .Fn access

224 may have predicted success.

225 .Pp

226 Additionally, set-user-ID and set-group-ID applications should restore the

227 effective user or group ID,

228 and perform actions directly rather than use

229 .Fn access

230 to simulate access checks for the real user or group ID.