C Language Programming Interface List

This page lists the elements of the BlackBerry Dynamics C language programming interface. More...

Typedefs
typedef void(*	nslookupCompletionCallback) (const char *jsonResponse)
	BlackBerry Dynamics name service lookup completion callback. More...
typedef void(*	nslookupCompletionCallbackEx) (const char *jsonResponse, const void *data)
	BlackBerry Dynamics name service lookup completion extended callback. More...
typedef enum GD_nslookup_type_t	GD_nslookup_type
	Enumerated constants for use with the BlackBerry Dynamics name service. More...
typedef void(*	completionCallback) (const char *myIP)
	End point IP address retrieval completion callback. More...
typedef void(*	completionCallbackEx) (const char *myIP, const void *data)
	End point IP address retrieval completion extended callback. More...
typedef size_t	GD_FILE
	C API file structure, for accessing secure storage.
typedef size_t	GD_DIR
	C API directory structure, for accessing secure storage.

Enumerations
enum	GD_nslookup_type_t { GD_nslookup_CNAME = 0, GD_nslookup_ARECORD }
	Enumerated constants for use with the BlackBerry Dynamics name service. More...
enum	GD_ROUTE {   GD_ROUTE_UNKNOWN, GD_ROUTE_INTERNET, GD_ROUTE_GOOD_PROXY, GD_ROUTE_DENY,   GD_ROUTE_INTERNET_LISTED }
	Route information constants. More...

Functions
void	GD_nslookup (const char *host, GD_nslookup_type type, nslookupCompletionCallback callback)
	Execute a BlackBerry Dynamics name service lookup. More...
void	GD_nslookupEx (const char *host, GD_nslookup_type type, nslookupCompletionCallbackEx callback, const void *data)
	Execute a BlackBerry Dynamics name service lookup with a callback extension. More...
char *	GD_getFqdn (const char *host)
	Get a fully qualified domain name for a host server. More...
void	GD_myipaddress (const char *host, unsigned int port, completionCallback callback)
	Get the IP address of the BlackBerry Dynamics end point for a specified host. More...
void	GD_myipaddressEx (const char *host, unsigned int port, completionCallbackEx callback, const void *data)
	Get the IP address of the BlackBerry Dynamics end point for a specified host with a callback extension. More...
int	GD_fcntl (int fd, int cmd,...)
	C API.
struct hostent *	GD_gethostbyname (const char *name)
	C API.
int	GD_getaddrinfo (const char *node, const char *service, const struct addrinfo *hints, struct addrinfo **addresses)
	C API.
int	GD_freeaddrinfo (struct addrinfo *ai)
	C API.
int	GD_getnameinfo (const struct sockaddr *address, socklen_t addressLength, char *node, size_t nodeLength, char *service, size_t serviceLength, int flags)
	C API.
enum GD_ROUTE	GD_getRouteInfo (const struct sockaddr *address)
	Check if routing is via the BlackBerry Dynamics infrastructure. More...
ssize_t	GD_sendfile (int out_fd, int in_fd, off_t *offset, size_t count)
	C API.
int	GD_accept (int, struct sockaddr *__restrict addr, socklen_t *__restrict addrlen)
	C API.
int	GD_bind (int, const struct sockaddr *, socklen_t)
	C API.
int	GD_connect (int, const struct sockaddr *, socklen_t)
	C API.
int	GD_getpeername (int, struct sockaddr *__restrict, socklen_t *__restrict)
	C API.
int	GD_getsockname (int, struct sockaddr *__restrict, socklen_t *__restrict)
	C API.
int	GD_getsockopt (int, int, int, void *__restrict, socklen_t *__restrict)
	C API.
int	GD_listen (int, int)
	C API.
ssize_t	GD_recv (int, void *, size_t, int)
	C API.
ssize_t	GD_recvfrom (int, void *, size_t, int, struct sockaddr *__restrict, socklen_t *__restrict)
	C API.
ssize_t	GD_recvmsg (int, struct msghdr *, int)
	C API.
ssize_t	GD_send (int, const void *, size_t, int)
	C API.
ssize_t	GD_sendmsg (int, const struct msghdr *, int)
	C API.
ssize_t	GD_sendto (int, const void *, size_t, int, const struct sockaddr *, socklen_t)
	C API.
int	GD_setsockopt (int, int, int, const void *, socklen_t)
	C API.
int	GD_shutdown (int, int)
	C API.
int	GD_sockatmark (int)
	C API.
int	GD_socket (int, int, int)
	C API.
int	GD_socketpair (int, int, int, int *)
	C API.
int	GD_ioctlsocket (int, long, unsigned long *)
	C API.
int	GD_gethostname (char *name, size_t len)
	C API.
int	GD_select (int, fd_set *, fd_set *, fd_set *, struct timeval *)
	C API.
int	GD_UNISTD_fstat (int fd, struct stat *buf)
	File statistics. More...
int	GD_UNISTD_lstat (const char *path, struct stat *buf)
	File statistics. More...
ssize_t	GD_readv (int, const struct iovec *, int)
	C API.
ssize_t	GD_writev (int, const struct iovec *, int)
	C API.
int	GD_UNISTD_open (const char *path, int flags,...)
	C API.
int	GD_UNISTD_close (int fd)
	C API.
ssize_t	GD_UNISTD_read (int fd, void *buffer, size_t nbytes)
	C API.
ssize_t	GD_UNISTD_write (int fd, const void *buffer, size_t nbytes)
	C API.
off_t	GD_UNISTD_lseek (int fd, off_t offset, int whence)
	C API.
int	GD_UNISTD_ftruncate (int fd, off_t length)
	C API.
int	GD_UNISTD_truncate (const char *path, off_t length)
	C API.
int	GD_UNISTD_fdatasync (int fd)
	C API.
int	GD_UNISTD_fsync (int fd)
	C API.
int	GD_UNISTD_fchown (int fd, uid_t owner, gid_t group)
	C API.
int	GD_UNISTD_chown (const char *path, uid_t owner, gid_t group)
	C API.
int	GD_UNISTD_lchown (const char *path, uid_t owner, gid_t group)
	C API.
int	GD_UNISTD_chroot (const char *path)
	C API.
int	GD_UNISTD_fchdir (int fd)
	C API.
int	GD_UNISTD_chdir (const char *path)
	C API.
char *	GD_UNISTD_getcwd (char *buf, size_t size)
	C API.
int	GD_UNISTD_rmdir (const char *path)
	C API.
