Functions
int	smbc_unlink (const char *furl)
int	smbc_rename (const char ourl, const char nurl)
int	smbc_opendir (const char *durl)
int	smbc_closedir (int dh)
int	smbc_getdents (unsigned int dh, struct smbc_dirent *dirp, int count)
struct smbc_dirent *	smbc_readdir (unsigned int dh)
off_t	smbc_telldir (int dh)
int	smbc_lseekdir (int fd, off_t offset)
int	smbc_mkdir (const char *durl, mode_t mode)
int	smbc_rmdir (const char *durl)
int	smbc_urldecode (char dest, char src, size_t max_dest_len)
const char *	smbc_version (void)

Detailed Description

Functions used to access directory entries

Function Documentation

int smbc_closedir ( int dh )

Close a directory handle opened by smbc_opendir().

Parameters:

dh	Directory handle to close

Returns:

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

EBADF dh is an invalid directory handle

See also:: smbc_opendir()

int smbc_getdents	(	unsigned int	dh,
		struct smbc_dirent *	dirp,
		int	count
	)

Get multiple directory entries.

smbc_getdents() reads as many dirent structures from the an open directory handle into a specified memory area as will fit.

Parameters:

dh	Valid directory as returned by smbc_opendir()
dirp	pointer to buffer that will receive the directory entries.
count	The size of the dirp buffer in bytes

Returns:

If any dirents returned, return will indicate the total size. If there were no more dirents available, 0 is returned. < 0 indicates an error.

EBADF Invalid directory handle
EINVAL Result buffer is too small or smbc_init not called.
ENOENT No such directory.

See also:: , smbc_dirent, smbc_readdir(), smbc_open()

Todo:: Are errno values complete and correct?

Todo:: Add example code so people know how to parse buffers.

int smbc_lseekdir	(	int	fd,
		off_t	offset
	)

lseek on directories.

smbc_lseekdir() may be used in conjunction with smbc_readdir() and smbc_telldir(). (rewind by smbc_lseekdir(fd, NULL))

Parameters:

fd	Valid directory as returned by smbc_opendir()
offset	The offset (as returned by smbc_telldir). Can be NULL, in which case we will rewind

Returns:

0 on success, -1 on failure

EBADF dh is not a valid directory handle
ENOTDIR if dh is not a directory
EINVAL offset did not refer to a valid dirent or smbc_init not called.

See also:: smbc_telldir()

Todo:: In what does the reture and errno values mean?

int smbc_mkdir	(	const char *	durl,
		mode_t	mode
	)

Create a directory.

Parameters:

durl	The url of the directory to create
mode	Specifies the permissions to use. It is modified by the process's umask in the usual way: the permissions of the created file are (mode & ~umask).

Returns:

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

EEXIST directory url already exists
EACCES The parent directory does not allow write permission to the process, or one of the directories
ENOENT A directory component in pathname does not exist.
EINVAL NULL durl passed or smbc_init not called.
ENOMEM Insufficient memory was available.

See also:: smbc_rmdir()

int smbc_opendir ( const char * durl )

Open a directory used to obtain directory entries.

Parameters:

durl	The smb url of the directory to open

Returns:

Valid directory handle. < 0 on error with errno set:

EACCES Permission denied.
EINVAL A NULL file/URL was passed, or the URL would not parse, or was of incorrect form or smbc_init not called.
ENOENT durl does not exist, or name is an
ENOMEM Insufficient memory to complete the operation.
ENOTDIR name is not a directory.
EPERM the workgroup could not be found.
ENODEV the workgroup or server could not be found.

See also:: smbc_getdents(), smbc_readdir(), smbc_closedir()

struct smbc_dirent* smbc_readdir ( unsigned int dh ) [read]

Get a single directory entry.

Parameters:

dh	Valid directory as returned by smbc_opendir()

Returns:

A pointer to a smbc_dirent structure, or NULL if an error occurs or end-of-directory is reached:

EBADF Invalid directory handle
EINVAL smbc_init() failed or has not been called

See also:: smbc_dirent, smbc_getdents(), smbc_open()

int smbc_rename	(	const char *	ourl,
		const char *	nurl
	)

Rename or move a file or directory.

Parameters:

ourl	The original smb url (source url) of file or directory to be moved
nurl	The new smb url (destination url) of the file or directory after the move. Currently nurl must be on the same share as ourl.

Returns:

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

EISDIR nurl is an existing directory, but ourl is not a directory.
EEXIST nurl is a non-empty directory, i.e., contains entries other than "." and ".."
EINVAL The new url contained a path prefix of the old, or, more generally, an attempt was made to make a directory a subdirectory of itself or smbc_init not called.
ENOTDIR A component used as a directory in ourl or nurl path is not, in fact, a directory. Or, ourl is a directory, and newpath exists but is not a directory.
EACCES or EPERM Write access to the directory containing ourl or nurl is not allowed for the process's effective uid, or one of the directories in ourl or nurl did not allow search (execute) permission, or ourl was a directory and did not allow write permission.
ENOENT A directory component in ourl or nurl does not exist.
EXDEV Rename across shares not supported.
ENOMEM Insufficient kernel memory was available.
EEXIST The target file, nurl, already exists.

Todo:: Are we going to support copying when urls are not on the same share? I say no... NOTE. I agree for the moment.

int smbc_rmdir ( const char * durl )

Remove a directory.

Parameters:

durl	The smb url of the directory to remove

Returns:

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

EACCES or EPERM Write access to the directory containing pathname was not allowed.
EINVAL durl is NULL or smbc_init not called.
ENOENT A directory component in pathname does not exist.
ENOTEMPTY directory contains entries.
ENOMEM Insufficient kernel memory was available.

See also:: smbc_mkdir(), smbc_unlink()

Todo:: Are errno values complete and correct?

off_t smbc_telldir ( int dh )

Get the current directory offset.

smbc_telldir() may be used in conjunction with smbc_readdir() and smbc_lseekdir().

Parameters:

dh	Valid directory as returned by smbc_opendir()

Returns:

The current location in the directory stream or -1 if an error occur. The current location is not an offset. Becuase of the implementation, it is a handle that allows the library to find the entry later.

EBADF dh is not a valid directory handle
EINVAL smbc_init() failed or has not been called
ENOTDIR if dh is not a directory

See also:: smbc_readdir()

int smbc_unlink ( const char * furl )

Unlink (delete) a file or directory.

Parameters:

furl	The smb url of the file to delete

Returns:

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

EACCES or EPERM Write access to the directory containing pathname is not allowed or one of the directories in pathname did not allow search (execute) permission
ENOENT A directory component in pathname does not exist
EINVAL NULL was passed in the file param or smbc_init not called.
EACCES You do not have access to the file
ENOMEM Insufficient kernel memory was available

See also:: smbc_rmdir()s

Todo:: Are errno values complete and correct?

int smbc_urldecode	(	char *	dest,
		char *	src,
		size_t	max_dest_len
	)

Convert strings of xx to their single character equivalent.

Parameters:

dest	A pointer to a buffer in which the resulting decoded string should be placed. This may be a pointer to the same buffer as src_segment.
src	A pointer to the buffer containing the URL to be decoded. Any xx sequences herein are converted to their single character equivalent. Each 'x' must be a valid hexadecimal digit, or that % sequence is left undecoded.
max_dest_len	The size of the buffer pointed to by dest_segment.

Returns:: The number of % sequences which could not be converted due to lack of two following hexadecimal digits.

const char* smbc_version ( void )

Return the version of the linked Samba code, and thus the version of the libsmbclient code.

Returns:: The version string.