1SETMODE(3bsd)                        LOCAL                       SETMODE(3bsd)
2

NAME

4     getmode, setmode — modify mode bits
5

LIBRARY

7     Utility functions from BSD systems (libbsd, -lbsd)
8

SYNOPSIS

10     #include <unistd.h>
11     (See libbsd(7) for include usage.)
12
13     void *
14     setmode(const char *mode_str);
15
16     mode_t
17     getmode(const void *set, mode_t mode);
18

DESCRIPTION

20     The setmode() function accepts a string representation of a file mode
21     change, compiles it to binary form, and returns an abstract representa‐
22     tion that may be passed to getmode().  The string may be an numeric
23     (octal) or symbolic string of the form accepted by chmod(1), and may rep‐
24     resent either an exact mode to set or a change to make to the existing
25     mode.
26
27     The getmode() function adjusts the file permission bits given by mode
28     according to the compiled change representation set, and returns the
29     adjusted mode.  While only the permission bits are altered, other parts
30     of the file mode, particularly the type, may be examined.
31
32     Because some of the possible symbolic values are defined relative to the
33     file creation mask, setmode() may call umask(2), temporarily changing the
34     mask.  If this occurs, the file creation mask will be restored before
35     setmode() returns.  If the calling program changes the value of its file
36     creation mask after calling setmode(), setmode() must be called again to
37     recompile the mode string if getmode() is to modify future file modes
38     correctly.
39
40     If the mode passed to setmode() is invalid, setmode() returns NULL.
41
42     The value returned from setmode() is obtained from malloc() and should be
43     returned to the system with free() when the program is done with it, gen‐
44     erally after a call to getmode().
45

EXAMPLES

47     The effects of the shell command ‘chmod a+x myscript.sh’ can be dupli‐
48     cated as follows:
49
50           const char *file = "myscript.sh";
51           struct stat st;
52           mode_t newmode;
53
54           stat(file, &st);
55           newmode = getmode(setmode("a+x"), st.st_mode);
56           chmod(file, newmode);
57

ERRORS

59     The setmode() function may fail and set errno for any of the errors spec‐
60     ified for the library routines malloc(3) or strtol(3).  In addition,
61     setmode() will fail and set errno to:
62
63     [EINVAL]           The mode argument does not represent a valid mode.
64

SEE ALSO

66     chmod(1), stat(2), umask(2), malloc(3)
67

HISTORY

69     The getmode() and setmode() functions first appeared in 4.4BSD.
70

BUGS

72     The type of set should really be some opaque struct type used only by
73     these functions rather than void *.
74
75BSD                             January 4, 2009                            BSD
Impressum