int	GD_UNISTD_access (const char *path, int mode)
	C API.
long int	GD_UNISTD_fpathconf (int fd, int name)
	C API.
long int	GD_UNISTD_pathconf (const char *path, int name)
	C API.
int	GD_UNISTD_lockf (int fd, int function, off_t size)
	C API.
char *	GD_UNISTD_ttyname (int fd)
	C API.
int	GD_UNISTD_ttyname_r (int fd, char *name, size_t namesize)
	C API.
int	GD_UNISTD_pipe (int fds[2])
	C API.
ssize_t	GD_UNISTD_pread (int fd, void *buffer, size_t nbyte, off_t offset)
	C API.
ssize_t	GD_UNISTD_pwrite (int fd, const void *buffer, size_t nbyte, off_t offset)
	C API.
ssize_t	GD_UNISTD_writev (int fd, const struct iovec *iov, int iovcnt)
	C API.
ssize_t	GD_UNISTD_readv (int fd, const struct iovec *iov, int iovcnt)
	C API.
int	GD_UNISTD_dup (int oldd)
	C API.
int	GD_UNISTD_dup2 (int oldd, int newd)
	C API.
int	GD_UNISTD_symlink (const char *file_path, const char *symlink_path)
	C API.
int	GD_UNISTD_readlink (const char *path, char *buffer, size_t nbyte)
	C API.
int	GD_UNISTD_link (const char *file_path, const char *link_path)
	C API.
int	GD_UNISTD_unlink (const char *path)
	C API.
void *	GD_UNISTD_mmap (void *addr, size_t length, int prot, int flags, int fd, off_t offset)
	C API.
int	GD_UNISTD_munmap (void *addr, size_t length)
	C API.
int	GD_UNISTD_msync (void *addr, size_t length, int flags)
	C API.
int	GD_UNISTD_fchmod (int fildes, mode_t mode)
	C API.
int	GD_UNISTD_fstatfs (int fd, struct statfs *buf)
	C API. More...
off64_t	GD_UNISTD_lseek64 (int fd, off64_t offset, int whence)
	C API.
ssize_t	GD_UNISTD_pwrite64 (int fd, const void *buffer, size_t nbyte, off64_t offset)
	C API.
int	GD_stat64 (const char *path, struct stat64 *buf)
	File statistics. More...
int	GD_UNISTD_lstat64 (const char *path, struct stat64 *buf)
	File statistics. More...
int	GD_UNISTD_fstat64 (int fd, struct stat64 *buf)
	File statistics. More...
GD_FILE *	GD_fopen (const char *filename, const char *mode)
	Open a file that is in the secure store, for reading or writing. More...
int	GD_fclose (GD_FILE *filePointer)
	Close a file that was previously opened. More...
size_t	GD_fread (void *ptr, size_t size, size_t count, GD_FILE *filePointer)
	Read from a file that is in the secure store, previously opened in read mode with GD_fopen. More...
size_t	GD_fwrite (const void *ptr, size_t size, size_t count, GD_FILE *filePointer)
	Write to a file that is in the secure store, previously opened in write mode with GD_fopen. More...
int	GD_remove (const char *filename)
	Delete a file. More...
long int	GD_ftell (GD_FILE *filePointer)
	Get the current position of the file pointer. More...
off_t	GD_ftello (GD_FILE *filePointer)
	Get the current position of the file pointer. More...
int	GD_fseek (GD_FILE *filePointer, long int offset, int origin)
	Set the position of the file pointer. More...
int	GD_fseeko (GD_FILE *filePointer, off_t offset, int origin)
	Set the position of the file pointer. More...
int	GD_fscanf (GD_FILE *filePointer, const char *format,...)
	Read formatted data from stream. More...
int	GD_vfscanf (GD_FILE *filePointer, const char *format, va_list args)
	Read formatted data from stream into variable argument list. More...
int	GD_feof (GD_FILE *filePointer)
	Test if the file pointer is at the end of the file. More...
char *	GD_tmpnam (char *str)
	Generate a unique file name. More...
int	GD_truncate (const char *filename, off_t length)
	Truncate a file that is in the secure store. More...
int	GD_ftruncate (GD_FILE *filePointer, off_t length)
	Truncate a file that is in the secure store. More...
GD_FILE *	GD_freopen (const char *filename, const char *mode, GD_FILE *filePointer)
	Reopen stream with different file or mode. More...
int	GD_fgetpos (GD_FILE *filePointer, fpos_t *pos)
	Get current position in stream. More...
int	GD_fsetpos (GD_FILE *filePointer, const fpos_t *pos)
	Set position indicator of stream. More...
void	GD_rewind (GD_FILE *filePointer)
	Set position of stream to the beginning. More...
int	GD_fgetc (GD_FILE *filePointer)
	Get character from stream. More...
char *	GD_fgets (char *buf, int count, GD_FILE *filePointer)
	Get string from stream. More...
int	GD_fputc (int character, GD_FILE *filePointer)
	Write character to stream. More...
int	GD_fputs (const char *buf, GD_FILE *filePointer)
	Write string to stream. More...
int	GD_fprintf (GD_FILE *filePointer, const char *format,...)
	Write formatted data to stream. More...
int	GD_vfprintf (GD_FILE *filePointer, const char *format, va_list args)
	Write formatted data from variable argument list to stream. More...
int	GD_rename (const char *oldname, const char *newname)
	Rename file. More...
int	GD_setvbuf (GD_FILE *filePointer, char *buf, int mode, size_t size)
	Change stream buffering. More...
void	GD_setbuffer (GD_FILE *filePointer, char *buf, int size)
	Change stream buffering. More...
void	GD_setbuf (GD_FILE *filePointer, char *buf)
	Change stream buffering. More...
int	GD_fflush (GD_FILE *filePointer)
	Flush stream. More...
int	GD_fsync (GD_FILE *filePointer)
	Flush stream and synchronize. More...
void	GD_clearerr (GD_FILE *filePointer)
	Clear error indicators. More...
int	GD_ferror (GD_FILE *filePointer)
	Check error indicator. More...
int	GD_mkdir (const char *dirname, mode_t mode)
	Create a directory at the specified path. More...
GD_DIR *	GD_opendir (const char *dirname)
	Open a directory at specified path. More...
int	GD_closedir (GD_DIR *dirp)
	Close an already opened directory stream. More...
struct dirent *	GD_readdir (GD_DIR *dirp)
	Read next directory entry. More...
int	GD_readdir_r (GD_DIR *dirp, struct dirent *entry, struct dirent **result)
	Read next directory entry into a buffer. More...
