[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

13. Changing file attributes

A file is not merely its contents, a name, and a file type (see section Special file types). A file also has an owner (a user ID), a group (a group ID), permissions (what the owner can do with the file, what people in the group can do, and what everyone else can do), various timestamps, and other information. Collectively, we call these a file's attributes.

These commands change file attributes.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

13.1 chown: Change file owner and group

chown changes the user and/or group ownership of each given file to new-owner or to the user and group of an existing reference file. Synopsis:

 
chown [option]… {new-owner | --reference=ref_file} file

If used, new-owner specifies the new owner and/or group as follows (with no embedded white space):

 
[owner] [ : [group] ]

Specifically:

owner

If only an owner (a user name or numeric user ID) is given, that user is made the owner of each given file, and the files' group is not changed.

owner`:'group

If the owner is followed by a colon and a group (a group name or numeric group ID), with no spaces between them, the group ownership of the files is changed as well (to group).

owner`:'

If a colon but no group name follows owner, that user is made the owner of the files and the group of the files is changed to owner's login group.

`:'group

If the colon and following group are given, but the owner is omitted, only the group of the files is changed; in this case, chown performs the same function as chgrp.

`:'

If only a colon is given, or if new-owner is empty, neither the owner nor the group is changed.

If owner or group is intended to represent a numeric user or group ID, then you may specify it with a leading `+'. See section chown and chgrp: Disambiguating user names and IDs.

Some older scripts may still use `.' in place of the `:' separator. POSIX 1003.1-2001 (see section Standards conformance) does not require support for that, but for backward compatibility GNU chown supports `.' so long as no ambiguity results. New scripts should avoid the use of `.' because it is not portable, and because it has undesirable results if the entire owner`.'group happens to identify a user whose name contains `.'.

The chown command sometimes clears the set-user-ID or set-group-ID permission bits. This behavior depends on the policy and functionality of the underlying chown system call, which may make system-dependent file mode modifications outside the control of the chown command. For example, the chown command might not affect those bits when invoked by a user with appropriate privileges, or when the bits signify some function other than executable permission (e.g., mandatory locking). When in doubt, check the underlying system behavior.

The program accepts the following options. Also see Common options.

`-c'
`--changes'

Verbosely describe the action for each file whose ownership actually changes.

`-f'
`--silent'
`--quiet'

Do not print error messages about files whose ownership cannot be changed.

`--from=old-owner'

Change a file's ownership only if it has current attributes specified by old-owner. old-owner has the same form as new-owner described above. This option is useful primarily from a security standpoint in that it narrows considerably the window of potential abuse. For example, to reflect a user ID numbering change for one user's files without an option like this, root might run

 
find / -owner OLDUSER -print0 | xargs -0 chown -h NEWUSER

But that is dangerous because the interval between when the find tests the existing file's owner and when the chown is actually run may be quite large. One way to narrow the gap would be to invoke chown for each file as it is found:

 
find / -owner OLDUSER -exec chown -h NEWUSER {} \;

But that is very slow if there are many affected files. With this option, it is safer (the gap is narrower still) though still not perfect:

 
chown -h -R --from=OLDUSER NEWUSER /
`--dereference'

Do not act on symbolic links themselves but rather on what they point to. This is the default.

`-h'
`--no-dereference'

Act on symbolic links themselves instead of what they point to. This mode relies on the lchown system call. On systems that do not provide the lchown system call, chown fails when a file specified on the command line is a symbolic link. By default, no diagnostic is issued for symbolic links encountered during a recursive traversal, but see `--verbose'.

`--preserve-root'

Fail upon any attempt to recursively change the root directory, `/'. Without `--recursive', this option has no effect. See section Treating `/' specially.

`--no-preserve-root'

Cancel the effect of any preceding `--preserve-root' option. See section Treating `/' specially.

`--reference=ref_file'

Change the user and group of each file to be the same as those of ref_file. If ref_file is a symbolic link, do not use the user and group of the symbolic link, but rather those of the file it refers to.

`-v'
`--verbose'

Output a diagnostic for every file processed. If a symbolic link is encountered during a recursive traversal on a system without the lchown system call, and `--no-dereference' is in effect, then issue a diagnostic saying neither the symbolic link nor its referent is being changed.

`-R'
`--recursive'

Recursively change ownership of directories and their contents.

`-H'

If `--recursive' (`-R') is specified and a command line argument is a symbolic link to a directory, traverse it. See section Traversing symlinks.

`-L'

In a recursive traversal, traverse every symbolic link to a directory that is encountered. See section Traversing symlinks.

`-P'

Do not traverse any symbolic links. This is the default if none of `-H', `-L', or `-P' is specified. See section Traversing symlinks.

