apr---接口篇-CFANZ编程社区

apr　:　Apache Portable Runtime

apr 接口详见： http://apr.apache.org/docs/apr/2.0/group__apr__thread__proc.html#ga1426acc5bdd96385769e7b42bfa6ebbd

Library initialization and termination :

1. apr_status_t apr_initialize (void)

// Setup any APR internal data structures. This MUST be the first function called for any APR library.

初始化APR内部数据结构， apr_initialize()函数必须是第一个被调用的APR库函数

2. void apr_terminate (void)

// Tear down any APR internal data structures which aren't torn down automatically.

结束APR库的使用，销毁apr 不能自动回收的数据结构。

Memory Pool Functions：

1. apr_status_t apr_pool_create (apr_pool_t **newpool, apr_pool_t *parent)

//创建一个内存池

//Create a new pool.

//parent:The parent pool. If this is NULL, the new pool is a root pool.

创建一个内存池，这个内存池将一直存活，直到你调用 apr_pool_destroy() 函数以后被销毁

2. void * apr_palloc(apr_pool_t*p, apr_size_t size);

//在内存池上分配指定内存大小的内存块

//Allocate a block of memory from a pool

3. void apr_pool_destroy(apr_pool_t *p);

//销毁一个内存池

//Destroy the pool.

//Remarks: This will actually free the memory

4. void * apr_pcalloc (apr_pool_t *p, apr_size_t size)

在内存池上分配指定内存大小的内存块，并将所有内存置为0

Thread Pool routines

1. apr_status_t apr_thread_pool_create( apr_thread_pool_t ** me, apr_size_t init_threads, apr_size_t max_threads, apr_pool_t * pool )

创建线程地址池

2. apr_status_t apr_thread_pool_destroy(apr_thread_pool_t * me)

Destroy the thread pool and stop all the threads

String routines :

1. apr_status_t apr_tokenize_to_argv (const char *arg_str, char ***argv_out, apr_pool_t *token_context)

// Convert the arguments to a program from one string to an array of strings terminated by a NULL pointer

File I/O Handling Functions:

1. apr_status_t apr_file_open (apr_file_t **newf, const char *fname, apr_int32_t flag, apr_fileperms_t perm, apr_pool_t *pool)

// Open the specified file.

2. apr_status_t apr_file_close (apr_file_t *file)

// Close the specified file.

3. apr_status_t apr_file_read (apr_file_t *thefile, void *buf, apr_size_t *nbytes)

// Read data from the specified file.

4. apr_status_t apr_file_write (apr_file_t *thefile, const void *buf, apr_size_t *nbytes)

//Write data to the specified file.

5. apr_status_t apr_file_write_full (apr_file_t *thefile, const void *buf, apr_size_t nbytes, apr_size_t *bytes_written)

// Write data to the specified file, ensuring that all of the data is written before returning.

6. apr_status_t apr_file_info_get (apr_finfo_t *finfo, apr_int32_t wanted, apr_file_t *thefile)

// get the specified file's stats.

7. apr_status_t apr_file_trunc (apr_file_t *fp, apr_off_t offset)

// Truncate the file's length to the specified offset

8. int apr_file_printf (apr_file_t *fptr, const char *format,...)

//Write a string to a file using a printf format.

9. apr_status_t apr_file_rename (const char *from_path, const char *to_path, apr_pool_t *pool)

// Rename the specified file.

5. apr_status_t apr_file_eof (apr_file_t *fptr)

// Are we at the end of the file

Directory Manipulation Functions :

1. apr_status_t apr_dir_open (apr_dir_t **new_dir, const char *dirname, apr_pool_t *pool)

// Open the specified directory.

2. apr_status_t apr_dir_close (apr_dir_t *thedir)

// close the specified directory.

3. apr_status_t apr_dir_make_recursive (const char *path, apr_fileperms_t perm, apr_pool_t *pool)

// Creates a new directory on the file system, but behaves like 'mkdir -p'. Creates intermediate directories as required. No error will be reported if PATH already exists.

Time Routines :

1. apr_time_t apr_time_now (void)

// the current time

2. void apr_sleep (apr_interval_time_t t)

// Sleep for the specified number of micro-seconds.

3. #define apr_time_from_sec(sec) ((apr_time_t)(sec) * APR_USEC_PER_SEC)

