From: franklahm Date: Tue, 5 Jan 2010 19:05:52 +0000 (+0000) Subject: More doxygen style API documentation X-Git-Tag: branch-dircache-rewrite-start~30 X-Git-Url: https://arthur.barton.de/gitweb/?p=netatalk.git;a=commitdiff_plain;h=458d23f49dee93c7fca0ce757bed6cc11b5ea1ac More doxygen style API documentation --- diff --git a/include/atalk/util.h b/include/atalk/util.h index 52c56280..c03fe311 100644 --- a/include/atalk/util.h +++ b/include/atalk/util.h @@ -1,5 +1,15 @@ /* - * $Id: util.h,v 1.17 2010-01-05 13:48:47 franklahm Exp $ + * $Id: util.h,v 1.18 2010-01-05 19:05:52 franklahm Exp $ + */ + +/*! + * @file + * Netatalk utility functions + * + * Utility functions for these areas: \n + * * sockets \n + * * locking \n + * * misc UNIX function wrappers, eg for getcwd */ #ifndef _ATALK_UTIL_H @@ -88,49 +98,7 @@ extern void *mod_symbol (void *, const char *); * locking.c ******************************************************************/ -/* - * Function: lock_reg - * - * Purpose: lock a file with fctnl - * - * Arguments: - * - * fd (r) File descriptor - * cmd (r) cmd to fcntl, only F_SETLK is usable here - * type (r) F_RDLCK, F_WRLCK, F_UNLCK - * offset (r) byte offset relative to l_whence - * whence (r) SEEK_SET, SEEK_CUR, SEEK_END - * len (r) no. of bytes (0 means to EOF) - * - * Returns: 0 on success, -1 on failure - * fcntl return value and errno - * - * Effects: - * - * Function called by macros to ease locking. - */ extern int lock_reg(int fd, int cmd, int type, off_t offest, int whence, off_t len); - -/* - * Macros: read_lock, write_lock, un_lock - * - * Purpose: lock and unlock files - * - * Arguments: - * - * fd (r) File descriptor - * offset (r) byte offset relative to l_whence - * whence (r) SEEK_SET, SEEK_CUR, SEEK_END - * len (r) no. of bytes (0 means to EOF) - * - * Returns: 0 on success, -1 on failure - * fcntl return value and errno - * - * Effects: - * - * Nice locking macros. - */ - #define read_lock(fd, offset, whence, len) \ lock_reg((fd), F_SETLK, F_RDLCK, (offset), (whence), (len)) #define write_lock(fd, offset, whence, len) \ @@ -138,112 +106,20 @@ extern int lock_reg(int fd, int cmd, int type, off_t offest, int whence, off_t l #define unlock(fd, offset, whence, len) \ lock_reg((fd), F_SETLK, F_UNLCK, (offset), (whence), (len)) -#endif - /****************************************************************** * socket.c ******************************************************************/ -/* - * Function: setnonblock - * - * Purpose: set or unset non-blocking IO on a fd - * - * Arguments: - * - * fd (r) File descriptor - * cmd (r) 0: disable non-blocking IO, ie block - * <>0: enable non-blocking IO - * - * Returns: 0 on success, -1 on failure - * - * Effects: - * - * fd's file flags. - */ extern int setnonblock(int fd, int cmd); - -/* - * Function: getip_string - * - * Purpose: convert an IPv4 or IPv6 address to a static string using inet_ntop - * - * Arguments: - * - * sa (r) pointer to an struct sockaddr - * - * Returns: pointer to a static string cotaining the converted address as string. - * On error pointers to "0.0.0.0" or "::0" are returned. - * - * Effects: - * - * IPv6 mapped IPv4 addresses are returned as IPv4 addreses eg - * ::ffff:10.0.0.0 is returned as "10.0.0.0". - */ extern const char *getip_string(const struct sockaddr *sa); - -/* - * Function: getip_string - * - * Purpose: return port number from struct sockaddr - * - * Arguments: - * - * sa (r) pointer to an struct sockaddr - * - * Returns: port as unsigned int - * - * Effects: none. - */ extern unsigned int getip_port(const struct sockaddr *sa); - -/* - * Function: apply_ip_mask - * - * Purpose: apply netmask to IP (v4 or v6) - * - * Arguments: - * - * ai (rw) pointer to an struct sockaddr - * mask (r) number of maskbits - * - * Returns: void - * - * Effects: - * - * Modifies IP address in sa->sin[6]_addr-s[6]_addr. The caller is responsible - * for passing a value for mask that is sensible to the passed address, - * eg 0 <= mask <= 32 for IPv4 or 0<= mask <= 128 for IPv6. mask > 32 for - * IPv4 is treated as mask = 32, mask > 128 is set to 128 for IPv6. - */ extern void apply_ip_mask(struct sockaddr *ai, int maskbits); - -/* - * Function: compare_ip - * - * Purpose: Compare IP addresses for equality - * - * Arguments: - * - * sa1 (r) pointer to an struct sockaddr - * sa2 (r) pointer to an struct sockaddr - * - * Returns: Addresses are converted to strings and compared with strcmp and - * the result of strcmp is returned. - * - * Effects: - * - * IPv6 mapped IPv4 addresses are treated as IPv4 addresses. - */ extern int compare_ip(const struct sockaddr *sa1, const struct sockaddr *sa2); /****************************************************************** * unix.c *****************************************************************/ -/*! - * @brief get cwd in static buffer - * - * @returns pointer to path or pointer to error messages on error - */ extern const char *getcwdpath(void); + +#endif /* _ATALK_UTIL_H */ diff --git a/libatalk/util/locking.c b/libatalk/util/locking.c index b7ffd766..2d5b913e 100644 --- a/libatalk/util/locking.c +++ b/libatalk/util/locking.c @@ -1,5 +1,5 @@ /* - $Id: locking.c,v 1.3 2009-10-22 12:35:39 franklahm Exp $ + $Id: locking.c,v 1.4 2010-01-05 19:05:52 franklahm Exp $ Copyright (c) 2009 Frank Lahm This program is free software; you can redistribute it and/or modify @@ -13,6 +13,11 @@ GNU General Public License for more details. */ +/*! + * @file + * Netatalk utility functions + */ + #ifdef HAVE_CONFIG_H #include "config.h" #endif /* HAVE_CONFIG_H */ @@ -21,25 +26,62 @@ #include #include -/* - * Function: lock_reg +/*! + * @def read_lock(fd, offset, whence, len) + * @brief place read lock on file + * + * @param fd (r) File descriptor + * @param offset (r) byte offset relative to l_whence + * @param whence (r) SEEK_SET, SEEK_CUR, SEEK_END + * @param len (r) no. of bytes (0 means to EOF) + * + * @returns 0 on success, -1 on failure with + * fcntl return value and errno + */ + +/*! + * @def write_lock(fd, offset, whence, len) + * @brief place write lock on file * - * Purpose: lock a file with fctnl + * @param fd (r) File descriptor + * @param offset (r) byte offset relative to l_whence + * @param whence (r) SEEK_SET, SEEK_CUR, SEEK_END + * @param len (r) no. of bytes (0 means to EOF) * - * Arguments: + * @returns 0 on success, -1 on failure with + * fcntl return value and errno + */ + +/*! + * @def unlock(fd, offset, whence, len) + * @brief unlock a file + * + * @param fd (r) File descriptor + * @param offset (r) byte offset relative to l_whence + * @param whence (r) SEEK_SET, SEEK_CUR, SEEK_END + * @param len (r) no. of bytes (0 means to EOF) + * + * @returns 0 on success, -1 on failure with + * fcntl return value and errno + */ + +/*! + * @brief lock a file with fctnl * - * fd (r) File descriptor - * cmd (r) cmd to fcntl, only F_SETLK is usable here - * type (r) F_RDLCK, F_WRLCK, F_UNLCK - * offset (r) byte offset relative to l_whence - * whence (r) SEEK_SET, SEEK_CUR, SEEK_END - * len (r) no. of bytes (0 means to EOF) + * This function is called via the macros: + * read_lock, write_lock, un_lock * - * Returns: fcntl return value + * @param fd (r) File descriptor + * @param cmd (r) cmd to fcntl, only F_SETLK is usable here + * @param type (r) F_RDLCK, F_WRLCK, F_UNLCK + * @param offset (r) byte offset relative to l_whence + * @param whence (r) SEEK_SET, SEEK_CUR, SEEK_END + * @param len (r) no. of bytes (0 means to EOF) * - * Effects: + * @returns 0 on success, -1 on failure with + * fcntl return value and errno * - * Function called by macros {read|write|un]_lock to ease locking. + * @sa read_lock, write_lock, unlock */ int lock_reg(int fd, int cmd, int type, off_t offset, int whence, off_t len) { diff --git a/libatalk/util/socket.c b/libatalk/util/socket.c index 770c93fe..af41825f 100644 --- a/libatalk/util/socket.c +++ b/libatalk/util/socket.c @@ -1,5 +1,5 @@ /* - $Id: socket.c,v 1.5 2009-11-23 19:04:15 franklahm Exp $ + $Id: socket.c,v 1.6 2010-01-05 19:05:52 franklahm Exp $ Copyright (c) 2009 Frank Lahm This program is free software; you can redistribute it and/or modify @@ -13,6 +13,11 @@ GNU General Public License for more details. */ +/*! + * @file + * Netatalk utility functions + */ + #ifdef HAVE_CONFIG_H #include "config.h" #endif /* HAVE_CONFIG_H */ @@ -28,6 +33,15 @@ static char ipv4mapprefix[] = {0,0,0,0,0,0,0,0,0,0,0xff,0xff}; +/*! + * @brief set or unset non-blocking IO on a fd + * + * @param fd (r) File descriptor + * @param cmd (r) 0: disable non-blocking IO, ie block\n + * <>0: enable non-blocking IO + * + * @returns 0 on success, -1 on failure + */ int setnonblock(int fd, int cmd) { int ofdflags; @@ -48,6 +62,17 @@ int setnonblock(int fd, int cmd) return 0; } +/*! + * @brief convert an IPv4 or IPv6 address to a static string using inet_ntop + * + * IPv6 mapped IPv4 addresses are returned as IPv4 addreses eg + * ::ffff:10.0.0.0 is returned as "10.0.0.0". + * + * @param sa (r) pointer to an struct sockaddr + * + * @returns pointer to a static string cotaining the converted address as string.\n + * On error pointers to "0.0.0.0" or "::0" are returned. + */ const char *getip_string(const struct sockaddr *sa) { static char ip4[INET_ADDRSTRLEN]; @@ -78,6 +103,13 @@ const char *getip_string(const struct sockaddr *sa) /* We never get here */ } +/*! + * @brief return port number from struct sockaddr + * + * @param sa (r) pointer to an struct sockaddr + * + * @returns port as unsigned int + */ unsigned int getip_port(const struct sockaddr *sa) { if (sa->sa_family == AF_INET) { /* IPv4 */ @@ -91,6 +123,17 @@ unsigned int getip_port(const struct sockaddr *sa) /* We never get here */ } +/*! + * @brief apply netmask to IP (v4 or v6) + * + * Modifies IP address in sa->sin[6]_addr-s[6]_addr. The caller is responsible + * for passing a value for mask that is sensible to the passed address, + * eg 0 <= mask <= 32 for IPv4 or 0<= mask <= 128 for IPv6. mask > 32 for + * IPv4 is treated as mask = 32, mask > 128 is set to 128 for IPv6. + * + * @param ai (rw) pointer to an struct sockaddr + * @parma mask (r) number of maskbits + */ void apply_ip_mask(struct sockaddr *sa, uint32_t mask) { @@ -132,6 +175,17 @@ void apply_ip_mask(struct sockaddr *sa, uint32_t mask) } } +/*! + * @brief compare IP addresses for equality + * + * @param sa1 (r) pointer to an struct sockaddr + * @param sa2 (r) pointer to an struct sockaddr + * + * @returns Addresses are converted to strings and compared with strcmp and + * the result of strcmp is returned. + * + * @note IPv6 mapped IPv4 addresses are treated as IPv4 addresses. + */ int compare_ip(const struct sockaddr *sa1, const struct sockaddr *sa2) { int ret; diff --git a/libatalk/util/unix.c b/libatalk/util/unix.c index beb9ab5a..c54de60e 100644 --- a/libatalk/util/unix.c +++ b/libatalk/util/unix.c @@ -1,5 +1,5 @@ /* - $Id: unix.c,v 1.1 2010-01-05 13:48:47 franklahm Exp $ + $Id: unix.c,v 1.2 2010-01-05 19:05:52 franklahm Exp $ Copyright (c) 2010 Frank Lahm This program is free software; you can redistribute it and/or modify @@ -13,6 +13,11 @@ GNU General Public License for more details. */ +/*! + * @file + * Netatalk utility functions + */ + #ifdef HAVE_CONFIG_H #include "config.h" #endif /* HAVE_CONFIG_H */ @@ -36,6 +41,11 @@ #include #include +/*! + * @brief get cwd in static buffer + * + * @returns pointer to path or pointer to error messages on error + */ extern const char *getcwdpath(void) { static char cwd[MAXPATHLEN + 1];