Libiberty Obstacks

https://gcc.gnu.org/onlinedocs/libiberty/
Admin
Libiberty Obstacks provides detailed documentation on obstacks, a memory management technique within...
Tokens:44,069
Snippets:475
Trust Score:10
Update:4 months ago
Show doc for...
Tokens:
Raw
### Example Usage of Fast Growth Macros

Source: https://gcc.gnu.org/onlinedocs/libiberty/Extra-Fast-Growing.html

An example demonstrating how to use `obstack_room` and fast growth macros to efficiently add data to an obstack, with a fallback to ordinary growth macros when space is limited.

```APIDOC
## Example: add_string function

### Description
This function demonstrates how to add a string to an obstack using fast growth macros, with checks for available room.

### Code Example
```c
void
add_string (struct obstack *obstack, const char *ptr, size_t len)
{
  while (len > 0)
    {
      size_t room = obstack_room (obstack);
      if (room == 0)
        {
          /* Not enough room.  Add one character slowly,
             which may copy to a new chunk and make room.  */
          obstack_1grow (obstack, *ptr++);
          len--;
        }
      else
        {
          if (room > len)
            room = len;
          /* Add fast as much as we have room for. */
          len -= room;
          while (room-- > 0)
            obstack_1grow_fast (obstack, *ptr++);
        }
    }
}
```
```

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

### Initialize Static Obstack

Source: https://gcc.gnu.org/onlinedocs/libiberty/Preparing-for-Obstacks.html

Example of initializing a statically declared obstack structure using 'obstack_init'.

```c
static struct obstack myobstack;


obstack_init (&myobstack);

```

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

### Obstack Allocation Example

Source: https://gcc.gnu.org/onlinedocs/libiberty/Obstack-Functions.html

Demonstrates how to allocate memory from an obstack. The first argument (obstack pointer) should not contain side effects as it may be evaluated multiple times.

```c
obstack_alloc (get_obstack (), 4);
```

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

### Initialize Dynamically Allocated Obstack

Source: https://gcc.gnu.org/onlinedocs/libiberty/Preparing-for-Obstacks.html

Example of initializing a dynamically allocated obstack structure using 'obstack_init'.

```c
struct obstack *myobstack_ptr
  = (struct obstack *) xmalloc (sizeof (struct obstack));

obstack_init (myobstack_ptr);

```

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

### String Version Comparison Examples

Source: https://gcc.gnu.org/onlinedocs/libiberty/Functions.html

Compares strings considering them as version numbers. Useful for sorting filenames. Handles integral and fractional numeric parts differently.

```c
strverscmp ("no digit", "no digit")
    => 0    // same behavior as strcmp.
strverscmp ("item#99", "item#100")
    => <0   // same prefix, but 99 < 100.
strverscmp ("alpha1", "alpha001")
    => >0   // fractional part inferior to integral one.
strverscmp ("part1_f012", "part1_f01")
    => >0   // two fractional parts.
strverscmp ("foo.009", "foo.0")
    => <0   // idem, but with leading zeroes only.

```

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

### Standard Library Licensing Text

Source: https://gcc.gnu.org/onlinedocs/libiberty/Library-Copying.html

Include this text at the start of each source file to apply the LGPL terms. It specifies redistribution rights and warranty exclusions.

```text
one line to give the library's name and an idea of what it does.
Copyright (C) year  name of author

This library is free software; you can redistribute it and/or modify it
under the terms of the GNU Lesser General Public License as published by
the Free Software Foundation; either version 2.1 of the License, or (at
your option) any later version.

This library is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public
License along with this library; if not, write to the Free Software
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301,
USA.

```

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

### Add String Using Fast Growth Macros

Source: https://gcc.gnu.org/onlinedocs/libiberty/Extra-Fast-Growing.html

This example demonstrates how to add a string to an obstack using a combination of `obstack_room` for checking space and `obstack_1grow_fast` for efficient growth. It falls back to `obstack_1grow` when no room is available, which may trigger a chunk reallocation.

```c
void
add_string (struct obstack *obstack, const char *ptr, size_t len)
{
  while (len > 0)
    {
      size_t room = obstack_room (obstack);
      if (room == 0)
        {
          /* Not enough room.  Add one character slowly,
             which may copy to a new chunk and make room.  */
          obstack_1grow (obstack, *ptr++);
          len--;
        }
      else
        {
          if (room > len)
            room = len;
          /* Add fast as much as we have room for. */
          len -= room;
          while (room-- > 0)
            obstack_1grow_fast (obstack, *ptr++);
        }
    }
}

```

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

### Get Base Address of Growing Object in Obstack

Source: https://gcc.gnu.org/onlinedocs/libiberty/Status-of-an-Obstack.html

Returns the tentative address of the beginning of the currently growing object. If no object is growing, it returns the starting address for the next object.

```c
void * obstack_base (struct obstack *obstack-ptr)
```

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

### Get Canonical Real Path

Source: https://gcc.gnu.org/onlinedocs/libiberty/Functions.html

Resolves symlinks and simplifies '.' and '..' components in a pathname. Returns a malloced string or NULL on allocation error.

```c
const char* lrealpath(const char *name);
```

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

### obstack_base

Source: https://gcc.gnu.org/onlinedocs/libiberty/Summary-of-Obstacks.html

Returns the tentative starting address of the currently growing object within an obstack.

