current community

your communities

more stack exchange communities

Stack Exchange
tour help
Take the 2-minute tour ×
Unix & Linux Stack Exchange is a question and answer site for users of Linux, FreeBSD and other Un*x-like operating systems.. It's 100% free, no registration required.
up vote 36 down vote favorite
19

While researching another problem, I came across a command,

locate something | xargs -I {} bash -c "if [ -d "{}" ]; then echo {}; fi"

that I wanted to learn more about. So I ran man xargs and get the following output:

XARGS(1)                    General Commands Manual                   XARGS(1)

NAME
       xargs - build and execute command lines from standard input

SYNOPSIS
       xargs  [-0prtx]  [-E  eof-str] [-e[eof-str]] [--eof[=eof-str]] [--null]
       [-d delimiter] [--delimiter delimiter]  [-I  replace-str]  [-i[replace-
       str]]    [--replace[=replace-str]]   [-l[max-lines]]   [-L   max-lines]
       [--max-lines[=max-lines]] [-n max-args] [--max-args=max-args] [-s  max-
       chars]  [--max-chars=max-chars]  [-P max-procs] [--max-procs=max-procs]
       [--interactive]      [--verbose]      [--exit]      [--no-run-if-empty]
       [--arg-file=file]   [--show-limits]   [--version]   [--help]   [command
       [initial-arguments]]

DESCRIPTION
       This manual page documents the GNU version of xargs...

I am trying to get better at using documentation to learn about Linux programs, but that "Synopsis" section is intimidating to new users. It literally looks like gibberish compared to man locate or man free.

So far, I understand that square brackets mean optional and nested brackets mean options in optional. But how am I supposed to induce a valid command with that?

I am not asking for help with xargs here. I am looking for help interpreting a man page to understand complicated commands. I want to stop making Google-indexed web blogs and personal help from others my first approach to learning Linux commands.

share|improve this question
12  
Continue reading the man page. The "OPTIONS" section explains all the options available in the "SYNOPSIS" section. –  John Apr 1 at 12:57
11  
More often than not, go directly to the bottom and look for an examples section. –  teppic Apr 1 at 13:05
7  
And don't just scan the man page for keywords. Really read it! Supposed strange behaviors are often well explained. –  FloHimself Apr 1 at 13:07
4  
And don't use that command which is dangerous, inefficient and unreliable. –  Stéphane Chazelas Apr 1 at 14:46
4  
after man man read man intro. –  mikeserv Apr 1 at 14:56

7 Answers 7

up vote 39 down vote accepted

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

Have in mind what you want to do.

When 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. On the following steps I'll take find as an example. Let's just pretend that we know nothing about this command.

Always read the DESCRIPTION before starting

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 how standard input works, 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. Don't even thing to jump this part of the manpage ;)

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, back to find. I know the existence of it and what it does. I have an specific problem that is: I have to look for every file with the .jpg extension, and with 500KiB (KiB = 1024 byte, commonly called kibibyte), 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 see 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.

Tips that apply to all commands

Some options, mnemonics and "syntax style" travel through all commands making you buy some time by not having to open the manpage at all. Those are learned by practice and the most common are:

  • Generally -v means verbose. -vvv is a variation "very very verbose" on some softwares.
  • Following the POSIX standard, generally one dash arguments can be stacked. Example: tar -xzvf, cp -Rv.
  • Generally -R and/or -r means recursive.
  • Almost all commands have a brief help with the --help option.
  • --version shows the version of a software.
  • -y means YES, or "proceed without confirmation" in most cases.

But, when I don't know what command is?

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

share|improve this answer
    
You can also do man find | grep .... I like man command | sed -n '/^[[:space:]]*-/,/^$/p' –  mikeserv Apr 1 at 14:48
2  
Yup. You can. I was just assuming that the operator is "noob" and trying to get started with manpages :) –  nwildner Apr 1 at 14:49
    
There's a lot of depth here. It's pretty good. But scratch that last sed thing: man ... | sed -n '$!N;/^\n[[:blank:]]*-/,/\n$/P;D' is better. –  mikeserv Apr 1 at 14:54
    
