Functions
int	smbc_open (const char *furl, int flags, mode_t mode)
int	smbc_creat (const char *furl, mode_t mode)
ssize_t	smbc_read (int fd, void *buf, size_t bufsize)
ssize_t	smbc_write (int fd, const void *buf, size_t bufsize)
off_t	smbc_lseek (int fd, off_t offset, int whence)
int	smbc_close (int fd)

Detailed Description

Functions used to access individual file contents

Function Documentation

int smbc_close ( int fd )

Close an open file handle.

Parameters:

fd	The file handle to close

Returns:

0 on success, < 0 on error with errno set:

EBADF fd isn't a valid open file descriptor
EINVAL smbc_init() failed or has not been called

See also:: smbc_open(), smbc_creat()

int smbc_creat	(	const char *	furl,
		mode_t	mode
	)

Create a file on an SMB server.

Same as calling smbc_open() with flags = O_CREAT|O_WRONLY|O_TRUNC

Parameters:

furl	The smb url of the file to be created
mode	mode specifies the permissions to use if a new file is created. It is modified by the process's umask in the usual way: the permissions of the created file are (mode & ~umask)

NOTE, the above is not true. We are dealing with an SMB server, which has no concept of a umask!

Returns:

Valid file handle, < 0 on error with errno set:

ENOMEM Out of memory
EINVAL if an invalid parameter passed, like no file, or smbc_init not called.
EEXIST pathname already exists and O_CREAT and O_EXCL were used.
EISDIR pathname refers to a directory and the access requested involved writing.
EACCES The requested access to the file is not allowed
ENOENT A directory component in pathname does not exist.
ENODEV The requested share does not exist.

See also:: smbc_open()

off_t smbc_lseek	(	int	fd,
		off_t	offset,
		int	whence
	)

Seek to a specific location in a file.

Parameters:

fd	Open file handle from smbc_open() or smbc_creat()
offset	Offset in bytes from whence
whence	A location in the file: SEEK_SET The offset is set to offset bytes from the beginning of the file SEEK_CUR The offset is set to current location plus offset bytes. SEEK_END The offset is set to the size of the file plus offset bytes.

Returns:

Upon successful completion, lseek returns the resulting offset location as measured in bytes from the beginning of the file. Otherwise, a value of (off_t)-1 is returned and errno is set to indicate the error:

EBADF Fildes is not an open file descriptor.
EINVAL Whence is not a proper value or smbc_init not called.

Todo:: Are all the whence values really supported?

Todo:: Are errno values complete and correct?

int smbc_open	(	const char *	furl,
		int	flags,
		mode_t	mode
	)

Open a file on an SMB server.

Parameters:

furl	The smb url of the file to be opened.
flags	Is one of O_RDONLY, O_WRONLY or O_RDWR which request opening the file read-only,write-only or read/write. flags may also be bitwise-or'd with one or more of the following: O_CREAT - If the file does not exist it will be created. O_EXCL - When used with O_CREAT, if the file already exists it is an error and the open will fail. O_TRUNC - If the file already exists it will be truncated. O_APPEND The file is opened in append mode
mode	mode specifies the permissions to use if a new file is created. It is modified by the process's umask in the usual way: the permissions of the created file are (mode & ~umask)

Not currently use, but there for future use. We will map this to SYSTEM, HIDDEN, etc bits that reverses the mapping that smbc_fstat does.

Returns:

Valid file handle, < 0 on error with errno set:

ENOMEM Out of memory
EINVAL if an invalid parameter passed, like no file, or smbc_init not called.
EEXIST pathname already exists and O_CREAT and O_EXCL were used.
EISDIR pathname refers to a directory and the access requested involved writing.
EACCES The requested access to the file is not allowed
ENODEV The requested share does not exist
ENOTDIR A file on the path is not a directory
ENOENT A directory component in pathname does not exist.

See also:: smbc_creat()

Note:: This call uses an underlying routine that may create a new connection to the server specified in the URL. If the credentials supplied in the URL, or via the auth_fn in the smbc_init call, fail, this call will try again with an empty username and password. This often gets mapped to the guest account on some machines.

ssize_t smbc_read	(	int	fd,
		void *	buf,
		size_t	bufsize
	)

Read from a file using an opened file handle.

Parameters:

fd	Open file handle from smbc_open() or smbc_creat()
buf	Pointer to buffer to recieve read data
bufsize	Size of buf in bytes

Returns:

Number of bytes read; 0 upon EOF; < 0 on error, with errno set:

EISDIR fd refers to a directory
EBADF fd is not a valid file descriptor or is not open for reading.
EINVAL fd is attached to an object which is unsuitable for reading, or no buffer passed or smbc_init not called.

See also:: smbc_open(), smbc_write()

ssize_t smbc_write	(	int	fd,
		const void *	buf,
		size_t	bufsize
	)

Write to a file using an opened file handle.

Parameters:

fd	Open file handle from smbc_open() or smbc_creat()
buf	Pointer to buffer to recieve read data
bufsize	Size of buf in bytes

Returns:

Number of bytes written, < 0 on error with errno set:

EISDIR fd refers to a directory.
EBADF fd is not a valid file descriptor or is not open for reading.
EINVAL fd is attached to an object which is unsuitable for reading, or no buffer passed or smbc_init not called.

See also:: smbc_open(), smbc_read()