```APIDOC
## obstack_base

### Description
Returns the tentative starting address of the currently growing object within an obstack.

### Function Signature
`void *obstack_base (struct obstack *obstack-ptr)`

### Parameters
* **obstack-ptr** (`struct obstack *`) - A pointer to the obstack structure.

### Returns
The tentative starting address of the growing object.
```

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

### Get Process Execution Times (pex_get_times)

Source: https://gcc.gnu.org/onlinedocs/libiberty/Functions.html

Retrieves the process execution times for programs run via 'pex_obj'. Results are stored in 'vector'. 'struct pex_time' contains user and system seconds/microseconds. Returns 0 on error, 1 on success.

```c
int pex_get_times (struct pex_obj *obj, int count, struct pex_time *vector)
```

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

### Initialize Process Execution Pipeline (pex_init)

Source: https://gcc.gnu.org/onlinedocs/libiberty/Functions.html

Prepares to execute a pipeline of programs. 'flags' control behavior like recording times or using pipes. 'pname' is for error messages, and 'tempbase' is for temporary file naming.

```c
struct pex_obj * pex_init (int flags, const char *pname, const char *tempbase)
```

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

### simple_object_start_write

Source: https://gcc.gnu.org/onlinedocs/libiberty/Functions.html

Initiates the creation of a new object file based on provided attributes.

```APIDOC
## simple_object_start_write

### Description
Start creating a new object file using the object file format described in attrs. You must fetch attribute information from an existing object file before you can create a new one. There is currently no support for creating an object file de novo.

### Parameters
#### Path Parameters
- **attrs** (simple_object_attributes) - Required - Attributes describing the new object file.
- **segment_name** (const char *) - Optional - Segment name for Mach-O format (required on Darwin, ignored otherwise).
- **errmsg** (const char **) - Required - Pointer to store error message.
- **err** (int *) - Required - Pointer to store errno value or 0.

### Returns
- **simple_object_write*** - A pointer to an `simple_object_write` structure on success, or `NULL` on error.

### Error Handling
- On error `simple_object_start_write` returns `NULL`, sets `*ERRMSG` to an error message, and sets `*err` to an errno value or `0` if there is no relevant errno.
```

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

### obstack_begin

Source: https://gcc.gnu.org/onlinedocs/libiberty/Summary-of-Obstacks.html

Initializes an obstack with a specified initial chunk size. This allows for pre-allocation of memory for the obstack.

```APIDOC
## obstack_begin

### Description
Initializes an obstack with a specified initial chunk size. This allows for pre-allocation of memory for the obstack.

### Function Signature
`int obstack_begin (struct obstack *obstack-ptr, size_t chunk_size)`

### Parameters
* **obstack-ptr** (`struct obstack *`) - A pointer to the obstack structure to be initialized.
* **chunk_size** (`size_t`) - The size in bytes for the initial chunk of memory.

### Returns
An integer indicating the success or failure of the initialization.
```

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

### pex_init

Source: https://gcc.gnu.org/onlinedocs/libiberty/Functions.html

Initializes a pex_obj for executing a pipeline of programs.

```APIDOC
## pex_init

### Description
Prepares to execute one or more programs, where the standard output of each program is piped to the standard input of the next. This provides a system-independent interface for executing a pipeline.

### Method
N/A (C function)

### Parameters
- **flags** (int) - Bitwise combination of flags:
  - `PEX_RECORD_TIMES`: Record subprocess times if possible.
  - `PEX_USE_PIPES`: Use pipes for communication between processes, if possible.
  - `PEX_SAVE_TEMPS`: Do not delete temporary files used for communication between processes.
- **pname** (const char *) - The name of the program to be executed, used in error messages.
- **tempbase** (const char *) - A base name for temporary files; can be `NULL` to use a randomly chosen name.

### Return Value
- **struct pex_obj * ** - A pointer to the initialized `pex_obj`, or `NULL` on error.
```

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

### ISIDST

Source: https://gcc.gnu.org/onlinedocs/libiberty/Functions.html

Checks if a character is an identifier start character (alphabetic or underscore). This macro is defined in safe-ctype.h and provides additional character classes useful for lexical analysis.

```APIDOC
## ISIDST

### Description
Checks if a character is an identifier start character (A-Z, a-z, _).

### Signature
`ISIDST(c)`

### Parameters
* **c** (int) - The character to check.
```

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

### Get Basename from Pathname

Source: https://gcc.gnu.org/onlinedocs/libiberty/Functions.html

Extracts the last component of a pathname. Returns a pointer within the original string, handling empty strings and paths ending in '/'.

```c
const char* lbasename(const char *name);
```

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

### Construct Relative Path Prefix

Source: https://gcc.gnu.org/onlinedocs/libiberty/Functions.html

Calculates a path relative to progname's directory, based on the difference between bin_prefix and prefix. May search PATH if progname lacks a directory. Returns a malloced string or NULL.

```c
const char* make_relative_prefix(const char *progname, const char *bin_prefix, const char *prefix);
```

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

### Search Memory for Character (memchr)

Source: https://gcc.gnu.org/onlinedocs/libiberty/Functions.html

Searches the first 'n' bytes of memory starting at 's' for the character 'c'. Returns a pointer to the first occurrence or NULL if not found.

```c
void* memchr (const void *s, int c, size_t n)
```

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

### choose_tmpdir

Source: https://gcc.gnu.org/onlinedocs/libiberty/Functions.html

Returns a pointer to a directory path suitable for creating temporary files.

```APIDOC
## choose_tmpdir

### Description
Returns a pointer to a directory path suitable for creating temporary files in.

### Function Signature
`const char* choose_tmpdir()`
```

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