This answer needs to be the top result for "How do I effectively use man?" Thank you and well done. –  user1717828 Apr 1 at 14:58
2  
@nwildner, you deserve a candy after such huge and well formated answer. Good job! –  Willian Paixao 2 days ago
up vote 21 down vote

This is quite nicely explained in man man:

   The following conventions apply to the SYNOPSIS section and can be used
   as a guide in other sections.

   bold text          type exactly as shown.
   italic text        replace with appropriate argument.
   [-abc]             any or all arguments within [ ] are optional.
   -a|-b              options delimited by | cannot be used together.

   argument ...       argument is repeatable.
   [expression] ...   entire expression within [ ] is repeatable.

As for how you're supposed to write a valid command from that, well, you're not. The synopsis is useful once you know how a command works. It can help you refresh your memory. In order to understand how the command works, you should read the man page. Especially the descriptions of the options and the examples section.

Sometimes the synopsis is enough. For example, in man ls:

SYNOPSIS
       ls [OPTION]... [FILE]...

Other times, it is useless unless you already know how to use the command in question. For example, man dd:

   dd [OPERAND]...
   dd OPTION

So, in conclusion, don't worry if you don't get the synopsis. That's normal. Read the man page itself.

share|improve this answer
    
Thank you for the advice, especially the "As for how..." paragraph. –  user1717828 Apr 1 at 14:59
up vote 12 down vote

Some basics to understand synopsis

  • each [foo] represent optional argument or parameter.
  • when [foo [ bar ] ] syntax is used, you may use foo, and you may add bar.
  • mandatory option parameter are used this way [ -S size ] , which tell that -S argument is waiting for a mandatory size.

For instance : foo [-S size ] filename ...

means

  • command is foo
  • optional paramter -S can be use, you have to tell size (name give you a hint)
  • mandatory argument is filename (this give you an hint also, see man mkdir )
  • elipsis ... tell you you can use multiple file.

You still have to go in depth of man page to understand option (in my sample case above, what -S size is about )

share|improve this answer
up vote 10 down vote

man pages normally are displayed with less nowadays. That makes it possible to search through them. I would not bother with the synopsis, especially not because you have a particular commandline that you want to understand.

Hit the / and start typing -I and then Enter. The first hit will be in the synopsis, the second (use n for next) gets you the detailed explanation for -I.

share|improve this answer
up vote 6 down vote

One key thing to remember is that you cannot only look at the manual for one command, in the case of commands that execute other commands.

For your example command

locate something | xargs -I {} bash -c "if [ -d "{}" ]; then echo {}; fi"

You need information on not only xargs but also bash and [ (this may be in the test manpage). You may also need information on your shell (probably also bash) for the quoting rules, since your command includes a complex quoted string. I can already tell you that the quoted argument is wrong (and wrong in a way that will only show up when you encounter a file with spaces in the name); the inner "{}" should probably be '{}'.

So first you would refer to the xargs manpage and see [-I replace-str] for what -I {} means, and [command [initial-arguments]] for what bash and everything after it means. Then you would refer to the bash manpage for what -c does, etc.

share|improve this answer
up vote 0 down vote

To get a quick help with your specific command, you can use Explain Shell. E.g. your command. After getting the first high-level understanding how this works, you should proceed with manpages as other answers recommend.

share|improve this answer
up vote 0 down vote

Adding on to the great answers already given:

1) If you're interested in a gnu utility, especially ones like sed and grep, sometimes, using the info command will bring up a greatly expanded version of the command information. sed, for instance, has a detailed section on how to write regular expressions and another section with some very complex usage examples.

2) It's a "manual". A manual is primarily designed to help you remember the details of something you already understand. It's designed so you can get the details you need quickly and get out. (And way too many have no usage examples or only trivial ones.)

When I need to learn something new, even a small feature of a command that isn't clear to me, I go to the web and search using the best keywords I can think of (e.g. Linux xargs) and add the word howto, examples, or tutorial. This is very often quite productive.

I usually use duckduckgo because it maintains my privacy, but if I need more control of my searches, I use Google because I can tell it just to search within one website or to only return results from the last year. (It has many other Advanced Search options. You can Google them. ;) )

share|improve this answer

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.