BRL-CAD
Loading...
Searching...
No Matches
Environment Management

Cross platform API for interacting with the operating system environment. More...

Collaboration diagram for Environment Management:

Files

file  env.h
 

Macros

#define BU_MEM_ALL   0
 
#define BU_MEM_AVAIL   1
 
#define BU_MEM_PAGE_SIZE   2
 

Functions

int bu_setenv (const char *name, const char *value, int overwrite)
 
ssize_t bu_mem (int type, size_t *sz)
 
const charbu_editor (struct bu_ptbl *editor_opts, int etype, int check_for_cnt, const char **check_for_editors)
 
int bu_interrupt_suspend (void)
 
int bu_interrupt_restore (void)
 

Detailed Description

Cross platform API for interacting with the operating system environment.

Routines for managing signals.

Platform-independent methods for interacting with the parent operating system environment.

These routines provide a common means to temporarily disable and buffer signal processing during critical write operations.

Macro Definition Documentation

◆ BU_MEM_ALL

#define BU_MEM_ALL   0

Definition at line 45 of file env.h.

◆ BU_MEM_AVAIL

#define BU_MEM_AVAIL   1

Definition at line 46 of file env.h.

◆ BU_MEM_PAGE_SIZE

#define BU_MEM_PAGE_SIZE   2

Definition at line 47 of file env.h.

Function Documentation

◆ bu_setenv()

int bu_setenv ( const char name,
const char value,
int  overwrite 
)
extern

◆ bu_mem()

ssize_t bu_mem ( int  type,
size_t sz 
)
extern

Report system memory sizes.

Returns -1 on error and the size of the requested memory type on success. Optionally if sz is non-NULL, the size of the requested memory type will be set to it.

◆ bu_editor()

const char * bu_editor ( struct bu_ptbl editor_opts,
int  etype,
int  check_for_cnt,
const char **  check_for_editors 
)

Select an editor.

Returns a string naming an editor to be used. If an option is needed for invoking the editor, it is supplied via the editor_opt output.

When 0 is supplied to the etype parameter, all editors will be considered when using libbu's internal editors list. To restrict the set searched to console editors, set etype to 1. For only GUI editors, set etype to 2.

The general pattern for trying to locate an editor using inputs (either internal or user supplied is:

  1. If the input is a full, valid path it will be used as-is.
  2. Otherwise, the BRL-CAD's binaries will be checked for a bundled copy.
  3. Otherwise, bu_which will attempt to find the full path.

The highest priority source for editors to try are the BRLCAD_EDITOR_GUI (for graphical editors) and BRLCAD_EDITOR_CONSOLE for console editors. If those are unset or don't satisfy the criteria, the VISUAL (2nd priority) or EDITOR (3rd priority) environment variables are checked next. If any of those variables are set and identify a valid edtior per current criteria they take priority over both libbu's internal list and a user supplied list.

If the environment variables don't pan out, the next priority is any user supplied options via the check_for_editors array. As with the env variables, an attempt will be made to respect the etype setting.

If the optional check_for_editors array is provided, libbu will first attempt to use the contents of that array to find an editor. The main purpose of check_for_editors is to allow applications to define their own preferred precedence order in case there are specific advantages to using some editors over others. It is also useful if an app wishes to list some specialized editor not part of the normal listings, although users should note that the etype modal checks will not be useful when such editors are supplied. If an application wishes to use ONLY a check_for_editors list and not fall back on libbu's internal list if it fails, they should assign the last entry of check_for_editors to be NULL to signal libbu to stop looking for an editor there:

int check_for_cnt = 3; const char *check_for_editors[3] = {"editor1", "editor2", NULL};

To allow libbu to continue on if all check_for_editors entries fail, don't terminate with a NULL:

int check_for_cnt = 2; const char *check_for_editors[3] = {"editor1", "editor2"};

In the latter case, if none of those inputs result in an editor being returned, libbu will attempt to use its own internal lists to search. We are deliberately NOT documenting the libbu's internal editor list as public API, nor do we make any guarantees about what precedence any editor that IS on the list will take relative to other editors. What editors are popular in various environments can change over time, and the purpose of this function is to provide some editor, rather than locking in any particular precedence. check_for_editors should be used if an app needs more guaranteed stability in lookup behaviors.

If etype != 0, bu_editor will attempt to validate any candidate returns against its own internal list of GUI and console editors to avoid returning an editor that is incompatible with the specified environment. There are no strong guarantees offered for this checking - libbu's knowledge of editors is not comprehensive and specification strings for editors may break the matching being used internally. In a case where libbu CAN'T make a definite categorization (a user supplied custom editor, for example) the default behavior will be to pass through the result as successful. This is obviously not foolproof, but in various common cases libbu will avoid returning (for example) nano from an EDITOR setting when a GUI editor type was requested.

Caller should NOT free the main string return from bu_editor or the contents of the editor_opts bu_ptbl. The caller has ownership of the editor_opts bu_ptbl container however, so they ARE responsible for for freeing the table itself once use of editor_opts is complete.

◆ bu_interrupt_suspend()

int bu_interrupt_suspend ( void  )
extern

Defer signal processing and interrupts before critical sections.

Signal processing for a variety of signals that would otherwise disrupt the logic of an application are put on hold until bu_interrupt_restore() is called.

If an interrupt signal is received while suspended, it will be raised when/if interrupts are restored.

Returns 0 on success. Returns non-zero on error (with perror set if signal() failure).

◆ bu_interrupt_restore()

int bu_interrupt_restore ( void  )
extern

Resume signal processing and interrupts after critical sections.

If a signal was raised since bu_interrupt_suspend() was called, the previously installed signal handler will be immediately called albeit only once even if multiple signals were received.

Returns 0 on success. Returns non-zero on error (with perror set if signal() failure).