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 .\" 3. 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: src/lib/libc/sys/chflags.2,v 1.11.2.7 2001/12/14 18:34:00 ru Exp $
  30 .\" $DragonFly: src/lib/libc/sys/chflags.2,v 1.5 2008/11/11 00:55:49 pavalos Exp $
  31 .\"
  32 .Dd November 10, 2008
  33 .Dt CHFLAGS 2
  34 .Os
  35 .Sh NAME
  36 .Nm chflags ,
  37 .Nm lchflags ,
  38 .Nm fchflags
  39 .Nd set file flags
  40 .Sh LIBRARY
  41 .Lb libc
  42 .Sh SYNOPSIS
  43 .In sys/stat.h
  44 .In unistd.h
  45 .Ft int
  46 .Fn chflags "const char *path"  "u_long flags"
  47 .Ft int
  48 .Fn lchflags "const char *path" "u_long flags"
  49 .Ft int
  50 .Fn fchflags "int fd" "u_long flags"
  51 .Sh DESCRIPTION
  52 The file whose name
  53 is given by
  54 .Fa path
  55 or referenced by the descriptor
  56 .Fa fd
  57 has its flags changed to
  58 .Fa flags .
  59 .Pp
  60 The
  61 .Fn lchflags
  62 system call is like
  63 .Fn chflags
  64 except in the case where the named file is a symbolic link,
  65 in which case
  66 .Fn lchflags
  67 will change the flags of the link itself,
  68 rather than the file it points to.
  69 .Pp
  70 The flags specified are formed by
  71 .Em or Ns 'ing
  72 the following values
  73 .Pp
  74 .Bl -tag -width "SF_IMMUTABLE" -compact -offset indent
  75 .It UF_NODUMP
  76 Do not dump the file.
  77 .It UF_IMMUTABLE
  78 The file may not be changed.
  79 .It UF_APPEND
  80 The file may only be appended to.
  81 .It UF_OPAQUE
  82 The directory is opaque when viewed through a union stack.
  83 .It UF_NOUNLINK
  84 The file may not be renamed or deleted.
  85 .It UF_NOHISTORY
  86 Do not retain history for file.
  87 .It UF_CACHE
  88 Enable
  89 .Xr swapcache 8
  90 data caching.
  91 The flag is recursive and need only be set on a top-level directory.
  92 .It SF_ARCHIVED
  93 The file may be archived.
  94 .It SF_IMMUTABLE
  95 The file may not be changed.
  96 .It SF_APPEND
  97 The file may only be appended to.
  98 .It SF_NOUNLINK
  99 The file may not be renamed or deleted.
 100 .It SF_NOHISTORY
 101 Do not retain history for file.
 102 .It SF_NOCACHE
 103 Disable
 104 .Xr swapcache 8
 105 data caching.
 106 The flag is recursive and need only be set on a top-level directory.
 107 .El
 108 .Pp
 109 The
 110 .Dq UF_
 111 prefixed
 112 flags may be set or unset by either the owner of a file or the super-user.
 113 .Pp
 114 The
 115 .Dq SF_
 116 prefixed
 117 flags may only be set or unset by the super-user.
 118 Attempts by the non-super-user to set the super-user only flags
 119 are silently ignored.
 120 These flags may be set at any time, but normally may only be unset when
 121 the system is in single-user mode.
 122 (See
 123 .Xr init 8
 124 for details.)
 125 .Sh RETURN VALUES
 126 .Rv -std
 127 .Sh ERRORS
 128 .Fn Chflags
 129 will fail if:
 130 .Bl -tag -width Er
 131 .It Bq Er ENOTDIR
 132 A component of the path prefix is not a directory.
 133 .It Bq Er ENAMETOOLONG
 134 A component of a pathname exceeded 255 characters,
 135 or an entire path name exceeded 1023 characters.
 136 .It Bq Er ENOENT
 137 The named file does not exist.
 138 .It Bq Er EACCES
 139 Search permission is denied for a component of the path prefix.
 140 .It Bq Er ELOOP
 141 Too many symbolic links were encountered in translating the pathname.
 142 .It Bq Er EPERM
 143 The effective user ID does not match the owner of the file and
 144 the effective user ID is not the super-user.
 145 .It Bq Er EROFS
 146 The named file resides on a read-only file system.
 147 .It Bq Er EFAULT
 148 .Fa Path
 149 points outside the process's allocated address space.
 150 .It Bq Er EIO
 151 An
 152 .Tn I/O
 153 error occurred while reading from or writing to the file system.
 154 .It Bq Er EOPNOTSUPP
 155 The underlying file system does not support file flags.
 156 .El
 157 .Pp
 158 .Fn Fchflags
 159 will fail if:
 160 .Bl -tag -width Er
 161 .It Bq Er EBADF
 162 The descriptor is not valid.
 163 .It Bq Er EINVAL
 164 .Fa fd
 165 refers to a socket, not to a file.
 166 .It Bq Er EPERM
 167 The effective user ID does not match the owner of the file and
 168 the effective user ID is not the super-user.
 169 .It Bq Er EROFS
 170 The file resides on a read-only file system.
 171 .It Bq Er EIO
 172 An
 173 .Tn I/O
 174 error occurred while reading from or writing to the file system.
 175 .It Bq Er EOPNOTSUPP
 176 The underlying file system does not support file flags.
 177 .El
 178 .Sh SEE ALSO
 179 .Xr chflags 1 ,
 180 .Xr fflagstostr 3 ,
 181 .Xr strtofflags 3 ,
 182 .Xr init 8 ,
 183 .Xr mount_union 8 ,
 184 .Xr swapcache 8
 185 .Sh HISTORY
 186 The
 187 .Nm chflags
 188 and
 189 .Nm fchflags
 190 functions first appeared in
 191 .Bx 4.4 .