tsmugfs.4 - plan9port - [fork] Plan 9 from user space
HTML git clone git://src.adamsgaard.dk/plan9port
DIR Log
DIR Files
DIR Refs
DIR README
DIR LICENSE
---
tsmugfs.4 (6332B)
---
1 .TH SMUGFS 4
2 .SH NAME
3 smugfs \- file system access to SmugMug photo sharing
4 .SH SYNOPSIS
5 .B smugfs
6 [
7 .B -DFH
8 ]
9 [
10 .B -k
11 .I keypattern
12 ]
13 [
14 .B -m
15 .I mtpt
16 ]
17 [
18 .B -s
19 .I srvname
20 ]
21 .SH DESCRIPTION
22 .I Smugfs
23 is a user-level file system that provides access to images
24 stored on the SmugMug photo sharing service.
25 It logs in after
26 obtaining a password from
27 .MR factotum (4)
28 using
29 .B server=smugmug.com
30 and
31 .I keypattern
32 (if any)
33 as key criteria
34 (see
35 .MR auth (3) ).
36 Then
37 .I smugfs
38 serves a virtual directory tree mounted at
39 .I mtpt
40 (default
41 .BR /n/smug )
42 and posted at
43 .I srvname ,
44 if the
45 .B -s
46 option is given.
47 .PP
48 The directory tree is arranged in five levels:
49 root, user, category, album, and image.
50 For example,
51 .B /n/smug/cmac/
52 is a user directory,
53 .B /n/smug/cmac/People/
54 is a category directory,
55 .B /n/smug/cmac/People/Friends/
56 is an album directory,
57 and
58 .B /n/smug/cmac/albums/Friends/2631/
59 is an image directory.
60 .PP
61 SmugMug allows fine-grained classification
62 via subcategories, but subcategories are not yet implemented.
63 .ig
64 Subcategories are inserted as
65 an additional directory level between category
66 and album.
67 [Subcategories are not yet implemented.]
68 ..
69 .PP
70 All directories contain a special control file named
71 .BR ctl ;
72 text commands written to
73 .B ctl
74 change
75 .IR smugfs 's
76 behavior or implement functionality
77 that does not fit nicely into the file system
78 interface.
79 .PP
80 .I Smugfs
81 caches information about users, categories, albums,
82 and images. If changes are made outside of
83 .I smugfs
84 (for example, using a web browser),
85 the cache may need to be discarded.
86 Writing the string
87 .B sync
88 to a directory's
89 .B ctl
90 file causes
91 .I smugfs
92 to discard all cached information used to
93 present that directory and its children.
94 Thus, writing
95 .B sync
96 to the root
97 .B ctl
98 file discards all of
99 .I smugfs 's
100 cached information.
101 .SS "Root directory"
102 The root directory contains directories
103 named after users.
104 By default, it contains only a directory for
105 the logged-in user, but other directories will
106 be created as needed to satisfy directory lookups.
107 .PP
108 In addition to user directories, the root directory
109 contains three special files:
110 .BR ctl ,
111 .BR rpclog ,
112 and
113 .BR uploads .
114 Reading
115 .B rpclog
116 returns a list of recent RPCs issued to the SmugMug API server.
117 Reads at the end of the file block until a new RPC is issued.
118 The
119 .B uploads
120 file lists the file upload queue (q.v.).
121 .SS "User directories"
122 User directories contain category directories
123 named after the categories.
124 SmugMug pre-defines a variety of categories,
125 so it is common to have many categories that
126 do not contain albums.
127 .PP
128 In a user directory, creating a new directory
129 creates a new category on SmugMug.
130 Similarly, renaming or removing a category
131 directory renames or removes the category on SmugMug.
132 Categories cannot be removed if they contain albums.
133 .PP
134 User directories also contain a directory
135 named
136 .B albums
137 that itself contains all of that user's albums.
138 .SS "Category directories"
139 Each category directory contains album directories
140 named using the album's title.
141 .PP
142 In a category directory, creating a new directory
143 creates a new album on SmugMug.
144 Similarly, renaming or removing an album directory
145 renames or removes the album on SmugMug.
146 Albums cannot be removed if they contain images.
147 .ig
148 .PP
149 Category directories might also contain subcategory directories.
150 Like albums, subcategories can be renamed and removed (when empty).
151 Unlike albums, subcategories cannot be created via ordinary
152 file system operations.
153 Instead, write the command
154 .B subcategory
155 .I name
156 to the category's
157 .B ctl
158 file.
159 .PP
160 Subcategories are identical to categories
161 except that they cannot themselves contain subcategories.
162 ..
163 .SS "Album directories"
164 Each album directory contains image directories
165 named using the image's decimal SmugMug ID.
166 Image directories cannot be created or renamed,
167 but they can be removed. Removing an image directory
168 removes the image from the album on SmugMug.
169 .PP
170 Album directories also contain three special files,
171 .BR ctl ,
172 .BR settings ,
173 and
174 .BR url .
175 .PP
176 The
177 .B settings
178 file contains the album settings in textual form,
179 one setting per line.
180 Each line represents a single setting and is formatted
181 as an alphabetic setting name followed by a single tab
182 followed by the value.
183 Many settings can be changed by writing new setting lines,
184 in the same format, to the
185 .B settings
186 file.
187 .PP
188 Copying a file into the album directory queues it for
189 uploading to SmugMug to be added to the album.
190 Files disappear from the album directory once they
191 have finished uploading, replaced by new image directories.
192 The
193 .B uploads
194 file in the root directory lists all pending uploads,
195 which are stored temporarily
196 in
197 .BR /var/tmp .
198 .SS "Image directories"
199 Each image directory contains an image file, named
200 with its original name, if available.
201 If the image belongs to another user, SmugMug does not
202 expose the original name, so the file is named
203 .RB \fInnnn\fP .jpg ,
204 where
205 .I nnnn
206 is the SmugMug image ID number.
207 The file content is the original image
208 or else the largest image available.
209 .PP
210 The directory contains a
211 .B settings
212 file holding per-image settings, similar to the
213 file in the album directory;
214 and a
215 .B url
216 file, containing URLs to the various sized images
217 on the SmugMug server.
218 .SH EXAMPLES
219 .LP
220 Mount
221 .I smugfs
222 on
223 .BR /n/smug ;
224 the current user must have write access to
225 .B /n/smug
226 and
227 .BR /dev/fuse .
228 .IP
229 .EX
230 % smugfs
231 .EE
232 Watch API calls as they execute:
233 .IP
234 .EX
235 % cat /n/smug/rpclog &
236 .EE
237 Create a new album in the Vacation category
238 and fill it with photos:
239 .IP
240 .EX
241 % mkdir /n/smug/you/Vacation/Summer
242 % cp *.jpg /n/smug/you/Vacation/Summer
243 .EE
244 .LP
245 The photos are now uploading in the background.
246 Wait for the uploads to finish:
247 .IP
248 .EX
249 % while(test -s /n/smug/uploads) sleep 60
250 .EE
251 .LP
252 Make the album publicly viewable and share it.
253 .IP
254 .EX
255 % echo public 1 >/n/smug/you/Vacation/Summer/settings
256 % cat /n/smug/you/Vacation/Summer/url | mail friends
257 .EE
258 .SH SOURCE
259 .B \*9/src/cmd/smugfs
260 .SH SEE ALSO
261 SmugMug,
262 .HR http://smugmug.com/
263 .SH BUGS
264 .PP
265 If multiple categories or albums have the same name,
266 only one will be accessible via the file system interface.
267 Renaming the accessible one via Unix's
268 .MR mv (1)
269 will resolve the problem.
270 .PP
271 Boolean values appear as
272 .B true
273 and
274 .B false
275 in settings files but must be changed using
276 .B 1
277 and
278 .BR 0 .