1 /**
2 * collectd - src/common.c
3 * Copyright (C) 2005-2014 Florian octo Forster
4 *
5 * Permission is hereby granted, free of charge, to any person obtaining a
6 * copy of this software and associated documentation files (the "Software"),
7 * to deal in the Software without restriction, including without limitation
8 * the rights to use, copy, modify, merge, publish, distribute, sublicense,
9 * and/or sell copies of the Software, and to permit persons to whom the
10 * Software is furnished to do so, subject to the following conditions:
11 *
12 * The above copyright notice and this permission notice shall be included in
13 * all copies or substantial portions of the Software.
14 *
15 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
20 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
21 * DEALINGS IN THE SOFTWARE.
22 *
23 * Authors:
24 * Florian octo Forster <octo at collectd.org>
25 * Niki W. Waibel <niki.waibel@gmx.net>
26 * Sebastian Harl <sh at tokkee.org>
27 * Michał Mirosław <mirq-linux at rere.qmqm.pl>
28 **/
30 #if HAVE_CONFIG_H
31 # include "config.h"
32 #endif
34 #include "collectd.h"
35 #include "common.h"
36 #include "plugin.h"
37 #include "utils_cache.h"
39 #if HAVE_PTHREAD_H
40 # include <pthread.h>
41 #endif
43 #ifdef HAVE_MATH_H
44 # include <math.h>
45 #endif
47 /* for getaddrinfo */
48 #include <sys/types.h>
49 #include <netdb.h>
51 #include <poll.h>
53 #if HAVE_NETINET_IN_H
54 # include <netinet/in.h>
55 #endif
57 /* for ntohl and htonl */
58 #if HAVE_ARPA_INET_H
59 # include <arpa/inet.h>
60 #endif
62 #ifdef HAVE_LIBKSTAT
63 extern kstat_ctl_t *kc;
64 #endif
66 #if !HAVE_GETPWNAM_R
67 static pthread_mutex_t getpwnam_r_lock = PTHREAD_MUTEX_INITIALIZER;
68 #endif
70 #if !HAVE_STRERROR_R
71 static pthread_mutex_t strerror_r_lock = PTHREAD_MUTEX_INITIALIZER;
72 #endif
74 char *sstrncpy (char *dest, const char *src, size_t n)
75 {
76 strncpy (dest, src, n);
77 dest[n - 1] = '\0';
79 return (dest);
80 } /* char *sstrncpy */
82 int ssnprintf (char *dest, size_t n, const char *format, ...)
83 {
84 int ret = 0;
85 va_list ap;
87 va_start (ap, format);
88 ret = vsnprintf (dest, n, format, ap);
89 dest[n - 1] = '\0';
90 va_end (ap);
92 return (ret);
93 } /* int ssnprintf */
95 char *ssnprintf_alloc (char const *format, ...) /* {{{ */
96 {
97 char static_buffer[1024] = "";
98 char *alloc_buffer;
99 size_t alloc_buffer_size;
100 int status;
101 va_list ap;
103 /* Try printing into the static buffer. In many cases it will be
104 * sufficiently large and we can simply return a strdup() of this
105 * buffer. */
106 va_start (ap, format);
107 status = vsnprintf (static_buffer, sizeof (static_buffer), format, ap);
108 va_end (ap);
109 if (status < 0)
110 return (NULL);
112 /* "status" does not include the null byte. */
113 alloc_buffer_size = (size_t) (status + 1);
114 if (alloc_buffer_size <= sizeof (static_buffer))
115 return (strdup (static_buffer));
117 /* Allocate a buffer large enough to hold the string. */
118 alloc_buffer = malloc (alloc_buffer_size);
119 if (alloc_buffer == NULL)
120 return (NULL);
121 memset (alloc_buffer, 0, alloc_buffer_size);
123 /* Print again into this new buffer. */
124 va_start (ap, format);
125 status = vsnprintf (alloc_buffer, alloc_buffer_size, format, ap);
126 va_end (ap);
127 if (status < 0)
128 {
129 sfree (alloc_buffer);
130 return (NULL);
131 }
133 return (alloc_buffer);
134 } /* }}} char *ssnprintf_alloc */
136 char *sstrdup (const char *s)
137 {
138 char *r;
139 size_t sz;
141 if (s == NULL)
142 return (NULL);
144 /* Do not use `strdup' here, because it's not specified in POSIX. It's
145 * ``only'' an XSI extension. */
146 sz = strlen (s) + 1;
147 r = (char *) malloc (sizeof (char) * sz);
148 if (r == NULL)
149 {
150 ERROR ("sstrdup: Out of memory.");
151 exit (3);
152 }
153 memcpy (r, s, sizeof (char) * sz);
155 return (r);
156 } /* char *sstrdup */
158 /* Even though Posix requires "strerror_r" to return an "int",
159 * some systems (e.g. the GNU libc) return a "char *" _and_
160 * ignore the second argument ... -tokkee */
161 char *sstrerror (int errnum, char *buf, size_t buflen)
162 {
163 buf[0] = '\0';
165 #if !HAVE_STRERROR_R
166 {
167 char *temp;
169 pthread_mutex_lock (&strerror_r_lock);
171 temp = strerror (errnum);
172 sstrncpy (buf, temp, buflen);
174 pthread_mutex_unlock (&strerror_r_lock);
175 }
176 /* #endif !HAVE_STRERROR_R */
178 #elif STRERROR_R_CHAR_P
179 {
180 char *temp;
181 temp = strerror_r (errnum, buf, buflen);
182 if (buf[0] == '\0')
183 {
184 if ((temp != NULL) && (temp != buf) && (temp[0] != '\0'))
185 sstrncpy (buf, temp, buflen);
186 else
187 sstrncpy (buf, "strerror_r did not return "
188 "an error message", buflen);
189 }
190 }
191 /* #endif STRERROR_R_CHAR_P */
193 #else
194 if (strerror_r (errnum, buf, buflen) != 0)
195 {
196 ssnprintf (buf, buflen, "Error #%i; "
197 "Additionally, strerror_r failed.",
198 errnum);
199 }
200 #endif /* STRERROR_R_CHAR_P */
202 return (buf);
203 } /* char *sstrerror */
205 void *smalloc (size_t size)
206 {
207 void *r;
209 if ((r = malloc (size)) == NULL)
210 {
211 ERROR ("Not enough memory.");
212 exit (3);
213 }
215 return (r);
216 } /* void *smalloc */
218 #if 0
219 void sfree (void **ptr)
220 {
221 if (ptr == NULL)
222 return;
224 if (*ptr != NULL)
225 free (*ptr);
227 *ptr = NULL;
228 }
229 #endif
231 ssize_t sread (int fd, void *buf, size_t count)
232 {
233 char *ptr;
234 size_t nleft;
235 ssize_t status;
237 ptr = (char *) buf;
238 nleft = count;
240 while (nleft > 0)
241 {
242 status = read (fd, (void *) ptr, nleft);
244 if ((status < 0) && ((errno == EAGAIN) || (errno == EINTR)))
245 continue;
247 if (status < 0)
248 return (status);
250 if (status == 0)
251 {
252 DEBUG ("Received EOF from fd %i. "
253 "Closing fd and returning error.",
254 fd);
255 close (fd);
256 return (-1);
257 }
259 assert ((0 > status) || (nleft >= (size_t)status));
261 nleft = nleft - ((size_t) status);
262 ptr = ptr + ((size_t) status);
263 }
265 return (0);
266 }
269 ssize_t swrite (int fd, const void *buf, size_t count)
270 {
271 const char *ptr;
272 size_t nleft;
273 ssize_t status;
274 struct pollfd pfd;
276 ptr = (const char *) buf;
277 nleft = count;
279 /* checking for closed peer connection */
280 pfd.fd = fd;
281 pfd.events = POLLIN | POLLHUP;
282 pfd.revents = 0;
283 if (poll(&pfd, 1, 0) > 0) {
284 char buffer[32];
285 if (recv(fd, buffer, sizeof(buffer), MSG_PEEK | MSG_DONTWAIT) == 0) {
286 // if recv returns zero (even though poll() said there is data to be read),
287 // that means the connection has been closed
288 return -1;
289 }
290 }
292 while (nleft > 0)
293 {
294 status = write (fd, (const void *) ptr, nleft);
296 if ((status < 0) && ((errno == EAGAIN) || (errno == EINTR)))
297 continue;
299 if (status < 0)
300 return (status);
302 nleft = nleft - ((size_t) status);
303 ptr = ptr + ((size_t) status);
304 }
306 return (0);
307 }
309 int strsplit (char *string, char **fields, size_t size)
310 {
311 size_t i;
312 char *ptr;
313 char *saveptr;
315 i = 0;
316 ptr = string;
317 saveptr = NULL;
318 while ((fields[i] = strtok_r (ptr, " \t\r\n", &saveptr)) != NULL)
319 {
320 ptr = NULL;
321 i++;
323 if (i >= size)
324 break;
325 }
327 return ((int) i);
328 }
330 int strjoin (char *buffer, size_t buffer_size,
331 char **fields, size_t fields_num,
332 const char *sep)
333 {
334 size_t avail;
335 char *ptr;
336 size_t sep_len;
337 size_t i;
339 if ((buffer_size < 1) || (fields_num <= 0))
340 return (-1);
342 memset (buffer, 0, buffer_size);
343 ptr = buffer;
344 avail = buffer_size - 1;
346 sep_len = 0;
347 if (sep != NULL)
348 sep_len = strlen (sep);
350 for (i = 0; i < fields_num; i++)
351 {
352 size_t field_len;
354 if ((i > 0) && (sep_len > 0))
355 {
356 if (avail < sep_len)
357 return (-1);
359 memcpy (ptr, sep, sep_len);
360 ptr += sep_len;
361 avail -= sep_len;
362 }
364 field_len = strlen (fields[i]);
365 if (avail < field_len)
366 return (-1);
368 memcpy (ptr, fields[i], field_len);
369 ptr += field_len;
370 avail -= field_len;
371 }
373 assert (buffer[buffer_size - 1] == 0);
374 return ((int) strlen (buffer));
375 }
377 int strsubstitute (char *str, char c_from, char c_to)
378 {
379 int ret;
381 if (str == NULL)
382 return (-1);
384 ret = 0;
385 while (*str != '\0')
386 {
387 if (*str == c_from)
388 {
389 *str = c_to;
390 ret++;
391 }
392 str++;
393 }
395 return (ret);
396 } /* int strsubstitute */
398 int escape_string (char *buffer, size_t buffer_size)
399 {
400 char *temp;
401 size_t i;
402 size_t j;
404 /* Check if we need to escape at all first */
405 temp = strpbrk (buffer, " \t\"\\");
406 if (temp == NULL)
407 return (0);
409 if (buffer_size < 3)
410 return (EINVAL);
412 temp = (char *) malloc (buffer_size);
413 if (temp == NULL)
414 return (ENOMEM);
415 memset (temp, 0, buffer_size);
417 temp[0] = '"';
418 j = 1;
420 for (i = 0; i < buffer_size; i++)
421 {
422 if (buffer[i] == 0)
423 {
424 break;
425 }
426 else if ((buffer[i] == '"') || (buffer[i] == '\\'))
427 {
428 if (j > (buffer_size - 4))
429 break;
430 temp[j] = '\\';
431 temp[j + 1] = buffer[i];
432 j += 2;
433 }
434 else
435 {
436 if (j > (buffer_size - 3))
437 break;
438 temp[j] = buffer[i];
439 j++;
440 }
441 }
443 assert ((j + 1) < buffer_size);
444 temp[j] = '"';
445 temp[j + 1] = 0;
447 sstrncpy (buffer, temp, buffer_size);
448 sfree (temp);
449 return (0);
450 } /* int escape_string */
452 int strunescape (char *buf, size_t buf_len)
453 {
454 size_t i;
456 for (i = 0; (i < buf_len) && (buf[i] != '\0'); ++i)
457 {
458 if (buf[i] != '\\')
459 continue;
461 if (((i + 1) >= buf_len) || (buf[i + 1] == 0)) {
462 ERROR ("string unescape: backslash found at end of string.");
463 /* Ensure null-byte at the end of the buffer. */
464 buf[i] = 0;
465 return (-1);
466 }
468 switch (buf[i + 1]) {
469 case 't':
470 buf[i] = '\t';
471 break;
472 case 'n':
473 buf[i] = '\n';
474 break;
475 case 'r':
476 buf[i] = '\r';
477 break;
478 default:
479 buf[i] = buf[i + 1];
480 break;
481 }
483 /* Move everything after the position one position to the left.
484 * Add a null-byte as last character in the buffer. */
485 memmove (buf + i + 1, buf + i + 2, buf_len - i - 2);
486 buf[buf_len - 1] = 0;
487 }
488 return (0);
489 } /* int strunescape */
491 size_t strstripnewline (char *buffer)
492 {
493 size_t buffer_len = strlen (buffer);
495 while (buffer_len > 0)
496 {
497 if ((buffer[buffer_len - 1] != '\n')
498 && (buffer[buffer_len - 1] != '\r'))
499 break;
500 buffer_len--;
501 buffer[buffer_len] = 0;
502 }
504 return (buffer_len);
505 } /* size_t strstripnewline */
507 int escape_slashes (char *buffer, size_t buffer_size)
508 {
509 size_t buffer_len;
510 size_t i;
512 buffer_len = strlen (buffer);
514 if (buffer_len <= 1)
515 {
516 if (strcmp ("/", buffer) == 0)
517 {
518 if (buffer_size < 5)
519 return (-1);
520 sstrncpy (buffer, "root", buffer_size);
521 }
522 return (0);
523 }
525 /* Move one to the left */
526 if (buffer[0] == '/')
527 {
528 memmove (buffer, buffer + 1, buffer_len);
529 buffer_len--;
530 }
532 for (i = 0; i < buffer_len; i++)
533 {
534 if (buffer[i] == '/')
535 buffer[i] = '_';
536 }
538 return (0);
539 } /* int escape_slashes */
541 void replace_special (char *buffer, size_t buffer_size)
542 {
543 size_t i;
545 for (i = 0; i < buffer_size; i++)
546 {
547 if (buffer[i] == 0)
548 return;
549 if ((!isalnum ((int) buffer[i])) && (buffer[i] != '-'))
550 buffer[i] = '_';
551 }
552 } /* void replace_special */
554 int timeval_cmp (struct timeval tv0, struct timeval tv1, struct timeval *delta)
555 {
556 struct timeval *larger;
557 struct timeval *smaller;
559 int status;
561 NORMALIZE_TIMEVAL (tv0);
562 NORMALIZE_TIMEVAL (tv1);
564 if ((tv0.tv_sec == tv1.tv_sec) && (tv0.tv_usec == tv1.tv_usec))
565 {
566 if (delta != NULL) {
567 delta->tv_sec = 0;
568 delta->tv_usec = 0;
569 }
570 return (0);
571 }
573 if ((tv0.tv_sec < tv1.tv_sec)
574 || ((tv0.tv_sec == tv1.tv_sec) && (tv0.tv_usec < tv1.tv_usec)))
575 {
576 larger = &tv1;
577 smaller = &tv0;
578 status = -1;
579 }
580 else
581 {
582 larger = &tv0;
583 smaller = &tv1;
584 status = 1;
585 }
587 if (delta != NULL) {
588 delta->tv_sec = larger->tv_sec - smaller->tv_sec;
590 if (smaller->tv_usec <= larger->tv_usec)
591 delta->tv_usec = larger->tv_usec - smaller->tv_usec;
592 else
593 {
594 --delta->tv_sec;
595 delta->tv_usec = 1000000 + larger->tv_usec - smaller->tv_usec;
596 }
597 }
599 assert ((delta == NULL)
600 || ((0 <= delta->tv_usec) && (delta->tv_usec < 1000000)));
602 return (status);
603 } /* int timeval_cmp */
605 int check_create_dir (const char *file_orig)
606 {
607 struct stat statbuf;
609 char file_copy[512];
610 char dir[512];
611 int dir_len = 512;
612 char *fields[16];
613 int fields_num;
614 char *ptr;
615 char *saveptr;
616 int last_is_file = 1;
617 int path_is_absolute = 0;
618 size_t len;
619 int i;
621 /*
622 * Sanity checks first
623 */
624 if (file_orig == NULL)
625 return (-1);
627 if ((len = strlen (file_orig)) < 1)
628 return (-1);
629 else if (len >= sizeof (file_copy))
630 return (-1);
632 /*
633 * If `file_orig' ends in a slash the last component is a directory,
634 * otherwise it's a file. Act accordingly..
635 */
636 if (file_orig[len - 1] == '/')
637 last_is_file = 0;
638 if (file_orig[0] == '/')
639 path_is_absolute = 1;
641 /*
642 * Create a copy for `strtok_r' to destroy
643 */
644 sstrncpy (file_copy, file_orig, sizeof (file_copy));
646 /*
647 * Break into components. This will eat up several slashes in a row and
648 * remove leading and trailing slashes..
649 */
650 ptr = file_copy;
651 saveptr = NULL;
652 fields_num = 0;
653 while ((fields[fields_num] = strtok_r (ptr, "/", &saveptr)) != NULL)
654 {
655 ptr = NULL;
656 fields_num++;
658 if (fields_num >= 16)
659 break;
660 }
662 /*
663 * For each component, do..
664 */
665 for (i = 0; i < (fields_num - last_is_file); i++)
666 {
667 /*
668 * Do not create directories that start with a dot. This
669 * prevents `../../' attacks and other likely malicious
670 * behavior.
671 */
672 if (fields[i][0] == '.')
673 {
674 ERROR ("Cowardly refusing to create a directory that "
675 "begins with a `.' (dot): `%s'", file_orig);
676 return (-2);
677 }
679 /*
680 * Join the components together again
681 */
682 dir[0] = '/';
683 if (strjoin (dir + path_is_absolute, (size_t) (dir_len - path_is_absolute),
684 fields, (size_t) (i + 1), "/") < 0)
685 {
686 ERROR ("strjoin failed: `%s', component #%i", file_orig, i);
687 return (-1);
688 }
690 while (42) {
691 if ((stat (dir, &statbuf) == -1)
692 && (lstat (dir, &statbuf) == -1))
693 {
694 if (errno == ENOENT)
695 {
696 if (mkdir (dir, S_IRWXU | S_IRWXG | S_IRWXO) == 0)
697 break;
699 /* this might happen, if a different thread created
700 * the directory in the meantime
701 * => call stat() again to check for S_ISDIR() */
702 if (EEXIST == errno)
703 continue;
705 char errbuf[1024];
706 ERROR ("check_create_dir: mkdir (%s): %s", dir,
707 sstrerror (errno,
708 errbuf, sizeof (errbuf)));
709 return (-1);
710 }
711 else
712 {
713 char errbuf[1024];
714 ERROR ("check_create_dir: stat (%s): %s", dir,
715 sstrerror (errno, errbuf,
716 sizeof (errbuf)));
717 return (-1);
718 }
719 }
720 else if (!S_ISDIR (statbuf.st_mode))
721 {
722 ERROR ("check_create_dir: `%s' exists but is not "
723 "a directory!", dir);
724 return (-1);
725 }
726 break;
727 }
728 }
730 return (0);
731 } /* check_create_dir */
733 #ifdef HAVE_LIBKSTAT
734 int get_kstat (kstat_t **ksp_ptr, char *module, int instance, char *name)
735 {
736 char ident[128];
738 *ksp_ptr = NULL;
740 if (kc == NULL)
741 return (-1);
743 ssnprintf (ident, sizeof (ident), "%s,%i,%s", module, instance, name);
745 *ksp_ptr = kstat_lookup (kc, module, instance, name);
746 if (*ksp_ptr == NULL)
747 {
748 ERROR ("get_kstat: Cound not find kstat %s", ident);
749 return (-1);
750 }
752 if ((*ksp_ptr)->ks_type != KSTAT_TYPE_NAMED)
753 {
754 ERROR ("get_kstat: kstat %s has wrong type", ident);
755 *ksp_ptr = NULL;
756 return (-1);
757 }
759 #ifdef assert
760 assert (*ksp_ptr != NULL);
761 assert ((*ksp_ptr)->ks_type == KSTAT_TYPE_NAMED);
762 #endif
764 if (kstat_read (kc, *ksp_ptr, NULL) == -1)
765 {
766 ERROR ("get_kstat: kstat %s could not be read", ident);
767 return (-1);
768 }
770 if ((*ksp_ptr)->ks_type != KSTAT_TYPE_NAMED)
771 {
772 ERROR ("get_kstat: kstat %s has wrong type", ident);
773 return (-1);
774 }
776 return (0);
777 }
779 long long get_kstat_value (kstat_t *ksp, char *name)
780 {
781 kstat_named_t *kn;
782 long long retval = -1LL;
784 if (ksp == NULL)
785 {
786 ERROR ("get_kstat_value (\"%s\"): ksp is NULL.", name);
787 return (-1LL);
788 }
789 else if (ksp->ks_type != KSTAT_TYPE_NAMED)
790 {
791 ERROR ("get_kstat_value (\"%s\"): ksp->ks_type (%#x) "
792 "is not KSTAT_TYPE_NAMED (%#x).",
793 name,
794 (unsigned int) ksp->ks_type,
795 (unsigned int) KSTAT_TYPE_NAMED);
796 return (-1LL);
797 }
799 if ((kn = (kstat_named_t *) kstat_data_lookup (ksp, name)) == NULL)
800 return (-1LL);
802 if (kn->data_type == KSTAT_DATA_INT32)
803 retval = (long long) kn->value.i32;
804 else if (kn->data_type == KSTAT_DATA_UINT32)
805 retval = (long long) kn->value.ui32;
806 else if (kn->data_type == KSTAT_DATA_INT64)
807 retval = (long long) kn->value.i64; /* According to ANSI C99 `long long' must hold at least 64 bits */
808 else if (kn->data_type == KSTAT_DATA_UINT64)
809 retval = (long long) kn->value.ui64; /* XXX: Might overflow! */
810 else
811 WARNING ("get_kstat_value: Not a numeric value: %s", name);
813 return (retval);
814 }
815 #endif /* HAVE_LIBKSTAT */
817 #ifndef HAVE_HTONLL
818 unsigned long long ntohll (unsigned long long n)
819 {
820 #if BYTE_ORDER == BIG_ENDIAN
821 return (n);
822 #else
823 return (((unsigned long long) ntohl (n)) << 32) + ntohl (n >> 32);
824 #endif
825 } /* unsigned long long ntohll */
827 unsigned long long htonll (unsigned long long n)
828 {
829 #if BYTE_ORDER == BIG_ENDIAN
830 return (n);
831 #else
832 return (((unsigned long long) htonl (n)) << 32) + htonl (n >> 32);
833 #endif
834 } /* unsigned long long htonll */
835 #endif /* HAVE_HTONLL */
837 #if FP_LAYOUT_NEED_NOTHING
838 /* Well, we need nothing.. */
839 /* #endif FP_LAYOUT_NEED_NOTHING */
841 #elif FP_LAYOUT_NEED_ENDIANFLIP || FP_LAYOUT_NEED_INTSWAP
842 # if FP_LAYOUT_NEED_ENDIANFLIP
843 # define FP_CONVERT(A) ((((uint64_t)(A) & 0xff00000000000000LL) >> 56) | \
844 (((uint64_t)(A) & 0x00ff000000000000LL) >> 40) | \
845 (((uint64_t)(A) & 0x0000ff0000000000LL) >> 24) | \
846 (((uint64_t)(A) & 0x000000ff00000000LL) >> 8) | \
847 (((uint64_t)(A) & 0x00000000ff000000LL) << 8) | \
848 (((uint64_t)(A) & 0x0000000000ff0000LL) << 24) | \
849 (((uint64_t)(A) & 0x000000000000ff00LL) << 40) | \
850 (((uint64_t)(A) & 0x00000000000000ffLL) << 56))
851 # else
852 # define FP_CONVERT(A) ((((uint64_t)(A) & 0xffffffff00000000LL) >> 32) | \
853 (((uint64_t)(A) & 0x00000000ffffffffLL) << 32))
854 # endif
856 double ntohd (double d)
857 {
858 union
859 {
860 uint8_t byte[8];
861 uint64_t integer;
862 double floating;
863 } ret;
865 ret.floating = d;
867 /* NAN in x86 byte order */
868 if ((ret.byte[0] == 0x00) && (ret.byte[1] == 0x00)
869 && (ret.byte[2] == 0x00) && (ret.byte[3] == 0x00)
870 && (ret.byte[4] == 0x00) && (ret.byte[5] == 0x00)
871 && (ret.byte[6] == 0xf8) && (ret.byte[7] == 0x7f))
872 {
873 return (NAN);
874 }
875 else
876 {
877 uint64_t tmp;
879 tmp = ret.integer;
880 ret.integer = FP_CONVERT (tmp);
881 return (ret.floating);
882 }
883 } /* double ntohd */
885 double htond (double d)
886 {
887 union
888 {
889 uint8_t byte[8];
890 uint64_t integer;
891 double floating;
892 } ret;
894 if (isnan (d))
895 {
896 ret.byte[0] = ret.byte[1] = ret.byte[2] = ret.byte[3] = 0x00;
897 ret.byte[4] = ret.byte[5] = 0x00;
898 ret.byte[6] = 0xf8;
899 ret.byte[7] = 0x7f;
900 return (ret.floating);
901 }
902 else
903 {
904 uint64_t tmp;
906 ret.floating = d;
907 tmp = FP_CONVERT (ret.integer);
908 ret.integer = tmp;
909 return (ret.floating);
910 }
911 } /* double htond */
912 #endif /* FP_LAYOUT_NEED_ENDIANFLIP || FP_LAYOUT_NEED_INTSWAP */
914 int format_name (char *ret, int ret_len,
915 const char *hostname,
916 const char *plugin, const char *plugin_instance,
917 const char *type, const char *type_instance)
918 {
919 char *buffer;
920 size_t buffer_size;
922 buffer = ret;
923 buffer_size = (size_t) ret_len;
925 #define APPEND(str) do { \
926 size_t l = strlen (str); \
927 if (l >= buffer_size) \
928 return (ENOBUFS); \
929 memcpy (buffer, (str), l); \
930 buffer += l; buffer_size -= l; \
931 } while (0)
933 assert (plugin != NULL);
934 assert (type != NULL);
936 APPEND (hostname);
937 APPEND ("/");
938 APPEND (plugin);
939 if ((plugin_instance != NULL) && (plugin_instance[0] != 0))
940 {
941 APPEND ("-");
942 APPEND (plugin_instance);
943 }
944 APPEND ("/");
945 APPEND (type);
946 if ((type_instance != NULL) && (type_instance[0] != 0))
947 {
948 APPEND ("-");
949 APPEND (type_instance);
950 }
951 assert (buffer_size > 0);
952 buffer[0] = 0;
954 #undef APPEND
955 return (0);
956 } /* int format_name */
958 int format_values (char *ret, size_t ret_len, /* {{{ */
959 const data_set_t *ds, const value_list_t *vl,
960 _Bool store_rates)
961 {
962 size_t offset = 0;
963 int status;
964 size_t i;
965 gauge_t *rates = NULL;
967 assert (0 == strcmp (ds->type, vl->type));
969 memset (ret, 0, ret_len);
971 #define BUFFER_ADD(...) do { \
972 status = ssnprintf (ret + offset, ret_len - offset, \
973 __VA_ARGS__); \
974 if (status < 1) \
975 { \
976 sfree (rates); \
977 return (-1); \
978 } \
979 else if (((size_t) status) >= (ret_len - offset)) \
980 { \
981 sfree (rates); \
982 return (-1); \
983 } \
984 else \
985 offset += ((size_t) status); \
986 } while (0)
988 BUFFER_ADD ("%.3f", CDTIME_T_TO_DOUBLE (vl->time));
990 for (i = 0; i < ds->ds_num; i++)
991 {
992 if (ds->ds[i].type == DS_TYPE_GAUGE)
993 BUFFER_ADD (":"GAUGE_FORMAT, vl->values[i].gauge);
994 else if (store_rates)
995 {
996 if (rates == NULL)
997 rates = uc_get_rate (ds, vl);
998 if (rates == NULL)
999 {
1000 WARNING ("format_values: uc_get_rate failed.");
1001 return (-1);
1002 }
1003 BUFFER_ADD (":"GAUGE_FORMAT, rates[i]);
1004 }
1005 else if (ds->ds[i].type == DS_TYPE_COUNTER)
1006 BUFFER_ADD (":%llu", vl->values[i].counter);
1007 else if (ds->ds[i].type == DS_TYPE_DERIVE)
1008 BUFFER_ADD (":%"PRIi64, vl->values[i].derive);
1009 else if (ds->ds[i].type == DS_TYPE_ABSOLUTE)
1010 BUFFER_ADD (":%"PRIu64, vl->values[i].absolute);
1011 else
1012 {
1013 ERROR ("format_values: Unknown data source type: %i",
1014 ds->ds[i].type);
1015 sfree (rates);
1016 return (-1);
1017 }
1018 } /* for ds->ds_num */
1020 #undef BUFFER_ADD
1022 sfree (rates);
1023 return (0);
1024 } /* }}} int format_values */
1026 int parse_identifier (char *str, char **ret_host,
1027 char **ret_plugin, char **ret_plugin_instance,
1028 char **ret_type, char **ret_type_instance)
1029 {
1030 char *hostname = NULL;
1031 char *plugin = NULL;
1032 char *plugin_instance = NULL;
1033 char *type = NULL;
1034 char *type_instance = NULL;
1036 hostname = str;
1037 if (hostname == NULL)
1038 return (-1);
1040 plugin = strchr (hostname, '/');
1041 if (plugin == NULL)
1042 return (-1);
1043 *plugin = '\0'; plugin++;
1045 type = strchr (plugin, '/');
1046 if (type == NULL)
1047 return (-1);
1048 *type = '\0'; type++;
1050 plugin_instance = strchr (plugin, '-');
1051 if (plugin_instance != NULL)
1052 {
1053 *plugin_instance = '\0';
1054 plugin_instance++;
1055 }
1057 type_instance = strchr (type, '-');
1058 if (type_instance != NULL)
1059 {
1060 *type_instance = '\0';
1061 type_instance++;
1062 }
1064 *ret_host = hostname;
1065 *ret_plugin = plugin;
1066 *ret_plugin_instance = plugin_instance;
1067 *ret_type = type;
1068 *ret_type_instance = type_instance;
1069 return (0);
1070 } /* int parse_identifier */
1072 int parse_identifier_vl (const char *str, value_list_t *vl) /* {{{ */
1073 {
1074 char str_copy[6 * DATA_MAX_NAME_LEN];
1075 char *host = NULL;
1076 char *plugin = NULL;
1077 char *plugin_instance = NULL;
1078 char *type = NULL;
1079 char *type_instance = NULL;
1080 int status;
1082 if ((str == NULL) || (vl == NULL))
1083 return (EINVAL);
1085 sstrncpy (str_copy, str, sizeof (str_copy));
1087 status = parse_identifier (str_copy, &host,
1088 &plugin, &plugin_instance,
1089 &type, &type_instance);
1090 if (status != 0)
1091 return (status);
1093 sstrncpy (vl->host, host, sizeof (vl->host));
1094 sstrncpy (vl->plugin, plugin, sizeof (vl->plugin));
1095 sstrncpy (vl->plugin_instance,
1096 (plugin_instance != NULL) ? plugin_instance : "",
1097 sizeof (vl->plugin_instance));
1098 sstrncpy (vl->type, type, sizeof (vl->type));
1099 sstrncpy (vl->type_instance,
1100 (type_instance != NULL) ? type_instance : "",
1101 sizeof (vl->type_instance));
1103 return (0);
1104 } /* }}} int parse_identifier_vl */
1106 int parse_value (const char *value_orig, value_t *ret_value, int ds_type)
1107 {
1108 char *value;
1109 char *endptr = NULL;
1110 size_t value_len;
1112 if (value_orig == NULL)
1113 return (EINVAL);
1115 value = strdup (value_orig);
1116 if (value == NULL)
1117 return (ENOMEM);
1118 value_len = strlen (value);
1120 while ((value_len > 0) && isspace ((int) value[value_len - 1]))
1121 {
1122 value[value_len - 1] = 0;
1123 value_len--;
1124 }
1126 switch (ds_type)
1127 {
1128 case DS_TYPE_COUNTER:
1129 ret_value->counter = (counter_t) strtoull (value, &endptr, 0);
1130 break;
1132 case DS_TYPE_GAUGE:
1133 ret_value->gauge = (gauge_t) strtod (value, &endptr);
1134 break;
1136 case DS_TYPE_DERIVE:
1137 ret_value->derive = (derive_t) strtoll (value, &endptr, 0);
1138 break;
1140 case DS_TYPE_ABSOLUTE:
1141 ret_value->absolute = (absolute_t) strtoull (value, &endptr, 0);
1142 break;
1144 default:
1145 sfree (value);
1146 ERROR ("parse_value: Invalid data source type: %i.", ds_type);
1147 return -1;
1148 }
1150 if (value == endptr) {
1151 ERROR ("parse_value: Failed to parse string as %s: %s.",
1152 DS_TYPE_TO_STRING (ds_type), value);
1153 sfree (value);
1154 return -1;
1155 }
1156 else if ((NULL != endptr) && ('\0' != *endptr))
1157 INFO ("parse_value: Ignoring trailing garbage \"%s\" after %s value. "
1158 "Input string was \"%s\".",
1159 endptr, DS_TYPE_TO_STRING (ds_type), value_orig);
1161 sfree (value);
1162 return 0;
1163 } /* int parse_value */
1165 int parse_values (char *buffer, value_list_t *vl, const data_set_t *ds)
1166 {
1167 size_t i;
1168 char *dummy;
1169 char *ptr;
1170 char *saveptr;
1172 if ((buffer == NULL) || (vl == NULL) || (ds == NULL))
1173 return EINVAL;
1175 i = 0;
1176 dummy = buffer;
1177 saveptr = NULL;
1178 vl->time = 0;
1179 while ((ptr = strtok_r (dummy, ":", &saveptr)) != NULL)
1180 {
1181 dummy = NULL;
1183 if (i >= vl->values_len)
1184 {
1185 /* Make sure i is invalid. */
1186 i = 0;
1187 break;
1188 }
1190 if (vl->time == 0)
1191 {
1192 if (strcmp ("N", ptr) == 0)
1193 vl->time = cdtime ();
1194 else
1195 {
1196 char *endptr = NULL;
1197 double tmp;
1199 errno = 0;
1200 tmp = strtod (ptr, &endptr);
1201 if ((errno != 0) /* Overflow */
1202 || (endptr == ptr) /* Invalid string */
1203 || (endptr == NULL) /* This should not happen */
1204 || (*endptr != 0)) /* Trailing chars */
1205 return (-1);
1207 vl->time = DOUBLE_TO_CDTIME_T (tmp);
1208 }
1210 continue;
1211 }
1213 if ((strcmp ("U", ptr) == 0) && (ds->ds[i].type == DS_TYPE_GAUGE))
1214 vl->values[i].gauge = NAN;
1215 else if (0 != parse_value (ptr, &vl->values[i], ds->ds[i].type))
1216 return -1;
1218 i++;
1219 } /* while (strtok_r) */
1221 if ((ptr != NULL) || (i == 0))
1222 return (-1);
1223 return (0);
1224 } /* int parse_values */
1226 #if !HAVE_GETPWNAM_R
1227 int getpwnam_r (const char *name, struct passwd *pwbuf, char *buf,
1228 size_t buflen, struct passwd **pwbufp)
1229 {
1230 int status = 0;
1231 struct passwd *pw;
1233 memset (pwbuf, '\0', sizeof (struct passwd));
1235 pthread_mutex_lock (&getpwnam_r_lock);
1237 do
1238 {
1239 pw = getpwnam (name);
1240 if (pw == NULL)
1241 {
1242 status = (errno != 0) ? errno : ENOENT;
1243 break;
1244 }
1246 #define GETPWNAM_COPY_MEMBER(member) \
1247 if (pw->member != NULL) \
1248 { \
1249 int len = strlen (pw->member); \
1250 if (len >= buflen) \
1251 { \
1252 status = ENOMEM; \
1253 break; \
1254 } \
1255 sstrncpy (buf, pw->member, buflen); \
1256 pwbuf->member = buf; \
1257 buf += (len + 1); \
1258 buflen -= (len + 1); \
1259 }
1260 GETPWNAM_COPY_MEMBER(pw_name);
1261 GETPWNAM_COPY_MEMBER(pw_passwd);
1262 GETPWNAM_COPY_MEMBER(pw_gecos);
1263 GETPWNAM_COPY_MEMBER(pw_dir);
1264 GETPWNAM_COPY_MEMBER(pw_shell);
1266 pwbuf->pw_uid = pw->pw_uid;
1267 pwbuf->pw_gid = pw->pw_gid;
1269 if (pwbufp != NULL)
1270 *pwbufp = pwbuf;
1271 } while (0);
1273 pthread_mutex_unlock (&getpwnam_r_lock);
1275 return (status);
1276 } /* int getpwnam_r */
1277 #endif /* !HAVE_GETPWNAM_R */
1279 int notification_init (notification_t *n, int severity, const char *message,
1280 const char *host,
1281 const char *plugin, const char *plugin_instance,
1282 const char *type, const char *type_instance)
1283 {
1284 memset (n, '\0', sizeof (notification_t));
1286 n->severity = severity;
1288 if (message != NULL)
1289 sstrncpy (n->message, message, sizeof (n->message));
1290 if (host != NULL)
1291 sstrncpy (n->host, host, sizeof (n->host));
1292 if (plugin != NULL)
1293 sstrncpy (n->plugin, plugin, sizeof (n->plugin));
1294 if (plugin_instance != NULL)
1295 sstrncpy (n->plugin_instance, plugin_instance,
1296 sizeof (n->plugin_instance));
1297 if (type != NULL)
1298 sstrncpy (n->type, type, sizeof (n->type));
1299 if (type_instance != NULL)
1300 sstrncpy (n->type_instance, type_instance,
1301 sizeof (n->type_instance));
1303 return (0);
1304 } /* int notification_init */
1306 int walk_directory (const char *dir, dirwalk_callback_f callback,
1307 void *user_data, int include_hidden)
1308 {
1309 struct dirent *ent;
1310 DIR *dh;
1311 int success;
1312 int failure;
1314 success = 0;
1315 failure = 0;
1317 if ((dh = opendir (dir)) == NULL)
1318 {
1319 char errbuf[1024];
1320 ERROR ("walk_directory: Cannot open '%s': %s", dir,
1321 sstrerror (errno, errbuf, sizeof (errbuf)));
1322 return -1;
1323 }
1325 while ((ent = readdir (dh)) != NULL)
1326 {
1327 int status;
1329 if (include_hidden)
1330 {
1331 if ((strcmp (".", ent->d_name) == 0)
1332 || (strcmp ("..", ent->d_name) == 0))
1333 continue;
1334 }
1335 else /* if (!include_hidden) */
1336 {
1337 if (ent->d_name[0]=='.')
1338 continue;
1339 }
1341 status = (*callback) (dir, ent->d_name, user_data);
1342 if (status != 0)
1343 failure++;
1344 else
1345 success++;
1346 }
1348 closedir (dh);
1350 if ((success == 0) && (failure > 0))
1351 return (-1);
1352 return (0);
1353 }
1355 ssize_t read_file_contents (const char *filename, char *buf, size_t bufsize)
1356 {
1357 FILE *fh;
1358 ssize_t ret;
1360 fh = fopen (filename, "r");
1361 if (fh == NULL)
1362 return (-1);
1364 ret = (ssize_t) fread (buf, 1, bufsize, fh);
1365 if ((ret == 0) && (ferror (fh) != 0))
1366 {
1367 ERROR ("read_file_contents: Reading file \"%s\" failed.",
1368 filename);
1369 ret = -1;
1370 }
1372 fclose(fh);
1373 return (ret);
1374 }
1376 counter_t counter_diff (counter_t old_value, counter_t new_value)
1377 {
1378 counter_t diff;
1380 if (old_value > new_value)
1381 {
1382 if (old_value <= 4294967295U)
1383 diff = (4294967295U - old_value) + new_value + 1;
1384 else
1385 diff = (18446744073709551615ULL - old_value) + new_value + 1;
1386 }
1387 else
1388 {
1389 diff = new_value - old_value;
1390 }
1392 return (diff);
1393 } /* counter_t counter_diff */
1395 int rate_to_value (value_t *ret_value, gauge_t rate, /* {{{ */
1396 rate_to_value_state_t *state,
1397 int ds_type, cdtime_t t)
1398 {
1399 gauge_t delta_gauge;
1400 cdtime_t delta_t;
1402 if (ds_type == DS_TYPE_GAUGE)
1403 {
1404 state->last_value.gauge = rate;
1405 state->last_time = t;
1407 *ret_value = state->last_value;
1408 return (0);
1409 }
1411 /* Counter and absolute can't handle negative rates. Reset "last time"
1412 * to zero, so that the next valid rate will re-initialize the
1413 * structure. */
1414 if ((rate < 0.0)
1415 && ((ds_type == DS_TYPE_COUNTER)
1416 || (ds_type == DS_TYPE_ABSOLUTE)))
1417 {
1418 memset (state, 0, sizeof (*state));
1419 return (EINVAL);
1420 }
1422 /* Another invalid state: The time is not increasing. */
1423 if (t <= state->last_time)
1424 {
1425 memset (state, 0, sizeof (*state));
1426 return (EINVAL);
1427 }
1429 delta_t = t - state->last_time;
1430 delta_gauge = (rate * CDTIME_T_TO_DOUBLE (delta_t)) + state->residual;
1432 /* Previous value is invalid. */
1433 if (state->last_time == 0) /* {{{ */
1434 {
1435 if (ds_type == DS_TYPE_DERIVE)
1436 {
1437 state->last_value.derive = (derive_t) rate;
1438 state->residual = rate - ((gauge_t) state->last_value.derive);
1439 }
1440 else if (ds_type == DS_TYPE_COUNTER)
1441 {
1442 state->last_value.counter = (counter_t) rate;
1443 state->residual = rate - ((gauge_t) state->last_value.counter);
1444 }
1445 else if (ds_type == DS_TYPE_ABSOLUTE)
1446 {
1447 state->last_value.absolute = (absolute_t) rate;
1448 state->residual = rate - ((gauge_t) state->last_value.absolute);
1449 }
1450 else
1451 {
1452 assert (23 == 42);
1453 }
1455 state->last_time = t;
1456 return (EAGAIN);
1457 } /* }}} */
1459 if (ds_type == DS_TYPE_DERIVE)
1460 {
1461 derive_t delta_derive = (derive_t) delta_gauge;
1463 state->last_value.derive += delta_derive;
1464 state->residual = delta_gauge - ((gauge_t) delta_derive);
1465 }
1466 else if (ds_type == DS_TYPE_COUNTER)
1467 {
1468 counter_t delta_counter = (counter_t) delta_gauge;
1470 state->last_value.counter += delta_counter;
1471 state->residual = delta_gauge - ((gauge_t) delta_counter);
1472 }
1473 else if (ds_type == DS_TYPE_ABSOLUTE)
1474 {
1475 absolute_t delta_absolute = (absolute_t) delta_gauge;
1477 state->last_value.absolute = delta_absolute;
1478 state->residual = delta_gauge - ((gauge_t) delta_absolute);
1479 }
1480 else
1481 {
1482 assert (23 == 42);
1483 }
1485 state->last_time = t;
1486 *ret_value = state->last_value;
1487 return (0);
1488 } /* }}} value_t rate_to_value */
1490 int value_to_rate (gauge_t *ret_rate, /* {{{ */
1491 value_t value, int ds_type, cdtime_t t, value_to_rate_state_t *state)
1492 {
1493 gauge_t interval;
1495 /* Another invalid state: The time is not increasing. */
1496 if (t <= state->last_time)
1497 {
1498 memset (state, 0, sizeof (*state));
1499 return (EINVAL);
1500 }
1502 interval = CDTIME_T_TO_DOUBLE(t - state->last_time);
1504 /* Previous value is invalid. */
1505 if (state->last_time == 0)
1506 {
1507 state->last_value = value;
1508 state->last_time = t;
1509 return (EAGAIN);
1510 }
1512 switch (ds_type) {
1513 case DS_TYPE_DERIVE: {
1514 derive_t diff = value.derive - state->last_value.derive;
1515 *ret_rate = ((gauge_t) diff) / ((gauge_t) interval);
1516 break;
1517 }
1518 case DS_TYPE_GAUGE: {
1519 *ret_rate = value.gauge;
1520 break;
1521 }
1522 case DS_TYPE_COUNTER: {
1523 counter_t diff = counter_diff (state->last_value.counter, value.counter);
1524 *ret_rate = ((gauge_t) diff) / ((gauge_t) interval);
1525 break;
1526 }
1527 case DS_TYPE_ABSOLUTE: {
1528 absolute_t diff = value.absolute;
1529 *ret_rate = ((gauge_t) diff) / ((gauge_t) interval);
1530 break;
1531 }
1532 default:
1533 return EINVAL;
1534 }
1536 state->last_value = value;
1537 state->last_time = t;
1538 return (0);
1539 } /* }}} value_t rate_to_value */
1541 int service_name_to_port_number (const char *service_name)
1542 {
1543 struct addrinfo *ai_list;
1544 struct addrinfo *ai_ptr;
1545 struct addrinfo ai_hints;
1546 int status;
1547 int service_number;
1549 if (service_name == NULL)
1550 return (-1);
1552 ai_list = NULL;
1553 memset (&ai_hints, 0, sizeof (ai_hints));
1554 ai_hints.ai_family = AF_UNSPEC;
1556 status = getaddrinfo (/* node = */ NULL, service_name,
1557 &ai_hints, &ai_list);
1558 if (status != 0)
1559 {
1560 ERROR ("service_name_to_port_number: getaddrinfo failed: %s",
1561 gai_strerror (status));
1562 return (-1);
1563 }
1565 service_number = -1;
1566 for (ai_ptr = ai_list; ai_ptr != NULL; ai_ptr = ai_ptr->ai_next)
1567 {
1568 if (ai_ptr->ai_family == AF_INET)
1569 {
1570 struct sockaddr_in *sa;
1572 sa = (void *) ai_ptr->ai_addr;
1573 service_number = (int) ntohs (sa->sin_port);
1574 }
1575 else if (ai_ptr->ai_family == AF_INET6)
1576 {
1577 struct sockaddr_in6 *sa;
1579 sa = (void *) ai_ptr->ai_addr;
1580 service_number = (int) ntohs (sa->sin6_port);
1581 }
1583 if ((service_number > 0) && (service_number <= 65535))
1584 break;
1585 }
1587 freeaddrinfo (ai_list);
1589 if ((service_number > 0) && (service_number <= 65535))
1590 return (service_number);
1591 return (-1);
1592 } /* int service_name_to_port_number */
1594 int strtoderive (const char *string, derive_t *ret_value) /* {{{ */
1595 {
1596 derive_t tmp;
1597 char *endptr;
1599 if ((string == NULL) || (ret_value == NULL))
1600 return (EINVAL);
1602 errno = 0;
1603 endptr = NULL;
1604 tmp = (derive_t) strtoll (string, &endptr, /* base = */ 0);
1605 if ((endptr == string) || (errno != 0))
1606 return (-1);
1608 *ret_value = tmp;
1609 return (0);
1610 } /* }}} int strtoderive */
1612 int strtogauge (const char *string, gauge_t *ret_value) /* {{{ */
1613 {
1614 gauge_t tmp;
1615 char *endptr = NULL;
1617 if ((string == NULL) || (ret_value == NULL))
1618 return (EINVAL);
1620 errno = 0;
1621 endptr = NULL;
1622 tmp = (gauge_t) strtod (string, &endptr);
1623 if (errno != 0)
1624 return (errno);
1625 else if ((endptr == NULL) || (*endptr != 0))
1626 return (EINVAL);
1628 *ret_value = tmp;
1629 return (0);
1630 } /* }}} int strtogauge */
1632 int strarray_add (char ***ret_array, size_t *ret_array_len, char const *str) /* {{{ */
1633 {
1634 char **array;
1635 size_t array_len = *ret_array_len;
1637 if (str == NULL)
1638 return (EINVAL);
1640 array = realloc (*ret_array,
1641 (array_len + 1) * sizeof (*array));
1642 if (array == NULL)
1643 return (ENOMEM);
1644 *ret_array = array;
1646 array[array_len] = strdup (str);
1647 if (array[array_len] == NULL)
1648 return (ENOMEM);
1650 array_len++;
1651 *ret_array_len = array_len;
1652 return (0);
1653 } /* }}} int strarray_add */
1655 void strarray_free (char **array, size_t array_len) /* {{{ */
1656 {
1657 size_t i;
1659 for (i = 0; i < array_len; i++)
1660 sfree (array[i]);
1661 sfree (array);
1662 } /* }}} void strarray_free */