### Get Process Execution Status (pex_get_status)

Source: https://gcc.gnu.org/onlinedocs/libiberty/Functions.html

Retrieves the exit status of programs executed via 'pex_obj'. Results are stored in 'vector'. Returns 0 on error, 1 on success.

```c
int pex_get_status (struct pex_obj *obj, int count, int *vector)
```

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

### pwait

Source: https://gcc.gnu.org/onlinedocs/libiberty/Functions.html

Another part of the old execution interface.

```APIDOC
## pwait

### Description
Another part of the old execution interface.

### Parameters
- `pid` (*int*)
- `status` (*int* *.*
- `flags` (*int*)

### Return Value
(*int*)
```

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

### Reverse Memory Search for Character (memrchr)

Source: https://gcc.gnu.org/onlinedocs/libiberty/Functions.html

Searches the first 'n' bytes of memory starting at 's' in reverse order for the character 'c'. Returns a pointer to the first occurrence or NULL if not found.

```c
void* memrchr (const void *s, int c, size_t n)
```

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

### expandargv

Source: https://gcc.gnu.org/onlinedocs/libiberty/Functions.html

Processes command-line arguments to expand response files (arguments starting with '@'). It modifies `argc` and `argv` in place, inserting arguments from response files. The caller may need to deallocate the modified `argv`.

```APIDOC
## expandargv

### Description
The argcp and `argvp` arguments are pointers to the usual `argc` and `argv` arguments to `main`. This function looks for arguments that begin with the character ‘@’. Any such arguments are interpreted as “response files”. The contents of the response file are interpreted as additional command line options. In particular, the file is separated into whitespace-separated strings; each such string is taken as a command-line option. The new options are inserted in place of the option naming the response file, and `*argcp` and `*argvp` will be updated. If the value of `*argvp` is modified by this function, then the new value has been dynamically allocated and can be deallocated by the caller with `freeargv`. However, most callers will simply call `expandargv` near the beginning of `main` and allow the operating system to free the memory when the program exits.

### Function Signature
`void expandargv(int *argcp, char ***argvp)`
```

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

### pexecute

Source: https://gcc.gnu.org/onlinedocs/libiberty/Functions.html

This is the old interface to execute one or more programs. It is still supported for compatibility purposes, but is no longer documented.

```APIDOC
## pexecute

### Description
This is the old interface to execute one or more programs. It is still supported for compatibility purposes, but is no longer documented.

### Parameters
- `program` (*const char*)
- `argv` (*char* *const* *.*
- `this_pname` (*const char*)
- `temp_base` (*const char*)
- `errmsg_fmt` (*char* **
- `errmsg_arg` (*char* **
- `flags` (*int*)
```

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

### mkstemps

Source: https://gcc.gnu.org/onlinedocs/libiberty/Functions.html

Generates a unique temporary file name and opens it. Returns a file descriptor.

```APIDOC
## mkstemps

### Description
Generates a unique temporary file name based on the provided `pattern`. The `pattern` should contain `XXXXXX` in the location where the unique characters will be inserted. `suffix_len` specifies the length of the suffix. The function replaces the `XXXXXX` with unique characters, opens the file for reading and writing, and returns a file descriptor.

### Method
N/A (C function)

### Parameters
- **pattern** (char *) - The template for the filename, containing `XXXXXX`.
- **suffix_len** (int) - The length of the suffix in the pattern.

### Return Value
- **int** - A file descriptor open on the created temporary file, or -1 on error.
```

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

### Get Next Free Byte Address in Obstack Chunk

Source: https://gcc.gnu.org/onlinedocs/libiberty/Status-of-an-Obstack.html

Returns the address of the first free byte in the current chunk, which is the end of the currently growing object. If no object is growing, it returns the same value as obstack_base.

```c
void * obstack_next_free (struct obstack *obstack-ptr)
```

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

### Emulate vfork

Source: https://gcc.gnu.org/onlinedocs/libiberty/Functions.html

Emulates the vfork system call by calling fork and returning its value.

```c
int vfork(void)
```

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

### Execute Program with Environment

Source: https://gcc.gnu.org/onlinedocs/libiberty/Functions.html

Executes a program in a pipeline, allowing specification of the child process environment. Behavior is similar to pex_run, with the environment provided as a NULL-terminated array of 'VAR=VALUE' strings.

```c
char* const* env,
   int env_size,
   const char* outname,
   const char* errname,
   int* err)
```

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

### vprintf

Source: https://gcc.gnu.org/onlinedocs/libiberty/Functions.html

Prints formatted output to standard output using a va_list.

```APIDOC
## vprintf (const char *format, va_list ap)

### Description
Prints formatted output to standard output. It is the same as `printf`, but takes a `va_list` argument instead of a variable number of arguments.

### Method
N/A (C function)

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
N/A

### Response
#### Success Response
Returns the number of characters printed, or a negative value if an output error occurred.

#### Response Example
N/A
```

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

### xatexit

Source: https://gcc.gnu.org/onlinedocs/libiberty/Functions.html

Behaves like the standard `atexit` function but allows an unlimited number of functions to be registered. Requires `xexit` for program termination.

```APIDOC
## xatexit

### Description
Behaves as the standard `atexit` function, but with no limit on the number of registered functions. Returns 0 on success, or −1 on failure. If you use `xatexit` to register functions, you must use `xexit` to terminate your program.

### Signature
`int xatexit(void (*fn) (void))`
```

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

### Execute Program (Old Interface)