void	GD_rewinddir (GD_DIR *dirp)
	Reset directory stream. More...
void	GD_seekdir (GD_DIR *dirp, long loc)
	Set the position of a directory stream. More...
long	GD_telldir (GD_DIR *dirp)
	Current location of a directory stream. More...
int	GD_stat (const char *path, struct stat *buf)
	File statistics. More...
int	GD_statdir (GD_DIR *dirp, const char *name, struct stat *buf)
	Obtain information about the directory or file associated with the named directory stream. More...
int	GD_getc (GD_FILE *filePointer)
	Get character from stream. More...
int	GD_ungetc (int character, GD_FILE *filePointer)
	Push character back onto stream. More...

Detailed Description

There is a C language programming interface for some BlackBerry Dynamics capabilities. It can be used by applications built with the Android Native Development Kit (NDK). Functions and other elements in the interface in general have the same names as the corresponding elements in the Standard C library or POSIX standard interface, but with a "GD_" or "GD_UNISTD_" prefix. For example, the BlackBerry Dynamics functions are GD_fopen() instead of fopen(), and GD_accept() instead of accept(). The interfaces are otherwise the same, with some exceptions.

To import the headers for the C API, download the BlackBerry Dynamics SDK for Android from developers.blackberry.com and extract the headers from the path /sdk/libs/handheld/libs/gd/inc/ within the downloaded zip.

See also

System Interfaces: Detailed Table of Contents on the opengroup.org website for links to specifications of the POSIX standard interface.

Typedef Documentation

nslookupCompletionCallback

typedef void(* nslookupCompletionCallback) (const char *jsonResponse)

Pass a reference to a method of this type as the callback parameter to the GD_nslookup() method.

The callback receives one parameter.

Parameters

jsonResponse

char * containing a JSON string representation of the results, or an empty string, or NULL. See GD_nslookup() for details.

nslookupCompletionCallbackEx

typedef void(* nslookupCompletionCallbackEx) (const char *jsonResponse, const void *data)

Pass a reference to a method of this type as the callback parameter to the GD_nslookupEx() method.

The callback receives two parameters.

Parameters

jsonResponse	char * containing a JSON string representation of the results, or an empty string, or NULL. See GD_nslookup() for details.
data	void * pointer to the extended data that was passed to the original method call.

GD_nslookup_type

typedef enum GD_nslookup_type_t GD_nslookup_type

Use these constants to specify the type of results required for a BlackBerry Dynamics name service lookup. The type parameter of the GD_nslookup() method always takes one of these values.

completionCallback

typedef void(* completionCallback) (const char *myIP)

Pass a reference to a method of this type as the callback parameter to the GD_myipaddress() method.

The callback receives one parameter.

Parameters

myIP	char * containing an IP address, or an empty string, or NULL. See GD_myipaddress() for details.

completionCallbackEx

typedef void(* completionCallbackEx) (const char *myIP, const void *data)

Pass a reference to a method of this type as the callback parameter to the GD_myipaddressEx() method.

The callback receives two parameters.

Parameters

myIP	char * containing an IP address, or an empty string, or NULL. See GD_myipaddress() for details.
data	void * pointer to the extended data that was passed to the original method call.

Enumeration Type Documentation

GD_nslookup_type_t

enum GD_nslookup_type_t

Use these constants to specify the type of results required for a BlackBerry Dynamics name service lookup. The type parameter of the GD_nslookup() method always takes one of these values.

Enumerator
GD_nslookup_CNAME	Specify a CNAME lookup.
GD_nslookup_ARECORD	Specify an A record lookup.

GD_ROUTE

enum GD_ROUTE

Use the constants in this enumeration to check the return value of GD_getRouteInfo.

Enumerator
GD_ROUTE_UNKNOWN	The connection information didn't include BlackBerry Dynamics routing information.
GD_ROUTE_INTERNET	The connection will be routed direct to the Internet.
GD_ROUTE_GOOD_PROXY	The connection will be routed via the BlackBerry Dynamics infrastructure.
GD_ROUTE_DENY	The connection will be denied via the BlackBerry Dynamics SDK.
GD_ROUTE_INTERNET_LISTED	The connection will be routed direct to the Internet per WhiteList.

Function Documentation

GD_nslookup()

void GD_nslookup	(	const char *	host,
		GD_nslookup_type	type,
		nslookupCompletionCallback	callback
	)

Call this method to execute a BlackBerry Dynamics name service lookup. The lookup can be for canonical name (CNAME) or address record (A record).

The lookup will be executed from an enterprise end point of the BlackBerry Dynamics deployment to which the application is connected. The end point could be a BlackBerry Proxy server located behind the enterprise firewall or in its perimeter network (also known as DMZ, demilitarized zone, and screened subnet). Details for enterprise application servers could be in scope of the lookup, depending on the network configuration at the enterprise.

The lookup is asynchronous. When the lookup completes, a completion callback will be invoked. The callback will be passed a char* pointer to memory containing the results represented as a JSON string, if the lookup was successful. If the specified host is not listed for client connection in the enterprise management console, then an empty string is passed to the callback instead. If an error occurred, then NULL is passed.

Parameters

host	char* pointer to memory containing the name to look up.
type	GD_nslookup_type specifying the type of result required, either CNAME or A record.
callback	function to execute when the lookup completes. The function receives one parameter as described above.

GD_nslookupEx()

void GD_nslookupEx	(	const char *	host,
		GD_nslookup_type	type,
		nslookupCompletionCallbackEx	callback,
		const void *	data
	)

Call this function to execute a BlackBerry Dynamics name service lookup and supply extended data to the results callback. This function does the same lookup as the GD_nslookup() function, see above.

The completion callback will receive extended data, which is passed as a parameter to this function.

Parameters

host	char* pointer to memory containing the name to look up.
type	GD_nslookup_type specifying the type of result required, either CNAME or A record.
callback	function to execute when the lookup completes. The function receives a response parameter, as described above under GD_nslookup(), and extended data, as passed in the data parameter, below.
data	void* pointer to the extended data for the callback.

GD_getFqdn()

char* GD_getFqdn

(

const char *

host

)

Call this function to retrieve a fully qualified domain name (FQDN) for a specified host server. An FQDN will be available after a successful socket connection has been made to the server.

The host specifier passed to this function must be the same as was used when the socket connection was set up. The returned value will be the FQDN to which the host specifier resolved at set-up time.

