1.\" $NetBSD: stat_flags.3,v 1.9 2023/05/31 21:49:39 uwe 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 May 31, 2023 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 46The 47.Fn flags_to_string 48and 49.Fn string_to_flags 50functions are used by 51programs such as 52.Xr chflags 1 , 53.Xr ls 1 , 54.Xr makefs 8 , 55.Xr mtree 8 , 56etc., to parse and/or print the 57.Fa st_flags 58field in the 59.Xr stat 2 60structure. 61. 62.Pp 63They recognize the following flags: 64. 65.Bl -tag -width Cm -offset indent 66. 67.It Cm arch , Cm archived Pq Dv SF_ARCHIVED 68file is archived 69.Po legacy/compat flag for 70.Xr mount_msdos 8 71filesystems 72.Pc 73. 74.It Cm nodump Pq Dv UF_NODUMP 75do not 76.Xr dump 8 77file 78. 79.It Cm opaque Pq Dv UF_OPAQUE 80directory is opaque in 81.Xr mount_union 8 82filesystems 83. 84.It Cm sappnd , Cm sappend Pq Dv SF_APPEND 85writes to the file may only append 86.Pq flag can be changed by the superuser only 87. 88.It Cm schg , Cm schange , Cm simmutable Pq Dv SF_IMMUTABLE 89file cannot be changed; it is immutable 90.Pq flag can be changed by the superuser only 91. 92.It Cm snap Pq Dv SF_SNAPSHOT 93file is an 94.Xr fss 4 95snapshot inode 96. 97.It Cm uappnd , Cm uappend Pq Dv UF_APPEND 98writes to the file may only append 99. 100.It Cm uchg , Cm uchange , Cm uimmutable Pq Dv UF_IMMUTABLE 101file cannot be changed; it is immutable 102. 103.El 104. 105.Pp 106The 107.Fn flags_to_string 108function converts the bits set in the 109.Fa flags 110argument to a comma-separated string and returns it. 111If no flags are set, then the 112.Fa def 113string is returned. 114The returned string is allocated via 115.Xr malloc 3 116and it is the responsibility of the caller to 117.Xr free 3 118it. 119.Pp 120Where the above list has several flag names for a flag, 121the first of the listed names is returned. 122. 123.Pp 124The 125.Fn string_to_flags 126function takes a 127.Fa stringp 128of space, comma, or tab separated flag names 129and places their bit value on the 130.Fa setp 131argument. 132.Pp 133If the flag name is prefixed by 134.Ql no , 135then the bit value is placed on the 136.Fa clrp 137argument. 138Both 139.Cm nonodump 140and 141.Cm dump 142are recognized as negative forms of the 143.Cm nodump 144flag name. 145.Pp 146Where the above list has several flag names for a flag, 147all of them are recognized. 148The 149.Cm snap 150flag name is 151.Em not 152recognized 153.Pq as its flag cannot be changed anyway . 154. 155.Sh RETURN VALUES 156.Fn flags_to_string 157returns the symbolic representation of flags, the default string, or 158.Dv NULL 159if allocation failed. 160. 161.Pp 162.Fn string_to_flags 163returns 164.Dv 0 165on success and 166.Dv 1 167if it fails to parse the string, setting 168.Fa stringp 169to point to the first name that it failed to parse. 170.Sh SEE ALSO 171.Xr chflags 2 , 172.Xr stat 2 173