setmode (3)

Leading comments

	$NetBSD: setmode.3,v 1.18.28.1 2009/01/04 17:02:19 christos Exp $

 Copyright (c) 1989, 1991, 1993
	The Regents of the University of California.  All rights reserved.

 Redistribution and use in source and binary forms, with or without
 modification, are permitted provided that the following conditions
 are met:
 1. Redistributions of source code must retain the above copyright
    notice, this list of conditions and the following disclaimer.
 2. Redistributions in binary form must reproduce...

(The comments found at the beginning of the groff file "man3/setmode.3bsd".)

NAME

getmode setmode - modify mode bits

LIBRARY

Lb libbsd

SYNOPSIS

In unistd.h (See libbsd(7) for include usage.) Ft void * Fn setmode const char *mode_str Ft mode_t Fn getmode const void *set mode_t mode

DESCRIPTION

The Fn setmode function accepts a string representation of a file mode change, compiles it to binary form, and returns an abstract representation that may be passed to Fn getmode . The string may be an numeric (octal) or symbolic string of the form accepted by chmod(1), and may represent either an exact mode to set or a change to make to the existing mode.

The Fn getmode function adjusts the file permission bits given by Fa mode according to the compiled change representation Fa set , and returns the adjusted mode. While only the permission bits are altered, other parts of the file mode, particularly the type, may be examined.

Because some of the possible symbolic values are defined relative to the file creation mask, Fn setmode may call umask(2), temporarily changing the mask. If this occurs, the file creation mask will be restored before Fn setmode returns. If the calling program changes the value of its file creation mask after calling Fn setmode , Fn setmode must be called again to recompile the mode string if Fn getmode is to modify future file modes correctly.

If the mode passed to Fn setmode is invalid, Fn setmode returns NULL

The value returned from Fn setmode is obtained from Fn malloc and should be returned to the system with Fn free when the program is done with it, generally after a call to Fn getmode .

EXAMPLES

The effects of the shell command `chmod' a+x myscript.sh can be duplicated as follows:

const char *file = "myscript.sh";
struct stat st;
mode_t newmode;

stat(file, Am]st);
newmode = getmode(setmode("a+x"), st.st_mode);
chmod(file, newmode);

ERRORS

The Fn setmode function may fail and set errno for any of the errors specified for the library routines malloc(3) or strtol(3). In addition, Fn setmode will fail and set errno to:

Bq Er EINVAL

The Fa mode argument does not represent a valid mode.

SEE ALSO

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

HISTORY

The Fn getmode and Fn setmode functions first appeared in BSD 4.4

BUGS

The type of Fa set should really be some opaque struct type used only by these functions rather than Ft void * .