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 #include "android/utils/compiler.h" 19 20 ANDROID_BEGIN_HEADER 21 22 /** FORMATTED BUFFER PRINTING 23 ** 24 ** bufprint() allows your to easily and safely append formatted string 25 ** content to a given bounded character buffer, in a way that is easier 26 ** to use than raw snprintf() 27 ** 28 ** 'buffer' is the start position in the buffer, 29 ** 'buffend' is the end of the buffer, the function assumes (buffer <= buffend) 30 ** 'format' is a standard printf-style format string, followed by any number 31 ** of formatting arguments 32 ** 33 ** the function returns the next position in the buffer if everything fits 34 ** in it. in case of overflow or formatting error, it will always return "buffend" 35 ** 36 ** this allows you to chain several calls to bufprint() and only check for 37 ** overflow at the end, for exemple: 38 ** 39 ** char buffer[1024]; 40 ** char* p = buffer; 41 ** char* end = p + sizeof(buffer); 42 ** 43 ** p = bufprint(p, end, "%s/%s", first, second); 44 ** p = bufprint(p, end, "/%s", third); 45 ** if (p >= end) ---> overflow 46 ** 47 ** as a convenience, the appended string is zero-terminated if there is no overflow. 48 ** (this means that even if p >= end, the content of "buffer" is zero-terminated) 49 ** 50 ** vbufprint() is a variant that accepts a va_list argument 51 **/ 52 53 extern char* vbufprint(char* buffer, char* buffend, const char* fmt, va_list args ); 54 extern char* bufprint (char* buffer, char* buffend, const char* fmt, ... ); 55 56 /** USEFUL DIRECTORY SUPPORT 57 ** 58 ** bufprint_add_dir() appends the application's directory to a given bounded buffer 59 ** 60 ** bufprint_config_path() appends the applications' user-specific configuration directory 61 ** to a bounded buffer. on Unix this is usually ~/.android, and something a bit more 62 ** complex on Windows 63 ** 64 ** bufprint_config_file() appends the name of a file or directory relative to the 65 ** user-specific configuration directory to a bounded buffer. this really is equivalent 66 ** to concat-ing the config path + path separator + 'suffix' 67 ** 68 ** bufprint_temp_dir() appends the temporary directory's path to a given bounded buffer 69 ** 70 ** bufprint_temp_file() appens the name of a file or directory relative to the 71 ** temporary directory. equivalent to concat-ing the temp path + path separator + 'suffix' 72 **/ 73 74 extern char* bufprint_app_dir (char* buffer, char* buffend); 75 extern char* bufprint_config_path(char* buffer, char* buffend); 76 extern char* bufprint_config_file(char* buffer, char* buffend, const char* suffix); 77 extern char* bufprint_temp_dir (char* buffer, char* buffend); 78 extern char* bufprint_temp_file (char* buffer, char* buffend, const char* suffix); 79 80 ANDROID_END_HEADER 81 82 #endif /* _ANDROID_UTILS_BUFPRINT_H */ 83