The returned value, if any, will be a pointer to memory that has been allocated from the heap using malloc. The caller must release the memory, by calling free.

Parameters

host	char* pointer to memory containing the specifier for the server.

Returns

char* pointer to allocated memory containing the FQDN, or NULL if an FQDN isn't available.

GD_myipaddress()

void GD_myipaddress	(	const char *	host,
		unsigned int	port,
		completionCallback	callback
	)

Call this function to retrieve the IP address of the BlackBerry Dynamics end point for a specified host.

Only hosts that are listed for client connection in the enterprise management console will have a BlackBerry Dynamics end point. The end point could be a BlackBerry Proxy server, or legacy Good Proxy server, for example.

Retrieval is asynchronous. When retrieval completes, a completion callback will be invoked.
The callback will be passed a char * pointing to a buffer containing the IP address if retrieval was successful. The callback must copy the contents of the buffer if the IP address is to be used later. The memory for the passed buffer will be released when the callback completes.
If the specified host isn't listed for client connection in the management console then an empty string is passed to the callback instead. If an error occurred then NULL is passed.

Parameters

host	char * containing the server address of the host.
port	unsigned int containing the port number of the host.
callback	Function to execute when the retrieval completes. The function receives one parameter as described above.

GD_myipaddressEx()

void GD_myipaddressEx	(	const char *	host,
		unsigned int	port,
		completionCallbackEx	callback,
		const void *	data
	)

Call this function to retrieve the IP address of the BlackBerry Dynamics end point for a specified host and supply extended data to the results callback. This method does the same retrieval as the GD_myipaddress() method, see above.

The completion callback will receive extended data, which is passed as a parameter to this method.

Parameters

host	char * containing the server address of the host.
port	unsigned int containing the port number of the host.
callback	Function to execute when the retrieval completes. The function receives a results parameter, as described above under GD_myipaddress(), and extended data, as passed in the data parameter, below.
data	void * pointer to the extended data for the callback.

GD_getRouteInfo()

enum GD_ROUTE GD_getRouteInfo

(

const struct sockaddr *

address

)

Call this function to check how a connection would be routed, either via the BlackBerry Dynamics infrastructure, direct to the Internet or Denied. The connection is specified by a socket address, sockaddr, structure that is passed as an input parameter. This route check compares the host name to the Connectivity Profile entries to determine routing.

The input socket address structure must have been obtained from the GD_getaddrinfo function.

Parameters

address

pointer to a sockaddr structure for the required connection.

Returns

GD_ROUTE constant for the result.

GD_UNISTD_fstat()

int GD_UNISTD_fstat	(	int	fd,
		struct stat *	buf
	)

This function returns information about the file at a specified path. Read, write or execute permission of the named file is not required, but all directories listed in the path name leading to the file must be searchable. GD_UNISTD_fstat() is identical to GD_stat(), except that the file to be stat-ed is specified by the file descriptor fd.

Parameters

fd	int file descriptor which specifies file to be stat-ed.
buf	struct stat* buffer in which to write the stat data.

Returns

int 0 on success, -1 on failure.

GD_UNISTD_lstat()

int GD_UNISTD_lstat	(	const char *	path,
		struct stat *	buf
	)

This function returns information about the file at a specified path. Read, write or execute permission of the named file is not required, but all directories listed in the path name leading to the file must be searchable. GD_UNISTD_lstat() is identical to GD_stat(), except that if path is a symbolic link, then the link itself is stat-ed, not the file that it refers to.

Parameters

path	const char* pointer to a C string containing the path to the file.
buf	struct stat* buffer in which to write the stat data.

Returns

int 0 on success, -1 on failure.

GD_UNISTD_fstatfs()

int GD_UNISTD_fstatfs	(	int	fd,
		struct statfs *	buf
	)

C API.

GD_stat64()

int GD_stat64	(	const char *	path,
		struct stat64 *	buf
	)

This is 64-bit version of stat. This function returns information about the file at a specified path. Read, write or execute permission of the named file is not required, but all directories listed in the path name leading to the file must be searchable.

Parameters

path	const char* pointer to a C string containing the path to the file.
buf	struct stat64* buffer in which to write the stat data.

Returns

int 0 on success, -1 on failure.

GD_UNISTD_lstat64()

int GD_UNISTD_lstat64	(	const char *	path,
		struct stat64 *	buf
	)

This is 64-bit version of lstat. This function returns information about the file at a specified path. Read, write or execute permission of the named file is not required, but all directories listed in the path name leading to the file must be searchable. GD_UNISTD_lstat() is identical to GD_stat(), except that if path is a symbolic link, then the link itself is stat-ed, not the file that it refers to.

Parameters

path	const char* pointer to a C string containing the path to the file.
buf	struct stat64* buffer in which to write the stat data.

Returns

int 0 on success, -1 on failure.

GD_UNISTD_fstat64()

int GD_UNISTD_fstat64	(	int	fd,
		struct stat64 *	buf
	)

This is 64-bit version of fstat. This function returns information about the file at a specified path. Read, write or execute permission of the named file is not required, but all directories listed in the path name leading to the file must be searchable. GD_UNISTD_fstat() is identical to GD_stat(), except that the file to be stat-ed is specified by the file descriptor fd.

Parameters

fd	int file descriptor which specifies file to be stat-ed.
buf	struct stat64* buffer in which to write the stat data.

Returns

int 0 on success, -1 on failure.

GD_fopen()

GD_FILE* GD_fopen	(	const char *	filename,
		const char *	mode
	)

Call this function to open a file in the secure store for reading or writing. Files in the secure store are encrypted on the device; this function provides access to decrypted data.

Parameters

filename	const char* pointer to a C string containing the path, within the secure store, that represents the file to be opened.
mode	const char* pointer to a C string of the mode. The values are analogous to the standard C call fopen and can be: write "w" read "r" append "a" Note that the "+" qualifier is supported for opening a file for both reading and writing. The "b" and "t" qualifiers aren't supported.

Returns

GD_FILE* object pointer (analogous to the FILE* file pointer returned from fopen) which can be used for subsequent file access, or NULL if the file could not be opened or created.

GD_fclose()

int GD_fclose

(

GD_FILE *

filePointer

)

Call this function to close a file that was previously opened by a call to GD_fopen.

Parameters

filePointer

GD_FILE* object which was returned by a previous call to GD_fopen. Note that this should always be called when file access is no longer required. It also forces a flush of any uncommitted write operation.

Returns

int 0 if successful, EOF otherwise

GD_fread()

