contrib/wpa_supplicant-0.5.8/os.h

   1 /*
   2  * wpa_supplicant/hostapd / OS specific functions
   3  * Copyright (c) 2005-2006, Jouni Malinen <j@w1.fi>
   4  *
   5  * This program is free software; you can redistribute it and/or modify
   6  * it under the terms of the GNU General Public License version 2 as
   7  * published by the Free Software Foundation.
   8  *
   9  * Alternatively, this software may be distributed under the terms of BSD
  10  * license.
  11  *
  12  * See README and COPYING for more details.
  13  */
  14
  15 #ifndef OS_H
  16 #define OS_H
  17
  18 typedef long os_time_t;
  19
  20 /**
  21  * os_sleep - Sleep (sec, usec)
  22  * @sec: Number of seconds to sleep
  23  * @usec: Number of microseconds to sleep
  24  */
  25 void os_sleep(os_time_t sec, os_time_t usec);
  26
  27 struct os_time {
  28         os_time_t sec;
  29         os_time_t usec;
  30 };
  31
  32 /**
  33  * os_get_time - Get current time (sec, usec)
  34  * @t: Pointer to buffer for the time
  35  * Returns: 0 on success, -1 on failure
  36  */
  37 int os_get_time(struct os_time *t);
  38
  39
  40 /* Helper macros for handling struct os_time */
  41
  42 #define os_time_before(a, b) \
  43         ((a)->sec < (b)->sec || \
  44          ((a)->sec == (b)->sec && (a)->usec < (b)->usec))
  45
  46 #define os_time_sub(a, b, res) do { \
  47         (res)->sec = (a)->sec - (b)->sec; \
  48         (res)->usec = (a)->usec - (b)->usec; \
  49         if ((res)->usec < 0) { \
  50                 (res)->sec--; \
  51                 (res)->usec += 1000000; \
  52         } \
  53 } while (0)
  54
  55 /**
  56  * os_mktime - Convert broken-down time into seconds since 1970-01-01
  57  * @year: Four digit year
  58  * @month: Month (1 .. 12)
  59  * @day: Day of month (1 .. 31)
  60  * @hour: Hour (0 .. 23)
  61  * @min: Minute (0 .. 59)
  62  * @sec: Second (0 .. 60)
  63  * @t: Buffer for returning calendar time representation (seconds since
  64  * 1970-01-01 00:00:00)
  65  * Returns: 0 on success, -1 on failure
  66  */
  67 int os_mktime(int year, int month, int day, int hour, int min, int sec,
  68               os_time_t *t);
  69
  70
  71 /**
  72  * os_daemonize - Run in the background (detach from the controlling terminal)
  73  * @pid_file: File name to write the process ID to or %NULL to skip this
  74  * Returns: 0 on success, -1 on failure
  75  */
  76 int os_daemonize(const char *pid_file);
  77
  78 /**
  79  * os_daemonize_terminate - Stop running in the background (remove pid file)
  80  * @pid_file: File name to write the process ID to or %NULL to skip this
  81  */
  82 void os_daemonize_terminate(const char *pid_file);
  83
  84 /**
  85  * os_get_random - Get cryptographically strong pseudo random data
  86  * @buf: Buffer for pseudo random data
  87  * @len: Length of the buffer
  88  * Returns: 0 on success, -1 on failure
  89  */
  90 int os_get_random(unsigned char *buf, size_t len);
  91
  92 /**
  93  * os_random - Get pseudo random value (not necessarily very strong)
  94  * Returns: Pseudo random value
  95  */
  96 unsigned long os_random(void);
  97
  98 /**
  99  * os_rel2abs_path - Get an absolute path for a file
 100  * @rel_path: Relative path to a file
 101  * Returns: Absolute path for the file or %NULL on failure
 102  *
 103  * This function tries to convert a relative path of a file to an absolute path
 104  * in order for the file to be found even if current working directory has
 105  * changed. The returned value is allocated and caller is responsible for
 106  * freeing it. It is acceptable to just return the same path in an allocated
 107  * buffer, e.g., return strdup(rel_path). This function is only used to find
 108  * configuration files when os_daemonize() may have changed the current working
 109  * directory and relative path would be pointing to a different location.
 110  */
 111 char * os_rel2abs_path(const char *rel_path);
 112
 113 /**
 114  * os_program_init - Program initialization (called at start)
 115  * Returns: 0 on success, -1 on failure
 116  *
 117  * This function is called when a programs starts. If there are any OS specific
 118  * processing that is needed, it can be placed here. It is also acceptable to
 119  * just return 0 if not special processing is needed.
 120  */
 121 int os_program_init(void);
 122
 123 /**
 124  * os_program_deinit - Program deinitialization (called just before exit)
 125  *
 126  * This function is called just before a program exists. If there are any OS
 127  * specific processing, e.g., freeing resourced allocated in os_program_init(),
 128  * it should be done here. It is also acceptable for this function to do
 129  * nothing.
 130  */
 131 void os_program_deinit(void);
 132
 133 /**
 134  * os_setenv - Set environment variable
 135  * @name: Name of the variable
 136  * @value: Value to set to the variable
 137  * @overwrite: Whether existing variable should be overwritten
 138  * Returns: 0 on success, -1 on error
 139  *
 140  * This function is only used for wpa_cli action scripts. OS wrapper does not
 141  * need to implement this if such functionality is not needed.
 142  */
 143 int os_setenv(const char *name, const char *value, int overwrite);
 144
 145 /**
 146  * os_unsetenv - Delete environent variable
 147  * @name: Name of the variable
 148  * Returns: 0 on success, -1 on error
 149  *
 150  * This function is only used for wpa_cli action scripts. OS wrapper does not
 151  * need to implement this if such functionality is not needed.
 152  */
 153 int os_unsetenv(const char *name);
 154
 155 /**
 156  * os_readfile - Read a file to an allocated memory buffer
 157  * @name: Name of the file to read
 158  * @len: For returning the length of the allocated buffer
 159  * Returns: Pointer to the allocated buffer or %NULL on failure
 160  *
 161  * This function allocates memory and reads the given file to this buffer. Both
 162  * binary and text files can be read with this function. The caller is
 163  * responsible for freeing the returned buffer with os_free().
 164  */
 165 char * os_readfile(const char *name, size_t *len);
 166
 167 /**
 168  * os_zalloc - Allocate and zero memory
 169  * @size: Number of bytes to allocate
 170  * Returns: Pointer to allocated and zeroed memory or %NULL on failure
 171  *
 172  * Caller is responsible for freeing the returned buffer with os_free().
 173  */
 174 void * os_zalloc(size_t size);
 175
 176
 177 /*
 178  * The following functions are wrapper for standard ANSI C or POSIX functions.
 179  * By default, they are just defined to use the standard function name and no
 180  * os_*.c implementation is needed for them. This avoids extra function calls
 181  * by allowing the C pre-processor take care of the function name mapping.
 182  *
 183  * If the target system uses a C library that does not provide these functions,
 184  * build_config.h can be used to define the wrappers to use a different
 185  * function name. This can be done on function-by-function basis since the
 186  * defines here are only used if build_config.h does not define the os_* name.
 187  * If needed, os_*.c file can be used to implement the functions that are not
 188  * included in the C library on the target system. Alternatively,
 189  * OS_NO_C_LIB_DEFINES can be defined to skip all defines here in which case
 190  * these functions need to be implemented in os_*.c file for the target system.
 191  */
 192
 193 #ifdef OS_NO_C_LIB_DEFINES
 194
 195 /**
 196  * os_malloc - Allocate dynamic memory
 197  * @size: Size of the buffer to allocate
 198  * Returns: Allocated buffer or %NULL on failure
 199  *
 200  * Caller is responsible for freeing the returned buffer with os_free().
 201  */
 202 void * os_malloc(size_t size);
 203
 204 /**
 205  * os_realloc - Re-allocate dynamic memory
 206  * @ptr: Old buffer from os_malloc() or os_realloc()
 207  * @size: Size of the new buffer
 208  * Returns: Allocated buffer or %NULL on failure
 209  *
 210  * Caller is responsible for freeing the returned buffer with os_free().
 211  * If re-allocation fails, %NULL is returned and the original buffer (ptr) is
 212  * not freed and caller is still responsible for freeing it.
 213  */
 214 void * os_realloc(void *ptr, size_t size);
 215
 216 /**
 217  * os_free - Free dynamic memory
 218  * @ptr: Old buffer from os_malloc() or os_realloc(); can be %NULL
 219  */
 220 void os_free(void *ptr);
 221
 222 /**
 223  * os_memcpy - Copy memory area
 224  * @dest: Destination
 225  * @src: Source
 226  * @n: Number of bytes to copy
 227  * Returns: dest
 228  *
 229  * The memory areas src and dst must not overlap. os_memmove() can be used with
 230  * overlapping memory.
 231  */
 232 void * os_memcpy(void *dest, const void *src, size_t n);
 233
 234 /**
 235  * os_memmove - Copy memory area
 236  * @dest: Destination
 237  * @src: Source
 238  * @n: Number of bytes to copy
 239  * Returns: dest
 240  *
 241  * The memory areas src and dst may overlap.
 242  */
 243 void * os_memmove(void *dest, const void *src, size_t n);
 244
 245 /**
 246  * os_memset - Fill memory with a constant byte
 247  * @s: Memory area to be filled
 248  * @c: Constant byte
 249  * @n: Number of bytes started from s to fill with c
 250  * Returns: s
 251  */
 252 void * os_memset(void *s, int c, size_t n);
 253
 254 /**
 255  * os_memcmp - Compare memory areas
 256  * @s1: First buffer
 257  * @s2: Second buffer
 258  * @n: Maximum numbers of octets to compare
 259  * Returns: An integer less than, equal to, or greater than zero if s1 is
 260  * found to be less than, to match, or be greater than s2. Only first n
 261  * characters will be compared.
 262  */
 263 int os_memcmp(const void *s1, const void *s2, size_t n);
 264
 265 /**
 266  * os_strdup - Duplicate a string
 267  * @s: Source string
 268  * Returns: Allocated buffer with the string copied into it or %NULL on failure
 269  *
 270  * Caller is responsible for freeing the returned buffer with os_free().
 271  */
 272 char * os_strdup(const char *s);
 273
 274 /**
 275  * os_strlen - Calculate the length of a string
 276  * @s: '\0' terminated string
 277  * Returns: Number of characters in s (not counting the '\0' terminator)
 278  */
 279 size_t os_strlen(const char *s);
 280
 281 /**
 282  * os_strcasecmp - Compare two strings ignoring case
 283  * @s1: First string
 284  * @s2: Second string
 285  * Returns: An integer less than, equal to, or greater than zero if s1 is
 286  * found to be less than, to match, or be greatred than s2
 287  */
 288 int os_strcasecmp(const char *s1, const char *s2);
 289
 290 /**
 291  * os_strncasecmp - Compare two strings ignoring case
 292  * @s1: First string
 293  * @s2: Second string
 294  * @n: Maximum numbers of characters to compare
 295  * Returns: An integer less than, equal to, or greater than zero if s1 is
 296  * found to be less than, to match, or be greater than s2. Only first n
 297  * characters will be compared.
 298  */
 299 int os_strncasecmp(const char *s1, const char *s2, size_t n);
 300
 301 /**
 302  * os_strchr - Locate the first occurrence of a character in string
 303  * @s: String
 304  * @c: Character to search for
 305  * Returns: Pointer to the matched character or %NULL if not found
 306  */
 307 char * os_strchr(const char *s, int c);
 308
 309 /**
 310  * os_strrchr - Locate the last occurrence of a character in string
 311  * @s: String
 312  * @c: Character to search for
 313  * Returns: Pointer to the matched character or %NULL if not found
 314  */
 315 char * os_strrchr(const char *s, int c);
 316
 317 /**
 318  * os_strcmp - Compare two strings
 319  * @s1: First string
 320  * @s2: Second string
 321  * Returns: An integer less than, equal to, or greater than zero if s1 is
 322  * found to be less than, to match, or be greatred than s2
 323  */
 324 int os_strcmp(const char *s1, const char *s2);
 325
 326 /**
 327  * os_strncmp - Compare two strings
 328  * @s1: First string
 329  * @s2: Second string
 330  * @n: Maximum numbers of characters to compare
 331  * Returns: An integer less than, equal to, or greater than zero if s1 is
 332  * found to be less than, to match, or be greater than s2. Only first n
 333  * characters will be compared.
 334  */
 335 int os_strncmp(const char *s1, const char *s2, size_t n);
 336
 337 /**
 338  * os_strncpy - Copy a string
 339  * @dest: Destination
 340  * @src: Source
 341  * @n: Maximum number of characters to copy
 342  * Returns: dest
 343  */
 344 char * os_strncpy(char *dest, const char *src, size_t n);
 345
 346 /**
 347  * os_strstr - Locate a substring
 348  * @haystack: String (haystack) to search from
 349  * @needle: Needle to search from haystack
 350  * Returns: Pointer to the beginning of the substring or %NULL if not found
 351  */
 352 char * os_strstr(const char *haystack, const char *needle);
 353
 354 /**
 355  * os_snprintf - Print to a memory buffer
 356  * @str: Memory buffer to print into
 357  * @size: Maximum length of the str buffer
 358  * @format: printf format
 359  * Returns: Number of characters printed (not including trailing '\0').
 360  *
 361  * If the output buffer is truncated, number of characters which would have
 362  * been written is returned. Since some C libraries return -1 in such a case,
 363  * the caller must be prepared on that value, too, to indicate truncation.
 364  *
 365  * Note: Some C library implementations of snprintf() may not guarantee null
 366  * termination in case the output is truncated. The OS wrapper function of
 367  * os_snprintf() should provide this guarantee, i.e., to null terminate the
 368  * output buffer if a C library version of the function is used and if that
 369  * function does not guarantee null termination.
 370  *
 371  * If the target system does not include snprintf(), see, e.g.,
 372  * http://www.ijs.si/software/snprintf/ for an example of a portable
 373  * implementation of snprintf.
 374  */
 375 int os_snprintf(char *str, size_t size, const char *format, ...);
 376
 377 #else /* OS_NO_C_LIB_DEFINES */
 378
 379 #ifndef os_malloc
 380 #define os_malloc(s) malloc((s))
 381 #endif
 382 #ifndef os_realloc
 383 #define os_realloc(p, s) realloc((p), (s))
 384 #endif
 385 #ifndef os_free
 386 #define os_free(p) free((p))
 387 #endif
 388
 389 #ifndef os_memcpy
 390 #define os_memcpy(d, s, n) memcpy((d), (s), (n))
 391 #endif
 392 #ifndef os_memmove
 393 #define os_memmove(d, s, n) memmove((d), (s), (n))
 394 #endif
 395 #ifndef os_memset
 396 #define os_memset(s, c, n) memset(s, c, n)
 397 #endif
 398 #ifndef os_memcmp
 399 #define os_memcmp(s1, s2, n) memcmp((s1), (s2), (n))
 400 #endif
 401
 402 #ifndef os_strdup
 403 #ifdef _MSC_VER
 404 #define os_strdup(s) _strdup(s)
 405 #else
 406 #define os_strdup(s) strdup(s)
 407 #endif
 408 #endif
 409 #ifndef os_strlen
 410 #define os_strlen(s) strlen(s)
 411 #endif
 412 #ifndef os_strcasecmp
 413 #ifdef _MSC_VER
 414 #define os_strcasecmp(s1, s2) _stricmp((s1), (s2))
 415 #else
 416 #define os_strcasecmp(s1, s2) strcasecmp((s1), (s2))
 417 #endif
 418 #endif
 419 #ifndef os_strncasecmp
 420 #ifdef _MSC_VER
 421 #define os_strncasecmp(s1, s2, n) _strnicmp((s1), (s2), (n))
 422 #else
 423 #define os_strncasecmp(s1, s2, n) strncasecmp((s1), (s2), (n))
 424 #endif
 425 #endif
 426 #ifndef os_strchr
 427 #define os_strchr(s, c) strchr((s), (c))
 428 #endif
 429 #ifndef os_strcmp
 430 #define os_strcmp(s1, s2) strcmp((s1), (s2))
 431 #endif
 432 #ifndef os_strncmp
 433 #define os_strncmp(s1, s2, n) strncmp((s1), (s2), (n))
 434 #endif
 435 #ifndef os_strncpy
 436 #define os_strncpy(d, s, n) strncpy((d), (s), (n))
 437 #endif
 438 #ifndef os_strrchr
 439 #define os_strrchr(s, c) strrchr((s), (c))
 440 #endif
 441 #ifndef os_strstr
 442 #define os_strstr(h, n) strstr((h), (n))
 443 #endif
 444
 445 #ifndef os_snprintf
 446 #ifdef _MSC_VER
 447 #define os_snprintf _snprintf
 448 #else
 449 #define os_snprintf snprintf
 450 #endif
 451 #endif
 452
 453 #endif /* OS_NO_C_LIB_DEFINES */
 454
 455
 456 #ifdef OS_REJECT_C_LIB_FUNCTIONS
 457 #define malloc OS_DO_NOT_USE_malloc
 458 #define realloc OS_DO_NOT_USE_realloc
 459 #define free OS_DO_NOT_USE_free
 460 #define memcpy OS_DO_NOT_USE_memcpy
 461 #define memmove OS_DO_NOT_USE_memmove
 462 #define memset OS_DO_NOT_USE_memset
 463 #define memcmp OS_DO_NOT_USE_memcmp
 464 #undef strdup
 465 #define strdup OS_DO_NOT_USE_strdup
 466 #define strlen OS_DO_NOT_USE_strlen
 467 #define strcasecmp OS_DO_NOT_USE_strcasecmp
 468 #define strncasecmp OS_DO_NOT_USE_strncasecmp
 469 #undef strchr
 470 #define strchr OS_DO_NOT_USE_strchr
 471 #undef strcmp
 472 #define strcmp OS_DO_NOT_USE_strcmp
 473 #undef strncmp
 474 #define strncmp OS_DO_NOT_USE_strncmp
 475 #undef strncpy
 476 #define strncpy OS_DO_NOT_USE_strncpy
 477 #define strrchr OS_DO_NOT_USE_strrchr
 478 #define strstr OS_DO_NOT_USE_strstr
 479 #undef snprintf
 480 #define snprintf OS_DO_NOT_USE_snprintf
 481
 482 #define strcpy OS_DO_NOT_USE_strcpy
 483 #endif /* OS_REJECT_C_LIB_FUNCTIONS */
 484
 485 #endif /* OS_H */