lib/libutil/stat_flags.3

   1 .\" $NetBSD: stat_flags.3,v 1.4 2006/12/23 09:55:47 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 December 14, 2006
  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 -tag -width "schg (SF_IMMUTABLE)"
  62 .It Dv arch Pq Dv SF_ARCHIVED
  63 file is archived.
  64 .It Dv nodump Pq Dv UF_NODUMP
  65 do not dump file.
  66 .It Dv opaque Pq Dv UF_OPAQUE
  67 directory is opaque in union filesystems.
  68 .It Dv sappnd Pq Dv SF_APPEND
  69 writes to the file may only append (superuser only).
  70 .It Dv schg Pq Dv SF_IMMUTABLE
  71 file cannot be changed, is immutable (superuser only).
  72 .It Dv snap Pq Dv SF_SNAPSHOT
  73 file is snapshot inode.
  74 .It Dv uappnd Pq Dv UF_APPEND
  75 writes to the file may only append (user only).
  76 .It Dv uchg Pq Dv UF_IMMUTABLE
  77 file cannot be changed, is immutable (user only).
  78 .El
  79 .Pp
  80 The
  81 .Fn flags_to_string
  82 function converts the bits set in the
  83 .Fa flags
  84 argument to a comma-separated string and returns it.
  85 If no flags are set, then the
  86 .Fa def
  87 string is returned.
  88 The returned string is allocated via
  89 .Xr malloc 3
  90 and it is the responsibility of the caller to
  91 .Xr free 3
  92 it.
  93 .Pp
  94 The
  95 .Fn string_to_flags
  96 function takes a
  97 .Fa stringp
  98 of space, comma, or tab separated flag names
  99 and places their bit value on the
 100 .Fa setp
 101 argument.
 102 If the flag name is prefixed by:
 103 .Dq no ,
 104 then the bit value is placed on the
 105 .Fa clrp
 106 argument.
 107 .Sh RETURN VALUES
 108 .Fn flags_to_string
 109 returns the symbolic representation of flags, the default string, or
 110 .Dv NULL
 111 if allocation failed.
 112 .Pp
 113 .Fn string_to_flags
 114 returns
 115 .Dv 0
 116 on success and
 117 .Dv 1
 118 if it fails to parse the string, setting
 119 .Fa stringp
 120 to point to the first string that it failed to parse.
 121 .Sh SEE ALSO
 122 .Xr stat 2