size_t GD_fread	(	void *	ptr,
		size_t	size,
		size_t	count,
		GD_FILE *	filePointer
	)

Call this function to read a file in the secure store previously opened with GD_open in a read mode such as "r" or "w+".

Parameters

ptr	void* pointer to a buffer to receive the read data.
size	size_t size of the data block.
count	size_t number of data blocks.
filePointer	GD_FILE* a pointer to a valid GD_FILE* object.

(Note that the underlying library simply reads size * count bytes from the secure file system.)

Returns

size_t The total number of elements successfully read is returned. If this number differs from the count parameter, either a reading error occurred or the end-of-file was reached while reading. In both cases, the proper indicator is set, which can be checked with ferror and feof, respectively. If either size or count is zero, the function returns zero and both the stream state and the content pointed by ptr remain unchanged.
size_t is an unsigned integral type.

GD_fwrite()

size_t GD_fwrite	(	const void *	ptr,
		size_t	size,
		size_t	count,
		GD_FILE *	filePointer
	)

Call this function to read a file in the secure store previously opened with GD_open in a read mode such as "w" or "r+".

Parameters

ptr	void* pointer to a buffer containing the data to be written
size	size_t size of the data block.
count	size_t number of data blocks
filePointer	GD_FILE* a pointer to a valid GD_FILE* object

(Note that the underlying library simply writes size * count bytes to the encrypted file system.)

Returns

size_t The total number of elements successfully written is returned. If this number differs from the count parameter, a writing error prevented the function from completing. In this case, the error indicator (ferror) will be set for the stream. If either size or count is zero, the function returns zero and the error indicator remains unchanged. size_t is an unsigned integral type.

GD_remove()

int GD_remove

(

const char *

filename

)

Call this function to delete a file by path.

Parameters

filename

const char* the path of the field to be deleted.

Returns

int 0 if successful, -1 otherwise.

GD_ftell()

long int GD_ftell

(

GD_FILE *

filePointer

)

Call this function obtain the current file pointer position.

Parameters

filePointer

GD_FILE* object which was returned by a previous call to GD_fopen.

Returns

long int the position of the file pointer or -1 if an error has occurred.

GD_ftello()

off_t GD_ftello

(

GD_FILE *

filePointer

)

Call this function obtain the current file pointer position.

Parameters

filePointer

GD_FILE* object which was returned by a previous call to GD_fopen.

Returns

off_t the position of the file pointer or -1 if an error has occurred.

GD_fseek()

int GD_fseek	(	GD_FILE *	filePointer,
		long int	offset,
		int	origin
	)

Call this function to set the file pointer position.

Parameters

filePointer	GD_FILE* object which was returned by a previous call to GD_fopen.
offset	long int offset relative to the origin parameter
origin	int one of SEEK_SET, SEEK_CUR, SEEK_END

Returns

int 0 for success or -1 for failure

GD_fseeko()

int GD_fseeko	(	GD_FILE *	filePointer,
		off_t	offset,
		int	origin
	)

Call this function to set the file pointer position.

Parameters

filePointer	GD_FILE* object which was returned by a previous call to GD_fopen.
offset	off_t offset relative to the origin parameter
origin	int one of SEEK_SET, SEEK_CUR, SEEK_END

Returns

int 0 for success or -1 for failure

GD_fscanf()

int GD_fscanf	(	GD_FILE *	filePointer,
		const char *	format,
			...
	)

Reads data from the stream and stores them according to the parameter format into the locations pointed by the additional arguments. The additional arguments should point to already allocated objects of the type specified by their corresponding format specifier (subsequences beginning with %) within the format string.

Parameters

filePointer	Pointer to a GD_FILE object that identifies an input stream to read data from.
format	C string that contains a sequence of characters that control how characters extracted from the stream are treated.

Returns

int On success, the function returns the number of items of the argument list successfully filled. On error, the function returns EOF and sets the error indicator (ferror).

GD_vfscanf()

int GD_vfscanf	(	GD_FILE *	filePointer,
		const char *	format,
		va_list	args
	)

Reads data from the stream and stores them according to parameter format into the locations pointed to by the elements in the variable argument list identified by args.

Internally, the function retrieves arguments from the list identified by arg as if va_arg was used on it, and thus the state of arg is likely to be altered by the call.

In any case, arg should have been initialized by va_start at some point before the call, and it is expected to be released by va_end at some point after the call.

Parameters

filePointer	Pointer to a GD_FILE object that identifies an input stream.
format	C string that contains a format string that follows the same specification as scanf (see scanf for details).
args	A value identifying a variable arguments list initialized with va_start. va_list is a special type defined in <stdarg.h> file.

Returns

int On success, the function returns the number of items of the argument list successfully filled. On error, the function returns EOF and sets the error indicator (ferror).

GD_feof()

int GD_feof

(

GD_FILE *

filePointer

)

Call this function to check if the file pointer is at the end of the file.

Parameters

filePointer

GD_FILE* object which was returned by a previous call to GD_fopen.

Returns

int non-zero if the end of file indicator is set, otherwise 0

GD_tmpnam()

char* GD_tmpnam

(

char *

str

)

Call this function to check or generate a unique file name

Parameters

str	char* an array of bytes of at least L_tmpnam length to contain the proposed file name. If this argument is NULL then an internal static array is used.

Returns

char* a pointer to a unique filename. If the str argument is not NULL then the pointer will refer to this array otherwise it will point to an internal static array. If the function cannot create a unique filename then NULL is returned.

GD_truncate()

int GD_truncate	(	const char *	filename,
		off_t	length
	)

Call this function to truncate a file in the secure store to a specified length. If file was previously larger than the length specified, the file will be truncated and the extra data lost. If the file was previously smaller than the length specified, the file will be extended and padded with null bytes ('\0').

Parameters

filename	const char* pointer to a C string containing the path, within the secure store, that represents the file to be truncated.
length	off_t in bytes of the file once truncated.

Returns

int 0 for success or -1 for failure

GD_ftruncate()

int GD_ftruncate	(	GD_FILE *	filePointer,
		off_t	length
	)

Call this function to truncate a file in the secure store to a specified length. If file was previously larger than the length specified, the file will be truncated and the extra data lost. If the file was previously smaller than the length specified, the file will be extended and padded with null bytes ('\0').

Parameters

filePointer	GD_FILE* object which was returned by a previous call to GD_fopen.
length	off_t in bytes of the file once truncated.

Returns

int 0 for success or -1 for failure

GD_freopen()

