cfl.texi

CFL是Unix下的通用抽象库,以简化Unix下的系统软件开发,CFL库中包含几个分组的函数和宏

subprocess, redirecting its standard input stream to @file{/dev/null},
and connecting its standard output and standard error streams to a new
file descriptor whose value is stored at @var{fd}. It returns
immediately after forking the subprocess. Subsequent reads from the file
descriptor at @var{fd} will effect a piping of output from the
subprocess into the caller.

@code{C_exec_pipefrom_cwd()} is identical to @code{C_exec_pipefrom()},
except that the additional argument @var{cwd} specifies a new working
directory for the spawned subprocess. If this path does not exist or is
not readable, the working directory of the subprocess will remain
unchanged.

The functions return @code{0} on success, or @code{-1} on failure.

The following code illustrates the use of @code{C_exec_pipefrom()} to
process the output from an execution of the @code{ls} program.

@example
int fd, r;
char buf[100], **args;
FILE *fp;

args = C_string_va_makevec(NULL, "/bin/ls", "-al",
                           "/usr/local/bin", NULL);
r = C_exec_pipefrom(args, &fd);
if(r != -1)
  @{
  fp = fdopen(fd, "r");
  while(C_io_gets(fp, buf, sizeof(buf), '\n') != EOF)
    printf("Received: %s\n", buf);
  fclose(fp);
  @}

C_free_vec(args);
@end example

@end deftypefun

@deftypefun int C_exec_pipeto (char **@var{argv}, int *@var{fd})
@deftypefunx int C_exec_pipeto_cwd (char **@var{argv}, int *@var{fd}, @w{const char *@var{cwd}})

@code{C_exec_pipeto()} executes the command specified by @var{argv} as a
subprocess, redirecting its standard output and standard error streams
to @file{/dev/null}, and connecting its standard input stream to a new
file descriptor whose value is stored at @var{fd}. It returns
immediately after forking the subprocess. Subsequent writes to the file
descriptor at @var{fd} will effect a piping of input into the subprocess
from the caller.

@code{C_exec_pipeto_cwd()} is identical to @code{C_exec_pipeto()},
except that the additional argument @var{cwd} specifies a new working
directory for the spawned subprocess. If this path does not exist or is
not readable, the working directory of the subprocess will remain
unchanged.

The functions return @code{0} on success, or @code{-1} on failure.

@end deftypefun 

@deftypefun int C_exec_va_call (const char *@var{arg}, @w{... /* , NULL */})

This function is intended for use as a replacement for the unsafe
@code{system()} library function. It executes in a subprocess the
command specified by the @code{NULL}-terminated variable argument list,
waits for the subprocess to finish, and returns the exit value returned
by the subprocess. No stream redirection takes place: the subprocess
reads from and writes to the parent's standard I/O streams. This function
is implemented using a call to @code{C_exec_run()}, which calls the
@code{execvp()} system call.

On success, the function returns the exit status from the subprocess. On
failure, it returns @code{-1}.

@end deftypefun

@deftypefun int C_exec_wait (pid_t @var{pid})

This function is an interface to the @code{waitpid()} system call. It
waits for the process with process ID of @var{pid} to complete, and
returns its exit status.

@end deftypefun

@node Filesystem Functions, Mandatory File Locking Functions, Process Control Functions, System Functions
@comment  node-name,  next,  previous,  up
@section Filesystem Functions

The following functions provide for the manipulation of files and
directories in the UNIX filesystem.

@deftypefun c_bool_t C_file_readdir (const char *@var{path}, @w{c_dirlist_t *@var{dir}}, @w{int @var{flags}})

@tindex c_dirlist_t
This function reads the names of the files in the directory specified by
@var{path} into the directory list pointed to by @var{dir}. The type
@i{c_dirlist_t} represents a directory file list. Specific directory
reading options are specified in the @var{flags} argument, which is a
bitwise OR of the following macros:

@table @code

@item C_FILE_SKIPDOT
Specifies that the @file{.} entry (referring to the current directory)
not be included in the list.

@item C_FILE_SKIP2DOT
Specifies that the @file{..} entry (referring to the parent directory)
not be included in the list.

