OS

Access OS services. More...

Defines

#define OS_EXEC_FLAG_NO_INPUT   0
#define OS_EXEC_FLAG_INPUT   1
#define OS_EXEC_FLAG_ERROK   2
#define OS_EXEC_FLAG_SILENT   4
#define os_become_must_be_active()   os_become_must_be_active_gizzards(__FILE__, __LINE__)
#define os_become_must_not_be_active()   os_become_must_not_be_active_gizzards(__FILE__, __LINE__)

Enumerations

enum  edit_ty { edit_not_set, edit_foreground, edit_background }

Functions

int os_exists (string_ty *path, bool eaccess_is_ok=false)
bool os_exists (const nstring &path, bool eaccess_is_ok=false)
void os_mkdir (string_ty *path, int mode)
void os_mkdir (const nstring &path, int mode)
void os_rmdir (string_ty *path)
void os_rmdir (const nstring &path)
void os_rmdir_errok (string_ty *path)
void os_rmdir_errok (const nstring &path)
void os_rmdir_bg (string_ty *path)
void os_rmdir_bg (const nstring &path)
void os_rmdir_tree (string_ty *path)
void os_rmdir_tree (const nstring &path)
void os_mkdir_between (string_ty *root, string_ty *rel, int mode)
void os_mkdir_between (const nstring &root, const nstring &rel, int mode)
void os_rename (string_ty *oldpath, string_ty *newpath)
void os_rename (const nstring &oldpath, const nstring &newpath)
void os_unlink (string_ty *path)
void os_unlink (const nstring &path)
void os_unlink_errok (string_ty *path)
void os_unlink_errok (const nstring &path)
string_ty * os_curdir (void)
string_ty * os_path_join (string_ty *lhs, string_ty *rhs)
nstring os_path_join (const nstring &lhs, const nstring &rhs)
string_ty * os_path_cat (string_ty *lhs, string_ty *rhs)
nstring os_path_cat (const nstring &lhs, const nstring &rhs)
string_ty * os_path_rel2abs (string_ty *root, string_ty *path)
nstring os_path_rel2abs (const nstring &root, const nstring &path)
string_ty * os_pathname (string_ty *path, int resolve)
nstring os_pathname (const nstring &path, bool resolve)
string_ty * os_basename (string_ty *name, string_ty *ext=NULL)
nstring os_basename (const nstring &name, const nstring &ext="")
string_ty * os_dirname (string_ty *path)
nstring os_dirname (const nstring &path)
string_ty * os_dirname_relative (string_ty *path)
nstring os_dirname_relative (const nstring &path)
string_ty * os_entryname (string_ty *path)
nstring os_entryname (const nstring &path)
string_ty * os_entryname_relative (string_ty *path)
nstring os_entryname_relative (const nstring &path)
string_ty * os_below_dir (string_ty *higher, string_ty *lower)
nstring os_below_dir (const nstring &upper, const nstring &lower)
void os_chdir (string_ty *path)
void os_chdir (const nstring &path)
void os_setuid (int id)
void os_setgid (int id)
void os_execute (string_ty *cmd, int flags, string_ty *dir)
void os_execute (const nstring &cmd, int flags, const nstring &dir)
int os_execute_retcode (string_ty *cmd, int flags, string_ty *dir)
int os_execute_retcode (const nstring &cmd, int flags, const nstring &dir)
string_ty * os_execute_slurp (string_ty *cmd, int flags, string_ty *dir)
void os_xargs (string_ty *the_command, struct string_list_ty *the_list, string_ty *dir)
void os_xargs (const nstring &the_command, const nstring_list &the_list, const nstring &dir)
long os_file_size (string_ty *)
void os_mtime_range (string_ty *, time_t *, time_t *)
time_t os_mtime_actual (string_ty *)
void os_mtime_set (string_ty *, time_t)
void os_mtime_set_errok (string_ty *, time_t)
void os_chown_check (string_ty *path, int mode, int uid, int gid)
void os_chmod (string_ty *path, int mode)
void os_chmod (const nstring &path, int mode)
void os_chmod_errok (string_ty *path, int mode)
void os_chmod_errok (const nstring &path, int mode)
int os_chmod_query (string_ty *)
void os_link (string_ty *from, string_ty *to)
void os_link (const nstring &from, const nstring &to)
int os_testing_mode (void)
void os_become_init (void)
void os_become_init_mortal (void)
void os_become_reinit_mortal (void)
void os_become (int uid, int gid, int umsk)
void os_become_undo (void)
void os_become_undo (int uid, int gid)
void os_become_undo_atexit (void)
void os_become_orig (void)
void os_become_query (int *uid, int *gid, int *umsk)
void os_become_orig_query (int *uid, int *gid, int *umsk)
int os_become_active (void)
void os_become_must_be_active_gizzards (const char *, int)
void os_become_must_not_be_active_gizzards (const char *, int)
int os_background (void)
 test for backgroundness