GD_FILE* GD_freopen	(	const char *	filename,
		const char *	mode,
		GD_FILE *	filePointer
	)

Reuses stream to either open the file specified by filename or to change its access mode. If a new filename is specified, the function first attempts to close any file already associated with filePointer (third parameter) and disassociates it. Then, independently of whether that filePointer was successfuly closed or not, freopen opens the file specified by filename and associates it with the filePointer just as fopen would do using the specified mode. If filename is a null pointer, the function attempts to change the mode of the filePointer. The error indicator and eof indicator are automatically cleared (as if clearerr was called).

Parameters

filename	const char* C string containing the name of the file to be opened.
mode	const char* pointer to a C string of the mode. The values are analogous to the standard C call fopen and can be: write "w" read "r" append "a" Note that the "+" qualifier is supported for opening a file for both reading and writing. The "b" and "t" qualifiers aren't supported.
filePointer	GD_FILE* object which was returned by a previous call to GD_fopen.

Returns

GD_FILE* If the file is successfully reopened, the function returns the pointer passed as parameter filePointer, which can be used to identify the reopened stream. Otherwise, a null pointer is returned.

GD_fgetpos()

int GD_fgetpos	(	GD_FILE *	filePointer,
		fpos_t *	pos
	)

Retrieves the current position in the stream. The function fills the fpost_t object pointed by pos with the information needed from the filePointer's position indicator to restore the stream to its current position (and multibyte state, if wide-oriented) with a call to fsetpos. The ftell function can be used to retrieve the current position in the stream as an integer value.

Parameters

filePointer	GD_FILE* object which was returned by a previous call to GD_fopen.
pos	fpos_t Pointer to a fpos_t object.

Returns

int On success, the function returns zero. In case of error, errno is set to a platform-specific positive value and the function returns a non-zero value.

GD_fsetpos()

int GD_fsetpos	(	GD_FILE *	filePointer,
		const fpos_t *	pos
	)

Restores the current position in the stream to pos. The internal file position indicator associated with stream is set to the position represented by pos, which is a pointer to an fpos_t object whose value shall have been previously obtained by a call to fgetpos. The end-of-file internal indicator of the stream is cleared after a successful call to this function, and all effects from previous calls to ungetc on this stream are dropped. On streams open for update (read+write), a call to fsetpos allows to switch between reading and writing.

Parameters

filePointer	GD_FILE* object which was returned by a previous call to GD_fopen.
pos	fpos_t Pointer to a fpos_t object containing a position previously obtained with fgetpos.

Returns

int On success, the function returns zero. On failure, a non-zero value is returned and errno is set to a system-specific positive value.

GD_rewind()

void GD_rewind

(

GD_FILE *

filePointer

)

Sets the position indicator associated with stream to the beginning of the file. The end-of-file and error internal indicators associated to the stream are cleared after a successful call to this function, and all effects from previous calls to ungetc on this stream are dropped.

Parameters

filePointer

GD_FILE* object which was returned by a previous call to GD_fopen.

GD_fgetc()

int GD_fgetc

(

GD_FILE *

filePointer

)

Returns the character currently pointed by the internal file position indicator of the specified stream. The internal file position indicator is then advanced to the next character. If the stream is at the end-of-file when called, the function returns EOF and sets the end-of-file indicator for the stream (feof). If a read error occurs, the function returns EOF and sets the error indicator for the stream (ferror).

Parameters

filePointer

GD_FILE* object which was returned by a previous call to GD_fopen.

Returns

int On success, the character read is returned (promoted to an int value). The return type is int to accommodate for the special value EOF, which indicates failure: If the position indicator was at the end-of-file, the function returns EOF and sets the eof indicator (feof) of stream. If some other reading error happens, the function also returns EOF, but sets its error indicator (ferror) instead.

GD_fgets()

char* GD_fgets	(	char *	buf,
		int	count,
		GD_FILE *	filePointer
	)

Reads characters from stream and stores them as a C string into str until (num-1) characters have been read or either a newline or the end-of-file is reached, whichever happens first. A newline character makes fgets stop reading, but it is considered a valid character by the function and included in the string copied to str. A terminating null character is automatically appended after the characters copied to str.

Parameters

buf	char* Pointer to an array of chars where the string read is copied.
count	int Maximum number of characters to be copied into str (including the terminating null-character).
filePointer	GD_FILE* object which was returned by a previous call to GD_fopen.

Returns

char* On success, the function returns str. If the end-of-file is encountered while attempting to read a character, the eof indicator is set (feof). If this happens before any characters could be read, the pointer returned is a null pointer (and the contents of str remain unchanged). If a read error occurs, the error indicator (ferror) is set and a null pointer is also returned (but the contents pointed by str may have changed).

GD_fputc()

int GD_fputc	(	int	character,
		GD_FILE *	filePointer
	)

Writes a character to the stream and advances the position indicator. The character is written at the position indicated by the internal position indicator of the stream, which is then automatically advanced by one.

Parameters

character	int The int promotion of the character to be written. The value is internally converted to an unsigned char when written.
filePointer	GD_FILE* object which was returned by a previous call to GD_fopen.

Returns

int On success, the character written is returned. If a writing error occurs, EOF is returned and the error indicator (ferror) is set.

GD_fputs()

int GD_fputs	(	const char *	buf,
		GD_FILE *	filePointer
	)

Writes the C string pointed by str to the stream. The function begins copying from the address specified (str) until it reaches the terminating null character ('\0'). This terminating null-character is not copied to the stream.

Parameters

buf	const char* C string with the content to be written to stream.
filePointer	GD_FILE* object which was returned by a previous call to GD_fopen.

Returns

int On success, a non-negative value is returned. On error, the function returns EOF and sets the error indicator (ferror).

GD_fprintf()

int GD_fprintf	(	GD_FILE *	filePointer,
		const char *	format,
			...
	)

Writes the C string pointed by format to the stream. If format includes format specifiers (subsequences beginning with %), the additional arguments following format are formatted and inserted in the resulting string replacing their respective specifiers.

Parameters

filePointer	Pointer to a GD_FILE object that identifies an output stream.
format	C string that contains the text to be written to the stream. It can optionally contain embedded format specifiers that are replaced by the values specified in subsequent additional arguments and formatted as requested.

Returns

int On success, the total number of characters written is returned. On error, the function returns EOF and sets the error indicator (ferror).

GD_vfprintf()

int GD_vfprintf	(	GD_FILE *	filePointer,
		const char *	format,
		va_list	args
	)

