3D ( 1 ) USER COMMANDS3D ( 1 )


NAME

3d - execute a command with nDFS filesystem services enabled

SYNOPSIS

3d [ options ] [ command [ arg ... ] ]

DESCRIPTION

3d executes a dynamically linked command with nDFS filesystem services enabled. It intercepts pathname system calls and applies the nDFS operations specified by the VPATH environment variable, the command line mounts, and the vpath command. If command is omitted then an interactive sh(1) is started. All processes executed by command also have nDFS enabled.

The main 3d service is viewpathing. A viewpath mounts one directory tree on top of another. Files in the top level (directory tree) obscure files in the lower level. Lower level files have copy-on-write semantics to the top level. i.e., files in the lower level are readonly; if a lower level file is modified it is first copied to the top level before modification. Viewpath mounted directories can be chained. All levels but the top in a chain are readonly. The traditional VPATH=d1:d2:d3 viewpathing is specified by the two 3d mounts "d1 d2" and "d2 d3".

The following service mounts are initialized by default:

/dev/fd

/dev/fd/n refers to the open file descriptor n in the current process.
/dev/fdp

/dev/fdp/local/service opens a 2-way stream to service on the local host. The stream supports file descriptor exchange.
/dev/tcp

/dev/tcp/host/service opens a 2-way connection to service on host. inetd(8) services are named either by inet.service or by port number.
/dev/udp

/dev/udb/host/service opens a datagram connection to service on host. inetd(8) services are named either by inet.service or by port number.

OPTIONS

-c, --command

Ignored; allows 3d to be invoked like sh(1).
-d, --debug=level

Set the debug trace level to level. Higher levels produce more output.
-l, --lite

Disable the default service mounts.
-m, --mount="top bottom"

Mount the path top onto the path bottom. If bottom is a directory then the directory top is viewpathed on top of bottom. Otherwise bottom must match a 3d fs path of the form /#special.
-n, --exec

Execute command. --noexec shows how command would be invoked but does not execute. On by default; -n means --noexec.
-o, --output=file

--trace and --debug output is written to file instead of the standard error.
-s, --shell=file

Sets the sh(1) executable path to file . The default value is ksh.
-t, --trace=id

If id is 1 then intercepted system calls for all child processes will be traced. If id is greater than 1 then intercepted system calls for the current process and all children will be traced.
-v, --version=major.minor

Use 3d version major.minor instead of the latest version.
-x
Passed to the 3d sh(1).

FS PATHS

3d fs paths of the form /#special[/...] control the semantics of 3d and allow services to be attached to the file namespace. Unsupported fs paths are silently ignored. The supported fs paths are:
/#fd
/#fs/name[/option/...]
/#map
/#null
/#option
2d
3d
boundary
call=value
count=value
debug=level
dump=[value]
call=value
file=value
fs=value
map=value
mount=value
safe=value
state=value
view=value
file=value
fork
init
license=path
mount=value
table=value
test=bitmask
timeout=value
timestamp
trace=value
version=1
/#pwd
/#safe
/#view

DETAILS

nDFS semantics are applied by intercepting system calls with a dll that is preloaded at process startup before main () is called. The interception mechanism may involve the environment on some systems; in those cases commands like env(1) that clear the enviroment before execution may defeat the 3d intercepts. The intercepted system calls are listed by vpath - /#option/dump=call. Note that implementation system call names may differ from those listed in section 2 of the manual; stat(2) is especially vulnerbale to mangling.

3d ignores calls not present in a particular host system. In addition, 3d only works on dynamically linked executables that have neither set-uid nor set-gid permissions. It may not have the intended effect on programs written in a language or linked with a language runtime that hides or mangles system call library symbols, or that directly emit system call instruction sequences rather than using the corresponding library functions, or that dynamically link libraries outside of the scope of the 3d intercepts.

Multi-process client-server applications may misbehave if the 3d environment between the related processes is not kept in sync.

ENVIRONMENT

3d is implemented by four components: the 3d script, located on $PATH; the 3d dll (shared library), located either on $PATH or in one of the ../lib* directories on $PATH, depending on local compilation system conventions; and the 2d sh(1) alias and _2d sh(1) function that allow commands to be run with nDFS semantics disabled. Systems like sgi.mips3 that support multiple a.out formats may have multiple versions of the 3d dll. In all cases the 3d script handles the dll search.

EXAMPLES

$ 3d $ VPATH=$INSTALLROOT:$PACKAGEROOT 3d $ 3d ls -l $ 2d ls -l

SEE ALSO

env(1), ie(1), sh(1), trace(1), warp(1), stat(2)

IMPLEMENTATION

version

3d (AT&T Labs Research) 2006-10-01
author

Glenn Fowler <glenn.s.fowler@gmail.com>
author

David Korn <dgkorn@gmail.com>
author

Eduardo Krell <ekrell@adexus.cl>
copyright

Copyright © 1989-2012 AT&T Intellectual Property
license

http://www.eclipse.org/org/documents/epl-v10.html