An exit status of zero indicates success, and a nonzero value indicates failure.

Examples:

 
# Change the owner of /u to "root".
chown root /u

# Likewise, but also change its group to "staff".
chown root:staff /u

# Change the owner of /u and subfiles to "root".
chown -hR root /u

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

13.2 chgrp: Change group ownership

chgrp changes the group ownership of each given file to group (which can be either a group name or a numeric group ID) or to the group of an existing reference file. Synopsis:

 
chgrp [option]… {group | --reference=ref_file} file

If group is intended to represent a numeric group ID, then you may specify it with a leading `+'. See section chown and chgrp: Disambiguating user names and IDs.

The program accepts the following options. Also see Common options.

`-c'
`--changes'

Verbosely describe the action for each file whose group actually changes.

`-f'
`--silent'
`--quiet'

Do not print error messages about files whose group cannot be changed.

`--dereference'

Do not act on symbolic links themselves but rather on what they point to. This is the default.

`-h'
`--no-dereference'

Act on symbolic links themselves instead of what they point to. This mode relies on the lchown system call. On systems that do not provide the lchown system call, chgrp fails when a file specified on the command line is a symbolic link. By default, no diagnostic is issued for symbolic links encountered during a recursive traversal, but see `--verbose'.

`--preserve-root'

Fail upon any attempt to recursively change the root directory, `/'. Without `--recursive', this option has no effect. See section Treating `/' specially.

`--no-preserve-root'

Cancel the effect of any preceding `--preserve-root' option. See section Treating `/' specially.

`--reference=ref_file'

Change the group of each file to be the same as that of ref_file. If ref_file is a symbolic link, do not use the group of the symbolic link, but rather that of the file it refers to.

`-v'
`--verbose'

Output a diagnostic for every file processed. If a symbolic link is encountered during a recursive traversal on a system without the lchown system call, and `--no-dereference' is in effect, then issue a diagnostic saying neither the symbolic link nor its referent is being changed.

`-R'
`--recursive'

Recursively change the group ownership of directories and their contents.

`-H'

If `--recursive' (`-R') is specified and a command line argument is a symbolic link to a directory, traverse it. See section Traversing symlinks.

`-L'

In a recursive traversal, traverse every symbolic link to a directory that is encountered. See section Traversing symlinks.

`-P'

Do not traverse any symbolic links. This is the default if none of `-H', `-L', or `-P' is specified. See section Traversing symlinks.

An exit status of zero indicates success, and a nonzero value indicates failure.

Examples:

 
# Change the group of /u to "staff".
chgrp staff /u

# Change the group of /u and subfiles to "staff".
chgrp -hR staff /u

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

13.3 chmod: Change access permissions

chmod changes the access permissions of the named files. Synopsis:

 
chmod [option]… {mode | --reference=ref_file} file

chmod never changes the permissions of symbolic links, since the chmod system call cannot change their permissions. This is not a problem since the permissions of symbolic links are never used. However, for each symbolic link listed on the command line, chmod changes the permissions of the pointed-to file. In contrast, chmod ignores symbolic links encountered during recursive directory traversals.

A successful use of chmod clears the set-group-ID bit of a regular file if the file's group ID does not match the user's effective group ID or one of the user's supplementary group IDs, unless the user has appropriate privileges. Additional restrictions may cause the set-user-ID and set-group-ID bits of mode or ref_file to be ignored. This behavior depends on the policy and functionality of the underlying chmod system call. When in doubt, check the underlying system behavior.

If used, mode specifies the new file mode bits. For details, see the section on File permissions. If you really want mode to have a leading `-', you should use `--' first, e.g., `chmod -- -w file'. Typically, though, `chmod a-w file' is preferable, and chmod -w file (without the `--') complains if it behaves differently from what `chmod a-w file' would do.

The program accepts the following options. Also see Common options.

`-c'
`--changes'

Verbosely describe the action for each file whose permissions actually changes.

`-f'
`--silent'
`--quiet'

Do not print error messages about files whose permissions cannot be changed.

`--preserve-root'

Fail upon any attempt to recursively change the root directory, `/'. Without `--recursive', this option has no effect. See section Treating `/' specially.

`--no-preserve-root'

Cancel the effect of any preceding `--preserve-root' option. See section Treating `/' specially.

`-v'
`--verbose'

Verbosely describe the action or non-action taken for every file.