int os_readable (string_ty *path)
int os_readable (const nstring &path)
bool os_executable (string_ty *)
int os_waitpid (int child, int *status)
int os_waitpid_status (int child, const char *cmd)
const char * os_shell (void)
void os_edit (string_ty *filename, edit_ty mode)
void os_edit (const nstring &filename, edit_ty mode)
string_ty * os_edit_string (string_ty *, edit_ty)
string_ty * os_edit_new (edit_ty)
string_ty * os_edit_filename (int)
string_ty * os_tmpdir (void)
int os_pathconf_name_max (const nstring &path)
int os_pathconf_name_max (string_ty *path)
int os_pathconf_path_max (const nstring &path)
int os_pathconf_path_max (string_ty *path)
void os_symlink (string_ty *src, string_ty *dst)
void os_symlink (const nstring &src, const nstring &dst)
void os_symlink_or_copy (string_ty *src, string_ty *dst)
string_ty * os_readlink (string_ty *)
int os_symlink_query (string_ty *)
void os_throttle (void)
bool os_unthrottle (void)
void os_owner_query (string_ty *, int *, int *)
string_ty * os_fingerprint (string_ty *)
void os_interrupt_register (void)
void os_interrupt_cope (void)
void os_interrupt_ignore (void)
int os_interrupt_has_occurred (void)
int os_isa_directory (string_ty *path)
bool os_isa_symlink (string_ty *path)
int os_isa_special_file (string_ty *path)
nstring os_magic_file (const nstring &filename)
nstring os_magic_file (string_ty *filename)
string_ty * os_canonify_dirname (string_ty *dirname)
nstring os_canonify_dirname (const nstring &dirname)
void os_check_path_traversable (string_ty *path)

Detailed Description

Access OS services.

Define Documentation

 
#define os_become_must_be_active (  )     os_become_must_be_active_gizzards(__FILE__, __LINE__)

Definition at line 946 of file os.h.

 
#define os_become_must_not_be_active (  )     os_become_must_not_be_active_gizzards(__FILE__, __LINE__)

Definition at line 949 of file os.h.

#define OS_EXEC_FLAG_ERROK   2

Definition at line 38 of file os.h.

#define OS_EXEC_FLAG_INPUT   1

Definition at line 37 of file os.h.

#define OS_EXEC_FLAG_NO_INPUT   0

Definition at line 36 of file os.h.

#define OS_EXEC_FLAG_SILENT   4

Definition at line 39 of file os.h.

Enumeration Type Documentation

enum edit_ty

Enumerator:
edit_not_set 
edit_foreground 
edit_background 

Definition at line 995 of file os.h.

Function Documentation

int os_background ( void   ) 

test for backgroundness

The background function is used to determine if the curent process is running in the background.

Returns:
zero if process is not in the background, nonzero if the process is in the background.

nstring os_basename ( const nstring &  name,
const nstring &  ext = "" 
)

The os_basename function strip directory and suffix from filenames. (see basename(1))

Parameters:
name the filename to process
ext the (optional) suffix to be stripped

string_ty* os_basename ( string_ty *  name,
string_ty *  ext = NULL 
)

The os_basename function strip directory and suffix from filenames. (see basename(1))

Parameters:
name the filename to process
ext the (optional) suffix to be stripped

void os_become ( int  uid,
int  gid,
int  umsk 
)

int os_become_active ( void   ) 

void os_become_init ( void   ) 

void os_become_init_mortal ( void   ) 

void os_become_must_be_active_gizzards ( const char *  ,
int   
)

void os_become_must_not_be_active_gizzards ( const char *  ,
int   
)

void os_become_orig ( void   ) 

void os_become_orig_query ( int *  uid,
int *  gid,
int *  umsk 
)

void os_become_query ( int *  uid,
int *  gid,
int *  umsk 
)

void os_become_reinit_mortal ( void   ) 

void os_become_undo ( int  uid,
int  gid 
)

The os_become_undo function is used to undo the effects of the os_become function. It returns the effective uid and gid to root, so that future os_become call will work.

