1 '\" te
   2 .\" \&.Copyright (c) 2002, Sun Microsystems, Inc.  All Rights Reserved
   3 .\" 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.
   4 .\" 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.
   5 .\" 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]
   6 .TH GETFACL 1 "Nov 5, 1994"
   7 .SH NAME
   8 getfacl \- display discretionary file information
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 \fBgetfacl\fR [\fB-ad\fR] \fIfile\fR...
  13 .fi
  14 
  15 .SH DESCRIPTION
  16 .sp
  17 .LP
  18 For each argument that is a regular file, special file, or named pipe, the
  19 \fBgetfacl\fR utility displays the owner, the group, and the Access Control
  20 List (\fBACL\fR). For each directory argument, \fBgetfacl\fR displays the
  21 owner, the group, and the \fBACL\fR and/or the default \fBACL\fR. Only
  22 directories contain default \fBACL\fRs.
  23 .sp
  24 .LP
  25 The \fBgetfacl\fR utility may be executed on a file system that does not
  26 support \fBACL\fRs. It reports the \fBACL\fR based on the base permission bits.
  27 .sp
  28 .LP
  29 With no options specified, \fBgetfacl\fR displays the filename, the file owner,
  30 the file group owner, and both the \fBACL\fR and the default \fBACL\fR, if it
  31 exists.
  32 .SH OPTIONS
  33 .sp
  34 .LP
  35 The following options are supported:
  36 .sp
  37 .ne 2
  38 .na
  39 \fB\fB-a\fR\fR
  40 .ad
  41 .RS 6n
  42 Displays the filename, the file owner, the file group owner, and the \fBACL\fR
  43 of the file.
  44 .RE
  45 
  46 .sp
  47 .ne 2
  48 .na
  49 \fB\fB-d\fR\fR
  50 .ad
  51 .RS 6n
  52 Displays the filename, the file owner, the file group owner, and the default
  53 \fBACL\fR of the file, if it exists.
  54 .RE
  55 
  56 .SH OPERANDS
  57 .sp
  58 .LP
  59 The following operands are supported:
  60 .sp
  61 .ne 2
  62 .na
  63 \fB\fIfile\fR\fR
  64 .ad
  65 .RS 8n
  66 The path name of a regular file, special file, or named pipe.
  67 .RE
  68 
  69 .SH OUTPUT
  70 .sp
  71 .LP
  72 The format for \fBACL\fR output is as follows:
  73 .sp
  74 .in +2
  75 .nf
  76 # file: filename        
  77 # owner: uid    
  78 # group: gid    
  79 user::perm      
  80 user:uid:perm   
  81 group::perm     
  82 group:gid:perm  
  83 mask:perm       
  84 other:perm      
  85 default:user::perm      
  86 default:user:uid:perm   
  87 default:group::perm     
  88 default:group:gid:perm  
  89 default:mask:perm       
  90 default:other:perm
  91 .fi
  92 .in -2
  93 .sp
  94 
  95 .sp
  96 .LP
  97 When multiple files are specified on the command line, a blank line separates
  98 the \fBACL\fRs for each file.
  99 .sp
 100 .LP
 101 The \fBACL\fR entries are displayed in the order in which they are evaluated
 102 when an access check is performed. The default \fBACL\fR entries that may exist
 103 on a directory have no effect on access checks.
 104 .sp
 105 .LP
 106 The first three lines display the filename, the file owner, and the file group
 107 owner. Notice that when only the \fB-d\fR option is specified and the file has
 108 no default \fBACL\fR, only these three lines are displayed.
 109 .sp
 110 .LP
 111 The \fBuser\fR entry without a user \fBID\fR indicates the permissions that
 112 are granted to the file owner. One or more additional user entries indicate the
 113 permissions that are granted to the specified users.
 114 .sp
 115 .LP
 116 The \fBgroup\fR entry without a group \fBID\fR indicates the permissions that
 117 are granted to the file group owner. One or more additional group entries
 118 indicate the permissions that  are granted to the specified groups.
 119 .sp
 120 .LP
 121 The \fBmask\fR entry indicates the \fBACL\fR mask permissions. These are the
 122 maximum permissions allowed to any user entries except the file owner, and to
 123 any group entries, including the file group owner. These permissions restrict
 124 the permissions specified in other entries.
 125 .sp
 126 .LP
 127 The \fBother\fR entry indicates the permissions that are granted to others.
 128 .sp
 129 .LP
 130 The \fBdefault\fR entries may exist only for directories. These entries
 131 indicate the default entries that are added to a file created within the
 132 directory.
 133 .sp
 134 .LP
 135 The \fBuid\fR is a login name or a user \fBID\fR if there is no entry for the
 136 \fBuid\fR in the system password file, \fB/etc/passwd\fR. The \fBgid\fR is a
 137 group name or a group \fBID\fR if there is no entry for the \fBgid\fR in the
 138 system group file, \fB/etc/group\fR. The \fBperm\fR is a three character string
 139 composed of the letters representing the separate discretionary access rights:
 140 \fBr\fR (read), \fBw\fR (write), \fBx\fR (execute/search), or the place holder
 141 character \fB\(mi\fR\&. The \fBperm\fR is displayed in the following order:
 142 \fBrwx\fR. If a permission is not granted by an \fBACL\fR entry, the place
 143 holder character appears.
 144 .sp
 145 .LP
 146 If  you use the \fBchmod\fR(1) command to change the file group owner
 147 permissions on a file with \fBACL\fR entries, both the file group owner
 148 permissions and the \fBACL\fR mask are changed to the new permissions. Be aware
 149 that the new \fBACL\fR mask permissions may change the effective permissions
 150 for additional users and groups who have \fBACL\fR entries on the file.
 151 .sp
 152 .LP
 153 In order to indicate that the \fBACL\fR mask  restricts an \fBACL\fR entry,
 154 \fBgetfacl\fR displays an additional tab character, pound sign (\fB#\fR), and
 155 the actual permissions granted, following the entry.
 156 .SH EXAMPLES
 157 .LP
 158 \fBExample 1 \fRDisplaying file information
 159 .sp
 160 .LP
 161 Given file \fBfoo\fR, with an \fBACL\fR six entries long, the command
 162 
 163 .sp
 164 .in +2
 165 .nf
 166 host% \fBgetfacl foo\fR
 167 .fi
 168 .in -2
 169 .sp
 170 
 171 .sp
 172 .LP
 173 would print:
 174 
 175 .sp
 176 .in +2
 177 .nf
 178 # file: foo
 179 # owner: shea
 180 # group: staff
 181 user::rwx
 182 user:spy:\|\(mi\|\(mi\|\(mi
 183 user:mookie:r\|\(mi\|\(mi
 184 group::r\|\(mi\|\(mi
 185 mask::rw\|\(mi
 186 other::\|\(mi\|\(mi\|\(mi
 187 .fi
 188 .in -2
 189 .sp
 190 
 191 .LP
 192 \fBExample 2 \fRDisplaying information after chmod command
 193 .sp
 194 .LP
 195 Continue with the above example, after \fBchmod\fR \fB700 foo\fR was issued:
 196 
 197 .sp
 198 .in +2
 199 .nf
 200 host% \fBgetfacl foo\fR
 201 .fi
 202 .in -2
 203 .sp
 204 
 205 .sp
 206 .LP
 207 would print:
 208 
 209 .sp
 210 .in +2
 211 .nf
 212 # file: foo
 213 # owner: shea
 214 # group: staff
 215 user::rwx
 216 user:spy:\|\(mi\|\(mi\|\(mi
 217 user:mookie:r\|\(mi\|\(mi     #effective:\|\(mi\|\(mi\|\(mi
 218 group::\|\(mi\|\(mi\|\(mi
 219 mask::\|\(mi\|\(mi\|\(mi
 220 other::\|\(mi\|\(mi\|\(mi
 221 .fi
 222 .in -2
 223 .sp
 224 
 225 .LP
 226 \fBExample 3 \fRDisplaying information when ACL contains default entries
 227 .sp
 228 .LP
 229 Given directory \fBdoo\fR, with an \fBACL\fR containing default entries, the
 230 command
 231 
 232 .sp
 233 .in +2
 234 .nf
 235 host% \fBgetfacl -d doo\fR
 236 .fi
 237 .in -2
 238 .sp
 239 
 240 .sp
 241 .LP
 242 would print:
 243 
 244 .sp
 245 .in +2
 246 .nf
 247 # file: doo
 248 # owner: shea
 249 # group: staff
 250 default:user::rwx
 251 default:user:spy:\|\(mi\|\(mi\|\(mi
 252 default:user:mookie:r\|\(mi\|\(mi
 253 default:group::r\|\(mi\|\(mi
 254 default:mask::\|\(mi\|\(mi\|\(mi
 255 default:other::\|\(mi\|\(mi\|\(mi
 256 .fi
 257 .in -2
 258 .sp
 259 
 260 .SH FILES
 261 .sp
 262 .ne 2
 263 .na
 264 \fB\fB/etc/passwd\fR\fR
 265 .ad
 266 .RS 15n
 267 system password file
 268 .RE
 269 
 270 .sp
 271 .ne 2
 272 .na
 273 \fB\fB/etc/group\fR\fR
 274 .ad
 275 .RS 15n
 276 group file
 277 .RE
 278 
 279 .SH ATTRIBUTES
 280 .sp
 281 .LP
 282 See \fBattributes\fR(5) for descriptions of the following attributes:
 283 .sp
 284 
 285 .sp
 286 .TS
 287 box;
 288 c | c
 289 l | l .
 290 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 291 _
 292 Interface Stability     Evolving
 293 .TE
 294 
 295 .SH SEE ALSO
 296 .sp
 297 .LP
 298 \fBchmod\fR(1), \fBls\fR(1), \fBsetfacl\fR(1), \fBacl\fR(2),
 299 \fBaclsort\fR(3SEC), \fBgroup\fR(4), \fBpasswd\fR(4), \fBattributes\fR(5)
 300 .SH NOTES
 301 .sp
 302 .LP
 303 The output from \fBgetfacl\fR is in the correct format for input to the
 304 \fBsetfacl\fR \fB-f\fR command. If the output from \fBgetfacl\fR is redirected
 305 to a file, the file may be used as input to \fBsetfacl\fR. In this way, a user
 306 may easily assign one file's \fBACL\fR to another file.