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 46The 47.Fn flags_to_string 48and 49.Fn string_to_flags 50functions are used by 51programs such as 52.Xr ls 1 , 53.Xr mtree 8 , 54.Xr makefs 8 , 55etc., to parse and/or print the 56.Dv st_flags field in the 57.Xr stat 2 58structure. 59.Pp 60They 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 73The 74.Dv SF_APPEND 75and 76.Dv SF_IMMUTABLE 77flags are for the superuser only, whereas 78.Dv UF_APPEND 79and 80.Dv UF_IMMUTABLE 81are for the user only. 82.Pp 83The 84.Fn flags_to_string 85function converts the bits set in the 86.Fa flags 87argument to a comma-separated string and returns it. 88If no flags are set, then the 89.Fa def 90string is returned. 91The returned string is allocated via 92.Xr malloc 3 93and it is the responsibility of the caller to 94.Xr free 3 95it. 96.Pp 97The 98.Fn string_to_flags 99function takes a 100.Fa stringp 101of space, comma, or tab separated flag names 102and places their bit value on the 103.Fa setp 104argument. 105If the flag name is prefixed by: 106.Dq no , 107then the bit value is placed on the 108.Fa clrp 109argument. 110.Sh RETURN VALUES 111.Fn flags_to_string 112returns the symbolic representation of flags, the default string, or 113.Dv NULL 114if allocation failed. 115.Pp 116.Fn string_to_flags 117returns 118.Dv 0 119on success and 120.Dv 1 121if it fails to parse the string, setting 122.Fa stringp 123to point to the first string that it failed to parse. 124.Sh SEE ALSO 125.Xr chflags 2 , 126.Xr stat 2 127