share/man/man1/runat.1

   1 '\" te
   2 .\" Portions Copyright (c) 2003, Sun Microsystems, Inc.  All Rights Reserved
   3 .\" 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.
   4 .\" 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.
   5 .\" 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]
   6 .TH RUNAT 1 "Jun 22, 2001"
   7 .SH NAME
   8 runat \- execute command in extended attribute name space
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 \fB/usr/bin/runat\fR \fIfile\fR [\fIcommand\fR]
  13 .fi
  14
  15 .SH DESCRIPTION
  16 .sp
  17 .LP
  18 The \fBrunat\fR utility is used to execute shell commands in a file's hidden
  19 attribute directory. Effectively, this utility changes the current working
  20 directory to be the hidden attribute directory associated with the file
  21 argument and then executes the specified command in the bourne shell
  22 (\fB/bin/sh\fR). If no command argument is provided, an interactive shell is
  23 spawned. The environment variable $\fBSHELL\fR defines the shell to be spawned.
  24 If this variable is undefined, the default shell, \fB/bin/sh\fR, is used.
  25 .sp
  26 .LP
  27 The file argument can be any file, including a directory, that can support
  28 extended attributes. It is not necessary that this file have any attributes, or
  29 be prepared in any way, before invoking the \fBrunat\fR command.
  30 .SH OPERANDS
  31 .sp
  32 .LP
  33 The following operands are supported:
  34 .sp
  35 .ne 2
  36 .na
  37 \fB\fIfile\fR\fR
  38 .ad
  39 .RS 12n
  40 Any file, including a directory, that can support extended attributes.
  41 .RE
  42
  43 .sp
  44 .ne 2
  45 .na
  46 \fB\fIcommand\fR \fR
  47 .ad
  48 .RS 12n
  49 The command to be executed in an attribute directory.
  50 .RE
  51
  52 .SH ERRORS
  53 .sp
  54 .LP
  55 A non-zero exit status will be returned if \fBrunat\fR cannot access the
  56 \fIfile\fR argument, or the \fIfile\fR argument does not support extended
  57 attributes.
  58 .SH USAGE
  59 .sp
  60 .LP
  61 See \fBfsattr\fR(5) for a detailed description of extended file attributes.
  62 .sp
  63 .LP
  64 The process context created by the \fBrunat\fR command has its current working
  65 directory set to the hidden directory containing the file's extended
  66 attributes. The parent of this directory (the "\fB\&..\fR" entry) always refers
  67 to the file provided on the command line. As such, it may not be a directory.
  68 Therefore, commands (such as \fBpwd\fR) that depend upon the parent entry being
  69 well-formed (that is, referring to a directory) may fail.
  70 .sp
  71 .LP
  72 In the absence of the \fIcommand\fR argument, \fBrunat\fR will spawn a new
  73 interactive shell with its current working directory set to be the provided
  74 file's hidden attribute directory. Notice that some shells (such as \fBzsh\fR
  75 and \fBtcsh\fR) are not well behaved when the directory parent is not a
  76 directory, as described above. These shells should not be used with
  77 \fBrunat\fR.
  78 .SH EXAMPLES
  79 .LP
  80 \fBExample 1 \fRUsing runat to list extended attributes on a file
  81 .sp
  82 .in +2
  83 .nf
  84 example% \fBrunat file.1 ls -l\fR
  85 example% \fBrunat file.1 ls\fR
  86 .fi
  87 .in -2
  88 .sp
  89
  90 .LP
  91 \fBExample 2 \fRCreating extended attributes
  92 .sp
  93 .in +2
  94 .nf
  95 example% \fBrunat file.2 cp /tmp/attrdata attr.1\fR
  96 example% \fBrunat file.2 cat /tmp/attrdata > attr.1\fR
  97 .fi
  98 .in -2
  99 .sp
 100
 101 .LP
 102 \fBExample 3 \fRCopying an attribute from one file to another
 103 .sp
 104 .in +2
 105 .nf
 106 example% \fBrunat file.2 cat attr.1 | runat file.1 "cat > attr.1"\fR
 107 .fi
 108 .in -2
 109 .sp
 110
 111 .LP
 112 \fBExample 4 \fRUsing runat to spawn an interactive shell
 113 .sp
 114 .in +2
 115 .nf
 116 example% \fBrunat file.3 /bin/sh\fR
 117 .fi
 118 .in -2
 119 .sp
 120
 121 .sp
 122 .LP
 123 This spawns a new shell in the attribute directory for \fBfile.3\fR. Notice
 124 that the shell will not be able to determine what your current directory is. To
 125 leave the attribute directory, either exit the spawned shell or change
 126 directory (\fBcd\fR) using an absolute path.
 127
 128 .sp
 129 .LP
 130 Recommended methods for performing basic attribute operations:
 131
 132 .sp
 133 .ne 2
 134 .na
 135 \fBdisplay\fR
 136 .ad
 137 .RS 22n
 138 \fBrunat \fIfile\fR ls [\fIoptions\fR]\fR
 139 .RE
 140
 141 .sp
 142 .ne 2
 143 .na
 144 \fBread\fR
 145 .ad
 146 .RS 22n
 147 \fBrunat \fIfile\fR cat \fIattribute\fR\fR
 148 .RE
 149
 150 .sp
 151 .ne 2
 152 .na
 153 \fBcreate/modify\fR
 154 .ad
 155 .RS 22n
 156 \fBrunat \fIfile\fR cp \fIabsolute-file-path\fR \fIattribute\fR\fR
 157 .RE
 158
 159 .sp
 160 .ne 2
 161 .na
 162 \fBdelete\fR
 163 .ad
 164 .RS 22n
 165 \fBrunat \fIfile\fR rm \fIattribute\fR\fR
 166 .RE
 167
 168 .sp
 169 .ne 2
 170 .na
 171 \fBpermission changes\fR
 172 .ad
 173 .RS 22n
 174 .sp
 175 .in +2
 176 .nf
 177 \fBrunat \fIfile\fR chmod \fImode attribute\fR
 178 runat \fIfile\fR chgrp \fIgroup attribute\fR
 179 runat \fIfile\fR chown \fIowner attribute\fR\fR
 180 .fi
 181 .in -2
 182 .sp
 183
 184 .RE
 185
 186 .sp
 187 .ne 2
 188 .na
 189 \fBinteractive shell\fR
 190 .ad
 191 .RS 22n
 192 .LP
 193 .nf
 194 \fBrunat \fIfile\fR /bin/sh\fR or set your $SHELL to /bin/sh and \fBrunat \fIfile\fR\fR
 195 .fi
 196
 197 .RE
 198
 199 .sp
 200 .LP
 201 The above list includes commands that are known to work with \fBrunat\fR. While
 202 many other commands may work, there is no guarantee that any beyond this list
 203 will work. Any command that relies on being able to determine its current
 204 working directory is likely to fail. Examples of such commands follow:
 205 .LP
 206 \fBExample 5 \fRUsing man in an attribute directory
 207 .sp
 208 .in +2
 209 .nf
 210 example% \fBrunat file.1 man runat\fR
 211 >getcwd: Not a directory
 212 .fi
 213 .in -2
 214 .sp
 215
 216 .LP
 217 \fBExample 6 \fRSpawning a tcsh shell in an attribute directory
 218 .sp
 219 .in +2
 220 .nf
 221 example% \fBrunat file.3 /usr/bin/tcsh\fR
 222 tcsh: Not a directory
 223 tcsh: Trying to start from "/home/\fIuser\fR"
 224 .fi
 225 .in -2
 226 .sp
 227
 228 .sp
 229 .LP
 230 A new tcsh shell has been spawned with the current working directory set to the
 231 user's home directory.
 232
 233 .LP
 234 \fBExample 7 \fRSpawning a zsh shell in an attribute directory
 235 .sp
 236 .in +2
 237 .nf
 238 example% \fBrunat file.3 /usr/bin/zsh\fR
 239 example%
 240 .fi
 241 .in -2
 242 .sp
 243
 244 .sp
 245 .LP
 246 While the command appears to have worked, \fBzsh\fR has actually just changed
 247 the current working directory to '/'. This can be seen by using \fB/bin/pwd\fR:
 248
 249 .sp
 250 .in +2
 251 .nf
 252 example% \fB/bin/pwd\fR
 253 /
 254 .fi
 255 .in -2
 256 .sp
 257
 258 .SH ENVIRONMENT VARIABLES
 259 .sp
 260 .ne 2
 261 .na
 262 \fB\fBSHELL\fR\fR
 263 .ad
 264 .RS 9n
 265 Specifies the command shell to be invoked by \fBrunat\fR.
 266 .RE
 267
 268 .SH EXIT STATUS
 269 .sp
 270 .LP
 271 The following exit values are returned:
 272 .sp
 273 .ne 2
 274 .na
 275 \fB\fB125\fR \fR
 276 .ad
 277 .RS 8n
 278 The attribute directory of the file referenced by the \fIfile\fR argument
 279 cannot be accessed.
 280 .RE
 281
 282 .sp
 283 .ne 2
 284 .na
 285 \fB\fB126\fR \fR
 286 .ad
 287 .RS 8n
 288 The exec of the provided \fIcommand\fR argument failed.
 289 .RE
 290
 291 .sp
 292 .LP
 293 Otherwise, the exit status returned is the exit status of the shell invoked to
 294 execute the provided command.
 295 .SH ATTRIBUTES
 296 .sp
 297 .LP
 298 See \fBattributes\fR(5) for descriptions of the following attributes:
 299 .sp
 300
 301 .sp
 302 .TS
 303 box;
 304 c | c
 305 l | l .
 306 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 307 _
 308 CSI     Enabled
 309 _
 310 Interface Stability     Evolving
 311 .TE
 312
 313 .SH SEE ALSO
 314 .sp
 315 .LP
 316 \fBopen\fR(2), \fBattributes\fR(5), \fBfsattr\fR(5)
 317 .SH NOTES
 318 .sp
 319 .LP
 320 It is not always obvious why a command fails in \fBrunat\fR when it is unable
 321 to determine the current working directory. The errors resulting can be
 322 confusing and ambiguous (see the \fBtcsh\fR and \fBzsh\fR examples above).