`--reference=ref_file'

Change the mode of each file to be the same as that of ref_file. See section File permissions. If ref_file is a symbolic link, do not use the mode of the symbolic link, but rather that of the file it refers to.

`-R'
`--recursive'

Recursively change permissions of directories and their contents.

An exit status of zero indicates success, and a nonzero value indicates failure.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

13.4 touch: Change file timestamps

touch changes the access and/or modification times of the specified files. Synopsis:

 
touch [option]… file

Any file argument that does not exist is created empty, unless option `--no-create' (`-c') or `--no-dereference' (`-h') was in effect.

A file argument string of `-' is handled specially and causes touch to change the times of the file associated with standard output.

If changing both the access and modification times to the current time, touch can change the timestamps for files that the user running it does not own but has write permission for. Otherwise, the user must own the files.

Although touch provides options for changing two of the times--the times of last access and modification--of a file, there is actually a standard third one as well: the inode change time. This is often referred to as a file's ctime. The inode change time represents the time when the file's meta-information last changed. One common example of this is when the permissions of a file change. Changing the permissions doesn't access the file, so the atime doesn't change, nor does it modify the file, so the mtime doesn't change. Yet, something about the file itself has changed, and this must be noted somewhere. This is the job of the ctime field. This is necessary, so that, for example, a backup program can make a fresh copy of the file, including the new permissions value. Another operation that modifies a file's ctime without affecting the others is renaming. In any case, it is not possible, in normal operations, for a user to change the ctime field to a user-specified value. Some operating systems and file systems support a fourth time: the birth time, when the file was first created; by definition, this timestamp never changes.

Time stamps assume the time zone rules specified by the TZ environment variable, or by the system default rules if TZ is not set. See (libc)TZ Variable section `Specifying the Time Zone with TZ' in The GNU C Library Reference Manual. You can avoid ambiguities during daylight saving transitions by using UTC time stamps.

The program accepts the following options. Also see Common options.

`-a'
`--time=atime'
`--time=access'
`--time=use'

Change the access time only.

`-c'
`--no-create'

Do not warn about or create files that do not exist.

`-d'
`--date=time'

Use time instead of the current time. It can contain month names, time zones, `am' and `pm', `yesterday', etc. For example, `--date="2004-02-27 14:19:13.489392193 +0530"' specifies the instant of time that is 489,392,193 nanoseconds after February 27, 2004 at 2:19:13 PM in a time zone that is 5 hours and 30 minutes east of UTC. See section Date input formats. File systems that do not support high-resolution time stamps silently ignore any excess precision here.

`-f'

Ignored; for compatibility with BSD versions of touch.

`-h'
`--no-dereference'

Attempt to change the timestamps of a symbolic link, rather than what the link refers to. When using this option, empty files are not created, but option `-c' must also be used to avoid warning about files that do not exist. Not all systems support changing the timestamps of symlinks, since underlying system support for this action was not required until POSIX 2008. Also, on some systems, the mere act of examining a symbolic link changes the access time, such that only changes to the modification time will persist long enough to be observable. When coupled with option `-r', a reference timestamp is taken from a symbolic link rather than the file it refers to.

`-m'
`--time=mtime'
`--time=modify'

Change the modification time only.

`-r file'
`--reference=file'

Use the times of the reference file instead of the current time. If this option is combined with the `--date=time' (`-d time') option, the reference file's time is the origin for any relative times given, but is otherwise ignored. For example, `-r foo -d '-5 seconds'' specifies a time stamp equal to five seconds before the corresponding time stamp for `foo'. If file is a symbolic link, the reference timestamp is taken from the target of the symlink, unless `-h' was also in effect.

`-t [[cc]yy]mmddhhmm[.ss]'

Use the argument (optional four-digit or two-digit years, months, days, hours, minutes, optional seconds) instead of the current time. If the year is specified with only two digits, then cc is 20 for years in the range 0 … 68, and 19 for years in 69 … 99. If no digits of the year are specified, the argument is interpreted as a date in the current year. Note that ss may be `60', to accommodate leap seconds.

On older systems, touch supports an obsolete syntax, as follows. If no timestamp is given with any of the `-d', `-r', or `-t' options, and if there are two or more files and the first file is of the form `mmddhhmm[yy]' and this would be a valid argument to the `-t' option (if the yy, if any, were moved to the front), and if the represented year is in the range 1969-1999, that argument is interpreted as the time for the other files instead of as a file name. This obsolete behavior can be enabled or disabled with the _POSIX2_VERSION environment variable (see section Standards conformance), but portable scripts should avoid commands whose behavior depends on this variable. For example, use `touch ./12312359 main.c' or `touch -t 12312359 main.c' rather than the ambiguous `touch 12312359 main.c'.

An exit status of zero indicates success, and a nonzero value indicates failure.


[ << ] [ >> ]           [Top] [Contents] [Index] [ ? ]

This document was generated on January, 20 2010 using texi2html 1.76.