Initial commit of OpenSPARC T2 design and verification files.

[OpenSPARC-T2-DV] / tools / perl-5.8.0 / man / man1 / pshconfig.1

.\" Automatically generated by Pod::Man v1.34, Pod::Parser v1.13
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  | will give a
.\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
.\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
.\" expand to `' in nroff, nothing in troff, for use with C<>.
.tr \(*W-|\(bv\*(Tr
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "PSHCONFIG 1"
.TH PSHCONFIG 1 "2003-01-02" "perl v5.8.0" "User Contributed Perl Documentation"
.SH "NAME"
pshconfig \- Configuring the Perl Shell
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
How to configure the Perl Shell
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Perl Shell uses a built\-in, unified configuration system. All essential
configuration is done by choosing a set of evaluation strategies, using
the \f(CW\*(C`strategy\*(C'\fR builtin, or by setting options, using the \f(CW\*(C`option\*(C'\fR builtin.
.Sh "\s-1CONFIGURATION\s0 \s-1OPTIONS\s0"
.IX Subsection "CONFIGURATION OPTIONS"
All options marked as (\s-1ENV\s0) inherit their settings from the current
environment.
.PP
All options marked as (\s-1EARLY\s0) must be set in the pshrc file or earlier to
be evaluated.
.IP "\(bu \fBarray_exports\fR" 4
.IX Item "array_exports"
Contains a list of environment variables which should be tied
to arrays. The key of the hash is the name of the variable, the
value is the delimiter of the list (e.g. ':' in \s-1PATH\s0). The
default value for array_exports currently contains \s-1PATH\s0, \s-1CLASSPATH\s0,
\&\s-1LD_LIBRARY_PATH\s0, \s-1FIGNORE\s0 and \s-1CDPATH\s0.
.IP "\(bu \fBcdpath\fR (\s-1ENV\s0)" 4
.IX Item "cdpath (ENV)"
A list of paths of directories in which the \f(CW\*(C`cd\*(C'\fR builtin
should search for its argument. Defaults to \*(L".\*(R".
.IP "\(bu \fBecho\fR" 4
.IX Item "echo"
Controls whether the processing loop saves and displays the Perl value 
of executing a line of input. Three cases are distinguished: a false
value, in which case no results are displayed; a subroutine reference, 
in which case the subroutine is called with the results (this may be
multiple arguments if the eval returned an array) and should return
true to display, false to not; or a true (scalar) value, in which case 
any non\-undef, non-empty value is displayed.
.Sp
In addition to displaying the value, it is pushed onto the array
determined by \f(CW$Psh::result_array\fR.
Note that scalar values are pushed directly onto this array, but array
values are pushed by reference. 
.IP "\(bu \fBfignore\fR (\s-1ENV\s0)" 4
.IX Item "fignore (ENV)"
A list (separated by the path separator) of file endings to
ignore when performing \s-1TAB\s0 completion. No default.
.IP "\(bu \fBhistory_file\fR" 4
.IX Item "history_file"
The filename \fBpsh\fR will use to save the command history in from one
invocation to the next, if \fBsave_history\fR is set.
.Sp
Default is "\fI$ENV{\s-1HOME\s0}/.${bin}_history\fR".
.IP "\(bu \fBhistsize\fR (\s-1ENV\s0) (\s-1EARLY\s0)" 4
.IX Item "histsize (ENV) (EARLY)"
The maximum number of lines to save in the history file.
Defaults to 50.
.IP "\(bu \fBignoredie\fR" 4
.IX Item "ignoredie"
If set, \fBpsh\fR will attempt to continue after internal
errors.
.IP "\(bu \fBignoreeof\fR (\s-1ENV\s0)" 4
.IX Item "ignoreeof (ENV)"
Controls the action of the shell on receipt of an \s-1EOF\s0 character as the
sole input.  If set, the value is the number of consecutive \s-1EOF\s0 characters
typed as the first characters on an input line before bash exits.
If the variable exists but does not have a numeric value, the default value
is 10. If it does not exist, \s-1EOF\s0 signifies the end of input to the shell.
.IP "\(bu \fBignoresegfault\fR (\s-1EARLY\s0)" 4
.IX Item "ignoresegfault (EARLY)"
If set, Perl Shell will try to ignore all segementation faults. Use this
at your own risk!
.IP "\(bu \fBpath\fR (\s-1ENV\s0)" 4
.IX Item "path (ENV)"
A list of directories to search for executables.
.IP "\(bu \fBps1\fR (\s-1ENV\s0)" 4
.IX Item "ps1 (ENV)"
This is the standard prompt. It may contain a string or a code reference.
Please see below for more information.
.IP "\(bu \fBps2\fR (\s-1ENV\s0)" 4
.IX Item "ps2 (ENV)"
This is the continuation prompt.
.IP "\(bu \fBtrace\fR" 4
.IX Item "trace"
If set, the shell will display each line again before it executes it.
.IP "\(bu \fBwindow_title\fR" 4
.IX Item "window_title"
Controls the window title in interactive use. See prompt evaluation
for escape codes.
.IP "\(bu \fBsave_history\fR" 4
.IX Item "save_history"
If this is true, the command history is saved in file \f(CW$Psh::history_file\fR
from one invocation of \fBpsh\fR to the next.
.SH "PROMPT STRINGS"
.IX Header "PROMPT STRINGS"
Setting the variable \fIps1\fR to a string will cause that string
to be used as the prompt\-string. Setting it to a subroutine reference
causes the result of running that subroutine to be used each time.
For example,
.Sp
.Vb 1
\&  option ps1= sub { $i++; "psh [$i]\e$ "; }
.Ve
.Sp
will cause the prompt to be \f(CW\*(C`psh [1]$\*(C'\fR followed by \f(CW\*(C`psh [2]$\*(C'\fR, and so on.
.Sp
\&\fBpsh\fR uses some of the same ``prompting variables'' as \fBbash\fR. They are
accessed by placing a backslash followed by the code in the prompt string,
either hard coded, or as returned by the prompt string function. The
variables supported are:
.RS 4
.IP "d The date in ``Weekday Month Day'' format" 4
.IX Item "d The date in ``Weekday Month Day'' format"
.PD 0
.IP "E The escape character" 4
.IX Item "E The escape character"
.IP "h The short hostname" 4
.IX Item "h The short hostname"
.IP "H The long hostname" 4
.IX Item "H The long hostname"
.IP "n A carriage return and line feed" 4
.IX Item "n A carriage return and line feed"
.IP "s The name of the shell" 4
.IX Item "s The name of the shell"
.IP "t The current time in \s-1HH:MM:SS\s0 format" 4
.IX Item "t The current time in HH:MM:SS format"
.IP "u The username of the current user" 4
.IX Item "u The username of the current user"
.IP "w The current working directory" 4
.IX Item "w The current working directory"
.IP "W The basename of the current working directory" 4
.IX Item "W The basename of the current working directory"
.IP "# The command number of the current command" 4
.IX Item "# The command number of the current command"
.IP "$ `#' if the effective \s-1UID\s0 is zero, else `$'" 4
.IX Item "$ `#' if the effective UID is zero, else `$'"
.IP "[ ] Used for Term::ReadLine::Gnu to ignore control characters while determining the length of the prompt" 4
.IX Item "[ ] Used for Term::ReadLine::Gnu to ignore control characters while determining the length of the prompt"
.RE
.RS 4
.PD
.Sp
Please note that bash's support of backticks to execute code from within the prompt is not supported in psh. Instead use the newer syntax \e$(command) which is also support by bash.
.Sp
Custom prompting variables may be added by adding entries to the array
\&\fI%Psh::prompt_vars\fR keyed by the single character code. The entries
should be subroutine references that return the replacement string.
.SH "PSH SCALAR VARIABLES"
.IX Header "PSH SCALAR VARIABLES"
\&\fBpsh\fR makes a number of variables and functions accessible to the
user in the \f(CW\*(C`Psh::\*(C'\fR package for configuration or utility
purposes. Their default values are given in parentheses below. If the
variable is also marked \*(L"[late]\*(R", then it is undefined at the start of 
the \fI.pshrc\fR file, but any value given to it during that file will be 
used instead of the default setting.
.IP "\fI$Psh::bin\fR (the basename of the file \fBpsh\fR was invoked by)" 4
.IX Item "$Psh::bin (the basename of the file psh was invoked by)"
The name of the current shell.
.IP "\fI$Psh::cmd\fR" 4
.IX Item "$Psh::cmd"
The command serial number in the currently-executing processing loop.
.IP "\fI$Psh::currently_active\fR (0)" 4
.IX Item "$Psh::currently_active (0)"
The pid of the process \fBpsh\fR will currently forward signals to, or 0
if \fBpsh\fR will handle the signals internally. Usually
0 unless \fBpsh\fR is waiting for a process in the \*(L"foreground\*(R".
.IP "\fI$Psh::debugging\fR (the value of the \fB\-d\fR option or 0)" 4
.IX Item "$Psh::debugging (the value of the -d option or 0)"
Whether \fBpsh\fR's internal debugging output should be produced. If this
variable is set to 1, all available debug output will be shown. If
this is set to a string to characters, only debug output belonging
to the classes signified by the characters will be shown. Debug
classes etc. are in \fBpshdevel\fR
.ie n .IP "\fI$Psh::eval_preamble\fR (""package main;"")" 4
.el .IP "\fI$Psh::eval_preamble\fR (``package main;'')" 4
.IX Item "$Psh::eval_preamble (package main;)"
Every Perl expression that \fBpsh\fR evaluates as part of its read-eval loop
is prepended with this string, intended primarily to set the expected
package context.
.ie n .IP "\fI$Psh::host\fR (the output of """"hostname \-s"""") [late]" 4
.el .IP "\fI$Psh::host\fR (the output of ``\f(CWhostname \-s\fR'') [late]" 4
.IX Item "$Psh::host (the output of ""hostname -s"") [late]"
The short host name of the machine \fBpsh\fR is currently running on.
.IP "\fI$Psh::interactive\fR" 4
.IX Item "$Psh::interactive"
This is not a customization variable but a flag which tells wether
you are currently in interactive mode (1) or processing a file (0)
.IP "\fI$Psh::login_shell\fR (0)" 4
.IX Item "$Psh::login_shell (0)"
Set to true if \fBpsh\fR is the user's login shell. On systems where this
does not apply, set to true unless called from another instance of \fBpsh\fR.
.ie n .IP "\fI$Psh::longhost\fR (the output of """"hostname"""") [late]" 4
.el .IP "\fI$Psh::longhost\fR (the output of ``\f(CWhostname\fR'') [late]" 4
.IX Item "$Psh::longhost (the output of ""hostname"") [late]"
The fully qualified host name of the machine \fBpsh\fR is running on.
.IP "\fI$Psh::result_array\fR ('Psh::val')" 4
.IX Item "$Psh::result_array ('Psh::val')"
Controls where the results of Perl evaluations saved via \f(CW$Psh::echo\fR 
will go. It may be a reference to an array, or the string name of an
array.
.IP "\fI$Psh::which_regexp\fR ('^[\-a\-zA\-Z0\-9_~+]*$')" 4
.IX Item "$Psh::which_regexp ('^[-a-zA-Z0-9_~+]*$')"
When \f(CW\*(C`Psh::Util::which\*(C'\fR is asked to locate a filename in the current
\&\s-1PATH\s0, it will only look for filenames which match this regexp. Names
that do not match this regexp will automatically come back \*(L"not found\*(R".
.RE
.RS 4
.SH "PSH ARRAY VARIABLES"
.IX Header "PSH ARRAY VARIABLES"
.IP "\fI@Psh::Completion::bookmarks\fR ( from /etc/hosts )" 4
.IX Item "@Psh::Completion::bookmarks ( from /etc/hosts )"
Supposed to contain your most used \s-1IP\s0 numbers, hostnames or URLs.
Those will be eligible for \s-1TAB\s0 completion if you add a command
for completion using complete \f(CW\*(C`\-A\*(C'\fR hostname command. \f(CW\*(C`psh\*(C'\fR will
initialize this list with your /etc/hosts file
.IP "\fI@Psh::history\fR" 4
.IX Item "@Psh::history"
An array of lines to write to the history file when \fBpsh\fR exits, only
filled when the ReadLine module doesn't handle the history file.
.IP "\fI@Psh::val\fR" 4
.IX Item "@Psh::val"
The default array where \fBpsh\fR stores away the results of executing
lines, as described in \f(CW$Psh::echo\fR above. 
.RE
.RS 4
.SH "PSH HASH VARIABLES"
.IX Header "PSH HASH VARIABLES"
.IP "\fI%Psh::Prompt::prompt_vars\fR" 4
.IX Item "%Psh::Prompt::prompt_vars"
The keys of this hash are single characters, and the values are
subroutine references that implement the given escape character in
prompt strings. (See \*(L"\s-1PROMPT\s0 \s-1STRINGS\s0\*(R" below.)
.RE
.RS 4
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (C) 1999\-2003 Gregor N. Purdy. All rights reserved.
This script is free software. It may be copied or modified according
to the same terms as Perl itself.