It is a bug (and a fatal error will be issued) if there is no matching os_become call. If DEBUG is enabled, it will cause an assert failure if the uid and gid in the undo does not match the os_become.

void os_become_undo ( void   ) 

The os_become_undo function is used to undo the effects of the os_become function. It returns the effective uid and gid to root, so that future os_become call will work.

It is a bug (and a fatal error will be issued) if there is no matching os_become call.

void os_become_undo_atexit ( void   ) 

The os_become_undo_atexit function is used to cancel any os_become setting, if one is active. It performs all of the functions of_os_become_undo, except it is not an error if there has been no matching os_become call. This function may only be called from quite_action derived classes.

nstring os_below_dir ( const nstring &  upper,
const nstring &  lower 
)

The os_below_dir function is used to test whether a given path (lower) is below another directory (upper).

Parameters:
upper The top directory.
lower The full directory including "higher" and exterding for additional path compenents.
Returns:
narrow string; being the relative portion below "higher"; or "" if "lower" is not below "higher"; or "." if lower equals higher.
Note:
The return values are not the same as the old string_ty version of this function.

string_ty* os_below_dir ( string_ty *  higher,
string_ty *  lower 
)

The os_below_dir function is used to test whether a given path (lower) is below another directory (upper).

Parameters:
higher The top directory.
lower The full directory including "higher" and exterding for additional path compenents.
Returns:
pointer to string in dynamic memory, being the relative portion below "higher"; NULL if "lower" is not below "higher"; the empty string if lower equals upper.

nstring os_canonify_dirname ( const nstring &  dirname  ) 

The os_canonify_dirname function is used transform a directory name in canonical form (without the trailing slash).

Parameters:
dirname The name of the directory to be canonified.
Returns:
A string with the canonified name of the directory.

string_ty* os_canonify_dirname ( string_ty *  dirname  ) 

The os_canonify_dirname function is used transform a directory name in canonical form (without the trailing slash). This is for compatibility and will eventually disappear.

Parameters:
dirname The name of the directory to be canonified.
Returns:
A string with the canonified name of the directory.

void os_chdir ( const nstring &  path  ) 

The os_chdir function is used to changes the current directory to the specified path.

Parameters:
path The directory to change to.
Note:
This function does not return if there is an error; it printf an error message and exits.

void os_chdir ( string_ty *  path  ) 

The os_chdir function is used to changes the current directory to the specified path.

Parameters:
path The directory to change to.
Note:
This function does not return if there is an error; it printf an error message and exits.

void os_check_path_traversable ( string_ty *  path  ) 

The os_check_path_traversable function is used to check that a path, consisting entirely of existing directories, is traversable (has directory 'x' permissions) by the current user.

Parameters:
path The directory path to walk and check.
Note:
This function does not return if any problem is found; instead it prints a fatal error message and exits.

void os_chmod ( const nstring &  path,
int  mode 
)

The os_chmod function is used to change the permission mode of a file. This function does not return if there is an error; instead it prints an error messages and exits.

Parameters:
path The path of the file to be changed.
mode The permissions mode the file is to assume.

void os_chmod ( string_ty *  path,
int  mode 
)

The os_chmod function is used to change the permission mode of a file. This function does not return if there is an error; instead it prints an error messages and exits.

Parameters:
path The path of the file to be changed.
mode The permissions mode the file is to assume.

void os_chmod_errok ( const nstring &  path,
int  mode 
)

The os_chmod_errok function is used to change the permission mode of a file. This function ignores arror.

Parameters:
path The path of the file to be changed.
mode The permissions mode the file is to assume.

void os_chmod_errok ( string_ty *  path,
int  mode 
)

The os_chmod_errok function is used to change the permission mode of a file. This function ignores arror.

Parameters:
path The path of the file to be changed.
mode The permissions mode the file is to assume.

int os_chmod_query ( string_ty *   ) 

void os_chown_check ( string_ty *  path,
int  mode,
int  uid,
int  gid 
)

string_ty* os_curdir ( void   ) 

The os_curdir function is used to obtain the absolute path of the current directory.

Note:
This function does not return if there is an error; it prints an error message and exits.

nstring os_dirname ( const nstring &  path  ) 

The os_dirname function is used to extract the directory part of a path (i.e. the last /component removed).

Parameters:
path The path to be dismembered.
Note:
The pash is resolved via os_pathname before the directory part is extracted.