Source: https://gcc.gnu.org/onlinedocs/libiberty/Functions.html

This is an older interface for executing one or more programs, maintained for compatibility. It is no longer actively documented.

```c
int pexecute(const char* program,
   char* const* argv,
   const char* this_pname,
   const char* temp_base,
   char** errmsg_fmt,
   char** errmsg_arg,
   int flags)
```

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

### Include Obstack Header

Source: https://gcc.gnu.org/onlinedocs/libiberty/Preparing-for-Obstacks.html

Include the 'obstack.h' header file in your source file to use obstack functionalities.

```c
#include <obstack.h>

```

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

### vfork

Source: https://gcc.gnu.org/onlinedocs/libiberty/Functions.html

Emulates the `vfork` system call by utilizing the `fork` system call.

```APIDOC
## vfork (void)

### Description
Emulates `vfork` by calling `fork` and returning its value.

### Method
N/A (C function)

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
N/A

### Response
#### Success Response
Returns the process ID of the child process, or -1 if the fork failed.

#### Response Example
N/A
```

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

### Create Unique Temporary File (mkstemps)

Source: https://gcc.gnu.org/onlinedocs/libiberty/Functions.html

Generates a unique temporary file name based on 'pattern' and 'suffix_len'. The 'XXXXXX' in 'pattern' is replaced with unique characters. Returns a file descriptor open for reading and writing.

```c
int mkstemps (char *pattern, int suffix_len)
```

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

### obstack_init

Source: https://gcc.gnu.org/onlinedocs/libiberty/Summary-of-Obstacks.html

Initializes the use of an obstack. This function is essential for setting up an obstack before any other operations can be performed on it.

```APIDOC
## obstack_init

### Description
Initializes the use of an obstack. This function is essential for setting up an obstack before any other operations can be performed on it.

### Function Signature
`int obstack_init (struct obstack *obstack-ptr)`

### Parameters
* **obstack-ptr** (`struct obstack *`) - A pointer to the obstack structure to be initialized.

### Returns
An integer indicating the success or failure of the initialization.
```

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

### Variable Argument List Output Functions

Source: https://gcc.gnu.org/onlinedocs/libiberty/Functions.html

Implement printf, fprintf, and sprintf functionality using a va_list. Application must call va_end. Implemented using _doprnt.

```c
int vprintf(const char *format, va_list ap)
```

```c
int vfprintf(FILE *stream,   const char *format, va_list ap)
```

```c
int vsprintf(char *str,   const char *format, va_list ap)
```

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

### asprintf

Source: https://gcc.gnu.org/onlinedocs/libiberty/Functions.html

Similar to sprintf, but allocates memory dynamically for the output string. It computes the required buffer size, allocates memory using malloc, and stores a pointer to the allocated memory.

```APIDOC
## asprintf

### Description
Like `sprintf`, but instead of passing a pointer to a buffer, you pass a pointer to a pointer. This function will compute the size of the buffer needed, allocate memory with `malloc`, and store a pointer to the allocated memory in `*resptr`. The value returned is the same as `sprintf` would return. If memory could not be allocated, minus one is returned and `NULL` is stored in `*resptr`.

### Signature
`int asprintf(char **resptr, const char *format, ...)`
```

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

### Allocate and Copy String in Obstack

Source: https://gcc.gnu.org/onlinedocs/libiberty/Allocation-in-an-Obstack.html

Allocates a copy of a string in a specific obstack. Requires the obstack to be initialized.

```c
struct obstack string_obstack;

char *
copystring (char *string)
{
  size_t len = strlen (string) + 1;
  char *s = (char *) obstack_alloc (&string_obstack, len);
  memcpy (s, string, len);
  return s;
}

```

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

### xvasprintf

Source: https://gcc.gnu.org/onlinedocs/libiberty/Functions.html

Prints formatted output to a dynamically allocated string without failing. If allocation fails, it prints an error to stderr and calls `xexit`.

```APIDOC
## xvasprintf

### Description
Print to allocated string without fail. If `xvasprintf` fails, this will print a message to `stderr` (using the name set by `xmalloc_set_program_name`, if any) and then call `xexit`.

### Signature
`char* xvasprintf(const char *format, va_list args)`
```

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

### random, srandom, initstate, setstate

Source: https://gcc.gnu.org/onlinedocs/libiberty/Functions.html

Functions for random number generation.

```APIDOC
## Random Number Functions

### random

#### Description
Returns a random number in the range 0 to `LONG_MAX`.

#### Return Value
(*long int*)

### srandom

#### Description
Initializes the random number generator to some starting point determined by seed (else, the values returned by `random` are always the same for each run of the program).

#### Parameters
- `seed` (*unsigned int*)

### initstate

#### Description
Allows fine-grained control over the state of the random number generator.

#### Parameters
- `seed` (*unsigned int*)
- `arg_state` (*void* *.*
- `n` (*unsigned long*)

#### Return Value
(*void* *)

### setstate

#### Description
Allows fine-grained control over the state of the random number generator.

#### Parameters
- `arg_state` (*void* *)

#### Return Value
(*void* *)
```

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

### choose_temp_base

Source: https://gcc.gnu.org/onlinedocs/libiberty/Functions.html

Provides a prefix for temporary file names. It returns a dynamically allocated string for a temporary file prefix or NULL if unable to find one. Its use is not recommended for new code.

