GNU Gnulib

https://www.gnu.org/software/gnulib/manual/html_node/
Admin
GNU Gnulib is a source-code library of common routines and portability workarounds that enables GNU...
Tokens:777,149
Snippets:5,114
Trust Score:10
Update:5 days ago
Show doc for...
Tokens:
Raw
### Example .sym file for -export-symbols

Source: https://www.gnu.org/software/gnulib/manual/html_node/LD-Version-Scripts.html

A small example of the file syntax for the -export-symbols option, listing the symbols to export: libfoo_init, libfoo_doit, and libfoo_done.

```text
libfoo_init
libfoo_doit
libfoo_done

```

--------------------------------

### Example version script file (LIBFOO_1.0)

Source: https://www.gnu.org/software/gnulib/manual/html_node/LD-Version-Scripts.html

A small example of a version script file format as documented in the GNU LD manual. It exports the symbols libfoo_init, libfoo_doit, and libfoo_done globally, and hides all others locally.

```ld-script
LIBFOO_1.0 {
  global:
    libfoo_init; libfoo_doit; libfoo_done;

  local:
    *;
};

```

--------------------------------

### Link field example: $(POW_LIBM) and $(LTLIBICONV)

Source: https://www.gnu.org/software/gnulib/manual/html_node/Module-description.html

Shows how to specify libraries needed for linking in the Link field. Libraries are written one per line so that gnulib-tool can remove duplicates. The example includes a conditional note about using $(LTLIBICONV) with libtool and $(LIBICONV) otherwise.

```text
$(POW_LIBM)
$(LTLIBICONV) when linking with libtool, $(LIBICONV) otherwise

```

--------------------------------

### Use timevar_push and timevar_pop in main

Source: https://www.gnu.org/software/gnulib/manual/html_node/Profiling-of-program-phases.html

Example of using timevar_push and timevar_pop to start and stop timers around function calls. It initializes the timevar system, starts the total timer, and prints the results to stderr.

```c
#include <config.h>
#include "timevar.h"

#include <stdio.h>
#include "read.h"
#include "work.h"
#include "output.h"

int
main (void)
{
  timevar_enabled = true;
  timevar_init ();
  timevar_start (tv_total);

  timevar_push (tv_read);
  reader ();
  timevar_pop (tv_read);

  timevar_push (tv_work);
  work ();
  timevar_pop (tv_work);

  timevar_push (tv_output);
  output ();
  timevar_pop (tv_output);

  timevar_stop (tv_total);
  timevar_print (stderr);
}
```

--------------------------------

### Makefile.am for library installed in $(libdir)

Source: https://www.gnu.org/software/gnulib/manual/html_node/Supporting-Relocation.html

Add to Makefile.am for every library libfoo installed in $(libdir). Uses RELOCATABLE_VIA_LD conditional.

```makefile
if RELOCATABLE_VIA_LD
libfoo_la_LDFLAGS = `$(RELOCATABLE_LDFLAGS) $(libdir)`
endif

```

--------------------------------

### Initial directory structure

Source: https://www.gnu.org/software/gnulib/manual/html_node/Multiple-instances.html

Shows the initial project layout with a lib directory for the library and a src directory for the programs.

```text
.
|-- configure.ac
|-- lib
|   |-- foo.c
|   `-- Makefile.am
|-- Makefile.am
`-- src
    |-- bar.c
    `-- Makefile.am

```

--------------------------------

### Makefile.am for program installed in $(pkglibdir)

Source: https://www.gnu.org/software/gnulib/manual/html_node/Supporting-Relocation.html

Add to Makefile.am for every program foo installed in $(pkglibdir). Uses RELOCATABLE_VIA_LD conditional and pkglibdir_c_make variable.

```makefile
foo_CPPFLAGS = -DINSTALLDIR=$(pkglibdir_c_make)
if RELOCATABLE_VIA_LD
foo_LDFLAGS = `$(RELOCATABLE_LDFLAGS) $(pkglibdir)`
endif

```

--------------------------------

### Makefile.am for program installed in $(bindir)

Source: https://www.gnu.org/software/gnulib/manual/html_node/Supporting-Relocation.html

Add to Makefile.am for every program foo installed in $(bindir). Uses RELOCATABLE_VIA_LD conditional and bindir_c_make variable.

```makefile
foo_CPPFLAGS = -DINSTALLDIR=$(bindir_c_make)
if RELOCATABLE_VIA_LD
foo_LDFLAGS = `$(RELOCATABLE_LDFLAGS) $(bindir)`
endif

