<html lang="en">
<head>
<title>Setting Permissions - The GNU C Library</title>
<meta http-equiv="Content-Type" content="text/html">
<meta name="description" content="The GNU C Library">
<meta name="generator" content="makeinfo 4.13">
<link title="Top" rel="start" href="index.html#Top">
<link rel="up" href="File-Attributes.html#File-Attributes" title="File Attributes">
<link rel="prev" href="Access-Permission.html#Access-Permission" title="Access Permission">
<link rel="next" href="Testing-File-Access.html#Testing-File-Access" title="Testing File Access">
<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
<!--
This file documents the GNU C library.

This is Edition 0.12, last updated 2007-10-27,
of `The GNU C Library Reference Manual', for version
2.8 (Sourcery G++ Lite 2011.03-41).

Copyright (C) 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2001, 2002,
2003, 2007, 2008, 2010 Free Software Foundation, Inc.

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with the
Invariant Sections being ``Free Software Needs Free Documentation''
and ``GNU Lesser General Public License'', the Front-Cover texts being
``A GNU Manual'', and with the Back-Cover Texts as in (a) below.  A
copy of the license is included in the section entitled "GNU Free
Documentation License".

(a) The FSF's Back-Cover Text is: ``You have the freedom to
copy and modify this GNU manual.  Buying copies from the FSF
supports it in developing GNU and promoting software freedom.''-->
<meta http-equiv="Content-Style-Type" content="text/css">
<style type="text/css"><!--
  pre.display { font-family:inherit }
  pre.format  { font-family:inherit }
  pre.smalldisplay { font-family:inherit; font-size:smaller }
  pre.smallformat  { font-family:inherit; font-size:smaller }
  pre.smallexample { font-size:smaller }
  pre.smalllisp    { font-size:smaller }
  span.sc    { font-variant:small-caps }
  span.roman { font-family:serif; font-weight:normal; } 
  span.sansserif { font-family:sans-serif; font-weight:normal; } 
--></style>
<link rel="stylesheet" type="text/css" href="../cs.css">
</head>
<body>
<div class="node">
<a name="Setting-Permissions"></a>
<p>
Next:&nbsp;<a rel="next" accesskey="n" href="Testing-File-Access.html#Testing-File-Access">Testing File Access</a>,
Previous:&nbsp;<a rel="previous" accesskey="p" href="Access-Permission.html#Access-Permission">Access Permission</a>,
Up:&nbsp;<a rel="up" accesskey="u" href="File-Attributes.html#File-Attributes">File Attributes</a>
<hr>
</div>

<h4 class="subsection">14.9.7 Assigning File Permissions</h4>

<p><a name="index-file-creation-mask-1562"></a><a name="index-umask-1563"></a>The primitive functions for creating files (for example, <code>open</code> or
<code>mkdir</code>) take a <var>mode</var> argument, which specifies the file
permissions to give the newly created file.  This mode is modified by
the process's <dfn>file creation mask</dfn>, or <dfn>umask</dfn>, before it is
used.

   <p>The bits that are set in the file creation mask identify permissions
that are always to be disabled for newly created files.  For example, if
you set all the &ldquo;other&rdquo; access bits in the mask, then newly created
files are not accessible at all to processes in the &ldquo;other&rdquo; category,
even if the <var>mode</var> argument passed to the create function would
permit such access.  In other words, the file creation mask is the
complement of the ordinary access permissions you want to grant.

   <p>Programs that create files typically specify a <var>mode</var> argument that
includes all the permissions that make sense for the particular file. 
For an ordinary file, this is typically read and write permission for
all classes of users.  These permissions are then restricted as
specified by the individual user's own file creation mask.

   <p><a name="index-chmod-1564"></a>To change the permission of an existing file given its name, call
<code>chmod</code>.  This function uses the specified permission bits and
ignores the file creation mask.

   <p><a name="index-umask-1565"></a>In normal use, the file creation mask is initialized by the user's login
shell (using the <code>umask</code> shell command), and inherited by all
subprocesses.  Application programs normally don't need to worry about
the file creation mask.  It will automatically do what it is supposed to
do.

   <p>When your program needs to create a file and bypass the umask for its
access permissions, the easiest way to do this is to use <code>fchmod</code>
after opening the file, rather than changing the umask.  In fact,
changing the umask is usually done only by shells.  They use the
<code>umask</code> function.

   <p>The functions in this section are declared in <samp><span class="file">sys/stat.h</span></samp>. 
<a name="index-sys_002fstat_002eh-1566"></a>
<!-- sys/stat.h -->
<!-- POSIX.1 -->

<div class="defun">
&mdash; Function: mode_t <b>umask</b> (<var>mode_t mask</var>)<var><a name="index-umask-1567"></a></var><br>
<blockquote><p>The <code>umask</code> function sets the file creation mask of the current
process to <var>mask</var>, and returns the previous value of the file
creation mask.

        <p>Here is an example showing how to read the mask with <code>umask</code>
without changing it permanently:

     <pre class="smallexample">          mode_t
          read_umask (void)
          {
            mode_t mask = umask (0);
            umask (mask);
            return mask;
          }
</pre>
        <p class="noindent">However, it is better to use <code>getumask</code> if you just want to read
the mask value, because it is reentrant (at least if you use the GNU
operating system). 
</p></blockquote></div>

<!-- sys/stat.h -->
<!-- GNU -->
<div class="defun">
&mdash; Function: mode_t <b>getumask</b> (<var>void</var>)<var><a name="index-getumask-1568"></a></var><br>
<blockquote><p>Return the current value of the file creation mask for the current
process.  This function is a GNU extension. 
</p></blockquote></div>

<!-- sys/stat.h -->
<!-- POSIX.1 -->
<div class="defun">
&mdash; Function: int <b>chmod</b> (<var>const char *filename, mode_t mode</var>)<var><a name="index-chmod-1569"></a></var><br>
<blockquote><p>The <code>chmod</code> function sets the access permission bits for the file
named by <var>filename</var> to <var>mode</var>.

        <p>If <var>filename</var> is a symbolic link, <code>chmod</code> changes the
permissions of the file pointed to by the link, not those of the link
itself.

        <p>This function returns <code>0</code> if successful and <code>-1</code> if not.  In
addition to the usual file name errors (see <a href="File-Name-Errors.html#File-Name-Errors">File Name Errors</a>), the following <code>errno</code> error conditions are defined for
this function:

          <dl>
<dt><code>ENOENT</code><dd>The named file doesn't exist.

          <br><dt><code>EPERM</code><dd>This process does not have permission to change the access permissions
of this file.  Only the file's owner (as judged by the effective user ID
of the process) or a privileged user can change them.

          <br><dt><code>EROFS</code><dd>The file resides on a read-only file system.

          <br><dt><code>EFTYPE</code><dd><var>mode</var> has the <code>S_ISVTX</code> bit (the &ldquo;sticky bit&rdquo;) set,
and the named file is not a directory.  Some systems do not allow setting the
sticky bit on non-directory files, and some do (and only some of those
assign a useful meaning to the bit for non-directory files).

          <p>You only get <code>EFTYPE</code> on systems where the sticky bit has no useful
meaning for non-directory files, so it is always safe to just clear the
bit in <var>mode</var> and call <code>chmod</code> again.  See <a href="Permission-Bits.html#Permission-Bits">Permission Bits</a>,
for full details on the sticky bit. 
</dl>
        </p></blockquote></div>

<!-- sys/stat.h -->
<!-- BSD -->
<div class="defun">
&mdash; Function: int <b>fchmod</b> (<var>int filedes, int mode</var>)<var><a name="index-fchmod-1570"></a></var><br>
<blockquote><p>This is like <code>chmod</code>, except that it changes the permissions of the
currently open file given by <var>filedes</var>.

        <p>The return value from <code>fchmod</code> is <code>0</code> on success and <code>-1</code>
on failure.  The following <code>errno</code> error codes are defined for this
function:

          <dl>
<dt><code>EBADF</code><dd>The <var>filedes</var> argument is not a valid file descriptor.

          <br><dt><code>EINVAL</code><dd>The <var>filedes</var> argument corresponds to a pipe or socket, or something
else that doesn't really have access permissions.

          <br><dt><code>EPERM</code><dd>This process does not have permission to change the access permissions
of this file.  Only the file's owner (as judged by the effective user ID
of the process) or a privileged user can change them.

          <br><dt><code>EROFS</code><dd>The file resides on a read-only file system. 
</dl>
        </p></blockquote></div>

   </body></html>