// return seconds as an apr_time_t

4. apr_status_t apr_time_exp_lt (apr_time_exp_t *result, apr_time_t input)

// convert a time to its human readable components in local timezone

Threads and Process Functions：

1. apr_status_t apr_procattr_create (apr_procattr_t **new_attr, apr_pool_t *cont)
   //创建并初始化新进程的属性, new_attr 是返回的结果， cont是要使用的内存池
   //Create and initialize a new procattr variable
2.

typedef enum {
    APR_SHELLCMD,           /**< use the shell to invoke the program */
    APR_PROGRAM,            /**< invoke the program directly, no copied env */
    APR_PROGRAM_ENV,        /**< invoke the program, replicating our environment */
    APR_PROGRAM_PATH,       /**< find program on PATH, use our environment */
    APR_SHELLCMD_ENV        /**< use the shell to invoke the program,
                             *   replicating our environment
                             */
} apr_cmdtype_e;

apr_status_t apr_procattr_cmdtype_set(apr_procattr_t*attr, apr_cmdtype_e cmd);

// Set what type of command the child process will call.

3. apr_status_t apr_procattr_error_check_set（apr_procattr_t * attr, apr_int32_t chk ）

//Specify that apr_proc_create() should do whatever it can to report failures to the caller of apr_proc_create(), rather than find out in the child.

4. apr_status_t apr_procattr_user_set( apr_procattr_t * attr, const char * username, const char * password )

// Set the username used for running process

5. apr_status_t apr_procattr_group_set (apr_procattr_t *attr, const char *groupname)

//Set the group used for running process

6. apr_status_t apr_procattr_dir_set (apr_procattr_t *attr, const char *dir)

//Set which directory the child process should start executing in.

7. apr_status_t apr_proc_create (apr_proc_t *new_proc, const char *progname, const char *const *args, const char *const *env, apr_procattr_t *attr, apr_pool_t *pool)

//Create a new process and execute a new program within that process.

8. apr_status_t apr_proc_detach (int daemonize)

//Detach the process from the controlling terminal.

9. apr_status_t apr_proc_kill (apr_proc_t *proc, int sig)

//Terminate a process.

10. apr_status_t apr_proc_wait (apr_proc_t *proc, int *exitcode, apr_exit_why_e *exitwhy, apr_wait_how_e waithow)

//Wait for a child process to die

1. apr_status_t apr_threadattr_create (apr_threadattr_t **new_attr, apr_pool_t *cont)

// Create and initialize a new threadattr variable

2. apr_status_t apr_threadattr_stacksize_set (apr_threadattr_t *attr, apr_size_t stacksize)

// Set the stack size of newly created threads.

3. apr_status_t apr_thread_detach (apr_thread_t *thd)

// detach a thread

4. apr_status_t apr_thread_join (apr_status_t *retval, apr_thread_t *thd)

// block until the desired thread stops executing.

pipe 接口：

详见：http://dev.ariel-networks.com/apr/apr-tutorial/html/apr-tutorial-15.html

1. APR_DECLARE(apr_status_t) apr_procattr_io_set(apr_procattr_t *attr, apr_int32_t in, apr_int32_t out, apr_int32_t err);

//设置进程属性的标准intput/output/error 属性

Functions for manipulating the environment :

1. apr_status_t 　apr_env_get (char **value, const char *envvar, apr_pool_t *pool)

//Get the value of an environment variable

Network Routines :

１.　apr_status_t 　apr_socket_create (apr_socket_t **new_sock, int family, int type, int protocol, apr_pool_t *cont)

// Create a socket.

2. apr_status_t 　apr_socket_connect (apr_socket_t *sock, apr_sockaddr_t *sa)

Issue a connection request to a socket either on the same machine or a different one.

3. apr_status_t 　apr_socket_bind (apr_socket_t *sock, apr_sockaddr_t *sa)

// Bind the socket to its associated port

4. apr_status_t 　apr_socket_listen (apr_socket_t *sock, apr_int32_t backlog)

// Listen to a bound socket for connections.

5. apr_status_t 　apr_socket_accept (apr_socket_t **new_sock, apr_socket_t *sock, apr_pool_t *connection_pool)

// Accept a new connection request

6. apr_status_t 　apr_socket_send (apr_socket_t *sock, const char *buf, apr_size_t *len)

