htslib: return hts_boolean from the yes/no library functions

The exported API had many functions returning int where the int is really a
yes/no answer. Type the 14 genuinely-boolean ones as hts_boolean
(catch_url, dir_exists, is_dyntype, may_unknown, hts_findnext,
hts_findisdir/isfile/issystem, hts_has_stopped, hts_addurl, hts_resetaddurl,
hts_log, get_httptype_sized, guess_httptype_sized) and the three boolean int
parameters likewise (get_httptype_sized's flag, unescape_http_unharm's no_high,
hts_request_stop's force).

hts_boolean moves from htsopt.h to htsglobal.h so the library header, which only
forward-declares httrackp and does not include htsopt.h, can see the type.

The audit deliberately left alone the functions whose name suggests a boolean
but whose value is not 0/1: hts_is_testing returns 0..5, hts_is_exiting and
is_knowntype/is_userknowntype are tri-state, structcheck and the *_utf8 wrappers
are POSIX 0/-1, hts_findgetsize is a size, hts_main is an exit code, and
copy_htsopt returns 0 for success (a bool would read backwards). hts_setpause
and hts_is_parsing keep int params because they gate on '>= 0', not 0/1.

Not an ABI break: int -> int-sized enum is the same calling convention for both
return values (eax) and parameters, and enum<->int is implicit for callers, so
already-compiled consumers keep working. Verified by comparing per-object
disassembly against master: 39 of 45 objects byte-identical, htslib differs only
in __LINE__ immediates, and the five caller/definer objects differ only in
register allocation and return-block merging (no control-flow or value change).
make check passes.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Signed-off-by: Xavier Roche <roche@httrack.com>

src/htscatchurl.c

@@ -135,7 +135,8 @@ HTSEXT_API T_SOC catch_url_init(int *port, /* 128 bytes */ char *adr) {
 // returns 0 if error
 // url: buffer where URL must be stored - or ip:port in case of failure
 // data: 32Kb
-HTSEXT_API int catch_url(T_SOC soc, char *url, char *method, char *data) {
+HTSEXT_API hts_boolean catch_url(T_SOC soc, char *url, char *method,
+                                 char *data) {
   int retour = 0;
 
   // connexion (accept)

src/htscore.c

@@ -2585,7 +2585,7 @@ static int mkdir_compat(const char *pathname) {
 
 /* path must end with "/" or with the finename (/tmp/bar/ or /tmp/bar/foo.zip) */
 /* Note: preserve errno */
-HTSEXT_API int dir_exists(const char *path) {
+HTSEXT_API hts_boolean dir_exists(const char *path) {
   const int err = errno;
   STRUCT_STAT st;
   char BIGSTK file[HTS_URLMAXSIZE * 2];
@@ -3646,7 +3646,7 @@ HTSEXT_API int hts_setpause(httrackp * opt, int p) {
 }
 
 // ask for termination
-HTSEXT_API int hts_request_stop(httrackp * opt, int force) {
+HTSEXT_API int hts_request_stop(httrackp *opt, hts_boolean force) {
   if (opt != NULL) {
     hts_log_print(opt, LOG_ERROR, "Exit requested by shell or user");
     hts_mutexlock(&opt->state.lock);
@@ -3656,7 +3656,7 @@ HTSEXT_API int hts_request_stop(httrackp * opt, int force) {
   return 0;
 }
 
-HTSEXT_API int hts_has_stopped(httrackp * opt) {
+HTSEXT_API hts_boolean hts_has_stopped(httrackp *opt) {
   int ended;
   hts_mutexlock(&opt->state.lock);
   ended = opt->state.is_ended;
@@ -3678,12 +3678,12 @@ HTSEXT_API int hts_has_stopped(httrackp * opt) {
 //}
 // ajout d'URL
 // -1 : erreur
-HTSEXT_API int hts_addurl(httrackp * opt, char **url) {
+HTSEXT_API hts_boolean hts_addurl(httrackp *opt, char **url) {
   if (url)
     opt->state._hts_addurl = url;
   return (opt->state._hts_addurl != NULL);
 }
-HTSEXT_API int hts_resetaddurl(httrackp * opt) {
+HTSEXT_API hts_boolean hts_resetaddurl(httrackp *opt) {
   opt->state._hts_addurl = NULL;
   return (opt->state._hts_addurl != NULL);
 }

src/htsglobal.h

@@ -242,6 +242,14 @@ Please visit our Website: http://www.httrack.com
 #define HTS_NOPARAM "(none)"
 #define HTS_NOPARAM2 "\"(none)\""
 
+/* Boolean flag for option fields and API yes/no returns. An enum (not C bool)
+   so it stays int-sized: option fields keep the httrackp layout/ABI, and a
+   return type stays compatible with the int it replaces. */
+#ifndef HTS_DEF_DEFSTRUCT_hts_boolean
+#define HTS_DEF_DEFSTRUCT_hts_boolean
+typedef enum hts_boolean { HTS_FALSE = 0, HTS_TRUE = 1 } hts_boolean;
+#endif
+
 /* Larger/smaller of two values. Macros: arguments are evaluated twice. */
 #define maximum(A,B) ( (A) > (B) ? (A) : (B) )
 

src/htslib.c

@@ -3646,8 +3646,9 @@ HTSEXT_API char *unescape_http(char *const catbuff, const size_t size, const cha
 // DOES NOT DECODE %25 (part of CHAR_DELIM)
 // no_high & 1: decode high chars
 // no_high & 2: decode space
-HTSEXT_API char *unescape_http_unharm(char *const catbuff, const size_t size, 
-                                      const char *s, const int no_high) {
+HTSEXT_API char *unescape_http_unharm(char *const catbuff, const size_t size,
+                                      const char *s,
+                                      const hts_boolean no_high) {
   size_t i, j;
 
   RUNTIME_TIME_CHECK_SIZE(size);
@@ -3931,8 +3932,8 @@ void hts_replace(char *s, char from, char to) {
 
 // guess a local file's mime type (e.g. fil="toto.gif" -> s="image/gif")
 // returns 1 if a type was written to s, 0 otherwise
-int guess_httptype_sized(httrackp *opt, char *s, size_t ssize,
-                         const char *fil) {
+hts_boolean guess_httptype_sized(httrackp *opt, char *s, size_t ssize,
+                                 const char *fil) {
   return get_httptype_sized(opt, s, ssize, fil, 1);
 }
 
@@ -3945,8 +3946,8 @@ void guess_httptype(httrackp * opt, char *s, const char *fil) {
 // write the mime type for fil into s (capacity ssize)
 // flag: 1 to always return a type (the "application/..." / octet-stream
 // fallback) returns 1 if a type was written to s, 0 otherwise
-HTSEXT_API int get_httptype_sized(httrackp *opt, char *s, size_t ssize,
-                                  const char *fil, int flag) {
+HTSEXT_API hts_boolean get_httptype_sized(httrackp *opt, char *s, size_t ssize,
+                                          const char *fil, hts_boolean flag) {
   // userdef overrides get_httptype (a rule with an empty value, e.g. "--assume
   // cgi=", matches but writes nothing: report it as "no type" like the old
   // code, whose callers tested strnotempty(s))
@@ -4196,7 +4197,7 @@ HTSEXT_API int is_userknowntype(httrackp * opt, const char *fil) {
 
 // page dynamique?
 // is_dyntype(get_ext("foo.asp"))
-HTSEXT_API int is_dyntype(const char *fil) {
+HTSEXT_API hts_boolean is_dyntype(const char *fil) {
   int j = 0;
 
   if (!fil)
@@ -4214,7 +4215,7 @@ HTSEXT_API int is_dyntype(const char *fil) {
 
 // types critiques qui ne doivent pas être changés car renvoyés par des serveurs qui ne
 // connaissent pas le type
-int may_unknown(httrackp * opt, const char *st) {
+hts_boolean may_unknown(httrackp *opt, const char *st) {
   int j = 0;
 
   // types média
@@ -5236,7 +5237,8 @@ HTSEXT_API int hts_uninit_module(void) {
 }
 
 // legacy. do not use
-HTSEXT_API int hts_log(httrackp * opt, const char *prefix, const char *msg) {
+HTSEXT_API hts_boolean hts_log(httrackp *opt, const char *prefix,
+                               const char *msg) {
   if (opt->log != NULL) {
     fspc(opt, opt->log, prefix);
     fprintf(opt->log, "%s" LF, msg);

src/htsopt.h

@@ -354,13 +354,6 @@ typedef enum hts_travel_scope {
 #define HTS_TRAVEL_SCOPE_MASK 0xff   /**< mask selecting the scope value */
 #define HTS_TRAVEL_TEST_ALL (1 << 8) /**< also test forbidden URLs (-t) */
 
-/* Boolean option flag. An enum (not C bool) so the option fields stay int-sized
-   and the httrackp layout/ABI is unchanged. */
-#ifndef HTS_DEF_DEFSTRUCT_hts_boolean
-#define HTS_DEF_DEFSTRUCT_hts_boolean
-typedef enum hts_boolean { HTS_FALSE = 0, HTS_TRUE = 1 } hts_boolean;
-#endif
-
 #ifndef HTS_DEF_FWSTRUCT_lien_buffers
 #define HTS_DEF_FWSTRUCT_lien_buffers
 typedef struct lien_buffers lien_buffers;

src/htstools.c

@@ -1213,7 +1213,7 @@ HTSEXT_API find_handle hts_findfirst(char *path) {
   return NULL;
 }
 
-HTSEXT_API int hts_findnext(find_handle find) {
+HTSEXT_API hts_boolean hts_findnext(find_handle find) {
   if (find) {
 #ifdef _WIN32
     if ((FindNextFileA(find->handle, &find->hdata)))
@@ -1273,7 +1273,7 @@ HTSEXT_API int hts_findgetsize(find_handle find) {
   return -1;
 }
 
-HTSEXT_API int hts_findisdir(find_handle find) {
+HTSEXT_API hts_boolean hts_findisdir(find_handle find) {
   if (find) {
     if (!hts_findissystem(find)) {
 #ifdef _WIN32
@@ -1287,7 +1287,7 @@ HTSEXT_API int hts_findisdir(find_handle find) {
   }
   return 0;
 }
-HTSEXT_API int hts_findisfile(find_handle find) {
+HTSEXT_API hts_boolean hts_findisfile(find_handle find) {
   if (find) {
     if (!hts_findissystem(find)) {
 #ifdef _WIN32
@@ -1301,7 +1301,7 @@ HTSEXT_API int hts_findisfile(find_handle find) {
   }
   return 0;
 }
-HTSEXT_API int hts_findissystem(find_handle find) {
+HTSEXT_API hts_boolean hts_findissystem(find_handle find) {
   if (find) {
 #ifdef _WIN32
     if (find->hdata.

src/htstools.h

@@ -108,15 +108,15 @@ HTSEXT_API int hts_buildtopindex(httrackp * opt, const char *path,
 // Portable directory find functions
 // Directory find functions
 HTSEXT_API find_handle hts_findfirst(char *path);
-HTSEXT_API int hts_findnext(find_handle find);
+HTSEXT_API hts_boolean hts_findnext(find_handle find);
 HTSEXT_API int hts_findclose(find_handle find);
 
 //
 HTSEXT_API char *hts_findgetname(find_handle find);
 HTSEXT_API int hts_findgetsize(find_handle find);
-HTSEXT_API int hts_findisdir(find_handle find);
-HTSEXT_API int hts_findisfile(find_handle find);
-HTSEXT_API int hts_findissystem(find_handle find);
+HTSEXT_API hts_boolean hts_findisdir(find_handle find);
+HTSEXT_API hts_boolean hts_findisfile(find_handle find);
+HTSEXT_API hts_boolean hts_findissystem(find_handle find);
 
 #endif
 

src/httrack-library.h

@@ -206,7 +206,8 @@ HTSEXT_API htsErrorCallback hts_get_error_callback(void);
 /* Logging */
 /** Legacy: write prefix then msg to opt->log. Returns 0 if written, 1 if
     opt->log is NULL. Prefer hts_log_print(). */
-HTSEXT_API int hts_log(httrackp * opt, const char *prefix, const char *msg);
+HTSEXT_API hts_boolean hts_log(httrackp *opt, const char *prefix,
+                               const char *msg);
 
 /** printf-style log at level @p type (an hts_log_type, optionally |LOG_ERRNO).
     Forwards to the registered log callback, and when the level is <= opt->debug
@@ -313,7 +314,8 @@ HTSEXT_API T_SOC catch_url_init(int *port, char *adr);
     "ip:port". The buffers are caller-allocated and not bounds-checked: @p data
     must be CATCH_URL_DATA_SIZE bytes, and @p url / @p method must fit the
     captured request line. */
-HTSEXT_API int catch_url(T_SOC soc, char *url, char *method, char *data);
+HTSEXT_API hts_boolean catch_url(T_SOC soc, char *url, char *method,
+                                 char *data);
 
 /* State */
 /** Whether the engine is parsing HTML. Returns 0 if not, otherwise the percent
@@ -334,10 +336,10 @@ HTSEXT_API int hts_is_exiting(httrackp * opt);
     caller-owned, NULL-terminated array of strings; the engine stores the
    pointer without copying, so the array and its strings must stay valid until
    the engine consumes them. @return nonzero if a list is now set. */
-HTSEXT_API int hts_addurl(httrackp * opt, char **url);
+HTSEXT_API hts_boolean hts_addurl(httrackp *opt, char **url);
 
 /** Clear any pending add-URL list set by hts_addurl(). Always returns 0. */
-HTSEXT_API int hts_resetaddurl(httrackp * opt);
+HTSEXT_API hts_boolean hts_resetaddurl(httrackp *opt);
 
 /** Apply the runtime-tunable options from @p from onto @p to, to adjust a live
     mirror. Only fields set to a non-sentinel value are copied; the rest of @p
@@ -356,7 +358,7 @@ HTSEXT_API int hts_setpause(httrackp * opt, int);
    lock, so it is safe to call from another thread). @p force is currently
    ignored.
     @return 0; no-op if @p opt is NULL. */
-HTSEXT_API int hts_request_stop(httrackp * opt, int force);
+HTSEXT_API int hts_request_stop(httrackp *opt, hts_boolean force);
 
 /** Queue a single in-progress file, by URL, to be cancelled by the engine.
     @p url is copied internally. Takes the state lock, so it is thread-safe.
@@ -373,7 +375,7 @@ HTSEXT_API void hts_cancel_parsing(httrackp * opt);
 
 /** Nonzero once the mirror has fully ended. Read under the engine state lock,
    so safe to poll from another thread. Wait for this before hts_free_opt(). */
-HTSEXT_API int hts_has_stopped(httrackp * opt);
+HTSEXT_API hts_boolean hts_has_stopped(httrackp *opt);
 
 /* Tools */
 /** Ensure the directory chain leading to @p path exists, creating missing
@@ -390,7 +392,7 @@ HTSEXT_API int structcheck_utf8(const char *path);
 /** Whether the directory containing @p path exists. The basename is stripped
     first, so passing a file path tests its parent directory. @return 1 if it is
     a directory, 0 otherwise. */
-HTSEXT_API int dir_exists(const char *path);
+HTSEXT_API hts_boolean dir_exists(const char *path);
 
 /** Write the HTTP reason phrase for @p statuscode into @p msg, a caller buffer
    of at least 64 bytes. For an unknown code a non-empty @p msg is kept,
@@ -573,14 +575,15 @@ HTSEXT_API char *unescape_http(char *const catbuff, const size_t size, const cha
     must-avoid escapes are kept encoded, and %25 is never decoded). @p no_high &
    1 also decodes high (>= 128) bytes; @p no_high & 2 also decodes an escaped
     space. Returns @p catbuff. */
-HTSEXT_API char *unescape_http_unharm(char *const catbuff, const size_t size, const char *s, const int no_high);
+HTSEXT_API char *unescape_http_unharm(char *const catbuff, const size_t size,
+                                      const char *s, const hts_boolean no_high);
 
 /** Determine the MIME type of local file name @p fil into @p s (capacity
     @p ssize): user --assume rules, then ".html", then the built-in extension
     table. @p flag != 0 forces a fallback type. @return 1 if a type was written,
     0 otherwise. */
-HTSEXT_API int get_httptype_sized(httrackp *opt, char *s, size_t ssize,
-                                  const char *fil, int flag);
+HTSEXT_API hts_boolean get_httptype_sized(httrackp *opt, char *s, size_t ssize,
+                                          const char *fil, hts_boolean flag);
 
 /** @deprecated Use get_httptype_sized(). Assumes @p s has at least
     HTS_MIMETYPE_SIZE capacity. */
@@ -600,7 +603,7 @@ HTSEXT_API int is_userknowntype(httrackp * opt, const char *fil);
 
 /** 1 if @p fil, an extension such as "asp" or "php" (not a full filename), is a
     known dynamic-page type, else 0. */
-HTSEXT_API int is_dyntype(const char *fil);
+HTSEXT_API hts_boolean is_dyntype(const char *fil);
 
 /** Extract the extension of @p fil (text after the last '.', stopping at '?')
     into caller scratch @p catbuff (capacity @p size) and return it. Returns ""
@@ -610,12 +613,12 @@ HTSEXT_API const char *get_ext(char *catbuff, size_t size, const char *fil);
 
 /** 1 if MIME type @p st must not be reclassified or renamed (hypertext types
    and a built-in keep-list of commonly mislabeled types), else 0. */
-HTSEXT_API int may_unknown(httrackp * opt, const char *st);
+HTSEXT_API hts_boolean may_unknown(httrackp *opt, const char *st);
 
 /** Guess the MIME type of local file @p fil into @p s (capacity @p ssize),
     always producing a type. @return 1 if a type was written. */
-HTSEXT_API int guess_httptype_sized(httrackp *opt, char *s, size_t ssize,
-                                    const char *fil);
+HTSEXT_API hts_boolean guess_httptype_sized(httrackp *opt, char *s,
+                                            size_t ssize, const char *fil);
 
 /** @deprecated Use guess_httptype_sized(). Assumes @p s has at least
     HTS_MIMETYPE_SIZE capacity. */
@@ -677,7 +680,7 @@ HTSEXT_API find_handle hts_findfirst(char *path);
 
 /** Advance to the next directory entry. Returns 1 if an entry is available, 0
    at end of directory. */
-HTSEXT_API int hts_findnext(find_handle find);
+HTSEXT_API hts_boolean hts_findnext(find_handle find);
 
 /** Close the iteration and free @p find. Always returns 0; NULL is accepted. */
 HTSEXT_API int hts_findclose(find_handle find);
@@ -692,16 +695,16 @@ HTSEXT_API int hts_findgetsize(find_handle find);
 
 /** 1 if the current entry is a directory, else 0 (a system/special entry, see
     hts_findissystem(), reports 0). */
-HTSEXT_API int hts_findisdir(find_handle find);
+HTSEXT_API hts_boolean hts_findisdir(find_handle find);
 
 /** 1 if the current entry is a regular file, else 0 (a system/special entry,
    see hts_findissystem(), reports 0). */
-HTSEXT_API int hts_findisfile(find_handle find);
+HTSEXT_API hts_boolean hts_findisfile(find_handle find);
 
 /** 1 if the current entry is a special/system entry to skip: "." or "..", on
     POSIX also device/fifo/socket nodes, on Windows also system, hidden or
     temporary entries. Else 0. */
-HTSEXT_API int hts_findissystem(find_handle find);
+HTSEXT_API hts_boolean hts_findissystem(find_handle find);
 
 /* UTF-8 aware FILE API */
 /* On non-Windows these macros resolve directly to the POSIX calls. On Windows