~ubuntu-branches/ubuntu/vivid/cctools/vivid

This product includes software developed by and/or derived from the Globus Project (http://www.globus.org/) to which the U.S. Government retains certain rights.

This program is released under the GNU General Public License. See the file COPYING for details.

This software comes with no warranty and no guarantee of support.

Questions, bug reports, and patches may be sent to

<a href=mailto:condor-admin@cs.wisc.edu>condor-admin@cs.wisc.edu</a>.

We will address such inquiries as time and resources permit.

<h2>Introduction</h2>

FTP-Lite is a library for accessing FTP servers from UNIX C programs.

It is designed to be simple, correct, and easily debuggable.

In particular, FTP-Lite presents an FTP service in terms of UNIX abstractions.

Errors are return in standard <code>errno</code> values.

Data streams are presented as <code>FILE</code> objects.

All procedures perform blocking I/O.

The library may be built as-is in order to communicate with ordinary

name/password or anonymous FTP servers. However, if the

<a href=http://www.globus.org>Globus Toolkit</a> is available, it will

also perform GSI authentication with your proxy certificate.

FTP-Lite provides perfectly reasonable performance for simple clients

that access one file at a time. For clients that need to manage multiple

servers at once, we heartily recommend the FTP implementation found in the

Globus Toolkit. It uses a variety of techniques, such as

multiple data streams and non-blocking interfaces, for achieving high

performance and multi-server access.

This library was designed specifically to be used with the

<a href=http://www.cs.wisc.edu/condor/pfs>Pluggable File System</a>,

which presents network storage devices as UNIX file systems.

You are welcome to use it for other purposes, according to the terms

set out in the GNU Library General Public License.

<h2>Installation</h2>

Download the FTP-Lite source package from the

<a href=http://www.cs.wisc.edu/condor/ftp_lite>web page</a>.

Unpack the archive like so:

<dir>

<pre>

% gunzip ftp_lite-0.0.tar.gz

% tar xvf ftp_lite-0.0.tar

</pre>

</dir>

Decide on a place to install FTP-Lite.

If you have the Globus and SSL libraries, figure out where they are installed,

and feed the information to <code>configure</code>:

<dir>

<pre>

% cd ftp_lite-0.0

% ./configure --prefix /install/dir --with-globus-path /path/to/globus --with-ssl-path /path/to/ssl

</pre>

</dir>

(At UW-Madison, the appropriate invocation would be:)

<dir>

<pre>

% cd ftp_lite-0.0

% ./configure --prefix ~/ftp_lite --with-globus-path /p/condor/workspaces/globus --with-ssl-path /p/condor/workspaces/ssl

</pre>

</dir>

Finally, build and install the library:

<dir>

100

<pre>

101

% make

102

% make install

103

</pre>

104

</dir>

105

106

To build a program using FTP-Lite, change your compile and link options like so:

107

108

<dir>

109

<pre>

110

CCFLAGS += -I/install/dir/include

111

LDFLAGS += -L/install/dir/lib -lftp_lite

112

</pre>

113

</dir>

114

115

116

<h2>Examples</h2>

117

118

For examples of using the library, we recommend that you begin by examining the code for the simple programs <code>ftp_lite_test</code> and <code>ftp_lite_copy</code>. A complete description of every function may be found in the <a href=#reference>reference</a> section below. Here is a brief example to get you started.

119

120

A program using the library must first include <code>ftp_lite.h</code>:

121

<dir>

122

<pre>

123

#include "ftp_lite.h"

124

</pre>

125

</dir>

126

To open a server, call <code>ftp_lite_open</code> with a server name, port number, and a stream on which to send debugging messages. For no debugging, leave the third argument null. On success, this function returns a pointer to a server.

127

<dir>

128

<pre>

129

struct ftp_server *s;

130

131

s = ftp_lite_open( "ftp.cs.wisc.edu", FTP_LITE_DEFAULT_PORT, stderr );

132

if(!s) {

133

perror("couldn't open server");

134

return 0;

135

}

136

</pre>

137

</dir>

138

You must authenticate yourself to the server before accessing any data. Three sorts of authentication are currently provided: anonymous, userpass, and Globus. For example, to authenticate with a username and password:

139

<dir>

140

<pre>

141

success = ftp_lite_auth_userpass(server,"fred","secret");

142

if(!success) {

143

perror("couldn't log in");

144

return 0;

145

}

146

</pre>

147

</dir>

148

For convenience, FTP-Lite provides a single procedure which tries the various authentication methods, possible requesting information from the console. Most users will find it easiest to replace the above two steps with :

149

<pre>

150

<dir>

151

s = ftp_lite_open_and_auth( "ftp.cs.wisc.edu", stderr );

152

if(!s) {

153

perror("couldn't open server");

154

return 0;

155

}

156

</pre>

157

</dir>

158

To retrieve a file, call <code>ftp_lite_get</code> with the server pointer, a path name, and the offset at which to begin. On success, it returns a <code>FILE</code> object.

159

<dir>

160

<pre>

161

FILE *f;

162

163

f = ftp_lite_get( s, "README", 0 );

164

if(!f) {

165

perror("couldn't get file");

166

return 0;

167

}

168

</pre>

169

</dir>

170

You may read from this stream pointer using any of the standard UNIX I/O operations, such as <code>fscanf</code>, <code>fread</code>, and so on. For convenience, FTP-Lite provides a function <code>ftp_lite_stream_to_stream</code> that will copy one whole file pointer into another. So, to display this file, you might do this:

171

<dir>

172

<pre>

173

length = ftp_lite_stream_to_stream( f, stdout );

174

if(length<0) {

175

perror("couldn't transfer data");

176

return 0;

177

}

178

</pre>

179

</dir>

180

When done reading data, you must close the stream and inform the server that you are done:

181

<dir>

182

<pre>

183

fclose(f);

184

ftp_lite_done(s);

185

</pre>

186

</dir>

187

To close the connection to the server completely:

188

<dir>

189

<pre>

190

ftp_lite_close(s);

191

</pre>

192

</dir>

193

194

195

<h2>Reference</h2>

196

197

This section lists all of the public functions in the FTP-Lite library.

198

199

Unless noted otherwise, all functions return true (non-zero) on success or false (zero) on failure. In addition, every function sets <code>errno</code> appropriately on a failure. Tools for handling error values can be found in the UNIX man pages for <code>errno</code>, <code>strerror</code>, and <code>perror</code>. Nearly every error value is a possible result of any function.

200

201

Some error values are inacurrate, due to weaknesses in the FTP protocol itself. For example, the FTP error 550 is represented as the errno <code>EEXIST</code>. However, a brief poll of servers shows that many return the same error value for errors that should be distinct, such as "no such file", and "file already exists." So, be careful.

202

203

If the library is returning unexpected results, we recommend that you debug the code by passing <code>stderr</code> as the debugging argument to <code>ftp_lite_open</code>. This will show a low of events in the protocol, and is invaluable in revealing unexpected events.

204

205

So, here are the procedures in the library:

206

<dir>

207

<li>ftp_lite_auth_anonymous

208

int ftp_lite_auth_anonymous( struct ftp_lite_server *s );

209

Attempt to log in anonymously to an already-opened server.

210

211

<li>ftp_lite_auth_globus

212

int ftp_lite_auth_globus( struct ftp_lite_server *s );

213

Attempt to log in with Globus credentials to an already-opened server.

214

The caller must have already established a proxy certificate with <code>grid-proxy-init</code> or a similar tool.

215

216

<li>ftp_lite_auth_userpass

217

int ftp_lite_auth_userpass( struct ftp_lite_server *s, const char *user, const char *password );

218

Attempt to log in with this name and password. This mechanism sends names and passwords in the clear and should be deprecated in favor of Globus authentication.

219

220

<li>ftp_lite_change_dir

221

int ftp_lite_change_dir( struct ftp_lite_server *s, const char *dir );

222

Change the current working directory to that given.

223

224

<li>ftp_lite_close

225

void ftp_lite_close( struct ftp_lite_server *server );

226

Close this open server. Once a connection is closed, the server pointer is no longer valid.

227

228

<li>ftp_lite_delete int

229

int ftp_lite_delete( struct ftp_lite_server *s, const char *path );

230

Delete a file.

231

232

<li>ftp_lite_delete_dir

233

int ftp_lite_delete_dir( struct ftp_lite_server *s, const char *dir );

234

Delete a directory. Most servers will not permit the deletion of a directory that is not empty.

235

236

<li>ftp_lite_done

237

int ftp_lite_done( struct ftp_lite_server *s );

238

Signal that a data transfer is complete. This must be called before any other functions are invoked.

239

240

<li>ftp_lite_get

241

FILE * ftp_lite_get( struct ftp_lite_server *s, const char *path, off_t offset );

242

Retrieve a file beginning from this offset. On success, returns a stream pointer. On failure, returns null. After reading to the end of the stream, you must call <code>fclose</code> and <code>ftp_lite_done</code>.

243

244

<li>ftp_lite_list

245

FILE * ftp_lite_list( struct ftp_lite_server *s, const char *path );

246

Retrieve the list of names contained in this directory. On success, return a stream pointer which will provide the list of newline-terminated names. On failure, returns null. After reading to the end of the stream, you must call <code>fclose</code> and <code>ftp_lite_done</code>.

247

248

<li>ftp_lite_login

249

int ftp_lite_login( const char *prompt, char *name, int namelen, char *pass, int passlen );

250

Display a prompt on the console and ask the user to enter a name and password. <code>name</code> and <code>pass</code> are filled in up to the lengths given.

251

252

<li>ftp_lite_make_dir

253

int ftp_lite_make_dir( struct ftp_lite_server *s, const char *dir );

254

Create a directory.

255

256

<li>ftp_lite_nop

257

int ftp_lite_nop( struct ftp_lite_server *s );

258

Send a no-operation command to the server. This command is useful for determining if a connection is still alive.

259

260

<li>ftp_lite_open

261

struct ftp_lite_server * ftp_lite_open( const char *host, int port, FILE *log );

262

Connect to a server on the given host and port. The third argument gives a stream which is used for debugging information. On success, return an opaque pointer to a server. On failure, return null. The appropriate port depends on the authentication method to be used. For Globus authentication, connect to <code>FTP_LITE_GSS_DEFAULT_PORT</code>. For anonymous and userpass authentication, connect to <code>FTP_LITE_DEFAULT_PORT</code>.

263

264

<li>ftp_lite_open_and_auth

265

struct ftp_lite_server * ftp_lite_open_and_auth( const char *host, FILE *log );

266

Connect to a server, but try all available ports and authentication methods. The second argument gives a stream to be used for debugging. On success, return an opaque pointer to a server. On failure, return null.

267

268

<li>ftp_lite_put

269

FILE * ftp_lite_put( struct ftp_lite_server *s, const char *path, off_t offset, size_t size );

270

Transmit a file to a server. On success, returns a stream to be written to. On failure, returns null. After writing all data to the stream, you must call <code>fclose</code> and <code>ftp_lite_done</code>. <code>offset</code> controls the point at which writing will begin in the target file. If <code>size</code> is <code>FTP_LITE_WHOLE_FILE</code>, then the target file will be truncated when the stream is closed. A variety of FTP commands may be used to implement a put, and not all severs will support all combinations of <code>offset</code> and <code>size</code>.

271

272

<li>ftp_lite_rename

273

int ftp_lite_rename( struct ftp_lite_server *s, const char *oldname, const char *newname );

274

Move the file <code>oldname</code> in <code>newname</code>.

275

276

<li>ftp_lite_size

277

size_t ftp_lite_size( struct ftp_lite_server *s, const char *path );

278

Return the number of bytes stored in this file. On failure, returns -1.

279

280

<li>ftp_lite_stream_to_buffer

281

int ftp_lite_stream_to_buffer( FILE *input, char **buffer );

282

Copy the contents of this stream into a memory buffer. On success, returns the number of bytes copied. On failure, returns -1. <code>input</code> must be a stream opened for reading, and <code>buffer</code> must be a pointer to an uninitialized <code>char *</code>. Space for the buffer will be allocated with <code>malloc</code>. The caller becomes responsible for freeing the buffer when done.

283

284

<li>ftp_lite_stream_to_stream

285

int ftp_lite_stream_to_stream( FILE *input, FILE *output );

286

Copy the contents of one stream into another. On success, returns the number of bytes copied. On failure, returns -1.

287

288

<li>ftp_lite_third_party_transfer

289

int ftp_lite_third_party_transfer( struct ftp_lite_server *source, const char *source_file, struct ftp_lite_server *target, const char *target_file );

290

Performs a third-party transfer between two servers. Each server must already be opened and authenticated. There are a large number of reasons for which a third party transfer might fail. We recommend you use this feature with the debugging stream enabled.

291

292

</dir>

293

294

</body>

295

Older »