string_ty* os_dirname ( string_ty *  path  ) 

The os_dirname function is used to extract the directory part of a path (i.e. the last /component removed).

Parameters:
path The path to be dismembered.
Note:
The pash is resolved via os_pathname before the directory part is extracted.

nstring os_dirname_relative ( const nstring &  path  ) 

The os_dirname_relative function is used to extract the directory part of a path (i.e. the last /component removed). If there is no slash (/) in the filename, "." is returned.

Parameters:
path The path to be dismembered.

string_ty* os_dirname_relative ( string_ty *  path  ) 

The os_dirname_relative function is used to extract the directory part of a path (i.e. the last /component removed). If there is no slash (/) in the filename, "." is returned.

Parameters:
path The path to be dismembered.

void os_edit ( const nstring &  filename,
edit_ty  mode 
)

The os_edit function is used to pass the named file to an edirot for the user to edit. It returns whn the user quit the editor.

Parameters:
filename The name of the file to be edited.
mode How the editing is to be done.

void os_edit ( string_ty *  filename,
edit_ty  mode 
)

The os_edit function is used to pass the named file to an edirot for the user to edit. It returns whn the user quit the editor.

Parameters:
filename The name of the file to be edited.
mode How the editing is to be done.

string_ty* os_edit_filename ( int   ) 

string_ty* os_edit_new ( edit_ty   ) 

string_ty* os_edit_string ( string_ty *  ,
edit_ty   
)

nstring os_entryname ( const nstring &  path  ) 

The os_entryname function is used to extract the last pathname portion of the given path.

Parameters:
path The path to be dismembered.
Note:
The path is resolved via os_pathname before the last portion of the path is extracted.

string_ty* os_entryname ( string_ty *  path  ) 

The os_entryname function is used to extract the last pathname portion of the given path.

Parameters:
path The path to be dismembered.
Note:
The path is resolved via os_pathname before the last portion of the path is extracted.

nstring os_entryname_relative ( const nstring &  path  ) 

The os_entryname_relative function is used to extract the last pathname portion of the given path.

Parameters:
path The path to be dismembered.

string_ty* os_entryname_relative ( string_ty *  path  ) 

The os_entryname_relative function is used to extract the last pathname portion of the given path.

Parameters:
path The path to be dismembered.

bool os_executable ( string_ty *   ) 

void os_execute ( const nstring &  cmd,
int  flags,
const nstring &  dir 
)

The os_execute function i sused to execute a command. It is expected that you have already called os_become to set the user the command is to be executed as.

This function does not return if the command returns a non-zero exit status.

Parameters:
cmd The command to be executed.
flags specific conditions to run the command
dir The current directory to execute the command from.

void os_execute ( string_ty *  cmd,
int  flags,
string_ty *  dir 
)

The os_execute function i sused to execute a command. It is expected that you have already called os_become to set the user the command is to be executed as.

This function does not return if the command returns a non-zero exit status.

Parameters:
cmd The command to be executed.
flags specific conditions to run the command
dir The current directory to execute the command from.

int os_execute_retcode ( const nstring &  cmd,
int  flags,
const nstring &  dir 
)

The os_execute_retcode function is used to execute a command an returns its exit status.

Parameters:
cmd The command to execute
flags flags for how to run the command
dir the directory in which to run the command
Returns:
the exit status: zero on success, non-zero on failure

int os_execute_retcode ( string_ty *  cmd,
int  flags,
string_ty *  dir 
)

The os_execute_retcode function is used to execute a command an returns its exit status.

Parameters:
cmd The command to execute
flags flags for how to run the command
dir the directory in which to run the command
Returns:
the exit status: zero on success, non-zero on failure

string_ty* os_execute_slurp ( string_ty *  cmd,
int  flags,
string_ty *  dir 
)

bool os_exists ( const nstring &  path,
bool  eaccess_is_ok = false 
)

The os_exists function is used to determine if the given path exists. It does not follow symlinks.

Parameters:
path The path to check for existance.
eaccess_is_ok If true, the EACCES error is also cause for returning false, rather than reporting a fatal error and exiting.
Returns:
bool; true if the file exists, false if the file doesn't exist (ENOENT or ENOTDIR).
Note:
This function does not return for any error other than ENOENT or ENOTDIR, but prints an error and exits.

int os_exists ( string_ty *  path,
bool  eaccess_is_ok = false 
)

The os_exists function is used to determine if the given path exists. It does not follow symlinks.

