Linux man pages


Manual pages are grouped into sections based upon the type of command, 
function, or file they describe. 

  Section 1

      user commands
  Section 2

      system calls

      This chapter describes the Linux system calls. For a list of the 
      164 syscalls present in Linux 2.0, see syscalls(2)

  Section 3

      library functions

      This chapter describes all library functions excluding the 
      library functions described in chapter 2, which implement system 
  Section 4

      special files

      This chapter describes special files. 
      /dev/* --- device files 

  Section 5

      file formats

      This chapter describes various file formats and protocols, and 
      the used C structures, if any 

  Section 6


      This chapter describes all the games and funny little programs 
      available on the system

  Section 7

      conventions and miscellany

      This chapter describes conventions and protocols, character set 
      standards, the standard file system layout, and miscellaneous 
      other things
  Section 8

      administration and privileged commands

      This chapter describes commands which either can be or are only 
      used by the superuser, like daemons and hardware related commands

  Section L

      math library functions 

      This chapter describes commands which either can be or are only 
      used by the superuser, like daemons and hardware related commands.

  Section N

      tcl fuctions

intro - Introduction to user commands

Linux is a flavour of Unix, and as a first approximation all user 
commands under Unix work precisely the same under Linux ( and FreeBSD 
and lots of other Unix-like systems). Under Linux there are GUIs 
(graphical user interfaces), where you can point and click and drag, 
and hopefully get work done without first reading lots of 
documentation. The traditional Unix environment is a CLI (command line 
interface), where you type commands to tell the computer what to do. 
That is faster and more powerful, but requires finding out what the 
commands are. Below a bare minimum, to get started. 


In order to start working, you probably first have to login, that is, 
give your username and password. See also login(1). The program login 
now starts a shell (command interpreter) for you. In case of a 
graphical login, you get a screen with menus or icons and a mouse click
will start a shell in a window. See also xterm(1). 

The shell 

One types commands to the shell, the command interpreter. It is not 
built-in, but is just a program and you can change your shell. 
Everybody has her own favourite one. The standard one is called sh. 
See also ash(1), bash(1), csh(1), zsh(1), chsh(1). 

A session might go like 

    knuth login: aeb
    Password: ********
    % date
    Tue Aug  6 23:50:44 CEST 2002
    % cal
         August 2002
    Su Mo Tu We Th Fr Sa 
                 1  2  3
     4  5  6  7  8  9 10
    11 12 13 14 15 16 17
    18 19 20 21 22 23 24
    25 26 27 28 29 30 31

    % ls
    bin  tel
    % ls -l
    total 2
    drwxrwxr-x   2 aeb       1024 Aug  6 23:51 bin
    -rw-rw-r--   1 aeb         37 Aug  6 23:52 tel
    % cat tel
    maja    0501-1136285
    peter   0136-7399214
    % cp tel tel2
    % ls -l
    total 3
    drwxr-xr-x   2 aeb       1024 Aug  6 23:51 bin
    -rw-r--r--   1 aeb         37 Aug  6 23:52 tel
    -rw-r--r--   1 aeb         37 Aug  6 23:53 tel2
    % mv tel tel1
    % ls -l
    total 3
    drwxr-xr-x   2 aeb       1024 Aug  6 23:51 bin
    -rw-r--r--   1 aeb         37 Aug  6 23:52 tel1
    -rw-r--r--   1 aeb         37 Aug  6 23:53 tel2
    % diff tel1 tel2
    % rm tel1
    % grep maja tel2
    maja    0501-1136285

and here typing Control-D ended the session. The % here was the command
prompt - it is the shell's way of indicating that it is ready for the 
next command. The prompt can be customized in lots of ways, and one 
might include stuff like user name, machine name, current directory, 
time, etc. An assignment PS1="What next, master? " would change the 
prompt as indicated. 

We see that there are commands date (that gives date and time), and cal
(that gives a calendar). 

The command ls lists the contents of the current directory - it tells 
you what files you have. With a -l option it gives a long listing, that 
includes the owner and size and date of the file, and the permissions 
people have for reading and/or changing the file. For example, the 
file "tel" here is 37 bytes long, owned by aeb and the owner can read 
and write it, others can only read it. Owner and permissions can be 
changed by the commands chown and chmod. 

The command cat will show the contents of a file. (The name is from 
"concatenate and print": all files given as parameters are concatenated
and sent to "standard output", here the terminal screen.) 

The command cp (from "copy") will copy a file. On the other hand, the 
command mv (from "move") only renames it. 

The command diff lists the differences between two files. Here there 
was no output because there were no differences. 

The command rm (from "remove") deletes the file, and be careful! it is 
gone. No wastepaper basket or anything. Deleted means lost. 

The command grep (from "g/re/p") finds occurrences of a string in one 
or more files. Here it finds Maja's telephone number. 

Path names and the current directory 

Files live in a large tree, the file hierarchy. Each has a path name 
describing the path from the root of the tree (which is called /) to 
the file. For example, such a full path name might be /home/aeb/tel. 
Always using full path names would be inconvenient, and the name of a 
file in the current directory may be abbreviated by only giving the 
last component. That is why "/home/aeb/tel" can be abbreviated to "tel" 
when the current directory is "/home/aeb". 

The command pwd prints the current directory. 

The command cd changes the current directory. Try "cd /" and "pwd" and 
"cd" and "pwd". 


The command mkdir makes a new directory. 

The command rmdir removes a directory if it is empty, and complains 

The command find (with a rather baroque syntax) will find files with 
given name or other properties. For example, "find . -name tel" would 
find the file "tel" starting in the present directory (which is called 
"."). And "find / -name tel" would do the same, but starting at the 
root of the tree. Large searches on a multi-GB disk will be 
time-consuming, and it may be better to use locate(1). 

Disks and Filesystems 

The command mount will attach the filesystem found on some disk (or 
floppy, or CDROM or so) to the big filesystem hierarchy. And umount 
detaches it again. The command df will tell you how much of your disk 
is still free. 


On a Unix system many user and system processes run simultaneously. 
The one you are talking to runs in the foreground, the others in the 
background. The command ps will show you which processes are active and
what numbers these processes have. The command kill allows you to get 
rid of them. Without option this is a friendly request: please go away. 
And "kill -9" followed by the number of the process is an immediate 
kill. Foreground processes can often be killed by typing Control-C. 

Getting information 

There are thousands of commands, each with many options. Traditionally 
commands are documented on man pages, (like this one), so that the 
command "man kill" will document the use of the command "kill" (and 
"man man" document the command "man"). The program man sends the text 
through some pager, usually less. Hit the space bar to get the next 
page, hit q to quit. 

In documentation it is custumary to refer to man pages by giving the 
name and section number, as in man(1). Man pages are terse, and allow 
you to find quickly some forgotten detail. For newcomers an 
introductory text with more examples and explanations is useful. 

A lot of GNU/FSF software is provided with info files. Type "info info" 
for an introduction on the use of the program "info". 

Special topics are often treated in HOWTOs. 
Look in /usr/share/doc/howto/en and use a browser if you find HTML 
files there. 

intro, _syscall - Introduction to system calls 

This chapter describes the Linux system calls. For a list of the 164 
syscalls present in Linux 2.0, see syscalls(2).

Calling Directly 

In most cases, it is unnecessary to invoke a system call directly, but 
there are times when the Standard C library does not implement a nice 
function call for you. 

  A _syscall macro 
  desired system call 

The important thing to know about a system call is its prototype. You 
need to know how many arguments, their types, and the function return 
type. There are six macros that make the actual call into the system 
easier. They have the form: 

  _syscallX(type,name,type1,arg1, type2,arg2,...) 

where X is 0-5, which are the number of arguments taken by the system 
      call type is the return type of the system call 
      name is the name of the system call 
      typeN is the Nth argument's type 
      argN is the name of the Nth argument

These macros create a function called name with the arguments you 
specify. Once you include the _syscall() in your source file, you call 
the system call by name.  


#include    /* for _syscallX macros/related stuff */
#include    /* for struct sysinfo */