```APIDOC
## choose_temp_base

### Description
Return a prefix for temporary file names or `NULL` if unable to find one. The current directory is chosen if all else fails so the program is exited if a temporary directory can’t be found (`mktemp` fails). The buffer for the result is obtained with `xmalloc`.
This function is provided for backwards compatibility only. Its use is not recommended.

### Function Signature
`char* choose_temp_base(void)`
```

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

### simple_object_open_read

Source: https://gcc.gnu.org/onlinedocs/libiberty/Functions.html

Opens an object file for reading, returning a pointer for subsequent data extraction.

```APIDOC
## simple_object_open_read

### Description
Opens an object file for reading. Creates and returns an `simple_object_read` pointer which may be passed to other functions to extract data from the object file.

### Parameters
#### Path Parameters
- **descriptor** (int) - Required - File descriptor permitting reading.
- **offset** (off_t) - Required - Offset into the file (0 in normal case).
- **segment_name** (const char *) - Optional - Segment name for Mach-O format (ignored on other systems).
- **errmsg** (const char **) - Required - Pointer to store error message.
- **err** (int *) - Required - Pointer to store errno value or 0.

### Returns
- **simple_object_read*** - A pointer to an `simple_object_read` structure on success, or `NULL` on error.

### Error Handling
- If an error occurs, returns `NULL` and sets `*errmsg` to an error string and `*err` to an errno value or `0`.
```

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

### buildargv

Source: https://gcc.gnu.org/onlinedocs/libiberty/Functions.html

Parses a string into fields separated by whitespace, handling quotes, and builds a vector of pointers to copies of these fields. Memory is allocated using xmalloc.

```APIDOC
## buildargv

### Description
Given a pointer to a string, parse the string extracting fields separated by whitespace and optionally enclosed within either single or double quotes (which are stripped off), and build a vector of pointers to copies of the string for each field. The input string remains unchanged. The last element of the vector is followed by a `NULL` element.
All of the memory for the pointer array and copies of the string is obtained from `xmalloc`. All of the memory can be returned to the system with the single function call `freeargv`, which takes the returned result of `buildargv`, as it’s argument.
Returns a pointer to the argument vector if successful. Returns `NULL` if sp is `NULL` or if there is insufficient memory to complete building the argument vector.
If the input is a null string (as opposed to a `NULL` pointer), then buildarg returns an argument vector that has one arg, a null string.

### Signature
`char** buildargv(char *sp)`
```

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

### putenv

Source: https://gcc.gnu.org/onlinedocs/libiberty/Functions.html

Uses setenv or unsetenv to put a string into the environment or remove it.

```APIDOC
## putenv

### Description
Uses `setenv` or `unsetenv` to put string into the environment or remove it. If string is of the form ‘name=value’ the string is added; if no ‘=’ is present the name is unset/removed.

### Parameters
- `string` (*const char*)

### Return Value
(*int*)
```

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

### pex_input_file

Source: https://gcc.gnu.org/onlinedocs/libiberty/Functions.html

Returns a stream for a temporary file to be used as input for the first program in a pipeline. The stream is automatically closed by the first call to pex_run.

```APIDOC
## pex_input_file

### Description
Return a stream for a temporary file to pass to the first program in the pipeline as input. The name of the input file is chosen according to the same rules `pex_run` uses to choose output file names, based on in_name, obj and the `PEX_SUFFIX` bit in flags. Don’t call `fclose` on the returned stream; the first call to `pex_run` closes it automatically. If flags includes `PEX_BINARY_OUTPUT`, open the stream in binary mode; otherwise, open it in the default mode. Including `PEX_BINARY_OUTPUT` in flags has no effect on Unix.

### Parameters
- **obj** (*struct pex_obj **): Pointer to a pex object.
- **flags** (int): Flags to control file opening and naming. Can include `PEX_BINARY_OUTPUT`.
- **in_name** (const char *): Base name for the input file.

### Returns
- FILE *: A stream for the temporary input file, or NULL on error.
```

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

### pex_run

Source: https://gcc.gnu.org/onlinedocs/libiberty/Functions.html

Execute one program in a pipeline. On success this returns NULL. On failure it returns an error message.

```APIDOC
## pex_run

### Description
Execute one program in a pipeline. On success this returns `NULL`. On failure it returns an error message, a statically allocated string. obj is returned by a previous call to `pex_init`. flags is a bitwise combination of the following:

`PEX_LAST`:
This must be set on the last program in the pipeline. In particular, it should be set when executing a single program. The standard output of the program will be sent to outname, or, if outname is `NULL`, to the standard output of the calling program. Do _not_ set this bit if you want to call `pex_read_output` (described below). After a call to `pex_run` with this bit set, pex_run may no longer be called with the same obj.

`PEX_SEARCH`:
Search for the program using the user’s executable search path.

`PEX_SUFFIX`:
outname is a suffix. See the description of outname, below.

### Parameters
- **obj** (*struct pex_obj **): Pointer to a pex object returned by `pex_init`.
- **flags** (int): A bitwise combination of flags such as `PEX_LAST`, `PEX_SEARCH`, `PEX_SUFFIX`.
- **executable** (const char *): The name of the executable to run.
- **argv** (char * const *): An array of strings representing the arguments to the program.
- **outname** (const char *): The name of the file to redirect standard output to. If `NULL`, output goes to the calling program's stdout. If `PEX_LAST` is set, this is interpreted as a filename or suffix.
- **errname** (const char *): The name of the file to redirect standard error to.
- **err** (int *): Pointer to an integer where error information will be stored.

### Returns
- const char *: `NULL` on success, or an error message string on failure.
```

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

