usr/src/man/man3c/fgetattr.3c

   1 '\" te
   2 .\" Copyright 2014 Nexenta Systems, Inc.  All rights reserved.
   3 .\" Copyright (c) 2008, Sun Microsystems Inc. All Rights Reserved.
   4 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   5 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   6 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   7 .TH FGETATTR 3C "Nov 24, 2014"
   8 .SH NAME
   9 fgetattr, fsetattr, getattrat, setattrat \- get and set system attributes
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 #include <fcntl.h>
  14 #include <sys/types.h>
  15 #include <attr.h>
  16 #include <sys/nvpair.h>
  17
  18 \fBint\fR \fBfgetattr\fR(\fBint\fR fildes, \fBxattr_view_t\fR view,\fBnvlist_t **\fRresponse);
  19 .fi
  20
  21 .LP
  22 .nf
  23 \fBint\fR \fBfsetattr\fR(\fBint\fR fildes, \fBxattr_view_t\fR view,\fBnvlist_t *\fRrequest)
  24 .fi
  25
  26 .LP
  27 .nf
  28 \fBint\fR \fBgetattrat\fR(\fBint\fR fildes, \fBxattr_view_t\fR view, \fBconst char *\fRfilename,
  29      \fBnvlist_t **\fRresponse);
  30 .fi
  31
  32 .LP
  33 .nf
  34 \fBint\fR \fBsetattrat\fR(\fBint\fR fildes, \fBxattr_view_t\fR view, \fBconst char *\fRfilename,
  35      \fBnvlist_t *\fRrequest);
  36 .fi
  37
  38 .SH DESCRIPTION
  39 .LP
  40 The \fBfgetattr()\fR function obtains an nvlist of system attribute information
  41 about an open file object specified by the file descriptor \fIfildes\fR,
  42 obtained from a successful \fBopen\fR(2), \fBcreat\fR(2), \fBdup\fR(2),
  43 \fBfcntl\fR(2), or \fBpipe\fR(2) function.
  44 .sp
  45 .LP
  46 The \fBgetattrat()\fR function first opens the extended attribute file
  47 specified by \fIfilename\fR in the already opened file directory object
  48 specified by \fIfildes\fR. It then retrieves an nvlist of system attributes and
  49 their values from \fIfilename\fR.
  50 .sp
  51 .LP
  52 The \fIresponse\fR argument is allocated by either \fBfgetattr()\fR or
  53 \fBgetattrat()\fR. The application must call \fBnvlist_free\fR(3NVPAIR) to
  54 deallocate the memory.
  55 .sp
  56 .LP
  57 Upon successful completion, the nvlist will contain one nvpair for each of the
  58 system attributes associated with \fIview\fR.  The list of views and the
  59 attributes associated with each view are listed below.  Not all underlying file
  60 systems support all views and all attributes. The nvlist will not contain an
  61 nvpair for any attribute not supported by the underlying filesystem.
  62 .sp
  63 .LP
  64 The \fBfsetattr()\fR function uses the nvlist pointed to by \fIrequest\fR to
  65 update one or more of the system attribute's information about an open file
  66 object specified by the file descriptor \fIfildes\fR, obtained from a
  67 successful \fBopen()\fR, \fBcreat()\fR, \fBdup()\fR, \fBfcntl()\fR, or
  68 \fBpipe()\fR function. The \fBsetattrat()\fR function first opens the extended
  69 attribute file specified by \fIfilename\fR in the already opened file directory
  70 object specified by \fIfildes\fR. It then uses the nvlist pointed to by
  71 \fIrequest\fR to update one or more of the system attributes of filename.
  72 .sp
  73 .LP
  74 If completion is not successful then no system attribute information is
  75 updated.
  76 .sp
  77 .LP
  78 The following chart lists the supported views, attributes, and  data types for
  79 each view:
  80 .sp
  81
  82 .sp
  83 .TS
  84 c c c
  85 l l l .
  86 View    Attribute       Data type
  87 _
  88 \fBXATTR_VIEW_READONLY\fR       \fBA_FSID\fR    \fBuint64_value\fR
  89         \fBA_OPAQUE\fR  \fBboolean_value\fR
  90         \fBA_AV_SCANSTAMP\fR    \fBuint8_array[]\fR
  91 \fBXATTR_VIEW_READWRITE\fR      \fBA_READONLY\fR        \fBboolean_value\fR
  92         \fBA_HIDDEN\fR  \fBboolean_value\fR
  93         \fBA_SYSTEM\fR  \fBboolean_value\fR
  94         \fBA_ARCHIVE\fR \fBboolean_value\fR
  95         \fBA_CRTIME\fR  \fBuint64_array\fR[2]
  96         \fBA_NOUNLINK\fR        \fBboolean_value\fR
  97         \fBA_IMMUTABLE\fR       \fBboolean_value\fR
  98         \fBA_APPENDONLY\fR      \fBboolean_value\fR
  99         \fBA_NODUMP\fR  \fBboolean_value\fR
 100         \fBA_AV_QUARANTINED\fR  \fBboolean_value\fR
 101         \fBA_AV_MODIFIED\fR     \fBboolean_value\fR
 102         \fBA_OWNERSID\fR        T{
 103 nvlist composed of \fBuint32_value\fR and \fBstring\fR
 104 T}
 105         \fBA_GROUPSID\fR        T{
 106 nvlist composed of \fBuint32_value\fR and \fBstring\fR
 107 T}
 108         \fBA_OFFLINE\fR \fBboolean_value\fR
 109         \fBA_SPARSE\fR  \fBboolean_value\fR
 110 .TE
 111
 112 .SH RETURN VALUES
 113 .LP
 114 Upon successful completion, 0 is returned. Otherwise, -1  is returned and
 115 \fBerrno\fR is set to indicate the error.
 116 .SH ERRORS
 117 .LP
 118 The \fBfgetattr()\fR, \fBgetattrat()\fR, \fBfsetattr()\fR, and
 119 \fBsetattrat()\fR, functions will fail if:
 120 .sp
 121 .ne 2
 122 .na
 123 \fB\fBEBADF\fR\fR
 124 .ad
 125 .RS 10n
 126 The \fIfildes\fR argument is not a valid open file descriptor.
 127 .RE
 128
 129 .sp
 130 .ne 2
 131 .na
 132 \fB\fBEINVAL\fR\fR
 133 .ad
 134 .RS 10n
 135 The underlying file system does not support extended file attributes.
 136 .RE
 137
 138 .sp
 139 .ne 2
 140 .na
 141 \fB\fBEIO\fR\fR
 142 .ad
 143 .RS 10n
 144 An error occurred while reading from the file system.
 145 .RE
 146
 147 .sp
 148 .LP
 149 The \fBgetattrat()\fR and \fBsetattrat()\fR functions will fail if:
 150 .sp
 151 .ne 2
 152 .na
 153 \fB\fBEACCES\fR\fR
 154 .ad
 155 .RS 10n
 156 Search permission or write permission for \fIfilename\fR is denied.
 157 .RE
 158
 159 .sp
 160 .ne 2
 161 .na
 162 \fB\fBENOENT\fR\fR
 163 .ad
 164 .RS 10n
 165 The \fIfilename\fR argument does not name an existing file in the extended
 166 attribute directory represented by \fIfildes\fR.
 167 .RE
 168
 169 .sp
 170 .ne 2
 171 .na
 172 \fB\fBEPERM\fR\fR
 173 .ad
 174 .RS 10n
 175 There are insufficient privileges to manipulate attributes.
 176 .RE
 177
 178 .SH EXAMPLES
 179 .LP
 180 \fBExample 1 \fRObtain an nvlist of readonly system attributes for an open file
 181 object.
 182 .sp
 183 .LP
 184 Use \fBfgetattr()\fR to obtain an nvlist of the readonly system attributes for
 185 the open file object represented by file descriptor \fIfildes\fR.
 186
 187 .sp
 188 .in +2
 189 .nf
 190 #include <fcntl.h>
 191 #include <sys/types.h>
 192 #include <attr.h>
 193 #include <sys/nvpair.h>
 194
 195 nvlist_t *response;
 196 nvpair_t *pair = NULL;
 197
 198 if (fgetattr(fildes, XATTR_VIEW_READONLY, &response)) {
 199              exit(1);
 200 }
 201 while (pair = nvlist_next_nvpair(response, pair)) {
 202     .
 203     .
 204     .
 205 }
 206 nvlist_free(response);
 207 .fi
 208 .in -2
 209
 210 .LP
 211 \fBExample 2 \fRSet the \fBA_READONLY\fR system attribute on an open file
 212 object.
 213 .sp
 214 .LP
 215 Use \fBfsetattr()\fR to set the \fBA_OPAQUE\fR system attribute on the open
 216 file object represented by file descriptor \fIfildes\fR.
 217
 218 .sp
 219 .in +2
 220 .nf
 221 nvlist_t *request;
 222 nvpair_t *pair = NULL;
 223
 224 if (nvlist_alloc(&request, NV_UNIQUE_NAME, 0) != 0) {
 225             exit(1);
 226 }
 227 if (nvlist_add_boolean_value(request, A_READONLY, 1) != 0) {
 228             exit(1);
 229 }
 230 if (fsetattr(fildes, XATTR_VIEW_READWRITE, request)) {
 231             exit(1);
 232 }
 233 .fi
 234 .in -2
 235
 236 .LP
 237 \fBExample 3 \fRObtain an nvlist of the read/write system attributes for a
 238 file.
 239 .sp
 240 .LP
 241 Use \fBgetattrat()\fR to obtain an nvlist of the read/write system attributes
 242 for the file named \fBxattrfile\fR in the extended attribute directory of the
 243 open file represented by file descriptor \fIfildes\fR.
 244
 245 .sp
 246 .in +2
 247 .nf
 248 nvlist_t *response;
 249 nvpair_t *pair = NULL;
 250
 251 if (getattrat(fildes, XATTR_VIEW_READWRITE, "file", &response)) {
 252              exit(1);
 253 }
 254 while (pair = nvlist_next_nvpair(response, pair)) {
 255     .
 256     .
 257     .
 258 }
 259 nvlist_free(response);
 260 .fi
 261 .in -2
 262
 263 .LP
 264 \fBExample 4 \fRSet the \fBA_APPENDONLY\fR system attribute on a file.
 265 .sp
 266 .LP
 267 Use \fBsetattrat()\fR to set the \fBA_APPENDONLY\fR system attribute on the
 268 file named \fBfile\fR in the extended attribute directory of the open file
 269 represented by file descriptor \fIfildes\fR.
 270
 271 .sp
 272 .in +2
 273 .nf
 274 nvlist_t *request;
 275 nvpair_t *pair = NULL;
 276
 277 if (nvlist_alloc(&request, NV_UNIQUE_NAME, 0) != 0) {
 278             exit(1);
 279 }
 280 if (nvlist_add_boolean_value(request, A_APPENDONLY, 1) != 0) {
 281             exit(1);
 282 }
 283 if (setattrat(fildes, XATTR_VIEW_READWRITE, "file", request)) {
 284             exit(1);
 285      }
 286 .fi
 287 .in -2
 288
 289 .SH ATTRIBUTES
 290 .LP
 291 See \fBattributes\fR(5) for descriptions of the following attributes:
 292 .sp
 293
 294 .sp
 295 .TS
 296 box;
 297 c | c
 298 l | l .
 299 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 300 _
 301 Interface Stability     Committed
 302 _
 303 MT-Level        Safe
 304 .TE
 305
 306 .SH SEE ALSO
 307 .LP
 308 \fBcreat\fR(2), \fBdup\fR(2), \fBfcntl\fR(2), \fBfstat\fR(2), \fBfstatat\fR(2),
 309 \fBopen\fR(2), \fBpipe\fR(2), \fBlibnvpair\fR(3LIB), \fBattributes\fR(5),
 310 \fBfsattr\fR(5)