From: Martin Ling Date: Sun, 3 Nov 2013 22:30:46 +0000 (+0000) Subject: Update documentation. X-Git-Tag: libserialport-0.1.0~146 X-Git-Url: https://sigrok.org/gitweb/?a=commitdiff_plain;h=016193288478dd146b8aec2f8d14945ccd4bd2aa;hp=e3b2f7a4e3c1315d51d6a91eec7dde44ec0a623b;p=libserialport.git Update documentation. --- diff --git a/README b/README index 50cb7b2..2bd7fea 100644 --- a/README +++ b/README @@ -67,7 +67,7 @@ port. This structure is obtained from the array returned by sp_list_ports(). All functions can return only three possible error values. SP_ERR_ARG indicates the function was called with invalid arguments. SP_ERR_FAIL indicates that the OS reported a failure. SP_ERR_MEM indicates that a memory allocation failed. -Aoth these error values are negative. +All of these error values are negative. When SP_ERR_FAIL is returned, an error code or string description of the error can be obtained by calling sp_last_error_code() or sp_last_error_message(). The @@ -82,15 +82,36 @@ The available functions are as follows: Enumeration ----------- -struct sp_port **sp_list_ports(); +int sp_get_port_by_name(const char *portname, struct sp_port **port_ptr); - Lists the serial ports available on the system. The value returned is an array - of pointers to sp_port structures, terminated by a NULL. It should be freed after - use by calling sp_free_port_list(). + Obtains a pointer to a new sp_port structure representing the named port. The + user should allocate a variable of type "struct sp_port *" and pass a pointer + to this to receive the result. + + Returns: SP_OK on success, SP_ERR_FAIL on failure, SP_ERR_MEM on allocation failure, + or SP_ERR_ARG if an invalid pointer is passed. If any error is returned, + the value pointed to by port_ptr will be set to NULL. + +void sp_free_port(struct sp_port *port); + + Frees a port structure obtained from sp_get_port_by_name(). + +int sp_list_ports(struct sp_port ***list_ptr); + + Lists the serial ports available on the system. The result obtained is an + array of pointers to sp_port structures, terminated by a NULL. The user should + allocate a variable of type "struct sp_port **" and pass a pointer to this to + receive the result. + + The result should be freed after use by calling sp_free_port_list(). + + Returns: SP_OK on success, SP_ERR_FAIL on failure, SP_ERR_MEM on allocation failure, + or SP_ERR_ARG if an invalid pointer is passed. If any error is returned, + the value pointed to by list_ptr will be set to NULL. void sp_free_port_list(struct sp_port **list); - Frees the data structure returned by sp_list_ports(). + Frees a port list obtained from sp_list_ports(). Opening and closing ports ------------------------- @@ -106,7 +127,7 @@ int sp_open(struct sp_port *port, int flags); flags are: SP_MODE_RDWR, SP_MODE_RDONLY, and SP_MODE_NONBLOCK. Returns: SP_OK on success, SP_ERR_FAIL on failure, or SP_ERR_ARG - if an invalid port or name is passed. + if an invalid port is passed. int sp_close(struct sp_port *port);