libfossil
fossil-util.h
Go to the documentation of this file.
1 /* -*- Mode: C; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
2 /* vim: set ts=2 et sw=2 tw=80: */
3 #if !defined(NET_FOSSIL_SCM_FSL_UTIL_H_INCLUDED)
4 #define NET_FOSSIL_SCM_FSL_UTIL_H_INCLUDED
5 /*
6  Copyright (c) 2014 D. Richard Hipp
7 
8  This program is free software; you can redistribute it and/or
9  modify it under the terms of the Simplified BSD License (also
10  known as the "2-Clause License" or "FreeBSD License".)
11 
12  This program is distributed in the hope that it will be useful,
13  but without any warranty; without even the implied warranty of
14  merchantability or fitness for a particular purpose.
15 
16  Author contact information:
17  drh@hwaci.com
18  http://www.hwaci.com/drh/
19 
20  ******************************************************************************
21  */
22 
23 /** @file fossil-util.h
24 
25  This file declares a number of utility classes and routines used by
26  libfossil. All of them considered "public", suitable for direct use
27  by client code.
28 
29 */
30 
31 #include "fossil-config.h" /* MUST come first b/c of config macros */
32 #include <stdio.h> /* FILE type */
33 #include <stdarg.h> /* va_list */
34 #include <time.h> /* tm struct */
35 #if defined(__cplusplus)
36 extern "C" {
37 #endif
39 typedef struct fsl_buffer fsl_buffer;
40 typedef struct fsl_error fsl_error;
42 typedef struct fsl_fstat fsl_fstat;
43 typedef struct fsl_list fsl_list;
44 typedef struct fsl_outputer fsl_outputer;
45 typedef struct fsl_state fsl_state;
46 typedef struct fsl_id_bag fsl_id_bag;
47 
48 /**
49  A typedef for comparison function used by standard C
50  routines such as qsort(). It is provided here primarily
51  to simplify documentation of other APIs. Concrete
52  implementations must compare lhs and rhs, returning negative,
53  0, or right depending on whether lhs is less than, equal to,
54  or greater than rhs.
55 
56  Implementations might need to be able to deal with NULL
57  arguments. That depends on the routine which uses the comparison
58  function.
59 */
60 typedef int (*fsl_generic_cmp_f)( void const * lhs, void const * rhs );
61 
62 /**
63  fsl_uuid_str and fsl_uuid_cstr are "for documentation and
64  readability purposes" typedefs used to denote strings which the
65  API requires to be in the form of Fossil UUID strings. Such
66  strings are exactly FSL_UUID_STRLEN bytes long plus a
67  terminating NUL byte and contain only lower-case hexadecimal
68  bytes. Where this typedef is used, the library requires,
69  enforces, and/or assumes (at different times) that fsl_is_uuid()
70  returns true for such strings (if they are not NULL, though not
71  all contexts allow a NULL UUID). These typedef are _not_ used to
72  denote arguments which may refer to partial UUIDs or symbolic
73  names, only 100% bonafide Fossil UUIDs (which are different from
74  RFC4122 UUIDs).
75 
76  The API guarantees that this typedef will always be (char *) and
77  that fsl_uuid_cstr will always ben (char const *), and thus it
78  is safe/portable to use those type instead of thse. These
79  typedefs serve only to improve the readability of certain APIs
80  by implying (through the use of this typedef) the preconditions
81  defined for UUID strings.
82 
83  @see fsl_is_uuid()
84 */
85 typedef char * fsl_uuid_str;
86 
87 /**
88  The const counterpart of fsl_uuid_str.
89 
90  @see fsl_is_uuid()
91 */
92 typedef char const * fsl_uuid_cstr;
93 
94 /**
95  Returns true (non-0) if str is not NULL, is exactly
96  FSL_UUID_STRLEN bytes long (meaning its final byte is a NUL),
97  and contains only lower-case hexadecimal characters, else
98  returns false (0).
99 
100  Note that Fossil UUIDs are not RFC4122 UUIDs, but are SHA1
101  hash strings. Don't let that disturb you. As Tim Berners-Lee
102  writes:
103 
104  'The assertion that the space of URIs is a universal space
105  sometimes encounters opposition from those who feel there should
106  not be one universal space. These people need not oppose the
107  concept because it is not of a single universal space: Indeed,
108  the fact that URIs form universal space does not prevent anyone
109  else from forming their own universal space, which of course by
110  definition would be able to envelop within it as a subset the
111  universal URI space. Therefore the web meets the "independent
112  design" test, that if a similar system had been concurrently and
113  independently invented elsewhere, in such a way that the
114  arbitrary design decisions were made differently, when they met
115  later, the two systems could be made to interoperate.'
116 
117  Source: http://www.w3.org/DesignIssues/Axioms.html
118 
119  (Just mentally translate URI as UUID.)
120 */
121 FSL_EXPORT char fsl_is_uuid(char const * str);
122 
123 /**
124  Expects str to be a string containing an unsigned decimal
125  value. Returns its decoded value, or -1 on error.
126 */
127 FSL_EXPORT fsl_size_t fsl_str_to_size(char const * str);
128 
129 /**
130  Expects str to be a string containing a decimal value,
131  optionally with a leading sign. Returns its decoded value, or
132  dflt if !str or on error.
133 */
134 FSL_EXPORT fsl_int_t fsl_str_to_int(char const * str, fsl_int_t dflt);
135 
136 
137 /**
138  Generic list container type. This is used heavily by the Fossil
139  API for storing arrays of dynamically-allocated objects. It is
140  not useful as a non-pointer-array replacement.
141 
142  It is up to the APIs using this type to manage the entry count
143  member and use fsl_list_reserve() to manage the "capacity"
144  member.
145 
146  @see fsl_list_reserve()
147  @see fsl_list_append()
148  @see fsl_list_visit()
149 */
150 struct fsl_list {
151  /**
152  Array of entries. It contains this->capacity entries,
153  this->count of which are "valid" (in use).
154  */
155  void ** list;
156  /**
157  Number of "used" entries in the list.
158  */
160  /**
161  Number of slots allocated in this->list. Use fsl_list_reserve()
162  to modify this. Doing so might move the this->list pointer but
163  the values it points to will stay stable.
164  */
166 };
167 
168 /**
169  Empty-initialized fsl_list structure, intended for const-copy
170  initialization.
171 */
172 #define fsl_list_empty_m { NULL, 0, 0 }
173 /**
174  Empty-initialized fsl_list structure, intended for copy
175  initialization.
176 */
178 
179 
180 /**
181  Generic interface for finalizing/freeing memory. Intended
182  primarily for use as a destructor/finalizer for high-level
183  structs. Implementations must semantically behave like free(mem),
184  regardless of whether or not they actually free the memory. At
185  the very least, they generally should clean up any memory owned by
186  mem (e.g. db resources or buffers), even if they do not free() mem.
187  some implementations assume that mem is stack-allocated
188  and they only clean up resources owned by mem.
189 
190  The state parameter is any state needed by the finalizer
191  (e.g. a memory allocation context) and mem is the memory which is
192  being finalized.
193 
194  The exact interpretaion of the state and mem are of course
195  implementation-specific.
196 */
197 typedef void (*fsl_finalizer_f)( void * state, void * mem );
198 
199 /**
200  Generic interface for memory finalizers.
201 */
203  /**
204  State to be passed as the first argument to f().
205  */
206  void * state;
207  /**
208  Finalizer function. Should be called like this->f( this->state, ... ).
209  */
211 };
212 
213 /** Empty-initialized fsl_finalizer struct. */
214 #define fsl_finalizer_empty_m {NULL,NULL}
215 
216 /**
217  fsl_finalizer_f() impl which requires that mem be-a
218  (fsl_buffer*). This function frees all memory associated with
219  that buffer and zeroes out the structure, but does not free mem
220  (because it is rare that fsl_buffers are created on the
221  heap). The state parameter is ignored.
222 */
223 FSL_EXPORT int fsl_finalizer_f_buffer( void * state, void * mem );
224 
225 
226 /**
227  Generic state-with-finalizer holder. Used for binding
228  client-specified state to another other object, such that a
229  client-specified finalizer is called with the other object is
230  cleaned up.
231 */
232 struct fsl_state {
233  /**
234  Arbitrary context-dependent state.
235  */
236  void * state;
237  /**
238  Finalizer for this->state. If used, it should be called like:
239 
240  @code
241  this->finalize.f( this->finalize.state, this->state );
242  @endcode
243 
244  After which this->state must be treated as if it has been
245  free(3)'d.
246  */
248 };
249 
250 /** Empty-initialized fsl_state struct. */
251 #define fsl_state_empty_m {NULL,fsl_finalizer_empty_m}
252 
253 /**
254  Empty-initialized fsl_state struct, intended for
255  copy-initializing.
256 */
258 
259 
260 /**
261  Generic interface for streaming out data. Implementations must
262  write n bytes from s to their destination channel and return 0 on
263  success, non-0 on error (assumed to be a value from the fsl_rc_t
264  enum). The state parameter is the implementation-specified
265  output channel.
266 
267  Potential TODO: change the final argument to a pointer, with
268  semantics similar to fsl_input_f(): at call-time n is the number
269  of bytes to output, and on returning n is the number of bytes
270  actually written. This would allow, e.g. the fsl_zip_writer APIs
271  to be able to stream a ZIP file (they have to know the real size
272  of the output, and this interface doesn't support that
273  operation).
274 */
275 typedef int (*fsl_output_f)( void * state,
276  void const * src, fsl_size_t n );
277 
278 
279 /**
280  Generic interface for flushing arbitrary output streams. Must
281  return 0 on success, non-0 on error, but the result code
282  "should" (to avoid downstream confusion) be one of the fsl_rc_t
283  values. When in doubt, return FSL_RC_IO on error. The
284  interpretation of the state parameter is
285  implementation-specific.
286 */
287 typedef int (*fsl_flush_f)(void * state);
288 
289 /**
290  Generic interface for streaming in data. Implementations must
291  read (at most) *n bytes from their input, copy it to dest, assign
292  *n to the number of bytes actually read, return 0 on success, and
293  return non-0 on error (assumed to be a value from the fsl_rc_t
294  enum). When called, *n is the max length to read. On return, *n
295  is the actual amount read. The state parameter is the
296  implementation-specified input file/buffer/whatever channel.
297 */
298 typedef int (*fsl_input_f)( void * state, void * dest, fsl_size_t * n );
299 
300 /**
301  fsl_output_f() implementation which requires state to be a
302  writeable (FILE*) handle. Is a no-op (returning 0) if
303  !n. Returns FSL_RC_MISUSE if !state or !src.
304 */
305 FSL_EXPORT int fsl_output_f_FILE( void * state, void const * src, fsl_size_t n );
306 
307 /**
308  fsl_output_f() implementation which requires state to be a
309  (fsl_cx*) to which this routine simply redirects the output via
310  fsl_output(). Is a no-op (returning 0) if !n. Returns
311  FSL_RC_MISUSE if !state or !src.
312 */
313 FSL_EXPORT int fsl_output_f_fsl_cx(void * state, void const * src, fsl_size_t n );
314 
315 
316 /**
317  An interface which encapsulates data for managing an output
318  destination, primarily intended for use with fsl_output(). Why
319  abstract it to this level? So that we can do interesting things
320  like output to buffers, files, sockets, etc., using the core
321  output mechanism. e.g. so script bindings can send their output
322  to the same channel used by the library and other library
323  clients.
324 */
325 struct fsl_outputer {
326  /**
327  Output channel.
328  */
330  /**
331  flush() implementation.
332  */
334  /**
335  State to be used when calling this->out(), namely:
336  this->out( this->state.state, ... ).
337  */
339 };
340 /** Empty-initialized fsl_outputer instance. */
341 #define fsl_outputer_empty_m {NULL,NULL,fsl_state_empty_m}
342 /**
343  Empty-initialized fsl_outputer instance, intended for
344  copy-initializing.
345 */
347 
348 /**
349  A fsl_outputer instance which is initialized to output to a
350  (FILE*). To use it, this value then set the copy's state.state
351  member to an opened-for-write (FILE*) handle. By default it will
352  use stdout. Its finalizer (if called!) will fclose(3)
353  self.state.state if self.state.state is not one of (stdout,
354  stderr). To disable the closing behaviour (and not close the
355  file), set self.state.finalize.f to NULL (but then be sure that
356  the file handle outlives this object and to fclose(3) it when
357  finished with it).
358 */
360 
361 /**
362  fsl_outputer initializer which uses fsl_flush_f_FILE(),
363  fsl_output_f_FILE(), and fsl_finalizer_f_FILE().
364 */
365 #define fsl_outputer_FILE_m { \
366  fsl_output_f_FILE, \
367  fsl_flush_f_FILE, \
368  {/*state*/ \
369  NULL, \
370  {NULL,fsl_finalizer_f_FILE} \
371  } \
372  }
373 /**
374  Generic stateful alloc/free/realloc() interface.
375 
376  Implementations must behave as follows:
377 
378  - If 0==n then semantically behave like free(3) and return
379  NULL.
380 
381  - If 0!=n and !mem then semantically behave like malloc(3), returning
382  newly-allocated memory on success and NULL on error.
383 
384  - If 0!=n and NULL!=mem then semantically behave like
385  realloc(3). Note that realloc specifies: "If n was equal to 0,
386  either NULL or a pointer suitable to be passed to free() is
387  returned." Which is kind of useless, and thus implementations
388  MUST return NULL when n==0.
389 */
390 typedef void *(*fsl_realloc_f)(void * state, void * mem, fsl_size_t n);
391 
392 /**
393  Holds an allocator function and its related state.
394 */
396  /**
397  Base allocator function. It must be passed this->state
398  as its first parameter.
399  */
401  /**
402  State intended to be passed as the first parameter to
403  this->f().
404  */
405  void * state;
406 };
407 
408 /** Empty-initialized fsl_allocator instance. */
409 #define fsl_allocator_empty_m {NULL,NULL}
410 
411 
412 /**
413  A fsl_realloc_f() implementation which uses the standard
414  malloc()/free()/realloc(). The state parameter is ignored.
415 */
416 FSL_EXPORT void * fsl_realloc_f_stdalloc(void * state, void * mem, fsl_size_t n);
417 
418 
419 /**
420  Semantically behaves like malloc(3), but may introduce instrumentation,
421  error checking, or similar.
422 */
423 void * fsl_malloc( fsl_size_t n )
424 #ifdef __GNUC__
425  __attribute__ ((malloc))
426 #endif
427  ;
428 
429 /**
430  Semantically behaves like free(3), but may introduce instrumentation,
431  error checking, or similar.
432 */
433 FSL_EXPORT void fsl_free( void * mem );
434 
435 /**
436  Behaves like realloc(3). Clarifications on the behaviour (because
437  the standard has one case of unfortunate wording involving what
438  it returns when n==0):
439 
440  - If passed (NULL, n>0) then it semantically behaves like
441  fsl_malloc(f, n).
442 
443  - If 0==n then it semantically behaves like free(2) and returns
444  NULL (clarifying the aforementioned wording problem).
445 
446  - If passed (non-NULL, n) then it semantically behaves like
447  realloc(mem,n).
448 
449 */
450 FSL_EXPORT void * fsl_realloc( void * mem, fsl_size_t n );
451 
452 /**
453  A fsl_flush_f() impl which expects _FILE to be-a (FILE*) opened
454  for writing, which this function passes the call on to
455  fflush(). If fflush() returns 0, so does this function, else it
456  returns non-0.
457 */
458 FSL_EXPORT int fsl_flush_f_FILE(void * _FILE);
459 
460 /**
461  A fsl_finalizer_f() impl which requires that mem be-a (FILE*).
462  This function passes that FILE to fsl_fclose(). The state
463  parameter is ignored.
464 */
465 FSL_EXPORT void fsl_finalizer_f_FILE( void * state, void * mem );
466 
467 /**
468  A fsl_output_f() impl which requires state to be-a (FILE*), which
469  this function passes the call on to fwrite(). Returns 0 on
470  success, FSL_RC_IO on error.
471 */
472 FSL_EXPORT int fsl_output_f_FILE( void * state, void const * src, fsl_size_t n );
473 
474 /**
475  A fsl_output_f() impl which requires state to be-a (fsl_buffer*),
476  which this function passes to fsl_buffer_append(). Returns 0 on
477  success, FSL_RC_OOM (probably) on error.
478 */
479 FSL_EXPORT int fsl_output_f_buffer( void * state, void const * src, fsl_size_t n );
480 
481 /**
482  A fsl_input_f() implementation which requires that state be
483  a readable (FILE*) handle.
484 */
485 FSL_EXPORT int fsl_input_f_FILE( void * state, void * dest, fsl_size_t * n );
486 
487 /**
488  A fsl_input_f() implementation which requires that state be a
489  readable (fsl_buffer*) handle. The buffer's cursor member is
490  updated to track input postion, but that is the only
491  modification made by this routine. Thus the user may need to
492  reset the cursor to 0 if he wishes to start consuming the buffer
493  at its starting point. Subsequent calls to this function will
494  increment the cursor by the number of bytes returned via *n.
495  The buffer's "used" member is used to determine the logical end
496  of input.
497 
498  Returns 0 on success and has no error conditions except for
499  invalid arguments, which result in undefined beavhiour. Results
500  are undefined if any argument is NULL.
501 
502  Tip (and warning): sometimes a routine might have a const buffer
503  handle which it would like to use in conjunction with this
504  routine but cannot withou violating constness. Here's a crude
505  workaround:
506 
507  @code
508  fsl_buffer kludge = *originalConstBuffer; // normally this is dangerous!
509  rc = some_func( fsl_input_f_buffer, &kludge, ... );
510  assert(kludge.mem==originalConstBuffer->mem); // See notes below.
511  // DO NOT clean up the kludge buffer. Memory belongs to the original!
512  @endcode
513 
514  That is ONLY (ONLY! ONLY!! ONLY!!!) legal because this routine
515  modifies only fsl_buffer::cursor. Such a workaround is STRICLY
516  ILLEGAL if there is ANY CHANCE WHATSOEVER that the buffer's
517  memory will be modified, in particular if it will be resized,
518  and such use will eventually leak and/or corrupt memory.
519 */
520 FSL_EXPORT int fsl_input_f_buffer( void * state, void * dest, fsl_size_t * n );
521 
522 
523 /**
524  A generic streaming routine which copies data from an
525  fsl_input_f() to an fsl_outpuf_f().
526 
527  Reads all data from inF() in chunks of an unspecified size and
528  passes them on to outF(). It reads until inF() returns fewer
529  bytes than requested. Returns the result of the last call to
530  outF() or (only if reading fails) inF(). Returns FSL_RC_MISUSE
531  if inF or ouF are NULL.
532 
533  Here is an example which basically does the same thing as the
534  cat(1) command on Unix systems:
535 
536  @code
537  fsl_stream( fsl_input_f_FILE, stdin, fsl_output_f_FILE, stdout );
538  @endcode
539 
540  Or copy a FILE to a buffer:
541 
542  @code
543  fsl_buffer myBuf = fsl_buffer_empty;
544  rc = fsl_stream( fsl_input_f_FILE, stdin, fsl_output_f_buffer, &myBuf );
545  // Note that on error myBuf might be partially populated.
546  // Eventually clean up the buffer:
547  fsl_buffer_clear(&myBuf);
548  @endcode
549 
550 */
551 FSL_EXPORT int fsl_stream( fsl_input_f inF, void * inState,
552  fsl_output_f outF, void * outState );
553 
554 /**
555  Consumes two input streams looking for differences. It stops
556  reading as soon as either or both streams run out of input or a
557  byte-level difference is found. It consumes input in chunks of
558  an unspecified size, and after this returns the input cursor of
559  the streams is not well-defined. i.e. the cursor probably does
560  not point to the exact position of the difference because this
561  level of abstraction does not allow that unless we read byte by
562  byte.
563 
564  Returns 0 if both streams emit the same amount of output and
565  that ouput is bitwise identical, otherwise it returns non-0.
566 */
567 FSL_EXPORT int fsl_stream_compare( fsl_input_f in1, void * in1State,
568  fsl_input_f in2, void * in2State );
569 
570 
571 /**
572  A general-purpose buffer class, analog to Fossil v1's Blob
573  class, but it is not called fsl_blob to avoid confusion with
574  DB-side blobs. Buffers are used extensively in fossil to do
575  everything from reading files to compressing artifacts to
576  creating dynamically-formatted strings. Because they are such a
577  pervasive low-level type, and have such a simple structure,
578  their members (unlike most other structs in this API) may be
579  considered public and used directly by client code (as long as
580  they do not mangle their state, e.g. by setting this->capacity
581  smaller than this->used!).
582 
583  General conventions of this class:
584 
585  - ALWAYS initialize them by copying fsl_buffer_empty or
586  (depending on the context) fsl_buffer_empty_m. Failing to
587  initialize them properly leads to undefined behaviour.
588 
589  - ALWAYS fsl_buffer_clear() buffers when done with
590  them. Remember that failed routines which output to buffers
591  might partially populate the buffer, so be sure to clean up on
592  error cases.
593 
594  - The 'capacity' member specifies how much memory the buffer
595  current holds in its 'mem' member.
596 
597  - The 'used' member specifies how much of the memory is actually
598  "in use" by the client.
599 
600  - As a rule, the API tries to keep (used<capacity) and always
601  (unless documented otherwise) tries to keep the memory buffer
602  NUL-terminated (if it has any memory at all).
603 
604  - Use fsl_buffer_reset() to keep memory around and reset the
605  'used' amount to 0. Most rountines which write to buffers will
606  re-use that memory if they can.
607 
608  This example demonstrates the difference between 'used' and
609  'capacity' (error checking reduced to assert()ions for clarity):
610 
611  @code
612  fsl_buffer b = fsl_buffer_empty;
613  int rc = fsl_buffer_reserve(&b, 20);
614  assert(0==rc);
615  assert(b.capacity>=20); // it may reserve more!
616  assert(0==b.used);
617  rc = fsl_buffer_append(&b, "abc", 3);
618  assert(0==rc);
619  assert(3==b.used);
620  assert(0==b.mem[b.used]); // API always NUL-terminates
621  @endcode
622 
623  @see fsl_buffer_reserve()
624  @see fsl_buffer_append()
625  @see fsl_buffer_appendf()
626  @see fsl_buffer_cstr()
627  @see fsl_buffer_size()
628  @see fsl_buffer_capacity()
629  @see fsl_buffer_clear()
630  @see fsl_buffer_reset()
631 */
632 struct fsl_buffer {
633  /**
634  The raw memory owned by this buffer. It is this->capacity bytes
635  long, of which this->used are considered "used" by the client.
636  The difference beween (this->capacity - this->used) represents
637  space the buffer has available for use before it will require
638  another expansion/reallocation.
639  */
640  unsigned char * mem;
641  /**
642  Number of bytes allocated for this buffer.
643  */
645  /**
646  Number of "used" bytes in the buffer. This is generally
647  interpreted as the string length of this->mem, and the buffer
648  APIs which add data to a buffer always ensure that
649  this->capacity is large enough to account for a trailing NUL
650  byte in this->mem.
651 
652  Library routines which manipulate buffers must ensure that
653  (this->used<=this->capacity) is always true, expanding the
654  buffer if necessary. Much of the API assumes that precondition
655  is always met, and any violation of it opens the code to
656  undefined behaviour (which is okay, just don't ever break that
657  precondition). Most APIs ensure that (used<capacity) is always
658  true (as opposed to used<=capacity) because they add a
659  trailing NUL byte which is not counted in the "used" length.
660  */
662 
663  /**
664  Used by some routines to keep a cursor into this->mem.
665 
666  TODO: factor this back out and let those cases keep their own
667  state. This is only used by fsl_input_f_buffer() (and that
668  function cannot be implemented unless we add the cursor here
669  or add another layer of state type specifically for it).
670  */
672 };
673 
674 /** Empty-initialized fsl_buffer instance, intended for const-copy
675  initialization. */
676 #define fsl_buffer_empty_m {NULL,0U,0U,0U}
677 
678 /** Empty-initialized fsl_buffer instance, intended for copy
679  initialization. */
681 
682 /**
683  A container for storing generic error state. It is used to
684  propagate error state between layers of the API back to the
685  client. i.e. they act as basic exception containers.
686 
687  @see fsl_error_set()
688  @see fsl_error_get()
689  @see fsl_error_move()
690  @see fsl_error_clear()
691 */
692 struct fsl_error {
693  /**
694  Error message text is stored in this->msg.mem. The usable text
695  part is this->msg.used bytes long.
696  */
698  /**
699  Error code, generally assumed to be a fsl_rc_t value.
700  */
701  int code;
702 };
703 
704 /** Empty-initialized fsl_error instance, intended for const-copy initialization. */
705 #define fsl_error_empty_m {fsl_buffer_empty_m,0}
706 
707 /** Empty-initialized fsl_error instance, intended for copy initialization. */
709 
710 /**
711  Populates err with the given code and formatted string, replacing
712  any existing state. If fmt==NULL then fsl_rc_cstr(rc) is used to
713  get the error string.
714 
715  Returns code on success, some other non-0 code on error.
716 
717  As a special case, if 0==code then fmt is ignored and the error
718  state is cleared. This will not free any memory held by err but
719  will re-set its string to start with a NUL byte, ready for
720  re-use later on.
721 
722  As a special case, if code==FSL_RC_OOM then fmt is ignored
723  to avoid a memory allocation (which would presumably fail).
724 
725  @see fsl_error_get()
726  @see fsl_error_clear()
727  @see fsl_error_move()
728 */
729 FSL_EXPORT int fsl_error_set( fsl_error * err, int code, char const * fmt,
730  ... );
731 
732 /**
733  va_list counterpart to fsl_error_set().
734 */
735 FSL_EXPORT int fsl_error_setv( fsl_error * err, int code, char const * fmt,
736  va_list args );
737 
738 /**
739  Fetches the error state from err. If !err it returns
740  FSL_RC_MISUSE without side-effects, else it returns err's current
741  error code.
742 
743  If str is not NULL then *str will be assigned to the raw
744  (NUL-terminated) error string (which might be empty or even
745  NULL). The memory for the string is owned by err and may be
746  invalidated by any calls which take err as a non-const parameter
747  OR which might modify it indirectly through a container object,
748  so the client is required to copy it if it is needed for later
749  on.
750 
751  If len is not NULL then *len will be assigned to the length of
752  the returned string (in bytes).
753 
754  @see fsl_error_set()
755  @see fsl_error_clear()
756  @see fsl_error_move()
757 */
758 FSL_EXPORT int fsl_error_get( fsl_error const * err, char const ** str, fsl_size_t * len );
759 
760 /**
761  Frees up any resources owned by err and sets its error code to 0,
762  but does not free err. This is harmless no-op if !err or if err
763  holds no dynamically allocated no memory.
764 
765  @see fsl_error_set()
766  @see fsl_error_get()
767  @see fsl_error_move()
768  @see fsl_error_reset()
769 */
770 FSL_EXPORT void fsl_error_clear( fsl_error * err );
771 
772 /**
773  Sets err->code to 0 and resets its buffer, but keeps any
774  err->msg memory around for later re-use.
775 
776  @see fsl_error_clear()
777 */
778 FSL_EXPORT void fsl_error_reset( fsl_error * err );
779 
780 /**
781  Copies the error state from src to dest. If dest contains state, it is
782  cleared/recycled by this operation.
783 
784  Returns 0 on success, FSL_RC_MISUSE if either argument is NULL
785  or if (src==dest), and FSL_RC_OOM if allocation of the message
786  string fails.
787 
788  As a special case, if src->code==FSL_RC_OOM, then the code is
789  copied but the message bytes (if any) are not (under the
790  assumption that we have no more memory).
791 */
792 FSL_EXPORT int fsl_error_copy( fsl_error const * src, fsl_error * dest );
793 
794 /**
795  Moves the error state from one fsl_error object to
796  another, intended as an allocation optimization when
797  propagating error state up the API.
798 
799  This "uplifts" an error from the 'from' object to the 'to'
800  object. After this returns 'to' will contain the prior error state
801  of 'from' and 'from' will contain the old error message memory of
802  'to'. 'from' will be re-set to the non-error state (its buffer
803  memory is kept intact for later reuse, though).
804 
805  Results are undefined if either parameter is NULL or either is
806  not properly initialized. i.e. neither may refer to uninitialized
807  memory. Copying fsl_error_empty at declaration-time is a simple
808  way to ensure that instances are cleanly initialized.
809 */
810 FSL_EXPORT void fsl_error_move( fsl_error * from, fsl_error * to );
811 
812 /**
813  Returns the given Unix Epoch timestamp value as its approximate
814  Julian Day value. Note that the calculation does not account for
815  leap seconds.
816 */
818 
819 /**
820  Returns the current Unix Epoch time converted to its approximate
821  Julian form. Equivalent to fsl_unix_to_julian(time(0)). See
822  fsl_unix_to_julian() for details. Note that the returned time
823  has seconds, not milliseconds, precision.
824 */
826 
827 #if 0
828 /** UNTESTED, possibly broken vis-a-vis timezone conversion.
829 
830  Returns the given Unix Epoch time value formatted as an ISO8601
831  string. Returns NULL on allocation error, else a string 19
832  bytes long plus a terminating NUL
833  (e.g. "2013-08-19T20:35:49"). The returned memory must
834  eventually be freed using fsl_free().
835 */
836 FSL_EXPORT char * fsl_unix_to_iso8601( fsl_time_t j );
837 #endif
838 
839 /**
840  Returns non-0 (true) if the first 10 digits of z _appear_ to
841  form the start of an ISO date string (YYYY-MM-DD). Whether or
842  not the string is really a valid date is left for downstream
843  code to determine. Returns 0 (false) in all other cases,
844  including if z is NULL.
845 */
846 FSL_EXPORT char fsl_str_is_date(const char *z);
847 
848 
849 /**
850  Checks if z is syntactically a time-format string in the format:
851 
852  [Y]YYYY-MM-DD
853 
854  (Yes, the year may be five-digits, left-padded with a zero for
855  years less than 9999.)
856 
857  Returns a positive value if the YYYYY part has five digits, a
858  negative value if it has four. It returns 0 (false) if z does not
859  match that pattern.
860 
861  If it returns a negative value, the MM part of z starts at byte offset
862  (z+5), and a positive value means the MM part starts at (z+6).
863 
864  z need not be NUL terminated - this function does not read past
865  the first invalid byte. Thus is can be used on, e.g., full
866  ISO8601-format strings. If z is NULL, 0 is returned.
867 */
868 FSL_EXPORT int fsl_str_is_date2(const char *z);
869 
870 
871 /**
872  Reserves at least n bytes of capacity in buf. Returns 0 on
873  success, FSL_RC_OOM if allocation fails, FSL_RC_MISUSE if !buf.
874 
875  This does not change buf->used, nor will it shrink the buffer
876  (reduce buf->capacity) unless n is 0, in which case it
877  immediately frees buf->mem and sets buf->capacity and buf->used
878  to 0.
879 
880  @see fsl_buffer_resize()
881  @see fsl_buffer_clear()
882 */
884 
885 /**
886  Convenience equivalent of fsl_buffer_reserve(buf,0).
887  This a no-op if buf==NULL.
888 */
890 
891 /**
892  Resets buf->used to 0 and sets buf->mem[0] (if buf->mem is not
893  NULL) to 0. Does not (de)allocate memory, only changes the
894  logical "used" size of the buffer. Returns 0 on success,
895  FSL_RC_MISUSE if !buf.
896 
897  Achtung for v1 porters: this function's semantics are much
898  different from the v1 blob_reset(). To get those semantics, use
899  fsl_buffer_reserve(buf, 0) or its convenience form
900  fsl_buffer_clear().
901 */
903 
904 /**
905  Similar to fsl_buffer_reserve() except that...
906 
907  - It does not free all memory when n==0. Instead it essentially
908  makes the memory a length-0, NUL-terminated string.
909 
910  - It will try to shrink (realloc) buf's memory if (n<buf->capacity).
911 
912  - It sets buf->capacity to (n+1) and buf->used to n. This routine
913  allocates one extra byte to ensure that buf is always
914  NUL-terminated.
915 
916  - On success it always NUL-terminates the buffer at
917  offset buf->used.
918 
919  Returns 0 on success, FSL_RC_MISUSE if !buf, FSL_RC_OOM if
920  (re)allocation fails.
921 
922  @see fsl_buffer_reserve()
923  @see fsl_buffer_clear()
924 */
926 
927 /**
928  Swaps the contents of the left and right arguments. Results are
929  undefined if either argument is NULL or points to uninitialized
930  memory.
931 */
932 FSL_EXPORT void fsl_buffer_swap( fsl_buffer * left, fsl_buffer * right );
933 
934 /**
935  Similar fsl_buffer_swap() but it also optionally frees one of
936  the buffer's memories after swapping them. If clearWhich is
937  negative then the left buffer (1st arg) is cleared _after_
938  swapping (i.e., the NEW left hand side gets cleared). If
939  clearWhich is greater than 0 then the right buffer (2nd arg) is
940  cleared _after_ swapping (i.e. the NEW right hand side gets
941  cleared). If clearWhich is 0, this function behaves identically
942  to fsl_buffer_swap().
943 
944  A couple examples should clear this up:
945 
946  @code
947  fsl_buffer_swap_free( &b1, &b2, -1 );
948  @endcode
949 
950  Swaps the contents of b1 and b2, then frees the contents
951  of the left-side buffer (b1).
952 
953  @code
954  fsl_buffer_swap_free( &b1, &b2, 1 );
955  @endcode
956 
957  Swaps the contents of b1 and b2, then frees the contents
958  of the right-side buffer (b2).
959 */
961  int clearWhich );
962 
963 /**
964  Appends the first n bytes of src, plus a NUL byte, to b,
965  expanding b as necessary and incrementing b->used by n. If n is
966  less than 0 then the equivalent of fsl_strlen((char const*)src)
967  is used to calculate the length.
968 
969  If n is 0 (or negative and !*src), this function ensures that
970  b->mem is not NULL and is NUL-terminated, so it may allocate
971  to have space for that NUL byte.
972 
973  src may only be NULL if n==0. If passed (src==NULL, n!=0) then
974  FSL_RC_RANGE is returned.
975 
976  Returns 0 on success, FSL_RC_MISUSE if !f, !b, or !src,
977  FSL_RC_OOM if allocation of memory fails.
978 
979  If this function succeeds, it guarantees that it NUL-terminates
980  the buffer (but that the NUL terminator is not counted in
981  b->used).
982 
983  @see fsl_buffer_appendf()
984  @see fsl_buffer_reserve()
985 */
987  void const * src, fsl_int_t n );
988 
989 /**
990  Uses fsl_appendf() to append formatted output to the given
991  buffer. Returns 0 on success, FSL_RC_MISUSE if !f or !dest, and
992  FSL_RC_OOM if an allocation fails while expanding dest.
993 
994  @see fsl_buffer_append()
995  @see fsl_buffer_reserve()
996 */
998  char const * fmt, ... );
999 
1000 /** va_list counterpart to fsl_buffer_appendfv(). */
1002  char const * fmt, va_list args );
1003 
1004 /**
1005  Compresses the first pIn->used bytes of pIn to pOut. It is ok for
1006  pIn and pOut to be the same blob.
1007 
1008  pOut must either be the same as pIn or else a properly
1009  initialized buffer. Any prior contents will be freed or their
1010  memory reused.
1011 
1012  Results are undefined if any argument is NULL.
1013 
1014  Returns 0 on success, FSL_RC_OOM on allocation error, and FSL_RC_ERROR
1015  if the lower-level compression routines fail.
1016 
1017  Use fsl_buffer_uncompress() to uncompress the data. The data is
1018  encoded with a big-endian, unsigned 32-bit length as the first
1019  four bytes, and then the data as compressed by zlib.
1020 
1021  TODO: if pOut!=pIn1 then re-use pOut's memory, if it has any.
1022 
1023  @see fsl_buffer_compress2()
1024  @see fsl_buffer_uncompress()
1025  @see fsl_buffer_is_compressed()
1026 */
1027 FSL_EXPORT int fsl_buffer_compress(fsl_buffer const *pIn, fsl_buffer *pOut);
1028 
1029 /**
1030  Compress the concatenation of a blobs pIn1 and pIn2 into pOut.
1031 
1032  pOut must be either empty (cleanly initialized or newly
1033  recycled) or must be the same as either pIn1 or pIn2.
1034 
1035  Results are undefined if any argument is NULL.
1036 
1037  Returns 0 on success, FSL_RC_OOM on allocation error, and FSL_RC_ERROR
1038  if the lower-level compression routines fail.
1039 
1040  TODO: if pOut!=(pIn1 or pIn2) then re-use its memory, if it has any.
1041 
1042  @see fsl_buffer_compress()
1043  @see fsl_buffer_uncompress()
1044  @see fsl_buffer_is_compressed()
1045 */
1047  fsl_buffer const *pIn2, fsl_buffer *pOut);
1048 
1049 /**
1050  Uncompress buffer pIn and store the result in pOut. It is ok for
1051  pIn and pOut to be the same buffer. Returns 0 on success. On
1052  error pOut is not modified.
1053 
1054  pOut must be either cleanly initialized/empty or the same as pIn.
1055 
1056  Results are undefined if any argument is NULL.
1057 
1058  Returns 0 on success, FSL_RC_OOM on allocation error, and
1059  FSL_RC_ERROR if the lower-level decompression routines fail.
1060 
1061  TODO: if pOut!=(pIn1 or pIn2) then re-use its memory, if it has any.
1062 
1063  @see fsl_buffer_compress()
1064  @see fsl_buffer_compress2()
1065  @see fsl_buffer_is_compressed()
1066 */
1067 FSL_EXPORT int fsl_buffer_uncompress(fsl_buffer const *pIn, fsl_buffer *pOut);
1068 
1069 /**
1070  Returns true if this function believes that mem (which must be
1071  at least len bytes of valid memory long) appears to have been
1072  compressed by fsl_buffer_compress() or equivalent. This is not a
1073  100% reliable check - it could potentially have false positives
1074  on certain inputs, but that is thought to be unlikely (at least
1075  for text data).
1076 
1077  Returns 0 if mem is NULL.
1078 */
1079 FSL_EXPORT char fsl_data_is_compressed(unsigned char const * mem, fsl_size_t len);
1080 
1081 /**
1082  Equivalent to fsl_data_is_compressed(buf->mem, buf->used).
1083 */
1085 
1086 /**
1087  If fsl_data_is_compressed(mem,len) returns true then this function
1088  returns the uncompressed size of the data, else it returns a negative
1089  value.
1090 */
1091 FSL_EXPORT fsl_int_t fsl_data_uncompressed_size(unsigned char const *mem, fsl_size_t len);
1092 
1093 /**
1094  The fsl_buffer counterpart of fsl_data_uncompressed_size().
1095 */
1097 
1098 /**
1099  Equivalent to ((char const *)b->mem), but returns NULL if
1100  !b. The returned string is effectively b->used bytes long unless
1101  the user decides to apply his own conventions. Note that the buffer APIs
1102  generally assure that buffers are NUL-terminated, meaning that strings
1103  returned from this function can (for the vast majority of cases)
1104  assume that the returned string is NUL-terminated (with a string length
1105  of b->used _bytes_).
1106 
1107  @see fsl_buffer_str()
1108  @see fsl_buffer_cstr2()
1109 */
1110 FSL_EXPORT char const * fsl_buffer_cstr(fsl_buffer const *b);
1111 
1112 /**
1113  If buf is not NULL and has any memory allocated to it, that
1114  memory is returned. If both b and len are not NULL then *len is
1115  set to b->used. If b has no dynamic memory then NULL is returned
1116  and *len (if len is not NULL) is set to 0.
1117 
1118  @see fsl_buffer_str()
1119  @see fsl_buffer_cstr()
1120 */
1121 FSL_EXPORT char const * fsl_buffer_cstr2(fsl_buffer const *b, fsl_size_t * len);
1122 
1123 /**
1124  Equivalent to ((char *)b->mem), but returns NULL if !b. The
1125  returned memory is effectively b->used bytes long unless the user
1126  decides to apply his own conventions.
1127 */
1128 FSL_EXPORT char * fsl_buffer_str(fsl_buffer const *b);
1129 
1130 /**
1131  Returns the "used" size of b, or 0 if !b.
1132 */
1134 
1135 /**
1136  Returns the current capacity of b, or 0 if !b.
1137 */
1139 
1140 /**
1141  Compares the contents of buffers lhs and rhs using memcmp(3)
1142  semantics. Return negative, zero, or positive if the first
1143  buffer is less then, equal to, or greater than the second.
1144  Results are undefined if either argument is NULL.
1145 
1146  When buffers of different length match on the first N bytes,
1147  where N is the shorter of the two buffers' lengths, it treats the
1148  shorter buffer as being "less than" the longer one.
1149 */
1150 FSL_EXPORT int fsl_buffer_compare(fsl_buffer const * lhs, fsl_buffer const * rhs);
1151 
1152 /**
1153  Bitwise-compares the contents of b against the file named by
1154  zFile. Returns 0 if they have the same size and contents, else
1155  non-zero. This function has no way to report if zFile cannot be
1156  opened, and any error results in a non-0 return value. No
1157  interpretation/canonicalization of zFile is performed - it is
1158  used as-is.
1159 
1160  This resolves symlinks and returns non-0 if zFile refers (after
1161  symlink resolution) to a non-file.
1162 
1163  If zFile does not exist, is not readable, or has a different
1164  size than b->used, non-0 is returned without opening/reading the
1165  file contents. If a content comparison is performed, it is
1166  streamed in chunks of an unspecified (but relatively small)
1167  size, so it does not need to read the whole file into memory
1168  (unless it is smaller than the chunk size).
1169 */
1170 FSL_EXPORT int fsl_buffer_compare_file( fsl_buffer const * b, char const * zFile );
1171 
1172 /**
1173  Compare two buffers in constant (a.k.a. O(1)) time and return
1174  zero if they are equal. Constant time comparison only applies
1175  for buffers of the same length. If lengths are different,
1176  immediately returns 1. This operation is provided for cases
1177  where the timing/duration of fsl_buffer_compare() (or an
1178  equivalent memcmp()) might inadvertently leak security-relevant
1179  information. Specifically, it address the concern that
1180  attackers can use timing differences to check for password
1181  misses, to narrow down an attack to passwords of a specific
1182  length or content properties.
1183 */
1184 FSL_EXPORT int fsl_buffer_compare_O1(fsl_buffer const * lhs, fsl_buffer const * rhs);
1185 
1186 /**
1187  Overwrites dest's contents with a copy of those from src
1188  (reusing dest's memory if it has any). Results are undefined if
1189  either pointer is NULL or invalid. Returns 0 on success,
1190  FSL_RC_OOM on allocation error.
1191 */
1192 FSL_EXPORT int fsl_buffer_copy( fsl_buffer const * src, fsl_buffer * dest );
1193 
1194 
1195 /**
1196  Apply the delta in pDelta to the original content pOriginal to
1197  generate the target content pTarget. All three pointers must point
1198  to properly initialized memory.
1199 
1200  If pTarget==pOriginal then this is a destructive operation,
1201  replacing the original's content with its new form.
1202 
1203  Return 0 on success.
1204 
1205  @see fsl_buffer_delta_apply()
1206  @see fsl_delta_apply()
1207  @see fsl_delta_apply2()
1208 */
1209 FSL_EXPORT int fsl_buffer_delta_apply( fsl_buffer const * pOriginal,
1210  fsl_buffer const * pDelta,
1211  fsl_buffer * pTarget);
1212 
1213 /**
1214  Identical to fsl_buffer_delta_apply() except that if delta
1215  application fails then any error messages/codes are written to
1216  pErr if it is not NULL. It is rare that delta application fails
1217  (only if the inputs are invalid, e.g. do not belong together or
1218  are corrupt), but when it does, having error information can be
1219  useful.
1220 
1221  @see fsl_buffer_delta_apply()
1222  @see fsl_delta_apply()
1223  @see fsl_delta_apply2()
1224 */
1225 FSL_EXPORT int fsl_buffer_delta_apply2( fsl_buffer const * pOriginal,
1226  fsl_buffer const * pDelta,
1227  fsl_buffer * pTarget,
1228  fsl_error * pErr);
1229 
1230 
1231 /**
1232  Uses a fsl_input_f() function to buffer input into a fsl_buffer.
1233 
1234  dest must be a non-NULL, initialized (though possibly empty)
1235  fsl_buffer object. Its contents, if any, will be overwritten by
1236  this function, and any memory it holds might be re-used.
1237 
1238  The src function is called, and passed the state parameter, to
1239  fetch the input. If it returns non-0, this function returns that
1240  error code. src() is called, possibly repeatedly, until it
1241  reports that there is no more data.
1242 
1243  Whether or not this function succeeds, dest still owns any memory
1244  pointed to by dest->mem, and the client must eventually free it
1245  by calling fsl_buffer_reserve(dest,0).
1246 
1247  dest->mem might (and possibly will) be (re)allocated by this
1248  function, so any pointers to it held from before this call might
1249  be invalidated by this call.
1250 
1251  On error non-0 is returned and dest may bge partially populated.
1252 
1253  Errors include:
1254 
1255  dest or src are NULL (FSL_RC_MISUSE)
1256 
1257  Allocation error (FSL_RC_OOM)
1258 
1259  src() returns an error code
1260 
1261  Whether or not the state parameter may be NULL depends on the src
1262  implementation requirements.
1263 
1264  On success dest will contain the contents read from the input
1265  source. dest->used will be the length of the read-in data, and
1266  dest->mem will point to the memory. dest->mem is automatically
1267  NUL-terminated if this function succeeds, but dest->used does not
1268  count that terminator. On error the state of dest->mem must be
1269  considered incomplete, and is not guaranteed to be
1270  NUL-terminated.
1271 
1272  Example usage:
1273 
1274  @code
1275  fsl_buffer buf = fsl_buffer_empty;
1276  int rc = fsl_buffer_fill_from( &buf,
1277  fsl_input_f_FILE,
1278  stdin );
1279  if( rc ){
1280  fprintf(stderr,"Error %d (%s) while filling buffer.\n",
1281  rc, fsl_rc_cstr(rc));
1282  fsl_buffer_reserve( &buf, 0 );
1283  return ...;
1284  }
1285  ... use the buf->mem ...
1286  ... clean up the buffer ...
1287  fsl_buffer_reserve( &buf, 0 );
1288  @endcode
1289 
1290  To take over ownership of the buffer's memory, do:
1291 
1292  @code
1293  void * mem = buf.mem;
1294  buf = fsl_buffer_empty;
1295  @endcode
1296 
1297  In which case the memory must eventually be passed to fsl_free()
1298  to free it.
1299 */
1300 FSL_EXPORT int fsl_buffer_fill_from( fsl_buffer * dest, fsl_input_f src, void * state );
1301 
1302 /**
1303  A fsl_buffer_fill_from() proxy which overwrite's dest->mem with
1304  the contents of the given FILE handler (which must be opened for
1305  read access). Returns 0 on success, after which dest->mem
1306  contains dest->used bytes of content from the input source. On
1307  error dest may be partially filled.
1308 */
1309 FSL_EXPORT int fsl_buffer_fill_from_FILE( fsl_buffer * dest, FILE * src );
1310 
1311 /**
1312  A wrapper for fsl_buffer_fill_from_FILE() which gets its input
1313  from the given file name. It uses fsl_fopen() to open the file,
1314  so it supports "-" as an alias for stdin.
1315 
1316  Uses fsl_fopen() to open the file, so it supports the name '-'
1317  as an alias for stdin.
1318 */
1319 FSL_EXPORT int fsl_buffer_fill_from_filename( fsl_buffer * dest, char const * filename );
1320 
1321 /**
1322  Writes the given buffer to the given filename. Returns 0 on success,
1323  FSL_RC_MISUSE if !b or !fname, FSL_RC_IO if opening or writing fails.
1324 
1325  Uses fsl_fopen() to open the file, so it supports the name '-'
1326  as an alias for stdout.
1327 */
1328 FSL_EXPORT int fsl_buffer_to_filename( fsl_buffer const * b, char const * fname );
1329 
1330 /**
1331  Copy N lines of text from pFrom into pTo. The copy begins at
1332  the current pFrom->cursor position. pFrom->cursor is left
1333  pointing at the first character past the last \n copied.
1334 
1335  If pTo==NULL then this routine simply skips over N lines.
1336 
1337  Returns 0 if it copies lines or does nothing (because N is 0 or
1338  pFrom's contents have been exhausted. Copying fewer lines than
1339  requested (because of EOF) is not an error. Returns non-0 only
1340  on allocation error. Results are undefined if either of the
1341  first two arguments are NULL.
1342 
1343  @see fsl_buffer_stream_lines()
1344 */
1346 
1347 /**
1348  Works identically to fsl_buffer_copy_lines() except that it sends its output
1349 
1350 
1351  @see fsl_buffer_copy_lines()
1352 */
1354  void * toState, fsl_size_t N);
1355 
1356 
1357 /**
1358  Works like fsl_appendfv(), but appends all output to a
1359  dynamically-allocated string, expanding the string as necessary
1360  to collect all formatted data. The returned NUL-terminated string
1361  is owned by the caller and it must be cleaned up using
1362  fsl_free(...). If !fmt, NULL is returned. It is conceivable that
1363  it returns NULL on a zero-length formatted string, e.g. (%.*s)
1364  with (0,"...") as arguments, but it will only do that if the
1365  whole format string resolves to empty.
1366 */
1367 FSL_EXPORT char * fsl_mprintf( char const * fmt, ... );
1368 
1369 /**
1370  va_list counterpart to fsl_mprintf().
1371 */
1372 FSL_EXPORT char * fsl_mprintfv(char const * fmt, va_list vargs );
1373 
1374 /**
1375  An sprintf(3) clone which uses fsl_appendf() for the formatting.
1376  Outputs at most n bytes to dest and returns the number of bytes
1377  output. Returns a negative value if !dest or !fmt. Returns 0
1378  without side-effects if !n or !*fmt.
1379 
1380  If the destination buffer is long enough (this function returns
1381  a non-negative value less than n), this function NUL-terminates it.
1382  If it returns n then there was no space for the terminator.
1383 
1384 */
1385 FSL_EXPORT fsl_int_t fsl_snprintf( char * dest, fsl_size_t n, char const * fmt, ... );
1386 
1387 /**
1388  va_list counterpart to fsl_snprintf()
1389 */
1390 FSL_EXPORT fsl_int_t fsl_snprintfv( char * dest, fsl_size_t n, char const * fmt, va_list args );
1391 
1392 /**
1393  Equivalent to fsl_strndup(src,-1).
1394 */
1395 FSL_EXPORT char * fsl_strdup( char const * src );
1396 
1397 /**
1398  Similar to strndup(3) but returns NULL if !src. The returned
1399  memory must eventually be passed to fsl_free(). Returns NULL on
1400  allocation error. If len is less than 0 and src is not NULL then
1401  fsl_strlen() is used to calculate its length.
1402 
1403  If src is not NULL but len is 0 then it will return an empty
1404  (length-0) string, as opposed to NULL.
1405 */
1406 FSL_EXPORT char * fsl_strndup( char const * src, fsl_int_t len );
1407 
1408 /**
1409  Equivalent to strlen(3) but returns 0 if src is NULL.
1410  Note that it counts bytes, not UTF characters.
1411 */
1412 FSL_EXPORT fsl_size_t fsl_strlen( char const * src );
1413 
1414 /**
1415  Like strcmp(3) except that it accepts NULL pointers. NULL sorts
1416  before all non-NULL string pointers. Also, this routine
1417  performs a binary comparison that does not consider locale.
1418 */
1419 FSL_EXPORT int fsl_strcmp( char const * lhs, char const * rhs );
1420 
1421 /**
1422  Equivalent to fsl_strcmp(), but with a signature suitable
1423  for use as a generic comparison function (e.g. for use with
1424  qsort() and search algorithms).
1425 */
1426 FSL_EXPORT int fsl_strcmp_cmp( void const * lhs, void const * rhs );
1427 
1428 /**
1429  Case-insensitive form of fsl_strcmp().
1430 
1431  @implements fsl_generic_cmp_f()
1432 */
1433 FSL_EXPORT int fsl_stricmp(const char *zA, const char *zB);
1434 
1435 /**
1436  Equivalent to fsl_stricmp(), but with a signature suitable
1437  for use as a generic comparison function (e.g. for use with
1438  qsort() and search algorithms).
1439 
1440  @implements fsl_generic_cmp_f()
1441 */
1442 FSL_EXPORT int fsl_stricmp_cmp( void const * lhs, void const * rhs );
1443 
1444 /**
1445  fsl_strcmp() variant which compares at most nByte bytes of the
1446  given strings, case-insensitively. If nByte is less than 0 then
1447  fsl_strlen(zB) is used to obtain the length for comparision
1448  purposes.
1449 */
1450 FSL_EXPORT int fsl_strnicmp(const char *zA, const char *zB, fsl_int_t nByte);
1451 
1452 /**
1453  fsl_strcmp() variant which compares at most nByte bytes of the
1454  given strings, case-sensitively. Returns 0 if nByte is 0.
1455 */
1456 FSL_EXPORT int fsl_strncmp(const char *zA, const char *zB, fsl_size_t nByte);
1457 
1458 /**
1459  Equivalent to fsl_strncmp(lhs, rhs, FSL_UUID_STRLEN).
1460 */
1461 FSL_EXPORT int fsl_uuidcmp( fsl_uuid_cstr lhs, fsl_uuid_cstr rhs );
1462 
1463 /**
1464  Returns false if s is NULL or starts with any of (0 (NUL), '0'
1465  (ASCII character zero), 'f', 'n', "off"), case-insensitively,
1466  else it returns true.
1467 */
1468 FSL_EXPORT char fsl_str_bool( char const * s );
1469 
1470 /**
1471  Flags for use with fsl_db_open() and friends.
1472 */
1474 /**
1475  The "no flags" value.
1476 */
1478 /**
1479  Flag for fsl_db_open() specifying that the db should be opened
1480  in read-only mode.
1481 */
1483 /**
1484  Flag for fsl_db_open() specifying that the db should be opened
1485  in read-write mode, but should not create the db if it does
1486  not already exist.
1487 */
1489 /**
1490  Flag for fsl_db_open() specifying that the db should be opened in
1491  read-write mode, creating the db if it does not already exist.
1492 */
1494 /**
1495  Shorthand for RW+CREATE flags.
1496 */
1498 /**
1499  Tells fsl_repo_open_xxx() to confirm that the db
1500  is a repository.
1501 */
1503 };
1504 
1505 
1506 /**
1507  _Almost_ equivalent to fopen(3) but:
1508 
1509  - expects name to be UTF8-encoded.
1510 
1511  - If name=="-", it returns one of stdin or stdout, depending on
1512  the mode string: stdout is returned if 'w' or '+' appear,
1513  otherwise stdin.
1514 
1515  If it returns NULL, the errno "should" contain a description of
1516  the problem unless the problem was argument validation. Pass it
1517  to fsl_errno_to_rc() to convert that into an API-conventional
1518  error code.
1519 
1520  If at all possible, use fsl_close() (as opposed to fclose()) to
1521  close these handles, as it has logic to skip closing the
1522  standard streams.
1523 
1524  Potential TODOs:
1525 
1526  - extend mode string to support 'x', meaning "exclusive", analog
1527  to open(2)'s O_EXCL flag. Barring race conditions, we have
1528  enough infrastructure to implement that. (It turns out that
1529  glibc's fopen() supports an 'x' with exactly this meaning.)
1530 
1531  - extend mode to support a 't', meaning "temporary". The idea
1532  would be that we delete the file from the FS right after
1533  opening, except that Windows can't do that.
1534 */
1535 FSL_EXPORT FILE * fsl_fopen(char const * name, char const *mode);
1536 
1537 /**
1538  Passes f to fclose(3) unless f is NULL or one of the C-standard
1539  (stdin, stdout, stderr) handles, in which cases it does nothing
1540  at all.
1541 */
1542 FSL_EXPORT void fsl_fclose(FILE * f);
1543 
1544 /**
1545  @typedef fsl_int_t (*fsl_appendf_f)( void * state, char const * data, fsl_int_t n )
1546 
1547  The fsl_appendf_f typedef is used to provide fsl_appendfv() with
1548  a flexible output routine, so that it can be easily send its
1549  output to arbitrary targets.
1550 
1551  The policies which implementations need to follow are:
1552 
1553  - state is an implementation-specific pointer (may be 0) which
1554  is passed to fsl_appendf(). fsl_appendfv() doesn't know what
1555  this argument is but passes it to its fsl_appendf_f argument.
1556  Typically this pointer will be an object or resource handle to
1557  which string data is pushed.
1558 
1559  - The 'data' parameter is the data to append. The API does not
1560  currently guaranty that data containing embeded NULs will
1561  survive the ride through fsl_appendf() and its delegates friends
1562  (but it "should work").
1563 
1564  - n is the number of bytes to read from data. The fact that n is
1565  of a signed type is historical. It can be treated as an unsigned
1566  type for purposes of fsl_appendf().
1567 
1568  - Returns, on success, the number of bytes appended (may be 0).
1569 
1570  - Returns, on error, an implementation-specified negative
1571  number. Returning a negative error code will cause
1572  fsl_appendfv() to stop processing and return. Note that 0 is a
1573  success value (some printf format specifiers do not add anything
1574  to the output).
1575 */
1576 typedef fsl_int_t (*fsl_appendf_f)( void * state,
1577  char const * data,
1578  fsl_int_t n );
1579 
1580 /**
1581  This function works similarly to classical printf
1582  implementations, but instead of outputing somewhere specific, it
1583  uses a callback function to push its output somewhere. This
1584  allows it to be used for arbitrary external representations. It
1585  can be used, for example, to output to an external string, a UI
1586  widget, or file handle (it can also emulate printf by outputing
1587  to stdout this way).
1588 
1589  INPUTS:
1590 
1591  pfAppend: The is a fsl_appendf_f function which is responsible
1592  for accumulating the output. If pfAppend returns a negative
1593  value then processing stops immediately.
1594 
1595  pfAppendArg: is ignored by this function but passed as the first
1596  argument to pfAppend. pfAppend will presumably use it as a data
1597  store for accumulating its string.
1598 
1599  fmt: This is the format string, as in the usual printf(3), except
1600  that it supports more options (detailed below).
1601 
1602  ap: This is a pointer to a list of arguments. Same as in
1603  vprintf() and friends.
1604 
1605 
1606  OUTPUTS:
1607 
1608  The return value is the total number of characters sent to the
1609  function "func", or a negative number on a pre-output error. If
1610  this function returns an integer greater than 1 it is in general
1611  impossible to know if all of the elements were output. As such
1612  failure can only happen if the callback function returns an
1613  error or if one of the formatting options needs to allocate
1614  memory and cannot. Both of those cases are very rare in a
1615  printf-like context, so this is not considered to be a
1616  significant problem. (The same is true for any classical printf
1617  implementations.) Clients may use their own state objects which
1618  can propagate errors from their own internals back to the
1619  caller, but generically speaking it is difficult to trace errors
1620  back through this routine. Then again, in practice that has
1621  never proven to be a problem.
1622 
1623  Most printf-style specifiers work as they do in standard printf()
1624  implementations. There might be some very minor differences, but
1625  the more common format specifiers work as most developers expect
1626  them to. In addition...
1627 
1628  Current (documented) printf extensions:
1629 
1630  (If you are NOT reading this via doxygen-processed sources: the
1631  percent signs below are doubled for the sake of doxygen, and
1632  each pair refers to only a single percent sign in the format
1633  string.)
1634 
1635  %%z works like %%s, but takes a non-const (char *) and deletes
1636  the string (using fsl_free()) after appending it to the output.
1637 
1638  %%h (HTML) works like %%s but converts certain characters (namely
1639  '<' and '&') to their HTML escaped equivalents.
1640 
1641  %%t (URL encode) works like %%s but converts certain characters
1642  into a representation suitable for use in an HTTP URL. (e.g. ' '
1643  gets converted to %%20)
1644 
1645  %%T (URL decode) does the opposite of %%t - it decodes
1646  URL-encoded strings and outputs their decoded form. ACHTUNG:
1647  fossil(1) interprets this the same as %%t except that it leaves
1648  '/' characters unescaped (did that change at some point? This
1649  code originally derived from that one some years ago!). It is
1650  still to be determined whether we "really need" that behaviour
1651  (we don't really need either one, seeing as the library is not
1652  CGI-centric like fossil(1) is).
1653 
1654  %%r requires an int and renders it in "ordinal form". That is,
1655  the number 1 converts to "1st" and 398 converts to "398th".
1656 
1657  %%q quotes a string as required for SQL. That is, '\''
1658  characters get doubled. It does NOT included the outer quotes
1659  and NULL values get replaced by the string "(NULL) (without
1660  quotes). See %%Q...
1661 
1662  %%Q works like %%q, but includes the outer '\'' characters and
1663  NULL pointers get output as the string literal "NULL" (without
1664  quotes), i.e. an SQL NULL.
1665 
1666  %%S works like %%.12s. It is intended for UUIDs.
1667 
1668  %%/: works like %%s but normalizes path-like strings by
1669  replacing backslashes with the One True Slash.
1670 
1671  %%b: works like %%s but takes its input from a (fsl_buffer
1672  const*) argument.
1673 
1674  %%B: works like %%Q but takes its input from a (fsl_buffer
1675  const*) argument.
1676 
1677  %%F: works like %%s but runs the output through
1678  fsl_bytes_fossilize(). This requires dynamic memory allocation,
1679  so is less efficient than re-using a client-provided buffer with
1680  fsl_bytes_fossilize() if the client needs to fossilize more than
1681  one element. A '#' between the percent and F works like %%.*s -
1682  it expects an int-type argument to give the maximum number of
1683  bytes from F to fossilize (not the maximum output length). Be
1684  very careful to pass (or cast to) an int, not a fsl_size_t or
1685  any other type which has a different sizeof() than int, or else
1686  variadic arg handling may Do The Wrong Thing.
1687 
1688  These extensions may be disabled by setting certain macros when
1689  compiling fsl_appendf.c (see that file for details).
1690 
1691 
1692  FIXME? fsl_appendf_f() is an artifact of older code from which
1693  this implementation derives. The first parameter should arguably
1694  be replaced with fsl_output_f(), which does the same thing _but_
1695  has different return semantics (more reliable, because the
1696  current semantics report partial success as success in some
1697  cases). Doing this would require us to change the return
1698  semantics of this function, but that wouldn't necessarily be a
1699  bad thing (we don't rely on sprintf()-like return semantics all
1700  that much, if at all). Or we just add a proxy which forwards to
1701  a fsl_output_f(). (Oh, hey, that's what fsl_outputf() does.) But
1702  that doesn't catch certain types of errors (namely allocation
1703  failures) which can happen as side-effects of some formatting
1704  operations.
1705 
1706  Potential TODO: add fsl_bytes_fossilize_out() which works like
1707  fsl_bytes_fossilize() but sends its output to an fsl_output_f()
1708  and fsl_appendf_f(), so that this routine doesn't need to alloc
1709  for that case.
1710 */
1711 FSL_EXPORT fsl_int_t fsl_appendfv(fsl_appendf_f pfAppend, void * pfAppendArg,
1712  const char *fmt, va_list ap );
1713 
1714 /**
1715  Identical to fsl_appendfv() but takes an ellipses list (...)
1716  instead of a va_list.
1717 */
1719  void * pfAppendArg,
1720  const char *fmt,
1721  ... )
1722 #if 0
1723 /* Would be nice, but complains about our custom format options: */
1724  __attribute__ ((__format__ (__printf__, 3, 4)))
1725 #endif
1726  ;
1727 
1728 /**
1729  A fsl_appendf_f() impl which requires that state be an opened,
1730  writable (FILE*) handle.
1731 */
1733  char const * s, fsl_int_t n );
1734 
1735 
1736 /**
1737  Emulates fprintf() using fsl_appendf(). Returns the result of
1738  passing the data through fsl_appendf() to the given file handle.
1739 */
1740 FSL_EXPORT fsl_int_t fsl_fprintf( FILE * fp, char const * fmt, ... );
1741 
1742 /**
1743  The va_list counterpart of fsl_fprintf().
1744 */
1745 FSL_EXPORT fsl_int_t fsl_fprintfv( FILE * fp, char const * fmt, va_list args );
1746 
1747 
1748 /**
1749  Possibly reallocates self->list, changing its size. This function
1750  ensures that self->list has at least n entries. If n is 0 then
1751  the list is deallocated (but the self object is not), BUT THIS
1752  DOES NOT DO ANY TYPE-SPECIFIC CLEANUP of the items. If n is less
1753  than or equal to self->capacity then there are no side effects. If
1754  n is greater than self->capacity, self->list is reallocated and
1755  self->capacity is adjusted to be at least n (it might be bigger -
1756  this function may pre-allocate a larger value).
1757 
1758  Passing an n of 0 when self->capacity is 0 is a no-op.
1759 
1760  Newly-allocated slots will be initialized with NUL bytes.
1761 
1762  Returns 0 on success, FSL_RC_MISUSE if !self, FSL_RC_OOM if
1763  reservation of new elements fails.
1764 
1765  The return value should be used like this:
1766 
1767  @code
1768  fsl_size_t const n = number of bytes to allocate;
1769  int const rc = fsl_list_reserve( myList, n );
1770  if( rc ) { ... error ... }
1771  @endcode
1772 
1773  @see fsl_list_clear()
1774  @see fsl_list_visit_free()
1775 */
1777 
1778 /**
1779  Appends a bitwise copy of cp to self->list, expanding the list as
1780  necessary and adjusting self->used.
1781 
1782  Ownership of cp is unchanged by this call. cp may not be NULL.
1783 
1784  Returns 0 on success, FSL_RC_MISUSE if any argument is NULL, or
1785  FSL_RC_OOM on allocation error.
1786 */
1787 FSL_EXPORT int fsl_list_append( fsl_list * self, void * cp );
1788 
1789 /**
1790  Swaps all contents of both lhs and rhs. Results are undefined if
1791  lhs or rhs are NULL or not properly initialized (via initial copy
1792  initialization from fsl_list_empty resp. fsl_list_empty_m).
1793 */
1794 FSL_EXPORT void fsl_list_swap( fsl_list * lhs, fsl_list * rhs );
1795 
1796 /** @typedef typedef int (*fsl_list_visitor_f)(void * p, void * visitorState )
1797 
1798  Generic visitor interface for fsl_list lists. Used by
1799  fsl_list_visit(). p is the pointer held by that list entry and
1800  visitorState is the 4th argument passed to fsl_list_visit().
1801 
1802  Implementations must return 0 on success. Any other value causes
1803  looping to stop and that value to be returned, but interpration
1804  of the value is up to the caller (it might or might not be an
1805  error, depending on the context). Note that client code may use
1806  custom values, and is not strictly required to use FSL_RC_xxx
1807  values. HOWEVER... all of the libfossil APIs which take these
1808  as arguments may respond differently to some codes (most notable
1809  FSL_RC_BREAK, which they tend to treat as a
1810  stop-iteration-without-error result), so clients are strongly
1811  encourage to return an FSL_RC_xxx value on error.
1812 */
1813 typedef int (*fsl_list_visitor_f)(void * obj, void * visitorState );
1814 
1815 /**
1816  A fsl_list_visitor_f() implementation which requires that obj be
1817  arbitrary memory which can legally be passed to fsl_free()
1818  (which this function does). The visitorState parameter is
1819  ignored.
1820 */
1821 FSL_EXPORT int fsl_list_v_fsl_free(void * obj, void * visitorState );
1822 
1823 
1824 /**
1825  For each item in self->list, visitor(item,visitorState) is
1826  called. The item is owned by self. The visitor function MUST
1827  NOT free the item (unless the visitor is a finalizer!), but may
1828  manipulate its contents if application rules do not specify
1829  otherwise.
1830 
1831  If order is 0 or greater then the list is traversed from start
1832  to finish, else it is traverse from end to begin.
1833 
1834  Returns 0 on success, non-0 on error.
1835 
1836  If visitor() returns non-0 then looping stops and that code is
1837  returned.
1838 */
1839 FSL_EXPORT int fsl_list_visit( fsl_list const * self, int order,
1840  fsl_list_visitor_f visitor, void * visitorState );
1841 
1842 /**
1843  A list clean-up routine which takes a callback to clean up its
1844  contents.
1845 
1846  Passes each element in the given list to
1847  childFinalizer(item,finalizerState). If that returns non-0,
1848  processing stops and that value is returned, otherwise
1849  fsl_list_reserve(list,0) is called and 0 is returned.
1850 
1851  WARNING: if cleanup fails because childFinalizer() returns non-0,
1852  the returned object is effectively left in an undefined state and
1853  the client has no way (unless the finalizer somehow accounts for it)
1854  to know which entries in the list were cleaned up. Thus it is highly
1855  recommended that finalizer functions follow the conventional wisdom
1856  of "destructors do not throw."
1857 
1858  @see fsl_list_visit_free()
1859 */
1860 FSL_EXPORT int fsl_list_clear( fsl_list * list, fsl_list_visitor_f childFinalizer,
1861  void * finalizerState );
1862 /**
1863  Similar to fsl_list_clear(list, fsl_list_v_fsl_free, NULL), but
1864  only frees list->list if the second argument is true, otherwise
1865  it sets the list's length to 0 but keep the list->list memory
1866  intact for later use. Note that this function never frees the
1867  list argument, only its contents.
1868 
1869  Be sure only to use this on lists of types for which fsl_free()
1870  is legal. i.e. don't use it on a list of fsl_deck objects or
1871  other types which have their own finalizers.
1872 
1873  Results are undefined if list is NULL.
1874 
1875  @see fsl_list_clear()
1876 */
1877 FSL_EXPORT void fsl_list_visit_free( fsl_list * list, char freeListMem );
1878 
1879 /**
1880  Works similarly to the visit operation without the _p suffix
1881  except that the pointer the visitor function gets is a (**)
1882  pointing back to the entry within this list. That means that
1883  callers can assign the entry in the list to another value during
1884  the traversal process (e.g. set it to 0). If shiftIfNulled is
1885  true then if the callback sets the list's value to 0 then it is
1886  removed from the list and self->used is adjusted (self->capacity
1887  is not changed).
1888 */
1889 FSL_EXPORT int fsl_list_visit_p( fsl_list * self, int order, char shiftIfNulled,
1890  fsl_list_visitor_f visitor, void * visitorState );
1891 
1892 
1893 /**
1894  Sorts the given list using the given comparison function. Neither
1895  argument may be NULL. The arugments passed to the comparison function
1896  will be pointers to pointers to the original entries, and may (depending
1897  on how the list is used) point to NULL.
1898 */
1900 
1901 /**
1902  Searches for a value in the given list, using the given
1903  comparison function to determine equivalence. The comparison
1904  function will never be passed a NULL value by this function - if
1905  value is NULL then only a NULL entry will compare equal to it.
1906  Results are undefined if li or cmpf are NULL.
1907 
1908  Returns the index in li of the entry, or a negative value if no
1909  match is found.
1910 */
1912  void const * value,
1913  fsl_generic_cmp_f cmpf);
1914 
1915 /**
1916  Equivalent to fsl_list_index_of(li, key, fsl_strcmp_cmp).
1917 */
1919  char const * key );
1920 
1921 
1922 /**
1923  Returns 0 if the given file is readable. Flags may be any values
1924  accepted by the access(2) resp. _waccess() system calls.
1925 */
1926 FSL_EXPORT int fsl_file_access(const char *zFilename, int flags);
1927 
1928 /**
1929  Computes a canonical pathname for a file or directory. Makes the
1930  name absolute if it is relative. Removes redundant / characters.
1931  Removes all /./ path elements. Converts /A/../ to just /. If the
1932  slash parameter is non-zero, the trailing slash, if any, is
1933  retained.
1934 
1935  If zRoot is not NULL then it is used for transforming a relative
1936  zOrigName into an absolute path. If zRoot is NULL fsl_getcwd()
1937  is used to determine the virtual root directory. If zRoot is
1938  empty (starts with a NUL byte) then this function effectively
1939  just sends zOrigName through fsl_file_simplify_name().
1940 
1941  Returns 0 on success, FSL_RC_MISUSE if !zOrigName or !pOut,
1942  FSL_RC_OOM if an allocation fails.
1943 
1944  pOut, if not NULL, is _appended_ to, so be sure to set
1945  pOut->used=0 (or pass it to fsl_buffer_reset()) before calling
1946  this if you want to start writing at the beginning of a re-used
1947  buffer. On error pOut might conceivably be partially populated,
1948  but that is highly unlikely. Nonetheless, be sure to
1949  fsl_buffer_clear() it at some point regardless of success or
1950  failure.
1951 
1952  This function does no actual filesystem-level processing unless
1953  zRoot is NULL or empty (and then only to get the current
1954  directory). This does not confirm whether the resulting file
1955  exists, nor that it is strictly a valid filename for the current
1956  filesystem. It simply transforms a potentially relative path
1957  into an absolute one.
1958 
1959  Example:
1960  @code
1961  int rc;
1962  char const * zRoot = "/a/b/c";
1963  char const * zName = "../foo.bar";
1964  fsl_buffer buf = fsl_buffer_empty;
1965  rc = fsl_file_canonical_name2(zRoot, zName, &buf, 0);
1966  if(!rc){
1967  fsl_buffer_clear(&buf);
1968  return rc;
1969  }
1970  assert(0 == fsl_strcmp( "/a/b/foo.bar, fsl_buffer_cstr(&buf)));
1971  fsl_buffer_clear(&buf);
1972  @endcode
1973 */
1974 FSL_EXPORT int fsl_file_canonical_name2(const char *zRoot,
1975  const char *zOrigName,
1976  fsl_buffer *pOut, char slash);
1977 
1978 /**
1979  Equivalent to fsl_file_canonical_name2(NULL, zOrigName, pOut, slash).
1980 
1981  @see fsl_file_canonical_name2()
1982 */
1983 
1984 FSL_EXPORT int fsl_file_canonical_name(const char *zOrigName,
1985  fsl_buffer *pOut, char slash);
1986 
1987 /**
1988  Calculates the "directory part" of zFilename and _appends_ it to
1989  pOut. The directory part is all parts up to the final path
1990  separator ('\\' or '/'). If leaveSlash is true (non-0) then the
1991  separator part is appended to pOut, otherwise it is not. This
1992  function only examines the first nLen bytes of zFilename. If
1993  nLen is negative then fsl_strlen() is used to determine the
1994  number of bytes to examine.
1995 
1996  If zFilename ends with a slash then it is considered to be its
1997  own directory part. i.e. the dirpart of "foo/" evaluates to
1998  "foo" (or "foo/" if leaveSlash is true), whereas the dirpart of
1999  "foo" resolves to nothing (empty - no output except a NUL
2000  terminator sent to pOut).
2001 
2002  Returns 0 on success, FSL_RC_MISUSE if !zFilename or !pOut,
2003  FSL_RC_RANGE if 0==nLen or !*zFilename, and FSL_RC_OOM if
2004  appending to pOut fails. If zFilename contains only a path
2005  separator and leaveSlash is false then only a NUL terminator is
2006  appended to pOut if it is not already NUL-terminated.
2007 
2008  This function does no filesystem-level validation of the the
2009  given path - only string evaluation.
2010 */
2011 FSL_EXPORT int fsl_file_dirpart(char const * zFilename, fsl_int_t nLen,
2012  fsl_buffer * pOut, char leaveSlash);
2013 
2014 
2015 /**
2016  Writes the absolute path name of the current directory to zBuf,
2017  which must be at least nBuf bytes long (nBuf includes the space
2018  for a trailing NUL terminator).
2019 
2020  Returns FSL_RC_RANGE if the name would be too long for nBuf,
2021  FSL_RC_IO if it cannot determine the current directory (e.g. a
2022  side effect of having removed the directory at runtime or similar
2023  things), and 0 on success.
2024 
2025  On success, if outLen is not NULL then the length of the string
2026  written to zBuf is assigned to *outLen. The output string is
2027  always NUL-terminated.
2028 
2029  On Windows, the name is converted from unicode to UTF8 and all '\\'
2030  characters are converted to '/'. No conversions are needed on
2031  Unix.
2032 */
2033 FSL_EXPORT int fsl_getcwd(char *zBuf, fsl_size_t nBuf, fsl_size_t * outLen);
2034 
2035 
2036 /**
2037  Return true (non-0) if the filename given is a valid filename
2038  for a file in a repository. Valid filenames follow all of the
2039  following rules:
2040 
2041  - Does not begin with "/"
2042  - Does not contain any path element named "." or ".."
2043  - Does not contain "/..." (special case)
2044  - Does not contain any of these characters in the path: "\"
2045  - Does not end with "/".
2046  - Does not contain two or more "/" characters in a row.
2047  - Contains at least one character
2048 
2049  Invalid UTF8 characters result in a false return if bStrictUtf8 is
2050  true. If bStrictUtf8 is false, invalid UTF8 characters are silently
2051  ignored. See http://en.wikipedia.org/wiki/UTF-8#Invalid_byte_sequences
2052  and http://en.wikipedia.org/wiki/Unicode (for the noncharacters).
2053 
2054  Fossil compatibility note: the bStrictUtf8 flag must be true
2055  when parsing new manifests but is false when parsing legacy
2056  manifests, for backwards compatibility.
2057 
2058  z must be NUL terminated. Results are undefined if !z.
2059 
2060  Note that periods in and of themselves are valid filename
2061  components, with the special exceptions of "." and "..", one
2062  implication being that "...." is, for purposes of this function,
2063  a valid simple filename.
2064 */
2065 FSL_EXPORT char fsl_is_simple_pathname(const char *z, char bStrictUtf8);
2066 
2067 /**
2068  Return the size of a file in bytes. Returns -1 if the file does
2069  not exist or is not stat(2)able.
2070 */
2071 FSL_EXPORT fsl_size_t fsl_file_size(const char *zFilename);
2072 
2073 /**
2074  Return the modification time for a file. Return -1 if the file
2075  does not exist or is not stat(2)able.
2076 */
2077 FSL_EXPORT fsl_time_t fsl_file_mtime(const char *zFilename);
2078 
2079 #if 0
2080 /**
2081  Don't use this. The wd (working directory) family of functions
2082  might or might-not be necessary and in any case they require
2083  a fsl_cx context argument because they require repo-specific
2084  "allow-symlinks" setting.
2085 
2086  Return TRUE if the named file is an ordinary file or symlink
2087  and symlinks are allowed.
2088 
2089  Return false for directories, devices, fifos, etc.
2090 */
2091 FSL_EXPORT char fsl_wd_isfile_or_link(const char *zFilename);
2092 #endif
2093 
2094 /**
2095  Return TRUE if the named file is an ordinary file. Return false
2096  for directories, devices, fifos, symlinks, etc.
2097 */
2098 FSL_EXPORT char fsl_is_file(const char *zFilename);
2099 
2100 /**
2101  Returns true if the given path appears to be absolute, else
2102  false. On Unix a path is absolute if it starts with a '/'. On
2103  Windows a path is also absolute if it starts with a letter, a
2104  colon, and either a backslash or forward slash.
2105 */
2106 FSL_EXPORT char fsl_is_absolute_path(const char *zPath);
2107 
2108 /**
2109  Simplify a filename by:
2110 
2111  * converting all \ into / on windows and cygwin
2112  * removing any trailing and duplicate /
2113  * removing /./
2114  * removing /A/../
2115 
2116  Changes are made in-place. Return the new name length. If the
2117  slash parameter is non-zero, the trailing slash, if any, is
2118  retained. If n is <0 then fsl_strlen() is used to calculate the
2119  length.
2120 */
2121 FSL_EXPORT fsl_size_t fsl_file_simplify_name(char *z, fsl_int_t n_, char slash);
2122 
2123 /**
2124  Return true (non-zero) if string z matches glob pattern zGlob
2125  and zero if the pattern does not match. Always returns 0 if
2126  either argument is NULL. Supports all globbing rules
2127  supported by sqlite3_strglob().
2128 */
2129 FSL_EXPORT char fsl_str_glob(const char *zGlob, const char *z);
2130 
2131 /**
2132  Parses zPatternList as a comma-and/or-fsl_isspace()-delimited
2133  list of glob patterns (as supported by fsl_str_glob()). Each
2134  pattern in that list is copied and appended to tgt in the form
2135  of a new (char *) owned by that list.
2136 
2137  Returns 0 on success, FSL_RC_OOM if copying a pattern to tgt
2138  fails, FSL_RC_MISUSE if !tgt or !zPatternList. An empty
2139  zPatternList is not considered an error (to simplify usage) and
2140  has no side-effects. On allocation error, tgt might be partially
2141  populated.
2142 
2143  Elements of the glob list may be optionally enclosed in single
2144  our double-quotes. This allows a comma to be part of a glob
2145  pattern.
2146 
2147  Leading and trailing spaces on unquoted glob patterns are
2148  ignored.
2149 
2150  Note that there is no separate "glob list" class. A "glob list"
2151  is simply a fsl_list whose list entries are glob-pattern strings
2152  owned by that list.
2153 
2154  Examples of a legal value for zPatternList:
2155  @code
2156  "*.c *.h, *.sh, '*.in'"
2157  @endcode
2158 
2159  @see fsl_glob_list_append()
2160  @see fsl_glob_list_matches()
2161  @see fsl_glob_list_clear()
2162 */
2163 FSL_EXPORT int fsl_glob_list_parse( fsl_list * tgt, char const * zPatternList );
2164 
2165 /**
2166  Appends a single blob pattern to tgt, in the form of a new (char *)
2167  owned by tgt. This function copies zGlob and appends that copy
2168  to tgt.
2169 
2170  Returns 0 on success, FSL_RC_MISUSE if !tgt or !zGlob or
2171  !*zGlob, FSL_RC_OOM if appending to the list fails.
2172 
2173  @see fsl_glob_list_parse()
2174  @see fsl_glob_list_matches()
2175  @see fsl_glob_list_clear()
2176 */
2177 FSL_EXPORT int fsl_glob_list_append( fsl_list * tgt, char const * zGlob );
2178 
2179 /**
2180  Assumes globList is a list of (char [const] *) glob values and
2181  tries to match each one against zHaystack using
2182  fsl_str_glob(). If any glob matches, it returns a pointer to the
2183  matched globList->list entry. If no matches are found, or if any
2184  argument is invalid, NULL is returned.
2185 
2186  The returned bytes are owned by globList and may be invalidated at
2187  its leisure. It is primarily intended to be used as a boolean,
2188  for example:
2189 
2190  @code
2191  if( fsl_glob_list_matches(myGlobs, someFilename) ) { ... }
2192  @endcode
2193 
2194  @see fsl_glob_list_parse()
2195  @see fsl_glob_list_append()
2196  @see fsl_glob_list_clear()
2197 */
2198 FSL_EXPORT char const * fsl_glob_list_matches( fsl_list const * globList, char const * zHaystack );
2199 
2200 /**
2201  If globList is not NULL this is equivalent to
2202  fsl_list_visit_free(globList, 1), otherwise it is a no-op.
2203 
2204  Note that this does not free the globList object itself, just
2205  its underlying list entries and list memory. (In practice, lists
2206  are either allocated on the stack or as part of a higher-level
2207  structure, and not on the heap.)
2208 
2209  @see fsl_glob_list_parse()
2210  @see fsl_glob_list_append()
2211  @see fsl_glob_list_matches()
2212 */
2213 FSL_EXPORT void fsl_glob_list_clear( fsl_list * globList );
2214 
2215 
2216 /**
2217  Returns true if the given letter is an ASCII alphabet character.
2218 */
2219 FSL_EXPORT char fsl_isalpha(int c);
2220 
2221 /**
2222  Returns true if c is a lower-case ASCII alphabet character.
2223 */
2224 FSL_EXPORT char fsl_islower(int c);
2225 
2226 /**
2227  Returns true if c is an upper-case ASCII alphabet character.
2228 */
2229 FSL_EXPORT char fsl_isupper(int c);
2230 
2231 /**
2232  Returns true if c is ' ', '\\r' (ASCII 13dec), or '\\t' (ASCII 9
2233  dec).
2234 */
2235 FSL_EXPORT char fsl_isspace(int c);
2236 
2237 /**
2238  Returns true if c is an ASCII digit in the range '0' to '9'.
2239 */
2240 FSL_EXPORT char fsl_isdigit(int c);
2241 
2242 /**
2243  Equivalent to fsl_isdigit(c) || fsl_isalpha().
2244 */
2245 FSL_EXPORT char fsl_isalnum(int c);
2246 
2247 /**
2248  Returns the upper-case form of c if c is an ASCII alphabet
2249  letter, else returns c.
2250 */
2251 FSL_EXPORT int fsl_tolower(int c);
2252 
2253 /**
2254  Returns the lower-case form of c if c is an ASCII alphabet
2255  letter, else returns c.
2256 */
2257 FSL_EXPORT int fsl_toupper(int c);
2258 
2259 #ifdef _WIN32
2260 /**
2261  Translate MBCS to UTF-8. Return a pointer to the translated
2262  text. ACHTUNG: Call fsl_mbcs_free() (not fsl_free()) to
2263  deallocate any memory used to store the returned pointer when
2264  done.
2265 */
2266 FSL_EXPORT char * fsl_mbcs_to_utf8(char const * mbcs);
2267 
2268 /**
2269  Frees a string allocated from fsl_mbcs_to_utf8(). Results are undefined
2270  if mbcs was allocated using any other mechanism.
2271 */
2272 FSL_EXPORT void fsl_mbcs_free(char * mbcs);
2273 #endif
2274 /* _WIN32 */
2275 
2276 /**
2277  Deallocates the given memory, which must have been allocated
2278  from fsl_unicode_to_utf8(), fsl_utf8_to_unicode(), or any
2279  function which explicitly documents this function as being the
2280  proper finalizer for its returned memory.
2281 */
2282 FSL_EXPORT void fsl_unicode_free(void *);
2283 
2284 
2285 /**
2286  Translate UTF-8 to Unicode for use in system calls. Returns a
2287  pointer to the translated text. The returned value must
2288  eventually be passed to fsl_unicode_free() to deallocate any
2289  memory used to store the returned pointer when done.
2290 
2291  This function exists only for Windows. On other platforms
2292  it behaves like fsl_strdup().
2293 
2294  The returned type is (wchar_t*) on Windows and (char*)
2295  everywhere else.
2296 */
2297 FSL_EXPORT void *fsl_utf8_to_unicode(const char *zUtf8);
2298 
2299 /**
2300  Translates Unicode text into UTF-8. Return a pointer to the
2301  translated text. Call fsl_unicode_free() to deallocate any
2302  memory used to store the returned pointer when done.
2303 
2304  This function exists only for Windows. On other platforms it
2305  behaves like fsl_strdup().
2306 */
2307 FSL_EXPORT char *fsl_unicode_to_utf8(const void *zUnicode);
2308 
2309 /**
2310  Translate text from the OS's character set into UTF-8. Return a
2311  pointer to the translated text. Call fsl_filename_free() to
2312  deallocate any memory used to store the returned pointer when
2313  done.
2314 
2315  This function must not convert '\' to '/' on Windows/Cygwin, as
2316  it is used in places where we are not sure it's really filenames
2317  we are handling, e.g. fsl_getenv() or handling the argv
2318  arguments from main().
2319 
2320  On Windows, translate some characters in the in the range
2321  U+F001 - U+F07F (private use area) to ASCII. Cygwin sometimes
2322  generates such filenames. See:
2323  <http://cygwin.com/cygwin-ug-net/using-specialnames.html>
2324 */
2325 FSL_EXPORT char *fsl_filename_to_utf8(const void *zFilename);
2326 
2327 /**
2328  Translate text from UTF-8 to the OS's filename character set.
2329  Return a pointer to the translated text. Call
2330  fsl_filename_free() to deallocate any memory used to store the
2331  returned pointer when done.
2332 
2333  On Windows, characters in the range U+0001 to U+0031 and the
2334  characters '"', '*', ':', '<', '>', '?' and '|' are invalid in
2335  filenames. Therefore, translate those to characters in the in the
2336  range U+F001 - U+F07F (private use area), so those characters
2337  never arrive in any Windows API. The filenames might look
2338  strange in Windows explorer, but in the cygwin shell everything
2339  looks as expected.
2340 
2341  See: <http://cygwin.com/cygwin-ug-net/using-specialnames.html>
2342 
2343  The returned type is (wchar_t*) on Windows and (char*)
2344  everywhere else.
2345 */
2346 FSL_EXPORT void *fsl_utf8_to_filename(const char *zUtf8);
2347 
2348 
2349 /**
2350  Deallocate pOld, which must have been allocated by
2351  fsl_filename_to_utf8(), fsl_utf8_to_filename(), fsl_getenv(), or
2352  another routine which explicitly documents this function as
2353  being the proper finalizer for its returned memory.
2354 */
2355 FSL_EXPORT void fsl_filename_free(void *pOld);
2356 
2357 /**
2358  Returns a (possible) copy of the environment variable with the
2359  given key, or NULL if no entry is found. The returned value must
2360  be passed to fsl_filename_free() to free it. ACHTUNG: DO NOT
2361  MODIFY the returned value - on Unix systems it is _not_ a
2362  copy. That interal API inconsistency "should" be resolved
2363  (==return a copy from here, but that means doing it everywhere)
2364  to avoid memory ownership problems later on.
2365 
2366  Why return a copy? Because native strings from at least one of
2367  the more widespread OSes often have to be converted to something
2368  portable and this requires allocation on such platforms, but
2369  not on Unix. For API transparency, that means all platforms get
2370  the copy(-like) behaviour.
2371 */
2372 FSL_EXPORT char *fsl_getenv(const char *zName);
2373 
2374 /**
2375  Returns a positive value if zFilename is a directory, 0 if
2376  zFilename does not exist, or a negative value if zFilename
2377  exists but is something other than a directory. Results are
2378  undefined if zFilename is NULL.
2379 
2380  This function expects zFilename to be a well-formed path -
2381  it performs no normalization on it.
2382 */
2383 FSL_EXPORT int fsl_dir_check(const char *zFilename);
2384 
2385 /**
2386  Deletes the given file from the filesystem. Returns 0 on
2387  success. If the component is a directory, this operation will
2388  fail unless the directory is empty. If zFilename refers to a
2389  symlink, the link (not its target) is removed.
2390 
2391  Results are undefined if zFilename is NULL.
2392 */
2393 FSL_EXPORT int fsl_file_unlink(const char *zFilename);
2394 
2395 /**
2396  Sets the mtime (Unix epoch) for a file. Returns 0 on success,
2397  non-0 on error. If newMTime is less than 0 then the current
2398  time(2) is used. This routine does not create non-existent files
2399  (e.g. like a Unix "touch" command).
2400 */
2401 FSL_EXPORT int fsl_file_mtime_set(const char *zFilename, fsl_time_t newMTime);
2402 
2403 /**
2404  Create the directory with the given name if it does not already
2405  exist. If forceFlag is true, delete any prior non-directory
2406  object with the same name.
2407 
2408  Return 0 on success, non-0 on error.
2409 
2410  If the directory already exists then 0 is returned, not an error
2411  (FSL_RC_ALREADY_EXISTS), because that simplifies usage. If
2412  another filesystem entry with this name exists and forceFlag is
2413  true then that entry is deleted before creating the directory,
2414  and this operation fails if deletion fails. If forceFlag is
2415  false and a non-directory entry already exists, FSL_RC_TYPE is
2416  returned.
2417 
2418  For recursively creating directories, use fsl_mkdir_for_file().
2419 
2420  Bug/corner case: if zFilename refers to a symlink to a
2421  non-existent directory, this function gets slightly confused,
2422  tries to make a dir with the symlink's name, and returns
2423  FSL_RC_ALREADY_EXISTS. How best to resolve that is not yet
2424  clear. The problem is that stat(2)ing the symlink says "nothing
2425  is there" (because the link points to a non-existing thing), so
2426  we move on to the underlying mkdir(), which then fails because
2427  the link exists with that name.
2428 */
2429 FSL_EXPORT int fsl_mkdir(const char *zName, char forceFlag);
2430 
2431 /**
2432  A convenience form of fsl_mkdir() which can recursively create
2433  directories. If zName has a trailing slash then the last
2434  component is assumed to be a directory part, otherwise it is
2435  assumed to be a file part (and no directory is created for that
2436  part). zName may be either an absolute or relative path.
2437 
2438  Returns 0 on success (including if all directories already
2439  exist). Returns FSL_RC_OOM if there is an allocation
2440  error. Returns FSL_RC_TYPE if one of the path components already
2441  exists and is not a directory. Returns FSL_RC_RANGE if
2442  zName is NULL or less than 2 bytes long.
2443 
2444  On systems which support symlinks, a link to a directory is
2445  considered to be a directory for purposes of this function.
2446 
2447  If forceFlag is true and a non-directory component is found in
2448  the filesystem where zName calls for a directory, that component
2449  is removed (and this function fails if removal fails).
2450 
2451  Examples:
2452 
2453  "/foo/bar" creates (if needed) /foo, but assumes "bar" is a file
2454  component. "/foo/bar/" creates /foo/bar. However "foo" will not
2455  create a directory - because the string has no path component,
2456  it is assumed to be a filename.
2457 
2458  Both "/foo/bar/my.doc" and "/foo/bar/" result in the directories
2459  /foo/bar.
2460 
2461 */
2462 FSL_EXPORT int fsl_mkdir_for_file(char const *zName, char forceFlag);
2463 
2464 
2465 /**
2466  Uses fsl_getenv() to look for the environment variables
2467  (FOSSIL_USER, (Windows: USERNAME), (Unix: USER, LOGNAME)). If
2468  it finds one it returns a copy of that value, which must
2469  eventually be passed to fsl_free() to free it (NOT
2470  fsl_filename_free(), though fsl_getenv() requires that one). If
2471  it finds no match, or if copying the entry fails, it returns
2472  NULL.
2473 
2474  @see fsl_cx_user_set()
2475  @see fsl_cx_user_get()
2476 */
2478 
2479 /**
2480  Tries to find the user's home directory. If found, 0 is
2481  returned, tgt's memory is _overwritten_ (not appended) with the
2482  path, and tgt->used is set to the path's string length. (Design
2483  note: the overwrite behaviour is inconsistent with most of the
2484  API, but the implementation currently requires this.)
2485 
2486  If requireWriteAccess is true then the directory is checked for
2487  write access, and FSL_RC_ACCESS is returned if that check
2488  fails. For historical (possibly techinical?) reasons, this check
2489  is only performed on Unix platforms. On others this argument is
2490  ignored. When writing code on Windows, it may be necessary to
2491  assume that write access is necessary on non-Windows platform,
2492  and to pass 1 for the second argument even though it is ignored
2493  on Windows.
2494 
2495  On error non-0 is returned and tgt is updated with an error
2496  string OR (if the error was an allocation error while appending
2497  to the path or allocating MBCS strings for Windows), it returns
2498  FSL_RC_OOM and tgt "might" be updated with a partial path (up to
2499  the allocation error), and "might" be empty (if the allocation
2500  error happens early on).
2501 
2502  This routine does not canonicalize/transform the home directory
2503  path provided by the environment, other than to convert the
2504  string byte encoding on some platforms. i.e. if the environment
2505  says that the home directory is "../" then this function will
2506  return that value, possibly to the eventual disappointment of
2507  the caller.
2508 
2509  Result codes include:
2510 
2511  - FSL_RC_OK (0) means a home directory was found and tgt is
2512  populated with its path.
2513 
2514  - FSL_RC_NOT_FOUND means the home directory (platform-specific)
2515  could not be found.
2516 
2517  - FSL_RC_ACCESS if the home directory is not writable and
2518  requireWriteAccess is true. Unix platforms only -
2519  requireWriteAccess is ignored on others.
2520 
2521  - FSL_RC_TYPE if the home (as determined via inspection of the
2522  environment) is not a directory.
2523 
2524  - FSL_RC_OOM if a memory (re)allocation fails.
2525 */
2526 FSL_EXPORT int fsl_find_home_dir( fsl_buffer * tgt, char requireWriteAccess );
2527 
2528 /**
2529  Values for use with the fsl_fstat::type field.
2530 */
2532 /** Sentinel value for unknown/invalid filesystem entry types. */
2534 /** Indicates a directory filesystem entry. */
2536 /** Indicates a non-directory, non-symlink filesystem entry.
2537  Because fossil's scope is limited to SCM work, it assumes that
2538  "special files" (sockets, etc.) are just files, and makes no
2539  special effort to handle them.
2540 */
2542 /** Indicates a symlink filesystem entry. */
2544 };
2546 
2547 /**
2548  Bitmask values for use with the fsl_fstat::perms field.
2549 */
2551 /**
2552  Sentinel value.
2553 */
2555 /**
2556  The executable bit, as understood by Fossil. Fossil does not
2557  differentiate between different +x values for user/group/other.
2558 */
2560 };
2562 
2563 /**
2564  A simple wrapper around the stat(2) structure resp. _stat/_wstat
2565  (on Windows). It exposes only the aspects of stat(2) info which
2566  Fossil works with, and not any platform-/filesystem-specific
2567  details except the executable bit for the permissions mode and some
2568  handling of symlinks.
2569 */
2570 struct fsl_fstat {
2571  /**
2572  Indicates the type of filesystem object.
2573  */
2574  fsl_fstat_type_t type;
2575  /**
2576  The time of the last file metadata change (owner, permissions,
2577  etc.). The man pages (neither for Linux nor Windows) do not
2578  specify exactly what unit this is. Let's assume seconds since the
2579  start of the Unix Epoch.
2580  */
2582  /**
2583  Last modification time.
2584  */
2586  /**
2587  The size of the stat'd file, in bytes.
2588  */
2590  /**
2591  Contains the filesystem entry's permissions as a bitmask of
2592  fsl_fstat_perm_t values. Note that only the executable bit for
2593  _files_ (not directories) is exposed here.
2594  */
2595  int perm;
2596 };
2597 
2598 /** Empty-initialized fsl_fstat structure, intended for const-copy
2599  construction. */
2600 #define fsl_fstat_empty_m {FSL_FSTAT_TYPE_UNKNOWN,0,0,0,0}
2601 
2602 /** Empty-initialized fsl_fstat instance, intended for copy
2603  construction. */
2605 
2606 /**
2607  Runs the OS's stat(2) equivalent to populate fst with
2608  information about the given file.
2609 
2610  Returns 0 on success, FSL_RC_MISUSE if zFilename is NULL, and
2611  FSL_RC_RANGE if zFilename starts with a NUL byte. Returns
2612  FSL_RC_NOT_FOUND if no filesystem entry is found for the given
2613  name. Returns FSL_RC_IO if the underlying stat() (or equivalent)
2614  fails for undetermined reasons inside the underlying
2615  stat()/_wstati64() call. Note that the fst parameter may be
2616  NULL, in which case the return value will be 0 if the name is
2617  stat-able, but will return no other information about it.
2618 
2619  The derefSymlinks argument is ignored on non-Unix platforms. On
2620  Unix platforms, if derefSymlinks is non-0 then stat(2) is used,
2621  else lstat(2) (if available on the platform) is used. For most
2622  cases clients should pass non-0. They should only pass 0 if they
2623  need to differentiate between symlinks and files.
2624 
2625  The fsl_fstat_type_t family of flags can be used to determine
2626  the type of the filesystem object being stat()'d (file,
2627  directory, or symlink). It does apply any special logic for
2628  platform-specific oddities other than symlinks (e.g. character
2629  devices and such).
2630 */
2631 FSL_EXPORT int fsl_stat(const char *zFilename, fsl_fstat * fst, char derefSymlinks );
2632 
2633 /**
2634  Create a new delta between the memory zIn and zOut.
2635 
2636  The delta is written into a preallocated buffer, zDelta, which
2637  must be at least 60 bytes longer than the target memory, zOut.
2638  The delta string will be NUL-terminated, but it might also
2639  contain embedded NUL characters if either the zSrc or zOut files
2640  are binary.
2641 
2642  On success this function returns 0 and the length of the delta
2643  string, in bytes, excluding the final NUL terminator character,
2644  is written to *deltaSize.
2645 
2646  Returns FSL_RC_MISUSE if any of the pointer arguments are NULL
2647  and FSL_RC_OOM if memory allocation fails during generation of
2648  the delta. Returns FSL_RC_RANGE if lenSrc or lenOut are "too
2649  big" (if they cause an overflow in the math).
2650 
2651  Output Format:
2652 
2653  The delta begins with a base64 number followed by a newline.
2654  This number is the number of bytes in the TARGET file. Thus,
2655  given a delta file z, a program can compute the size of the
2656  output file simply by reading the first line and decoding the
2657  base-64 number found there. The fsl_delta_applied_size()
2658  routine does exactly this.
2659 
2660  After the initial size number, the delta consists of a series of
2661  literal text segments and commands to copy from the SOURCE file.
2662  A copy command looks like this:
2663 
2664  (Achtung: extra backslashes are for Doxygen's benefit - not
2665  visible in the processsed docs.)
2666 
2667  NNN\@MMM,
2668 
2669  where NNN is the number of bytes to be copied and MMM is the
2670  offset into the source file of the first byte (both base-64).
2671  If NNN is 0 it means copy the rest of the input file. Literal
2672  text is like this:
2673 
2674  NNN:TTTTT
2675 
2676  where NNN is the number of bytes of text (base-64) and TTTTT is
2677  the text.
2678 
2679  The last term is of the form
2680 
2681  NNN;
2682 
2683  In this case, NNN is a 32-bit bigendian checksum of the output
2684  file that can be used to verify that the delta applied
2685  correctly. All numbers are in base-64.
2686 
2687  Pure text files generate a pure text delta. Binary files
2688  generate a delta that may contain some binary data.
2689 
2690  Algorithm:
2691 
2692  The encoder first builds a hash table to help it find matching
2693  patterns in the source file. 16-byte chunks of the source file
2694  sampled at evenly spaced intervals are used to populate the hash
2695  table.
2696 
2697  Next we begin scanning the target file using a sliding 16-byte
2698  window. The hash of the 16-byte window in the target is used to
2699  search for a matching section in the source file. When a match
2700  is found, a copy command is added to the delta. An effort is
2701  made to extend the matching section to regions that come before
2702  and after the 16-byte hash window. A copy command is only
2703  issued if the result would use less space that just quoting the
2704  text literally. Literal text is added to the delta for sections
2705  that do not match or which can not be encoded efficiently using
2706  copy commands.
2707 
2708  @see fsl_delta_applied_size()
2709  @see fsl_delta_apply()
2710 */
2711 FSL_EXPORT int fsl_delta_create( unsigned char const *zSrc, fsl_size_t lenSrc,
2712  unsigned char const *zOut, fsl_size_t lenOut,
2713  unsigned char *zDelta, fsl_size_t * deltaSize);
2714 
2715 /**
2716  Works identically to fsl_delta_create() but sends its output to
2717  the given output function. out(outState,...) may be called any
2718  number of times to emit delta output. Each time it is called it
2719  should append the new bytes to its output channel.
2720 
2721  The semantics of the return value and the first four arguments
2722  are identical to fsl_delta_create(), with these ammendments
2723  regarding the return value:
2724 
2725  - Returns FSL_RC_MISUSE if any of (zSrc, zOut, out) are NULL.
2726 
2727  - If out() returns non-0 at any time, delta generation is
2728  aborted and that code is returned.
2729 
2730  Example usage:
2731 
2732  @code
2733  int rc = fsl_delta_create( v1, v1len, v2, v2len,
2734  fsl_output_f_FILE, stdout);
2735  @endcode
2736 */
2737 FSL_EXPORT int fsl_delta_create2( unsigned char const *zSrc, fsl_size_t lenSrc,
2738  unsigned char const *zOut, fsl_size_t lenOut,
2739  fsl_output_f out, void * outState);
2740 
2741 /**
2742  A fsl_delta_create() wrapper which uses the first two arguments
2743  as the original and "new" content versions to delta, and outputs
2744  the delta to the 3rd argument (overwriting any existing contents
2745  and re-using any memory it had allocated).
2746 
2747  If the output buffer (delta) is the same as src or newVers,
2748  FSL_RC_MISUSE is returned, and results are undefined if delta
2749  indirectly refers to the same buffer as either src or newVers.
2750 
2751  Returns 0 on success.
2752 */
2754  fsl_buffer const * newVers,
2755  fsl_buffer * delta);
2756 
2757 /**
2758  Apply a delta created using fsl_delta_create().
2759 
2760  The output buffer must be big enough to hold the whole output
2761  file and a NUL terminator at the end. The
2762  fsl_delta_applied_size() routine can be used to determine that
2763  size.
2764 
2765  zSrc represents the original sources to apply the delta to.
2766  It must be at least lenSrc bytes of valid memory.
2767 
2768  zDelta holds the delta (created using fsl_delta_create()),
2769  and it must be lenDelta bytes long.
2770 
2771  On success this function returns 0 and writes the applied delta
2772  to zOut.
2773 
2774  Returns FSL_RC_MISUSE if any pointer argument is NULL. Returns
2775  FSL_RC_RANGE if lenSrc or lenDelta are "too big" (if they cause
2776  an overflow in the math). Invalid delta input can cause any of
2777  FSL_RC_RANGE, FSL_RC_DELTA_INVALID_TERMINATOR,
2778  FSL_RC_CHECKSUM_MISMATCH, FSL_RC_SIZE_MISMATCH, or
2779  FSL_RC_DELTA_INVALID_OPERATOR to be returned.
2780 
2781  Refer to the fsl_delta_create() documentation above for a
2782  description of the delta file format.
2783 
2784  @see fsl_delta_applied_size()
2785  @see fsl_delta_create()
2786  @see fsl_delta_apply2()
2787 */
2788 FSL_EXPORT int fsl_delta_apply( unsigned char const *zSrc, fsl_size_t lenSrc,
2789  unsigned char const *zDelta, fsl_size_t lenDelta,
2790  unsigned char *zOut );
2791 
2792 /**
2793  Functionally identical to fsl_delta_apply() but any errors generated
2794  during application of the delta are described in more detail
2795  in pErr. If pErr is NULL this behaves exactly as documented for
2796  fsl_delta_apply().
2797 */
2798 FSL_EXPORT int fsl_delta_apply2( unsigned char const *zSrc,
2799  fsl_size_t lenSrc,
2800  unsigned char const *zDelta,
2801  fsl_size_t lenDelta,
2802  unsigned char *zOut,
2803  fsl_error * pErr);
2804 /*
2805  Calculates the size (in bytes) of the output from applying a the
2806  given delta. On success 0 is returned and *appliedSize will be
2807  updated with the amount of memory required for applying the
2808  delta. zDelta must point to lenDelta bytes of memory in the
2809  format emitted by fsl_delta_create(). It is legal for appliedSize
2810  to point to the same memory as the 2nd argument.
2811 
2812  Returns FSL_RC_MISUSE if any pointer argument is NULL. Returns
2813  FSL_RC_RANGE if lenDelta is too short to be a delta. Returns
2814  FSL_RC_DELTA_INVALID_TERMINATOR if the delta's encoded length
2815  is not properly terminated.
2816 
2817  This routine is provided so that an procedure that is able to
2818  call fsl_delta_apply() can learn how much space is required for
2819  the output and hence allocate nor more space that is really
2820  needed.
2821 
2822  TODO?: consolidate 2nd and 3rd parameters into one i/o parameter?
2823 
2824  @see fsl_delta_apply()
2825  @see fsl_delta_create()
2826 */
2827 FSL_EXPORT int fsl_delta_applied_size(unsigned char const *zDelta,
2828  fsl_size_t lenDelta,
2829  fsl_size_t * appliedSize);
2830 
2831 /**
2832  "Fossilizes" the first len bytes of the given input string. If
2833  (len<0) then fsl_strlen(inp) is used to calculate its length.
2834  The output is appended to out, which is expanded as needed and
2835  out->used is updated accordingly. Returns 0 on success,
2836  FSL_RC_MISUSE if !inp or !out. Returns 0 without side-effects if
2837  0==len or (!*inp && len<0). Returns FSL_RC_OOM if reservation of
2838  the output buffer fails (it is expanded, at most, one time by
2839  this function).
2840 
2841  Fossilization replaces the following bytes/sequences with the
2842  listed replacements:
2843 
2844  (Achtung: usage of doubled backslashes here it just to please
2845  doxygen - they will show up as single slashes in the processed
2846  output.)
2847 
2848  - Backslashes are doubled.
2849 
2850  - (\\n, \\r, \\v, \\t, \\f) are replaced with \\\\X, where X is the
2851  conventional encoding letter for that escape sequence.
2852 
2853  - Spaces are replaced with \\s.
2854 
2855  - Embedded NULs are replaced by \\0 (numeric 0, not character
2856  '0').
2857 */
2858 FSL_EXPORT int fsl_bytes_fossilize( unsigned char const * inp, fsl_int_t len,
2859  fsl_buffer * out );
2860 /**
2861  "Defossilizes" bytes encoded by fsl_bytes_fossilize() in-place.
2862  inp must be a string encoded by fsl_bytes_fossilize(), and the
2863  decoding processes stops at the first unescaped NUL terminator.
2864  It has no error conditions except for !inp or if inp is not
2865  NUL-terminated, both of which invoke in undefined behaviour.
2866 
2867  If resultLen is not NULL then *resultLen is set to the resulting string
2868  length.
2869 
2870 */
2871 FSL_EXPORT void fsl_bytes_defossilize( unsigned char * inp, fsl_size_t * resultLen );
2872 
2873 /**
2874  Defossilizes the contents of b. Equivalent to:
2875  fsl_bytes_defossilize( b->mem, &b->used );
2876 */
2878 
2879 /**
2880  Return true (non-0) if the input string contains only valid base-16
2881  digits. If any invalid characters appear in the string, return
2882  0 (false).
2883 */
2884 FSL_EXPORT char fsl_validate16(const char *zIn, fsl_size_t nIn);
2885 
2886 /**
2887  The input string is a base16 value. Convert it into its canonical
2888  form. This means that digits are all lower case and that conversions
2889  like "l"->"1" and "O"->"0" occur.
2890 */
2891 FSL_EXPORT void fsl_canonical16(char *z, fsl_size_t n);
2892 
2893 /**
2894  Decode a N-character base-16 number into base-256. N must be a
2895  multiple of 2. The output buffer must be at least N/2 characters
2896  in length. Returns 0 on success.
2897 */
2898 FSL_EXPORT int fsl_decode16(const unsigned char *zIn, unsigned char *pOut, fsl_size_t N);
2899 
2900 /**
2901  Encode a N-digit base-256 in base-16. N is the byte length of pIn
2902  and zOut must be at least (N*2+1) bytes long (the extra is for a
2903  terminating NUL). Returns zero on success, FSL_RC_MISUSE if !pIn
2904  or !zOut.
2905 */
2906 FSL_EXPORT int fsl_encode16(const unsigned char *pIn, unsigned char *zOut, fsl_size_t N);
2907 
2908 
2909 /**
2910  Tries to convert the value of errNo, which is assumed to come
2911  from the global errno, to a fsl_rc_t code. If it can, it returns
2912  something approximating the errno value, else it returns dflt.
2913 
2914  Example usage:
2915 
2916  @code
2917  FILE * f = fsl_fopen("...", "...");
2918  int rc = f ? 0 : fsl_errno_to_rc(errno, FSL_RC_IO);
2919  ...
2920  @endcode
2921 
2922  Why require the caller to pass in errno, instead of accessing it
2923  directly from this function? To avoid the the off-chance that
2924  something changes errno between the call and the conversion
2925  (whether or not that's possible is as yet undetermined). It can
2926  also be used by clients to map to explicit errno values to
2927  fsl_rc_t values, e.g. fsl_errno_to_rc(EROFS,-1) returns
2928  FSL_RC_ACCESS.
2929 
2930  A list of the errno-to-fossil conversions:
2931 
2932  - EINVAL: FSL_RC_MISUSE (could arguably be FSL_RC_RANGE, though)
2933 
2934  - ENOMEM: FSL_RC_OOM
2935 
2936  - EACCES, EBUSY, EPERM: FSL_RC_ACCESS
2937 
2938  - EISDIR, ENOTDIR: FSL_RC_TYPE
2939 
2940  - ENAMETOOLONG, ELOOP: FSL_RC_RANGE
2941 
2942  - ENOENT: FSL_RC_NOT_FOUND
2943 
2944  - EEXIST: FSL_RC_ALREADY_EXISTS
2945 
2946  - EIO: FSL_RC_IO
2947 
2948  Any other value for errNo causes dflt to be returned.
2949 
2950 */
2951 FSL_EXPORT int fsl_errno_to_rc(int errNo, int dflt);
2952 
2953 /**
2954  Make the given string safe for HTML by converting every "<" into
2955  "&lt;", every ">" into "&gt;", every "&" into "&amp;", and
2956  encode '"' as &quot; so that it can appear as an argument to
2957  markup.
2958 
2959  The escaped output is send to out(oState,...).
2960 
2961  Returns 0 on success or if there is nothing to do (input has a
2962  length of 0, in which case out() is not called). Returns
2963  FSL_RC_MISUSE if !out or !zIn. If out() returns a non-0 code
2964  then that value is returned to the caller.
2965 
2966  If n is negative, fsl_strlen() is used to calculate zIn's length.
2967 */
2968 FSL_EXPORT int fsl_htmlize(fsl_output_f out, void * oState,
2969  const char *zIn, fsl_int_t n);
2970 
2971 /**
2972  Functionally equivalent to fsl_htmlize() but optimized to perform
2973  only a single allocation.
2974 
2975  Returns 0 on success or if there is nothing to do (input has a
2976  length of 0). Returns FSL_RC_MISUSE if !p or !zIn, and
2977  FSL_RC_OOM on allocation error.
2978 
2979  If n is negative, fsl_strlen() is used to calculate zIn's length.
2980 */
2981 FSL_EXPORT int fsl_htmlize_to_buffer(fsl_buffer *p, const char *zIn, fsl_int_t n);
2982 
2983 /**
2984  Equivalent to fsl_htmlize_to_buffer() but returns the result as a
2985  new string which must eventually be fsl_free()d by the caller.
2986 
2987  Returns NULL for invalidate arguments or allocation error.
2988 */
2989 FSL_EXPORT char *fsl_htmlize_str(const char *zIn, fsl_int_t n);
2990 
2991 
2992 /**
2993  If c is a character Fossil likes to HTML-escape, assigns *xlate
2994  to its transformed form, else set it to NULL. Returns 1 for
2995  untransformed characters and the strlen of *xlate for others.
2996  Bytes returned via xlate are static and immutable.
2997 
2998  Results are undefined if xlate is NULL.
2999 */
3000 FSL_EXPORT fsl_size_t fsl_htmlize_xlate(int c, char const ** xlate);
3001 
3002 /**
3003  Flags for use with text-diff generation APIs,
3004  e.g. fsl_diff_text().
3005 
3006  Maintenance reminder: these values are holy and must not be
3007  changed without also changing the corresponding code in
3008  fsl_diff.c.
3009 */
3011 /** Ignore end-of-line whitespace */
3013 /** Ignore end-of-line whitespace */
3015 /** Generate a side-by-side diff */
3017 /** Missing shown as empty files */
3019 /** Show filenames only. Not used in this impl! */
3021 /** Render HTML. */
3023 /** Show line numbers. */
3025 /** Suppress optimizations (debug). */
3027 /** Invert the diff (debug). */
3029 /** Only display if not "too big." */
3031 /** Strip trailing CR */
3033 /**
3034  This flag tells text-mode diff generation to add ANSI color
3035  sequences to some output. The colors are currently hard-coded
3036  and non-configurable. This has no effect for HTML output, and
3037  that flag trumps this one. It also currently only affects
3038  unified diffs, not side-by-side.
3039 
3040  Maintenance reminder: this one currently has no counterpart in
3041  fossil(1), is not tracked in the same way, and need not map to an
3042  internal flag value. That's a good thing, because we'll be out
3043  of flags once Jan's done tinkering in fossil(1) ;).
3044 */
3046 };
3047 
3048 /**
3049  Generates a textual diff from two text inputs and writes
3050  it to the given output function.
3051 
3052  pA and pB are the buffers to diff.
3053 
3054  contextLines is the number of lines of context to output. This
3055  parameter has a built-in limit of 2^16, and values larger than
3056  that get truncated. A value of 0 is legal, in which case no
3057  surrounding context is provided. A negative value translates to
3058  some unspecified default value.
3059 
3060  sbsWidth specifies the width (in characters) of the side-by-side
3061  columns. If sbsWidth is not 0 then this function behaves as if
3062  diffFlags contains the FSL_DIFF_SIDEBYSIDE flag. If sbsWidth is
3063  negative, OR if diffFlags explicitly contains
3064  FSL_DIFF_SIDEBYSIDE and sbsWidth is 0, then some default width
3065  is used. This parameter has a built-in limit of 255, and values
3066  larger than that get truncated to 255.
3067 
3068  diffFlags is a mask of fsl_diff_flag_t values. Not all of the
3069  fsl_diff_flag_t flags are yet [sup]ported.
3070 
3071  The output is sent to out(outState,...). If out() returns non-0
3072  during processing, processing stops and that result is returned
3073  to the caller of this function.
3074 
3075  Returns 0 on success, FSL_RC_OOM on allocation error,
3076  FSL_RC_MISUSE if any arguments are invalid, FSL_RC_TYPE if any
3077  of the content appears to be binary (contains embedded NUL
3078  bytes), FSL_RC_RANGE if some range is exceeded (e.g. the maximum
3079  number of input lines).
3080 
3081  None of (pA, pB, out) may be NULL.
3082 
3083  TODOs:
3084 
3085  - Add a predicate function for outputing only matching
3086  differences, analog to fossil(1)'s regex support (but more
3087  flexible).
3088 
3089  - Expose the raw diff-generation bits via the internal API
3090  to facilitate/enable the creation of custom diff formats.
3091 */
3092 FSL_EXPORT int fsl_diff_text(fsl_buffer const *pA, fsl_buffer const *pB,
3093  fsl_output_f out, void * outState,
3094  short contextLines, short sbsWidth,
3095  int diffFlags );
3096 
3097 /**
3098  Functionally equivalent to:
3099 
3100  @code:
3101  fsl_diff_text(pA, pB, fsl_output_f_buffer, pOut,
3102  contextLines, sbsWidth, diffFlags);
3103  @endcode
3104 
3105  Except that it returns FSL_RC_MISUSE if !pOut.
3106 */
3107 FSL_EXPORT int fsl_diff_text_to_buffer(fsl_buffer const *pA, fsl_buffer const *pB,
3108  fsl_buffer *pOut, short contextLines,
3109  short sbsWidth, int diffFlags );
3110 
3111 
3112 /**
3113  If zDate is an ISO8601-format string, optionally with a .NNN
3114  fractional suffix, then this function returns true and sets
3115  *pOut (if pOut is not NULL) to the corresponding Julian
3116  value. If zDate is not an ISO8601-format string then this
3117  returns false (0) and pOut is not modified.
3118 
3119  This function does NOT confirm that zDate ends with a NUL
3120  byte. i.e. if passed a valid date string which has trailing
3121  bytes after it then those are simply ignored. This is so that it
3122  can be used to read subsets of larger strings.
3123 
3124  Achtung: this calculation may, due to voodoo-level
3125  floating-point behaviours, differ by a small fraction of a point
3126  (at the millisecond level) for a given input compared to other
3127  implementations (e.g. sqlite's strftime() _might_ differ by a
3128  millisecond or two or _might_ not). Thus this routine should not
3129  be used when 100% round-trip fidelity is required, but is close
3130  enough for routines which do not require 100% millisecond-level
3131  fidelity in time conversions.
3132 
3133  @see fsl_julian_to_iso8601()
3134 */
3135 FSL_EXPORT char fsl_iso8601_to_julian( char const * zDate, fsl_double_t * pOut );
3136 
3137 /**
3138  Converts the Julian Day J to an ISO8601 time string. If addMs is
3139  true then the string includes the '.NNN' fractional part, else
3140  it will not. This function writes (on success) either 20 or 24
3141  bytes (including the terminating NUL byte) to pOut, depending on
3142  the value of addMs, and it is up to the caller to ensure that
3143  pOut is at least that long.
3144 
3145  Returns true (non-0) on success and the only error conditions
3146  [it can catch] are if pOut is NULL, J is less than 0, or
3147  evaluates to a time value which does not fit in ISO8601
3148  (e.g. only years 0-9999 are supported).
3149 
3150  @see fsl_iso8601_to_julian()
3151 */
3152 FSL_EXPORT char fsl_julian_to_iso8601( fsl_double_t J, char * pOut, char addMs );
3153 
3154 /**
3155  Returns the Julian Day time J value converted to a Unix Epoch
3156  timestamp. It assumes 86400 seconds per day and does not account
3157  for any sort leap seconds, leap years, leap frogs, or any other
3158  kind of leap, up to and including a leap of faith.
3159 */
3161 
3162 /**
3163  Performs a chdir() to the directory named by zChDir.
3164 
3165  Returns 0 on success. On error it tries to convert the
3166  underlying errno to one of the FSL_RC_xxx values, falling
3167  back to FSL_RC_IO if it cannot figure out anything more
3168  specific.
3169 */
3170 FSL_EXPORT int fsl_chdir(const char *zChDir);
3171 
3172 /**
3173  A strftime() implementation.
3174 
3175  dest must be valid memory at least destLen bytes long. The result
3176  will be written there.
3177 
3178  fmt must contain the format string. See the file fsl_strftime.c
3179  for the complete list of format specifiers and their descriptions.
3180 
3181  timeptr must be the time the caller wants to format.
3182 
3183  Returns 0 if any arguments are NULL.
3184 
3185  On success it returns the number of bytes written to dest, not
3186  counting the terminating NUL byte (which it also writes). It
3187  returns 0 on any error, and the client may need to distinguish
3188  between real errors and (destLen==0 or !*fmt), both of which could
3189  also look like errors.
3190 
3191  TODOs:
3192 
3193  - Refactor this to take a callback or a fsl_buffer, so that we can
3194  format arbitrarily long output.
3195 
3196  - Refactor it to return an integer error code.
3197 
3198  (This implementation is derived from public domain sources
3199  dating back to the early 1990's.)
3200 */
3201 FSL_EXPORT fsl_size_t fsl_strftime(char *dest, fsl_size_t destLen,
3202  const char *format, const struct tm *timeptr);
3203 
3204 /**
3205  A convenience form of fsl_strftime() which takes its timestamp in
3206  the form of a Unix Epoch time. See fsl_strftime() for the
3207  semantics of the first 3 arguments and the return value. If
3208  convertToLocal is true then epochTime gets converted to local
3209  time (via, oddly enough, localtime(3)), otherwise gmtime(3) is
3210  used for the conversion.
3211 
3212  BUG: this function uses static state and is not thread-safe.
3213 */
3214 FSL_EXPORT fsl_size_t fsl_strftime_unix(char * dest, fsl_size_t destLen, char const * format,
3215  fsl_time_t epochTime, char convertToLocal);
3216 
3217 
3218 /**
3219  A convenience form of fsl_strftime() which assumes that the
3220  formatted string is of "some reasonable size" and appends its
3221  formatted representation to b. Returns 0 on success, non-0 on
3222  error. If any argument is NULL or !*format then FSL_RC_MISUSE is
3223  returned. FSL_RC_RANGE is returned if the underlying call to
3224  fsl_strftime() fails (which it will if the format string
3225  resolves to something "unususually long"). It returns FSL_RC_OOM
3226  if appending to b fails due to an allocation error.
3227 */
3228 FSL_EXPORT int fsl_buffer_strftime(fsl_buffer * b, char const * format, const struct tm *timeptr);
3229 
3230 /**
3231  The "Path Finder" class is a utility class for searching the
3232  filesystem for files matching a set of common prefixes and/or
3233  suffixes (i.e. directories and file extensions).
3234 
3235  Example usage:
3236 
3237  @code
3238  fsl_pathfinder pf = fsl_pathfinder_empty;
3239  int rc;
3240  char const * found = NULL;
3241  rc = fsl_pathfinder_ext_add( &pf, ".doc" );
3242  if(rc) { ...error... }
3243  // The following error checks are elided for readability:
3244  rc = fsl_pathfinder_ext_add( &pf, ".txt" );
3245  rc = fsl_pathfinder_ext_add( &pf, ".wri" );
3246  rc = fsl_pathfinder_dir_add( &pf, "." );
3247  rc = fsl_pathfinder_dir_add( &pf, "/my/doc/dir" );
3248  rc = fsl_pathfinder_dir_add( &pf, "/other/doc/dir" );
3249 
3250  rc = fsl_pathfinder_search( &pf, "MyDoc", &found, NULL);
3251  if(0==rc){ assert(NULL!=found); }
3252 
3253  // Eventually clean up:
3254  fsl_pathfinder_clear(&pf);
3255  @endcode
3256 
3257  @see fsl_pathfinder_dir_add()
3258  @see fsl_pathfinder_ext_add()
3259  @see fsl_pathfinder_clear()
3260  @see fsl_pathfinder_search()
3261 */
3263  /**
3264  Holds the list of search extensions. Each entry
3265  is a (char *) owned by this object.
3266  */
3268  /**
3269  Holds the list of search directories. Each entry is a (char *)
3270  owned by this object.
3271  */
3273  /**
3274  Used to build up a path string during fsl_pathfinder_search(),
3275  and holds the result of a successful search. We use a buffer,
3276  as opposed to a simple string, because (A) it simplifies the
3277  search implementation and (B) reduces allocations (it gets
3278  reused for each search).
3279  */
3281 };
3282 
3284 /**
3285  Initialized-with-defaults fsl_pathfinder instance, intended for
3286  const copy initialization.
3287 */
3288 #define fsl_pathfinder_empty_m {fsl_list_empty_m/*ext*/,fsl_list_empty_m/*dirs*/,fsl_buffer_empty_m/*buf*/}
3289 
3290 /**
3291  Initialized-with-defaults fsl_pathfinder instance, intended for
3292  copy initialization.
3293 */
3295 
3296 /**
3297  Frees all memory associated with pf, but does not free pf.
3298  Is a no-op if pf is NULL.
3299 */
3301 
3302 /**
3303  Adds the given directory to pf's search path. Returns 0 on
3304  success, FSL_RC_MISUSE if !pf or !dir (dir _may_ be an empty
3305  string), FSL_RC_OOM if copying the string or adding it to the
3306  list fails.
3307 
3308  @see fsl_pathfinder_ext_add()
3309  @see fsl_pathfinder_search()
3310 */
3311 FSL_EXPORT int fsl_pathfinder_dir_add(fsl_pathfinder * pf, char const * dir);
3312 
3313 /**
3314  Adds the given directory to pf's search extensions. Returns 0 on
3315  success, FSL_RC_MISUSE if !pf or !dir (dir _may_ be an empty
3316  string), FSL_RC_OOM if copying the string or adding it to the
3317  list fails.
3318 
3319  Note that the client is responsible for adding a "." to the
3320  extension, if needed, as this API does not apply any special
3321  meaning to any characters in a search extension. e.g. "-journal"
3322  and "~" are both perfectly valid extensions for this purpose.
3323 
3324  @see fsl_pathfinder_dir_add()
3325  @see fsl_pathfinder_search()
3326 */
3327 FSL_EXPORT int fsl_pathfinder_ext_add(fsl_pathfinder * pf, char const * ext);
3328 
3329 /**
3330  Searches for a file whose name can be constructed by some
3331  combination of pf's directory/suffix list and the given base
3332  name.
3333 
3334  It searches for files in the following manner:
3335 
3336  If the 2nd parameter exists as-is in the filesystem, it is
3337  treated as a match, otherwise... Loop over all directories
3338  in pf->dirs. Create a path with DIR/base, or just base if
3339  the dir entry is empty (length of 0). Check for a match.
3340  If none is found, then... Loop over each extension in
3341  pf->ext, creating a path named DIR/baseEXT (note that it
3342  does not add any sort of separator between the base and the
3343  extensions, so "~" and "-foo" are legal extensions). Check
3344  for a match.
3345 
3346  On success (a readable filesystem entry is found):
3347 
3348  - It returns 0.
3349 
3350  - If pOut is not NULL then *pOut is set to the path it
3351  found. The bytes of the returned string are only valid until the
3352  next search operation on pf, so copy them if you need them.
3353  Note that the returned path is _not_ normalized via
3354  fsl_file_canonical_name() or similar, and it may very well
3355  return a relative path (if base or one of pf->dirs contains a
3356  relative path part).
3357 
3358  - If outLen is not NULL, *outLen will be set to the
3359  length of the returned string.
3360 
3361  On error:
3362 
3363  - Returns FSL_RC_MISUSE if !pf, !base, !*base.
3364 
3365  - Returns FSL_RC_OOM on allocation error (it uses a buffer to
3366  hold its path combinations and return value).
3367 
3368  - Returns FSL_RC_NOT_FOUND if it finds no entry.
3369 
3370  The host platform's customary path separator is used to separate
3371  directory/file parts ('\\' on Windows and '/' everywhere else).
3372 
3373  Note that it _is_ legal for pOut and outLen to both be NULL, in
3374  which case a return of 0 signals that an entry was found, but
3375  the client has no way of knowing what path it might be (unless,
3376  of course, he relies on internal details of the fsl_pathfinder
3377  API, which he most certainly should not do).
3378 
3379  Tip: if the client wants to be certain that this function will
3380  not allocate memory, simply use fsl_buffer_reserve() on pf->buf
3381  to reserve the desired amount of space in advance. As long as
3382  the search paths never extend that length, this function will
3383  not need to allocate. (Until/unless the following TODO is
3384  implemented...)
3385 
3386  Potential TODO: use fsl_file_canonical_name() so that the search
3387  dirs themselves do not need to be entered using
3388  platform-specific separators. The main reason it's not done now
3389  is that it requires another allocation. The secondary reason is
3390  because it's sometimes useful to use relative paths in this
3391  context (based on usage in previous trees from which this code
3392  derives).
3393 
3394  @see fsl_pathfinder_dir_add()
3395  @see fsl_pathfinder_ext_add()
3396  @see fsl_pathfinder_clear()
3397 */
3398 FSL_EXPORT int fsl_pathfinder_search(fsl_pathfinder * pf, char const * base,
3399  char const ** pOut, fsl_size_t * outLen );
3400 
3401 
3402 /**
3403  Result codes for the fsl_confirmation_f() family of functions.
3404 */
3406 /**
3407  Indicates there was some unrecoverable error during prompting.
3408  Should be used with care.
3409 */
3411 /**
3412  Indicates that the answer to the question at hand is "yes" or "okay."
3413 */
3415 /**
3416  Indicates that the answer to the question at hand is "yes" or
3417  "okay" and that the same answer should be assumed for any number
3418  of a series of similar questions. This is intended to have
3419  semantics similar to answering questions like "replace this
3420  file, cancel, or replace this and all up-coming files?"
3421 */
3423 /**
3424  This is the converse of FSL_CONFIRM_YES.
3425 */
3427 /**
3428  This is the converse of FSL_CONFIRM_YES_ALL.
3429 */
3431 };
3432 
3433 /**
3434  An interface for routines which answer a yes/no question, either
3435  via human interaction or programatic decisions.
3436 
3437  Conventions:
3438 
3439  The state parameter is arbitrary state needed for the confirmation,
3440  and its type is implementation-specified.
3441 
3442  msg is a message to present to the user (if any), and msgLen is
3443  its length in bytes.
3444 
3445  Must return one of the fsl_confirmation_t values to indicate
3446  the result of the question.
3447 */
3448 typedef int (*fsl_confirmation_f)(void * state, char const * msg, fsl_size_t msgLen);
3449 
3450 /**
3451  NOT YET IMPLEMENTED.
3452 
3453  A fsl_confirmation_f() implementation which reads from the opened FILE handle
3454  passed as the first argument.
3455 */
3456 typedef int fsl_confirmation_f_console_FILE(void * state, char const * msg, fsl_size_t msgLen);
3457 
3458 /**
3459  A fsl_confirmation_f() implementation which expects the state
3460  parameter to be a (int [const] *) which dereferences to one of
3461  the FSL_CONFIRM_xxx values, defaulting to FSL_CONFIRM_ERROR.
3462  This function simply returns that value on each call, ignoring
3463  its msg and msgLen parameters. It does not modify the state.
3464 
3465  Why? This can be used to feed a client-held status integer (not
3466  necessarily const) to the callback system. It was originally
3467  conceived for unit testing, but might find a client-side use or
3468  two. e.g. a simple progress dialog might implement its cancel
3469  operation via this callback, initially setting the state value
3470  (integer) to FSL_CONFIRM_YES, and changing it to
3471  FSL_CONFIRM_NO_ALL if the cancel button is clicked. The next
3472  time confirmation is called for, it would fail and the operation
3473  in question would be aborted.
3474 */
3475 FSL_EXPORT int fsl_confirmation_f_int(void * state, char const * msg, fsl_size_t msgLen);
3476 
3477 /**
3478  A helper type which wraps a fsl_confirmation_f() and its state
3479  into one object.
3480 */
3482  /**
3483  State to be passed as the first argument to this->f().
3484  */
3485  void * state;
3486  /**
3487  A confirmation function.
3488  */
3490 };
3492 /**
3493  Initialized-with-defaults fsl_confirmer struct.
3494 */
3495 #define fsl_confirmer_empty_m {NULL,NULL}
3496 /**
3497  Initialized-with-defaults fsl_confirmer struct.
3498 */
3500 
3501 /**
3502  Creates a formatted message string using fsl_appendf(fmt,...) and passes
3503  that message to f(state,...). On success (message allocation succeeds)
3504  then the result of the call to f() is returned, otherwise
3505 */
3506 FSL_EXPORT int fsl_confirm( fsl_confirmation_f f, void * state, char const * fmt, ... );
3507 
3508 /**
3509  The va_list counterpart of fsl_confirm().
3510 */
3511 FSL_EXPORT int fsl_confirmv( fsl_confirmation_f f, void * state, char const * fmt, va_list );
3512 
3513 
3514 /**
3515  A utility class for creating ZIP-format archives. All members
3516  are internal details and must not be mucked about with by the
3517  client. See fsl_zip_file_add() for an example of how to use it.
3518 
3519  Note that it creates ZIP content in memory, as opposed to
3520  streaming it (it is not yet certain if abstractly streaming a
3521  ZIP is possible), so creating a ZIP file this way is exceedingly
3522  memory-hungry.
3523 
3524  @see fsl_zip_file_add()
3525  @see fsl_zip_timestamp_set_julian()
3526  @see fsl_zip_timestamp_set_unix()
3527  @see fsl_zip_end()
3528  @see fsl_zip_body()
3529  @see fsl_zip_finalize()
3530 */
3532  /**
3533  Number of entries (files + dirs) added to the zip file so far.
3534  */
3536  /**
3537  Current DOS-format time of the ZIP.
3538  */
3540  /**
3541  Current DOS-format date of the ZIP.
3542  */
3544  /**
3545  Current Unix Epoch time of the ZIP.
3546  */
3548  /**
3549  An artificial root directory which gets prefixed
3550  to all inserted filenames.
3551  */
3552  char * rootDir;
3553  /**
3554  The buffer for the table of contents.
3555  */
3557  /**
3558  The buffer for the ZIP file body.
3559  */
3561  /**
3562  Internal scratchpad for ops which often allocate
3563  small buffers.
3564  */
3566  /**
3567  The current list of directory entries (as (char *)).
3568  */
3570 };
3572 
3573 /**
3574  An initialized-with-defaults fsl_zip_writer instance, intended
3575  for in-struct or const-copy initialization.
3576 */
3577 #define fsl_zip_writer_empty_m { \
3578  0/*entryCount*/, \
3579  0/*dosTime*/, \
3580  0/*dosDate*/, \
3581  0/*unixTime*/, \
3582  NULL/*rootDir*/, \
3583  fsl_buffer_empty_m/*toc*/, \
3584  fsl_buffer_empty_m/*body*/, \
3585  fsl_buffer_empty_m/*scratch*/, \
3586  fsl_list_empty_m/*dirs*/ \
3587  }
3588 
3589 /**
3590  An initialized-with-defaults fsl_zip_writer instance,
3591  intended for copy-initialization.
3592 */
3594 
3595 /**
3596  Sets a virtual root directory in z, such that all files added
3597  with fsl_zip_file_add() will get this directory prefixed to
3598  it.
3599 
3600  If zRoot is NULL or empty then this clears the virtual root,
3601  otherwise is injects any directory levels it needs to into the
3602  being-generated ZIP. Note that zRoot may contain multiple levels
3603  of directories, e.g. "foo/bar/baz", but it must be legal for
3604  use in a ZIP file.
3605 
3606  This routine copies zRoot's bytes, so they may be transient.
3607 
3608  Returns 0 on success, FSL_RC_ERROR if !z, FSL_RC_OOM on
3609  allocation error. Returns FSL_RC_RANGE if zRoot is an absolute
3610  path or if zRoot cannot be normalized to a "simplified name" (as
3611  per fsl_is_simple_pathname(), with the note that this routine
3612  will pass a copy of zRoot through fsl_file_simplify_name()
3613  first).
3614 
3615  @see fsl_zip_finalize()
3616 */
3617 FSL_EXPORT int fsl_zip_root_set(fsl_zip_writer * z, char const * zRoot );
3618 
3619 /**
3620  Adds a file or directory to the ZIP writer z. zFilename is the
3621  virtual name of the file or directory. If pContent is NULL then
3622  it is assumed that we are creating one or more directories,
3623  otherwise the ZIP's entry is populated from pContent. The
3624  permsFlag argument specifies the fossil-specific permission
3625  flags from the fsl_file_perm_t enum, but currently ignores the
3626  permsFlag argument for directories. Not that this function
3627  creates directory entries for any files automatically, so there
3628  is rarely a need for client code to create them (unless they
3629  specifically want to ZIP an empty directory entry).
3630 
3631  Notes of potential interest:
3632 
3633  - The ZIP is created in memory, and thus creating ZIPs with this
3634  API is exceedingly memory-hungry.
3635 
3636  - The timestamp of any given file must be set separately from
3637  this call using fsl_zip_timestamp_set_unix() or
3638  fsl_zip_timestamp_set_julian(). That value is then used for
3639  subsequent file-adds until a new time is set.
3640 
3641  - If a root directory has been set using fsl_zip_root_set() then
3642  that name, plus '/' (if the root does not end with one) gets
3643  prepended to all files added via this routine.
3644 
3645  An example of the ZIP-generation process:
3646 
3647  @code
3648  int rc;
3649  fsl_zip_writer z = fsl_zip_writer_empty;
3650  fsl_buffer buf = fsl_buffer_empty;
3651  fsl_buffer const * zipBody;
3652 
3653  // ...fill the buf buffer (not shown here)...
3654 
3655  // Optionally set a virtual root dir for new files:
3656  rc = fsl_zip_root_set( &z, "myRootDir" ); // trailing slash is optional
3657  if(rc) { ... error ...; goto end; }
3658 
3659  // We must set a timestamp which will be used until we set another:
3660  fsl_zip_timestamp_set_unix( &z, time(NULL) );
3661 
3662  // Add a file:
3663  rc = fsl_zip_file_add( &z, "foo/bar.txt", &buf, FSL_FILE_PERM_REGULAR );
3664  // Clean up our content:
3665  fsl_buffer_reset(&buf); // only needed if we want to re-use the buffer's memory
3666  if(rc) goto end;
3667 
3668  // ... add more files the same way (not shown) ...
3669 
3670  // Now "seal" the ZIP file:
3671  rc = fsl_zip_end( &z );
3672  if(rc) goto end;
3673 
3674  // Fetch the ZIP content:
3675  zipBody = fsl_zip_body( &z );
3676  // zipBody now points to zipBody->used bytes of ZIP file content
3677  // which can be sent to an arbitrary destination, e.g.:
3678  rc = fsl_buffer_to_filename( zipBody, "my.zip" );
3679 
3680  end:
3681  fsl_buffer_clear(&buf);
3682  // VERY important, once we're done with z:
3683  fsl_zip_finalize( &z );
3684  if(rc){...we had an error...}
3685  @endcode
3686 
3687  @see fsl_zip_timestamp_set_julian()
3688  @see fsl_zip_timestamp_set_unix()
3689  @see fsl_zip_end()
3690  @see fsl_zip_body()
3691  @see fsl_zip_finalize()
3692 */
3693 FSL_EXPORT int fsl_zip_file_add( fsl_zip_writer * z, char const * zFilename,
3694  fsl_buffer const * pContent, int permsFlag );
3695 
3696 /**
3697  Ends the ZIP-creation process, padding all buffers, writing all
3698  final required values, and freeing up most of the memory owned
3699  by z. After calling this, z->body contains the full generated
3700  ZIP file.
3701 
3702  Returns 0 on success. On error z's contents may still be
3703  partially intact (for debugging purposes) and z->body will not
3704  hold complete/valid ZIP file contents. Results are undefined if
3705  !z or z has not been properly initialized.
3706 
3707  The caller must eventually pass z to fsl_zip_finalize() to free
3708  up any remaining resources.
3709 
3710  @see fsl_zip_timestamp_set_julian()
3711  @see fsl_zip_timestamp_set_unix()
3712  @see fsl_zip_file_add()
3713  @see fsl_zip_body()
3714  @see fsl_zip_finalize()
3715  @see fsl_zip_end_take()
3716 */
3718 
3719 /**
3720  This variant of fsl_zip_end() transfers the current contents
3721  of the zip's body to dest, replacing (freeing) any contents it may
3722  hold when this is called, then passes z to fsl_zip_finalize()
3723  to free any other resources (which are invalidated by the removal
3724  of the body).
3725 
3726  Returns 0 on success, FSL_RC_MISUSE if either pointer is NULL,
3727  some non-0 code if the proxied fsl_zip_end() call fails. On
3728  error, the transfer of contents to dest does NOT take place, but
3729  z is finalized (if it is not NULL) regardless of success or
3730  failure (even if dest is NULL). i.e. on error z is still cleaned
3731  up.
3732 */
3734 
3735 /**
3736  This variant of fsl_zip_end_take() passes z to fsl_zip_end(),
3737  write's the ZIP body to the given filename, passes
3738  z to fsl_zip_finalize(), and returns the result of
3739  either end/save combination. Saving is not attempted
3740  if ending the ZIP fails.
3741 
3742  On success 0 is returned and the contents of the ZIP are in the
3743  given file. On error z is STILL cleaned up, and the file might
3744  have been partially populated (only on I/O error after writing
3745  started). In either case, z is cleaned up and ready for re-use or
3746  (in the case of a heap-allocated instance) freed.
3747 */
3748 FSL_EXPORT int fsl_zip_end_to_filename( fsl_zip_writer * z, char const * filename );
3749 
3750 
3751 /**
3752  Returns a pointer to z's ZIP content buffer. The contents
3753  are ONLY valid after fsl_zip_end() returns 0.
3754 
3755  @see fsl_zip_timestamp_set_julian()
3756  @see fsl_zip_timestamp_set_unix()
3757  @see fsl_zip_file_add()
3758  @see fsl_zip_end()
3759  @see fsl_zip_end_take()
3760  @see fsl_zip_finalize()
3761 */
3762 FSL_EXPORT fsl_buffer const * fsl_zip_body( fsl_zip_writer const * z );
3763 
3764 /**
3765  Frees all memory owned by z and resets it to a clean state, but
3766  does not free z. Any fsl_zip_writer instance which has been
3767  modified via the fsl_zip_xxx() family of functions MUST
3768  eventually be passed to this function to clean up any contents
3769  it might have accumulated during its life. After this returns,
3770  z is legal for re-use in creating a new ZIP archive.
3771 
3772  @see fsl_zip_timestamp_set_julian()
3773  @see fsl_zip_timestamp_set_unix()
3774  @see fsl_zip_file_add()
3775  @see fsl_zip_end()
3776  @see fsl_zip_body()
3777 */
3779 
3780 /**
3781  Set z's date and time from a Julian Day number. Results are
3782  undefined if !z. Results will be invalid if rDate is negative. The
3783  timestamp is applied to all fsl_zip_file_add() operations until it
3784  is re-set.
3785 
3786  @see fsl_zip_timestamp_set_unix()
3787  @see fsl_zip_file_add()
3788  @see fsl_zip_end()
3789  @see fsl_zip_body()
3790 */
3792 
3793 /**
3794  Set z's date and time from a Unix Epoch time. Results are
3795  undefined if !z. Results will be invalid if rDate is negative. The
3796  timestamp is applied to all fsl_zip_file_add() operations until it
3797  is re-set.
3798 */
3800 
3801 /**
3802  State for the fsl_timer_xxx() family of functions.
3803 
3804  @see fsl_timer_start()
3805  @see fsl_timer_reset()
3806  @see fsl_timer_stop()
3807 */
3809  /**
3810  The amount of time spent in "user space".
3811  */
3813  /**
3814  The amount of time spent in "kernel space".
3815  */
3817 };
3819 
3820 /**
3821  Initialized-with-defaults fsl_timer_state_empty instance,
3822  intended for const copy initialization.
3823 */
3824 #define fsl_timer_state_empty_m {0,0}
3825 
3826 /**
3827  Initialized-with-defaults fsl_timer_state_empty instance,
3828  intended for copy initialization.
3829 */
3831 
3832 /**
3833  Sets t's counter state to the current CPU timer usage, as
3834  determined by the OS.
3835 
3836  Achtung: timer support is only enabled if the library is built
3837  with the FSL_CONFIG_ENABLE_TIMER macro set to a true value (it is
3838  on by default).
3839 
3840  @see fsl_timer_reset()
3841  @see fsl_timer_stop()
3842 */
3844 
3845 /**
3846  Returns the difference in _CPU_ times in microseconds since t was
3847  last passed to fsl_timer_start() or fsl_timer_reset(). It might
3848  return 0 due to system-level precision restrictions. Note that this
3849  is not useful for measuring wall times.
3850 */
3852 
3853 /**
3854  Resets t to the current time and returns the number of microseconds
3855  since t was started or last reset.
3856 
3857  @see fsl_timer_start()
3858  @see fsl_timer_reset()
3859 */
3861 
3862 /**
3863  Clears t's state and returns the difference (in uSec) between the
3864  last time t was started or reset, as per fsl_timer_fetch().
3865 
3866  @see fsl_timer_start()
3867  @see fsl_timer_reset()
3868 */
3870 
3871 /**
3872  For the given red/green/blue values (all in the range of 0 to
3873  255, or truncated to be so!) this function returns the RGB
3874  encoded in the lower 24 bits of a single number. See
3875  fsl_gradient_color() for an explanation and example.
3876 
3877  For those asking themselves, "why does an SCM API have a function
3878  for encoding RGB colors?" the answer is: fossil(1) has a long
3879  history of using HTML color codes to set the color of branches,
3880  and this is provided in support of such features.
3881 
3882  @see fsl_rgb_decode()
3883  @see fsl_gradient_color()
3884 */
3885 FSL_EXPORT unsigned int fsl_rgb_encode( int r, int g, int b );
3886 
3887 /**
3888  Given an RGB-encoded source value, this function decodes
3889  the lower 24 bits into r, g, and b. Any of r, g, and b may
3890  be NULL to skip over decoding of that part.
3891 
3892  @see fsl_rgb_encode()
3893  @see fsl_gradient_color()
3894 */
3895 FSL_EXPORT void fsl_rgb_decode( unsigned int src, int *r, int *g, int *b );
3896 
3897 /**
3898  For two color values encoded as RRGGBB values (see below for the
3899  structure), this function computes a gradient somewhere between
3900  those colors. c1 and c2 are the edges of the gradient.
3901  numberOfSteps is the number of steps in the gradient. stepNumber
3902  is a number less than numberOfSteps which specifies the "degree"
3903  of the gradients. If either numberOfSteps or stepNumber is 0, c1
3904  is returned. stepNumber of equal to or greater than c2 returns
3905  c2.
3906 
3907  The returns value is an RGB-encoded value in the lower 24 bits,
3908  ordered in big-endian. In other words, assuming rc is the return
3909  value:
3910 
3911  - red = (rc&0xFF0000)>>16
3912  - green = (rc&0xFF00)>>8
3913  - blue = (rc&0xFF)
3914 
3915  Or use fsl_rgb_decode() to break it into its component parts.
3916 
3917  It can be passed directly to a printf-like function, using the
3918  hex-integer format specifier, e.g.:
3919 
3920  @code
3921  fsl_buffer_appendf(&myBuf, "#%06x", rc);
3922  @endcode
3923 
3924  Tip: for a given HTML RRGGBB value, its C representation is
3925  identical: HTML \#F0D0A0 is 0xF0D0A0 in C.
3926 
3927  @see fsl_rgb_encode()
3928  @see fsl_rgb_decode()
3929 */
3930 FSL_EXPORT unsigned int fsl_gradient_color(unsigned int c1, unsigned int c2,
3931  unsigned int numberOfSteps,
3932  unsigned int stepNumber);
3933 
3934 /**
3935  "Simplifies" an SQL string by making the following modifications
3936  inline:
3937 
3938  - Consecutive non-newline spaces outside of an SQL string are
3939  collapsed into one space.
3940 
3941  - Consecutive newlines outside of an SQL string are collapsed into
3942  one space.
3943 
3944  Contents of SQL strings are not transformed in any way.
3945 
3946  len must be the length of the sql string. If it is negative,
3947  fsl_strlen(sql) is used to calculate the length.
3948 
3949  Returns the number of bytes in the modified string (its strlen) and
3950  NUL-terminates it at the new length. Thus the input string must be
3951  at least one byte longer than its virtual length (its NUL
3952  terminator byte suffices, provided it is NUL-terminated, as we can
3953  safely overwrite that byte).
3954 
3955  If !sql or its length resolves to 0, this function returns 0
3956  without side effects.
3957 
3958 */
3959 FSL_EXPORT fsl_size_t fsl_simplify_sql( char * sql, fsl_int_t len );
3960 
3961 /**
3962  Convenience form of fsl_simplify_sql() which assumes b holds an SQL
3963  string. It gets processed by fsl_simplify_sql() and its 'used'
3964  length potentially gets adjusted to match the adjusted SQL string.
3965 */
3967 
3968 
3969 /**
3970  Returns the result of calling the platform's equivalent of
3971  isatty(fd). e.g. on Windows this is _isatty() and on Unix
3972  isatty(). i.e. it returns a true value (non-0) if it thinks that
3973  the given file descriptor value is attached to an interactive
3974  terminal, else it returns false.
3975 */
3976 FSL_EXPORT char fsl_isatty(int fd);
3977 
3978 
3979 /**
3980 
3981  A container type for lists of db record IDs. This is used in
3982  several places as a cache for record IDs, to keep track of ones
3983  we know about, ones we know that we don't know about, and to
3984  avoid duplicate processing in some contexts.
3985 */
3986 struct fsl_id_bag {
3987  /**
3988  Number of entries of this->list which are in use (have a
3989  positive value). They need not be contiguous! Must be <=
3990  capacity.
3991  */
3993  /**
3994  The number of elements allocated for this->list.
3995  */
3997  /**
3998  The number of elements in this->list which have a zero or
3999  positive value. Must be <= capacity.
4000  */
4002  /**
4003  Array of IDs this->capacity elements long. "Used" elements
4004  have a positive value. Unused ones are set to 0.
4005  */
4007 };
4008 
4009 /**
4010  Initialized-with-defaults fsl_id_bag structure,
4011  intended for copy initialization.
4012 */
4014 
4015 /**
4016  Initialized-with-defaults fsl_id_bag structure,
4017  intended for in-struct initialization.
4018 */
4019 #define fsl_id_bag_empty_m { \
4020  0/*entryCount*/, 0/*capacity*/, \
4021  0/*used*/, NULL/*list*/ }
4022 
4023 /**
4024 
4025  Return the number of elements in the bag.
4026 */
4028 
4029 /**
4030 
4031  Remove element e from the bag if it exists in the bag. If e is
4032  not in the bag, this is a no-op.
4033 */
4035 
4036 /**
4037 
4038  Returns true (non-0) if e in the bag. Returns false (0) if it is
4039  not. It is illegal to pass an e value of 0, and that will
4040  trigger an assertion in debug builds.
4041 */
4043 
4044 /**
4045 
4046  Insert element e into the bag if it is not there already.
4047  Returns 0 if it actually inserts something or if it already
4048  contains such an entry, and some other value on error
4049  (e.g. FSL_RC_OOM).
4050 
4051  e must be positive or an assertion is triggered in debug builds.
4052 */
4054 
4055 /**
4056 
4057  Returns the ID of the first element in the bag. Returns 0 if the
4058  bag is empty.
4059 
4060  Example usage:
4061 
4062  @code
4063  fsl_id_t nid;
4064  for( nid = fsl_id_bag_first(&list);
4065  nid > 0;
4066  nid = fsl_id_bag_next(&list, nid)){
4067 
4068  ...do something...
4069  }
4070  @endcode
4071 */
4073 
4074 /**
4075 
4076  Returns the next element in the bag after e. Return 0 if e is
4077  the last element in the bag. Any insert or removal from the bag
4078  might reorder the bag. It is illegal to pass this 0 (and will
4079  trigger an assertion in debug builds). For the first call, pass
4080  it the non-0 return value from fsl_id_bag_first(). For
4081  subsequent calls, pass the previous return value from this
4082  function.
4083 
4084  @see fsl_id_bag_first()
4085 FSL_EXPORT */
4087 
4088 /**
4089 
4090  Frees any memory owned by p, but does not free p.
4091 */
4093 
4094 
4095 
4096 #if defined(__cplusplus)
4097 } /*extern "C"*/
4098 #endif
4099 #endif
4100 /* NET_FOSSIL_SCM_FSL_UTIL_H_INCLUDED */
FSL_EXPORT void fsl_timer_start(fsl_timer_state *t)
Sets t's counter state to the current CPU timer usage, as determined by the OS.
FSL_EXPORT void fsl_buffer_defossilize(fsl_buffer *b)
Defossilizes the contents of b.
fsl_uint_t fsl_size_t
fsl_size_t is an unsigned integer type used to denote absolute ranges and lengths.
Holds an allocator function and its related state.
Definition: fossil-util.h:395
Shorthand for RW+CREATE flags.
Definition: fossil-util.h:1497
FSL_EXPORT int fsl_htmlize_to_buffer(fsl_buffer *p, const char *zIn, fsl_int_t n)
Functionally equivalent to fsl_htmlize() but optimized to perform only a single allocation.
FSL_EXPORT const fsl_outputer fsl_outputer_FILE
A fsl_outputer instance which is initialized to output to a (FILE*).
Definition: fossil-util.h:359
FSL_EXPORT fsl_size_t fsl_buffer_capacity(fsl_buffer const *b)
Returns the current capacity of b, or 0 if !b.
FSL_EXPORT int fsl_file_unlink(const char *zFilename)
Deletes the given file from the filesystem.
Suppress optimizations (debug).
Definition: fossil-util.h:3026
FSL_EXPORT int fsl_list_clear(fsl_list *list, fsl_list_visitor_f childFinalizer, void *finalizerState)
A list clean-up routine which takes a callback to clean up its contents.
fsl_uint64_t system
The amount of time spent in "kernel space".
Definition: fossil-util.h:3816
FSL_EXPORT void * fsl_utf8_to_filename(const char *zUtf8)
Translate text from UTF-8 to the OS's filename character set.
Sentinel value.
Definition: fossil-util.h:2554
FSL_EXPORT unsigned int fsl_rgb_encode(int r, int g, int b)
For the given red/green/blue values (all in the range of 0 to 255, or truncated to be so!) this funct...
int fsl_int32_t
Definition: fossil-config.h:81
FSL_EXPORT fsl_size_t fsl_strlen(char const *src)
Equivalent to strlen(3) but returns 0 if src is NULL.
FSL_EXPORT void fsl_zip_finalize(fsl_zip_writer *z)
Frees all memory owned by z and resets it to a clean state, but does not free z.
FSL_EXPORT int fsl_tolower(int c)
Returns the upper-case form of c if c is an ASCII alphabet letter, else returns c.
fsl_fstat_perm_t
Bitmask values for use with the fsl_fstat::perms field.
Definition: fossil-util.h:2550
FSL_EXPORT fsl_int_t fsl_fprintf(FILE *fp, char const *fmt,...)
Emulates fprintf() using fsl_appendf().
Generic state-with-finalizer holder.
Definition: fossil-util.h:232
FSL_EXPORT void fsl_error_move(fsl_error *from, fsl_error *to)
Moves the error state from one fsl_error object to another, intended as an allocation optimization wh...
FSL_EXPORT int fsl_buffer_strftime(fsl_buffer *b, char const *format, const struct tm *timeptr)
A convenience form of fsl_strftime() which assumes that the formatted string is of "some reasonable s...
FSL_EXPORT int fsl_input_f_buffer(void *state, void *dest, fsl_size_t *n)
A fsl_input_f() implementation which requires that state be a readable (fsl_buffer*) handle...
Invert the diff (debug).
Definition: fossil-util.h:3028
FSL_EXPORT fsl_int_t fsl_appendfv(fsl_appendf_f pfAppend, void *pfAppendArg, const char *fmt, va_list ap)
This function works similarly to classical printf implementations, but instead of outputing somewhere...
FSL_EXPORT int fsl_pathfinder_ext_add(fsl_pathfinder *pf, char const *ext)
Adds the given directory to pf's search extensions.
FSL_EXPORT int fsl_pathfinder_dir_add(fsl_pathfinder *pf, char const *dir)
Adds the given directory to pf's search path.
fsl_int32_t dosTime
Current DOS-format time of the ZIP.
Definition: fossil-util.h:3539
fsl_int32_t dosDate
Current DOS-format date of the ZIP.
Definition: fossil-util.h:3543
fsl_buffer body
The buffer for the ZIP file body.
Definition: fossil-util.h:3560
fsl_size_t capacity
The number of elements allocated for this->list.
Definition: fossil-util.h:3996
FSL_EXPORT int fsl_buffer_compare_file(fsl_buffer const *b, char const *zFile)
Bitwise-compares the contents of b against the file named by zFile.
FSL_EXPORT FILE * fsl_fopen(char const *name, char const *mode)
_Almost_ equivalent to fopen(3) but:
FSL_EXPORT int fsl_strcmp(char const *lhs, char const *rhs)
Like strcmp(3) except that it accepts NULL pointers.
FSL_EXPORT int fsl_buffer_compress(fsl_buffer const *pIn, fsl_buffer *pOut)
Compresses the first pIn->used bytes of pIn to pOut.
Only display if not "too big.".
Definition: fossil-util.h:3030
FSL_EXPORT int fsl_toupper(int c)
Returns the lower-case form of c if c is an ASCII alphabet letter, else returns c.
FSL_EXPORT fsl_size_t fsl_strftime_unix(char *dest, fsl_size_t destLen, char const *format, fsl_time_t epochTime, char convertToLocal)
A convenience form of fsl_strftime() which takes its timestamp in the form of a Unix Epoch time...
FSL_EXPORT int fsl_buffer_copy(fsl_buffer const *src, fsl_buffer *dest)
Overwrites dest's contents with a copy of those from src (reusing dest's memory if it has any)...
FSL_EXPORT int fsl_buffer_compare_O1(fsl_buffer const *lhs, fsl_buffer const *rhs)
Compare two buffers in constant (a.k.a.
FSL_EXPORT int fsl_file_mtime_set(const char *zFilename, fsl_time_t newMTime)
Sets the mtime (Unix epoch) for a file.
int fsl_confirmation_f_console_FILE(void *state, char const *msg, fsl_size_t msgLen)
NOT YET IMPLEMENTED.
Definition: fossil-util.h:3456
FSL_EXPORT const fsl_outputer fsl_outputer_empty
Empty-initialized fsl_outputer instance, intended for copy-initializing.
Definition: fossil-util.h:346
FSL_EXPORT int fsl_file_dirpart(char const *zFilename, fsl_int_t nLen, fsl_buffer *pOut, char leaveSlash)
Calculates the "directory part" of zFilename and _appends_ it to pOut.
FSL_EXPORT fsl_int_t fsl_list_index_of(fsl_list const *li, void const *value, fsl_generic_cmp_f cmpf)
Searches for a value in the given list, using the given comparison function to determine equivalence...
fsl_int64_t fsl_time_t
The type used to represent type values.
FSL_EXPORT char fsl_validate16(const char *zIn, fsl_size_t nIn)
Return true (non-0) if the input string contains only valid base-16 digits.
FSL_EXPORT char * fsl_unicode_to_utf8(const void *zUnicode)
Translates Unicode text into UTF-8.
FSL_EXPORT int fsl_buffer_copy_lines(fsl_buffer *pTo, fsl_buffer *pFrom, fsl_size_t N)
Copy N lines of text from pFrom into pTo.
This is the converse of FSL_CONFIRM_YES.
Definition: fossil-util.h:3426
fsl_buffer buf
Used to build up a path string during fsl_pathfinder_search(), and holds the result of a successful s...
Definition: fossil-util.h:3280
fsl_buffer toc
The buffer for the table of contents.
Definition: fossil-util.h:3556
A utility class for creating ZIP-format archives.
Definition: fossil-util.h:3531
FSL_EXPORT char fsl_isupper(int c)
Returns true if c is an upper-case ASCII alphabet character.
fsl_output_f out
Output channel.
Definition: fossil-util.h:329
FSL_EXPORT fsl_int_t fsl_appendf_f_FILE(void *state, char const *s, fsl_int_t n)
A fsl_appendf_f() impl which requires that state be an opened, writable (FILE*) handle.
FSL_EXPORT char fsl_is_uuid(char const *str)
Returns true (non-0) if str is not NULL, is exactly FSL_UUID_STRLEN bytes long (meaning its final byt...
Strip trailing CR.
Definition: fossil-util.h:3032
void * state
State intended to be passed as the first parameter to this->f().
Definition: fossil-util.h:405
FSL_EXPORT int fsl_errno_to_rc(int errNo, int dflt)
Tries to convert the value of errNo, which is assumed to come from the global errno, to a fsl_rc_t code.
FSL_EXPORT char * fsl_filename_to_utf8(const void *zFilename)
Translate text from the OS's character set into UTF-8.
FSL_EXPORT fsl_size_t fsl_strftime(char *dest, fsl_size_t destLen, const char *format, const struct tm *timeptr)
A strftime() implementation.
FSL_EXPORT char * fsl_mprintfv(char const *fmt, va_list vargs)
va_list counterpart to fsl_mprintf().
fsl_fstat_type_t type
Indicates the type of filesystem object.
Definition: fossil-util.h:2574
FSL_EXPORT const fsl_buffer fsl_buffer_empty
Empty-initialized fsl_buffer instance, intended for copy initialization.
Definition: fossil-util.h:680
FSL_EXPORT int fsl_file_canonical_name(const char *zOrigName, fsl_buffer *pOut, char slash)
Equivalent to fsl_file_canonical_name2(NULL, zOrigName, pOut, slash).
FSL_EXPORT void fsl_rgb_decode(unsigned int src, int *r, int *g, int *b)
Given an RGB-encoded source value, this function decodes the lower 24 bits into r, g, and b.
FSL_EXPORT void fsl_pathfinder_clear(fsl_pathfinder *pf)
Frees all memory associated with pf, but does not free pf.
FSL_EXPORT int fsl_buffer_appendfv(fsl_buffer *dest, char const *fmt, va_list args)
va_list counterpart to fsl_buffer_appendfv().
An interface which encapsulates data for managing an output destination, primarily intended for use w...
Definition: fossil-util.h:325
FSL_EXPORT int fsl_stricmp(const char *zA, const char *zB)
Case-insensitive form of fsl_strcmp().
Flag for fsl_db_open() specifying that the db should be opened in read-write mode, but should not create the db if it does not already exist.
Definition: fossil-util.h:1488
Flag for fsl_db_open() specifying that the db should be opened in read-only mode. ...
Definition: fossil-util.h:1482
FSL_EXPORT int fsl_buffer_append(fsl_buffer *b, void const *src, fsl_int_t n)
Appends the first n bytes of src, plus a NUL byte, to b, expanding b as necessary and incrementing b-...
int(* fsl_confirmation_f)(void *state, char const *msg, fsl_size_t msgLen)
An interface for routines which answer a yes/no question, either via human interaction or programatic...
Definition: fossil-util.h:3448
FSL_EXPORT int fsl_delta_applied_size(unsigned char const *zDelta, fsl_size_t lenDelta, fsl_size_t *appliedSize)
A container for storing generic error state.
Definition: fossil-util.h:692
FSL_EXPORT void * fsl_utf8_to_unicode(const char *zUtf8)
Translate UTF-8 to Unicode for use in system calls.
FSL_EXPORT fsl_size_t fsl_buffer_size(fsl_buffer const *b)
Returns the "used" size of b, or 0 if !b.
FSL_EXPORT char fsl_isspace(int c)
Returns true if c is ' ', '\r' (ASCII 13dec), or '\t' (ASCII 9 dec).
fsl_size_t capacity
Number of slots allocated in this->list.
Definition: fossil-util.h:165
FSL_EXPORT void fsl_canonical16(char *z, fsl_size_t n)
The input string is a base16 value.
FSL_EXPORT int fsl_buffer_fill_from_FILE(fsl_buffer *dest, FILE *src)
A fsl_buffer_fill_from() proxy which overwrite's dest->mem with the contents of the given FILE handle...
Ignore end-of-line whitespace.
Definition: fossil-util.h:3012
void * state
State to be passed as the first argument to this->f().
Definition: fossil-util.h:3485
FSL_EXPORT int fsl_buffer_delta_apply2(fsl_buffer const *pOriginal, fsl_buffer const *pDelta, fsl_buffer *pTarget, fsl_error *pErr)
Identical to fsl_buffer_delta_apply() except that if delta application fails then any error messages/...
void *(* fsl_realloc_f)(void *state, void *mem, fsl_size_t n)
Generic stateful alloc/free/realloc() interface.
Definition: fossil-util.h:390
FSL_EXPORT char * fsl_buffer_str(fsl_buffer const *b)
Equivalent to ((char *)b->mem), but returns NULL if !b.
FSL_EXPORT int fsl_file_canonical_name2(const char *zRoot, const char *zOrigName, fsl_buffer *pOut, char slash)
Computes a canonical pathname for a file or directory.
FSL_EXPORT int fsl_find_home_dir(fsl_buffer *tgt, char requireWriteAccess)
Tries to find the user's home directory.
FSL_EXPORT int fsl_getcwd(char *zBuf, fsl_size_t nBuf, fsl_size_t *outLen)
Writes the absolute path name of the current directory to zBuf, which must be at least nBuf bytes lon...
#define FSL_EXPORT
Definition: fossil-config.h:19
FSL_EXPORT const fsl_list fsl_list_empty
Empty-initialized fsl_list structure, intended for copy initialization.
Definition: fossil-util.h:177
FSL_EXPORT int fsl_error_setv(fsl_error *err, int code, char const *fmt, va_list args)
va_list counterpart to fsl_error_set().
FSL_EXPORT int fsl_zip_file_add(fsl_zip_writer *z, char const *zFilename, fsl_buffer const *pContent, int permsFlag)
Adds a file or directory to the ZIP writer z.
FSL_EXPORT void fsl_error_clear(fsl_error *err)
Frees up any resources owned by err and sets its error code to 0, but does not free err...
char const * fsl_uuid_cstr
The const counterpart of fsl_uuid_str.
Definition: fossil-util.h:92
FSL_EXPORT void fsl_glob_list_clear(fsl_list *globList)
If globList is not NULL this is equivalent to fsl_list_visit_free(globList, 1), otherwise it is a no-...
fsl_open_flags
Flags for use with fsl_db_open() and friends.
Definition: fossil-util.h:1473
Generic list container type.
Definition: fossil-util.h:150
void * state
State to be passed as the first argument to f().
Definition: fossil-util.h:206
FSL_EXPORT int fsl_list_visit(fsl_list const *self, int order, fsl_list_visitor_f visitor, void *visitorState)
For each item in self->list, visitor(item,visitorState) is called.
fsl_size_t size
The size of the stat'd file, in bytes.
Definition: fossil-util.h:2589
FSL_EXPORT void fsl_finalizer_f_FILE(void *state, void *mem)
A fsl_finalizer_f() impl which requires that mem be-a (FILE*).
FSL_EXPORT char const * fsl_buffer_cstr2(fsl_buffer const *b, fsl_size_t *len)
If buf is not NULL and has any memory allocated to it, that memory is returned.
Show filenames only.
Definition: fossil-util.h:3020
FSL_EXPORT fsl_time_t fsl_julian_to_unix(fsl_double_t J)
Returns the Julian Day time J value converted to a Unix Epoch timestamp.
Indicates that the answer to the question at hand is "yes" or "okay.".
Definition: fossil-util.h:3414
FSL_EXPORT int fsl_stat(const char *zFilename, fsl_fstat *fst, char derefSymlinks)
Runs the OS's stat(2) equivalent to populate fst with information about the given file...
The "no flags" value.
Definition: fossil-util.h:1477
Generate a side-by-side diff.
Definition: fossil-util.h:3016
A helper type which wraps a fsl_confirmation_f() and its state into one object.
Definition: fossil-util.h:3481
fsl_id_t fsl_id_bag_next(fsl_id_bag *p, fsl_id_t e)
Returns the next element in the bag after e.
FSL_EXPORT int fsl_glob_list_parse(fsl_list *tgt, char const *zPatternList)
Parses zPatternList as a comma-and/or-fsl_isspace()-delimited list of glob patterns (as supported by ...
FSL_EXPORT char fsl_isatty(int fd)
Returns the result of calling the platform's equivalent of isatty(fd).
Missing shown as empty files.
Definition: fossil-util.h:3018
FSL_EXPORT char fsl_str_is_date(const char *z)
Returns non-0 (true) if the first 10 digits of z _appear_ to form the start of an ISO date string (YY...
FSL_EXPORT int fsl_strnicmp(const char *zA, const char *zB, fsl_int_t nByte)
fsl_strcmp() variant which compares at most nByte bytes of the given strings, case-insensitively.
Indicates a non-directory, non-symlink filesystem entry.
Definition: fossil-util.h:2541
FSL_EXPORT char * fsl_htmlize_str(const char *zIn, fsl_int_t n)
Equivalent to fsl_htmlize_to_buffer() but returns the result as a new string which must eventually be...
FSL_EXPORT fsl_uint64_t fsl_timer_fetch(fsl_timer_state const *t)
Returns the difference in _CPU_ times in microseconds since t was last passed to fsl_timer_start() or...
fsl_size_t used
The number of elements in this->list which have a zero or positive value.
Definition: fossil-util.h:4001
Generic interface for memory finalizers.
Definition: fossil-util.h:202
FSL_EXPORT int fsl_zip_end(fsl_zip_writer *z)
Ends the ZIP-creation process, padding all buffers, writing all final required values, and freeing up most of the memory owned by z.
fsl_state state
State to be used when calling this->out(), namely: this->out( this->state.state, ...
Definition: fossil-util.h:338
FSL_EXPORT int fsl_uuidcmp(fsl_uuid_cstr lhs, fsl_uuid_cstr rhs)
Equivalent to fsl_strncmp(lhs, rhs, FSL_UUID_STRLEN).
FSL_EXPORT fsl_double_t fsl_julian_now()
Returns the current Unix Epoch time converted to its approximate Julian form.
FSL_EXPORT const fsl_id_bag fsl_id_bag_empty
Initialized-with-defaults fsl_id_bag structure, intended for copy initialization. ...
Definition: fossil-util.h:4013
Render HTML.
Definition: fossil-util.h:3022
FSL_EXPORT fsl_int_t fsl_snprintfv(char *dest, fsl_size_t n, char const *fmt, va_list args)
va_list counterpart to fsl_snprintf()
FSL_EXPORT char * fsl_strdup(char const *src)
Equivalent to fsl_strndup(src,-1).
FSL_EXPORT int fsl_dir_check(const char *zFilename)
Returns a positive value if zFilename is a directory, 0 if zFilename does not exist, or a negative value if zFilename exists but is something other than a directory.
FSL_EXPORT int fsl_buffer_reserve(fsl_buffer *buf, fsl_size_t n)
Reserves at least n bytes of capacity in buf.
State for the fsl_timer_xxx() family of functions.
Definition: fossil-util.h:3808
FSL_EXPORT char fsl_str_bool(char const *s)
Returns false if s is NULL or starts with any of (0 (NUL), '0' (ASCII character zero), 'f', 'n', "off"), case-insensitively, else it returns true.
FSL_EXPORT void fsl_buffer_swap(fsl_buffer *left, fsl_buffer *right)
Swaps the contents of the left and right arguments.
FSL_EXPORT char fsl_is_file(const char *zFilename)
Return TRUE if the named file is an ordinary file.
FSL_EXPORT char * fsl_strndup(char const *src, fsl_int_t len)
Similar to strndup(3) but returns NULL if !src.
fsl_uint64_t user
The amount of time spent in "user space".
Definition: fossil-util.h:3812
FSL_EXPORT fsl_size_t fsl_simplify_sql(char *sql, fsl_int_t len)
"Simplifies" an SQL string by making the following modifications inline:
FSL_EXPORT int fsl_buffer_to_filename(fsl_buffer const *b, char const *fname)
Writes the given buffer to the given filename.
fsl_list dirs
Holds the list of search directories.
Definition: fossil-util.h:3272
FSL_EXPORT int fsl_input_f_FILE(void *state, void *dest, fsl_size_t *n)
A fsl_input_f() implementation which requires that state be a readable (FILE*) handle.
unsigned char * mem
The raw memory owned by this buffer.
Definition: fossil-util.h:640
Flag for fsl_db_open() specifying that the db should be opened in read-write mode, creating the db if it does not already exist.
Definition: fossil-util.h:1493
int(* fsl_flush_f)(void *state)
Generic interface for flushing arbitrary output streams.
Definition: fossil-util.h:287
FSL_EXPORT int fsl_strncmp(const char *zA, const char *zB, fsl_size_t nByte)
fsl_strcmp() variant which compares at most nByte bytes of the given strings, case-sensitively.
This is the converse of FSL_CONFIRM_YES_ALL.
Definition: fossil-util.h:3430
void * fsl_malloc(fsl_size_t n)
Semantically behaves like malloc(3), but may introduce instrumentation, error checking, or similar.
FSL_EXPORT fsl_size_t fsl_id_bag_count(fsl_id_bag *p)
Return the number of elements in the bag.
FSL_EXPORT void fsl_buffer_swap_free(fsl_buffer *left, fsl_buffer *right, int clearWhich)
Similar fsl_buffer_swap() but it also optionally frees one of the buffer's memories after swapping th...
int(* fsl_list_visitor_f)(void *obj, void *visitorState)
Generic visitor interface for fsl_list lists.
Definition: fossil-util.h:1813
FSL_EXPORT char fsl_data_is_compressed(unsigned char const *mem, fsl_size_t len)
Returns true if this function believes that mem (which must be at least len bytes of valid memory lon...
fsl_size_t cursor
Used by some routines to keep a cursor into this->mem.
Definition: fossil-util.h:671
fsl_size_t entryCount
Number of entries of this->list which are in use (have a positive value).
Definition: fossil-util.h:3992
FSL_EXPORT char fsl_islower(int c)
Returns true if c is a lower-case ASCII alphabet character.
FSL_EXPORT char fsl_is_absolute_path(const char *zPath)
Returns true if the given path appears to be absolute, else false.
The "Path Finder" class is a utility class for searching the filesystem for files matching a set of c...
Definition: fossil-util.h:3262
FSL_EXPORT fsl_uint64_t fsl_timer_stop(fsl_timer_state *t)
Clears t's state and returns the difference (in uSec) between the last time t was started or reset...
char * rootDir
An artificial root directory which gets prefixed to all inserted filenames.
Definition: fossil-util.h:3552
void(* fsl_finalizer_f)(void *state, void *mem)
Generic interface for finalizing/freeing memory.
Definition: fossil-util.h:197
FSL_EXPORT int fsl_stricmp_cmp(void const *lhs, void const *rhs)
Equivalent to fsl_stricmp(), but with a signature suitable for use as a generic comparison function (...
char * fsl_uuid_str
fsl_uuid_str and fsl_uuid_cstr are "for documentation and readability purposes" typedefs used to deno...
Definition: fossil-util.h:85
fsl_flush_f flush
flush() implementation.
Definition: fossil-util.h:333
FSL_EXPORT int fsl_pathfinder_search(fsl_pathfinder *pf, char const *base, char const **pOut, fsl_size_t *outLen)
Searches for a file whose name can be constructed by some combination of pf's directory/suffix list a...
FSL_EXPORT char * fsl_getenv(const char *zName)
Returns a (possible) copy of the environment variable with the given key, or NULL if no entry is foun...
fsl_finalizer_f f
Finalizer function.
Definition: fossil-util.h:210
FSL_EXPORT char * fsl_guess_user_name()
Uses fsl_getenv() to look for the environment variables (FOSSIL_USER, (Windows: USERNAME), (Unix: USER, LOGNAME)).
fsl_int32_t fsl_id_t
fsl_id_t is a signed integer type used to store database record IDs.
FSL_EXPORT fsl_int_t fsl_data_uncompressed_size(unsigned char const *mem, fsl_size_t len)
If fsl_data_is_compressed(mem,len) returns true then this function returns the uncompressed size of t...
FSL_EXPORT fsl_buffer const * fsl_zip_body(fsl_zip_writer const *z)
Returns a pointer to z's ZIP content buffer.
FSL_EXPORT int fsl_confirmv(fsl_confirmation_f f, void *state, char const *fmt, va_list)
The va_list counterpart of fsl_confirm().
fsl_diff_flag_t
Flags for use with text-diff generation APIs, e.g.
Definition: fossil-util.h:3010
fsl_id_t * list
Array of IDs this->capacity elements long.
Definition: fossil-util.h:4006
FSL_EXPORT fsl_int_t fsl_str_to_int(char const *str, fsl_int_t dflt)
Expects str to be a string containing a decimal value, optionally with a leading sign.
fsl_size_t entryCount
Number of entries (files + dirs) added to the zip file so far.
Definition: fossil-util.h:3535
FSL_EXPORT int fsl_confirm(fsl_confirmation_f f, void *state, char const *fmt,...)
Creates a formatted message string using fsl_appendf(fmt,...) and passes that message to f(state...
FSL_EXPORT int fsl_buffer_delta_apply(fsl_buffer const *pOriginal, fsl_buffer const *pDelta, fsl_buffer *pTarget)
Apply the delta in pDelta to the original content pOriginal to generate the target content pTarget...
FSL_EXPORT void fsl_zip_timestamp_set_julian(fsl_zip_writer *z, fsl_double_t rDate)
Set z's date and time from a Julian Day number.
FSL_EXPORT void fsl_buffer_clear(fsl_buffer *buf)
Convenience equivalent of fsl_buffer_reserve(buf,0).
FSL_EXPORT fsl_size_t fsl_str_to_size(char const *str)
Expects str to be a string containing an unsigned decimal value.
FSL_EXPORT int fsl_encode16(const unsigned char *pIn, unsigned char *zOut, fsl_size_t N)
Encode a N-digit base-256 in base-16.
FSL_EXPORT char fsl_is_simple_pathname(const char *z, char bStrictUtf8)
Return true (non-0) if the filename given is a valid filename for a file in a repository.
FSL_EXPORT char fsl_str_glob(const char *zGlob, const char *z)
Return true (non-zero) if string z matches glob pattern zGlob and zero if the pattern does not match...
FSL_EXPORT int fsl_buffer_compress2(fsl_buffer const *pIn1, fsl_buffer const *pIn2, fsl_buffer *pOut)
Compress the concatenation of a blobs pIn1 and pIn2 into pOut.
FSL_EXPORT int fsl_list_visit_p(fsl_list *self, int order, char shiftIfNulled, fsl_list_visitor_f visitor, void *visitorState)
Works similarly to the visit operation without the _p suffix except that the pointer the visitor func...
FSL_EXPORT int fsl_htmlize(fsl_output_f out, void *oState, const char *zIn, fsl_int_t n)
Make the given string safe for HTML by converting every "<" into "<", every ">" into ">"...
Sentinel value for unknown/invalid filesystem entry types.
Definition: fossil-util.h:2533
FSL_EXPORT int fsl_file_access(const char *zFilename, int flags)
Returns 0 if the given file is readable.
FSL_EXPORT int fsl_bytes_fossilize(unsigned char const *inp, fsl_int_t len, fsl_buffer *out)
"Fossilizes" the first len bytes of the given input string.
A general-purpose buffer class, analog to Fossil v1's Blob class, but it is not called fsl_blob to av...
Definition: fossil-util.h:632
FSL_EXPORT char const * fsl_glob_list_matches(fsl_list const *globList, char const *zHaystack)
Assumes globList is a list of (char [const] *) glob values and tries to match each one against zHayst...
fsl_buffer scratch
Internal scratchpad for ops which often allocate small buffers.
Definition: fossil-util.h:3565
FSL_EXPORT char fsl_id_bag_contains(fsl_id_bag *p, fsl_id_t e)
Returns true (non-0) if e in the bag.
FSL_EXPORT int fsl_buffer_fill_from(fsl_buffer *dest, fsl_input_f src, void *state)
Uses a fsl_input_f() function to buffer input into a fsl_buffer.
FSL_EXPORT char fsl_isalpha(int c)
Returns true if the given letter is an ASCII alphabet character.
FSL_EXPORT int fsl_list_v_fsl_free(void *obj, void *visitorState)
A fsl_list_visitor_f() implementation which requires that obj be arbitrary memory which can legally b...
int code
Error code, generally assumed to be a fsl_rc_t value.
Definition: fossil-util.h:701
fsl_list ext
Holds the list of search extensions.
Definition: fossil-util.h:3267
fsl_time_t ctime
The time of the last file metadata change (owner, permissions, etc.).
Definition: fossil-util.h:2581
FSL_EXPORT fsl_size_t fsl_simplify_sql_buffer(fsl_buffer *b)
Convenience form of fsl_simplify_sql() which assumes b holds an SQL string.
Indicates a symlink filesystem entry.
Definition: fossil-util.h:2543
FSL_EXPORT int fsl_confirmation_f_int(void *state, char const *msg, fsl_size_t msgLen)
A fsl_confirmation_f() implementation which expects the state parameter to be a (int [const] *) which...
FSL_EXPORT int fsl_mkdir(const char *zName, char forceFlag)
Create the directory with the given name if it does not already exist.
FSL_EXPORT const fsl_state fsl_state_empty
Empty-initialized fsl_state struct, intended for copy-initializing.
Definition: fossil-util.h:257
FSL_EXPORT fsl_int_t fsl_buffer_uncompressed_size(fsl_buffer const *b)
The fsl_buffer counterpart of fsl_data_uncompressed_size().
Tells fsl_repo_open_xxx() to confirm that the db is a repository.
Definition: fossil-util.h:1502
FSL_EXPORT fsl_time_t fsl_file_mtime(const char *zFilename)
Return the modification time for a file.
FSL_EXPORT int fsl_list_reserve(fsl_list *self, fsl_size_t n)
Possibly reallocates self->list, changing its size.
int(* fsl_input_f)(void *state, void *dest, fsl_size_t *n)
Generic interface for streaming in data.
Definition: fossil-util.h:298
FSL_EXPORT int fsl_delta_create2(unsigned char const *zSrc, fsl_size_t lenSrc, unsigned char const *zOut, fsl_size_t lenOut, fsl_output_f out, void *outState)
Works identically to fsl_delta_create() but sends its output to the given output function.
FSL_EXPORT void fsl_zip_timestamp_set_unix(fsl_zip_writer *z, fsl_time_t epochTime)
Set z's date and time from a Unix Epoch time.
FSL_EXPORT void fsl_unicode_free(void *)
Deallocates the given memory, which must have been allocated from fsl_unicode_to_utf8(), fsl_utf8_to_unicode(), or any function which explicitly documents this function as being the proper finalizer for its returned memory.
FSL_EXPORT char fsl_iso8601_to_julian(char const *zDate, fsl_double_t *pOut)
If zDate is an ISO8601-format string, optionally with a .NNN fractional suffix, then this function re...
A container type for lists of db record IDs.
Definition: fossil-util.h:3986
fsl_confirmation_t
Result codes for the fsl_confirmation_f() family of functions.
Definition: fossil-util.h:3405
FSL_EXPORT fsl_int_t fsl_appendf(fsl_appendf_f pfAppend, void *pfAppendArg, const char *fmt,...)
Identical to fsl_appendfv() but takes an ellipses list (...) instead of a va_list.
FSL_EXPORT int fsl_delta_apply(unsigned char const *zSrc, fsl_size_t lenSrc, unsigned char const *zDelta, fsl_size_t lenDelta, unsigned char *zOut)
Apply a delta created using fsl_delta_create().
FSL_EXPORT fsl_int_t fsl_list_index_of_cstr(fsl_list const *li, char const *key)
Equivalent to fsl_list_index_of(li, key, fsl_strcmp_cmp).
fsl_int64_t fsl_int_t
fsl_int_t is a signed integer type used to denote "relative" ranges and lengths, or to tell a routine...
FSL_EXPORT int fsl_buffer_reset(fsl_buffer *buf)
Resets buf->used to 0 and sets buf->mem[0] (if buf->mem is not NULL) to 0.
FSL_EXPORT int fsl_delta_create(unsigned char const *zSrc, fsl_size_t lenSrc, unsigned char const *zOut, fsl_size_t lenOut, unsigned char *zDelta, fsl_size_t *deltaSize)
Create a new delta between the memory zIn and zOut.
FSL_EXPORT int fsl_zip_end_take(fsl_zip_writer *z, fsl_buffer *dest)
This variant of fsl_zip_end() transfers the current contents of the zip's body to dest...
FSL_EXPORT int fsl_output_f_FILE(void *state, void const *src, fsl_size_t n)
fsl_output_f() implementation which requires state to be a writeable (FILE*) handle.
FSL_EXPORT void * fsl_realloc(void *mem, fsl_size_t n)
Behaves like realloc(3).
fsl_size_t used
Number of "used" entries in the list.
Definition: fossil-util.h:159
FSL_EXPORT int fsl_finalizer_f_buffer(void *state, void *mem)
fsl_finalizer_f() impl which requires that mem be-a (fsl_buffer*).
FSL_EXPORT fsl_int_t fsl_snprintf(char *dest, fsl_size_t n, char const *fmt,...)
An sprintf(3) clone which uses fsl_appendf() for the formatting.
FSL_EXPORT int fsl_stream(fsl_input_f inF, void *inState, fsl_output_f outF, void *outState)
A generic streaming routine which copies data from an fsl_input_f() to an fsl_outpuf_f().
FSL_EXPORT int fsl_flush_f_FILE(void *_FILE)
A fsl_flush_f() impl which expects _FILE to be-a (FILE*) opened for writing, which this function pass...
Ignore end-of-line whitespace.
Definition: fossil-util.h:3014
FSL_EXPORT void fsl_list_swap(fsl_list *lhs, fsl_list *rhs)
Swaps all contents of both lhs and rhs.
double fsl_double_t
fsl_double_t is the double type used by the library.
FSL_EXPORT fsl_id_t fsl_id_bag_first(fsl_id_bag *p)
Returns the ID of the first element in the bag.
FSL_EXPORT char const * fsl_buffer_cstr(fsl_buffer const *b)
Equivalent to ((char const *)b->mem), but returns NULL if !b.
FSL_EXPORT fsl_double_t fsl_unix_to_julian(fsl_time_t unixEpoch)
Returns the given Unix Epoch timestamp value as its approximate Julian Day value. ...
FSL_EXPORT int fsl_delta_apply2(unsigned char const *zSrc, fsl_size_t lenSrc, unsigned char const *zDelta, fsl_size_t lenDelta, unsigned char *zOut, fsl_error *pErr)
Functionally identical to fsl_delta_apply() but any errors generated during application of the delta ...
FSL_EXPORT fsl_uint64_t fsl_timer_reset(fsl_timer_state *t)
Resets t to the current time and returns the number of microseconds since t was started or last reset...
void ** list
Array of entries.
Definition: fossil-util.h:155
The executable bit, as understood by Fossil.
Definition: fossil-util.h:2559
FSL_EXPORT int fsl_zip_root_set(fsl_zip_writer *z, char const *zRoot)
Sets a virtual root directory in z, such that all files added with fsl_zip_file_add() will get this d...
FSL_EXPORT int fsl_chdir(const char *zChDir)
Performs a chdir() to the directory named by zChDir.
Show line numbers.
Definition: fossil-util.h:3024
FSL_EXPORT int fsl_decode16(const unsigned char *zIn, unsigned char *pOut, fsl_size_t N)
Decode a N-character base-16 number into base-256.
FSL_EXPORT void fsl_error_reset(fsl_error *err)
Sets err->code to 0 and resets its buffer, but keeps any err->msg memory around for later re-use...
A simple wrapper around the stat(2) structure resp.
Definition: fossil-util.h:2570
fsl_time_t unixTime
Current Unix Epoch time of the ZIP.
Definition: fossil-util.h:3547
FSL_EXPORT fsl_size_t fsl_htmlize_xlate(int c, char const **xlate)
If c is a character Fossil likes to HTML-escape, assigns *xlate to its transformed form...
fsl_buffer msg
Error message text is stored in this->msg.mem.
Definition: fossil-util.h:697
FSL_EXPORT const fsl_fstat fsl_fstat_empty
Empty-initialized fsl_fstat instance, intended for copy construction.
Definition: fossil-util.h:2604
FSL_EXPORT int fsl_strcmp_cmp(void const *lhs, void const *rhs)
Equivalent to fsl_strcmp(), but with a signature suitable for use as a generic comparison function (e...
fsl_int_t(* fsl_appendf_f)(void *state, char const *data, fsl_int_t n)
The fsl_appendf_f typedef is used to provide fsl_appendfv() with a flexible output routine...
Definition: fossil-util.h:1576
FSL_EXPORT void fsl_id_bag_remove(fsl_id_bag *p, fsl_id_t e)
Remove element e from the bag if it exists in the bag.
FSL_EXPORT int fsl_error_copy(fsl_error const *src, fsl_error *dest)
Copies the error state from src to dest.
FSL_EXPORT char fsl_isdigit(int c)
Returns true if c is an ASCII digit in the range '0' to '9'.
void * state
Arbitrary context-dependent state.
Definition: fossil-util.h:236
FSL_EXPORT int fsl_buffer_appendf(fsl_buffer *dest, char const *fmt,...)
Uses fsl_appendf() to append formatted output to the given buffer.
int perm
Contains the filesystem entry's permissions as a bitmask of fsl_fstat_perm_t values.
Definition: fossil-util.h:2595
fsl_fstat_type_t
Values for use with the fsl_fstat::type field.
Definition: fossil-util.h:2531
FSL_EXPORT int fsl_list_append(fsl_list *self, void *cp)
Appends a bitwise copy of cp to self->list, expanding the list as necessary and adjusting self->used...
fsl_realloc_f f
Base allocator function.
Definition: fossil-util.h:400
Indicates there was some unrecoverable error during prompting.
Definition: fossil-util.h:3410
fsl_size_t capacity
Number of bytes allocated for this buffer.
Definition: fossil-util.h:644
FSL_EXPORT void fsl_free(void *mem)
Semantically behaves like free(3), but may introduce instrumentation, error checking, or similar.
FSL_EXPORT int fsl_diff_text(fsl_buffer const *pA, fsl_buffer const *pB, fsl_output_f out, void *outState, short contextLines, short sbsWidth, int diffFlags)
Generates a textual diff from two text inputs and writes it to the given output function.
FSL_EXPORT int fsl_buffer_compare(fsl_buffer const *lhs, fsl_buffer const *rhs)
Compares the contents of buffers lhs and rhs using memcmp(3) semantics.
FSL_EXPORT int fsl_zip_end_to_filename(fsl_zip_writer *z, char const *filename)
This variant of fsl_zip_end_take() passes z to fsl_zip_end(), write's the ZIP body to the given filen...
FSL_EXPORT char fsl_julian_to_iso8601(fsl_double_t J, char *pOut, char addMs)
Converts the Julian Day J to an ISO8601 time string.
fsl_finalizer finalize
Finalizer for this->state.
Definition: fossil-util.h:247
FSL_EXPORT int fsl_buffer_uncompress(fsl_buffer const *pIn, fsl_buffer *pOut)
Uncompress buffer pIn and store the result in pOut.
FSL_EXPORT void fsl_filename_free(void *pOld)
Deallocate pOld, which must have been allocated by fsl_filename_to_utf8(), fsl_utf8_to_filename(), fsl_getenv(), or another routine which explicitly documents this function as being the proper finalizer for its returned memory.
FSL_EXPORT void fsl_bytes_defossilize(unsigned char *inp, fsl_size_t *resultLen)
"Defossilizes" bytes encoded by fsl_bytes_fossilize() in-place.
FSL_EXPORT fsl_size_t fsl_file_size(const char *zFilename)
Return the size of a file in bytes.
fsl_size_t used
Number of "used" bytes in the buffer.
Definition: fossil-util.h:661
FSL_EXPORT int fsl_buffer_stream_lines(fsl_buffer *pFrom, fsl_output_f fTo, void *toState, fsl_size_t N)
Works identically to fsl_buffer_copy_lines() except that it sends its output.
FSL_EXPORT int fsl_diff_text_to_buffer(fsl_buffer const *pA, fsl_buffer const *pB, fsl_buffer *pOut, short contextLines, short sbsWidth, int diffFlags)
Functionally equivalent to:
FSL_EXPORT const fsl_zip_writer fsl_zip_writer_empty
An initialized-with-defaults fsl_zip_writer instance, intended for copy-initialization.
Definition: fossil-util.h:3593
FSL_EXPORT int fsl_mkdir_for_file(char const *zName, char forceFlag)
A convenience form of fsl_mkdir() which can recursively create directories.
FSL_EXPORT int fsl_error_get(fsl_error const *err, char const **str, fsl_size_t *len)
Fetches the error state from err.
fsl_time_t mtime
Last modification time.
Definition: fossil-util.h:2585
fsl_list dirs
The current list of directory entries (as (char *)).
Definition: fossil-util.h:3569
FSL_EXPORT char fsl_isalnum(int c)
Equivalent to fsl_isdigit(c) || fsl_isalpha().
FSL_EXPORT const fsl_confirmer fsl_confirmer_empty
Initialized-with-defaults fsl_confirmer struct.
Definition: fossil-util.h:3499
FSL_EXPORT void fsl_id_bag_clear(fsl_id_bag *p)
Frees any memory owned by p, but does not free p.
FSL_EXPORT int fsl_stream_compare(fsl_input_f in1, void *in1State, fsl_input_f in2, void *in2State)
Consumes two input streams looking for differences.
fsl_confirmation_f f
A confirmation function.
Definition: fossil-util.h:3489
unsigned long long int fsl_uint64_t
Definition: fossil-config.h:95
FSL_EXPORT char fsl_buffer_is_compressed(fsl_buffer const *buf)
Equivalent to fsl_data_is_compressed(buf->mem, buf->used).
FSL_EXPORT int fsl_output_f_fsl_cx(void *state, void const *src, fsl_size_t n)
fsl_output_f() implementation which requires state to be a (fsl_cx*) to which this routine simply red...
FSL_EXPORT void * fsl_realloc_f_stdalloc(void *state, void *mem, fsl_size_t n)
A fsl_realloc_f() implementation which uses the standard malloc()/free()/realloc().
FSL_EXPORT int fsl_buffer_resize(fsl_buffer *buf, fsl_size_t n)
Similar to fsl_buffer_reserve() except that...
FSL_EXPORT fsl_size_t fsl_file_simplify_name(char *z, fsl_int_t n_, char slash)
Simplify a filename by:
FSL_EXPORT int fsl_id_bag_insert(fsl_id_bag *p, fsl_id_t e)
Insert element e into the bag if it is not there already.
FSL_EXPORT int fsl_error_set(fsl_error *err, int code, char const *fmt,...)
Populates err with the given code and formatted string, replacing any existing state.
int(* fsl_generic_cmp_f)(void const *lhs, void const *rhs)
A typedef for comparison function used by standard C routines such as qsort().
Definition: fossil-util.h:60
FSL_EXPORT unsigned int fsl_gradient_color(unsigned int c1, unsigned int c2, unsigned int numberOfSteps, unsigned int stepNumber)
For two color values encoded as RRGGBB values (see below for the structure), this function computes a...
Indicates that the answer to the question at hand is "yes" or "okay" and that the same answer should ...
Definition: fossil-util.h:3422
FSL_EXPORT fsl_int_t fsl_fprintfv(FILE *fp, char const *fmt, va_list args)
The va_list counterpart of fsl_fprintf().
FSL_EXPORT void fsl_list_visit_free(fsl_list *list, char freeListMem)
Similar to fsl_list_clear(list, fsl_list_v_fsl_free, NULL), but only frees list->list if the second a...
FSL_EXPORT int fsl_buffer_fill_from_filename(fsl_buffer *dest, char const *filename)
A wrapper for fsl_buffer_fill_from_FILE() which gets its input from the given file name...
int(* fsl_output_f)(void *state, void const *src, fsl_size_t n)
Generic interface for streaming out data.
Definition: fossil-util.h:275
FSL_EXPORT int fsl_str_is_date2(const char *z)
Checks if z is syntactically a time-format string in the format:
FSL_EXPORT int fsl_buffer_delta_create(fsl_buffer const *src, fsl_buffer const *newVers, fsl_buffer *delta)
A fsl_delta_create() wrapper which uses the first two arguments as the original and "new" content ver...
FSL_EXPORT char * fsl_mprintf(char const *fmt,...)
Works like fsl_appendfv(), but appends all output to a dynamically-allocated string, expanding the string as necessary to collect all formatted data.
FSL_EXPORT void fsl_list_sort(fsl_list *li, fsl_generic_cmp_f cmp)
Sorts the given list using the given comparison function.
FSL_EXPORT const fsl_pathfinder fsl_pathfinder_empty
Initialized-with-defaults fsl_pathfinder instance, intended for copy initialization.
Definition: fossil-util.h:3294
FSL_EXPORT int fsl_glob_list_append(fsl_list *tgt, char const *zGlob)
Appends a single blob pattern to tgt, in the form of a new (char *) owned by tgt. ...
FSL_EXPORT const fsl_timer_state fsl_timer_state_empty
Initialized-with-defaults fsl_timer_state_empty instance, intended for copy initialization.
Definition: fossil-util.h:3830
FSL_EXPORT int fsl_output_f_buffer(void *state, void const *src, fsl_size_t n)
A fsl_output_f() impl which requires state to be-a (fsl_buffer*), which this function passes to fsl_b...
Indicates a directory filesystem entry.
Definition: fossil-util.h:2535
FSL_EXPORT void fsl_fclose(FILE *f)
Passes f to fclose(3) unless f is NULL or one of the C-standard (stdin, stdout, stderr) handles...
This flag tells text-mode diff generation to add ANSI color sequences to some output.
Definition: fossil-util.h:3045
FSL_EXPORT const fsl_error fsl_error_empty
Empty-initialized fsl_error instance, intended for copy initialization.
Definition: fossil-util.h:708