Return to Revisions

Well, this is my very personal way to read manpages:

#Have in mind what you want to do.

When you was doing your research about xargs you did it for a purpouse, right? You had a specific need that was reading standard output and executing commands based on that output. I'll take find as an example here. Let's just pretend that we know nothing about this command.

#Other things to pay attention...

You know that you can search for files using find. There is a ton of options and if you look only the SYNOPSIS you will get overwhelmed by those. It's just the tip of the iceberg. Excluding NAME, SYNOPSIS, and DESCRIPTION, you will have the following sections:

• AUTHORS: the people who created or assisted in the creation of the command.

• BUGS: lists any know defects. Could be only implementation limitations.

• ENVIRONMENT: Aspects of your shell that could be affected by the command, or variables that will be used.

• EXAMPLES or NOTES: Self explained.

• REPORTING BUGS: Who you will have to contact, if you find bugs on this tool or in it's documentation.

• COPYRIGHT: Person who created and disclaimers about the software. All related with the license of the software itself.

• SEE ALSO: Other commands, tools or working aspects that are related to this command, and could not fit on any of the other sections.

You will most probably find interesting info about the aspects you want of a tool on the examples/notes section.

#Pager

When you open a manpage, it will be displayed by less or more command. I suggest you to switch to less whenever possible. If you are using linux you are probably served with you man infrastructure already configured to use less( unless you installed some minimal distro)

#Example

Ok. I know the existence of find and what it does. I have an specific problem that is: I have to look for every file with the .jpg extension, and with 500k(Kilobytes - units of 1024), or more in size inside a ftp server folder.

First, open the manual: man find. The SYNOPSIS is slim. Let's search for things inside the manual: Type / plus the word you want(size). It will index a lot of entries -size that will count specific sizes. Got stuck. Don't know how to search with "more than" or "less than" a given size, and the man does not show that to me.

Lets give it a try, and search for the next found entry by hitting n. Ok. Found something interesting: find \( -size +100M -fprintf /root/big.txt %-10s %p\n \). Maybe, this example is showing us that with -size +100M it will find files with 100Mb or more. How could i confirm? Going to the head of the manpage and searching for other words.

Again, lets try the word greater. Pressing g will lead us to the head of the manpage. /greater, and the first entry is:

 Numeric arguments can be specified as

    +n     for **greater** than n,

    -n     for less than n,

     n      for exactly n.

Sounds great. It seems that this block of manual confirmed what we suspected. However, this will not only apply to filesizes. It will apply to any n that could be found on this manpage(as the phrase said: Numeric arguments can be specified as).

Good. Let us find a way to filter by name: g /insensitive. Why? Insensitive? Wtf?. We have a hypotetical ftp server, where "that other OS" people could give a filename with extensions as .jpg, .JPG , .JpG. This will lead us to:

-ilname pattern
              Like  -lname,  but  the  match  is  case insensitive.  If the -L
              option or the -follow option is in  effect,  this  test  returns
              false unless the symbolic link is broken.

However, after you search for lname you will se hat this will only search for symbolic links. We want real files. The next entry:

   -iname pattern
          Like -name, but the match is case insensitive.  For example, the
          patterns `fo*' and `F??' match  the  file  names  `Foo',  `FOO',
          `foo',  `fOo',  etc.   In these patterns, unlike filename expan‐
          sion by the shell, an initial '.' can be matched by  `*'.   That
          is, find -name *bar will match the file `.foobar'.   Please note
          that you should quote patterns as a matter of course,  otherwise
          the shell will expand any wildcard characters in them.

Great. I don't even need to read about -name to see that -iname is the case insensitive version of this argument. Lets assemble the command:

Command: find /ftp/dir/ -size +500k -iname "*.jpg"

What is implicit here: The knowledge that the wildcard ? represents "any character at a single position" and * represents "any of characters in any quantity of them". The -name parameter will give you a brief of this knowledge.

#When this method will not work so well...

• Manpages that have no examples
• Manpages where options have a short explanation
• When you use generic keywords like and, to, for inside the manpages

In some cases the examples will be pretty simple, and you will have to make some executions of your command to test, or in a worst case scenario, google it.

#Allways read the DESCRIPTION

Take a time and read the description. By just reading the description of the xargs command we will learn that:

• xargs reads from STDIN and executes the command needed. This also means that you will need to have some knowledge of that standard input means, and how to manipulate it through pipes to chain commands
• The default behavior is to act like /bin/echo. This gives you a little tip that if you need to chain more than one xargs, you don't need to use echo to print.
• We have also learned that unix filenames can contain blank and newlines, that this could be a problem and the argument -0 is a way to prevent things explode by using null character separators. The description warns you that the command being used as input needs to support this feature too, and that GNU find support it. Great. We use a lot of find with xargs.
• xargs will stop if exit status 255 is reached.

Some descriptions are very short and that is generally because the software works on a very simple way.

#But, when i dont know what command is?

Use man -k or apropos(they are equivalent). If i dont know how to find a file: man -k file | grep search. Read the descriptions and find one that will better fit on your needs.