Introduction

Even appparently simple commands can have an abundance of options, and any you don't use regularly will probably not be at your finger-tips when you need them. Finding out which commands or options you need or what error messages mean is therefore a very common task. Many programs you use may have known bugs or oddities; you may (very occasionally) stumble across a new or undocumented bug; or you may wish to know how to do something very specific. This page discusses a few of the ways to get information and help, and some things to consider when doing so.

Man Pages

The definitive source of information on Linux commands is the built-in 'man' (manual) pages. These give a lot of information, but are not guides, and usually don't give examples or such like. However, they are a powerful resource, and are available anywhere you have a terminal, so it's a good idea to get familiar with their basics.

Man pages are invoked as

username@godzilla:~>man [command]

Man pages open in the system text editor, currently vim on the CSC system, so to exit type "q". Searching through the pages uses the normal editor commands.

Some tools also have pages in the GNU info system. For example, at the end of the man page for ls is this section:

Info is often more descriptive than man but also contains a lot of information.

Getting Specific Help

If you have internet access, google (or your favorite search engine) can be used to solve almost any problem you may have. However it takes some skill and practice to find a solution quickly.

1. The first trick is deciding how specific your problem or question is. Does the program appear to be working correctly, but you're having trouble getting the expected result, or your specific result? Is the program itself malfunctioning or missing parts?
2. Gather some more information. See Error Messages below for some information and also try and find the key words for the problem. For instance, a crash usually means a program stops unexpectedly, wheras a hang means it stops responding, and giving the wrong answer is neither.
3. Decide where to go for help. If you just need to know how a command works, a general search using the hints below can resolve things quickly. User forums, if the program has one, are a good place to ask specific questions. If it appears to be a system-level problem, such as a missing component on a cluster, you can try the relevant support system. For the SCRTP desktop and cluster, bugzilla is used. However, it's usually worth trying to find an answer before submitting a bug, and following the steps under "Writing a Bug Report".

Error Messages

Error messages can be very opaque at first, but learning to read them can save a lot of time and effort. The following steps are helpful before continuing.

• Remove very specific information: your username, the current date, the filename you're working with (but keep the extension)
• Add general information: say, for example, if you're working with a very large file, or a large number of files, or over a remote link.
• Add specific information: if the program appears to be working as expected, but you're having problems, its version number, your operating system, and your environment can be helpful. If the program isn't working, these are usually essential. Many programs can be invoked with --version to get their version info, see here for details.
  

Writing a Bug Report

Getting help with your problem or bug is made much easier by following some simple steps:

1. Look for an FAQ or a sticky link where you are submitting and read and follow it. SCRTP's bugzilla guidelines are here.
2. Search the forum/tracker and see if this is a known problem. There may be a solution, or you may be better off adding to an existing report.
3. Construct your bug. Give it:
   1. A short, descriptive title. Other users might recognise the problem, and be able to help.
   2. Version information for your program, operating system and any other relevant things. For example, the compiler version for compiled code.
   3. If possible, a minimum working example. This is the smallest piece of code, script, or action which reproduces your problem.
   4. Explain what happens?
      
      1. Under which circumstances, for example does this only happen sometimes?
      2. If you get an error, include the text using the suggestions under Error Messages.
      3. If your bug pertains to an unexpected result or behaviour, give a brief description of what you expected would happen instead.
      4. What have you tried doing to solve the problem so far?

Summary

Man pages are the built-in descriptions of linux commands, but they're often unhelpful for working out how to do something. A well constructed internet search can often get a better answer, faster.

If you have a problem with a program or computer, you may want to submit a bug report through the relevant system. Following the guidelines here makes it quicker and easier for people to help you.

Next Section

Accessing Remote Machines