Parameters:
path The path to check for existance.
eaccess_is_ok If true, the EACCES error is also cause for returning false, rather than reporting a fatal error and exiting.
Returns:
int; non-zero if the file exists, zero if the file doesn't (ENOENT or ENOTDIR)
Note:
This function does not return for any error other than ENOENT or ENOTDIR, but prints an error and exits.

long os_file_size ( string_ty *   ) 

string_ty* os_fingerprint ( string_ty *   ) 

void os_interrupt_cope ( void   ) 

int os_interrupt_has_occurred ( void   ) 

void os_interrupt_ignore ( void   ) 

void os_interrupt_register ( void   ) 

int os_isa_directory ( string_ty *  path  ) 

The os_isa_directory function is used to test whether the given absolute path is a directory.

Parameters:
path The absolute file path to be examined.
Returns:
bool; true if the file exists and is a directory, false if the file does not exist, false if the file exists and is not a directory.

int os_isa_special_file ( string_ty *  path  ) 

The os_isa_special_file function is used to test whether the given absolute path is a regular file or not.

Parameters:
path The absolute file path to be examined.
Returns:
bool; false if the file does not exist, false if the file exists and is a regular file, true if the file exists and is a directory, true if the file exists and is a symlink, true if the file exists and is not a regular file,

bool os_isa_symlink ( string_ty *  path  ) 

The os_isa_symlink function is used to test whether the given absolute path is a symbolic link.

Parameters:
path The absolute file path to be examined.
Returns:
bool; true if the file exists and is a symbolic link, false if the file does not exists, false if the file exists and is not a symbolic link.

void os_link ( const nstring &  from,
const nstring &  to 
)

The os_link function is used to make a hard link between two files.

Parameters:
from The existing file.
to The new file to be a hard link of the existing file.

void os_link ( string_ty *  from,
string_ty *  to 
)

The os_link function is used to make a hard link between two files.

Parameters:
from The existing file.
to The new file to be a hard link of the existing file.

nstring os_magic_file ( string_ty *  filename  ) 

The os_magic_file function is used to determine a file type from file contents. This is for compatibility and will eventually disappear.

Parameters:
filename The name of the file to be examined to determine the file type.
Returns:
A string describing the file, as a MIME content-type. E.g. most source files will be "text/plain; charset=us-ascii"

nstring os_magic_file ( const nstring &  filename  ) 

The os_magic_file function is used to determine a file type from file contents.

Parameters:
filename The name of the file to be examined to determine the file type.
Returns:
A string describing the file, as a MIME content-type. E.g. most source files will be "text/plain; charset=us-ascii"

void os_mkdir ( const nstring &  path,
int  mode 
)

The os_mkdir function is used to create a new directory. It does not mak intermediate directories.

Parameters:
path The path opf the directory to be created.
mode The mode of the created directory.
Note:
This function does not return for any error, but prints an error and exits.

void os_mkdir ( string_ty *  path,
int  mode 
)

The os_mkdir function is used to create a new directory. It does not mak intermediate directories.

Parameters:
path The path opf the directory to be created.
mode The mode of the created directory.
Note:
This function does not return for any error, but prints an error and exits.

void os_mkdir_between ( const nstring &  root,
const nstring &  rel,
int  mode 
)

The os_mkdir_between function is used to make intermediate directories, of necessary between a root and a relative destination. The final portion is not created.

Parameters:
root The root directory.
rel The path, relative to the root, which needs to have intermediate directories created.
mode The permissions mode for any created directories.
Note:
This function will not return if there is any error creating a directory, instead it will report the error and exit.

void os_mkdir_between ( string_ty *  root,
string_ty *  rel,
int  mode 
)

The os_mkdir_between function is used to make intermediate directories, of necessary between a root and a relative destination. The final portion is not created.

Parameters:
root The root directory.
rel The path, relative to the root, which needs to have intermediate directories created.
mode The permissions mode for any created directories.
Note:
This function will not return if there is any error creating a directory, instead it will report the error and exit.

time_t os_mtime_actual ( string_ty *   ) 

void os_mtime_range ( string_ty *  ,
time_t *  ,
time_t *   
)

void os_mtime_set ( string_ty *  ,
time_t   
)

void os_mtime_set_errok ( string_ty *  ,
time_t   
)

void os_owner_query ( string_ty *  ,
int *  ,
int *   
)

nstring os_path_cat ( const nstring &  lhs,
const nstring &  rhs 
)

The os_path_cat function is used to carefully join two path components together with a s