os.h revision 189251
1189251Ssam/* 2189251Ssam * wpa_supplicant/hostapd / OS specific functions 3189251Ssam * Copyright (c) 2005-2006, Jouni Malinen <j@w1.fi> 4189251Ssam * 5189251Ssam * This program is free software; you can redistribute it and/or modify 6189251Ssam * it under the terms of the GNU General Public License version 2 as 7189251Ssam * published by the Free Software Foundation. 8189251Ssam * 9189251Ssam * Alternatively, this software may be distributed under the terms of BSD 10189251Ssam * license. 11189251Ssam * 12189251Ssam * See README and COPYING for more details. 13189251Ssam */ 14189251Ssam 15189251Ssam#ifndef OS_H 16189251Ssam#define OS_H 17189251Ssam 18189251Ssamtypedef long os_time_t; 19189251Ssam 20189251Ssam/** 21189251Ssam * os_sleep - Sleep (sec, usec) 22189251Ssam * @sec: Number of seconds to sleep 23189251Ssam * @usec: Number of microseconds to sleep 24189251Ssam */ 25189251Ssamvoid os_sleep(os_time_t sec, os_time_t usec); 26189251Ssam 27189251Ssamstruct os_time { 28189251Ssam os_time_t sec; 29189251Ssam os_time_t usec; 30189251Ssam}; 31189251Ssam 32189251Ssam/** 33189251Ssam * os_get_time - Get current time (sec, usec) 34189251Ssam * @t: Pointer to buffer for the time 35189251Ssam * Returns: 0 on success, -1 on failure 36189251Ssam */ 37189251Ssamint os_get_time(struct os_time *t); 38189251Ssam 39189251Ssam 40189251Ssam/* Helper macros for handling struct os_time */ 41189251Ssam 42189251Ssam#define os_time_before(a, b) \ 43189251Ssam ((a)->sec < (b)->sec || \ 44189251Ssam ((a)->sec == (b)->sec && (a)->usec < (b)->usec)) 45189251Ssam 46189251Ssam#define os_time_sub(a, b, res) do { \ 47189251Ssam (res)->sec = (a)->sec - (b)->sec; \ 48189251Ssam (res)->usec = (a)->usec - (b)->usec; \ 49189251Ssam if ((res)->usec < 0) { \ 50189251Ssam (res)->sec--; \ 51189251Ssam (res)->usec += 1000000; \ 52189251Ssam } \ 53189251Ssam} while (0) 54189251Ssam 55189251Ssam/** 56189251Ssam * os_mktime - Convert broken-down time into seconds since 1970-01-01 57189251Ssam * @year: Four digit year 58189251Ssam * @month: Month (1 .. 12) 59189251Ssam * @day: Day of month (1 .. 31) 60189251Ssam * @hour: Hour (0 .. 23) 61189251Ssam * @min: Minute (0 .. 59) 62189251Ssam * @sec: Second (0 .. 60) 63189251Ssam * @t: Buffer for returning calendar time representation (seconds since 64189251Ssam * 1970-01-01 00:00:00) 65189251Ssam * Returns: 0 on success, -1 on failure 66189251Ssam * 67189251Ssam * Note: The result is in seconds from Epoch, i.e., in UTC, not in local time 68189251Ssam * which is used by POSIX mktime(). 69189251Ssam */ 70189251Ssamint os_mktime(int year, int month, int day, int hour, int min, int sec, 71189251Ssam os_time_t *t); 72189251Ssam 73189251Ssam 74189251Ssam/** 75189251Ssam * os_daemonize - Run in the background (detach from the controlling terminal) 76189251Ssam * @pid_file: File name to write the process ID to or %NULL to skip this 77189251Ssam * Returns: 0 on success, -1 on failure 78189251Ssam */ 79189251Ssamint os_daemonize(const char *pid_file); 80189251Ssam 81189251Ssam/** 82189251Ssam * os_daemonize_terminate - Stop running in the background (remove pid file) 83189251Ssam * @pid_file: File name to write the process ID to or %NULL to skip this 84189251Ssam */ 85189251Ssamvoid os_daemonize_terminate(const char *pid_file); 86189251Ssam 87189251Ssam/** 88189251Ssam * os_get_random - Get cryptographically strong pseudo random data 89189251Ssam * @buf: Buffer for pseudo random data 90189251Ssam * @len: Length of the buffer 91189251Ssam * Returns: 0 on success, -1 on failure 92189251Ssam */ 93189251Ssamint os_get_random(unsigned char *buf, size_t len); 94189251Ssam 95189251Ssam/** 96189251Ssam * os_random - Get pseudo random value (not necessarily very strong) 97189251Ssam * Returns: Pseudo random value 98189251Ssam */ 99189251Ssamunsigned long os_random(void); 100189251Ssam 101189251Ssam/** 102189251Ssam * os_rel2abs_path - Get an absolute path for a file 103189251Ssam * @rel_path: Relative path to a file 104189251Ssam * Returns: Absolute path for the file or %NULL on failure 105189251Ssam * 106189251Ssam * This function tries to convert a relative path of a file to an absolute path 107189251Ssam * in order for the file to be found even if current working directory has 108189251Ssam * changed. The returned value is allocated and caller is responsible for 109189251Ssam * freeing it. It is acceptable to just return the same path in an allocated 110189251Ssam * buffer, e.g., return strdup(rel_path). This function is only used to find 111189251Ssam * configuration files when os_daemonize() may have changed the current working 112189251Ssam * directory and relative path would be pointing to a different location. 113189251Ssam */ 114189251Ssamchar * os_rel2abs_path(const char *rel_path); 115189251Ssam 116189251Ssam/** 117189251Ssam * os_program_init - Program initialization (called at start) 118189251Ssam * Returns: 0 on success, -1 on failure 119189251Ssam * 120189251Ssam * This function is called when a programs starts. If there are any OS specific 121189251Ssam * processing that is needed, it can be placed here. It is also acceptable to 122189251Ssam * just return 0 if not special processing is needed. 123189251Ssam */ 124189251Ssamint os_program_init(void); 125189251Ssam 126189251Ssam/** 127189251Ssam * os_program_deinit - Program deinitialization (called just before exit) 128189251Ssam * 129189251Ssam * This function is called just before a program exists. If there are any OS 130189251Ssam * specific processing, e.g., freeing resourced allocated in os_program_init(), 131189251Ssam * it should be done here. It is also acceptable for this function to do 132189251Ssam * nothing. 133189251Ssam */ 134189251Ssamvoid os_program_deinit(void); 135189251Ssam 136189251Ssam/** 137189251Ssam * os_setenv - Set environment variable 138189251Ssam * @name: Name of the variable 139189251Ssam * @value: Value to set to the variable 140189251Ssam * @overwrite: Whether existing variable should be overwritten 141189251Ssam * Returns: 0 on success, -1 on error 142189251Ssam * 143189251Ssam * This function is only used for wpa_cli action scripts. OS wrapper does not 144189251Ssam * need to implement this if such functionality is not needed. 145189251Ssam */ 146189251Ssamint os_setenv(const char *name, const char *value, int overwrite); 147189251Ssam 148189251Ssam/** 149189251Ssam * os_unsetenv - Delete environent variable 150189251Ssam * @name: Name of the variable 151189251Ssam * Returns: 0 on success, -1 on error 152189251Ssam * 153189251Ssam * This function is only used for wpa_cli action scripts. OS wrapper does not 154189251Ssam * need to implement this if such functionality is not needed. 155189251Ssam */ 156189251Ssamint os_unsetenv(const char *name); 157189251Ssam 158189251Ssam/** 159189251Ssam * os_readfile - Read a file to an allocated memory buffer 160189251Ssam * @name: Name of the file to read 161189251Ssam * @len: For returning the length of the allocated buffer 162189251Ssam * Returns: Pointer to the allocated buffer or %NULL on failure 163189251Ssam * 164189251Ssam * This function allocates memory and reads the given file to this buffer. Both 165189251Ssam * binary and text files can be read with this function. The caller is 166189251Ssam * responsible for freeing the returned buffer with os_free(). 167189251Ssam */ 168189251Ssamchar * os_readfile(const char *name, size_t *len); 169189251Ssam 170189251Ssam/** 171189251Ssam * os_zalloc - Allocate and zero memory 172189251Ssam * @size: Number of bytes to allocate 173189251Ssam * Returns: Pointer to allocated and zeroed memory or %NULL on failure 174189251Ssam * 175189251Ssam * Caller is responsible for freeing the returned buffer with os_free(). 176189251Ssam */ 177189251Ssamvoid * os_zalloc(size_t size); 178189251Ssam 179189251Ssam 180189251Ssam/* 181189251Ssam * The following functions are wrapper for standard ANSI C or POSIX functions. 182189251Ssam * By default, they are just defined to use the standard function name and no 183189251Ssam * os_*.c implementation is needed for them. This avoids extra function calls 184189251Ssam * by allowing the C pre-processor take care of the function name mapping. 185189251Ssam * 186189251Ssam * If the target system uses a C library that does not provide these functions, 187189251Ssam * build_config.h can be used to define the wrappers to use a different 188189251Ssam * function name. This can be done on function-by-function basis since the 189189251Ssam * defines here are only used if build_config.h does not define the os_* name. 190189251Ssam * If needed, os_*.c file can be used to implement the functions that are not 191189251Ssam * included in the C library on the target system. Alternatively, 192189251Ssam * OS_NO_C_LIB_DEFINES can be defined to skip all defines here in which case 193189251Ssam * these functions need to be implemented in os_*.c file for the target system. 194189251Ssam */ 195189251Ssam 196189251Ssam#ifdef OS_NO_C_LIB_DEFINES 197189251Ssam 198189251Ssam/** 199189251Ssam * os_malloc - Allocate dynamic memory 200189251Ssam * @size: Size of the buffer to allocate 201189251Ssam * Returns: Allocated buffer or %NULL on failure 202189251Ssam * 203189251Ssam * Caller is responsible for freeing the returned buffer with os_free(). 204189251Ssam */ 205189251Ssamvoid * os_malloc(size_t size); 206189251Ssam 207189251Ssam/** 208189251Ssam * os_realloc - Re-allocate dynamic memory 209189251Ssam * @ptr: Old buffer from os_malloc() or os_realloc() 210189251Ssam * @size: Size of the new buffer 211189251Ssam * Returns: Allocated buffer or %NULL on failure 212189251Ssam * 213189251Ssam * Caller is responsible for freeing the returned buffer with os_free(). 214189251Ssam * If re-allocation fails, %NULL is returned and the original buffer (ptr) is 215189251Ssam * not freed and caller is still responsible for freeing it. 216189251Ssam */ 217189251Ssamvoid * os_realloc(void *ptr, size_t size); 218189251Ssam 219189251Ssam/** 220189251Ssam * os_free - Free dynamic memory 221189251Ssam * @ptr: Old buffer from os_malloc() or os_realloc(); can be %NULL 222189251Ssam */ 223189251Ssamvoid os_free(void *ptr); 224189251Ssam 225189251Ssam/** 226189251Ssam * os_memcpy - Copy memory area 227189251Ssam * @dest: Destination 228189251Ssam * @src: Source 229189251Ssam * @n: Number of bytes to copy 230189251Ssam * Returns: dest 231189251Ssam * 232189251Ssam * The memory areas src and dst must not overlap. os_memmove() can be used with 233189251Ssam * overlapping memory. 234189251Ssam */ 235189251Ssamvoid * os_memcpy(void *dest, const void *src, size_t n); 236189251Ssam 237189251Ssam/** 238189251Ssam * os_memmove - Copy memory area 239189251Ssam * @dest: Destination 240189251Ssam * @src: Source 241189251Ssam * @n: Number of bytes to copy 242189251Ssam * Returns: dest 243189251Ssam * 244189251Ssam * The memory areas src and dst may overlap. 245189251Ssam */ 246189251Ssamvoid * os_memmove(void *dest, const void *src, size_t n); 247189251Ssam 248189251Ssam/** 249189251Ssam * os_memset - Fill memory with a constant byte 250189251Ssam * @s: Memory area to be filled 251189251Ssam * @c: Constant byte 252189251Ssam * @n: Number of bytes started from s to fill with c 253189251Ssam * Returns: s 254189251Ssam */ 255189251Ssamvoid * os_memset(void *s, int c, size_t n); 256189251Ssam 257189251Ssam/** 258189251Ssam * os_memcmp - Compare memory areas 259189251Ssam * @s1: First buffer 260189251Ssam * @s2: Second buffer 261189251Ssam * @n: Maximum numbers of octets to compare 262189251Ssam * Returns: An integer less than, equal to, or greater than zero if s1 is 263189251Ssam * found to be less than, to match, or be greater than s2. Only first n 264189251Ssam * characters will be compared. 265189251Ssam */ 266189251Ssamint os_memcmp(const void *s1, const void *s2, size_t n); 267189251Ssam 268189251Ssam/** 269189251Ssam * os_strdup - Duplicate a string 270189251Ssam * @s: Source string 271189251Ssam * Returns: Allocated buffer with the string copied into it or %NULL on failure 272189251Ssam * 273189251Ssam * Caller is responsible for freeing the returned buffer with os_free(). 274189251Ssam */ 275189251Ssamchar * os_strdup(const char *s); 276189251Ssam 277189251Ssam/** 278189251Ssam * os_strlen - Calculate the length of a string 279189251Ssam * @s: '\0' terminated string 280189251Ssam * Returns: Number of characters in s (not counting the '\0' terminator) 281189251Ssam */ 282189251Ssamsize_t os_strlen(const char *s); 283189251Ssam 284189251Ssam/** 285189251Ssam * os_strcasecmp - Compare two strings ignoring case 286189251Ssam * @s1: First string 287189251Ssam * @s2: Second string 288189251Ssam * Returns: An integer less than, equal to, or greater than zero if s1 is 289189251Ssam * found to be less than, to match, or be greatred than s2 290189251Ssam */ 291189251Ssamint os_strcasecmp(const char *s1, const char *s2); 292189251Ssam 293189251Ssam/** 294189251Ssam * os_strncasecmp - Compare two strings ignoring case 295189251Ssam * @s1: First string 296189251Ssam * @s2: Second string 297189251Ssam * @n: Maximum numbers of characters to compare 298189251Ssam * Returns: An integer less than, equal to, or greater than zero if s1 is 299189251Ssam * found to be less than, to match, or be greater than s2. Only first n 300189251Ssam * characters will be compared. 301189251Ssam */ 302189251Ssamint os_strncasecmp(const char *s1, const char *s2, size_t n); 303189251Ssam 304189251Ssam/** 305189251Ssam * os_strchr - Locate the first occurrence of a character in string 306189251Ssam * @s: String 307189251Ssam * @c: Character to search for 308189251Ssam * Returns: Pointer to the matched character or %NULL if not found 309189251Ssam */ 310189251Ssamchar * os_strchr(const char *s, int c); 311189251Ssam 312189251Ssam/** 313189251Ssam * os_strrchr - Locate the last occurrence of a character in string 314189251Ssam * @s: String 315189251Ssam * @c: Character to search for 316189251Ssam * Returns: Pointer to the matched character or %NULL if not found 317189251Ssam */ 318189251Ssamchar * os_strrchr(const char *s, int c); 319189251Ssam 320189251Ssam/** 321189251Ssam * os_strcmp - Compare two strings 322189251Ssam * @s1: First string 323189251Ssam * @s2: Second string 324189251Ssam * Returns: An integer less than, equal to, or greater than zero if s1 is 325189251Ssam * found to be less than, to match, or be greatred than s2 326189251Ssam */ 327189251Ssamint os_strcmp(const char *s1, const char *s2); 328189251Ssam 329189251Ssam/** 330189251Ssam * os_strncmp - Compare two strings 331189251Ssam * @s1: First string 332189251Ssam * @s2: Second string 333189251Ssam * @n: Maximum numbers of characters to compare 334189251Ssam * Returns: An integer less than, equal to, or greater than zero if s1 is 335189251Ssam * found to be less than, to match, or be greater than s2. Only first n 336189251Ssam * characters will be compared. 337189251Ssam */ 338189251Ssamint os_strncmp(const char *s1, const char *s2, size_t n); 339189251Ssam 340189251Ssam/** 341189251Ssam * os_strncpy - Copy a string 342189251Ssam * @dest: Destination 343189251Ssam * @src: Source 344189251Ssam * @n: Maximum number of characters to copy 345189251Ssam * Returns: dest 346189251Ssam */ 347189251Ssamchar * os_strncpy(char *dest, const char *src, size_t n); 348189251Ssam 349189251Ssam/** 350189251Ssam * os_strstr - Locate a substring 351189251Ssam * @haystack: String (haystack) to search from 352189251Ssam * @needle: Needle to search from haystack 353189251Ssam * Returns: Pointer to the beginning of the substring or %NULL if not found 354189251Ssam */ 355189251Ssamchar * os_strstr(const char *haystack, const char *needle); 356189251Ssam 357189251Ssam/** 358189251Ssam * os_snprintf - Print to a memory buffer 359189251Ssam * @str: Memory buffer to print into 360189251Ssam * @size: Maximum length of the str buffer 361189251Ssam * @format: printf format 362189251Ssam * Returns: Number of characters printed (not including trailing '\0'). 363189251Ssam * 364189251Ssam * If the output buffer is truncated, number of characters which would have 365189251Ssam * been written is returned. Since some C libraries return -1 in such a case, 366189251Ssam * the caller must be prepared on that value, too, to indicate truncation. 367189251Ssam * 368189251Ssam * Note: Some C library implementations of snprintf() may not guarantee null 369189251Ssam * termination in case the output is truncated. The OS wrapper function of 370189251Ssam * os_snprintf() should provide this guarantee, i.e., to null terminate the 371189251Ssam * output buffer if a C library version of the function is used and if that 372189251Ssam * function does not guarantee null termination. 373189251Ssam * 374189251Ssam * If the target system does not include snprintf(), see, e.g., 375189251Ssam * http://www.ijs.si/software/snprintf/ for an example of a portable 376189251Ssam * implementation of snprintf. 377189251Ssam */ 378189251Ssamint os_snprintf(char *str, size_t size, const char *format, ...); 379189251Ssam 380189251Ssam#else /* OS_NO_C_LIB_DEFINES */ 381189251Ssam 382189251Ssam#ifndef os_malloc 383189251Ssam#define os_malloc(s) malloc((s)) 384189251Ssam#endif 385189251Ssam#ifndef os_realloc 386189251Ssam#define os_realloc(p, s) realloc((p), (s)) 387189251Ssam#endif 388189251Ssam#ifndef os_free 389189251Ssam#define os_free(p) free((p)) 390189251Ssam#endif 391189251Ssam 392189251Ssam#ifndef os_memcpy 393189251Ssam#define os_memcpy(d, s, n) memcpy((d), (s), (n)) 394189251Ssam#endif 395189251Ssam#ifndef os_memmove 396189251Ssam#define os_memmove(d, s, n) memmove((d), (s), (n)) 397189251Ssam#endif 398189251Ssam#ifndef os_memset 399189251Ssam#define os_memset(s, c, n) memset(s, c, n) 400189251Ssam#endif 401189251Ssam#ifndef os_memcmp 402189251Ssam#define os_memcmp(s1, s2, n) memcmp((s1), (s2), (n)) 403189251Ssam#endif 404189251Ssam 405189251Ssam#ifndef os_strdup 406189251Ssam#ifdef _MSC_VER 407189251Ssam#define os_strdup(s) _strdup(s) 408189251Ssam#else 409189251Ssam#define os_strdup(s) strdup(s) 410189251Ssam#endif 411189251Ssam#endif 412189251Ssam#ifndef os_strlen 413189251Ssam#define os_strlen(s) strlen(s) 414189251Ssam#endif 415189251Ssam#ifndef os_strcasecmp 416189251Ssam#ifdef _MSC_VER 417189251Ssam#define os_strcasecmp(s1, s2) _stricmp((s1), (s2)) 418189251Ssam#else 419189251Ssam#define os_strcasecmp(s1, s2) strcasecmp((s1), (s2)) 420189251Ssam#endif 421189251Ssam#endif 422189251Ssam#ifndef os_strncasecmp 423189251Ssam#ifdef _MSC_VER 424189251Ssam#define os_strncasecmp(s1, s2, n) _strnicmp((s1), (s2), (n)) 425189251Ssam#else 426189251Ssam#define os_strncasecmp(s1, s2, n) strncasecmp((s1), (s2), (n)) 427189251Ssam#endif 428189251Ssam#endif 429189251Ssam#ifndef os_strchr 430189251Ssam#define os_strchr(s, c) strchr((s), (c)) 431189251Ssam#endif 432189251Ssam#ifndef os_strcmp 433189251Ssam#define os_strcmp(s1, s2) strcmp((s1), (s2)) 434189251Ssam#endif 435189251Ssam#ifndef os_strncmp 436189251Ssam#define os_strncmp(s1, s2, n) strncmp((s1), (s2), (n)) 437189251Ssam#endif 438189251Ssam#ifndef os_strncpy 439189251Ssam#define os_strncpy(d, s, n) strncpy((d), (s), (n)) 440189251Ssam#endif 441189251Ssam#ifndef os_strrchr 442189251Ssam#define os_strrchr(s, c) strrchr((s), (c)) 443189251Ssam#endif 444189251Ssam#ifndef os_strstr 445189251Ssam#define os_strstr(h, n) strstr((h), (n)) 446189251Ssam#endif 447189251Ssam 448189251Ssam#ifndef os_snprintf 449189251Ssam#ifdef _MSC_VER 450189251Ssam#define os_snprintf _snprintf 451189251Ssam#else 452189251Ssam#define os_snprintf snprintf 453189251Ssam#endif 454189251Ssam#endif 455189251Ssam 456189251Ssam#endif /* OS_NO_C_LIB_DEFINES */ 457189251Ssam 458189251Ssam 459189251Ssam/** 460189251Ssam * os_strlcpy - Copy a string with size bound and NUL-termination 461189251Ssam * @dest: Destination 462189251Ssam * @src: Source 463189251Ssam * @siz: Size of the target buffer 464189251Ssam * Returns: Total length of the target string (length of src) (not including 465189251Ssam * NUL-termination) 466189251Ssam * 467189251Ssam * This function matches in behavior with the strlcpy(3) function in OpenBSD. 468189251Ssam */ 469189251Ssamsize_t os_strlcpy(char *dest, const char *src, size_t siz); 470189251Ssam 471189251Ssam 472189251Ssam#ifdef OS_REJECT_C_LIB_FUNCTIONS 473189251Ssam#define malloc OS_DO_NOT_USE_malloc 474189251Ssam#define realloc OS_DO_NOT_USE_realloc 475189251Ssam#define free OS_DO_NOT_USE_free 476189251Ssam#define memcpy OS_DO_NOT_USE_memcpy 477189251Ssam#define memmove OS_DO_NOT_USE_memmove 478189251Ssam#define memset OS_DO_NOT_USE_memset 479189251Ssam#define memcmp OS_DO_NOT_USE_memcmp 480189251Ssam#undef strdup 481189251Ssam#define strdup OS_DO_NOT_USE_strdup 482189251Ssam#define strlen OS_DO_NOT_USE_strlen 483189251Ssam#define strcasecmp OS_DO_NOT_USE_strcasecmp 484189251Ssam#define strncasecmp OS_DO_NOT_USE_strncasecmp 485189251Ssam#undef strchr 486189251Ssam#define strchr OS_DO_NOT_USE_strchr 487189251Ssam#undef strcmp 488189251Ssam#define strcmp OS_DO_NOT_USE_strcmp 489189251Ssam#undef strncmp 490189251Ssam#define strncmp OS_DO_NOT_USE_strncmp 491189251Ssam#undef strncpy 492189251Ssam#define strncpy OS_DO_NOT_USE_strncpy 493189251Ssam#define strrchr OS_DO_NOT_USE_strrchr 494189251Ssam#define strstr OS_DO_NOT_USE_strstr 495189251Ssam#undef snprintf 496189251Ssam#define snprintf OS_DO_NOT_USE_snprintf 497189251Ssam 498189251Ssam#define strcpy OS_DO_NOT_USE_strcpy 499189251Ssam#endif /* OS_REJECT_C_LIB_FUNCTIONS */ 500189251Ssam 501189251Ssam#endif /* OS_H */ 502