_syscall1(int, sysinfo, struct sysinfo *, info);

/* Note: if you copy directly from the nroff source, remember to
   REMOVE the extra backslashes in the printf statement. */

int main(void)
    struct sysinfo s_info;
    int error;

    error = sysinfo(&s_info);
    printf("code error = %d\n", error);
    printf("Uptime = %lds\nLoad: 1 min %lu / 5 min %lu / 15 min %lu\n"
            "RAM: total %lu / free %lu / shared %lu\n"
            "Memory in buffers = %lu\nSwap: total %lu / free %lu\n"
            "Number of processes = %d\n",
            s_info.uptime, s_info.loads[0],
            s_info.loads[1], s_info.loads[2],
            s_info.totalram, s_info.freeram,
            s_info.sharedram, s_info.bufferram,
            s_info.totalswap, s_info.freeswap,

Sample Output

code error = 0
uptime     = 502034s

Load: 1 min 13376 / 5 min 5504 / 15 min 1152
RAM: total 15343616 / free 827392 / shared 8237056
Memory in buffers = 5066752
Swap: total 27881472 / free 24698880
Number of processes = 40


The _syscall() macros DO NOT produce a prototype. You may have to 
create one, especially for C++ users. 

System calls are not required to return only positive or negative 
error codes. You need to read the source to be sure how it will return 
errors. Usually, it is the negative of a standard error code, e.g., 
-EPERM. The _syscall() macros will return the result r of the system 
call when r is nonnegative, but will return -1 and set the variable 
errno to -r when r is negative. For the error codes, see errno(3). 

Some system calls, such as mmap, require more than five arguments. 
These are handled by pushing the arguments on the stack and passing a 
pointer to the block of arguments. 

When defining a system call, the argument types MUST be passed by-value
or by-pointer (for aggregates like structs). 

The preferred way to invoke system calls that glibc does not know about 
yet, is via syscall(2). 

Conforming to

Certain codes are used to indicate Unix variants and standards to which
calls in the section conform. These are: 

 SVr4        System V Release 4 Unix, as described in the "Programmer's 
             Reference Manual: Operating System API (Intel processors)" 
             (Prentice-Hall 1992, ISBN 0-13-951294-2) 

 SVID        System V Interface Definition, as described in 
             "The System V Interface Definition, Fourth Edition". 

 POSIX.1     IEEE 1003.1-1990 part 1, aka ISO/IEC 9945-1:1990s, 
             aka "IEEE Portable Operating System Interface for 
             Computing Environments", as elucidated in Donald Lewine's 
             "POSIX Programmer's Guide" (O'Reilly & Associates, Inc., 
             1991, ISBN 0-937175-73-0. 

 POSIX.1b    IEEE Std 1003.1b-1993 (POSIX.1b standard) describing 
             real-time facilities for portable operating systems, 
             aka ISO/IEC 9945-1:1996, as elucidated in "Programming for 
             the real world - POSIX.4" by Bill O. Gallmeister (O'Reilly 
             & Associates, Inc. ISBN 1-56592-074-0). 

 SUS, SUSv2  Single Unix Specification. Developed by X/Open and The 
             Open Group. See also 

 4.3BSD      The 4.3 distribution of Berkeley Unix. 

 4.4BSD      4.4BSD was upward-compatible from 4.3. 

 V7          Version 7, the ancestral Unix from Bell Labs.

intro - Introduction to library functions 

This chapter describes all library functions excluding the library 
functions described in chapter 2, which implement system calls. There 
are various function groups which can be identified by a letter which 
is appended to the chapter number: 

(3C) These functions, the functions from chapter 2 and from 
     chapter 3S are contained in the C standard library libc, which 
     will be used by cc(1) by default. 

(3S) These functions are parts of the stdio(3) library. They are 
     contained in the standard C library libc. 

(3M) These functions are contained in the arithmetic library libm. 
     They are used by the f77(1) FORTRAN compiler by default, but not 
     by the cc(1) C compiler, which needs the option -lm. 

(3F) These functions are part of the FORTRAN library libF77. There are 
     no special compiler flags needed to use these functions. 

(3X) Various special libraries. The manual pages documenting their 
     functions specify the library names.

Date:   20050522