term

package: termutils

title: term(7)

summary: conventions for naming terminal types

text:
# term(7)

## NAME
term - conventions for naming terminal types

## DESCRIPTION
The environment variable TERM should normally contain the type name of the terminal, console or display-device type you are using. This information is critical for all screen-oriented programs, including your editor and mailer.

A default TERM value will be set on a per-line basis by either /etc/inittab (e.g., System-V-like UNIXes) or /etc/ttys (BSD UNIXes). This will nearly always suffice for workstation and microcomputer consoles.

If you use a dialup line, the type of device attached to it may vary. Older UNIX systems pre-set a very dumb terminal type like “dumb” or “dialup” on dialup lines. Newer ones may pre-set “vt100”, reflecting the prevalence of DEC VT100-compatible terminals and personal-computer emulators.

Modern telnets pass your TERM environment variable from the local side to the remote one. There can be problems if the remote terminfo or termcap entry for your type is not compatible with yours, but this situation is rare and can almost always be avoided by explicitly exporting “vt100” (assuming you are in fact using a VT100-superset console, terminal, or terminal emulator).

In any case, you are free to override the system TERM setting to your taste in your shell profile. The tset(1) utility may be of assistance; you can give it a set of rules for deducing or requesting a terminal type based on the tty device and baud rate.

Setting your own TERM value may also be useful if you have created a custom entry incorporating options (such as visual bell or reverse-video) which you wish to override the system default type for your line.

Terminal type descriptions are stored as files of capability data underneath /usr/share/terminfo. To browse a list of all terminal names recognized by the system, do

toe | more

from your shell. These capability files are in a binary format optimized for retrieval speed (unlike the old text-based termcap format they replace); to examine an entry, you must use the infocmp(1M) command. Invoke it as follows:

infocmp entry_name

where entry_name is the name of the type you wish to examine (and the name of its capability file the subdirectory of /usr/share/terminfo named for its first letter). This command dumps a capability file in the text format described by terminfo(5).

The first line of a terminfo(5) description gives the names by which terminfo knows a terminal, separated by “|” (pipe-bar) characters with the last name field terminated by a comma. The first name field is the type's primary name, and is the one to use when setting TERM. The last name field (if distinct from the first) is actually a description of the terminal type (it may contain blanks; the others must be single words). Name fields between the first and last (if present) are aliases for the terminal, usually historical names retained for compatibility.

There are some conventions for how to choose terminal primary names that help keep them informative and unique. Here is a step-by-step guide to naming terminals that also explains how to parse them:

First, choose a root name. The root will consist of a lower-case letter followed by up to seven lower-case letters or digits. You need to avoid using punctuation characters in root names, because they are used and interpreted as filenames and shell meta-characters (such as !, $, *, ?, etc.) embedded in them may cause odd and unhelpful behavior. The slash (/), or any other character that may be interpreted by anyone's file system (\, $, [, ]), is especially dangerous (terminfo is platform-independent, and choosing names with special characters could someday make life difficult for users of a future port). The dot (.) character is relatively safe as long as there is at most one per root name; some historical terminfo names use it.

