Man Pages and Permissions

Man Pages

There are many Unix commands, and most have several different arguments and options, making it implausible to remember all but a small number of them. Unix systems come with a built in manual, called "man pages".

The man pages list all of the things each command can do. Given this they are long and detailed. Being able to read them to discover what commands can do and how they work is really important for using the command-line effectively.

To look up the man page for a specific command, use the man command, and pass the command to lookup as the argument. For example, to read the man page for cp, we could run the following command:

ifinlay@cpsc:~$ man cp

You would then see the manual:

The man page for cp.

Reading Man Pages

man pages contain a synopsis section which gives you the basic syntax of the command. There may be several lines in the synopsis section which each give a different usage. In the cp example, there are three:

cp [OPTION]... [-T] SOURCE DEST
cp [OPTION]... SOURCE... DIRECTORY
cp [OPTION]... -t DIRECTORY SOURCE...

In the synopsis lines, anything inside of brackets, like [OPTION], is optional. The "..." means that there can be multiple of the preceding element. For example, the first line allows only one source, but the second allows multiple.

The first line is the case where one file is being copied to another location. The second is when multiple sources are copied. In this instance, the final parameter must be a directory — not another file. The third shows us a way of specifying the destination directory before the sources with the -t option, if we ever needed to do that for some reason.

The description section of the man page for cp lists all of the options that the command accepts with a description of each one.

Options

Most commands accept two types of options, short and long. For example, cp has this option in its man page:

-v, --verbose
       explain what is being done

The commands cp -v and cp --verbose are exactly identical. The short options are probably more common and that is what I will mostly use in this course.

Some options do not have a short form, however, such as the --strip-trailing-slashes option that cp supports.

Some options also require values to be set for them. One example is the "-t" flag to cp which is describes thusly in the man page:

-t, --target-directory=DIRECTORY
       copy all SOURCE arguments into DIRECTORY

The purpose of this option is to allow us to specify the target directory to copy to. When using the short version of this option, the required value (DIRECTORY in this case) comes right after the option. So to use this option to copy some files to the /tmp/ directory we could use:

ifinlay@cpsc:~$ cp -t /tmp/ file1 file2

With the long form of an option however, an equal sign character is placed between the option and the required value. To run the above command using the long form option would look like this:

ifinlay@cpsc:~$ cp --target-directory=/tmp/ file1 file2

Man Shortcuts

The man program, like Vim, suspends your normal shell until you exit out of it. man supports a few commands which allow you to navigate the manual:

j	Scroll down.
k	Scroll up.
Space	Scroll down one window.
/	Search forward.
?	Search backward.
g	Go to the top.
G	Go to the end.
q	Quit.
h	Display a help screen.

As you can see, the short cuts are modeled after those of Vim.

Like Vim, when you search with / or ?, you enter your search term right after typing the / or ? character, then hit enter to search for it. Also like Vim, you move to the next match with the 'n' key and to the previous match with the 'N' key.

File Permissions

The second topic included in this week's material is file permissions. These govern which users are, and are not, allowed to access files.

When we discussed the ls command back in week 2, we looked at the "-l" flag which gives detailed file listings. The output might look something like this:

ifinlay@cpsc:~$ ls -l
total 16
-rw-rw-r-- 1 ifinlay faculty    2 Jun 25 12:33 a.txt
-rw------- 1 ifinlay faculty    2 Jun 25 12:25 b.txt
-rw------- 1 ifinlay faculty    2 Jun 25 12:25 c.txt
-rwxr-xr-- 1 ifinlay faculty    2 Jun 25 12:27 prog.sh
drwxrwxr-x 2 ifinlay faculty 4096 Jun 25 15:19 files

The portion on the far left is the file permission info. This consists of 10 characters:

The first character identifies what type of file it is. This is a "-" for regular files, and a "d" for directories.
The next three characters indicate the user permissions on the file.
The next three characters indicate the group permissions for the file.
The final three characters indicate the other permissions for the file.

Each of these is explained below:

User
This lists the permissions of the owner of the file. ls -l lists the owners of files as well as the permissions. The "ifinlay" in the output above indicates that I own those files.
Group
This lists the permissions of the group of the file. The "faculty" in the output from ls -l indicates that the group of those files is the "faculty" group. This is a group on the server for faculty members. Your group will be "students". The group system allows for giving multiple users in a system access to files.
Other
Other is all other users who are not the owner or in the group of the file.

