libdi(3)

Name
libdi - disk information library

Synopsis

  Initialization
#include <di.h>

void * di_initialize (void);
int di_process_options (void *di_data, int targc, const char *targv [], int offset);
void di_cleanup (void *di_data);
const char *di_version (void);

  Options

int di_check_option (void *di_data, int option);
void di_format_iter_init (void *di_data);
int di_format_iterate (void *di_data);

  Getting data

int di_get_all_disk_info (void *di_data);
int di_iterate_init (void *di_data, int iteroption);
      typedef struct {
        const char   *strdata [DI_DISP_MAX];      /* string data */
        int          index;             /* internal index value */
        int          doPrint;           /* printable flag based on options */
        int          printFlag;         /* print result flag */
        int          isLocal;           /* filesystem is local */
        int          isReadOnly;        /* filesystem is read-only */
        int          isLoopback;        /* filesystem is a loopback filesystem */
      } di_pub_disk_info_t;

const di_pub_disk_info_t * di_iterate (void *di_data);
int di_get_scale_max (void *di_data, int index,
    int valueidxA, int valueidxB, int valueidxC);
double di_get_scaled (void *di_data, int index,
    int scaleidx, int valueidxA, int valueidxB, int valueidxC);
void di_disp_scaled (void *di_data, char *buff, long buffsz,
    int index, int scaleidx,
    int valueidxA, int valueidxB, int valueidxC);
double di_get_perc (void *di_data, int index,
    int valueidxA, int valueidxB,
    int valueidxC, int valueidxB, int valueidxE);
void di_disp_perc (void *di_data, char *buff, long buffsz,
    int index,
    int valueidxA, int valueidxB,
    int valueidxC, int valueidxB, int valueidxE);

Overview

  Initialization
di_initialize returns a pointer to a di_data structure, used in all of the other library calls. The returned pointer must be freed with di_cleanup.

di_process_options processes the arguments to di. These are passed as strings via an argv structure as if on the command line. If no call to di_process_options is made, di will use the defaults and the DI_ARGS environment variable will not be processed.

If the return value from di_process_options is not DI_EXIT_NORM, di_cleanup should be called and processing stopped.

di_cleanup frees all allocated data.

  Options
di_check_option returns the value of the specified option. All options will return a boolean value, excepting: DI_OPT_DEBUG, DI_OPT_FMT_STR_LEN, DI_OPT_SCALE and DI_OPT_BLOCK_SZ.

option may be one of:

    DI_OPT_POSIX_COMPAT
    DI_OPT_QUOTA_CHECK
    DI_OPT_DISP_CSV
    DI_OPT_DISP_CSV_TAB
    DI_OPT_EXCL_LOOPBACK
    DI_OPT_DISP_JSON
    DI_OPT_DISP_TOTALS
    DI_OPT_DISP_HEADER
    DI_OPT_DISP_ALL
    DI_OPT_LOCAL_ONLY
    DI_OPT_NO_SYMLINK
    DI_OPT_DEBUG
    DI_OPT_FMT_STR_LEN
    DI_OPT_SCALE
    DI_OPT_BLOCK_SZ

di_format_iter_init initializes the format string iterator.

di_format_iterate iterates through each format character in the format string. Note that di allows unrecognized format characters. In the main di program, these are printed as-is.

  Getting Data
di_get_all_disk_info retrieves and processes all of the disk information from the operating system.

If the return value from di_get_all_disk_info is not DI_EXIT_NORM, di_cleanup should be called and processing stopped.

di_iterate_init initializes the disk information iterator. iteroption is one of DI_ITER_PRINTABLE or DI_ITER_ALL. If DI_ITER_PRINTABLE is specified, only the partitions with the doPrint flag set will be returned by the iterator.

di_iterate iterates through the filesystems, returning a di_pub_disk_info_t structure for each filesystem. If the --totals flag was specified as an option, the totals will be the last item returned by the iterator.

di_get_scale_max gets the maximum scaling unit for the space value.

index is the index from the di_pub_disk_info_t structure.

The valueidx arguments indicate which disk space values to use to calculate the the space value. The formula is: A - (B - C). Valid combinations are:

    DI_SPACE_TOTAL, DI_VALUE_NONE, DI_VALUE_NONE // total
    DI_SPACE_TOTAL, DI_SPACE_FREE, DI_SPACE_AVAIL // used
    DI_SPACE_TOTAL, DI_SPACE_FREE, DI_VALUE_NONE // used
    DI_SPACE_TOTAL, DI_SPACE_AVAIL, DI_VALUE_NONE // used
    DI_SPACE_FREE, DI_VALUE_NONE, DI_VALUE_NONE // free
    DI_SPACE_AVAIL, DI_VALUE_NONE, DI_VALUE_NONE // free
    DI_INODE_TOTAL, DI_VALUE_NONE, DI_VALUE_NONE // inode total
    DI_INODE_TOTAL, DI_INODE_FREE, DI_VALUE_NONE // inodes used
    DI_INODE_FREE, DI_VALUE_NONE, DI_VALUE_NONE // inodes free

di_get_scaled gets a space value scaled according to the scaling unit.

index is the index from the di_pub_disk_info_t structure.

scaleidx is the scaling index to use. Use a scaling index returned from di_get_scale_max or use one of the following values:

    DI_SCALE_BYTE
    DI_SCALE_KILO
    DI_SCALE_MEGA
    DI_SCALE_GIGA
    DI_SCALE_TERA
    DI_SCALE_PETA
    DI_SCALE_EXA
    DI_SCALE_ZETTA
    DI_SCALE_YOTTA
    DI_SCALE_RONNA
    DI_SCALE_QUETTA

