usr.bin/chflags/chflags.1

   1 .\"-
   2 .\" Copyright (c) 1989, 1990, 1993, 1994
   3 .\"     The Regents of the University of California.  All rights reserved.
   4 .\"
   5 .\" This code is derived from software contributed to Berkeley by
   6 .\" the Institute of Electrical and Electronics Engineers, Inc.
   7 .\"
   8 .\" Redistribution and use in source and binary forms, with or without
   9 .\" modification, are permitted provided that the following conditions
  10 .\" are met:
  11 .\" 1. Redistributions of source code must retain the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer.
  13 .\" 2. Redistributions in binary form must reproduce the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer in the
  15 .\"    documentation and/or other materials provided with the distribution.
  16 .\" 3. All advertising materials mentioning features or use of this software
  17 .\"    must display the following acknowledgement:
  18 .\"     This product includes software developed by the University of
  19 .\"     California, Berkeley and its contributors.
  20 .\" 4. Neither the name of the University nor the names of its contributors
  21 .\"    may be used to endorse or promote products derived from this software
  22 .\"    without specific prior written permission.
  23 .\"
  24 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  25 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  26 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  27 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  28 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  29 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  30 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  31 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  32 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  33 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  34 .\" SUCH DAMAGE.
  35 .\"
  36 .\"     @(#)chflags.1   8.4 (Berkeley) 5/2/95
  37 .\" $FreeBSD: src/bin/chflags/chflags.1,v 1.30 2008/03/09 12:10:24 rwatson Exp $
  38 .\" $DragonFly: src/usr.bin/chflags/chflags.1,v 1.8 2008/11/12 15:18:26 swildner Exp $
  39 .\"
  40 .Dd November 11, 2008
  41 .Dt CHFLAGS 1
  42 .Os
  43 .Sh NAME
  44 .Nm chflags
  45 .Nd change file flags
  46 .Sh SYNOPSIS
  47 .Nm
  48 .Op Fl fhv
  49 .Oo
  50 .Fl R
  51 .Op Fl H | Fl L | Fl P
  52 .Oc
  53 .Ar flags
  54 .Ar
  55 .Sh DESCRIPTION
  56 The
  57 .Nm
  58 utility modifies the file flags of the listed files
  59 as specified by the
  60 .Ar flags
  61 operand.
  62 .Pp
  63 The options are as follows:
  64 .Bl -tag -width indent
  65 .It Fl f
  66 Do not display a diagnostic message if
  67 .Nm
  68 could not modify the flags for
  69 .Va file ,
  70 nor modify the exit status to reflect such failures.
  71 .It Fl H
  72 If the
  73 .Fl R
  74 option is specified, symbolic links on the command line are followed.
  75 (Symbolic links encountered in the tree traversal are not followed.)
  76 .It Fl h
  77 If the
  78 .Ar file
  79 is a symbolic link,
  80 change the file flags of the link itself rather than the file to which
  81 it points.
  82 .It Fl L
  83 If the
  84 .Fl R
  85 option is specified, all symbolic links are followed.
  86 .It Fl P
  87 If the
  88 .Fl R
  89 option is specified, no symbolic links are followed.
  90 This is the default.
  91 .It Fl R
  92 Change the file flags for the file hierarchies rooted
  93 in the files instead of just the files themselves.
  94 .It Fl v
  95 Cause
  96 .Nm
  97 to be verbose, showing filenames as the flags are modified.
  98 If the
  99 .Fl v
 100 option is specified more than once, the old and new flags of the file
 101 will also be printed, in octal notation.
 102 .El
 103 .Pp
 104 The flags are specified as an octal number or a comma separated list
 105 of keywords.
 106 The following keywords are currently defined:
 107 .Bl -tag -offset indent -width ".Cm nouhistory"
 108 .It Cm arch , archived
 109 set the archived flag (super-user only)
 110 .It Cm opaque
 111 set the opaque flag (owner or super-user only)
 112 .It Cm nodump
 113 set the nodump flag (owner or super-user only)
 114 .It Cm noshistory
 115 set the system nohistory flag (super-user only)
 116 .It Cm nouhistory , nohistory
 117 set the user nohistory flag (owner or super-user only)
 118 .It Cm sappnd , sappend
 119 set the system append-only flag (super-user only)
 120 .It Cm schg , schange , simmutable
 121 set the system immutable flag (super-user only)
 122 .It Cm sunlnk , sunlink
 123 set the system undeletable flag (super-user only)
 124 .It Cm uappnd , uappend
 125 set the user append-only flag (owner or super-user only)
 126 .It Cm uchg , uchange , uimmutable
 127 set the user immutable flag (owner or super-user only)
 128 .It Cm uunlnk , uunlink
 129 set the user undeletable flag (owner or super-user only)
 130 .It Cm cache , ucache
 131 control the data
 132 .Xr swapcache 8
 133 (recursive, does not cross mounts) (owner or super-user only)
 134 .It Cm noscache
 135 control the data
 136 .Xr swapcache 8
 137 (recursive, does not cross mounts) (super-user only)
 138 .El
 139 .Pp
 140 If a
 141 .Dq Cm no
 142 prefix is added or removed from a keyword, the meaning is negated.
 143 For example:
 144 .Pp
 145 .Bl -tag -offset indent -width "nouchg" -compact
 146 .It Cm nouchg
 147 clear the user immutable flag (owner or super-user only)
 148 .It Cm dump
 149 clear the nodump flag (owner or super-user only)
 150 .El
 151 .Pp
 152 A few of the octal values include:
 153 .Bl -tag -offset indent -width ".Li 10"
 154 .It Li 0
 155 Clear all file flags.
 156 .It Li 1
 157 Translates to the
 158 .Cm nodump
 159 keyword.
 160 .It Li 2
 161 Translates to the
 162 .Cm uchg
 163 keyword.
 164 .It Li 3
 165 Translates to the
 166 .Cm uchg , nodump
 167 keywords.
 168 .It Li 4
 169 Translates to the
 170 .Cm uappnd
 171 keyword.
 172 .It Li 10
 173 Translates to the
 174 .Cm opaque
 175 keyword.
 176 .It Li 20
 177 translates to the
 178 .Cm uunlnk
 179 keyword.
 180 .El
 181 .Pp
 182 Other combinations of keywords may be placed by using
 183 the octets assigned; however, these are the most notable.
 184 .Pp
 185 Unless the
 186 .Fl H ,
 187 .Fl L ,
 188 or
 189 .Fl h
 190 options are given,
 191 .Nm
 192 on a symbolic link always succeeds and has no effect.
 193 The
 194 .Fl H ,
 195 .Fl L
 196 and
 197 .Fl P
 198 options are ignored unless the
 199 .Fl R
 200 option is specified.
 201 In addition, these options override each other and the
 202 command's actions are determined by the last one specified.
 203 .Pp
 204 You can use
 205 .Dq Li "ls -lo"
 206 to see the flags of existing files.
 207 .Pp
 208 Note that the ability to change certain flags is dependent
 209 on the current kernel
 210 .Va securelevel
 211 setting.
 212 See
 213 .Xr security 7
 214 for more information on this setting.
 215 .Sh SWAPCACHE FLAGS
 216 The
 217 .Cm cache
 218 bit may be set to enable
 219 .Xr swapcache 8
 220 data caching.
 221 The superuser flag,
 222 .Cm noscache
 223 may be used to disable
 224 .Xr swapcache 8
 225 data caching and overrides the user flag.
 226 .Pp
 227 The flag is recursive but does not cross mount points.
 228 Setting it on a top-level directories or mount point will
 229 automatically apply the flag to the entire subtree or until
 230 a mount point is hit.
 231 You may have to refresh the namecache with a dummy
 232 .Xr find 1
 233 command after changing the flag in a top level directory.
 234 You do not have to recursive set the flag with
 235 .Nm
 236 .Fl R
 237 and, in fact, we do not recommend it under any circumstances.
 238 Filesystems which do not support flags generally have a
 239 .Cm cache
 240 mount option to enable swapcache operation on the mount.
 241 .Pp
 242 If you intend to use swapcache data the
 243 .Cm vm.swapcache.use_chflags
 244 sysctl determines whether the
 245 .Nm
 246 flags are used or not.
 247 If turned off and
 248 .Cm vm.swapcache.data_enable
 249 is turned on, data caching is turned on globally and the
 250 file flags are ignored.
 251 If
 252 .Cm use_chflags
 253 is turned on along with
 254 .Cm data_enable
 255 then only subtrees marked cacheable will be swapcached.
 256 .Pp
 257 You would typically want to enable the cache on
 258 .Pa /usr , /home ,
 259 and
 260 .Pa /bin
 261 and disable it for
 262 .Pa /usr/obj .
 263 Alternatively if you want to cache
 264 NFS mounts (where
 265 .Nm
 266 doesn't work), you can set the flag on
 267 some parent directory, possibly even the root
 268 .Pq Pa /
 269 itself,
 270 and then selectively disable it in places where you don't want it.
 271 .Pp
 272 This only applies to data caching.
 273 Meta-data caching is universal when enabled.
 274 .Sh EXIT STATUS
 275 .Ex -std
 276 .Sh SEE ALSO
 277 .Xr ls 1 ,
 278 .Xr chflags 2 ,
 279 .Xr stat 2 ,
 280 .Xr fts 3 ,
 281 .Xr security 7 ,
 282 .Xr symlink 7 ,
 283 .Xr swapcache 8
 284 .Sh HISTORY
 285 The
 286 .Nm
 287 command first appeared in
 288 .Bx 4.4 .
 289 .Sh BUGS
 290 Only a limited number of utilities are
 291 .Nm
 292 aware.
 293 Some of these tools include
 294 .Xr ls 1 ,
 295 .Xr cp 1 ,
 296 .Xr find 1 ,
 297 .Xr install 1 ,
 298 .Xr dump 8 ,
 299 and
 300 .Xr restore 8 .
 301 In particular a tool which is not currently
 302 .Nm
 303 aware is the
 304 .Xr pax 1
 305 utility.