1 .TH GET9ROOT 3
2 .SH NAME
3 get9root, unsharp \- get path to root of Plan 9 tree
4 .SH SYNOPSIS
5 .B #include <u.h>
6 .br
7 .B #include <libc.h>
8 .PP
9 .B
10 char*	get9root(void)
11 .PP
12 .B
13 char*	unsharp(char *path)
14 .SH DESCRIPTION
15 This tree of Plan 9 software is conventionally installed in
16 .B \*9
17 but may be installed in other places (for example, users without
18 the ability to write to
19 .B /usr/local
20 may with to install it in their own home directories).
21 The environment variable
22 .B $PLAN9
23 should contain the path to the root.
24 .I Get9root
25 returns a static pointer to the pathname of root, first checking
26 .B $PLAN9
27 and defaulting to
28 .BR \*9 .
29 .PP
30 The lack of a fixed location for the Plan 9 tree
31 makes it difficult to hard-code paths
32 to files. 
33 .I Unsharp
34 replaces a leading
35 .B #9
36 in 
37 .I path
38 with the root of the tree.
39 .I Unsharp
40 also replaces a leading
41 .B #d
42 with the path to the underlying system's file descriptor dup device,
43 typically
44 .BR /dev/fd .
45 The string returned from
46 .IR unsharp ,
47 if different from
48 .IR path ,
49 should be freed with
50 .I free
51 (see
52 .MR malloc (3) )
53 when no longer needed.
54 .PP
55 As a convention, programs should never
56 .I unsharp
57 paths obtained from user input.
58 .SH EXAMPLE
59 The
60 .MR plumber (4)
61 uses this code to find unrooted file names included by plumb rules.
62 .IP
63 .EX
64 snprint(buf, sizeof buf, "#9/plumb/%s", name);
65 fd = open(unsharp(buf), OREAD);
66 .EE
67 .SH SOURCE
68 .B \*9/src/lib9/get9root.c
69 .br
70 .B \*9/src/lib9/unsharp.c
71 .SH SEE ALSO
72 .MR intro (4)
73 .SH BUGS
74 .I Get9root
75 could be smarter about finding the tree when
76 .B $PLAN9
77 is not set.