# PetscOptionsHeadBegin
Puts a heading before listing any more published options. Used, for example, in KSPSetFromOptions_GMRES(). Logically Collective on the communicator passed in PetscOptionsBegin()


## Input Parameter

- ***head -*** the heading text





## Notes
Handles errors directly, hence does not return an error code

Must be between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`, and PetscOptionsObject created in `PetscOptionsBegin()` should be the first argument

Must be followed by a call to `PetscOptionsHeadEnd()` in the same function.


## See Also
 `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
`PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
`PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
`PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
`PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
`PetscOptionsFList()`, `PetscOptionsEList()`
@*/
#define PetscOptionsHeadBegin(PetscOptionsObject, head) \
do { \
if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) PetscCall((*PetscHelpPrintf)(PetscOptionsObject->comm, "  %s\n", head)); \
} while (0)

#define PetscOptionsHead(...) PETSC_DEPRECATED_MACRO("GCC warning \"Use PetscOptionsHeadBegin() (since version 3.18)\"") PetscOptionsHeadBegin(__VA_ARGS__)

/*MC
PetscOptionsHeadEnd - Ends a section of options begun with `PetscOptionsHeadBegin()`
See, for example, KSPSetFromOptions_GMRES().

Collective on the comm used in `PetscOptionsBegin()` or obj used in `PetscObjectOptionsBegin()`


## Synopsis
```
#include <petscoptions.h>
PetscErrorCode PetscOptionsHeadEnd(void)
```



## Notes
Must be between a `PetscOptionsBegin()` or `PetscObjectOptionsBegin()` and a `PetscOptionsEnd()`

Must be preceded by a call to `PetscOptionsHeadBegin()` in the same function.

This needs to be used only if the code below `PetscOptionsHeadEnd()` can be run ONLY once.
See, for example, `PCSetFromOptions_Composite()`. This is a return(0) in it for early exit
from the function.

This is only for use with the PETSc options GUI


## See Also
 `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
`PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
`PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
`PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
`PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
`PetscOptionsFList()`, `PetscOptionsEList()`, `PetscOptionsEnum()`

## Level
developer

## Location
<A HREF="PETSC_DOC_OUT_ROOT_PLACEHOLDER/include/petscoptions.h.html#PetscOptionsHeadBegin">include/petscoptions.h</A>

## Examples
<A HREF="PETSC_DOC_OUT_ROOT_PLACEHOLDER/src/ts/tutorials/ex11.c.html">src/ts/tutorials/ex11.c.html</A><BR>
<A HREF="PETSC_DOC_OUT_ROOT_PLACEHOLDER/src/ts/tutorials/ex11_sa.c.html">src/ts/tutorials/ex11_sa.c.html</A><BR>


---
[Edit on GitLab](https://gitlab.com/petsc/petsc/-/edit/release/include/petscoptions.h)


[Index of all Sys routines](index.md)  
[Table of Contents for all manual pages](/docs/manualpages/index.md)  
[Index of all manual pages](/docs/manualpages/singleindex.md)  
