lib/libc/gen/setmode.3

   1 .\" Copyright (c) 1989, 1991, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 3. Neither the name of the University nor the names of its contributors
  13 .\"    may be used to endorse or promote products derived from this software
  14 .\"    without specific prior written permission.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .\"     @(#)setmode.3   8.2 (Berkeley) 4/28/95
  29 .\" $FreeBSD: src/lib/libc/gen/setmode.3,v 1.8.2.3 2001/12/14 18:33:51 ru Exp $
  30 .\" $DragonFly: src/lib/libc/gen/setmode.3,v 1.3 2007/06/30 19:03:52 swildner Exp $
  31 .\"
  32 .Dd April 28, 1995
  33 .Dt SETMODE 3
  34 .Os
  35 .Sh NAME
  36 .Nm getmode ,
  37 .Nm setmode
  38 .Nd modify mode bits
  39 .Sh LIBRARY
  40 .Lb libc
  41 .Sh SYNOPSIS
  42 .In unistd.h
  43 .Ft mode_t
  44 .Fn getmode "const void *set" "mode_t mode"
  45 .Ft void *
  46 .Fn setmode "const char *mode_str"
  47 .Sh DESCRIPTION
  48 The
  49 .Fn getmode
  50 function
  51 returns a copy of the file permission bits
  52 .Fa mode
  53 as altered by the values pointed to by
  54 .Fa set .
  55 While only the mode bits are altered, other parts of the file mode
  56 may be examined.
  57 .Pp
  58 The
  59 .Fn setmode
  60 function
  61 takes an absolute (octal) or symbolic value, as described in
  62 .Xr chmod 1 ,
  63 as an argument
  64 and returns a pointer to mode values to be supplied to
  65 .Fn getmode .
  66 Because some of the symbolic values are relative to the file
  67 creation mask,
  68 .Fn setmode
  69 may call
  70 .Xr umask 2 .
  71 If this occurs, the file creation mask will be restored before
  72 .Fn setmode
  73 returns.
  74 If the calling program changes the value of its file creation mask
  75 after calling
  76 .Fn setmode ,
  77 .Fn setmode
  78 must be called again if
  79 .Fn getmode
  80 is to modify future file modes correctly.
  81 .Pp
  82 If the mode passed to
  83 .Fn setmode
  84 is invalid or if memory cannot be allocated for the return value,
  85 .Fn setmode
  86 returns
  87 .Dv NULL .
  88 .Pp
  89 The value returned from
  90 .Fn setmode
  91 is obtained from
  92 .Fn malloc
  93 and should be returned to the system with
  94 .Fn free
  95 when the program is done with it, generally after a call to
  96 .Fn getmode .
  97 .Sh ERRORS
  98 The
  99 .Fn setmode
 100 function may fail and set
 101 .Va errno
 102 for any of the errors specified for the library routine
 103 .Xr malloc 3 .
 104 .Sh SEE ALSO
 105 .Xr chmod 1 ,
 106 .Xr stat 2 ,
 107 .Xr umask 2 ,
 108 .Xr malloc 3
 109 .Sh HISTORY
 110 The
 111 .Fn getmode
 112 and
 113 .Fn setmode
 114 functions first appeared in
 115 .Bx 4.4 .