//Send data over a network.

7. apr_status_t 　apr_socket_recv (apr_socket_t *sock, char *buf, apr_size_t *len)

// Read data from a network.

8. apr_status_t apr_socket_opt_set (apr_socket_t *sock, apr_int32_t opt, apr_int32_t on)

//Setup socket options for the specified socket

9. apr_status_t apr_socket_timeout_set (apr_socket_t *sock, apr_interval_time_t t)

// Setup socket timeout for the specified socket

10. apr_status_t apr_sockaddr_info_get (apr_sockaddr_t **sa, const char *hostname, apr_int32_t family, apr_port_t port, apr_int32_t flags, apr_pool_t *p)

// Create apr_sockaddr_t from hostname, address family, and port.

11. apr_status_t apr_socket_addr_get (apr_sockaddr_t **sa, apr_interface_e which, apr_socket_t *sock)

//Return an address associated with a socket; either the address to which the socket is bound locally or the the address of the peer to which the socket is connected.

12. apr_status_t apr_sockaddr_ip_get (char **addr, apr_sockaddr_t *sockaddr)

// Return the IP address (in numeric address string format) in an APR socket address. APR will allocate storage for the IP address string from the pool of the apr_sockaddr_t.

13. apr_status_t 　apr_socket_close (apr_socket_t *thesocket)

// Close a socket.

14. apr_status_t apr_socket_shutdown (apr_socket_t *thesocket, apr_shutdown_how_e how)

// Shutdown either reading, writing, or both sides of a socket.

Command Argument Parsing :

1. apr_status_t apr_getopt_init (apr_getopt_t **os, apr_pool_t *cont, int argc, const char *const *argv)

// Initialize the arguments for parsing by apr_getopt().

Parameters:

os	The options structure created for apr_getopt()
cont	The pool to operate on
argc	The number of arguments to parse
argv	The array of arguments to parse

2. apr_status_t apr_getopt (apr_getopt_t *os, const char *opts, char *option_ch, const char **option_arg)

// Parse the options initialized by apr_getopt_init().

3. apr_status_t apr_getopt_long (apr_getopt_t *os, const apr_getopt_option_t *opts, int *option_ch, const char **option_arg)

处理长参数，以--开头，短参数以- 开头的参数选项

Error Codes :

1. char * apr_strerror (apr_status_t statcode, char *buf, apr_size_t bufsize)

// Return a human readable string describing the specified error.

User and Group ID Services :

1. apr_status_t apr_uid_get (apr_uid_t *userid, apr_gid_t *groupid, const char *username, apr_pool_t *p)

// Get the userid (and groupid) for the specified username

Atomic Operations

1. apr_status_t apr_atomic_init (apr_pool_t *p)

初始化原子操作

Hash Tables

1. typedef struct apr_hash_t apr_hash_t

apr hash table 的类型定义

2. apr_hash_t * apr_hash_make (apr_pool_t *pool)

创建一个hash table, 参数pool 是给这个hash table 内配内存的地址池

对于apr_hash_make而言，它的主要的工作就是创建apr_hash_t结构，并对其中的成员进行初始化，其中哈希元素的个数被初始化为16个，同时使用默认的哈希算法apr_hashfunc_default，而apr_hash_make_custom则使用自定义的哈希函数hash_func。

3. apr_hash_index_t * apr_hash_first (apr_pool_t *p, apr_hash_t *ht)

开始迭代哈希表中的条目。

4. apr_hash_index_t * apr_hash_next (apr_hash_index_t *hi)

Continue iterating over the entries in a hash table.

5. void * apr_hash_this_val (apr_hash_index_t *hi)

Get the current entry's value from the iteration state.

6. void apr_hash_set (apr_hash_t *ht, const void *key, apr_ssize_t klen, const void *val)

设置hash table 中key 对应的value,

如果val = null , 则删除该hash , 但是hash key 会一直存在，直到这个hash table 的地址池被回收

7. void * apr_hash_get (apr_hash_t *ht, const void *key, apr_ssize_t klen)

在哈希表中查找与键关联的值

Signal Handling

1. apr_sigfunc_t * apr_signal (int signo, apr_sigfunc_t *func)

Set the signal handler function for a given signal

String routines

1. char* apr_pstrdup (apr_pool_t *p, const char *s)

将字符串复制到从池中分配的内存中