The root name for a terminal or workstation console type should almost always begin with a vendor prefix (such as hp for Hewlett-Packard, wy for Wyse, or att for AT&T terminals), or a common name of the terminal line (vt for the VT series of terminals from DEC, or sun for Sun Microsystems workstation consoles, or regent for the ADDS Regent series. You can list the terminfo tree to see what prefixes are already in common use. The root name prefix should be followed when appropriate by a model number; thus vt100, hp2621, wy50.

The root name for a PC-Unix console type should be the OS name, i.e., linux, bsdos, freebsd, netbsd. It should not be console or any other generic that might cause confusion in a multi-platform environment! If a model number follows, it should indicate either the OS release level or the console driver release level.

The root name for a terminal emulator (assuming it does not fit one of the standard ANSI or vt100 types) should be the program name or a readily recognizable abbreviation of it (i.e., versaterm, ctrm).

Following the root name, you may add any reasonable number of hyphen-separated feature suffixes.

2p

Has two pages of memory. Likewise 4p, 8p, etc.

mc

Magic-cookie. Some terminals (notably older Wyses) can only support one attribute without magic-cookie lossage. Their base entry is usually paired with another that has this suffix and uses magic cookies to support multiple attributes.

-am

Enable auto-margin (right-margin wraparound).

-m

Mono mode - suppress color support.

-na

No arrow keys - termcap ignores arrow keys which are actually there on the terminal, so the user can use the arrow keys locally.

-nam

No auto-margin - suppress am capability.

-nl

No labels - suppress soft labels.

-nsl

No status line - suppress status line.

-pp

Has a printer port which is used.

-rv

Terminal in reverse video mode (black on white).

-s

Enable status line.

-vb

Use visible bell (flash) rather than beep.

-w

Wide; terminal is in 132-column mode.

Conventionally, if your terminal type is a variant intended to specify a line height, that suffix should go first. So, for a hypothetical FuBarCo model 2317 terminal in 30-line mode with reverse video, best form would be fubar-30-rv (rather than, say, “fubar-rv-30”).

Terminal types that are written not as standalone entries, but rather as components to be plugged into other entries via use capabilities, are distinguished by using embedded plus signs rather than dashes.

Commands which use a terminal type to control display often accept a -T option that accepts a terminal name argument. Such programs should fall back on the TERM environment variable when no -T option is specified.

## PORTABILITY
For maximum compatibility with older System V UNIXes, names and aliases should be unique within the first 14 characters.

## FILES
/usr/share/terminfo/?/*

compiled terminal capability database

/etc/inittab

tty line initialization (AT&T-like UNIXes)

/etc/ttys

tty line initialization (BSD-like UNIXes)

## SEE ALSO
curses(3X), terminfo(5), term(5).


tigmanual

package: tig

title: tigmanual(7)

summary: text\-mode interface for Git

text:
# tigmanual(7)

## NAME
tigmanual - text-mode interface for Git

## SYNOPSIS

```
tig        [options] [revisions] [--] [paths]
tig show   [options] [revisions] [--] [paths]
tig blame  [options] [rev] [--] path
tig status
tig <      [Git command output]
```

## DESCRIPTION
This is the manual for Tig, the ncurses-based text-mode interface for git. Tig allows you to browse changes in a Git repository and can additionally act as a pager for output of various Git commands. When used as a pager, it will display input from stdin and colorize it.

When browsing repositories, Tig uses the underlying Git commands to present the user with various views, such as summarized commit log and showing the commit with the log message, diffstat, and the diff.

## CALLING CONVENTIONS

### Pager Mode
If stdin is a pipe, any log or diff options will be ignored and the pager view will be opened loading data from stdin. The pager mode can be used for colorizing output from various Git commands.

Example on how to colorize the output of git-show(1):

```
$ git show | tig
```

### Git Command Options
All Git command options specified on the command line will be passed to the given command and all will be shell quoted before they are passed to the shell.

Note If you specify options for the main view, you should not use the --pretty option as this option will be set automatically to the format expected by the main view.

Example on how to view a commit and show both author and committer information:

```
$ tig show --pretty=fuller
```

See the section on specifying revisions for an introduction to revision options supported by the Git commands. For details on specific Git command options, refer to the man page of the command in question.

## THE VIEWER
The display consists of a status window on the last line of the screen and one or more views. The default is to only show one view at a time but it is possible to split both the main and log view to also show the commit diff.

If you are in the log view and press Enter when the current line is a commit line, such as:

```
commit 4d55caff4cc89335192f3e566004b4ceef572521
```

You will split the view so that the log view is displayed in the top window and the diff view in the bottom window. You can switch between the two views by pressing Tab. To maximize the log view again, simply press l.

### Views
Various views of a repository are presented. Each view is based on output from an external command, most often git log, git diff, or git show.

The main view

Is the default view, and it shows a one line summary of each commit in the chosen list of revisions. The summary includes author date, author, and the first line of the log message. Additionally, any repository references, such as tags, will be shown.

The log view

Presents a more rich view of the revision log showing the whole log message and the diffstat.

The reflog view

Presents a view of the reflog allowing to navigate the repo history.

The diff view

Shows either the diff of the current working tree, that is, what has changed since the last commit, or the commit diff complete with log message, diffstat and diff.

The tree view

Lists directory trees associated with the current revision allowing subdirectories to be descended or ascended and file blobs to be viewed.

The blob view

Displays the file content or "blob" of data associated with a file name.

The blame view

Displays the file content annotated or blamed by commits.

The refs view

Displays the branches, remotes and tags in the repository.

The status view

Displays status of files in the working tree and allows changes to be staged/unstaged as well as adding of untracked files.

The stage view

Displays diff changes for staged or unstaged files being tracked or file content of untracked files.

The stash view

Displays the list of stashes in the repository.

The grep view

Displays a list of files and all the lines that matches a search pattern.

The pager view

Is used for displaying both input from stdin and output from Git commands entered in the internal prompt.

The help view

Displays a quick reference of key bindings.

### Browsing State and User-defined Commands
The viewer keeps track of both what head and commit ID you are currently viewing. The commit ID will follow the cursor line and change every time you highlight a different commit. Whenever you reopen the diff view it will be reloaded, if the commit ID changed. The head ID is used when opening the main and log view to indicate from what revision to show history.

Some of the commands used or provided by Tig can be configured. This goes for some of the environment variables as well as the external commands. These user-defined commands can use arguments that refer to the current browsing state by using one of the following variables.

Table 1. Browsing state variables

%(head)

The currently viewed head ID. Defaults to HEAD

%(commit)

The currently selected commit ID.

%(blob)

The currently selected blob ID.

%(branch)

The currently selected branch name.

%(remote)

The currently selected remote name. For remote branches %(branch) will contain the branch name.

%(tag)

The currently selected tag name.

%(refname)

The currently selected reference name including the remote name for remote branches.

%(stash)

The currently selected stash name.

%(directory)

The current directory path in the tree view or "." if undefined.

%(file)

The currently selected file.

%(lineno)

The currently selected line number. Defaults to 0.

%(lineno_old)

The currently selected line number, before the diff was applied. Defaults to 0.

%(ref)

The reference given to blame or HEAD if undefined.

%(revargs)

The revision arguments passed on the command line.

%(fileargs)

The file arguments passed on the command line.

%(cmdlineargs)

All other options passed on the command line.

%(diffargs)

Options from diff-options or TIG_DIFF_OPTS used by the diff and stage view.

%(blameargs)

Options from blame-options used by the blame view.

%(logargs)

Options from log-options used by the log view.

%(mainargs)

Options from main-options used by the main view.

%(prompt)

Prompt for the argument value. Optionally specify a custom prompt using "%(prompt Enter branch name: )"

%(text)

The text of the currently selected line.

%(repo:head)

The name of the checked out branch, e.g. master

%(repo:head-id)

The commit ID of the checked out branch.

%(repo:remote)

The remote associated with the checked out branch, e.g. origin/master.

%(repo:cdup)

The path to change directory to the repository root, e.g. ../

%(repo:prefix)

The path prefix of the current work directory, e.g subdir/.

%(repo:git-dir)

The path to the Git directory, e.g. /src/repo/.git.

%(repo:worktree)

The worktree path, if defined.

%(repo:is-inside-work-tree)

Whether Tig is running inside a work tree, either true or false.

Example user-defined commands:

•Allow to amend the last commit:

```
bind generic + !git commit --amend
```

•Copy commit ID to clipboard:

```
bind generic 9 @sh -c "echo -n %(commit) | xclip -selection c"
```

•Add/edit notes for the current commit used during a review:

```
bind generic T !git notes edit %(commit)
```

•Enter Git’s interactive add for fine-grained staging of file content:

```
bind generic I !git add -i %(file)
```

•Rebase current branch on top of the selected branch:

```
bind refs 3 !git rebase -i %(branch)
```

### Title Windows
Each view has a title window which shows the name of the view, current commit ID if available, and where the view is positioned:

```
[main] c622eefaa485995320bc743431bae0d497b1d875 - commit 1 of 61 (1%)
```

By default, the title of the current view is highlighted using bold font. For long loading views (taking over 3 seconds) the time since loading started will be appended:

```
[main] 77d9e40fbcea3238015aea403e06f61542df9a31 - commit 1 of 779 (0%) 5s
```

## ENVIRONMENT VARIABLES
Several options related to the interface with Git can be configured via environment options.

### Configuration Files
Upon startup, Tig first reads the system wide configuration file ({sysconfdir}/tigrc by default) and then proceeds to read the user’s configuration file (~/.tigrc or $XDG_CONFIG_HOME/tig/config by default). The paths to either of these files can be overridden through the following environment variables:

TIGRC_USER

Path of the user configuration file.

TIGRC_SYSTEM

Path of the system wide configuration file.

### History Files
If compiled with readline support, Tig writes a persistent command and search history to ~/.tig_history or $XDG_DATA_HOME/tig/history.

### Repository References
Commits that are referenced by tags and branch heads will be marked by the reference name surrounded by [ and ]:

```
2006-03-26 19:42 Petr Baudis         | [cogito-0.17.1] Cogito 0.17.1
```

If you want to limit what branches are shown, say only show branches named master or those which start with the feature/ prefix, you can do it by setting the following variable:

```
$ TIG_LS_REMOTE="git ls-remote . master feature/*" tig
```

Or set the variable permanently in your environment.

TIG_LS_REMOTE

Command for retrieving all repository references. The command should output data in the same format as git-ls-remote(1). Defaults to:

```
git ls-remote .
```

### Diff options
It is possible to alter how diffs are shown by the diff view. If for example you prefer to have commit and author dates shown as relative dates, use:

```
$ TIG_DIFF_OPTS="--relative-date" tig
```

Or set the variable permanently in your environment.

## DEFAULT KEYBINDINGS
Below the default key bindings are shown.

### View Switching
Key

Action

m

Switch to main view.

d

Switch to diff view.

l

Switch to log view.

p

Switch to pager view.

t

Switch to (directory) tree view.

f

Switch to (file) blob view.

g

Switch to grep view.

b

Switch to blame view.

r

Switch to refs view.

y

Switch to stash view.

h

Switch to help view

s

Switch to status view

c

Switch to stage view

### View Manipulation
Key

Action

q

Close view, if multiple views are open it will jump back to the previous view in the view stack. If it is the last open view it will quit. Use Q to quit all views at once.

Enter

This key is "context sensitive" depending on what view you are currently in. When in log view on a commit line or in the main view, split the view and show the commit diff. In the diff view pressing Enter will simply scroll the view one line down.

Tab

Switch to next view.

R

Reload and refresh the current view.

O

Maximize the current view to fill the whole display.

Up

This key is "context sensitive" and will move the cursor one line up. However, if you opened a split view it will change the cursor to point to the previous commit in the parent view and update the child view to display it. If you prefer this key to move the cursor or scroll within the diff view instead, use bind diff <Up> move-up or bind diff <Up> scroll-line-up, respectively.

Down

Similar to Up but will move down.

,

Move to parent. In the tree view, this means switch to the parent directory. In the blame view it will load blame for the parent commit. For merges the parent is queried.

### View Specific Actions
Key

Action

u

Update status of file. In the status view, this allows you to add an untracked file or stage changes to a file for next commit (similar to running git-add <filename>). In the stage view, when pressing this on a diff chunk line stages only that chunk for next commit, when not on a diff chunk line all changes in the displayed diff are staged.

M

Resolve unmerged file by launching git-mergetool(1). Note, to work correctly this might require some initial configuration of your preferred merge tool. See the manpage of git-mergetool(1).

!

Checkout file with unstaged changes. This will reset the file to contain the content it had at last commit.

1

Stage single diff line.

@

Move to next chunk in the stage view.

]

Increase the diff context.

[

Decrease the diff context.

### Cursor Navigation
Key

Action

k

Move cursor one line up.

j

Move cursor one line down.

PgUp, -

Move cursor one page up.

PgDown, Space

Move cursor one page down.

Home

Jump to first line.

End

Jump to last line.

### Scrolling
Key

Action

Insert

Scroll view one line up.

Delete

Scroll view one line down.

ScrollBack

Scroll view one page up.

ScrollFwd

Scroll view one page down.

Left

Scroll view one column left.

Right

Scroll view one column right.

|

Scroll view to the first column.

### Searching
Key

Action

/

Search the view. Opens a prompt for entering search regexp to use.

?

Search backwards in the view. Also prompts for regexp.

n

Find next match for the current search regexp.

N

Find previous match for the current search regexp.

### Misc
Key

Action

Q

Quit.

<C-L>

Redraw screen.

z

Stop all background loading. This can be useful if you use Tig in a repository with a long history without limiting the revision log.

v

Show version.

o

Open option menu

\#

Toggle line numbers on/off.

D

Toggle date display on/off/relative/relative-compact/custom

A

Toggle author display on/off/abbreviated/email/email user name.

G

Toggle revision graph visualization on/off.

~

Toggle (line) graphics mode

F

Toggle reference display on/off (tag and branch names).

W

Toggle ignoring whitespace on/off for diffs

X

Toggle commit ID display on/off

%

Toggle file filtering in order to see the full diff instead of only the diff concerning the currently selected file.

$

Toggle highlighting of commit title overflow.

H

Go to the HEAD commit.

:

Open prompt. This allows you to specify what command to run and also to jump to a specific line, e.g. :23

e

Open file in editor.

### Prompt
Key

Action

:<number>

Jump to the specific line number, e.g. :80.

:<sha>

Jump to a specific commit, e.g. :2f12bcc.

:<x>

Execute the corresponding key binding, e.g. :q.

:!<command>

Execute a system command in a pager, e.g. :!git log -p.

:<action>

Execute a Tig command, e.g. :edit.

:goto <rev>

Jump to a specific revision, e.g. :goto %(commit)^2 to goto the current commit’s 2nd parent or :goto some/branch to goto the commit denoting the branch some/branch.

:save-display <file>

Save current display to <file>.

:save-options <file>

Save current options to <file>.

:save-view <file>

Save view info to <file> (for testing purposes).

:script <file>

Execute commands from <file>.

:exec <flags><args...>

Execute command using <args> with external user-defined command option flags defined in <flags>.

:echo <args...>

Display text in the status bar.

### External Commands
For more custom needs, external commands provide a way to easily execute a script or program. They are bound to keys and use information from the current browsing state, such as the current commit ID. Tig comes with the following built-in external commands:

Keymap

Key

Action

main

C

git cherry-pick %(commit)

status

C

git commit

generic

G

git gc

## REVISION SPECIFICATION
This section describes various ways to specify what revisions to display or otherwise limit the view to. Tig does not itself parse the described revision options so refer to the relevant Git man pages for further information. Relevant man pages besides git-log(1) are git-diff(1) and git-rev-list(1).

You can tune the interaction with Git by making use of the options explained in this section. For example, by configuring the environment variable described in the section on diff options.

### Limit by Path Name
If you are interested only in those revisions that made changes to a specific file (or even several files) list the files like this:

```
$ tig Makefile README
```

To avoid ambiguity with Tig’s subcommands or repository references such as tag names, be sure to separate file names from other Git options using "--". So if you have a file named status it will clash with the status subcommand, and thus you will have to use:

```
$ tig -- status
```

### Limit by Date or Number
To speed up interaction with Git, you can limit the amount of commits to show both for the log and main view. Either limit by date using e.g. --since=1.month or limit by the number of commits using -n400.

If you are only interested in changes that happened between two dates you can use:

```
$ tig --after="May 5th" --before="2006-05-16 15:44"
```

Note If you want to avoid having to quote dates containing spaces you can use "." instead, e.g. --after=May.5th.

### Limiting by Commit Ranges
Alternatively, commits can be limited to a specific range, such as "all commits between tag-1.0 and tag-2.0". For example:

```
$ tig tag-1.0..tag-2.0
```

This way of commit limiting makes it trivial to only browse the commits which haven’t been pushed to a remote branch. Assuming origin is your upstream remote branch, using:

```
$ tig origin..HEAD
```

will list what will be pushed to the remote branch. Optionally, the ending HEAD can be left out since it is implied.

### Limiting by Reachability
Git interprets the range specifier "tag-1.0..tag-2.0" as "all commits reachable from tag-2.0 but not from tag-1.0". Where reachability refers to what commits are ancestors (or part of the history) of the branch or tagged revision in question.

If you prefer to specify which commit to preview in this way use the following:

```
$ tig tag-2.0 ^tag-1.0
```

You can think of ^ as a negation operator. Using this alternate syntax, it is possible to further prune commits by specifying multiple branch cut offs.

### Combining Revisions Specification
Revision options can to some degree be combined, which makes it possible to say "show at most 20 commits from within the last month that changed files under the Documentation/ directory."

```
$ tig --since=1.month -n20 -- Documentation/
```

### Examining All Repository References
In some cases, it can be useful to query changes across all references in a repository. An example is to ask "did any line of development in this repository change a particular file within the last week". This can be accomplished using:

```
$ tig --all --since=1.week -- Makefile
```

## MORE INFORMATION
Please visit Tig’s home page[1] or main Git repository[2] for information about new releases and how to report bugs and feature requests.

## COPYRIGHT
Copyright (c) 2006-2014 Jonas Fonseca <jonas.fonseca@gmail.com[3]>

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

## SEE ALSO
Manpages:

•tig(1)

•tigrc(5)

## NOTES
1.

home page

https://jonas.github.io/tig

2.

main Git repository

https://github.com/jonas/tig

3.

jonas.fonseca@gmail.com

mailto:jonas.fonseca@gmail.com


timew-config

package: timewarrior

title: timew-config(7)

text:
# timew-config(7)

## NAME
timew-config - Timewarrior configuration file and override options

## SYNOPSIS
timew rc.<name>=<value> <command>

## DESCRIPTION
Timewarrior stores its configuration in the user's home directory in ~/.timewarrior/timewarrior.cfg. This file contains a mix of rules and configuration settings. Note that the TIMEWARRIORDB environment variable can be set to override this location. The values 'true', '1', 'y', 'yes' and 'on' are all equivalent and enable a setting. Any other value means disable the setting. Default values may be overridden by timewarrior.cfg values, which may in turn be overridden on the command line using: rc.<name>=<value>

For example, to turn off verbose mode:

rc.verbose=0

Note that hints can also do this (:quiet).

## CONFIGURATION
confirmation

Determines whether harmful operations require interactive confirmation.

May be overridden by the ':yes' hint.

Default value is 'yes'.

verbose

Determines whether Timewarrior generates feedback.

May be overridden by the ':quiet' hint.

Default value is 'yes'.

debug

Determines whether diagnostic debugging information is shown.

Useful for troubleshooting, but not for general use.

Default value is 'off'.

debug.indicator

The debug output prefix string.

Default value is '>>'.


timew-dates

title: timew-dates(7)

summary: date formats supported by Timewarrior

text:
# timew-dates(7)

## NAME
timew-dates - date formats supported by Timewarrior

## DESCRIPTION
Timewarrior supports the following date formats based on ISO-8601:

<extended-date> [T <extended-time>] Extended date, optional extended time

<date> [T <time>] Date, optional time

<extended-time> Extended time

<time> Time

extended-date:

YYYY-MM-DD Year, month, day

YYYY-MM Year, month, 1st

YYYY-DDD Year, Julian day 001-366

YYYY-WwwD Year, week number, day number

YYYY-Www Year, week number, day 1

extended-time:

hh:mm[:ss]Z Hours, minutes, optional seconds, UTC

hh:mm[:ss][+/-hh:mm] Hours, minutes, optional seconds, TZ

date:

YYYYMMDD Year, month, day

YYYYWww Year, week number, day number

YYYYDDD Year, Julian day 001-366

time:

hhmm[ss]Z Hour, minutes, optional seconds, UTC

hhmm[ss][+/-hh[mm]] Hour, minutes, optional seconds, TZ

Examples:

2016-06-09T08:12:00Z

2016-06T08:12:00+01:00

2016-06T08:12Z

2016-161

2016-W244

2016-W24

20160609T081200Z

2016W24

8:12:00Z

0812-0500

In addition to the standard date formats, the following are supported:

now Current date and time

today Current date at 0:00:00

yesterday Yesterday at 0:00:00

tomorrow Tomorrow at 0:00:00 (midnight tonight)

<day-of-week> Previous named day at 0:00:00

<month-of-year> Previous 1st of the month at 0:00:00

hh:mm[:ss][am|a|pm|p] Short time format

Nst, Nnd, Nrd, Nth Previous 1st, 2nd, 3rd ...

<epoch> POSIX time

later 2038-01-18T0:00:00 (Y2K38)

someday 2038-01-18T0:00:00 (Y2K38)

sopd, eopd Start/end of previous day

sod, eod Start/end of current day

sond, eond Start/end of next day

sopw, eopw Start/end of previous week

sow, eow Start/end of current week

sonw, eonw Start/end of next week

sopww, eopww Start/end of previous work week (mon - fri)

soww, eoww Start/end of current work week (mon - fri)

sonww, eonww Start/end of next work week (mon - fri)

sopm, eopm Start/end of previous month

som, eom Start/end of current month

sonm, eonm Start/end of next month

sopq, eopq Start/end of previous quarter

soq, eoq Start/end of current quarter

sonq, eonq Start/end of next quarter

sopy, eopy Start/end of previous year

soy, eoy Start/end of current year

sony, eony Start/end of next year

easter Easter Sunday

eastermonday Easter Monday

ascension Ascension

pentecost Pentecost

goodfriday Good Friday

midsommar midnight, 1st Saturday after 20th June

midsommarafton midnight, 1st Friday after 19th June

juhannus midnight, 1st Friday after 19th June

Examples:

8am

24th

monday

august

## SEE ALSO
timew-durations(7), timew-hints(7)


timew-dom

title: timew-dom(7)

summary: Timewarrior DOM

text:
# timew-dom(7)

## NAME
timew-dom - Timewarrior DOM

## DESCRIPTION
Supported DOM references are:

dom.tag.count Count of all tags

dom.tag.1 Nth tag used

dom.active '1' if there is active tracking, otherwise '0'

dom.active.tag.count Count of active tags

dom.active.tag.1 Active Nth tag

dom.active.start Active start timestamp (ISO Extended local date)

dom.active.duration Active elapsed (ISO Period)

dom.active.json Active interval as JSON

dom.tracked.count Count of tracked intervals

dom.tracked.1.tag.count Count of active tags

dom.tracked.1.tag.1 Tracked Nth, Nth tag

dom.tracked.1.start Tracked Nth, start time

dom.tracked.1.end Tracked Nth, end time, blank if closed

dom.tracked.1.duration Tracked Nth, elapsed

dom.tracked.1.json Tracked Nth, interval as JSON

dom.rc.<name> Configuration setting


timew-durations

title: timew-durations(7)

text:
# timew-durations(7)

## NAME
timew-durations - duration formats supported by Timewarrior

## DESCRIPTION
Timewarrior supports the following duration formats based on ISO-8601:

'P' [nn 'Y'] [nn 'M'] [nn 'D'] ['T' [nn 'H'] [nn 'M'] [nn 'S']]

PnnW

Examples:

P1Y 1 year

P1.5M 1.5 months

PT1S 1 second

PT4.5H 4.5 hours

PT4H30M 4.5 hours

P600D 600 days

P3W 3 weeks

P1Y1DT1H1M1S 1 year and 25 hours, 61 seconds (imprecise term)

Note that the year and month terms are imprecise, being defined as 365d and 30d respectively. For precision use the other terms.

In addition to the standard duration formats, the following are supported:

n[.n]<unit>

Where the <unit> is one of:

annual

biannual

bimonthly

biweekly

biyearly

daily

days, day, d

fortnight

hours, hour, hrs, hr, h

minutes, minute, mins, min

monthly, months, month, mnths, mths, mth, mos, mo, m

quarterly, quarters, quarter, qrtrs, qtr, q

semiannual

sennight

seconds, second, secs, sec, s

weekdays

weekly, weeks, week, wks, wk, w

yearly, years, year, yrs, yr, y

Examples:

1hour 60 minutes

1.5h 90 minutes

3mo 3 months

10d 10 days

Note that the year, quarter and month terms are imprecise, being defined as 365d, 91d and 30d respectively. For precision use the other terms.


timew-hints

title: timew-hints(7)

summary: Timewarrior hints

text:
# timew-hints(7)

## NAME
timew-hints - Timewarrior hints

## DESCRIPTION
Timewarrior supports hints, which are single-word command line features that start with a colon like this:

:week

Hints serve several purposes. This example is a shortcut for the date range that defines the current week.

Other hints, such as:

:quiet

Are ways to control the behavior of Timewarrior, in this case eliminating all forms of feedback, for purposes of automation.

The supported hints are:

:quiet Turns off all feedback. For automation

:debug Runs in debug mode, shows many runtime details

:yes Overrides confirmation by answering 'yes' to the questions

:color Force color on, even if not connected to a TTY

:nocolor Force color off, even if connected to a TTY

:blank Leaves tracked time out of a report

:fill Expand time to fill surrounding available gap

:adjust Automatically correct overlaps

:ids Displays interval ID numbers in the summary report

Range hints provide convenient shortcuts to date ranges:

:yesterday The 24 hours of the previous day

:day The 24 hours of the current day

:week This week

:month This month

:quarter This quarter

:year This year

:lastweek Last week

:lastmonth Last month

:lastquarter Last quarter

:lastyear Last year

:monday Previous monday

:tuesday Previous tuesday

:wednesday Previous wednesday

:thursday Previous thursday

:friday Previous friday

:saturday Previous saturday

:sunday Previous sunday


timew-ranges

title: timew-ranges(7)

text:
# timew-ranges(7)

## NAME
timew-ranges - date and time ranges supported by Timewarrior

## DESCRIPTION
An interval defines a block of time that is tracked. The syntax for specifying an interval is flexible, and may be one of:

[from] <date>

[from] <date> to/- <date>

[from] <date> for <duration>

<duration> before/after <date>

<duration> ago

[for] <duration>

Examples are:

from 9:00

from 9am - 11am

from 9:00:00 to 11:00

from 9:00 for 2h

2h after 9am

2h before 11:00

2h ago

for 2h

An interval is said to be 'closed' if there is both a start and end, and 'open' if there is no end date.


tntnet.properties

package: tntnet

title: tntnet.properties(7)

summary: configuration-file for tntnet (8)

text:
# tntnet.properties(7)

## NAME
tntnet.properties - configuration-file for tntnet (8)

## DESCRIPTION
tntnet(8) uses cxxtools for logging and is configured in the configuration-file tntnet.properties.

Because cxxtools is a meta-logging-library, which can be compiled to use different logging-libraries, the content of tntnet.properties is dependend of the underlying logging-library. Cxxtool has a built-in logging-library as default, which is documented here.

### format
The format of tntnet.properties is line-based. A line consists of a variable-name followed by a equals-symbol and a value. Lines, which does not follow this format and lines, which start with a hash (#), are ignored. It is recomended to prefix non-empty comments with a hash to make clear, that it is a comment.

### level
The logging-library has 5 levels for logging: fatal, error, warn, info and debug. Fatal has the highers priority and "debug" the lowest.

### category
Each log-message has a category. Categories are hierarchical. Names of subcategories are devided by a dot.

### log-message
Each log-message has a level and a category. If the level of the message is higher or equal to the level of the category, the message is logged. To assign a level to a category put a line with the word "logger", a dot, the category, the symbol "=" and the category into tntnet.properties. Only the first letter of the value is checked and case is ignored, so e.g. info can be specified with INFO, info, I or even ixxxx. If no level is specified for the current category, the upper category is checked. If nothing is found, the default level is used. The default level is specified by the variable "rootLogger". If no rootLogger is specified, the level error is used.

### destination
If nothing else is specified, log-messages are printed to standard-output. To redirect output to a file, specify the filename with the variable file.

The cxxtools-logger can limit the size of the log-file by rolling log-files. If the limit is reached, the current file is renamed by appending ".1" to it. If there is already a file with that name, this file is renamed to "*.2" and so on, until the maximum backupfile limit is reached. The oldest file is deleted then. To specify the maximum file size, set the variable maxfilesize. The value specified here can be postfixed with 'k' or 'M' to specify kBytes or MBytes. The maximum fileindex backed up is set with maxbackupindex.

Log-messages can be sent to another host in the network with udp. This is done by specifying a hostname and a port with the variable host. The value must be a hostname, followed by a ':' and a port. Each log-message is sent in a single udp-message.

## EXAMPLES

### logging to standard-output:
rootLogger=INFO

logger.tntnet=WARN

### logging to a file with rolling file and a background-flusher:
rootLogger=INFO

logger.tntnet=WARN

file=tntnet.log

maxfilesize=1MB

maxbackupindex=10

### logging to another host
rootLogger=INFO

logger.tntnet=WARN

host=pluto.tntnet.org:1234

## AUTHOR
This manual page was written by Tommi Mäkitalo <tommi@tntnet.org>.

## SEE ALSO
tntnet(8)


tntnet.xml

title: tntnet.xml(7)

summary: configuration file for

text:
# tntnet.xml(7)

## NAME
tntnet.xml - configuration file for tntnet(8)

## DESCRIPTION
Tntnet is configured using a xml file. The name of the file is tntnet.xml. The root node of tntnet.xml should be tntnet while it is not checked. Most of the settings are just single values. They are described here in alphabetical order.

## SETTINGS
This section describes the variables, used by Tntnet (8).

<accessLog>filename</accessLog>

Writes a log entry for each request in a common format. This format is compatible with most log file analyze systems for http servers.

The log file has the fields: peer-ip - username [time] "http-method query-string HTTP/major-version.minor-version" http-return-code content-size "referer" "user-agent"

The username, referer and user-agent may be '-' when the value is not available. Also the content-size can be empty in some cases.

Example

```
<accessLog>/var/log/tntnet/access.log</accessLog
```

<bufferSize>bytes</bufferSize>

Specifies the number of bytes sent in a single system-call. This does not limit anything in application-level. It does not affect e.g. savepoints or exception-handling. Component-output is collected completely and then passed in chunks of bufferSize bytes to the operating system.

The default value is 16384.

<comppath> [ <entry>path1</entry> ] </comppath>

comppath specifies, where tntnet should search for webapplications. Tntnet searches first in the current directory and then in each directory, you specify here, until a library is found. You can repeat the directive as many times as desired to add more entries. If it is not found, the next mappings entry is tried.

Example

```
<comppath>

  <entry>/usr/local/lib/tntnet</entry>

  <entry>/usr/local/share/tntnet</entry>
</comppath>
```

<chroot>directory</chroot>

Does a chroot(2)-system call on startup, which locks the process into the directory at system-level.

Example

```
<chroot>/var/tntnet</chroot>
```

<daemon>0|1</daemon>

If this flag is set to 1, Tntnet forks at startup and terminates the parent-process on successful initialization.

<dir>directory</dir>

Changes the current working directory of the process on startup.

Example

```
<dir>/var/tntnet</dir>
```

<enableCompression>yes|no</enableCompression>

Specifies, if Tntnet should use gzip-compression at http-level. By default Tntnet use compression. A http-client like a web browser can send a header "Accept-Encoding", to tell Tntnet, that it would accept compressed data. Tntnet then can decide, if it use compression. When the body is complete, Tntnet tries to compress the body. If the data can be compressed by more than 10%, Tntnet sends this compressed data. With this flag, this feature can be turned off.

Compression slows down processing but reduces the network-load. Normally the size of html-pages can be compressed by about 70%, while Tntnet slows down by up to 30%.

Example

```
<enableCompression>no</enableCompression>
```

<errorLog>filename</errorLog>

Redirects stderr to the specified file when tntnet runs as a daemon. If ErrorLog is not set stderr is redirected to /dev/null.

Example

```
<errorLog>/var/log/tntnet/error.log</errorLog>
```

<group>unix-group-id</group>

Changes the group under which tntnet runs.

The user is changes using the system call setgid(2), which is only allowed, when tntnet starts as root user.

Example

```
<group>tntnet-group</group>
```

<keepAliveTimeout>milliseconds</keepAliveTimeout>

Sets the timeout for keep-alive requests.

Tntnet tries to do keep-alive-requests wherever possible. This has the effect, that tntnet can receive multiple requests within a single tcp-connection. The connection times out after KeepAliveTimeout milliseconds. The timeout defaults to 15000ms.

Example

```
<keepAliveTimeout>300000</keepAliveTimeout>
```

<keepAliveMax>number</keepAliveMax>

Sets the maximum number of request per tcp-connection. This defaults to 100.

Example

```
<keepAliveTimeout>10</keepAliveTimeout>
```

<listeners>listener definition</listeners>

Specifies, on which local interfaces tntnet waits for connections. There can be more than one Listen-directives, in which case tntnet waits on every address.

See separate section Listeners

<logging>listener definition</logging>

Configures logging. See separate section logging

<listenRetry>number</listenRetry>

On startup Tntnet calls listen on the specified port. When the systemcall returns with an error, Tntnet tries again and fails after the specified number of attempts.

The default number is 5.

Example

```
<listenRetry>10</listenRetry>
```

<listenBacklog>number</listenBacklog>

The system-call listen(3p) needs a parameter backlog, which specifies, how many pending connections the operating-system should queue before it starts to ignore new request. The value is configurable here.

The default value is 16.

Example

```
<ListenBacklog>64</ListenBacklog>
```

<mappings>urlmappings</mappings>

This is the most important setting for tntnet. It specifies, which components schould be called on which urls.

For details see the section Url mapping.

<maxUrlMapCache>number</maxUrlMapCache>

Mapping urls to components is done using regular expressions. Executing these expressions is quite expensive while the number of different urls is quite limited in typical web applications. Hence tntnet caches the results.

The caching algorithm is very simple. Tntnet just collects the results in a map. When the maximum size of the list is reached, it is cleared. This makes management of the cache very cheap.

This setting sets the maximum number of entries in the map.

If you see frequently a warning message, that the cache is cleared, you may consider increasing the size.

The default value is 8192.

Example

```
<maxUrlMapCache>32768</maxUrlMapCache>
```

<maxRequestSize>number</maxRequestSize>

This directive limits the size of the request. After number Bytes the connection is just closed. This prevents denial-of-service-attacks through long requests. Every request is read into memory, so it must fit into it. Bear in mind, that if you use file-upload-fields a request might be larger than just a few bytes.

The value defaults to 0, which means, that there is no limit at all.

Example

```
<maxRequestSize>65536</maxRequestSize>
```

<maxRequestTime>seconds</maxRequestTime>

In daemon mode tntnet has a watchdog, which restarts tntnet when the maximum request time is exceeded. This happens, when a request is in a endless loop or otherwise hangs. Restarting tntnet looses all active sessions and the currently running requests. Therefore the timeout should be well long enough for the longes request.

The default value is 600 seconds, which is normally much longer than a http request should run. If the Timeout is set to 0, the watchdog is deactivated.

Example

```
<maxRequestTime>1200</maxRequestTime>
```

<minThreads>number</minThreads>

Tntnet uses a dynamic pool of worker-threads, which wait for incoming requests. MinThreads specifies, how many worker threads there have to be. This defaults to 5.

Example

```
<minThreads>10</minThreads>
```

<minCompressSize>number</minCompressSize>

Http-compression for replies smaller than this are not compressed at all.

The default value for this is 1024.

Example

```
<minCompressSize>256</minCompressSize>
```

<mimeDb>filename</mimeDb>

Specify filename for mime db. The default is /etc/mime.types.

The format of the file is just like this /etc/mime.types. A mime type is followed after white space by a list of file extensions delimited by white space.

<maxThreads>number</maxThreads>

Tntnet uses a dynamic pool of worker-threads, which wait for incoming requests. maxThreads limits the number of threads.

The default is 100.

Example

```
<maxThreads>200</maxThreads>
```

<pidFile>filename</pidFile>

When run in daemon-mode, tntnet writes the process-id of the monitor-process to filename. When the monitor-process is deactivated, the pid of the worker-process is written. This ensures, that sending a sigkill to the the stored process-id stops tntnet.

Example

```
<pidFile>/var/run/tntnet.pid</pidFile>
```

<queueSize>number</queueSize>

Tntnet has a request-queue, where new requests wait for service. This sets a maximum size of this queue, after wich new requests are not accepted.

The default value is 1000.

Example

```
<queueSize>50</queueSize>
```

<sessionTimeout>seconds</sessionTimeout>

This sets the number of seconds without requests after which a sesssion is timed out.

The default value is 300 seconds.

Example

```
<sessionTimeout>600</sessionTimeout>
```

<socketReadTimeout>milliseconds</socketReadTimeout>

A worker-thread waits for some milliseconds on incoming data. If there is no data, the job is put into a queue and another thread waits with poll(2) on incoming data on multiple sockets. The workerthreads are freed and they can respond to other requests quickly. The default value is 10 milliseconds, which is good for normal operation. A value of 0 results in non-blocking read. If timeout is reached, this does not mean, that the socket is closed. A small timeout reduces contextswitches on slow connections.

Example

```
<socketReadTimeout>0</socketReadTimeout>
```

<socketWriteTimeout>milliseconds</socketWriteTimeout>

This defines the time, how long the workerthreads wait on write. If the timeout is exceeded, the socket is closed and the browser might not get all data. The default value is 10000 milliseconds.

Example

```
<socketWriteTimeout>20000</socketWriteTimeout>
```

<threadStartDelay>ms</threadStartDelay>

When additional worker threads are needed tntnet waits the number of milliseconds before it starts additional threads to prevent high load when starting many threads at once.

The default value is 10ms.

Example

```
<threadStartDelay>1000</threadStartDelay>
```

<user>username</user>

Changes the user under which tntnet answers requests.

The user is changes using the system call setuid(2), which is only allowed, when tntnet starts as root user.

Example

```
<user>www-data</user>
```

## URL MAPPING
Tntnet is a web server, which receives http requests from a http client and answers them. A http request has a url and other attributes, which are used to decide, how the answer should look like. This is done my mapping urls to components.

A component is something, which generates a http reply. They are normally generated with the ecpp compiler ecppc(1). The ecppc compiler generated C++ classes with component names. The classes are compiled and linked into a shared library. Both the component name and the shared library name is needed to identify a component.

The component identifier is a string built from the component name, the @ character and the shared library name. A example is myclass@myapplication. This tells tntnet: load shared library myapplication and call the component with the name myclass in that library, which creates the reply to the request.

To tell tntnet, which component to call, url mappings must be configured.

Configuration is done in the xml section <mappings>. Multiple mappings can be configured there. A mapping has a condition and a target. Tntnet looks in the list of mappings for the first mapping, where the condition is met and uses that to call the component. The component may return either a reply - then the request is done or a special value DECLINED, which tells tntnet to continue in the list and look for the next mapping, where the condition is met.

The component, which returns DECLINED may already have generated part of the request. This is preserved for the next mapping. A common use case is to write a special component, which just checks the user name and password. If the user name and password is valid, DECLINED is returned and tntnet calls the next mapping where the condition is met.

Also when the condition is met, but the component could not be loaded, tntnet continues with the next mapping.

When the end of the list is reached and no mapping returned a http reply code, tntnet replies with http not found (404) error.

So how these mapping are specified then?

The mapping contains 3 kind of nodes:

conditions

Multiple conditions can be specified. All conditions must be met when the mapping is to be used.

The most important is <url>, which contains a extended regular expression (see regex(7) for details). This expression is checked against the url of the request. If the url tag is omitted, the mapping is used for every url.

The condition <vhost> specifies the virtual host, for which this mapping is valid. When this is specified, the mapping is only valid for requests, where the virtual host matches the setting. The value is also a extended regular expression. Note, that a dot matches any character in regular expressions, which may be irritating here. If you want to specify a mapping for the all hosts of the domain tntnet.org, you have to set <vhost>tntnet\.org$</vhost>. Also the dollar sign at the end is important, since it matches the end of the string. Otherwise the mapping would be also valid for a virtual host like tntnet.org.foo.com, which may not be what you meant.

The condition method specifies the http method for which the mapping should be considered. Again a extended regular expression is used.

The condition ssl is a boolean value. The value should be 0 or 1. The setting checks, whether this mapping should be used depending on ssl. If the value is 1, the condition is met, when the request is sent via ssl. If the value is 0, the condition is met, when the request is sent without ssl.

target

The mapping node contains a node <target>, which contains the component name, which is to be called when the conditions are met.

The target may contain back references to the regular expression in the <url> condition. Parts of the regular expression may be in brackets. In the target $1 is replaced with the first bracketed expression, $2 with the second and so on.

This node is mandatory.

parameters

When the condition is met, additional parameters may be passed to the called component. There are 2 nodes for this.

The node <pathinfo> can be requested in the component using request.getPathInfo(). If the node is not set, the url is set as path info.

The node <args> contains additional parameters, which can be passed to the component. The node can have any number of nodes with values. The tags are used as a parameter name and the content as the value. The method request.getArg(name) returns the value of the specified name. When the node is not set, the method returns a empty string. Optionally a diffrent default value can be passed to the method as an additional parameter like request.getArg(name,defaultValue).

For compatibility reasons with older tntnet request.getArg accepts a numeric argument. Previously the arguments did not have names but were accessed by index. To emulate this, request.getArg with a numeric argument translates the number into the name "argnumber". So accessing request.getArg(2) returns the value of the argument with the name arg2. Accessing a numeric argument equal or greater than the number of arguments (the first is number 0) used to be not allowed. Now a empty string is returned.

Example

```
<mappings>

  <!-- map / to index@myapp -->

  <mapping>

    <target>index@myapp</target>

    <url>^/$</url>

    <pathinfo>index.html</pathinfo>

  </mapping>

  <!-- map /comp.* or /comp to comp@myapp -->

  <mapping>

    <target>action@myapp</target>

    <url></url>               <!-- any url -->

    <method>POST</method>     <!-- but only on method POST -->

    <vhost>localhost</vhost>  <!-- and host header must be localhost -->

    <ssl>1</ssl>              <!-- and ssl is enabled -->

  </mapping>

  <mapping>

    <target>$1@myapp</target>

    <url>^/([^.]+)(\.(.+))?</url>

    <args>

      <extension>$2</extension>

    </args>

  </mapping>
</mappings>
```

## LISTENERS
The section <listeners> specifies the ip addresses and ports, where tntnet waits for incoming requests. Multiple listeners may be defined, when tntnet should listen on multiple ip addresses or ports.

Each listener is defined in a node <listener>. A listener must have a subnode <ip> and <port>. The node <ip> may contain a ip address or hostname or may be left empty. If the node is empty, any interface is used. The <port> must contain the numeric port number.

The ip address may be a IPv4 or IPv6 address.

Optionally a tag <certificate> may be added. This enables ssl on the interface and specifies the ssl host certificate for the interface. Note that tntnet can be built without ssl support. In that case the certificate is just ignored and unencrypted http is used here.

Example

```
<listeners>

  <listener>

    <ip></ip>

    <port>80</port>

  </listener>

  <listener>

    <ip></ip>

    <port>443</port>

    <!-- a certificate enables ssl -->

    <certificate>tntnet.pem</certificate>

  </listener>
</listeners>
```

## AUTHOR
This manual page was written by Tommi Mäkitalo tommi@tntnet.org.

## SEE ALSO
tntnet (1)


tofututo

package: tofu

title: tofututo(7)

text:
# tofututo(7)

## NAME
tofututo - a plain stupid tutorial for tofu.

## OBJECT
This tutorial covers the elements to master in order to be able to use tofu in an efficient way. The selected approach tries to be as much concrete, progressive and concise as possible.

## CONTENTS
PRELIMINARY STEPS

THE BASICS

Cook selections

Order your todo

Edit and feed your tasks

When things are got done

Several operations on a single line

TAGGING AND QUEUEING

Getting the right thing to work on now

A todo can hide another one

PLAY WITH MACROS

SEE ALSO

AUTHOR

## PRELIMINARY STEPS
Maybe you've already begun to play with tofu before discovering this tutorial. That's why we first go to create a separate and safe execution environment. Open a new terminal or a new console and type this ($ stands for the prompt, don't type it):

```
$ export TOFURC=/tmp/tofututorc
$ export TOFUDIR=/tmp/tofututo
```

If this one is not already set, specify also your favorite editor (unless vi is your pet):

```
$ export EDITOR=<edit_command>
```

At this point, we're sure to not break anything, so we can feed our dummy todo:

```
$ tofu next="Begin 'In Search of Lost Time'"
$ tofu next="Feed the cat before leaving"
$ tofu next="Clean the mouse"
$ tofu next="Recode getopt() in myproject-demo"
$ tofu next="Write myproject.1 and myproject.5"
$ tofu next="Recall Bob"
$ tofu next="Write the specification of myotherprojectDB"
$ tofu next="Fix the paths in MyProject.pm"
$ tofu next="Report the nasty bugs hidden in tofu"
$ tofu next="Achieve this tutorial"
$ tofu next="A last and pointless task"
```

Right, we're now ready to begin our exploration (notice that here you've already learned how to create new tasks :-). Ladies and Gentlemen, follow the guide...

## THE BASICS
In this section, we will introduce the set of functionnalities commonly needed for a daily use of tofu.

### Cook selections
As you can see if you enter it in your terminal, tofu invoked alone always prints the whole todo list. The first thing we will see is thus how to make more precise selections.

The easiest way to get a set of tasks is to call them by their position in the todo, enter this in your terminal:

```
$ tofu 3 2 5
```

You can also use a negative way, specifying the tasks you want to exclude and getting the others:

```
$ tofu -3 -2 -5
```

But let discover what's happens when we use the both mechanisms:

```
$ tofu 1 2 3 -3 -4 -5
```

As you can see, you get the two first tasks and the five last ones. We can deduce two things from this: 1) the -n (de-)selector is stonger than n, 2) when the selection is made exclusively from n selectors, this one is limited to the tasks selected by this way, but it's not the case when selector with a larger scope (-n means "all but") are introduced.

The first point is easy to understand and just illustrates the fact that tofu always takes the selection the most restrictive it can define. The second is more obscure though, has it any sense to use n with other ones? It has, let use them with the max=amount selector, which limits the amount of tasks selectedi, and the all one, which just call all the tasks in the selection:

```
$ tofu 7 8 9 all max=4
```

It results a selection composed from the first task plus the tasks we've explicitely selected. This shows the role of the n selectors when they are mixed with others: they create exceptions, so that the tasks selected by this way are never removed from the selection unless it's precisely requested.

### Order your todo
With tofu, the tasks are sorted by decreasing order of priority, so change the priority of a tasks is the same as change its position in the todo. The action to perform that is jump=position, try:

```
$ tofu 2 5 6 jump=1
$ tofu
```

tofu first extracts the tasks from the todo and makes a sub-list with them (it means that you could have write 6 5 2, the results would have been the same), then it inserts this one at the requested position in the remaining list. This means that the requested position doesn't refer to the one of the task which is currently at this one, but to the final position of the sub-list in the final todo. Illustration:

```
$ tofu 2 3 5 jump=4
$ tofu
```

You can see that the tasks 2, 3 and 5 are at the good position (fourth) in the current todo, but the task which was at the fourth in the previous todo is now the second one. So, keep in mind that the position are absolutely defined, not relatively to a task. It could seem not very handy at first glance, but in general it's not a problem (it's only unintuitive when the same jump both decreases and increases the priority of selected tasks).

Nevertheless, there are cases were it's handier to place the tasks relatively to another one. This can be achieved with the ride=task action:

```
$ tofu 2 3 8 ride=6
$ tofu
```

In the example above, the selection is inserted before the sixth task (which is now the seventh, due to the eighth which took a place before it). To get the same result with an absolute placing, the selection should have been sent to the fourth position.

### Edit and feed your tasks
Until now, a task has appeared to us as a mere line of text, but tofu does not limit you to this narrow format. Indeed, you have the possibility to append to each task as much further text as you want. This is very useful, for example when you know the algorithm you plan to use to realize a certain functionnality or when there are points you have absolutely to keep in mind when you modifying a certain part of code. Append text is performed with the edit action. Enter this an add some text after the first line:

```
$ tofu 1 edit
```

If, as usual, you type tofu on the command line after your editor's closed, you won't see much changes. This is normal, because default display of tofu tries to be concise. To recover the text you have entered, you have to use another display which is specified through the read action:

```
$ tofu 1 read
$ tofu 1 4 7 read
```

The first command above displays what you've written precedently, the second just aims to show you how tofu display several tasks in this mode. You can note that before each task header is inserted the position of the task, so that you can easily retrieve the ones interesting you in further tofu commands.

### When things are got done
Once you have realized a task in your todo, this one becomes useless. In the world of tofu, the way to process with such tasks is merely to definitively wipe them out. This is made through the delete action:

```
$ tofu 11 delete
```

To avoid precipitate trashing, tofu will always ask to you a confirmation and give you the possibility to read entirely the task a last time before throwing it back to the null dimension. This temperate behaviour also allows to strip a selection of tasks, deleting some and keeping others.

### Several operations on a single line
You've maybe remarked that the command lines we presented until now always put the selectors before the actions. This is merely because you can perform several selection-then-action cycles on the same line. Each time tofu detects a selector after a set of actions, it begins a new cycle. Look at this:

```
$ tofu 1 2 list 2 jump=1 1 2 list
```

As you can see, the two first tasks are primarily listed, then the second is moved to the first position, and endly we get an updated list. Trivial to understand, isn't it? Well, there is although a little subtlety, try this:

```
$ tofu 1 jump=7 list 1 list
```

Do you see the problem? in the second selection, the task should be different, as we have sent the first task to the seventh position, but it shows precisely this one at the seventh position. In fact, this is not a problem, but a solution. As matter of fact, when you begin to write a complex command line you generally know which task is which task, but after one or two jump or/and deletion it can rapidly become tricky to anticipate the position of each one. That's why tofu chooses to always refer to the initial positions in the todo, the only ones you can really know. So when you use n or -n, you can safely do it all along the line, you're sure of the task it will point on.

## TAGGING AND QUEUEING
Select tasks by position is enough to deal with todo containing few tasks, as the one we use in this tutorial. Nevertheless, if you need a todo manager software, it's probably because you expect to have a little more stuff than that. That's why we will see in this section how categorize things and create sub-todo list(s).

### Getting the right thing to work on now
The command to use to add tags is stamp=tags, let's add some on our tasks:

```
$ tofu 2 3 8 stamp=myproject,code
$ tofu 6 stamp=myotherproject,code
$ tofu 8 9 stamp=bug
$ tofu 7 10 stamp=read
$ tofu 1 4 stamp=life,pointless all
```

As you can see, the tags now appear in the digest of the tasks they are put on. This allows to easily retrieve our tasks accoding to the type of things we want to do at the moment. For example, if you want to code:

```
$ tofu wi=code
```

or, on the contrary, if after passing the day to do it, you want to do anything but not debugging nor coding:

```
$ tofu wo=code,bug
```

The new wi=tags and wo=tags we introduced respectively select and reject any task which bears at least one of the specified tags. There are also variants of them that select or reject any task which bears all of the specified tags:

```
$ tofu wil=bug,myproject digest wol=bug,myproject digest wo=read 10
```

As expected, the first cycle above shows you the eighth task while the second prints the ninth. The third cycle merely recalls you the characteristic of the individual selectors (the tenth task bears "read"), which becomes very handy used in conjonction with the tags.

To remove tags, use the erase=tags command:

```
$ tofu 1 4 erase=pointless
```

### A todo can hide another one
Tagging is a mechanism which quitely helps to deal with a large todo list. But it reaches its limits soon. For example, when you work on a project, you really don't care about the rest of your todo list and it's quickly annoying to have to remember to explicitely include or exclude this or this tag in commands. The queue=tag selector aims precisely to resolv such problems:

```
$ tofu queue=myproject
```

It creates a new list with all the tasks bearing the requested tag and masks the others. Moreover, tofu will stay in this queue as long as you don't order a change and automatically add its associated tag to the new tasks, so you can safely keep the nose in your project for hours, you don't risk to mess tasks that are not related. To get back the whole todo, simply request the main queue, which is a reserved item:

```
$ tofu queue=main
```

Note that change queue in the middle of a command line reset the individual selector references, so avoid to use them both or choose your queue in the first cycle:

```
$ tofu queue=read 1 list queue=bug 1 list 1 queue=main list
```

As you can see, each cycle above shows a different task for the same selector.

## PLAY WITH MACROS
To achieve this tutorial, we will say some words about another handy mechanism provided by tofu: the macros. If tofu becomes tour daily todo manager, you will often have to repeat the same operations, and sometimes these one are complex and long to specify. Define macros is then the solution to create shortcuts and new commands. These ones must be written into the configuration file. Edit it:

```
$ $EDITOR $TOFURC
```

Macro definitions are set through the macroname(macrobody) syntax. Each command which makes up the body is separated from the others by a period, and members of a tag list by a space. Moreover, the macros can take arguments if you let the arguments of the command which take some empty. Here are some examples (the leading # introduce comments):

```
# a shortcut for the "myproject" queue.
qmyproject(queue=myproject)
amyproject(next=, stamp=myproject code)
# (un-)highlight the tasks you want to work on.
select(stamp=workinprogress, color=1)
reject(erase=workinprogress, color=0)
qselect(queue=workinprogress)
wselect(wi=workinprogress)
# manage the todo in the tofu 2.x fashion
hset(stamp=hot, erase=cool warm, color=3)
wset(stamp=warm, erase=hot cool, color=5)
cset(stamp=cool, erase=warm hot, color=8)
hot(wi=hot)
warm(wi=warm)
cool(wi=cool)
sort(wi=cool, jump=1, wi=warm, jump=1, wi=hot, jump=1, all)
```

Once defined, the macros are used on the command line just like other commands, except that a column (:) is prepended to them:

```
$ tofu :amyproject="Recode the build system"
$ tofu :cset 6 7 :wset 2 3 :hset :sort
$ tofu 2 5 6 :select digest
```

The last examples should have taught you the purpose of the color=n command we introduced in the definition. This one is particuliary useful in macros where they are associated with tags.

## SEE ALSO
tofu(1), tofuup(1)

## AUTHOR
This tutorial written and are maintained by Sébastien Boillod. Bug/typo reports, patches, suggestions, feedbacks and so on are welcome at <sbb at tuxfamily dot org>.

This tutorial manual are published under the terms of the very permissive MIT/X11 license. The text of this one is reproduced at the head of the tofu script.


package: torque-client

title: pbs_job_attributes(7)

summary: pbs job attributes

text:
# pbs_job_attributes(7)

## NAME
pbs_job_attributes - pbs job attributes

## DESCRIPTION
A batch job has the following public attributes shown in the following list. The attributes marked with the section symbol § are required by POSIX 1003.2d: If an attribute is unset, the indicated default value is assumed.

Account_Name §

Used for accounting on some hosts. Format: string; default value: none, not used.

Checkpoint §

If supported by the server implementation and the host operating system, the checkpoint attribute determines when checkpointing will be performed by PBS on behalf of the job. The legal values for checkpoint are described under the qalter and qsub commands. Format: the strings "n", "s", "c", "c=mmmm"; default value: "u", which is unspecified.

depend

The type of inter-job dependencies specified by the job owner. Format: "type:jobid[,jobid...]"; default value: no dependencies.

Error_Path §

The final path name for the file containing the job's standard error stream. See the qsub and qalter command description for more detail. Format: "[hostname:]pathname"; default value: (job_name).e(job_number).

Execution_Time §

The time after which the job may execute. The time is maintained in seconds since Epoch. If this time has not yet been reached, the job will not be scheduled for execution and the job is said to be in wait state. Format: "[[CCwYY]MMDDhhmm[.ss]"; default value: time 0, no delay.

group_list §

A list of group_names@hosts which determines the group under which the job is run on a given host. [internal type: array of strings] When a job is to be placed into execution, the server will select a group name according to the following ordered set of rules:

1.

Select the group name from the list for which the associated host name matches the name of the execution host.

2.

Select the group name which has no associated host name, the wild card name.

3.

Use the login group for the user name under which the job will be run.

Format: "group_name[@host][,group_name[@host]...]".

Hold_Types §

The set of holds currently applied to the job. If the set is not null, the job will not be scheduled for execution and is said to be in the hold state. Note, the hold state takes precedence over the wait state. Format: string made up of the letters 'u', 's', 'o'; default value: no hold.

Job_Name §

The name assigned to the job by the qsub or qalter command. Format: string up to 15 characters, first character must be alphabetic; default value: the base name of the job script or STDIN.

Join_Path §

If the Join_Paths attribute is {TRUE}, then the job's standard error stream will be merged, inter-mixed, with the job's standard output stream and placed in the file determined by the Output_Path attribute. The Error_Path attribute is maintained, but ignored. Format: boolean, values accepted are "True", "TRUE", "true", "Y", "y", "1", "False", "FALSE", "false", "N", "n", "0"; default value: false.

Keep_Files §

If Keep_Files contains the values "o" and/or "e" the corresponding streams of the batch job will be retained on the execution host upon job termination. Keep_Files overrides the Output_Path and Error_Path attributes. Format: "o", "e", "oe" or "eo"; default value: no keep, return files to submission host.

Mail_Points §

Identifies at which state changes the server will send mail about the job. Format: string made up of the letters 'a' for abort, 'b' for beginning, and default value: 'a', send on job abort.

Mail_Users §

The set of users to whom mail may be sent when the job makes certain state changes. Format: "user@host[,user@host]"; default value: job owner only.

Output_Path §

The final path name for the file containing the job's standard output stream. See the qsub and qalter command description for more detail. Format: see error_path, default value: (job_name).o(job_number).

Priority §

The job scheduling priority assigned by the user. Format: "[+|-]nnnnn"; default value: undefined.

Rerunable §

The rerunable flag given by the user. Format: "y" or "n", see Join_Path; default value: y, job is rerunable.

Resource_List §

The list of resources required by the job. The resource list is a set of name=value strings. The meaning of name and value is server dependent. The value also establishes the limit of usage of that resource. If not set, the value for a resource may be determined by a queue or server default established by the administrator. Default value: no usage or no limit depending on specific resource.

Shell_Path_List §

A set of absolute paths of the program to process the job's script file. The list is in the format: "path[@host][,path[@host]...]". If this is null, then the user's login shell on the host of execution will be used. Default value: null, login shell.

stagein

The list of files to be staged in prior to job execution. Format: local_path@remote_host:remote_path

stageout

The list of files to be staged out after job execution. Format: local_path@remote_host:remote_path

User_List §

The list of user@hosts which determines the user name under which the job is run on a given host. [internal type: array of strings] When a job is to be placed into execution, the server will select a user name from the list according to the following ordered set of rules:

1.

Select the user name from the list for which the associated host name matches the name of the execution host.

2.

Select the user name which has no associated host name, the wild card name.

3.

Use the Job_Owner as the user name.

Default value: job owner name.

Variable_List §

This is the list of environment variables passed with the Queue Job batch request. Format: "name=value[,name=value...]".

The following attributes require system, manager, or operator privilege to set. They are visible to clients depending on privilege as noted.

comment

An attribute for displaying comments about the job from the system. Visible to any client. Format: any string; default value: none.

sched_hint

This attribute is present when the job is a member of a synchronous dependency set. It is set when the hold is released on the job. The value is {SYNC_SCHED_HINT_FIRST} (1) when the first job of the set is released for scheduling. This is a hint that may be used by the scheduler to decrease the priority of the job. This keeps a user from attempting to game the scheduler. The attribute is set to {SYNC_SCHED_HINT_OTHER} (2) for all other jobs in the set as they become schedulable. This should be taken as a hint by the scheduler to increase their priority to insure they will run at the same time as the earlier scheduled jobs in the set. [This attribute is viewable only by the batch administrator.] [type: integer]

The following attributes are read-only, they are established by the server and are visible to the client but cannot be set by a client. Certain ones are only visible to privileged clients (those run by the batch administrator).

alt_id

For a few systems, such as Irix 6.x running Array Services, the session id is insufficient to track which processes belong to the job. Where a different identifier is required, it is recorded in this attribute. If set, it will also be recorded in the end-of-job accounting record.

For Irix 6.x running Array Services, the alt_id attribute is set to the Array Session Handle (ASH) assigned to the job.

ctime

The time that the job was created.

etime

The time that the job became eligible to run, i.e. in a queued state while residing in an execution queue.

exec_host

If the job is running, this is set to the name of the host on which the job is executing.

exit_status

The exit status of the job. This is only set on receipt of a job obituary notice from MOM, and probably only useful if the "keep_completed" server attribute is set. Note that negative values are generated internally by PBS to indicate system errors and are listed as the JOB_EXEC_* defines in pbs_job.h. Positive values are returned from the user script and cannot be interpreted by PBS.

egroup

If the job is queued in an execution queue, this attribute is set to the group name under which the job is to be run. [This attribute is available only to the batch administrator.]

euser

If the job is queued in an execution queue, this attribute is set to the user name under which the job is to be run. [This attribute is available only to the batch administrator.]

hashname

The name used as a basename for various files, such as the job file, script file, and the standard output and error of the job. [This attribute is available only to the batch administrator.]

interactive

True if the job is an interactive PBS job. Format: boolean, see Join_Paths; default value: false.

Job_Owner §

The login name on the submitting host of the user who submitted the batch job.

job_state

The state of the job.

E

for exiting, the job has completed execution, with or without errors, and the batch system is doing post-execution clean-up.

H

for Held, one or more holds have been applied to the job.

Q

for Queued, the job resides in a execution or routing queue pending execution or routing. It is not in held or waiting state.

R

for Running, the job resides in a execution queue and has been placed into execution.

S

for Suspend (Job running on Unicos only), the job was executing and has been suspended. The job retains its assigned resources but does not use cpu cycle or walltime.

T

for Transiting, the job is in process of being routed or moved to a new destination.

W

for Waiting, the job is not held but the Execution_Time attribute contains a time which has not yet been reached.

mtime

The time that the job was last modified, changed state, or changed locations.

qtime

The time that the job entered the current queue.

queue

The name of the queue in which the job currently resides.

queue_rank

An ordered, non-sequential number indicating the job's position with in the queue. This is provided as an aid to the scheduler. [This attribute is available to the batch manager only.]

queue_type

An identification of the the type of queue in which the job is currently residing. This is provided as an aid to the scheduler. [This attribute is available to the batch manager only.] Format: The letter E or the letter r.

resources_used §

The amount of resources used by the job. This is provided as part of job status information if the job is running.

server

The name of the server which is currently managing the job.

session_id

If the job is running, this is set to the session id of the first executing task.

substate

A numerical indicator of the substate of the job. The substate is used by the PBS job server internally. The attribute is visible to privileged clients, such as the scheduler. Format: integer.

## SEE ALSO
PBS ERS, qsub(1B), qalter(1B), pbs_resources(7B)


title: pbs_queue_attributes(7)

summary: pbs queue attributes

text:
# pbs_queue_attributes(7)

## NAME
pbs_queue_attributes - pbs queue attributes

## DESCRIPTION
Queue public attributes are alterable on request by a client. The client must be acting for a user with administrator (manager) or operator privilege. Certain attributes require the user to have full administrator privilege before they can be modified. The following attributes apply to both queue types:

acl_group_enable

Attribute which when true directs the server to use the queue group access control list acl_groups . Format: boolean, "TRUE", "True", "true", "Y", "y", "1", "FALSE", "False", "false", "N", "n", "0"; default value: false = disabled.

acl_group_sloppy

Search a job user's secondary groups if the effective group doesn't match the group acl. Warning, this can be very slow and expensive. Format: boolean, "TRUE", "True", "true", "Y", "y", "1", "FALSE", "False", "false", "N", "n", "0"; default value: false = disabled.

acl_groups

List which allows or denies enqueuing of jobs owned by members of the listed groups. The groups in the list are groups on the server host, not submitting hosts. If acl_group_enable is set to true, only groups listed in the acl_groups attribute will be allowed access to the queue. See section 10.1, Authorization, in the PBS External Reference Specification. Format: "[+|-]group_name[,...]"; default value: all groups allowed.

acl_host_enable

Attribute which when true directs the server to use the acl_hosts access list. Format: boolean (see acl_group_enable); default value: disabled.

acl_hosts

List of hosts which may enqueue jobs in the queue. See section 10.1, Authorization, in the PBS External Reference Specification. Format: "[+|-]hostname[...]"; default value: all hosts allowed.

acl_logic_or

Modifies the way acls are applied if both acl_user_enable and acl_group_enable are set to true. If acl_logic_or is true, then user and group acls are logically OR'ed together (a job can pass either the user or group acl lists to be allowed access to the queue). If I acl_logic_or is false, then user and group acls are logically AND'ed together (a job would have to pass both user and group acl lists). Format: boolean (see acl_group_enable and acl_user_enable); default value: disabled.

acl_user_enable

Attribute which when true directs the server to use the the acl_users access list for this queue. Format: boolean (see acl_group_enable); default value: disabled.

acl_users

List of users allowed or denied the ability to enqueue jobs in this queue. See section 10.1, Authorization, in the PBS External Reference Specification. If acl_user_enable is set to true, only users listed in the acl_groups attribute will be allowed access to the queue. Format: "[+|-]user[@host][,...]"; default value: all users allowed.

disallowed_types

List of job "types" (interactive,batch,rerunable,nonrerunable,fault_tolerant,fault_intolerant) that are not allowed in this queue. default value: all types allowed.

enabled

Queue will or will not accept new jobs. When false the queue is disabled and will not accept jobs. Format: boolean (see acl_group_enable); default value: disabled.

from_route_only

When true, this queue will not accept jobs except when being routed by the server from a local routing queue. This is used to force user to submit jobs into a routing queue used to distribute jobs to other queues based on job resource limits. Format: boolean; default value: disabled.

is_transit

When true, jobs will be allowed into this queue that do not fit server resource limitations. This is to allow the jobs to be routed to a server that does have the appropriate resources. Any queue limits are checked.

max_queuable

The maximum number of jobs allowed to reside in the queue at any given time. Format: integer; default value: infinite.

max_user_queuable

The maximum number of jobs owned by a single user that are allowed to reside in the queue at any given time. Format: integer; default value: infinite.

max_running

The maximum number of jobs allowed to be selected from this queue for routing or execution at any given time. For a routing queue, this is enforced, if set, by the server. For an execution queue, this attribute is advisory to the Scheduler, it is not enforced by the server. Format: integer.

Priority

The priority of this queue against other queues of the same type on this server. May affect job selection for execution/routing. Advisory to the Scheduler, not used by the server. Format: integer.

queue_type

The type of the queue: execution or route. Format: "execution", "e", "route", "r". This attribute must be explicitly set.

resources_max

The maximum amount of each resource which can be requested by a single job in this queue. The queue value supersedes any server wide maximum limit. Format: "resources_max.resource_name=value", see qmgr(1B); default value: infinite usage.

resources_min

The minimum amount of each resource which can be requested by a single job in this queue. Format: see resources_max, default value: zero usage.

resources_default

The list of default resource values which are set as limits for a job residing in this queue and for which the job did not specify a limit. Format: "resources_default.resource_name=value", see qmgr(1B); default value: none; if not set, the default limit for a job is determined by the first of the following attributes which is set: server's resources_default, queue's resources_max, server's resources_max. If none of these are set, the job will unlimited resource usage.

started

Jobs may be scheduled for execution from this queue. When false, the queue is considered stopped. Advisory to the Scheduler, not enforced by the server. [default value: false, but depends on scheduler interpretation] Format: boolean (see acl_group_enable).

The following attributes apply only to execution queues:

checkpoint_defaults

Specifies the queues default checkpointing values to be used for a job that does not have any checkpointing specified. Format: string; default value: none.

checkpoint_min

Specifies the minimum interval of cpu time, in minutes, which is allowed between checkpoints of a job. If a user specifies a time less than this value, this value is used instead. Format: integer; default value: no minimum.

resources_available

The list of resource and amounts available to jobs running in this queue. The sum of the resource of each type used by all jobs running from this queue cannot exceed the total amount listed here. Advisory to the Scheduler, not enforced by the server. Format: "resources_available.resource_name=value", see qmgr(1B).

keep_completed

Number of seconds to retain completed jobs in the C state. This overrides the server attribute of the same name. EXPERIMENTAL Format: integer; default value: 0.

kill_delay

The amount of the time delay between the sending of SIGTERM and SIGKILL when a qdel command is issued against a running job. This overrides the server attribute of the same name. Format: integer seconds; default value: 2 seconds.

max_user_run

The maximum number of jobs owned by a single user that are allowed to be running from this queue at one time. This attribute is advisory to the Scheduler, it is not enforced by the server. Format: integer; default value: none.

max_group_run

The maximum number of jobs owned by any users in a single group that are allowed to be running from this queue at one time. This attribute is advisory to the Scheduler, it is not enforced by the server. Format: integer; default value: none.

The following attributes apply only to routing queues:

route_destinations

The list of destinations to which jobs may be routed. [default value: none, should be set to at least one valid destination]

alt_router

If true, an site supplied, alternative job router function is used to determine the destination for routing jobs from this queue. Otherwise, the default, round-robin router is used. Format: boolean (see acl_group_enable); default value: false.

route_held_jobs

If true, jobs with a hold type set may be routed from this queue. If false, held jobs are not to be routed. Format: boolean (see acl_group_enable); default value: false.

route_waiting_jobs

If true, jobs with a future execution_time attribute may be routed from this queue. If false, they are not to be routed. Format: boolean (see acl_group_enable); default value: false.

route_retry_time

Time delay between route retries. Typically used when the network between servers is down. Format: integer seconds; default value: {PBS_NET_RETRY_TIME} (30 seconds).

route_lifetime

The maximum time a job is allowed to exist in a routing queue. If the job cannot be routed in this amount of time, the job is aborted. If unset or set to a value of zero (0), the lifetime is infinite. Format: integer seconds; default infinite.

The following data items are read-only attributes of the queue. They are visible to but cannot be changed by clients.

Items which apply to all types of queues are:

total_jobs

The number of jobs currently residing in the queue.

state_count

The total number of jobs currently residing in the queue in each state.

These read-only attributes only apply to execution queues:

resources_assigned

The total amount of certain types of resources allocated to jobs running from this queue.

## SEE ALSO
the PBS ERS, qmgr(1B), pbs_resources(7B)


title: pbs_resources_aix4(7)

summary: pbs Resources on IBM AIX 4

text:
# pbs_resources_aix4(7)

## NAME
pbs_resources_aix4 - pbs Resources on IBM AIX 4

## DESCRIPTION
This page summarizes the resources supported by PBS for IBM systems running AIX version 4. These resources are specified for jobs by including them in the -l option argument on the qsub or qalter command or in the PBS job script.

## RESOURCES
cput

Maximum amount of CPU time used by all processes in the job. Units: time.

file

The largest size of any single file that may be created by the job. Units: size.

mem

Maximum amount of physical memory (workingset) used by the job. Units: size.

vmem

Maximum amount of virtual memory used by all concurrent processes in the job. Units: size.

nice

The nice value under which the job is to be run. Units: unitary.

pcput

Maximum amount of CPU time used by any single process in the job. Units: time.

pmem

Maximum amount of physical memory (workingset) used by any single process of the job. Units: size.

pvmem

Maximum amount of virtual memory used by any single process in the job. Units: size.

walltime

Maximum amount of real time during which the job can be in the running state. Units: time.

arch

Specifies the administrator defined system architecture requried. This defaults to whatever the PBS_MACH string is set to in "local.mk". Units: string.

host

Name of host on which job should be run. This resource is provided for use by the site's scheduling policy. The allowable values and effect on job placement is site dependent. Units: string.

nodes

Number and/or type of nodes to be reserved for exclusive use by the job. The value is one or more node_specs joined with the '+' character, "node_spec[+node_spec...]. Each node_spec is an number of nodes required of the type declared in the node_spec and a name or one or more property or properties desired for the nodes. The number, the name, and each property in the node_spec are separated by a colon ':'. If no number is specified, one (1) is assumed. Units: string.

The name of a node is its hostname. The properties of nodes are:

.

ppn=# specifying the number of processors per node requested. Defaults to 1.

.

arbitrary string assigned by the system administrator, please check with your administrator as to the node names and properties available to you.

Examples:

.

To ask for 12 nodes of any type: -l nodes=12

.

To ask for 2 "server" nodes and 14 other nodes (a total of 16): -l nodes=2:server+14

The above consist of two node_specs "2:server" and "14".

.

To ask for (a) 1 node that is a "server" and has a "hippi" interface, (b) 10 nodes that are not servers, and (c) 3 nodes that have a large amount of memory an have hippi:

-l nodes=server:hippi+10:noserver+3:bigmem:hippi

.

To ask for three nodes by name:

-l nodes=b2005+b1803+b1813

.

To ask for 2 processors on each of four nodes:

-l nodes=4:ppn=2

.

To ask for 4 processors on one node:

-l nodes=1:ppn=4

.

To ask for 2 processors on each of two blue nodes and three processors on one red node:

-l nodes=2:blue:ppn=2+red:ppn=3

host

Allows a user to specify the desired execution location. This resource is provided for use by the site's scheduling policy. The allowable values and effect on job placement is site dependent. Units: string.

other

Allows a user to specify site specific information. This resource is provided for use by the site's scheduling policy. The allowable values and effect on job placement is site dependent. Units: string.

software

Allows a user to specify software required by the job. This is useful if certain software packages are only available on certain systems in the site. This resource is provided for use by the site's scheduling policy. The allowable values and effect on job placement is site dependent. Units: string.

## EXAMPLES
qsub -l nodes=15,walltime=2:00:00 script

or in a qsub script as a directive:

\#PBS -l nodes=15,walltime=2:00:00

qsub -l cput=1:00:00,walltime=2:00:00,file=50gb,mem=15mb script

qalter -lcput=30:00,pmem=8mb 123.jobid

or in a qsub script as a directive:

\#PBS -l cput=1:00:00,walltime=2:00:00,file=50gb,mem=15mb

## RESOURCE UNITS
The resource values take the following units:

time

specifies a maximum time period the resource can be used. Time is expressed in seconds as an integer, or in the form:

[[hours:]minutes:]seconds[.milliseconds]

size

specifies the maximum amount in terms of bytes or words. It is expressed in the form integer[suffix] The suffix is a multiplier defined in the following table, The size of a word is the word size on the execution host.

b or w

bytes or words.

kb or kw

Kilo (1024) bytes or words.

mb or mw

Mega (1,048,576) bytes or words.

gb or gw

Giga (1,073,741,824) bytes or words.

unitary

The maximum amount of a resource which is expressed as a simple integer.

## SEE ALSO
the PBS ERS, qsub(1B), qalter(1B), pbs_submit(3B), pbs_alterjob(3B), pbs_statjob(3b) pbs_resources_irix5(7B), pbs_resources_sp2(7B), pbs_resources_sunos4(7B), pbs_resources_unicos8(7B)


title: pbs_resources_aix5(7)

summary: pbs Resources on IBM AIX 5

text:
# pbs_resources_aix5(7)

## NAME
pbs_resources_aix5 - pbs Resources on IBM AIX 5

## DESCRIPTION
This page summarizes the resources supported by PBS for IBM systems running AIX version 5. These resources are specified for jobs by including them in the -l option argument on the qsub or qalter command or in the PBS job script.

## RESOURCES
cput

Maximum amount of CPU time used by all processes in the job. Units: time.

file

The largest size of any single file that may be created by the job. Units: size.

mem

Maximum amount of physical memory (workingset) used by the job. Units: size.

vmem

Maximum amount of virtual memory used by all concurrent processes in the job. Units: size.

nice

The nice value under which the job is to be run. Units: unitary.

pcput

Maximum amount of CPU time used by any single process in the job. Units: time.

pmem

Maximum amount of physical memory (workingset) used by any single process of the job. Units: size.

pvmem

Maximum amount of virtual memory used by any single process in the job. Units: size.

walltime

Maximum amount of real time during which the job can be in the running state. Units: time.

arch

Specifies the administrator defined system architecture requried. This defaults to whatever the PBS_MACH string is set to in "local.mk". Units: string.

host

Name of host on which job should be run. This resource is provided for use by the site's scheduling policy. The allowable values and effect on job placement is site dependent. Units: string.

nodes

Number and/or type of nodes to be reserved for exclusive use by the job. The value is one or more node_specs joined with the '+' character, "node_spec[+node_spec...]. Each node_spec is an number of nodes required of the type declared in the node_spec and a name or one or more property or properties desired for the nodes. The number, the name, and each property in the node_spec are separated by a colon ':'. If no number is specified, one (1) is assumed. Units: string.

The name of a node is its hostname. The properties of nodes are:

.

ppn=# specifying the number of processors per node requested. Defaults to 1.

.

arbitrary string assigned by the system administrator, please check with your administrator as to the node names and properties available to you.

Examples:

.

To ask for 12 nodes of any type: -l nodes=12

.

To ask for 2 "server" nodes and 14 other nodes (a total of 16): -l nodes=2:server+14

The above consist of two node_specs "2:server" and "14".

.

To ask for (a) 1 node that is a "server" and has a "hippi" interface, (b) 10 nodes that are not servers, and (c) 3 nodes that have a large amount of memory an have hippi:

-l nodes=server:hippi+10:noserver+3:bigmem:hippi

.

To ask for three nodes by name:

-l nodes=b2005+b1803+b1813

.

To ask for 2 processors on each of four nodes:

-l nodes=4:ppn=2

.

To ask for 4 processors on one node:

-l nodes=1:ppn=4

.

To ask for 2 processors on each of two blue nodes and three processors on one red node:

-l nodes=2:blue:ppn=2+red:ppn=3

host

Allows a user to specify the desired execution location. This resource is provided for use by the site's scheduling policy. The allowable values and effect on job placement is site dependent. Units: string.

other

Allows a user to specify site specific information. This resource is provided for use by the site's scheduling policy. The allowable values and effect on job placement is site dependent. Units: string.

software

Allows a user to specify software required by the job. This is useful if certain software packages are only available on certain systems in the site. This resource is provided for use by the site's scheduling policy. The allowable values and effect on job placement is site dependent. Units: string.

## EXAMPLES
qsub -l nodes=15,walltime=2:00:00 script

or in a qsub script as a directive:

\#PBS -l nodes=15,walltime=2:00:00

qsub -l cput=1:00:00,walltime=2:00:00,file=50gb,mem=15mb script

qalter -lcput=30:00,pmem=8mb 123.jobid

or in a qsub script as a directive:

\#PBS -l cput=1:00:00,walltime=2:00:00,file=50gb,mem=15mb

## RESOURCE UNITS
The resource values take the following units:

time

specifies a maximum time period the resource can be used. Time is expressed in seconds as an integer, or in the form:

[[hours:]minutes:]seconds[.milliseconds]

size

specifies the maximum amount in terms of bytes or words. It is expressed in the form integer[suffix] The suffix is a multiplier defined in the following table, The size of a word is the word size on the execution host.

b or w

bytes or words.

kb or kw

Kilo (1024) bytes or words.

mb or mw

Mega (1,048,576) bytes or words.

gb or gw

Giga (1,073,741,824) bytes or words.

unitary

The maximum amount of a resource which is expressed as a simple integer.

## SEE ALSO
the PBS ERS, qsub(1B), qalter(1B), pbs_submit(3B), pbs_alterjob(3B), pbs_statjob(3b) pbs_resources_irix5(7B), pbs_resources_sp2(7B), pbs_resources_sunos4(7B), pbs_resources_unicos8(7B)