Debian Codegraph @

extfs/README

raw
1 Writing scripts for Midnight Commander's external vfs
2
3 IMPORTANT NOTE: There may be some bugs left in extfs. Enjoy.
4
5 Starting with version 3.1, the Midnight Commander comes with so called
6 extfs, which is one of the virtual filesystems. This system makes it
7 possible to create new virtual filesystems for the GNU MC very easily.
8
9 Such work has two basic steps:
10
11 1. Editing $(libdir)/extfs/extfs.ini.
12 2. Creating a shell script/program to handle requests.
13 (Note: $(libdir) should be substituted for actual libdir path stored when
14 configured or compiled, like /usr/local/lib/mc or /usr/lib/mc).
15
16 The first one is very easy:
17
18 You assign a vfs suffix. For example, if you have .zip file, and would
19 like to see what's inside it, path will be
20
21 /anypath/my.zip#uzip/some_path/...
22
23 Then you add a line extfs.ini file containing just that extension. If
24 your vfs does not require a file to work on, add ':' to the of name.
25
26 In this example, .zip is suffix, but I call vfs 'uzip'. Why? Well,
27 what this vfs essentially does is UNzip. UN is too long, so I choosed
28 U. Note that sometime in the future, a filesystem like zip may exist:
29 It will take whole tree and create .zip file from it. So /usr:zip will
30 be zipfile containing whole /usr tree.
31
32 The second one may require some knowledge of shell/c programming: You
33 have to create a program (with executable permissions), "prefix", in
34 $(libdir)/extfs (in our example $(libdir)/extfs/uzip).
35
36 * Commands that should be implemented by your shell script
37 ----------------------------------------------------------
38
39 $libdir/extfs/prefix command [arguments]
40
41 * Command: list archivename
42
43 This command should list the complete archive content in the following format
44 (a little modified ls -l listing):
45
46 AAAAAAA NNN OOOOOOOO GGGGGGGG SSSSSSSS DATETIME [PATH/]FILENAME [-> [PATH/]FILENAME[/]]]
47
48 where (things in [] are optional):
49
50 AAAAAAA is the permission string like in ls -l
51 NNN is the number of links
52 OOOOOOOO is the owner (either UID or name)
53 GGGGGGGG is the group (either GID or name)
54 SSSSSSSS is the file size
55 FILENAME is the filename
56 PATH is the path from the archive's root without the leading slash (/)
57 DATETIME has one of the following formats:
58 Mon DD hh:mm, Mon DD YYYY, Mon DD YYYY hh:mm, MM-DD-YY hh:mm
59
60 where Mon is a three digit english month name, DD day
61 1-31, MM month 01-12, YY two digit year, YYYY four digit
62 year, hh hour and mm minute.
63
64 If the -> [PATH/]FILENAME part is present, it means:
65
66 If permissions start with an l (ell), then it is the name that symlink
67 points to. (If this PATH starts with a MC vfs prefix, then it is a symlink
68 somewhere to the other virtual filesystem (if you want to specify path from
69 the local root, use local:/path_name instead of /path_name, since /path_name
70 means from root of the archive listed).
71
72 If permissions do not start with l, but number of links is greater than one,
73 then it says that this file should be a hardlinked with the other file.
74
75
76 * Command: copyout archivename storedfilename extractto
77
78 This should extract from archive archivename the file called
79 storedfilename (possibly with path if not located in archive's root
80 [this is wrong. current extfs strips paths! -- [email protected]])
81 to file extractto.
82
83 * Command: copyin archivename storedfilename sourcefile
84
85 This should add to the archivename the sourcefile with the name
86 storedfilename inside the archive.
87
88 Important note: archivename in the above examples may not have the
89 extension you are expecting to have, like it may happen that
90 archivename will be something like /tmp/f43513254 or just
91 anything. Some archivers do not like it, so you'll have to find some
92 workaround.
93
94 * Command: run archivename storedfilename
95
96 This should execute some appropriate command, for instance, in the
97 'deb' module, 'run a.deb INSTALL' installs the archive with dpkg.
98
99 ---------------------------------------------------------
100
101 Don't forget to mark this file executable (chmod 755 ThisFile, for example)
102
103 For skeleton structure of executable, look at some of filesystems
104 similar to yours.
105
106 ---------------------------------------------------------
107
108 In constructing these routines, errors will be made, and mc will not display
109 a malformed printing line. That can lead the programmer down many false
110 trails in search of the bug. Since this routine is an executable shell script
111 it can be run from the command line independently of mc, and its output will
112 show on the console or can be redirected to a file.
113
114 * Putting it to use
115 ----------------------------------------------------------
116 The file .mc.ext in a home directory, and in mc's user directory (commonly
117 /usr/local/lib/mc), contains instructions for operations on files depending
118 on filename extensions. It is well documented in other files in this
119 distribution, so here are just a few notes specifically on use of the
120 Virtual File System you just built.
121
122 There are entries in .mc.ext defining a few operations that can be done on a
123 file from an mc panel. Typically they are annotated with a hash mark and a
124 file extension like this:
125
126 # zip
127
128 There must be a way to find the file by extension, so the next line does
129 that. In essence it says "identify the string ".zip" or (|) ".ZIP" at the
130 end ($) of a filename":
131
132 regex/\.(zip|ZIP)$
133
134 The operations themselves follow that. They must be indented by at least a
135 space, and a tab works as well. In particular, the Open operation will
136 now use your new virtual file system by cd'ing to it like this:
137
138 Open=%cd zip:%d/%p
139
140 This is the line used when a file is highlighted in a panel and the user
141 presses <Enter> or <Return>. The contents of the archive should show just
142 as if they were in a real directory, and can be manipulated as such.
143 The rest of the entry pertains to use of the F3 View key:
144
145 View=%view{ascii} unzip -v %f
146
147 And perhaps an optional icon for X:
148
149 Icon=zip.xpm
150
151 And perhaps an operation to extract the contents of the file, called from
152 a menu selection:
153
154 Extract=unzip %f '*'
155
156 This is just an example. The current entry for .zip files has a menu selection
157 of 'Unzip' which could be used in place of 'Extract'. What goes here depends
158 on what items you have in, or add to, the menu system, and that's another
159 subject. The sum of this is the .mc.ext entry:
160
161 # zip
162 regex/\.(zip|ZIP)$
163 Open=%cd zip:%d/%p
164 View=%view{ascii} unzip -v %f
165 Icon=zip.xpm
166 Extract=unzip %f '*'
167
168 Add an entry like this to the .mc.ext file in a user's home directory, If you
169 want others to have it, add it to the mc.ext file in the mc system directory,
170 often /usr/local/lib/mc/mc.ext. Notice this file is not prepended with a dot.
171
172 Once all this is done, and things are in their proper places, exit mc if you
173 were using it, and restart it so it picks up the new information.
174
175 That's all there is to it. The hardest part is making a listing function
176 that sorts the output of a system listing command and turns it into a form
177 that mc can use. Currently awk (or gawk) is used because nearly all systems
178 have it. If another scripting language is available, like perl, that could
179 also be used. (update: perl is used in several of the scripts now)