7. Socket map client

The smapc program is a console-based utility for querying socket map servers. It has two operation modes. In single query mode, the utility performs a query, displays its result and exits immediately. In interactive mode, the utility enters a read-and-eval loop, in which it reads queries from the keyboard, runs them, and displays obtained results on the screen.

7.1 Single Query Mode

The simplest way to use smapc utility is to invoke it with three arguments:

 
smapc url map key
url

The URL of the server to query (see smap url).

map

The map name.

key

The lookup key.

For example:

 
$ smapc unix:///var/run/smap/sockmap aliases root@domain.com
OK smith dmk <rev@another.domain>

You may simplify the invocation if you add the URL to your initialization file, i.e. to the file smapc reads at startup for its defaults. This file resides in your home directory and is named ‘.smapc’. Open this file with your favorite editor, and add the following line to it:

 
open unix:///var/run/smap/sockmap

Now, when invoked with two arguments, smapc will use this URL by default:

 
$ smapc unix:///var/run/smap/sockmap aliases root@domain.com
OK smith dmk <rev@another.domain>

See section Initialization File, for a detailed description of this file.

7.2 Interactive Mode

If insufficient number of arguments is given in the command line, smapc enters interactive mode. In this mode it reads commands from the standard input, executes them and displays the results on the standard output. If the standard input is connected to a terminal, the readline and history facilities are enabled (see (readline)Command Line Editing section `Command Line Editing' in GNU Readline Library).

When in interactive mode, smapc displays its prompt and waits for you to enter a command. The default prompt is the name of the program, enclosed in parentheses:

 
(smapc) _

Depending on the first character, your input is recognized either as a smapc command, or as a query. All smapc commands begin with a single punctuation character, called command prefix. The default command prefix is a dot, but it can be changed using the prefix command (see section prefix). The prefix is not a part of the command, it is merely a means by which smapc recognizes that it has been given a command. So, when explaining commands below, we will refer to them by their name, without the prefix.

The most important command is ‘open’. It takes a server URL as its argument and opens a connection to that server:

 
(smapc) .open unix:///var/run/smap/sockmap

Now, if you type two or more words (the first of them not starting with the command prefix), smapc builds a query using the first word as of them is used as a map name and the rest of them as a key. It then sends the request to the server using the socket opened with the open command and displays the result on the standard output:

 
(smapc) aliases root@domain.com
OK smith dmk <rev@another.domain>

If you wish to change to another URL, give another ‘open’ command. Do not bother to close the previously opened socket: it will be done automatically.

If you are going to send a series of queries using the same map, you will save yourself some typing by declaring the default map, e.g.:

 
(smapc) .map aliases

From now on, every non-command input you give will be treated as lookup keys for that map name, e.g.:

 
(smapc) root@domain.com
OK smith dmk <rev@another.domain>
(smapc) postmaster
OK root
(smapc) daemon
NOTFOUND

If you forget what map you are currently using, type the map command without arguments. It will display the map name:

 
(smapc) .map
current map is aliases

Finally, to forget the default map and return to typing map name before the key, use ‘nomap’:

 
(smapc) .nomap

To quit the program, type ‘.quit’. Typing end-of-file character (C-d) has the same effect.

To obtain a listing of available commands with a short description for each of them, type ‘help’ or ‘?’.

7.2.1 Smapc Command Summary

This subsection lists all available smapc commands along with their short description and a reference to the part of this manual where they are described in detail. The command names are given without prefix.

smapc: open url

Open connection to socket map server at the given url. See smapc-open.

smapc: close

Close previously opened connection.

smapc: server

Show URL of the currently opened connection.

smapc: help

Display short command usage summary.

smapc: map [name]

Set the default map name. Without arguments, print the name of the map currently in use. See smapc-defmap.

smapc: nomap

Clear the default map name. After this command, map names must be given explicitly with each query. See nomap.

smapc: source [ip]

With argument, sets the source address for outgoing queries. Without argument, displays currently used source address.

smapc: debug spec

Sets the debug level. See section Tracing and Debugging, for a description of spec.

smapc: prefix [char]

If char is given, sets it as the command prefix. If called without arguments, displays the currently selected command prefix.

smapc: prompt [string]

Redefines the command prompt. Without arguments, prints the current prompt.

smapc: history

Prints the history of recently issued commands.

smapc: quit

Quits interactive mode.

smapc: quiet bool

This command command toggles the display of smapc startup banner. When started, smapc prints a short list of information useful for beginning users: the program version and warranty conditions and a command to get help, e.g.:

 
smapc (smap) 1.1
Copyright (C) 2010 Sergey Poznyakoff
License GPLv3+: GNU GPL version 3 or later
<http://gnu.org/licenses/gpl.html>
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.

Type ? for help summary

(smapc) _

If you find this output superfluous and useless, you can suppress it by setting

 
quiet yes

in your initialization file.

smapc: version

Displays the package name and version number.

smapc: warranty

Displays the copyright statement.

7.3 Initialization File

When you start smapc, it automatically executes commands from its initialization file, if such file exists. This file is located in your home directory and called ‘.smapc’.

Initialization file contains a series of smapc commands, as described in Interactive Mode, with the only difference that no command prefix is used by default. The ‘#’ character introduces a comment: any characters from (and including) ‘#’ up to the newline character are ignored(9).

Init files are useful to change the defaults for your smapc invocation. Consider, for example, this init file:

 
# Turn welcome banner off
quiet yes
# Open the default connection
open inet://127.0.0.1:3145
# Use `aliases' as a default map
map aliases
# Finally, set the custom command prefix
prefix :

Notice, that if you wish to change your command prefix, it is preferable to do it as a last command in your init file, as shown in this example.

7.4 Smap Invocation

The following table summarizes the options available for smapc. For each option a description is given and a cross reference is provided to more in-depth explanation in the body of the manual.

-B
--batch

Enable batch mode. This mode is optimized for reading input from files. The startup banner is suppressed, editing capabilities and input history are disabled, and input prompt is not shown. This mode is enabled automatically if smapd detects that its standard input is not connected to a terminal.

-p string
--prompt=string

Change command prompt. See smapc-prompt.

-Q
--quiet

Do not print the normal welcome banner. See smapc-quiet.

-q
--norc

Do not read initialization file. See section Initialization File.

-S url
--server=url

Connect to server at the given url. See smapc-open.

-s addr
--source=addr

Set source address. See smapc-source.

-T
--trace

Enable query traces. See section traces.

-d spec
-x spec
--debug=spec

Set debug verbosity level. See section Debugging information, for a detailed description. The ‘-x’ alias is for compatibility with version 1.0 and will be removed in subsequent releases.

-h
--help

Give a short summary of available command line options.

--usage

Display a list of available command line options.

-V
--version

Print program version and exit.

Footnotes

(9)

The same holds true for interactive mode as well, but you will hardly need comments on a terminal.