```

--------------------------------

### argp_version_setup

Source: https://www.gnu.org/software/gnulib/manual/html_node/Printing-_002d_002dversion-and-bug_002dreporting-information.html

Sets up version information for argp-based programs. It takes the program name and authors as arguments and should be called before argp_parse.

```APIDOC
## argp_version_setup

### Description
Sets up version information for argp-based programs. It takes the program name and authors as arguments and should be called before argp_parse.

### Function Signature
`void argp_version_setup (const char *program_name, const char *authors)`

### Parameters
- **program_name** (const char*) - Required - Name of the program
- **authors** (const char*) - Required - Authors string

### Usage Notes
This function modifies argp global variables and should be called before `argp_parse`.
```

--------------------------------

### Create Gnulib test directory with gnulib-tool

Source: https://www.gnu.org/software/gnulib/manual/html_node/Building-gnulib.html

Use this command to create a test directory with all modules and tests. Replace '...' with the target directory path.

```shell
gnulib-tool --create-testdir --with-tests --dir=...
```

--------------------------------

### Incorrect Overflow Check Example

Source: https://www.gnu.org/software/gnulib/manual/html_node/Checking-Integer-Overflow.html

An example of an overflow check that may fail due to compiler optimizations assuming signed overflow cannot occur.

```c
if ((a + b < b) == (a < 0))
  a += b;
else
  printf ("overflow\n");
```

--------------------------------

### Using version_etc to print version and copyright information

Source: https://www.gnu.org/software/gnulib/manual/html_node/Printing-_002d_002dversion-and-bug_002dreporting-information.html

Defines version_etc_copyright and calls version_etc to print version, copyright, license, and author information. The output shows the format with the package name, version, copyright year, and authors.

```c
const char version_etc_copyright[] = "Copyright %s %d copyright-holder";

int
main (void)
{
  version_etc (stdout, "my-program", "my-package", "1.0",
               "author1", "author2", (const char *) NULL);
  return 0;
}

```

```text
my-program (my-package) 1.0
Copyright (C) 2025 copyright-holder
License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.

Written by author1 and author2.

```

--------------------------------

### gnulib-tool --import strdup command and output

Source: https://www.gnu.org/software/gnulib/manual/html_node/Initial-import.html

Example command to import the strdup module into a library using Autoconf, Automake, and Libtool. The output lists modules, files copied, and follow-up steps such as adding lib/Makefile to AC_CONFIG_FILES and invoking gl_EARLY and gl_INIT.

```shell
~/src/libfoo$ gnulib-tool --import strdup
Module list with included dependencies:
  absolute-header
  extensions
  strdup
  string
File list:
  lib/dummy.c
  lib/strdup.c
  lib/string.in.h
  m4/absolute-header.m4
  m4/extensions.m4
  m4/gnulib-common.m4
  m4/strdup.m4
  m4/string_h.m4
Creating directory ./lib
Creating directory ./m4
Copying file lib/dummy.c
Copying file lib/strdup.c
Copying file lib/string.in.h
Copying file m4/absolute-header.m4
Copying file m4/extensions.m4
Copying file m4/gnulib-common.m4
Copying file m4/gnulib-tool.m4
Copying file m4/strdup.m4
Copying file m4/string_h.m4
Creating lib/Makefile.am
Creating m4/gnulib-cache.m4
Creating m4/gnulib-comp.m4
Finished.

You may need to add #include directives for the following .h files.
  #include <string.h>

Don't forget to
  - add "lib/Makefile" to AC_CONFIG_FILES in ./configure.ac,
  - mention "lib" in SUBDIRS in Makefile.am,
  - mention "-I m4" in ACLOCAL_AMFLAGS in Makefile.am,
    or add an AC_CONFIG_MACRO_DIRS([m4]) invocation in ./configure.ac,
  - invoke gl_EARLY in ./configure.ac, right after AC_PROG_CC,
  - invoke gl_INIT in ./configure.ac.
~/src/libfoo$