### pex_one

Source: https://gcc.gnu.org/onlinedocs/libiberty/Functions.html

An interface to permit the easy execution of a single program. It handles setting up the execution environment and capturing the exit status.

```APIDOC
## pex_one

### Description
An interface to permit the easy execution of a single program. The return value and most of the parameters are as for a call to `pex_run`. flags is restricted to a combination of `PEX_SEARCH`, `PEX_STDERR_TO_STDOUT`, and `PEX_BINARY_OUTPUT`. outname is interpreted as if `PEX_LAST` were set. On a successful return, `*status` will be set to the exit status of the program.

### Parameters
- **flags** (int): A bitwise combination of `PEX_SEARCH`, `PEX_STDERR_TO_STDOUT`, and `PEX_BINARY_OUTPUT`.
- **executable** (const char *): The name of the executable to run.
- **argv** (char * const *): An array of strings representing the arguments to the program.
- **pname** (const char *): The name of the program, used for error messages.
- **outname** (const char *): The name of the file to redirect standard output to. Interpreted as if `PEX_LAST` were set.
- **errname** (const char *): The name of the file to redirect standard error to.
- **status** (int *): Pointer to an integer where the exit status of the program will be stored.
- **err** (int *): Pointer to an integer where error information will be stored.

### Returns
- const char *: `NULL` on success, or an error message string on failure.
```

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

### Obstack Initialization Functions

Source: https://gcc.gnu.org/onlinedocs/libiberty/Preparing-for-Obstacks.html

These functions initialize an obstack structure for memory allocation. They allow for specifying chunk size, alignment, and custom allocation/deallocation functions.

```APIDOC
## obstack_init

### Description
Initializes an obstack structure for allocation of objects. This macro calls the obstack’s `obstack_chunk_alloc` function. If allocation of memory fails, the function pointed to by `obstack_alloc_failed_handler` is called. The `obstack_init` macro always returns 1.

### Method
Macro

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```c
static struct obstack myobstack;
obstack_init (&myobstack);
```

### Response
#### Success Response (1)
Returns 1.

#### Response Example
```
1
```

## obstack_begin

### Description
Initializes an obstack, specifying chunks to be at least `chunk_size` bytes in size. It uses the obstack’s `obstack_chunk_alloc` function for memory allocation.

### Method
Macro

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
* **chunk_size** (size_t) - The minimum size of chunks to allocate.

### Request Example
```c
obstack_begin (&myobstack, 1024);
```

### Response
#### Success Response (1)
Returns 1.

#### Response Example
```
1
```

## obstack_specify_allocation

### Description
Initializes an obstack, specifying chunk size, chunk alignment, and custom memory allocation and deallocation functions.

### Method
Macro

### Parameters
* **chunk_size** (size_t) - The minimum size of chunks to allocate. A value of zero uses the default size.
* **alignment** (size_t) - The alignment for allocated chunks. A value of zero uses the default alignment.
* **chunkfun** (void *(*)(size_t)) - A function pointer for allocating memory chunks.
* **freefun** (void (*)(void *)) - A function pointer for deallocating memory chunks.

### Request Example
```c
void *my_chunk_alloc(size_t size) { /* ... */ return malloc(size); }
void my_chunk_free(void *ptr) { free(ptr); }
obstack_specify_allocation(&myobstack, 2048, 16, &my_chunk_alloc, &my_chunk_free);
```

### Response
#### Success Response (1)
Returns 1.

#### Response Example
```
1
```

## obstack_specify_allocation_with_arg

### Description
Similar to `obstack_specify_allocation`, but allows custom memory allocation and deallocation functions that take an additional `arg` argument.

### Method
Macro

### Parameters
* **chunk_size** (size_t) - The minimum size of chunks to allocate. A value of zero uses the default size.
* **alignment** (size_t) - The alignment for allocated chunks. A value of zero uses the default alignment.
* **chunkfun** (void *(*)(void *, size_t)) - A function pointer for allocating memory chunks, taking an extra `arg`.
* **freefun** (void (*)(void *, void *)) - A function pointer for deallocating memory chunks, taking an extra `arg`.
* **arg** (void *) - An argument passed to the custom allocation and deallocation functions.

### Request Example
```c
void *my_chunk_alloc_with_arg(void *arg, size_t size) { /* ... */ return malloc(size); }
void my_chunk_free_with_arg(void *arg, void *ptr) { free(ptr); }
obstack_specify_allocation_with_arg(&myobstack, 0, 0, &my_chunk_alloc_with_arg, &my_chunk_free_with_arg, my_context_arg);
```

### Response
#### Success Response (1)
Returns 1.

#### Response Example
```
1
```
```

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

### Create Temporary File Name

Source: https://gcc.gnu.org/onlinedocs/libiberty/Functions.html

Generates a unique temporary file name with a specified suffix. The file is created, and the name is returned as a malloced string or NULL on failure.

```c
char* make_temp_file(const char *suffix);
```

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

### Initialize Random Number Generator

Source: https://gcc.gnu.org/onlinedocs/libiberty/Functions.html

Initializes the random number generator with a seed. If no seed is provided, the sequence of random numbers will be the same each run.

```c
void srandom(unsigned int seed)
```

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

### vasprintf

Source: https://gcc.gnu.org/onlinedocs/libiberty/Functions.html

Allocates memory and formats a string using a va_list, similar to vsprintf but with dynamic buffer allocation.

