'\" te
.\" Portions Copyright (c) 2003, Sun Microsystems, Inc.  All Rights Reserved
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH RUNAT 1 "Jun 22, 2001"
.SH NAME
runat \- execute command in extended attribute name space
.SH SYNOPSIS
.LP
.nf
\fB/usr/bin/runat\fR \fIfile\fR [\fIcommand\fR]
.fi

.SH DESCRIPTION
.sp
.LP
The \fBrunat\fR utility is used to execute shell commands in a file's hidden
attribute directory. Effectively, this utility changes the current working
directory to be the hidden attribute directory associated with the file
argument and then executes the specified command in the bourne shell
(\fB/bin/sh\fR). If no command argument is provided, an interactive shell is
spawned. The environment variable $\fBSHELL\fR defines the shell to be spawned.
If this variable is undefined, the default shell, \fB/bin/sh\fR, is used.
.sp
.LP
The file argument can be any file, including a directory, that can support
extended attributes. It is not necessary that this file have any attributes, or
be prepared in any way, before invoking the \fBrunat\fR command.
.SH OPERANDS
.sp
.LP
The following operands are supported:
.sp
.ne 2
.na
\fB\fIfile\fR\fR
.ad
.RS 12n
Any file, including a directory, that can support extended attributes.
.RE

.sp
.ne 2
.na
\fB\fIcommand\fR \fR
.ad
.RS 12n
The command to be executed in an attribute directory.
.RE

.SH ERRORS
.sp
.LP
A non-zero exit status will be returned if \fBrunat\fR cannot access the
\fIfile\fR argument, or the \fIfile\fR argument does not support extended
attributes.
.SH USAGE
.sp
.LP
See \fBfsattr\fR(5) for a detailed description of extended file attributes.
.sp
.LP
The process context created by the \fBrunat\fR command has its current working
directory set to the hidden directory containing the file's extended
attributes. The parent of this directory (the "\fB\&..\fR" entry) always refers
to the file provided on the command line. As such, it may not be a directory.
Therefore, commands (such as \fBpwd\fR) that depend upon the parent entry being
well-formed (that is, referring to a directory) may fail.
.sp
.LP
In the absence of the \fIcommand\fR argument, \fBrunat\fR will spawn a new
interactive shell with its current working directory set to be the provided
file's hidden attribute directory. Notice that some shells (such as \fBzsh\fR
and \fBtcsh\fR) are not well behaved when the directory parent is not a
directory, as described above. These shells should not be used with
\fBrunat\fR.
.SH EXAMPLES
.LP
\fBExample 1 \fRUsing runat to list extended attributes on a file
.sp
.in +2
.nf
example% \fBrunat file.1 ls -l\fR
example% \fBrunat file.1 ls\fR
.fi
.in -2
.sp

.LP
\fBExample 2 \fRCreating extended attributes
.sp
.in +2
.nf
example% \fBrunat file.2 cp /tmp/attrdata attr.1\fR
example% \fBrunat file.2 cat /tmp/attrdata > attr.1\fR
.fi
.in -2
.sp

.LP
\fBExample 3 \fRCopying an attribute from one file to another
.sp
.in +2
.nf
example% \fBrunat file.2 cat attr.1 | runat file.1 "cat > attr.1"\fR
.fi
.in -2
.sp

.LP
\fBExample 4 \fRUsing runat to spawn an interactive shell
.sp
.in +2
.nf
example% \fBrunat file.3 /bin/sh\fR
.fi
.in -2
.sp

.sp
.LP
This spawns a new shell in the attribute directory for \fBfile.3\fR. Notice
that the shell will not be able to determine what your current directory is. To
leave the attribute directory, either exit the spawned shell or change
directory (\fBcd\fR) using an absolute path.

.sp
.LP
Recommended methods for performing basic attribute operations:

.sp
.ne 2
.na
\fBdisplay\fR
.ad
.RS 22n
\fBrunat \fIfile\fR ls [\fIoptions\fR]\fR
.RE

.sp
.ne 2
.na
\fBread\fR
.ad
.RS 22n
\fBrunat \fIfile\fR cat \fIattribute\fR\fR
.RE

.sp
.ne 2
.na
\fBcreate/modify\fR
.ad
.RS 22n
\fBrunat \fIfile\fR cp \fIabsolute-file-path\fR \fIattribute\fR\fR
.RE

.sp
.ne 2
.na
\fBdelete\fR
.ad
.RS 22n
\fBrunat \fIfile\fR rm \fIattribute\fR\fR
.RE

.sp
.ne 2
.na
\fBpermission changes\fR
.ad
.RS 22n
.sp
.in +2
.nf
\fBrunat \fIfile\fR chmod \fImode attribute\fR
runat \fIfile\fR chgrp \fIgroup attribute\fR
runat \fIfile\fR chown \fIowner attribute\fR\fR
.fi
.in -2
.sp

.RE

.sp
.ne 2
.na
\fBinteractive shell\fR
.ad
.RS 22n
.LP
.nf
\fBrunat \fIfile\fR /bin/sh\fR or set your $SHELL to /bin/sh and \fBrunat \fIfile\fR\fR
.fi

.RE

.sp
.LP
The above list includes commands that are known to work with \fBrunat\fR. While
many other commands may work, there is no guarantee that any beyond this list
will work. Any command that relies on being able to determine its current
working directory is likely to fail. Examples of such commands follow:
.LP
\fBExample 5 \fRUsing man in an attribute directory
.sp
.in +2
.nf
example% \fBrunat file.1 man runat\fR
>getcwd: Not a directory
.fi
.in -2
.sp

.LP
\fBExample 6 \fRSpawning a tcsh shell in an attribute directory
.sp
.in +2
.nf
example% \fBrunat file.3 /usr/bin/tcsh\fR
tcsh: Not a directory
tcsh: Trying to start from "/home/\fIuser\fR"
.fi
.in -2
.sp

.sp
.LP
A new tcsh shell has been spawned with the current working directory set to the
user's home directory.

.LP
\fBExample 7 \fRSpawning a zsh shell in an attribute directory
.sp
.in +2
.nf
example% \fBrunat file.3 /usr/bin/zsh\fR
example%
.fi
.in -2
.sp

.sp
.LP
While the command appears to have worked, \fBzsh\fR has actually just changed
the current working directory to '/'. This can be seen by using \fB/bin/pwd\fR:

.sp
.in +2
.nf
example% \fB/bin/pwd\fR
/
.fi
.in -2
.sp

.SH ENVIRONMENT VARIABLES
.sp
.ne 2
.na
\fB\fBSHELL\fR\fR
.ad
.RS 9n
Specifies the command shell to be invoked by \fBrunat\fR.
.RE

.SH EXIT STATUS
.sp
.LP
The following exit values are returned:
.sp
.ne 2
.na
\fB\fB125\fR \fR
.ad
.RS 8n
The attribute directory of the file referenced by the \fIfile\fR argument
cannot be accessed.
.RE

.sp
.ne 2
.na
\fB\fB126\fR \fR
.ad
.RS 8n
The exec of the provided \fIcommand\fR argument failed.
.RE

.sp
.LP
Otherwise, the exit status returned is the exit status of the shell invoked to
execute the provided command.
.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
CSI	Enabled
_
Interface Stability	Evolving
.TE

.SH SEE ALSO
.sp
.LP
\fBopen\fR(2), \fBattributes\fR(5), \fBfsattr\fR(5)
.SH NOTES
.sp
.LP
It is not always obvious why a command fails in \fBrunat\fR when it is unable
to determine the current working directory. The errors resulting can be
confusing and ambiguous (see the \fBtcsh\fR and \fBzsh\fR examples above).