The valueidx arguments indicate which disk space values to use to calculate the the space value. The formula is: A - (B - C). See di_get_scale_max for a list of valid combinations.

di_disp_scaled gets a space value scaled according to the scaling unit, and creates a string that can be printed.

buff is the character string where the string will be stored.

buffsz is the size of the character string.

index is the index from the di_pub_disk_info_t structure.

scaleidx is the scaling index to use. Use a scaling index returned from di_get_scale_max or one of the values as listed in di_get_scaled.

The valueidx arguments indicate which disk space values to use to calculate the the space value. The formula is: A - (B - C). See di_get_scale_max for a list of valid combinations.

di_get_perc retrieves the disk space value as a percentage.

index is the index from the di_pub_disk_info_t structure.

The valueidx arguments indicate which disk space values to use to calculate the percentage. The formula is: (A - B) / (C - (D - E)).

Valid combinations are:

    /* percent used */
    DI_SPACE_TOTAL, DI_SPACE_AVAIL,
    DI_SPACE_TOTAL, DI_VALUE_NONE, DI_VALUE_NONE
    /* percent used */
    DI_SPACE_TOTAL, DI_SPACE_FREE,
    DI_SPACE_TOTAL, DI_VALUE_NONE, DI_VALUE_NONE
    /* percent used, BSD style */
    DI_SPACE_TOTAL, DI_SPACE_FREE,
    DI_SPACE_TOTAL, DI_VALUE_FREE, DI_VALUE_AVAIL
    /* percent free */
    DI_SPACE_AVAIL, DI_VALUE_NONE,
    DI_SPACE_TOTAL, DI_VALUE_NONE, DI_VALUE_NONE,
    /* percent free */
    DI_SPACE_FREE, DI_VALUE_NONE,
    DI_SPACE_TOTAL, DI_VALUE_NONE, DI_VALUE_NONE,
    /* inodes used */
    DI_INODE_TOTAL, DI_INODE_AVAIL,
    DI_INODE_TOTAL, DI_VALUE_NONE, DI_VALUE_NONE

di_disp_perc retrieves the disk space value as a percentage and creates a string that can be printed.

buff is the character string where the string will be stored.

buffsz is the size of the character string.

index is the index from the di_pub_disk_info_t structure.

The valueidx arguments indicate which disk space values to use to calculate the percentage. The formula is: (A - B) / (C - (D - E)). See di_get_perc for valid combinations.

Example
        /* this code is in the public domain */
        #include <stdio.h>
        #include <stdlib.h>
        #include <stdbool.h>
        #include <math.h>
        #include <di.h>
        enum {
          HAVE_SPACE = 0,
          NO_SPACE = 1,
        };
        int
        check_space (const char *fn, double space_wanted) {
          void        *di_data;
          int         targc;
          const char  *targv [10];
          int         exitflag;
          const di_pub_disk_info_t  *pub;
          int         rval = NO_SPACE;
          int         count;
          targc = 1;
          targv [0] = fn;
          targv [1] = NULL;
          di_data = di_initialize ();
          exitflag = di_process_options (di_data, targc, targv, 0);
          if (exitflag != DI_EXIT_NORM) {
            di_cleanup (di_data);
            exit (exitflag);
          }
          exitflag = di_get_all_disk_info (di_data);
          if (exitflag != DI_EXIT_NORM) {
            di_cleanup (di_data);
            exit (exitflag);
          }
          count = di_iterate_init (di_data, DI_ITER_PRINTABLE);
          while ((pub = di_iterate (di_data)) != NULL) {
            double    dval;
            /* compare terabytes available */
            dval = di_get_scaled (di_data, pub->index, DI_SCALE_TERA,
                DI_SPACE_AVAIL, DI_VALUE_NONE, DI_VALUE_NONE);
            if (dval >= space_wanted) {
              rval = HAVE_SPACE;
            }
          }
          di_cleanup (di_data);
          return rval;
        }
        int
        main (int argc, char *argv []) {
          const char  *fn = "/home/bll/s/di";
          double      spwant = 0.2;   /* terabytes */
          bool        rval;
          if (argc > 1) {
            fn = argv [1];
          }
          if (argc > 2) {
            spwant = atof (argv [2]);
          }
          rval = check_space (fn, spwant);
          if (rval == NO_SPACE) {
            fprintf (stdout, "Not enough disk space\n");
          }
          if (rval == HAVE_SPACE) {
            fprintf (stdout, "Enough disk space\n");
          }
          return rval;
        }

  Compile and Link
        dilibd=$HOME/local/lib
        diinc=$(pkg-config --with-path ${dilibd}/pkgconfig --cflags di)
        dilibs=$(pkg-config --with-path ${dilibd}/pkgconfig --libs di)
        cc -o tt ${diinc} tt.c -Wl,-R${dilibd} ${dilibs})

  Example Run

        bll-g7:bll$ ./tt /home/bll 0.5
        Not enough disk space
        bll-g7:bll$ ./tt /home/bll 0.1
        Enough disk space

See Also
df(1), di(1)

Bugs
Open a ticket at https://sourceforge.net/p/diskinfo-di/tickets/
Send bug reports to: brad.lanam.di @ gmail.com

Links
Home Page: https://diskinfo-di.sourceforge.io/
Wiki: https://sourceforge.net/p/diskinfo-di/wiki/Home/
Change Log: https://sourceforge.net/p/diskinfo-di/wiki/ChangeLog/

Author
Copyright 1994-2025 by Brad Lanam Pleasant Hill, CA