Home | History | Annotate | Line # | Download | only in programs 
      1 /*
      2  * Copyright (c) Meta Platforms, Inc. and affiliates.
      3  * All rights reserved.
      4  *
      5  * This source code is licensed under both the BSD-style license (found in the
      6  * LICENSE file in the root directory of this source tree) and the GPLv2 (found
      7  * in the COPYING file in the root directory of this source tree).
      8  * You may select, at your option, one of the above-listed licenses.
      9  */
     10 
     11 #ifndef UTIL_H_MODULE
     12 #define UTIL_H_MODULE
     13 
     14 /*-****************************************
     15 *  Dependencies
     16 ******************************************/
     17 #include "platform.h"     /* PLATFORM_POSIX_VERSION, ZSTD_NANOSLEEP_SUPPORT, ZSTD_SETPRIORITY_SUPPORT */
     18 #include <stddef.h>       /* size_t, ptrdiff_t */
     19 #include <stdio.h>        /* FILE */
     20 #include <sys/types.h>    /* stat, utime */
     21 #include <sys/stat.h>     /* stat, chmod */
     22 #include "../lib/common/mem.h"          /* U64 */
     23 #if !(defined(_MSC_VER) || defined(__MINGW32__) || defined (__MSVCRT__))
     24 #include <libgen.h>
     25 #endif
     26 
     27 /*-************************************************************
     28 *  Fix fseek()'s 2GiB barrier with MSVC, macOS, *BSD, MinGW
     29 ***************************************************************/
     30 #if defined(LIBC_NO_FSEEKO)
     31 /* Some older libc implementations don't include these functions (e.g. Bionic < 24) */
     32 #  define UTIL_fseek fseek
     33 #elif defined(_MSC_VER) && (_MSC_VER >= 1400)
     34 #  define UTIL_fseek _fseeki64
     35 #elif !defined(__64BIT__) && (PLATFORM_POSIX_VERSION >= 200112L) /* No point defining Large file for 64 bit */
     36 #  define UTIL_fseek fseeko
     37 #elif defined(__MINGW32__) && defined(__MSVCRT__) && !defined(__STRICT_ANSI__) && !defined(__NO_MINGW_LFS)
     38 #  define UTIL_fseek fseeko64
     39 #else
     40 #  define UTIL_fseek fseek
     41 #endif
     42 
     43 /*-*************************************************
     44 *  Sleep & priority functions: Windows - Posix - others
     45 ***************************************************/
     46 #if defined(_WIN32)
     47 #  include <windows.h>
     48 #  define SET_REALTIME_PRIORITY SetPriorityClass(GetCurrentProcess(), REALTIME_PRIORITY_CLASS)
     49 #  define UTIL_sleep(s) Sleep(1000*s)
     50 #  define UTIL_sleepMilli(milli) Sleep(milli)
     51 
     52 #elif PLATFORM_POSIX_VERSION > 0 /* Unix-like operating system */
     53 #  include <unistd.h>   /* sleep */
     54 #  define UTIL_sleep(s) sleep(s)
     55 #  if ZSTD_NANOSLEEP_SUPPORT   /* necessarily defined in platform.h */
     56 #      define UTIL_sleepMilli(milli) { struct timespec t; t.tv_sec=0; t.tv_nsec=milli*1000000ULL; nanosleep(&t, NULL); }
     57 #  else
     58 #      define UTIL_sleepMilli(milli) /* disabled */
     59 #  endif
     60 #  if ZSTD_SETPRIORITY_SUPPORT
     61 #    include <sys/resource.h> /* setpriority */
     62 #    define SET_REALTIME_PRIORITY setpriority(PRIO_PROCESS, 0, -20)
     63 #  else
     64 #    define SET_REALTIME_PRIORITY /* disabled */
     65 #  endif
     66 
     67 #else  /* unknown non-unix operating system */
     68 #  define UTIL_sleep(s)          /* disabled */
     69 #  define UTIL_sleepMilli(milli) /* disabled */
     70 #  define SET_REALTIME_PRIORITY  /* disabled */
     71 #endif
     72 
     73 
     74 /*-****************************************
     75 *  Compiler specifics
     76 ******************************************/
     77 #if defined(__INTEL_COMPILER)
     78 #  pragma warning(disable : 177)    /* disable: message #177: function was declared but never referenced, useful with UTIL_STATIC */
     79 #endif
     80 #if defined(__GNUC__)
     81 #  define UTIL_STATIC static __attribute__((unused))
     82 #elif defined (__cplusplus) || (defined (__STDC_VERSION__) && (__STDC_VERSION__ >= 199901L) /* C99 */)
     83 #  define UTIL_STATIC static inline
     84 #elif defined(_MSC_VER)
     85 #  define UTIL_STATIC static __inline
     86 #else
     87 #  define UTIL_STATIC static  /* this version may generate warnings for unused static functions; disable the relevant warning */
     88 #endif
     89 
     90 
     91 #if defined (__cplusplus)
     92 extern "C" {
     93 #endif
     94 
     95 /*-****************************************
     96 *  Console log
     97 ******************************************/
     98 extern int g_utilDisplayLevel;
     99 
    100 /**
    101  * Displays a message prompt and returns success (0) if first character from stdin
    102  * matches any from acceptableLetters. Otherwise, returns failure (1) and displays abortMsg.
    103  * If any of the inputs are stdin itself, then automatically return failure (1).
    104  */
    105 int UTIL_requireUserConfirmation(const char* prompt, const char* abortMsg, const char* acceptableLetters, int hasStdinInput);
    106 
    107 
    108 /*-****************************************
    109 *  File functions
    110 ******************************************/
    111 #if defined(_MSC_VER)
    112     typedef struct __stat64 stat_t;
    113     typedef int mode_t;
    114 #elif defined(__MINGW32__) && defined (__MSVCRT__)
    115     typedef struct _stati64 stat_t;
    116 #else
    117     typedef struct stat stat_t;
    118 #endif
    119 
    120 #if defined(_MSC_VER) || defined(__MINGW32__) || defined (__MSVCRT__) /* windows support */
    121 #define PATH_SEP '\\'
    122 #define STRDUP(s) _strdup(s)
    123 #else
    124 #define PATH_SEP '/'
    125 #define STRDUP(s) strdup(s)
    126 #endif
    127 
    128 
    129 /**
    130  * Calls platform's equivalent of stat() on filename and writes info to statbuf.
    131  * Returns success (1) or failure (0).
    132  *
    133  * UTIL_fstat() is like UTIL_stat() but takes an optional fd that refers to the
    134  * file in question. It turns out that this can be meaningfully faster. If fd is
    135  * -1, behaves just like UTIL_stat() (i.e., falls back to using the filename).
    136  */
    137 int UTIL_stat(const char* filename, stat_t* statbuf);
    138 int UTIL_fstat(const int fd, const char* filename, stat_t* statbuf);
    139 
    140 /**
    141  * Instead of getting a file's stats, this updates them with the info in the
    142  * provided stat_t. Currently sets owner, group, atime, and mtime. Will only
    143  * update this info for regular files.
    144  *
    145  * UTIL_setFDStat() also takes an fd, and will preferentially use that to
    146  * indicate which file to modify, If fd is -1, it will fall back to using the
    147  * filename.
    148  */
    149 int UTIL_setFileStat(const char* filename, const stat_t* statbuf);
    150 int UTIL_setFDStat(const int fd, const char* filename, const stat_t* statbuf);
    151 
    152 /**
    153  * Set atime to now and mtime to the st_mtim in statbuf.
    154  *
    155  * Directly wraps utime() or utimensat(). Returns -1 on error.
    156  * Does not validate filename is valid.
    157  */
    158 int UTIL_utime(const char* filename, const stat_t *statbuf);
    159 
    160 /*
    161  * These helpers operate on a pre-populated stat_t, i.e., the result of
    162  * calling one of the above functions.
    163  */
    164 
    165 int UTIL_isRegularFileStat(const stat_t* statbuf);
    166 int UTIL_isDirectoryStat(const stat_t* statbuf);
    167 int UTIL_isFIFOStat(const stat_t* statbuf);
    168 int UTIL_isBlockDevStat(const stat_t* statbuf);
    169 U64 UTIL_getFileSizeStat(const stat_t* statbuf);
    170 
    171 /**
    172  * Like chmod(), but only modifies regular files. Provided statbuf may be NULL,
    173  * in which case this function will stat() the file internally, in order to
    174  * check whether it should be modified.
    175  *
    176  * If fd is -1, fd is ignored and the filename is used.
    177  */
    178 int UTIL_chmod(char const* filename, const stat_t* statbuf, mode_t permissions);
    179 int UTIL_fchmod(const int fd, char const* filename, const stat_t* statbuf, mode_t permissions);
    180 
    181 /*
    182  * In the absence of a pre-existing stat result on the file in question, these
    183  * functions will do a stat() call internally and then use that result to
    184  * compute the needed information.
    185  */
    186 
    187 int UTIL_isRegularFile(const char* infilename);
    188 int UTIL_isDirectory(const char* infilename);
    189 int UTIL_isSameFile(const char* file1, const char* file2);
    190 int UTIL_isSameFileStat(const char* file1, const char* file2, const stat_t* file1Stat, const stat_t* file2Stat);
    191 int UTIL_isCompressedFile(const char* infilename, const char *extensionList[]);
    192 int UTIL_isLink(const char* infilename);
    193 int UTIL_isFIFO(const char* infilename);
    194 
    195 /**
    196  * Returns with the given file descriptor is a console.
    197  * Allows faking whether stdin/stdout/stderr is a console
    198  * using UTIL_fake*IsConsole().
    199  */
    200 int UTIL_isConsole(FILE* file);
    201 
    202 /**
    203  * Pretends that stdin/stdout/stderr is a console for testing.
    204  */
    205 void UTIL_fakeStdinIsConsole(void);
    206 void UTIL_fakeStdoutIsConsole(void);
    207 void UTIL_fakeStderrIsConsole(void);
    208 
    209 /**
    210  * Emit traces for functions that read, or modify file metadata.
    211  */
    212 void UTIL_traceFileStat(void);
    213 
    214 #define UTIL_FILESIZE_UNKNOWN  ((U64)(-1))
    215 U64 UTIL_getFileSize(const char* infilename);
    216 U64 UTIL_getTotalFileSize(const char* const * fileNamesTable, unsigned nbFiles);
    217 
    218 /**
    219  * Take @size in bytes,
    220  * prepare the components to pretty-print it in a scaled way.
    221  * The components in the returned struct should be passed in
    222  * precision, value, suffix order to a "%.*f%s" format string.
    223  * Output policy is sensible to @g_utilDisplayLevel,
    224  * for verbose mode (@g_utilDisplayLevel >= 4),
    225  * does not scale down.
    226  */
    227 typedef struct {
    228   double value;
    229   int precision;
    230   const char* suffix;
    231 } UTIL_HumanReadableSize_t;
    232 
    233 UTIL_HumanReadableSize_t UTIL_makeHumanReadableSize(U64 size);
    234 
    235 int UTIL_compareStr(const void *p1, const void *p2);
    236 const char* UTIL_getFileExtension(const char* infilename);
    237 void  UTIL_mirrorSourceFilesDirectories(const char** fileNamesTable, unsigned int nbFiles, const char *outDirName);
    238 char* UTIL_createMirroredDestDirName(const char* srcFileName, const char* outDirRootName);
    239 
    240 
    241 
    242 /*-****************************************
    243  *  Lists of Filenames
    244  ******************************************/
    245 
    246 typedef struct
    247 {   const char** fileNames;
    248     char* buf;            /* fileNames are stored in this buffer (or are read-only) */
    249     size_t tableSize;     /* nb of fileNames */
    250     size_t tableCapacity;
    251 } FileNamesTable;
    252 
    253 /*! UTIL_createFileNamesTable_fromFileName() :
    254  *  read filenames from @inputFileName, and store them into returned object.
    255  * @return : a FileNamesTable*, or NULL in case of error (ex: @inputFileName doesn't exist).
    256  *  Note: inputFileSize must be less than 50MB
    257  */
    258 FileNamesTable*
    259 UTIL_createFileNamesTable_fromFileName(const char* inputFileName);
    260 
    261 /*! UTIL_assembleFileNamesTable() :
    262  *  This function takes ownership of its arguments, @filenames and @buf,
    263  *  and store them inside the created object.
    264  *  note : this function never fails,
    265  *         it will rather exit() the program if internal allocation fails.
    266  * @return : resulting FileNamesTable* object.
    267  */
    268 FileNamesTable*
    269 UTIL_assembleFileNamesTable(const char** filenames, size_t tableSize, char* buf);
    270 
    271 /*! UTIL_freeFileNamesTable() :
    272  *  This function is compatible with NULL argument and never fails.
    273  */
    274 void UTIL_freeFileNamesTable(FileNamesTable* table);
    275 
    276 /*! UTIL_mergeFileNamesTable():
    277  * @return : FileNamesTable*, concatenation of @table1 and @table2
    278  *  note: @table1 and @table2 are consumed (freed) by this operation
    279  */
    280 FileNamesTable*
    281 UTIL_mergeFileNamesTable(FileNamesTable* table1, FileNamesTable* table2);
    282 
    283 
    284 /*! UTIL_expandFNT() :
    285  *  read names from @fnt, and expand those corresponding to directories
    286  *  update @fnt, now containing only file names,
    287  *  note : in case of error, @fnt[0] is NULL
    288  */
    289 void UTIL_expandFNT(FileNamesTable** fnt, int followLinks);
    290 
    291 /*! UTIL_createFNT_fromROTable() :
    292  *  copy the @filenames pointer table inside the returned object.
    293  *  The names themselves are still stored in their original buffer, which must outlive the object.
    294  * @return : a FileNamesTable* object,
    295  *        or NULL in case of error
    296  */
    297 FileNamesTable*
    298 UTIL_createFNT_fromROTable(const char** filenames, size_t nbFilenames);
    299 
    300 /*! UTIL_allocateFileNamesTable() :
    301  *  Allocates a table of const char*, to insert read-only names later on.
    302  *  The created FileNamesTable* doesn't hold a buffer.
    303  * @return : FileNamesTable*, or NULL, if allocation fails.
    304  */
    305 FileNamesTable* UTIL_allocateFileNamesTable(size_t tableSize);
    306 
    307 /*! UTIL_searchFileNamesTable() :
    308  *  Searched through entries in FileNamesTable for a specific name.
    309  * @return : index of entry if found or -1 if not found
    310  */
    311 int UTIL_searchFileNamesTable(FileNamesTable* table, char const* name);
    312 
    313 /*! UTIL_refFilename() :
    314  *  Add a reference to read-only name into @fnt table.
    315  *  As @filename is only referenced, its lifetime must outlive @fnt.
    316  *  Internal table must be large enough to reference a new member,
    317  *  otherwise its UB (protected by an `assert()`).
    318  */
    319 void UTIL_refFilename(FileNamesTable* fnt, const char* filename);
    320 
    321 
    322 /* UTIL_createExpandedFNT() is only active if UTIL_HAS_CREATEFILELIST is defined.
    323  * Otherwise, UTIL_createExpandedFNT() is a shell function which does nothing
    324  * apart from displaying a warning message.
    325  */
    326 #ifdef _WIN32
    327 #  define UTIL_HAS_CREATEFILELIST
    328 #elif defined(__linux__) || (PLATFORM_POSIX_VERSION >= 200112L)  /* opendir, readdir require POSIX.1-2001 */
    329 #  define UTIL_HAS_CREATEFILELIST
    330 #  define UTIL_HAS_MIRRORFILELIST
    331 #else
    332    /* do not define UTIL_HAS_CREATEFILELIST */
    333 #endif
    334 
    335 /*! UTIL_createExpandedFNT() :
    336  *  read names from @filenames, and expand those corresponding to directories.
    337  *  links are followed or not depending on @followLinks directive.
    338  * @return : an expanded FileNamesTable*, where each name is a file
    339  *        or NULL in case of error
    340  */
    341 FileNamesTable*
    342 UTIL_createExpandedFNT(const char* const* filenames, size_t nbFilenames, int followLinks);
    343 
    344 #if defined(_WIN32)
    345 DWORD CountSetBits(ULONG_PTR bitMask);
    346 #endif
    347 
    348 /*-****************************************
    349  *  System
    350  ******************************************/
    351 
    352 int UTIL_countCores(int logical);
    353 
    354 int UTIL_countPhysicalCores(void);
    355 
    356 int UTIL_countLogicalCores(void);
    357 
    358 #if defined (__cplusplus)
    359 }
    360 #endif
    361 
    362 #endif /* UTIL_H_MODULE */
    363