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