@item C_FILE_SKIPHIDDEN
Specifies that hidden files (those beginning with @file{.}) not be
included in the list.

@item C_FILE_ADDSLASH
Specifies that a slash (@file{/}) be appended to directory names.

@item C_FILE_SKIPDIRS
Specifies that directories not be included in the list.

@item C_FILE_SKIPFILES
Specifies that ordinary files not be included in the list.

@item C_FILE_SEPARATE
Specifies that directory names and file names be separated into two
separate lists.

@item C_FILE_SORT
Specifies that the resulting list(s) of names be sorted alphabetically.

@end table

The @i{c_dirlist_t} type is a structure that contains the following members:

@multitable @columnfractions .2 .7

@item @code{char **files}
@tab
A vector of file names (or all names, if @code{C_FILE_SEPARATE} was not
specified).
@item @code{char **dirs}
@tab
A vector of directory names (or @code{NULL}, if @code{C_FILE_SEPARATE} was
not specified).
@item @code{uint_t nfiles}
@tab
The number of regular file names read.
@item @code{uint_t ndirs}
@tab
The number of directory names read.

@end multitable

The function ignores all files which are not regular files or
directories, including symbolic links.

The function returns @code{TRUE} on success, or @code{FALSE} on failure
(for example, if @var{path} is @code{NULL} or invalid).

@end deftypefun

@deftypefun c_bool_t C_file_traverse (const char *@var{path}, c_bool_t (*@var{examine}) (const char *file, const struct stat *fst, uint_t depth, void *hook), @w{void *@var{hook}})

This is a general purpose directory tree traversal function. It begins
descending a directory tree rooted at @var{path}, recursing on
subdirectories. For each directory or regular file encountered, it calls
the function @var{examine}() with its name, its @i{struct stat}
information, and the file's depth from the original @var{path}. If the
@var{examine}() function returns @code{TRUE}, the traversal
continues. Otherwise, if it returns @code{FALSE},
@code{C_file_traverse()} sets the working directory back to @var{path}
and returns immediately.

The pointer @var{hook} may be used to pass arbitrary context data during
the traversal. This pointer will be passed to the @var{examine}()
function on each invocation.

The @var{examine}() function should not change the current working
directory, as this will confuse the traversal routine. If changing the
working directory is unavoidable, the function should save the working
directory on entry and restore it before returning.

The function returns @code{TRUE} if the tree traversal completed
successfully. It returns @code{FALSE} if any of the arguments were
invalid, if it could not set the working directory to @var{path}, or if
@var{examine}() returned @code{FALSE} during the traversal.

The following code fragment prints an outline-style list of all of the
files and subdirectories beginning at the current working directory.

@example
c_bool_t examine(const char *file, const struct stat *fst,
               uint_t depth, void *hook)
  @{
  int i;

  /* indent and print filename */
  for(i = depth * 2; (i--); putchar(' '));
  puts(file);
  return(TRUE);
  @}

void outline(void)
  @{
  C_file_traverse(".", examine, NULL);
  @}
@end example

@end deftypefun

@deftypefun {const char *} C_file_getcwd (void)

This function is a higher-level interface to the @code{getcwd()} system
call. It calls @code{getcwd()} with an initial path buffer, and if the
buffer is too small to hold the entire path, it resizes the buffer and
tries again, @i{ad infinitum}. The function returns a
dynamically allocated string containing the current path on success, or
@code{NULL} on failure. The returned string must eventually be freed by
the caller.

@end deftypefun

@deftypefun c_bool_t C_file_issymlink (const char *@var{path})

This function returns @code{TRUE} if the file specified by @var{path} is
a symbolic link, and @code{FALSE} otherwise.

@end deftypefun

@deftypefun c_bool_t C_file_mkdirs (@w{const char *@var{path}}, @w{mode_t @var{mode}})

This function creates all intermediate directories specified in
@var{path}. Directories will be created with the permissions specified
by @var{mode}. The function returns @code{TRUE} on success or
@code{FALSE} on failure.

@end deftypefun

@deftypefun {void *} C_file_load (@w{const char *@var{path}}, @w{size_t *@var{len}})

This function loads the entire file specified by @var{path} into
memory. The size of the file (that is, the number of bytes read) is
stored at @var{len}.