```

--------------------------------

### Perl script relocation code

Source: https://www.gnu.org/software/gnulib/manual/html_node/Supporting-Relocation.html

Add near the beginning of each installed Perl script after importing the relocatable-perl module. Adapt $orig_installdir to the script's install location and transform the needed variables at the end.

```perl
@relocatable_pl@
if ("@RELOCATABLE@" eq "yes") {
  my $exec_prefix = "@exec_prefix@";
  my $orig_installdir = "@bindir@"; # see Makefile.am's *_SCRIPTS variables
  my ($orig_installprefix, $curr_installprefix) =
    find_prefixes($orig_installdir, find_curr_installdir());

  # the subroutine is defined whether or not the enclosing block is executed
  sub relocate {
    my ($dir) = @_;
    if ("@RELOCATABLE@" eq "yes") {
      $dir =~ s%^$orig_installprefix/%$curr_installprefix/%;
      $dir =~ s,/$,,;
    }
    return $dir;
  }
}

# Get some relocated directory names.
# (The gnulib module 'configmake' can help with this.)
$sysconfdir = relocate("@sysconfdir@");
$some_datadir = relocate(@datadir@/something");

```

--------------------------------

### Shell script relocation code

Source: https://www.gnu.org/software/gnulib/manual/html_node/Supporting-Relocation.html

Add near the beginning of each installed shell script after importing the relocatable-script module. Adapt orig_installdir to the script's install location and transform the needed variables at the end.

```shell
@relocatable_sh@

prefix="@prefix@"
exec_prefix="@exec_prefix@"   # usually needs $prefix.
datarootdir="@datarootdir@"   # usually needs $prefix.

if test "@RELOCATABLE@" = yes; then
  bindir="@bindir@"
  orig_installdir="$bindir" # see Makefile.am's *_SCRIPTS variables
  func_find_curr_installdir # determine curr_installdir
  func_find_prefixes
  relocate () {
    echo "$1/" \
    | sed -e "s%^${orig_installprefix}/%${curr_installprefix}/%" \
    | sed -e 's,/$,, '
  }
else
  relocate () {
    echo "$1"
  }
fi

# Get some relocated directory names.
sysconfdir=`relocate "@sysconfdir@"`          # usually needs $prefix.
some_datadir=`relocate "@datadir@/something"` # usually needs $datarootdir.
bindir=`relocate "@bindir@"`       # usually needs $exec_prefix, hence $prefix.

```

--------------------------------

### Using the argmatch group

Source: https://www.gnu.org/software/gnulib/manual/html_node/Recognizing-Option-Arguments.html

Shows how to use the generated argmatch functions: argmatch_backup_choice, argmatch_backup_value, argmatch_backup_argument, and argmatch_backup_usage. Includes comments explaining return values and output.

```c
ptrdiff_t i = argmatch_backup_choice ("--backup", "none");
// argmatch_backup_group.args[i].arg is "none", so its value
// is argmatch_backup_group.args[i].val.
// Return -1 on invalid argument, and -2 on ambiguity.

enum backup_type val = *argmatch_backup_value ("--backup", "none");
// Returns a pointer to the value, and exit on errors.
// So argmatch_backup_group.args[i].val == val.

const char *arg = argmatch_backup_argument (&no_backups);
// arg is "no".

// Print the documentation on stdout.
argmatch_backup_usage (stdout);
// Gives:
//
// The backup suffix is '~', unless set with --suffix or SIMPLE_BACKUP_SUFFIX.
// The version control method may be selected via the --backup option or through
// the VERSION_CONTROL environment variable.  Here are the values:
//
//   no, none, off  never make backups (even if --backup is given)
//   numbered, t, newstyle
//                  make numbered backups
//   existing, nil, numbered-existing
//                  numbered if numbered backups exist, simple otherwise
//   simple, never, single
//                  always make simple backups

```

--------------------------------

### Test module build with gnulib-tool

Source: https://www.gnu.org/software/gnulib/manual/html_node/How-to-add-a-new-module.html

Commands to create a test directory and build the module to verify it compiles correctly. Run from the Gnulib source directory.

```shell
$ ./gnulib-tool --create-testdir --dir=/tmp/testdir module1 ... moduleN
$ cd /tmp/testdir
$ ./configure && make

```

--------------------------------

### Configure script with reliability compiler flags

Source: https://www.gnu.org/software/gnulib/manual/html_node/Writing-reliable-code.html

Example of running the configure script with specific CFLAGS and CPPFLAGS to enable security hardening and undefined behavior sanitization.

```bash
./configure \
 CPPFLAGS='-Wall'\
 CFLAGS='-g3 -O2'\
' -D_FORTIFY_SOURCE=3'\
' -D_GLIBCXX_ASSERTIONS'\
' -fsanitize=undefined'\
' -fsanitize-trap=all'
```

--------------------------------

### pthread_mutex_getprioceiling

Source: https://www.gnu.org/software/gnulib/manual/html_node/Functions-in-_003cpthread_002eh_003e.html

Gets the priority ceiling of a mutex.

```APIDOC
## pthread_mutex_getprioceiling

### Description
Gets the priority ceiling of a mutex.

### Function
pthread_mutex_getprioceiling

### Parameters
- mutex (const pthread_mutex_t*) - The mutex
- prioceiling (int*) - Output for priority ceiling

### Return Value
0 on success, error number on failure.
```

--------------------------------

### Create a POSIX substitutes test directory with gnulib-tool

Source: https://www.gnu.org/software/gnulib/manual/html_node/POSIX-Substitutes-Library.html

Use this command to extract the ISO C and POSIX substitutes into a specified directory. The posix-modules command must be located in the same directory as gnulib-tool.

```bash
gnulib-tool --create-testdir --source-base=lib \
            --dir=/tmp/posixlib `posix-modules`
```

--------------------------------

### pthread_getspecific

Source: https://www.gnu.org/software/gnulib/manual/html_node/Functions-in-_003cpthread_002eh_003e.html

Gets the thread-specific value associated with a key.

```APIDOC
## pthread_getspecific

### Description
Gets the thread-specific value associated with a key.

### Function
pthread_getspecific

### Parameters
- key (pthread_key_t) - The key

### Return Value
The thread-specific value, or NULL if none.
```

--------------------------------

### pthread_getschedparam

Source: https://www.gnu.org/software/gnulib/manual/html_node/Functions-in-_003cpthread_002eh_003e.html

Gets the scheduling policy and parameters of a thread.

```APIDOC
## pthread_getschedparam

### Description
Gets the scheduling policy and parameters of a thread.

### Function
pthread_getschedparam

### Parameters
- thread (pthread_t) - The thread
- policy (int*) - Output for scheduling policy
- param (struct sched_param*) - Output for scheduling parameters

### Return Value
0 on success, error number on failure.
```

--------------------------------

### Include verify.h and standard headers

Source: https://www.gnu.org/software/gnulib/manual/html_node/Compile_002dtime-Assertions.html

Required includes for using the verify module: verify.h, limits.h, and time.h.

```c
#include <verify.h>

#include <limits.h>
#include <time.h>

```

--------------------------------

### inotify_init1

Source: https://www.gnu.org/software/gnulib/manual/html_node/Glibc-sys_002finotify_002eh.html

Initializes a new inotify instance with configurable flags and returns a file descriptor.

```APIDOC
## inotify_init1

### Description
Initializes a new inotify instance with configurable flags and returns a file descriptor.

### Function Signature
`int inotify_init1(int flags)`

### Parameters
- **flags** (int) - Flags controlling the behavior of the new inotify instance.

### Return Value
- **int** - File descriptor for the new inotify instance, or -1 on error.
```

--------------------------------

### pthread_getcpuclockid

Source: https://www.gnu.org/software/gnulib/manual/html_node/Functions-in-_003cpthread_002eh_003e.html

Gets the CPU clock ID of a thread.

```APIDOC
## pthread_getcpuclockid

### Description
Gets the CPU clock ID of a thread.

### Function
pthread_getcpuclockid

### Parameters
- thread (pthread_t) - The thread
- clockid (clockid_t*) - Output for the clock ID

### Return Value
0 on success, error number on failure.
```

--------------------------------

### posix_spawnattr_getflags

Source: https://www.gnu.org/software/gnulib/manual/html_node/Functions-in-_003cspawn_002eh_003e.html

Gets the flags from a spawn attribute object.

```APIDOC
## posix_spawnattr_getflags

### Description
Gets the flags from a spawn attribute object.

### Function
posix_spawnattr_getflags
```

--------------------------------

### inotify_init

Source: https://www.gnu.org/software/gnulib/manual/html_node/Glibc-sys_002finotify_002eh.html

Initializes a new inotify instance and returns a file descriptor.

```APIDOC
## inotify_init

### Description
Initializes a new inotify instance and returns a file descriptor.

### Function Signature
`int inotify_init(void)`

### Parameters
None.

### Return Value
- **int** - File descriptor for the new inotify instance, or -1 on error.
```
Tokens:
Raw