lib/libc/sys/chflags.2

   1 .\" Copyright (c) 1989, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   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 .\"     @(#)chflags.2   8.3 (Berkeley) 5/2/95
  29 .\" $FreeBSD$
  30 .\"
  31 .Dd May 16, 2006
  32 .Dt CHFLAGS 2
  33 .Os
  34 .Sh NAME
  35 .Nm chflags ,
  36 .Nm lchflags ,
  37 .Nm fchflags
  38 .Nd set file flags
  39 .Sh LIBRARY
  40 .Lb libc
  41 .Sh SYNOPSIS
  42 .In sys/stat.h
  43 .In unistd.h
  44 .Ft int
  45 .Fn chflags "const char *path" "u_long flags"
  46 .Ft int
  47 .Fn lchflags "const char *path" "int flags"
  48 .Ft int
  49 .Fn fchflags "int fd" "u_long flags"
  50 .Sh DESCRIPTION
  51 The file whose name
  52 is given by
  53 .Fa path
  54 or referenced by the descriptor
  55 .Fa fd
  56 has its flags changed to
  57 .Fa flags .
  58 .Pp
  59 The
  60 .Fn lchflags
  61 system call is like
  62 .Fn chflags
  63 except in the case where the named file is a symbolic link,
  64 in which case
  65 .Fn lchflags
  66 will change the flags of the link itself,
  67 rather than the file it points to.
  68 .Pp
  69 The flags specified are formed by
  70 .Em or Ns 'ing
  71 the following values
  72 .Pp
  73 .Bl -tag -width ".Dv SF_IMMUTABLE" -compact -offset indent
  74 .It Dv UF_NODUMP
  75 Do not dump the file.
  76 .It Dv UF_IMMUTABLE
  77 The file may not be changed.
  78 .It Dv UF_APPEND
  79 The file may only be appended to.
  80 .It Dv UF_NOUNLINK
  81 The file may not be renamed or deleted.
  82 .It Dv UF_OPAQUE
  83 The directory is opaque when viewed through a union stack.
  84 .It Dv SF_ARCHIVED
  85 The file may be archived.
  86 .It Dv SF_IMMUTABLE
  87 The file may not be changed.
  88 .It Dv SF_APPEND
  89 The file may only be appended to.
  90 .It Dv SF_NOUNLINK
  91 The file may not be renamed or deleted.
  92 .It Dv SF_SNAPSHOT
  93 The file is a snapshot file.
  94 .El
  95 .Pp
  96 If one of
  97 .Dv SF_IMMUTABLE , SF_APPEND ,
  98 or
  99 .Dv SF_NOUNLINK
 100 is set a non-super-user cannot change any flags and even the super-user
 101 can change flags only if securelevel is greater than 0.
 102 (See
 103 .Xr init 8
 104 for details.)
 105 .Pp
 106 The
 107 .Dv UF_IMMUTABLE , UF_APPEND , UF_NOUNLINK , UF_NODUMP ,
 108 and
 109 .Dv UF_OPAQUE
 110 flags may be set or unset by either the owner of a file or the super-user.
 111 .Pp
 112 The
 113 .Dv SF_IMMUTABLE , SF_APPEND , SF_NOUNLINK ,
 114 and
 115 .Dv SF_ARCHIVED
 116 flags may only be set or unset by the super-user.
 117 Attempts to set these flags by non-super-users are rejected, attempts by
 118 non-superusers to clear flags that are already unset are silently ignored.
 119 These flags may be set at any time, but normally may only be unset when
 120 the system is in single-user mode.
 121 (See
 122 .Xr init 8
 123 for details.)
 124 .Pp
 125 The
 126 .Dv SF_SNAPSHOT
 127 flag is maintained by the system and cannot be changed by any user.
 128 .Sh RETURN VALUES
 129 .Rv -std
 130 .Sh ERRORS
 131 The
 132 .Fn chflags
 133 system call will fail if:
 134 .Bl -tag -width Er
 135 .It Bq Er ENOTDIR
 136 A component of the path prefix is not a directory.
 137 .It Bq Er ENAMETOOLONG
 138 A component of a pathname exceeded 255 characters,
 139 or an entire path name exceeded 1023 characters.
 140 .It Bq Er ENOENT
 141 The named file does not exist.
 142 .It Bq Er EACCES
 143 Search permission is denied for a component of the path prefix.
 144 .It Bq Er ELOOP
 145 Too many symbolic links were encountered in translating the pathname.
 146 .It Bq Er EPERM
 147 The effective user ID does not match the owner of the file and
 148 the effective user ID is not the super-user.
 149 .It Bq Er EPERM
 150 One of
 151 .Dv SF_IMMUTABLE , SF_APPEND ,
 152 or
 153 .Dv SF_NOUNLINK
 154 is set and the user is either not the super-user or
 155 securelevel is greater than 0.
 156 .It Bq Er EPERM
 157 A non-super-user tries to set one of
 158 .Dv SF_IMMUTABLE , SF_APPEND ,
 159 or
 160 .Dv SF_NOUNLINK .
 161 .It Bq Er EPERM
 162 User tries to set or remove the
 163 .Dv SF_SNAPSHOT
 164 flag.
 165 .It Bq Er EROFS
 166 The named file resides on a read-only file system.
 167 .It Bq Er EFAULT
 168 The
 169 .Fa path
 170 argument
 171 points outside the process's allocated address space.
 172 .It Bq Er EIO
 173 An
 174 .Tn I/O
 175 error occurred while reading from or writing to the file system.
 176 .It Bq Er EOPNOTSUPP
 177 The underlying file system does not support file flags.
 178 .El
 179 .Pp
 180 The
 181 .Fn fchflags
 182 system call will fail if:
 183 .Bl -tag -width Er
 184 .It Bq Er EBADF
 185 The descriptor is not valid.
 186 .It Bq Er EINVAL
 187 The
 188 .Fa fd
 189 argument
 190 refers to a socket, not to a file.
 191 .It Bq Er EPERM
 192 The effective user ID does not match the owner of the file and
 193 the effective user ID is not the super-user.
 194 .It Bq Er EPERM
 195 One of
 196 .Dv SF_IMMUTABLE , SF_APPEND ,
 197 or
 198 .Dv SF_NOUNLINK
 199 is set and the user is either not the super-user or
 200 securelevel is greater than 0.
 201 .It Bq Er EPERM
 202 A non-super-user tries to set one of
 203 .Dv SF_IMMUTABLE , SF_APPEND ,
 204 or
 205 .Dv SF_NOUNLINK .
 206 .It Bq Er EROFS
 207 The file resides on a read-only file system.
 208 .It Bq Er EIO
 209 An
 210 .Tn I/O
 211 error occurred while reading from or writing to the file system.
 212 .It Bq Er EOPNOTSUPP
 213 The underlying file system does not support file flags.
 214 .El
 215 .Sh SEE ALSO
 216 .Xr chflags 1 ,
 217 .Xr fflagstostr 3 ,
 218 .Xr strtofflags 3 ,
 219 .Xr init 8 ,
 220 .Xr mount_unionfs 8
 221 .Sh HISTORY
 222 The
 223 .Fn chflags
 224 and
 225 .Fn fchflags
 226 system calls first appeared in
 227 .Bx 4.4 .