```APIDOC
## vasprintf (char **resptr, const char *format, va_list args)

### Description
Like `vsprintf`, but instead of passing a pointer to a buffer, you pass a pointer to a pointer. This function will compute the size of the buffer needed, allocate memory with `malloc`, and store a pointer to the allocated memory in `*resptr`. The value returned is the same as `vsprintf` would return. If memory could not be allocated, minus one is returned and `NULL` is stored in `*resptr`.

### Method
N/A (C function)

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
N/A

### Response
#### Success Response
Returns the number of characters that would have been written if the buffer was large enough, or -1 if memory allocation failed.

#### Response Example
N/A
```

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

### splay_tree_new_with_typed_alloc

Source: https://gcc.gnu.org/onlinedocs/libiberty/Functions.html

Creates a splay tree using specified allocators for the tree and its nodes. It supports custom comparison, key deallocation, and value deallocation functions.

```APIDOC
## splay_tree_new_with_typed_alloc

### Description
Creates a splay tree that uses two different allocators, `tree_allocate_fn` and `node_allocate_fn`, for allocating the tree itself and its nodes respectively. This is useful when variables of different types need to be allocated with different allocators. The splay tree will use `compare_fn` to compare nodes, `delete_key_fn` to deallocate keys, and `delete_value_fn` to deallocate values. Keys and values will be deallocated when the tree is deleted using `splay_tree_delete` or when a node is removed using `splay_tree_remove`. `splay_tree_insert` will release the previously inserted key and value using `delete_key_fn` and `delete_value_fn` if the inserted key is already found in the tree.

### Parameters
- **compare_fn** (splay_tree_compare_fn) - Function pointer for comparing nodes.
- **delete_key_fn** (splay_tree_delete_key_fn) - Function pointer for deallocating keys.
- **delete_value_fn** (splay_tree_delete_value_fn) - Function pointer for deallocating values.
- **tree_allocate_fn** (splay_tree_allocate_fn) - Function pointer for allocating the tree.
- **node_allocate_fn** (splay_tree_allocate_fn) - Function pointer for allocating nodes.
- **deallocate_fn** (splay_tree_deallocate_fn) - Function pointer for deallocating memory.
- **allocate_data** (void *) - Data pointer for the allocators.
```

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

### xexit

Source: https://gcc.gnu.org/onlinedocs/libiberty/Functions.html

Terminates the program, first calling any functions registered with `xatexit`, and then using the system's `exit` call.

```APIDOC
## xexit

### Description
Terminates the program. If any functions have been registered with the `xatexit` replacement function, they will be called first. Termination is handled via the system’s normal `exit` call.

### Signature
`void xexit(int code)`
```

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

### obstack_specify_allocation

Source: https://gcc.gnu.org/onlinedocs/libiberty/Summary-of-Obstacks.html

Initializes an obstack with custom allocation functions, including chunk size, alignment, and memory allocation/freeing functions.

```APIDOC
## obstack_specify_allocation

### Description
Initializes an obstack with custom allocation functions, including chunk size, alignment, and memory allocation/freeing functions.

### Function Signature
`int obstack_specify_allocation (struct obstack *obstack-ptr, size_t chunk_size, size_t alignment, void *(*chunkfun) (size_t), void (*freefun) (void *))`

### Parameters
* **obstack-ptr** (`struct obstack *`) - A pointer to the obstack structure to be initialized.
* **chunk_size** (`size_t`) - The size of memory chunks to allocate.
* **alignment** (`size_t`) - The alignment requirement for allocated chunks.
* **chunkfun** (`void *(*)(size_t)`) - A function pointer for allocating memory chunks.
* **freefun** (`void (*)(void *)`) - A function pointer for freeing memory chunks.

### Returns
An integer indicating the success or failure of the initialization.
```

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

### pex_input_pipe

Source: https://gcc.gnu.org/onlinedocs/libiberty/Functions.html

Returns a stream for a pipe connected to the standard input of the first program in the pipeline. The stream is opened for writing and must be closed by the user.

```APIDOC
## pex_input_pipe

### Description
Return a stream fp for a pipe connected to the standard input of the first program in the pipeline; fp is opened for writing. You must have passed `PEX_USE_PIPES` to the `pex_init` call that returned obj. You must close fp using `fclose` yourself when you have finished writing data to the pipeline. The file descriptor underlying fp is marked not to be inherited by child processes. On systems that do not support pipes, this function returns `NULL`, and sets `errno` to `EINVAL`. If you would like to write code that is portable to all systems the `pex` functions support, consider using `pex_input_file` instead. There are two opportunities for deadlock using `pex_input_pipe`.

### Parameters
- **obj** (*struct pex_obj **): Pointer to a pex object.
- **binary** (int): Non-zero to open the stream in binary mode.

### Returns
- FILE *: A stream for the pipe, or NULL on error or if pipes are not supported.
```

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

### Concatenate Strings with Optional Free

Source: https://gcc.gnu.org/onlinedocs/libiberty/Functions.html

Concatenates strings, similar to 'concat'. If 'optr' is not NULL, it is freed after the new string is created. Useful for extending existing strings or building strings in a loop.

```c
str = reconcat (str, "pre-", str, NULL);
```

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

### make_relative_prefix

Source: https://gcc.gnu.org/onlinedocs/libiberty/Functions.html

Calculates a relative path prefix based on provided paths. It determines the path that is in the same relative position to progname's directory as prefix is to bin_prefix.