Each group of three characters (called a triad) indicates whether the given people can read, write, or execute the file:

Read
This permission is 'r' if read access is allowed, and '-' otherwise. Permission to read a file indicates that the contents can be read. Permission to read a directories indicates that the listing of the directory is available.
Write
This permission is 'w' if write access is allowed, and '-' otherwise. Permission to write a file indicates that the file may be edited or deleted. Permission to write a directory indicates that files can be created inside of the directory.
Execute
This permission is 'x' if executable access is allowed and '-' otherwise. Permission to execute a file indicates that the file may be executed as a binary program or as a script. Permission to execute a directory indicates that files in the directory can be accessed. This is different from the read permission. For instance if there is a directory called "foo" with a file called "bar" in it, and you are allowed to "execute" foo, but not read it, then you can still access the file "foo/bar", even if you cannot read the full listing of foo.

So taking this together, the permissions on "prog.sh" above, which are "-rwxr-xr--", give us the following information:

The initial "-" tells us it's a regular file and not a directory.
The next three characters, the "rwx" indicate the owner, me, can read, write,and execute the file.
The next triad, "r-x" tell us the group (faculty) are able to read and execute the file, but not write it.
Finally, the "r--" tells us that everyone else can read the file only.

Changing File Permissions

Changing file permissions is done using the chmod command. The basic usage of this command is to pass a mode as the first argument, and then the file or files to change as the second argument.

The mode consists of:

a set of letters indicating which user or users the change should affect. These can be chosen from:
- u - the user.
- g - the group.
- o - the other users.
- a - change for all three.
an operator which is either +, or -.
a set of letters indicating which permission(s) are begin modified. These can be chosen from:
- r - read permission.
- w - write permission.
- x - execute permission.

For example, we can set a file to be unreadable by anybody but the owner with the command chmod go-r:

ifinlay@cpsc:~$ ls -l file 
-rw-r--r-- 1 ifinlay faculty 0 2018-06-26 09:52 file
ifinlay@cpsc:~$ chmod go-r file 
ifinlay@cpsc:~$ ls -l file 
-rw------- 1 ifinlay faculty 0 2018-06-26 09:52 file

Multiple mode changes can be combined up when separated by commas. For example, If I wished to allow myself to execute a file, allow those in the group to write it, and re-allow all other users to read it, I could use the following command:

ifinlay@cpsc:~$ ls -l file 
-rw------- 1 ifinlay faculty 0 2018-06-26 09:52 file
ifinlay@cpsc:~$ chmod u+x,g+w,o+r file 
ifinlay@cpsc:~$ ls -l file 
-rwx-w-r-- 1 ifinlay faculty 0 2018-06-26 09:52 file

The chmod command also supports a "-R" recursive flag. As usual, "recursive" means to apply the operation to the entire contents of a directory. For instance the command:

ifinlay@cpsc:~$ chmod -R go-r projects

Will remove the read permission for everybody but the owner from the projects directory, but also from all files and directories located anywhere under projects.

Octal Modes

There is another way of using chmod which is to specify the permissions of the file using octal (base-8) codes.

This method sets the entire permission for a file, while the method described above modifies the current permission.

The octal codes are three octal digits. Each digit maps to one of the three triads: one for each of the user, group and other permissions. Each of these triads contains the three permissions, r, w, and x.

If the permission is enabled, that is a binary one, and if not, it is a binary 0. There are eight possibilities for each triad:

Permission	Binary Representation	Octal Code
---	000	0
--x	001	1
-w-	010	2
-wx	011	3
r--	100	4
r-x	101	5
rw-	110	6
rwx	111	7

The full octal code consists of three of these octal digits.

For example, if we want to set a file so that we can read and write it, those in our group can only read it, and others cannot read or write it, we would use the code "640". The 6 is for the user's "rw-" permission. The 4 is for the group's "r--" permission and the 0 is for the others "---" permission:

ifinlay@cpsc:~$ chmod 640 file 
ifinlay@cpsc:~$ ls -l file 
-rw-r----- 1 ifinlay faculty 0 2018-06-26 09:52 file

When I first began using Linux, I used the first method of changing permissions, and you can use only that if you like. The octal modes are probably more confusing, but have some benefits. For example, the octal codes sets the permissions exactly, in a way that does not depend on the existing permissions of a file.