On success, the function returns a pointer to the dynamically allocated
buffer containing the data. On failure (for example, if @var{path} or
@var{len} is @code{NULL}, or if the file does not exist or cannot be
read) the function returns @code{NULL}.

@end deftypefun

@node Mandatory File Locking Functions, I/O Functions, Filesystem Functions, System Functions
@comment  node-name,  next,  previous,  up
@section Mandatory File Locking Functions

The following functions implement mandatory file locks. Reader/writer
locks and simple filesystem-based semaphores can be implemented using
these functions. These functions lock and unlock entire files; finer
granularity locks may be implemented using the @code{fcntl()} system
call.

@deftypefun c_bool_t C_file_lock (FILE *@var{fp}, @w{int @var{type}})

This function locks an open file @var{fp}. The type of lock is specified
by @var{type} and must be one of @w{@code{C_FILE_READ_LOCK}} (for a read
lock) or @w{@code{C_FILE_WRITE_LOCK}} (for a write lock); these constants
are defined in @file{cfl/util.h}. If the file referred to by @var{fp} is
currently locked by another thread or process, this function blocks
until that lock is released.

The function returns @code{TRUE} if the lock operation succeeds, and
@code{FALSE} if it fails.

@end deftypefun

@deftypefun c_bool_t C_file_trylock (FILE *@var{fp}, @w{int @var{type}})

This function is similar to @w{@code{C_file_lock()}} above, except that if
the lock cannot be obtained, the function returns immediately with a
value of @code{FALSE}.

The function returns @code{TRUE} if the lock operation succeeds, and
@code{FALSE} if it fails.

@end deftypefun

@deftypefun c_bool_t C_file_unlock (FILE *@var{fp}, @w{int @var{type}})

This function removes the lock on the file @var{fp}. The type of lock is
specified by @var{type}, and must match the @var{type} value that was
used for the @w{@code{C_file_lock()}} or @w{@code{C_file_trylock()}}
call that established this lock.

The function returns @code{TRUE} if the unlock operation succeeds, and
@code{FALSE} if it fails.

@end deftypefun

@node I/O Functions, Logging Functions, Mandatory File Locking Functions, System Functions
@comment  node-name,  next,  previous,  up
@section I/O Functions

The following functions simplify reading from and writing to files and
obtaining input from the console.

@deftypefun int C_io_getchar (uint_t @var{delay})

This function is meant to be used as a replacement for @code{getchar()}
in interactive contexts. It accepts a single character of input from the
user by disabling all buffering and character processing on the
controlling terminal. Any character can be entered, including those that
have special meaning to the shell. The argument @var{delay} specifies
how many seconds to wait for a character to be entered.

If the delay expires before a character is typed, the function returns
@code{EOF}. Otherwise, it returns the ASCII value of the character. The
value of @var{delay} may be 0 to effect a poll of the keyboard.

@end deftypefun

@deftypefun int C_io_gets (FILE *@var{fp}, char *@var{buf}, size_t @var{bufsz}, char @var{termin})

This function is meant to be used as a replacement for the
@code{fgets()} library function. It reads data from the stream @var{fp}
into the buffer @var{buf} until @var{bufsz} - 1 bytes have been read or
the terminator character @var{termin} is encountered. Once either
condition has occurred, the input buffer is terminated with a @code{NUL}
character. The terminator character is discarded.

The function returns the number of bytes actually read, or @code{EOF} if
no more characters are available. A return value of @code{0} means that the
terminator character was the first character encountered; it does not
signify an end-of-file condition.

If @var{fp} or @var{buf} is @code{NULL}, the function returns @code{EOF}
immediately.

@end deftypefun

@deftypefun int C_io_getpasswd (@w{const char *@var{prompt}}, @w{char *@var{buf}}, @w{size_t @var{bufsz}})

This function is a general-purpose password input routine. It writes the
prompt string @var{prompt} to standard output, turns off echoing on the
controlling terminal, reads data from standard input into the buffer
@var{buf} in the same manner as @code{C_io_gets()} above, and then turns
echoing back on. The input buffer is terminated with a @code{NUL}
character. The newline terminator character is discarded.

@end deftypefun