Writes the C string pointed by format to the stream, replacing any format specifier in the same way as printf does, but using the elements in the variable argument list identified by arg instead of additional function arguments.

Internally, the function retrieves arguments from the list identified by arg as if va_arg was used on it, and thus the state of arg is likely altered by the call.

In any case, arg should have been initialized by va_start at some point before the call, and it is expected to be released by va_end at some point after the call.

Parameters

filePointer	Pointer to a GD_FILE object that identifies an output stream.
format	C string that contains a format string that follows the same specifications as format in printf (see printf for details).
args	A value identifying a variable arguments list initialized with va_start. va_list is a special type defined in the <stdarg.h> file.

Returns

int On success, the total number of characters written is returned. On error, the function returns EOF and sets the error indicator (ferror).

GD_rename()

int GD_rename	(	const char *	oldname,
		const char *	newname
	)

Changes the name of the file or directory specified by oldname to newname. This is an operation performed directly on a file; No streams are involved in the operation. If oldname and newname specify different paths and this is supported by the system, the file is moved to the new location. If newname names an existing file, the function may either fail or override the existing file, depending on the specific system and library implementation.

Parameters

oldname	const char* C string containing the name of an existing file to be renamed and/or moved.
newname	const char* C string containing the new name for the file.

Returns

int If the file is successfully renamed, a zero value is returned. On failure, a nonzero value is returned.

GD_setvbuf()

int GD_setvbuf	(	GD_FILE *	filePointer,
		char *	buf,
		int	mode,
		size_t	size
	)

Specifies a buffer for stream. The function allows to specify the mode and size of the buffer (in bytes). If buffer is a null pointer, the function automatically allocates a buffer (using size as a hint on the size to use). Otherwise, the array pointed by buffer may be used as a buffer of size bytes. This function should be called once the stream has been associated with an open file, but before any input or output operation is performed with it. A stream buffer is a block of data that acts as intermediary between the i/o operations and the physical file associated to the stream: For output buffers, data is output to the buffer until its maximum capacity is reached, then it is flushed (i.e.: all data is sent to the physical file at once and the buffer cleared). Likewise, input buffers are filled from the physical file, from which data is sent to the operations until exhausted, at which point new data is acquired from the file to fill the buffer again. Stream buffers can be explicitly flushed by calling fflush. They are also automatically flushed by fclose and freopen, or when the program terminates normally.

Parameters

filePointer	GD_FILE* object which was returned by a previous call to GD_fopen.
buf	char* User allocated buffer. Shall be at least size bytes long. If set to a null pointer, the function automatically allocates a buffer.
mode	int Specifies a mode for file buffering.(_IOFBF, _IOLBF and _IONBF)
size	size_t Buffer size, in bytes. If the buffer argument is a null pointer, this value may determine the size automatically allocated by the function for the buffer.

Returns

int If the buffer is correctly assigned to the file, a zero value is returned. Otherwise, a non-zero value is returned; This may be due to an invalid mode parameter or to some other error allocating or assigning the buffer.

GD_setbuffer()

void GD_setbuffer	(	GD_FILE *	filePointer,
		char *	buf,
		int	size
	)

Specifies a buffer for stream. The function allows to specify the size of the buffer (in bytes). If buffer is a null pointer, the function automatically allocates a buffer (using size as a hint on the size to use). Otherwise, the array pointed by buffer may be used as a buffer of size bytes. This function should be called once the stream has been associated with an open file, but before any input or output operation is performed with it. A stream buffer is a block of data that acts as intermediary between the i/o operations and the physical file associated to the stream: For output buffers, data is output to the buffer until its maximum capacity is reached, then it is flushed (i.e.: all data is sent to the physical file at once and the buffer cleared). Likewise, input buffers are filled from the physical file, from which data is sent to the operations until exhausted, at which point new data is acquired from the file to fill the buffer again. Stream buffers can be explicitly flushed by calling fflush. They are also automatically flushed by fclose and freopen, or when the program terminates normally.

Except for the lack of a return value, the GD_setbuffer function is exactly equivalent to the call setvbuf(stream, buf, buf ? _IOFBF : _IONBF, size);

Parameters

filePointer	GD_FILE* object which was returned by a previous call to GD_fopen.
buf	char* User allocated buffer. Shall be at least size bytes long. If set to a null pointer, the function automatically allocates a buffer.
size	int Buffer size, in bytes. If the buffer argument is a null pointer, this value may determine the size automatically allocated by the function for the buffer.

GD_setbuf()

void GD_setbuf	(	GD_FILE *	filePointer,
		char *	buf
	)

Specifies a buffer for stream. If buffer is a null pointer, the function automatically allocates a buffer. Otherwise, the array pointed by buffer may be used as a buffer of size BUFSIZ. This function should be called once the stream has been associated with an open file, but before any input or output operation is performed with it. A stream buffer is a block of data that acts as intermediary between the i/o operations and the physical file associated to the stream: For output buffers, data is output to the buffer until its maximum capacity is reached, then it is flushed (i.e.: all data is sent to the physical file at once and the buffer cleared). Likewise, input buffers are filled from the physical file, from which data is sent to the operations until exhausted, at which point new data is acquired from the file to fill the buffer again. Stream buffers can be explicitly flushed by calling fflush. They are also automatically flushed by fclose and freopen, or when the program terminates normally.

Except for the lack of a return value, the GD_setbuf() function is exactly equivalent to the call GD_setvbuf(filePointer, buf, buf ? _IOFBF : _IONBF, BUFSIZ);

Parameters

filePointer	GD_FILE* object which was returned by a previous call to GD_fopen.
buf	char* User allocated buffer. Shall be BUFSIZ bytes long. If set to a null pointer, the function automatically allocates a buffer.

GD_fflush()

int GD_fflush

(

GD_FILE *

filePointer

)

If the given stream was open for writing (or if it was open for updating and the last i/o operation was an output operation) any unwritten data in its output buffer is written to the file.

Note

Note that this will not synchronize any read streams open on the write stream. To additionally synchronize with open read streams on the same file, please use GD_fsync() instead.

The stream remains open after this call. When a file is closed, either because of a call to fclose or because the program terminates, all the buffers associated with it are automatically flushed.

Parameters

filePointer

GD_FILE* object which was returned by a previous call to GD_fopen.

Returns

int A zero value indicates success. If an error occurs, EOF is returned and the error indicator is set (see ferror).

GD_fsync()

int GD_fsync

(

GD_FILE *

filePointer

)

