1 /* Copyright (C) 2007-2008 The Android Open Source Project 2 ** 3 ** This software is licensed under the terms of the GNU General Public 4 ** License version 2, as published by the Free Software Foundation, and 5 ** may be copied, distributed, and modified under those terms. 6 ** 7 ** This program is distributed in the hope that it will be useful, 8 ** but WITHOUT ANY WARRANTY; without even the implied warranty of 9 ** MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 10 ** GNU General Public License for more details. 11 */ 12 13 #ifndef _ANDROID_UTILS_BUFPRINT_H 14 #define _ANDROID_UTILS_BUFPRINT_H 15 16 #include <stdarg.h> 17 18 /** FORMATTED BUFFER PRINTING 19 ** 20 ** bufprint() allows your to easily and safely append formatted string 21 ** content to a given bounded character buffer, in a way that is easier 22 ** to use than raw snprintf() 23 ** 24 ** 'buffer' is the start position in the buffer, 25 ** 'buffend' is the end of the buffer, the function assumes (buffer <= buffend) 26 ** 'format' is a standard printf-style format string, followed by any number 27 ** of formatting arguments 28 ** 29 ** the function returns the next position in the buffer if everything fits 30 ** in it. in case of overflow or formatting error, it will always return "buffend" 31 ** 32 ** this allows you to chain several calls to bufprint() and only check for 33 ** overflow at the end, for exemple: 34 ** 35 ** char buffer[1024]; 36 ** char* p = buffer; 37 ** char* end = p + sizeof(buffer); 38 ** 39 ** p = bufprint(p, end, "%s/%s", first, second); 40 ** p = bufprint(p, end, "/%s", third); 41 ** if (p >= end) ---> overflow 42 ** 43 ** as a convenience, the appended string is zero-terminated if there is no overflow. 44 ** (this means that even if p >= end, the content of "buffer" is zero-terminated) 45 ** 46 ** vbufprint() is a variant that accepts a va_list argument 47 **/ 48 49 extern char* vbufprint(char* buffer, char* buffend, const char* fmt, va_list args ); 50 extern char* bufprint (char* buffer, char* buffend, const char* fmt, ... ); 51 52 /** USEFUL DIRECTORY SUPPORT 53 ** 54 ** bufprint_add_dir() appends the application's directory to a given bounded buffer 55 ** 56 ** bufprint_config_path() appends the applications' user-specific configuration directory 57 ** to a bounded buffer. on Unix this is usually ~/.android, and something a bit more 58 ** complex on Windows 59 ** 60 ** bufprint_config_file() appends the name of a file or directory relative to the 61 ** user-specific configuration directory to a bounded buffer. this really is equivalent 62 ** to concat-ing the config path + path separator + 'suffix' 63 ** 64 ** bufprint_temp_dir() appends the temporary directory's path to a given bounded buffer 65 ** 66 ** bufprint_temp_file() appens the name of a file or directory relative to the 67 ** temporary directory. equivalent to concat-ing the temp path + path separator + 'suffix' 68 **/ 69 70 extern char* bufprint_app_dir (char* buffer, char* buffend); 71 extern char* bufprint_config_path(char* buffer, char* buffend); 72 extern char* bufprint_config_file(char* buffer, char* buffend, const char* suffix); 73 extern char* bufprint_temp_dir (char* buffer, char* buffend); 74 extern char* bufprint_temp_file (char* buffer, char* buffend, const char* suffix); 75 76 #endif /* _ANDROID_UTILS_BUFPRINT_H */ 77