diff options
author | Daniel Stenberg <daniel@haxx.se> | 2002-05-29 09:13:27 +0000 |
---|---|---|
committer | Daniel Stenberg <daniel@haxx.se> | 2002-05-29 09:13:27 +0000 |
commit | 93d720473a523cfd15491ef916fd3e6339bb4098 (patch) | |
tree | 4c293024f0b4a6ac544b638ae0a4b26f2b606649 /firmware | |
parent | 678c770396ffd332e74b53c711ac6e5b15d3eb17 (diff) | |
download | rockbox-93d720473a523cfd15491ef916fd3e6339bb4098.tar.gz rockbox-93d720473a523cfd15491ef916fd3e6339bb4098.zip |
modified button_get() according to its new prototype, added lots of blurb
for various file/dir functions, added the memory allocation functions
git-svn-id: svn://svn.rockbox.org/rockbox/trunk@783 a1c6a512-1295-4272-9138-f99709370657
Diffstat (limited to 'firmware')
-rw-r--r-- | firmware/API | 140 |
1 files changed, 124 insertions, 16 deletions
diff --git a/firmware/API b/firmware/API index 51e75c2a31..52f4876af2 100644 --- a/firmware/API +++ b/firmware/API @@ -56,28 +56,97 @@ Buttons return a different set of values. Note that the Recorder keypad has 10 keys, while the Player keypad only features 6. - button_init() init button functions - button_get() returns a bitmask for which keys were pressed + int button_get(bool block) + + Returns a bitmask for which keys were pressed. If 'block' is set TRUE it + won't return until a key is pressed. Files + (These functions are POSIX look-alikes) + #include <file.h> - open() - read() - lseek() - write() - close() - rename() - remove() + int open(const char *path, int oflag); + + The open() function establishes the connection between a file and a file + descriptor. It creates an open file descrip- tion that refers to a file + and a file descriptor that refers to that open file description. The file + descriptor is used by other I/O functions to refer to that file. + + int read(int fildes, void *buf, size_t nbyte); + + The read() function attempts to read nbyte bytes from the file associated + with the open file descriptor, fildes, into the buffer pointed to by buf. + + int lseek(int fildes, off_t offset, int whence); + + The lseek() function sets the file pointer associated with the open file + descriptor specified by fildes as follows: + + o If whence is SEEK_SET, the pointer is set to offset + bytes. + + o If whence is SEEK_CUR, the pointer is set to its + current location plus offset. + + o If whence is SEEK_END, the pointer is set to the size + of the file plus offset. + + int write(int fildes, const void *buf, size_t nbyte); + + NOT CURRENTLY SUPPORTED. + + write writes up to count bytes to the file referenced by the file + descriptor fd from the buffer starting at buf. + + int close(int fildes); + + The close() function will deallocate the file descriptor indicated by + fildes. To deallocate means to make the file descriptor available for + return by subsequent calls to open(2) or other functions that allocate + file descriptors. + + int rename(const char *old, const char *new); + + NOT CURRENTLY SUPPORTED. + + The rename() function changes the name of a file. The old argument points + to the pathname of the file to be renamed. The new argument points to the + new pathname of the file. + + int remove(const char *pathname); + + NOT CURRENTLY SUPPORTED. + + remove deletes a name from the filesystem. It calls unlink for files, + and rmdir for directories. + Directories #include <dir.h> - opendir() - readdir() - closedir() + DIR *opendir(const char *name); + + The opendir() function opens a directory stream corresponding to the + directory name, and returns a pointer to the directory stream. The + stream is positioned at the first entry in the directory. + + struct dirent *readdir(DIR *dir); + + The readdir() function returns a pointer to a dirent structure + representing the next directory entry in the directory stream pointed to + by dir. It returns NULL on reaching the end-of-file or if an error + occurred. + + Add a description of the struct here. + + int closedir(DIR *dir); + + The closedir() function closes the directory stream associated with dir. + The directory stream descriptor dir is not available after this call. + String/Memory @@ -89,17 +158,56 @@ String/Memory memset() ... +Memory allocation + + #include <dmalloc.h> + + void *malloc(size_t size); + + malloc() allocates size bytes and returns a pointer to the allocated + memory. The memory is not cleared. + + void free(void *ptr); + + free() frees the memory space pointed to by ptr, which must have been + returned by a previous call to malloc(), calloc() or realloc(). + Otherwise, or if free(ptr) has already been called before, undefined + behaviour occurs. + + void *realloc(void *ptr, size_t size); + + realloc() changes the size of the memory block pointed to by ptr to size + bytes. The contents will be unchanged to the minimum of the old and new + sizes; newly allocated memory will be uninitialized. If ptr is NULL, the + call is equivalent to malloc(size); if size is equal to zero, the call is + equivalent to free(ptr). Unless ptr is NULL, it must have been returned + by an earlier call to malloc(), calloc() or realloc(). + + void *calloc(size_t nmemb, size_t size); + + calloc() allocates memory for an array of nmemb elements of size bytes + each and returns a pointer to the allocated memory. The memory is set to + zero. + ID3 #include <id3.h> bool mp3info(mp3entry *entry, char *filename); - Return FALSE if successful. The given mp3entry is then filled in with - whatever id3 info it could find about the given file. + Return FALSE if successful. The given mp3entry is then filled in with + whatever id3 info it could find about the given file. Various #include <kernel.h> - sleep(ticks) - sleep a specified number of ticks, we currently have HZ ticks - per second + void sleep(ticks) + + Sleep a specified number of ticks, we have HZ ticks per second. + + void yield(void) + + Let another thread run. This should be used as soon as you have to "wait" + for something or similar, and also if you do anything that takes "a long + time". This function is the entire foundation that our "cooperative + multitasking" is based on. Use it. |