lib/libutil/stat_flags.3

   1 .\" $NetBSD: stat_flags.3,v 1.8 2012/09/19 23:22:56 wiz Exp $
   2 .\"
   3 .\" Copyright (c) 1996 The NetBSD Foundation, Inc.
   4 .\" All rights reserved.
   5 .\"
   6 .\" This code is derived from software contributed to The NetBSD Foundation
   7 .\" by Christos Zoulas.
   8 .\"
   9 .\" Redistribution and use in source and binary forms, with or without
  10 .\" modification, are permitted provided that the following conditions
  11 .\" are met:
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer.
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in the
  16 .\"    documentation and/or other materials provided with the distribution.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
  19 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  20 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  21 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
  22 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  23 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  24 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  25 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  26 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  27 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  28 .\" POSSIBILITY OF SUCH DAMAGE.
  29 .\"
  30 .Dd September 20, 2012
  31 .Dt STAT_FLAGS 3
  32 .Os
  33 .Sh NAME
  34 .Nm string_to_flags ,
  35 .Nm flags_to_string
  36 .Nd Stat flags parsing and printing functions
  37 .Sh LIBRARY
  38 .Lb libutil
  39 .Sh SYNOPSIS
  40 .In util.h
  41 .Ft char *
  42 .Fn flags_to_string "u_long flags" "const char *def"
  43 .Ft int
  44 .Fn string_to_flags "char **stringp" "u_long *setp" "u_long *clrp"
  45 .Sh DESCRIPTION
  46 The
  47 .Fn flags_to_string
  48 and
  49 .Fn string_to_flags
  50 functions are used by
  51 programs such as
  52 .Xr ls 1 ,
  53 .Xr mtree 8 ,
  54 .Xr makefs 8 ,
  55 etc., to parse and/or print the
  56 .Dv st_flags field in the
  57 .Xr stat 2
  58 structure.
  59 .Pp
  60 They recognize the following flags:
  61 .Bl -column -offset indent "uappnd " "SF_IMMUTABLE" "xxx"
  62 .It Sy String Ta Sy Flag Ta Sy Description
  63 .It Va arch Ta Dv SF_ARCHIVED Ta file is archived
  64 .It Va nodump Ta Dv UF_NODUMP Ta do not dump file
  65 .It Va opaque Ta Dv UF_OPAQUE Ta directory is opaque in union filesystems
  66 .It Va sappnd Ta Dv SF_APPEND Ta writes to the file may only append
  67 .It Va schg Ta Dv SF_IMMUTABLE Ta file cannot be changed; it is immutable
  68 .It Va snap Ta Dv SF_SNAPSHOT Ta file is a snapshot inode
  69 .It Va uappnd Ta Dv UF_APPEND Ta writes to the file may only append
  70 .It Va uchg Ta Dv UF_IMMUTABLE Ta file cannot be changed; it is immutable
  71 .El
  72 .Pp
  73 The
  74 .Dv SF_APPEND
  75 and
  76 .Dv SF_IMMUTABLE
  77 flags are for the superuser only, whereas
  78 .Dv UF_APPEND
  79 and
  80 .Dv UF_IMMUTABLE
  81 are for the user only.
  82 .Pp
  83 The
  84 .Fn flags_to_string
  85 function converts the bits set in the
  86 .Fa flags
  87 argument to a comma-separated string and returns it.
  88 If no flags are set, then the
  89 .Fa def
  90 string is returned.
  91 The returned string is allocated via
  92 .Xr malloc 3
  93 and it is the responsibility of the caller to
  94 .Xr free 3
  95 it.
  96 .Pp
  97 The
  98 .Fn string_to_flags
  99 function takes a
 100 .Fa stringp
 101 of space, comma, or tab separated flag names
 102 and places their bit value on the
 103 .Fa setp
 104 argument.
 105 If the flag name is prefixed by:
 106 .Dq no ,
 107 then the bit value is placed on the
 108 .Fa clrp
 109 argument.
 110 .Sh RETURN VALUES
 111 .Fn flags_to_string
 112 returns the symbolic representation of flags, the default string, or
 113 .Dv NULL
 114 if allocation failed.
 115 .Pp
 116 .Fn string_to_flags
 117 returns
 118 .Dv 0
 119 on success and
 120 .Dv 1
 121 if it fails to parse the string, setting
 122 .Fa stringp
 123 to point to the first string that it failed to parse.
 124 .Sh SEE ALSO
 125 .Xr chflags 2 ,
 126 .Xr stat 2