If the given stream was open for writing (or if it was open for updating and the last i/o operation was an output operation) any unwritten data in its output buffer is written to the file.

Note

This will also synchronize any read streams open on the write stream and is therefore less performant than GD_fflush(), which may be more appropriate if such synchronization is not required.

The stream remains open after this call. When a file is closed, either because of a call to fclose or because the program terminates, all the buffers associated with it are automatically flushed.

Parameters

filePointer

GD_FILE* object which was returned by a previous call to GD_fopen.

Returns

int A zero value indicates success. If an error occurs, EOF is returned and the error indicator is set (see ferror).

GD_clearerr()

void GD_clearerr

(

GD_FILE *

filePointer

)

Resets both the error and the eof indicators of the stream. When a i/o function fails either because of an error or because the end of the file has been reached, one of these internal indicators may be set for the stream. The state of these indicators is cleared by a call to this function, or by a call to any of: rewind, fseek, fsetpos and freopen.

Parameters

filePointer

GD_FILE* object which was returned by a previous call to GD_fopen.

GD_ferror()

int GD_ferror

(

GD_FILE *

filePointer

)

Checks if the error indicator associated with stream is set, returning a value different from zero if it is. This indicator is generally set by a previous operation on the stream that failed, and is cleared by a call to clearerr, rewind or freopen.

Parameters

filePointer

GD_FILE* object which was returned by a previous call to GD_fopen.

Returns

int A non-zero value is returned in the case that the error indicator associated with the stream is set. Otherwise, zero is returned.

GD_mkdir()

int GD_mkdir	(	const char *	dirname,
		mode_t	mode
	)

The directory path is created at the path specified. The mode parameter is not used and exists here for compatability.

Parameters

dirname	const char* directory path to be created.
mode	mode not used (all directories are rwx)

Returns

int

GD_opendir()

GD_DIR* GD_opendir

(

const char *

dirname

)

The opendir() function opens the directory named by dirname, associates a directory stream with it, and returns a pointer to be used to identify the directory stream in subsequent operations. The pointer NULL is returned if dirname cannot be accessed or if it cannot malloc(3) enough memory to hold the whole thing.

Parameters

dirname

char* string of the path to the directory.

Returns

GD_DIR* object which represents the directory, NULL is returned in the case of an error.

GD_closedir()

int GD_closedir

(

GD_DIR *

dirp

)

The closedir() function closes the named directory stream and frees the structure associated with the dirp pointer, returning 0 on success. On failure, -1 is returned and the global variable errno is set to indicate the error.

Parameters

dirp	GD_DIR* directory stream to close

Returns

int 0 on success, -1 on failure

GD_readdir()

struct dirent* GD_readdir

(

GD_DIR *

dirp

)

This function returns a pointer to the next directory entry. It returns NULL upon reaching the end of the directory or detecting an invalid seekdir() operation.

Parameters

dirp	dirp directory stream to read from.

Returns

struct dirent* pointer to a directory entry or NULL if the end has been reached.

GD_readdir_r()

int GD_readdir_r	(	GD_DIR *	dirp,
		struct dirent *	entry,
		struct dirent **	result
	)

This function provides the same functionality as GD_readdir(), but the caller must provide a directory entry buffer to store the results in.

If the read succeeds, result is pointed at the entry; upon reaching the end of the directory, result is set to NULL. readdir_r() returns 0 on success or an error number to indicate failure.

Parameters

dirp	GD_DIR* directory stream to use.
entry	struct dirent* caller provided buffer to store the directory entry.
result	struct dirent** on sucess result is pointed to entry.

Returns

int 0 on success, -1 on failure.

GD_rewinddir()

void GD_rewinddir

(

GD_DIR *

dirp

)

This function resets the position of the named directory stream to the beginning of the directory.

Parameters

dirp	GD_DIR* directory stream to use.

GD_seekdir()

void GD_seekdir	(	GD_DIR *	dirp,
		long	loc
	)

This function sets the position of the next readdir() operation on the directory stream. The new position reverts to the one associated with the directory stream when the telldir() operation was performed.

Parameters

dirp	GD_DIR* directory stream to use.
loc	long position to seek to.

GD_telldir()

long GD_telldir

(

GD_DIR *

dirp

)

This function returns the current location associated with the named directory stream. Values returned by this function are good only for the lifetime of the DIR pointer (e.g., dirp) from which they are derived. If the directory is closed and then reopened, prior values returned by a previous call will no longer be valid.

Parameters

dirp	GD_DIR* directory stream to use.

Returns

long current location in the stream.

GD_stat()

int GD_stat	(	const char *	path,
		struct stat *	buf
	)

This function returns information about the file at a specified path. Read, write or execute permission of the named file is not required, but all directories listed in the path name leading to the file must be searchable.

Parameters

path	const char* pointer to a C string containing the path to the file.
buf	struct stat* buffer in which to write the stat data.

Returns

int 0 on success, -1 on failure.

GD_statdir()

int GD_statdir	(	GD_DIR *	dirp,
		const char *	name,
		struct stat *	buf
	)

Parameters

dirp	GD_DIR* directory stream to use.
name	const char* pointer to a C string containing the name to the file or directory.
buf	struct stat* buffer in which to write the stat data.

Returns

int 0 on success, -1 on failure.

GD_getc()

int GD_getc

(

GD_FILE *

filePointer

)

Returns the character currently pointed by the internal file position indicator of the specified stream. The internal file position indicator is then advanced to the next character. If the stream is at the end-of-file when called, the function returns EOF and sets the end-of-file indicator for the stream (feof). If a read error occurs, the function returns EOF and sets the error indicator for the stream (ferror).

Parameters

filePointer

GD_FILE* object which was returned by a previous call to GD_fopen.

Returns

int On success, the character read is returned (promoted to an int value). The return type is int to accommodate for the special value EOF, which indicates failure: If the position indicator was at the end-of-file, the function returns EOF and sets the eof indicator (feof) of stream. If some other reading error happens, the function also returns EOF, but sets its error indicator (ferror) instead.

GD_ungetc()

int GD_ungetc	(	int	character,
		GD_FILE *	filePointer
	)

This function pushes the character c (converted to an unsigned char) back onto the specified input stream. The pushed-back character will be returned (in reverse order) by subsequent reads on the stream. A successful intervening call to one of the file positioning functions using the same stream, will discard the pushed-back characters.

Returns

The GD_ungetc function returns the character pushed-back after the conversion, or EOF if the operation fails. If the value of the argument c character equals EOF, the operation will fail and the stream will remain unchanged.