```APIDOC
## make_relative_prefix

### Description
Given three paths progname, bin_prefix, prefix, return the path that is in the same position relative to progname’s directory as prefix is relative to bin_prefix.

### Signature
`const char* make_relative_prefix(const char *progname, const char *bin_prefix, const char *prefix)`

### Parameters
* **progname** (`const char *`) - The program name path.
* **bin_prefix** (`const char *`) - The binary prefix path.
* **prefix** (`const char *`) - The target prefix path.

### Returns
`const char*` - The calculated relative prefix path, allocated via `malloc`, or `NULL` if no relative prefix can be found.
```

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

### vfprintf

Source: https://gcc.gnu.org/onlinedocs/libiberty/Functions.html

Prints formatted output to a specified file stream using a va_list.

```APIDOC
## vfprintf (FILE *stream, const char *format, va_list ap)

### Description
Prints formatted output to a specified file stream. It is the same as `fprintf`, but takes a `va_list` argument instead of a variable number of arguments.

### Method
N/A (C function)

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
N/A

### Response
#### Success Response
Returns the number of characters printed, or a negative value if an output error occurred.

#### Response Example
N/A
```

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

### xasprintf

Source: https://gcc.gnu.org/onlinedocs/libiberty/Functions.html

Prints formatted output to a dynamically allocated string without failing. If allocation fails, it prints an error to stderr and calls `xexit`.

```APIDOC
## xasprintf

### Description
Print to allocated string without fail. If `xasprintf` fails, this will print a message to `stderr` (using the name set by `xmalloc_set_program_name`, if any) and then call `xexit`.

### Signature
`char* xasprintf(const char *format, ...)`
```

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

### calloc

Source: https://gcc.gnu.org/onlinedocs/libiberty/Functions.html

Allocates storage for a specified number of elements of a given size and zeros the allocated memory.

```APIDOC
## calloc

### Description
Uses `malloc` to allocate storage for nelem objects of elsize bytes each, then zeros the memory.

### Signature
`void* calloc(size_t nelem, size_t elsize)`
```

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

### make_temp_file

Source: https://gcc.gnu.org/onlinedocs/libiberty/Functions.html

Creates and returns a temporary file name with a specified suffix. The returned string is allocated using malloc.

```APIDOC
## make_temp_file

### Description
Creates and returns a temporary file name with a specified suffix.

### Signature
`char* make_temp_file(const char *suffix)`

### Parameters
* **suffix** (`const char *`) - A suffix to append to the temporary file name.

### Returns
`char*` - A pointer to the temporary file name string, allocated with `malloc`, or `NULL` if unable to create one.
```

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

### Define Obstack Memory Allocation Macros

Source: https://gcc.gnu.org/onlinedocs/libiberty/Preparing-for-Obstacks.html

Define 'obstack_chunk_alloc' and 'obstack_chunk_free' macros for memory management. These macros should be defined before using obstacks and typically use 'xmalloc' and 'free'.

```c
#define obstack_chunk_alloc xmalloc
#define obstack_chunk_free free

```

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

### atexit

Source: https://gcc.gnu.org/onlinedocs/libiberty/Functions.html

Registers a function to be called when the program exits normally.

```APIDOC
## atexit

### Description
Causes function f to be called at exit. Returns 0.

### Signature
`int atexit(void (*f)())`
```

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

### stpcpy

Source: https://gcc.gnu.org/onlinedocs/libiberty/Functions.html

Copies the source string to the destination string and returns a pointer to the end of the copied string.

```APIDOC
## stpcpy

### Description
Copies the string `src` into `dst`. Returns a pointer to `dst + strlen(src)`.

### Parameters
- **dst** (char *) - The destination buffer.
- **src** (const char *) - The source string to copy.
```

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

### obstack_specify_allocation_with_arg

Source: https://gcc.gnu.org/onlinedocs/libiberty/Summary-of-Obstacks.html

Similar to obstack_specify_allocation, but allows custom allocation functions to accept an additional argument.

```APIDOC
## obstack_specify_allocation_with_arg

### Description
Similar to obstack_specify_allocation, but allows custom allocation functions to accept an additional argument.

### Function Signature
`int obstack_specify_allocation_with_arg (struct obstack *obstack-ptr, size_t chunk_size, size_t alignment, void *(*chunkfun) (void *, size_t), void (*freefun) (void *, void *), void *arg)`

### Parameters
* **obstack-ptr** (`struct obstack *`) - A pointer to the obstack structure to be initialized.
* **chunk_size** (`size_t`) - The size of memory chunks to allocate.
* **alignment** (`size_t`) - The alignment requirement for allocated chunks.
* **chunkfun** (`void *(*)(void *, size_t)`) - A function pointer for allocating memory chunks, taking an extra argument.
* **freefun** (`void (*)(void *, void *)`) - A function pointer for freeing memory chunks, taking an extra argument.
* **arg** (`void *`) - An extra argument to be passed to the allocation and freeing functions.

### Returns
An integer indicating the success or failure of the initialization.
```

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

### vsprintf

Source: https://gcc.gnu.org/onlinedocs/libiberty/Functions.html

Formats data into a string using a va_list, similar to sprintf but with variable arguments.

```APIDOC
## vsprintf (char *str, const char *format, va_list ap)

### Description
Formats data into a string. It is the same as `sprintf`, but takes a `va_list` argument instead of a variable number of arguments. Note that it does not call `va_end`; this is the application’s responsibility.

### Method
N/A (C function)

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
N/A

### Response
#### Success Response
Returns the number of characters written, not including the terminating null byte.

#### Response Example
N/A
```
Tokens:
Raw