Changeset 99758 in vbox for trunk/src/VBox/Runtime/common
- Timestamp:
- May 11, 2023 9:37:59 PM (21 months ago)
- Location:
- trunk/src/VBox/Runtime/common
- Files:
-
- 21 edited
-
checksum/crc64.cpp (modified) (4 diffs)
-
checksum/manifest2.cpp (modified) (10 diffs)
-
checksum/manifest3.cpp (modified) (4 diffs)
-
dbg/dbgas.cpp (modified) (23 diffs)
-
ldr/ldrEx.cpp (modified) (4 diffs)
-
ldr/ldrNative.cpp (modified) (3 diffs)
-
log/log.cpp (modified) (27 diffs)
-
misc/inifile.cpp (modified) (5 diffs)
-
misc/semspingpong.cpp (modified) (6 diffs)
-
misc/thread.cpp (modified) (22 diffs)
-
path/RTPathAbsDup.cpp (modified) (1 diff)
-
path/RTPathParentLength.cpp (modified) (1 diff)
-
path/RTPathParseSimple.cpp (modified) (1 diff)
-
path/RTPathRealDup.cpp (modified) (1 diff)
-
path/comparepaths.cpp (modified) (2 diffs)
-
rand/rand.cpp (modified) (1 diff)
-
string/strformat.cpp (modified) (2 diffs)
-
string/strspace.cpp (modified) (6 diffs)
-
string/strtonum.cpp (modified) (24 diffs)
-
string/utf-8-case.cpp (modified) (2 diffs)
-
time/time.cpp (modified) (14 diffs)
Legend:
- Unmodified
- Added
- Removed
-
trunk/src/VBox/Runtime/common/checksum/crc64.cpp
r98103 r99758 161 161 162 162 163 /**164 * Calculate CRC64 for a memory block.165 *166 * @returns CRC64 for the memory block.167 * @param pv Pointer to the memory block.168 * @param cb Size of the memory block in bytes.169 */170 163 RTDECL(uint64_t) RTCrc64(const void *pv, size_t cb) 171 164 { … … 179 172 180 173 181 /**182 * Start a multiblock CRC64 calculation.183 *184 * @returns Start CRC64.185 */186 174 RTDECL(uint64_t) RTCrc64Start(void) 187 175 { … … 191 179 192 180 193 /**194 * Processes a multiblock of a CRC64 calculation.195 *196 * @returns Intermediate CRC64 value.197 * @param uCRC64 Current CRC64 intermediate value.198 * @param pv The data block to process.199 * @param cb The size of the data block in bytes.200 */201 181 RTDECL(uint64_t) RTCrc64Process(uint64_t uCRC64, const void *pv, size_t cb) 202 182 { … … 209 189 210 190 211 /**212 * Complete a multiblock CRC64 calculation.213 *214 * @returns CRC64 value.215 * @param uCRC64 Current CRC64 intermediate value.216 */217 191 RTDECL(uint64_t) RTCrc64Finish(uint64_t uCRC64) 218 192 { -
trunk/src/VBox/Runtime/common/checksum/manifest2.cpp
r98103 r99758 192 192 193 193 194 /**195 * Creates an empty manifest.196 *197 * @returns IPRT status code.198 * @param fFlags Flags, MBZ.199 * @param phManifest Where to return the handle to the manifest.200 */201 194 RTDECL(int) RTManifestCreate(uint32_t fFlags, PRTMANIFEST phManifest) 202 195 { … … 223 216 } 224 217 225 /** 226 * Retains a reference to the manifest handle. 227 * 228 * @returns The new reference count, UINT32_MAX if the handle is invalid. 229 * @param hManifest The handle to retain. 230 */ 218 231 219 RTDECL(uint32_t) RTManifestRetain(RTMANIFEST hManifest) 232 220 { … … 268 256 269 257 270 /**271 * Releases a reference to the manifest handle.272 *273 * @returns The new reference count, 0 if free. UINT32_MAX is returned if the274 * handle is invalid.275 * @param hManifest The handle to release.276 * NIL is quietly ignored (returns 0).277 */278 258 RTDECL(uint32_t) RTManifestRelease(RTMANIFEST hManifest) 279 259 { … … 298 278 299 279 300 /**301 * Creates a duplicate of the specified manifest.302 *303 * @returns IPRT status code304 * @param hManifestSrc The manifest to clone.305 * @param phManifestDst Where to store the handle to the duplicate.306 */307 280 RTDECL(int) RTManifestDup(RTMANIFEST hManifestSrc, PRTMANIFEST phManifestDst) 308 281 { … … 740 713 741 714 742 /**743 * Sets a manifest attribute.744 *745 * @returns IPRT status code.746 * @param hManifest The manifest handle.747 * @param pszAttr The attribute name. If this already exists,748 * its value will be replaced.749 * @param pszValue The value string.750 * @param fType The attribute type, pass751 * RTMANIFEST_ATTR_UNKNOWN if not known.752 */753 715 RTDECL(int) RTManifestSetAttr(RTMANIFEST hManifest, const char *pszAttr, const char *pszValue, uint32_t fType) 754 716 { … … 784 746 785 747 786 /**787 * Unsets (removes) a manifest attribute if it exists.788 *789 * @returns IPRT status code.790 * @retval VWRN_NOT_FOUND if not found.791 *792 * @param hManifest The manifest handle.793 * @param pszAttr The attribute name.794 */795 748 RTDECL(int) RTManifestUnsetAttr(RTMANIFEST hManifest, const char *pszAttr) 796 749 { … … 1041 994 1042 995 1043 /**1044 * Sets an attribute of a manifest entry.1045 *1046 * @returns IPRT status code.1047 * @param hManifest The manifest handle.1048 * @param pszEntry The entry name. This will automatically be1049 * added if there was no previous call to1050 * RTManifestEntryAdd for this name. See1051 * RTManifestEntryAdd for the entry name rules.1052 * @param pszAttr The attribute name. If this already exists,1053 * its value will be replaced.1054 * @param pszValue The value string.1055 * @param fType The attribute type, pass1056 * RTMANIFEST_ATTR_UNKNOWN if not known.1057 */1058 996 RTDECL(int) RTManifestEntrySetAttr(RTMANIFEST hManifest, const char *pszEntry, const char *pszAttr, 1059 997 const char *pszValue, uint32_t fType) … … 1107 1045 1108 1046 1109 /**1110 * Unsets (removes) an attribute of a manifest entry if they both exist.1111 *1112 * @returns IPRT status code.1113 * @retval VWRN_NOT_FOUND if not found.1114 *1115 * @param hManifest The manifest handle.1116 * @param pszEntry The entry name.1117 * @param pszAttr The attribute name.1118 */1119 1047 RTDECL(int) RTManifestEntryUnsetAttr(RTMANIFEST hManifest, const char *pszEntry, const char *pszAttr) 1120 1048 { … … 1167 1095 1168 1096 1169 /**1170 * Adds a new entry to a manifest.1171 *1172 * The entry name rules:1173 * - The entry name can contain any character defined by unicode, except1174 * control characters, ':', '(' and ')'. The exceptions are mainly there1175 * because of uncertainty around how various formats handles these.1176 * - It is considered case sensitive.1177 * - Forward (unix) and backward (dos) slashes are considered path1178 * separators and converted to forward slashes.1179 *1180 * @returns IPRT status code.1181 * @retval VWRN_ALREADY_EXISTS if the entry already exists.1182 *1183 * @param hManifest The manifest handle.1184 * @param pszEntry The entry name (UTF-8).1185 *1186 * @remarks Some manifest formats will not be able to store an entry without1187 * any attributes. So, this is just here in case it comes in handy1188 * when dealing with formats which can.1189 */1190 1097 RTDECL(int) RTManifestEntryAdd(RTMANIFEST hManifest, const char *pszEntry) 1191 1098 { … … 1239 1146 1240 1147 1241 /**1242 * Removes an entry.1243 *1244 * @returns IPRT status code.1245 * @param hManifest The manifest handle.1246 * @param pszEntry The entry name.1247 */1248 1148 RTDECL(int) RTManifestEntryRemove(RTMANIFEST hManifest, const char *pszEntry) 1249 1149 { -
trunk/src/VBox/Runtime/common/checksum/manifest3.cpp
r98103 r99758 533 533 534 534 535 /**536 * Add an entry for an I/O stream using a passthru stream.537 *538 * The passthru I/O stream will hash all the data read from or written to the539 * stream and automatically add an entry to the manifest with the desired540 * attributes when it is released. Alternatively one can call541 * RTManifestPtIosAddEntryNow() to have more control over exactly when this542 * action is performed and which status it yields.543 *544 * @returns IPRT status code.545 * @param hManifest The manifest to add the entry to.546 * @param hVfsIos The I/O stream to pass thru to/from.547 * @param pszEntry The entry name.548 * @param fAttrs The attributes to create for this stream.549 * @param fReadOrWrite Whether it's a read or write I/O stream.550 * @param phVfsIosPassthru Where to return the new handle.551 */552 535 RTDECL(int) RTManifestEntryAddPassthruIoStream(RTMANIFEST hManifest, RTVFSIOSTREAM hVfsIos, const char *pszEntry, 553 536 uint32_t fAttrs, bool fReadOrWrite, PRTVFSIOSTREAM phVfsIosPassthru) … … 602 585 603 586 604 /**605 * Adds the entry to the manifest right now.606 *607 * @returns IPRT status code.608 * @param hVfsPtIos The manifest passthru I/O stream returned by609 * RTManifestEntryAddPassthruIoStream().610 */611 587 RTDECL(int) RTManifestPtIosAddEntryNow(RTVFSIOSTREAM hVfsPtIos) 612 588 { … … 621 597 622 598 623 /**624 * Checks if the give I/O stream is a manifest passthru instance or not.625 *626 * @returns true if it's a manifest passthru I/O stream, false if not.627 * @param hVfsPtIos Possible the manifest passthru I/O stream handle.628 */629 599 RTDECL(bool) RTManifestPtIosIsInstanceOf(RTVFSIOSTREAM hVfsPtIos) 630 600 { … … 639 609 640 610 641 /**642 * Adds an entry for a file with the specified set of attributes.643 *644 * @returns IPRT status code.645 *646 * @param hManifest The manifest handle.647 * @param hVfsIos The I/O stream handle of the entry. This will648 * be processed to its end on successful return.649 * (Must be positioned at the start to get650 * the expected results.)651 * @param pszEntry The entry name.652 * @param fAttrs The attributes to create for this stream.653 */654 611 RTDECL(int) RTManifestEntryAddIoStream(RTMANIFEST hManifest, RTVFSIOSTREAM hVfsIos, const char *pszEntry, uint32_t fAttrs) 655 612 { -
trunk/src/VBox/Runtime/common/dbg/dbgas.cpp
r98103 r99758 185 185 186 186 187 /**188 * Creates an empty address space.189 *190 * @returns IPRT status code.191 *192 * @param phDbgAs Where to store the address space handle on success.193 * @param FirstAddr The first address in the address space.194 * @param LastAddr The last address in the address space.195 * @param pszName The name of the address space.196 */197 187 RTDECL(int) RTDbgAsCreate(PRTDBGAS phDbgAs, RTUINTPTR FirstAddr, RTUINTPTR LastAddr, const char *pszName) 198 188 { … … 238 228 239 229 240 /**241 * Variant of RTDbgAsCreate that takes a name format string.242 *243 * @returns IPRT status code.244 *245 * @param phDbgAs Where to store the address space handle on success.246 * @param FirstAddr The first address in the address space.247 * @param LastAddr The last address in the address space.248 * @param pszNameFmt The name format of the address space.249 * @param va Format arguments.250 */251 230 RTDECL(int) RTDbgAsCreateV(PRTDBGAS phDbgAs, RTUINTPTR FirstAddr, RTUINTPTR LastAddr, const char *pszNameFmt, va_list va) 252 231 { … … 266 245 267 246 268 /**269 * Variant of RTDbgAsCreate that takes a name format string.270 *271 * @returns IPRT status code.272 *273 * @param phDbgAs Where to store the address space handle on success.274 * @param FirstAddr The first address in the address space.275 * @param LastAddr The last address in the address space.276 * @param pszNameFmt The name format of the address space.277 * @param ... Format arguments.278 */279 247 RTDECL(int) RTDbgAsCreateF(PRTDBGAS phDbgAs, RTUINTPTR FirstAddr, RTUINTPTR LastAddr, const char *pszNameFmt, ...) 280 248 { … … 361 329 362 330 363 /**364 * Retains another reference to the address space.365 *366 * @returns New reference count, UINT32_MAX on invalid handle (asserted).367 *368 * @param hDbgAs The address space handle.369 *370 * @remarks Will not take any locks.371 */372 331 RTDECL(uint32_t) RTDbgAsRetain(RTDBGAS hDbgAs) 373 332 { … … 379 338 380 339 381 /**382 * Release a reference to the address space.383 *384 * When the reference count reaches zero, the address space is destroyed.385 * That means unlinking all the modules it currently contains, potentially386 * causing some or all of them to be destroyed as they are managed by387 * reference counting.388 *389 * @returns New reference count, UINT32_MAX on invalid handle (asserted).390 *391 * @param hDbgAs The address space handle. The NIL handle is quietly392 * ignored and 0 is returned.393 *394 * @remarks Will not take any locks.395 */396 340 RTDECL(uint32_t) RTDbgAsRelease(RTDBGAS hDbgAs) 397 341 { … … 429 373 430 374 431 /**432 * Gets the name of an address space.433 *434 * @returns read only address space name.435 * NULL if hDbgAs is invalid.436 *437 * @param hDbgAs The address space handle.438 *439 * @remarks Will not take any locks.440 */441 375 RTDECL(const char *) RTDbgAsName(RTDBGAS hDbgAs) 442 376 { … … 448 382 449 383 450 /**451 * Gets the first address in an address space.452 *453 * @returns The address.454 * 0 if hDbgAs is invalid.455 *456 * @param hDbgAs The address space handle.457 *458 * @remarks Will not take any locks.459 */460 384 RTDECL(RTUINTPTR) RTDbgAsFirstAddr(RTDBGAS hDbgAs) 461 385 { … … 467 391 468 392 469 /**470 * Gets the last address in an address space.471 *472 * @returns The address.473 * 0 if hDbgAs is invalid.474 *475 * @param hDbgAs The address space handle.476 *477 * @remarks Will not take any locks.478 */479 393 RTDECL(RTUINTPTR) RTDbgAsLastAddr(RTDBGAS hDbgAs) 480 394 { … … 485 399 RT_EXPORT_SYMBOL(RTDbgAsLastAddr); 486 400 487 /** 488 * Gets the number of modules in the address space. 489 * 490 * This can be used together with RTDbgAsModuleByIndex 491 * to enumerate the modules. 492 * 493 * @returns The number of modules. 494 * 495 * @param hDbgAs The address space handle. 496 * 497 * @remarks Will not take any locks. 498 */ 401 499 402 RTDECL(uint32_t) RTDbgAsModuleCount(RTDBGAS hDbgAs) 500 403 { … … 650 553 651 554 652 /**653 * Links a module into the address space at the give address.654 *655 * The size of the mapping is determined using RTDbgModImageSize().656 *657 * @returns IPRT status code.658 * @retval VERR_OUT_OF_RANGE if the specified address will put the module659 * outside the address space.660 * @retval VERR_ADDRESS_CONFLICT if the mapping clashes with existing mappings.661 *662 * @param hDbgAs The address space handle.663 * @param hDbgMod The module handle of the module to be linked in.664 * @param ImageAddr The address to link the module at.665 * @param fFlags See RTDBGASLINK_FLAGS_*.666 */667 555 RTDECL(int) RTDbgAsModuleLink(RTDBGAS hDbgAs, RTDBGMOD hDbgMod, RTUINTPTR ImageAddr, uint32_t fFlags) 668 556 { … … 697 585 698 586 699 /**700 * Links a segment into the address space at the give address.701 *702 * The size of the mapping is determined using RTDbgModSegmentSize().703 *704 * @returns IPRT status code.705 * @retval VERR_OUT_OF_RANGE if the specified address will put the module706 * outside the address space.707 * @retval VERR_ADDRESS_CONFLICT if the mapping clashes with existing mappings.708 *709 * @param hDbgAs The address space handle.710 * @param hDbgMod The module handle.711 * @param iSeg The segment number (0-based) of the segment to be712 * linked in.713 * @param SegAddr The address to link the segment at.714 * @param fFlags See RTDBGASLINK_FLAGS_*.715 */716 587 RTDECL(int) RTDbgAsModuleLinkSeg(RTDBGAS hDbgAs, RTDBGMOD hDbgMod, RTDBGSEGIDX iSeg, RTUINTPTR SegAddr, uint32_t fFlags) 717 588 { … … 874 745 875 746 876 /**877 * Unlinks all the mappings of a module from the address space.878 *879 * @returns IPRT status code.880 * @retval VERR_NOT_FOUND if the module wasn't found.881 *882 * @param hDbgAs The address space handle.883 * @param hDbgMod The module handle of the module to be unlinked.884 */885 747 RTDECL(int) RTDbgAsModuleUnlink(RTDBGAS hDbgAs, RTDBGMOD hDbgMod) 886 748 { … … 914 776 915 777 916 /**917 * Unlinks the mapping at the specified address.918 *919 * @returns IPRT status code.920 * @retval VERR_NOT_FOUND if no module or segment is mapped at that address.921 *922 * @param hDbgAs The address space handle.923 * @param Addr The address within the mapping to be unlinked.924 */925 778 RTDECL(int) RTDbgAsModuleUnlinkByAddr(RTDBGAS hDbgAs, RTUINTPTR Addr) 926 779 { … … 950 803 951 804 952 /**953 * Get a the handle of a module in the address space by is index.954 *955 * @returns A retained handle to the specified module. The caller must release956 * the returned reference.957 * NIL_RTDBGMOD if invalid index or handle.958 *959 * @param hDbgAs The address space handle.960 * @param iModule The index of the module to get.961 *962 * @remarks The module indexes may change after calls to RTDbgAsModuleLink,963 * RTDbgAsModuleLinkSeg, RTDbgAsModuleUnlink and964 * RTDbgAsModuleUnlinkByAddr.965 */966 805 RTDECL(RTDBGMOD) RTDbgAsModuleByIndex(RTDBGAS hDbgAs, uint32_t iModule) 967 806 { … … 991 830 992 831 993 /**994 * Queries mapping module information by handle.995 *996 * @returns IPRT status code.997 * @retval VERR_NOT_FOUND if no mapping was found at the specified address.998 *999 * @param hDbgAs The address space handle.1000 * @param Addr Address within the mapping of the module or segment.1001 * @param phMod Where to the return the retained module handle.1002 * Optional.1003 * @param pAddr Where to return the base address of the mapping.1004 * Optional.1005 * @param piSeg Where to return the segment index. This is set to1006 * NIL if the entire module is mapped as a single1007 * mapping. Optional.1008 */1009 832 RTDECL(int) RTDbgAsModuleByAddr(RTDBGAS hDbgAs, RTUINTPTR Addr, PRTDBGMOD phMod, PRTUINTPTR pAddr, PRTDBGSEGIDX piSeg) 1010 833 { … … 1043 866 1044 867 1045 /**1046 * Queries mapping module information by name.1047 *1048 * @returns IPRT status code.1049 * @retval VERR_NOT_FOUND if no mapping was found at the specified address.1050 * @retval VERR_OUT_OF_RANGE if the name index was out of range.1051 *1052 * @param hDbgAs The address space handle.1053 * @param pszName The module name.1054 * @param iName There can be more than one module by the same name1055 * in an address space. This argument indicates which1056 * is meant. (0 based)1057 * @param phMod Where to the return the retained module handle.1058 */1059 868 RTDECL(int) RTDbgAsModuleByName(RTDBGAS hDbgAs, const char *pszName, uint32_t iName, PRTDBGMOD phMod) 1060 869 { … … 1098 907 1099 908 1100 /**1101 * Queries mapping information for a module given by index.1102 *1103 * @returns IRPT status code.1104 * @retval VERR_INVALID_HANDLE if hDbgAs is invalid.1105 * @retval VERR_OUT_OF_RANGE if the name index was out of range.1106 * @retval VINF_BUFFER_OVERFLOW if the array is too small and the returned1107 * information is incomplete.1108 *1109 * @param hDbgAs The address space handle.1110 * @param iModule The index of the module to get.1111 * @param paMappings Where to return the mapping information. The buffer1112 * size is given by *pcMappings.1113 * @param pcMappings IN: Size of the paMappings array. OUT: The number of1114 * entries returned.1115 * @param fFlags Flags for reserved for future use. MBZ.1116 *1117 * @remarks See remarks for RTDbgAsModuleByIndex regarding the volatility of the1118 * iModule parameter.1119 */1120 909 RTDECL(int) RTDbgAsModuleQueryMapByIndex(RTDBGAS hDbgAs, uint32_t iModule, PRTDBGASMAPINFO paMappings, uint32_t *pcMappings, uint32_t fFlags) 1121 910 { … … 1273 1062 1274 1063 1275 /**1276 * Adds a symbol to a module in the address space.1277 *1278 * @returns IPRT status code. See RTDbgModSymbolAdd for more specific ones.1279 * @retval VERR_INVALID_HANDLE if hDbgAs is invalid.1280 * @retval VERR_NOT_FOUND if no module was found at the specified address.1281 * @retval VERR_NOT_SUPPORTED if the module interpret doesn't support adding1282 * custom symbols.1283 *1284 * @param hDbgAs The address space handle.1285 * @param pszSymbol The symbol name.1286 * @param Addr The address of the symbol.1287 * @param cb The size of the symbol.1288 * @param fFlags Symbol flags, RTDBGSYMBOLADD_F_XXX.1289 * @param piOrdinal Where to return the symbol ordinal on success. If1290 * the interpreter doesn't do ordinals, this will be set to1291 * UINT32_MAX. Optional1292 */1293 1064 RTDECL(int) RTDbgAsSymbolAdd(RTDBGAS hDbgAs, const char *pszSymbol, RTUINTPTR Addr, RTUINTPTR cb, uint32_t fFlags, uint32_t *piOrdinal) 1294 1065 { … … 1346 1117 1347 1118 1348 /**1349 * Query a symbol by address.1350 *1351 * @returns IPRT status code. See RTDbgModSymbolAddr for more specific ones.1352 * @retval VERR_INVALID_HANDLE if hDbgAs is invalid.1353 * @retval VERR_NOT_FOUND if the address couldn't be mapped to a module.1354 * @retval VERR_INVALID_PARAMETER if incorrect flags.1355 *1356 * @param hDbgAs The address space handle.1357 * @param Addr The address which closest symbol is requested.1358 * @param fFlags Symbol search flags, see RTDBGSYMADDR_FLAGS_XXX.1359 * @param poffDisp Where to return the distance between the symbol and1360 * address. Optional.1361 * @param pSymbol Where to return the symbol info.1362 * @param phMod Where to return the module handle. Optional.1363 */1364 1119 RTDECL(int) RTDbgAsSymbolByAddr(RTDBGAS hDbgAs, RTUINTPTR Addr, uint32_t fFlags, 1365 1120 PRTINTPTR poffDisp, PRTDBGSYMBOL pSymbol, PRTDBGMOD phMod) … … 1439 1194 1440 1195 1441 /**1442 * Query a symbol by address.1443 *1444 * @returns IPRT status code. See RTDbgModSymbolAddrA for more specific ones.1445 * @retval VERR_INVALID_HANDLE if hDbgAs is invalid.1446 * @retval VERR_NOT_FOUND if the address couldn't be mapped to a module.1447 * @retval VERR_INVALID_PARAMETER if incorrect flags.1448 *1449 * @param hDbgAs The address space handle.1450 * @param Addr The address which closest symbol is requested.1451 * @param fFlags Symbol search flags, see RTDBGSYMADDR_FLAGS_XXX.1452 * @param poffDisp Where to return the distance between the symbol1453 * and address. Optional.1454 * @param ppSymInfo Where to return the pointer to the allocated symbol1455 * info. Always set. Free with RTDbgSymbolFree.1456 * @param phMod Where to return the module handle. Optional.1457 */1458 1196 RTDECL(int) RTDbgAsSymbolByAddrA(RTDBGAS hDbgAs, RTUINTPTR Addr, uint32_t fFlags, 1459 1197 PRTINTPTR poffDisp, PRTDBGSYMBOL *ppSymInfo, PRTDBGMOD phMod) … … 1558 1296 1559 1297 1560 /**1561 * Query a symbol by name.1562 *1563 * @returns IPRT status code.1564 * @retval VERR_SYMBOL_NOT_FOUND if not found.1565 *1566 * @param hDbgAs The address space handle.1567 * @param pszSymbol The symbol name. It is possible to limit the scope1568 * of the search by prefixing the symbol with a module1569 * name pattern followed by a bang (!) character.1570 * RTStrSimplePatternNMatch is used for the matching.1571 * @param pSymbol Where to return the symbol info.1572 * @param phMod Where to return the module handle. Optional.1573 */1574 1298 RTDECL(int) RTDbgAsSymbolByName(RTDBGAS hDbgAs, const char *pszSymbol, PRTDBGSYMBOL pSymbol, PRTDBGMOD phMod) 1575 1299 { … … 1634 1358 1635 1359 1636 /**1637 * Query a symbol by name, allocating the returned symbol structure.1638 *1639 * @returns IPRT status code.1640 * @retval VERR_SYMBOL_NOT_FOUND if not found.1641 *1642 * @param hDbgAs The address space handle.1643 * @param pszSymbol The symbol name. See RTDbgAsSymbolByName for more.1644 * @param ppSymbol Where to return the pointer to the allocated1645 * symbol info. Always set. Free with RTDbgSymbolFree.1646 * @param phMod Where to return the module handle. Optional.1647 */1648 1360 RTDECL(int) RTDbgAsSymbolByNameA(RTDBGAS hDbgAs, const char *pszSymbol, PRTDBGSYMBOL *ppSymbol, PRTDBGMOD phMod) 1649 1361 { … … 1709 1421 1710 1422 1711 /**1712 * Adds a line number to a module in the address space.1713 *1714 * @returns IPRT status code. See RTDbgModSymbolAdd for more specific ones.1715 * @retval VERR_INVALID_HANDLE if hDbgAs is invalid.1716 * @retval VERR_NOT_FOUND if no module was found at the specified address.1717 * @retval VERR_NOT_SUPPORTED if the module interpret doesn't support adding1718 * custom symbols.1719 *1720 * @param hDbgAs The address space handle.1721 * @param pszFile The file name.1722 * @param uLineNo The line number.1723 * @param Addr The address of the symbol.1724 * @param piOrdinal Where to return the line number ordinal on success.1725 * If the interpreter doesn't do ordinals, this will be1726 * set to UINT32_MAX. Optional.1727 */1728 1423 RTDECL(int) RTDbgAsLineAdd(RTDBGAS hDbgAs, const char *pszFile, uint32_t uLineNo, RTUINTPTR Addr, uint32_t *piOrdinal) 1729 1424 { -
trunk/src/VBox/Runtime/common/ldr/ldrEx.cpp
r98103 r99758 227 227 228 228 229 /**230 * Loads the image into a buffer provided by the user and applies fixups231 * for the given base address.232 *233 * @returns iprt status code.234 * @param hLdrMod The load module handle.235 * @param pvBits Where to put the bits.236 * Must be as large as RTLdrSize() suggests.237 * @param BaseAddress The base address.238 * @param pfnGetImport Callback function for resolving imports one by one.239 * If this is NULL, imports will not be resolved.240 * @param pvUser User argument for the callback.241 * @remark Not supported for RTLdrLoad() images.242 */243 229 RTDECL(int) RTLdrGetBits(RTLDRMOD hLdrMod, void *pvBits, RTLDRADDR BaseAddress, PFNRTLDRIMPORT pfnGetImport, void *pvUser) 244 230 { … … 265 251 266 252 267 /**268 * Relocates bits after getting them.269 * Useful for code which moves around a bit.270 *271 * @returns iprt status code.272 * @param hLdrMod The loader module handle.273 * @param pvBits Where the image bits are.274 * Must have been passed to RTLdrGetBits().275 * @param NewBaseAddress The new base address.276 * @param OldBaseAddress The old base address.277 * @param pfnGetImport Callback function for resolving imports one by one.278 * @param pvUser User argument for the callback.279 * @remark Not supported for RTLdrLoad() images.280 */281 253 RTDECL(int) RTLdrRelocate(RTLDRMOD hLdrMod, void *pvBits, RTLDRADDR NewBaseAddress, RTLDRADDR OldBaseAddress, 282 254 PFNRTLDRIMPORT pfnGetImport, void *pvUser) … … 381 353 382 354 383 /**384 * Enumerates all symbols in a module.385 *386 * @returns iprt status code.387 * @param hLdrMod The loader module handle.388 * @param fFlags Flags indicating what to return and such.389 * @param pvBits Optional pointer to the loaded image.390 * Set this to NULL if no RTLdrGetBits() processed image bits are available.391 * @param BaseAddress Image load address.392 * @param pfnCallback Callback function.393 * @param pvUser User argument for the callback.394 * @remark Not supported for RTLdrLoad() images.395 */396 355 RTDECL(int) RTLdrEnumSymbols(RTLDRMOD hLdrMod, unsigned fFlags, const void *pvBits, RTLDRADDR BaseAddress, 397 356 PFNRTLDRENUMSYMS pfnCallback, void *pvUser) … … 792 751 793 752 794 /**795 * Translates a RTLDRARCH value to a string.796 *797 * @returns Name corresponding to @a enmArch798 * @param enmArch The value to name.799 */800 753 RTDECL(const char *) RTLdrArchName(RTLDRARCH enmArch) 801 754 { -
trunk/src/VBox/Runtime/common/ldr/ldrNative.cpp
r98103 r99758 102 102 103 103 104 /**105 * Loads a dynamic load library (/shared object) image file using native106 * OS facilities.107 *108 * The filename will be appended the default DLL/SO extension of109 * the platform if it have been omitted. This means that it's not110 * possible to load DLLs/SOs with no extension using this interface,111 * but that's not a bad tradeoff.112 *113 * If no path is specified in the filename, the OS will usually search it's library114 * path to find the image file.115 *116 * @returns iprt status code.117 * @param pszFilename Image filename.118 * @param phLdrMod Where to store the handle to the loaded module.119 */120 104 RTDECL(int) RTLdrLoad(const char *pszFilename, PRTLDRMOD phLdrMod) 121 105 { … … 251 235 252 236 253 /**254 * Loads a dynamic load library (/shared object) image file residing in the255 * RTPathAppPrivateArch() directory.256 *257 * Suffix is not required.258 *259 * @returns iprt status code.260 * @param pszFilename Image filename. No path.261 * @param phLdrMod Where to store the handle to the loaded module.262 */263 237 RTDECL(int) RTLdrLoadAppPriv(const char *pszFilename, PRTLDRMOD phLdrMod) 264 238 { … … 317 291 318 292 319 /**320 * Gets the default file suffix for DLL/SO/DYLIB/whatever.321 *322 * @returns The stuff (readonly).323 */324 293 RTDECL(const char *) RTLdrGetSuff(void) 325 294 { -
trunk/src/VBox/Runtime/common/log/log.cpp
r98103 r99758 609 609 610 610 611 /**612 * Sets the default logger instance.613 *614 * @returns iprt status code.615 * @param pLogger The new default logger instance.616 */617 611 RTDECL(PRTLOGGER) RTLogSetDefaultInstance(PRTLOGGER pLogger) 618 612 { … … 735 729 736 730 737 /**738 * Sets the default logger instance.739 *740 * @returns iprt status code.741 * @param pLogger The new default release logger instance.742 */743 731 RTDECL(PRTLOGGER) RTLogRelSetDefaultInstance(PRTLOGGER pLogger) 744 732 { … … 757 745 758 746 759 /**760 *761 * This is the 2nd half of what RTLogGetDefaultInstanceEx() and762 * RTLogRelGetDefaultInstanceEx() does.763 *764 * @returns If the group has the specified flags enabled @a pLogger will be765 * returned returned. Otherwise NULL is returned.766 * @param pLogger The logger. NULL is NULL.767 * @param fFlagsAndGroup The flags in the lower 16 bits, the group number in768 * the high 16 bits.769 */770 747 RTDECL(PRTLOGGER) RTLogCheckGroupFlags(PRTLOGGER pLogger, uint32_t fFlagsAndGroup) 771 748 { … … 1555 1532 1556 1533 1557 /**1558 * Destroys a logger instance.1559 *1560 * The instance is flushed and all output destinations closed (where applicable).1561 *1562 * @returns iprt status code.1563 * @param pLogger The logger instance which close destroyed. NULL is fine.1564 */1565 1534 RTDECL(int) RTLogDestroy(PRTLOGGER pLogger) 1566 1535 { … … 1643 1612 1644 1613 1645 /**1646 * Sets the custom prefix callback.1647 *1648 * @returns IPRT status code.1649 * @param pLogger The logger instance.1650 * @param pfnCallback The callback.1651 * @param pvUser The user argument for the callback.1652 * */1653 1614 RTDECL(int) RTLogSetCustomPrefixCallback(PRTLOGGER pLogger, PFNRTLOGPREFIX pfnCallback, void *pvUser) 1654 1615 { … … 1673 1634 1674 1635 1675 /**1676 * Sets the custom flush callback.1677 *1678 * This can be handy for special loggers like the per-EMT ones in ring-0,1679 * but also for implementing a log viewer in the debugger GUI.1680 *1681 * @returns IPRT status code.1682 * @retval VWRN_ALREADY_EXISTS if it was set to a different flusher.1683 * @param pLogger The logger instance.1684 * @param pfnFlush The flush callback.1685 */1686 1636 RTDECL(int) RTLogSetFlushCallback(PRTLOGGER pLogger, PFNRTLOGFLUSH pfnFlush) 1687 1637 { … … 1783 1733 1784 1734 1785 /**1786 * Updates the group settings for the logger instance using the specified1787 * specification string.1788 *1789 * @returns iprt status code.1790 * Failures can safely be ignored.1791 * @param pLogger Logger instance.1792 * @param pszValue Value to parse.1793 */1794 1735 RTDECL(int) RTLogGroupSettings(PRTLOGGER pLogger, const char *pszValue) 1795 1736 { … … 2032 1973 2033 1974 2034 /**2035 * Get the current log group settings as a string.2036 *2037 * @returns VINF_SUCCESS or VERR_BUFFER_OVERFLOW.2038 * @param pLogger Logger instance (NULL for default logger).2039 * @param pszBuf The output buffer.2040 * @param cchBuf The size of the output buffer. Must be greater2041 * than zero.2042 */2043 1975 RTDECL(int) RTLogQueryGroupSettings(PRTLOGGER pLogger, char *pszBuf, size_t cchBuf) 2044 1976 { … … 2091 2023 2092 2024 2093 /**2094 * Updates the flags for the logger instance using the specified2095 * specification string.2096 *2097 * @returns iprt status code.2098 * Failures can safely be ignored.2099 * @param pLogger Logger instance (NULL for default logger).2100 * @param pszValue Value to parse.2101 */2102 2025 RTDECL(int) RTLogFlags(PRTLOGGER pLogger, const char *pszValue) 2103 2026 { … … 2178 2101 2179 2102 2180 /**2181 * Changes the buffering setting of the specified logger.2182 *2183 * This can be used for optimizing longish logging sequences.2184 *2185 * @returns The old state.2186 * @param pLogger The logger instance (NULL is an alias for the2187 * default logger).2188 * @param fBuffered The new state.2189 */2190 2103 RTDECL(bool) RTLogSetBuffering(PRTLOGGER pLogger, bool fBuffered) 2191 2104 { … … 2275 2188 #endif /* IN_RING0 */ 2276 2189 2277 /**2278 * Gets the current flag settings for the given logger.2279 *2280 * @returns Logger flags, UINT64_MAX if no logger.2281 * @param pLogger Logger instance (NULL for default logger).2282 */2283 2190 RTDECL(uint64_t) RTLogGetFlags(PRTLOGGER pLogger) 2284 2191 { … … 2291 2198 2292 2199 2293 /**2294 * Modifies the flag settings for the given logger.2295 *2296 * @returns IPRT status code. Returns VINF_SUCCESS if VINF_LOG_NO_LOGGER and @a2297 * pLogger is NULL.2298 * @param pLogger Logger instance (NULL for default logger).2299 * @param fSet Mask of flags to set (OR).2300 * @param fClear Mask of flags to clear (NAND). This is allowed to2301 * include invalid flags - e.g. UINT64_MAX is okay.2302 */2303 2200 RTDECL(int) RTLogChangeFlags(PRTLOGGER pLogger, uint64_t fSet, uint64_t fClear) 2304 2201 { … … 2323 2220 2324 2221 2325 /**2326 * Get the current log flags as a string.2327 *2328 * @returns VINF_SUCCESS or VERR_BUFFER_OVERFLOW.2329 * @param pLogger Logger instance (NULL for default logger).2330 * @param pszBuf The output buffer.2331 * @param cchBuf The size of the output buffer. Must be greater2332 * than zero.2333 */2334 2222 RTDECL(int) RTLogQueryFlags(PRTLOGGER pLogger, char *pszBuf, size_t cchBuf) 2335 2223 { … … 2419 2307 2420 2308 2421 /**2422 * Updates the logger destination using the specified string.2423 *2424 * @returns VINF_SUCCESS or VERR_BUFFER_OVERFLOW.2425 * @param pLogger Logger instance (NULL for default logger).2426 * @param pszValue The value to parse.2427 */2428 2309 RTDECL(int) RTLogDestinations(PRTLOGGER pLogger, char const *pszValue) 2429 2310 { … … 2616 2497 2617 2498 2618 /**2619 * Clear the file delay flag if set, opening the destination and flushing.2620 *2621 * @returns IPRT status code.2622 * @param pLogger Logger instance (NULL for default logger).2623 * @param pErrInfo Where to return extended error info. Optional.2624 */2625 2499 RTDECL(int) RTLogClearFileDelayFlag(PRTLOGGER pLogger, PRTERRINFO pErrInfo) 2626 2500 { … … 2655 2529 2656 2530 2657 /**2658 * Modifies the log destinations settings for the given logger.2659 *2660 * This is only suitable for simple destination settings that doesn't take2661 * additional arguments, like RTLOGDEST_FILE.2662 *2663 * @returns IPRT status code. Returns VINF_LOG_NO_LOGGER if VINF_LOG_NO_LOGGER2664 * and @a pLogger is NULL.2665 * @param pLogger Logger instance (NULL for default logger).2666 * @param fSet Mask of destinations to set (OR).2667 * @param fClear Mask of destinations to clear (NAND).2668 */2669 2531 RTDECL(int) RTLogChangeDestinations(PRTLOGGER pLogger, uint32_t fSet, uint32_t fClear) 2670 2532 { … … 2692 2554 2693 2555 2694 /**2695 * Gets the current destinations flags for the given logger.2696 *2697 * @returns Logger destination flags, UINT32_MAX if no logger.2698 * @param pLogger Logger instance (NULL for default logger).2699 */2700 2556 RTDECL(uint32_t) RTLogGetDestinations(PRTLOGGER pLogger) 2701 2557 { … … 2712 2568 2713 2569 2714 /**2715 * Get the current log destinations as a string.2716 *2717 * @returns VINF_SUCCESS or VERR_BUFFER_OVERFLOW.2718 * @param pLogger Logger instance (NULL for default logger).2719 * @param pszBuf The output buffer.2720 * @param cchBuf The size of the output buffer. Must be greater2721 * than 0.2722 */2723 2570 RTDECL(int) RTLogQueryDestinations(PRTLOGGER pLogger, char *pszBuf, size_t cchBuf) 2724 2571 { … … 3069 2916 *********************************************************************************************************************************/ 3070 2917 3071 /**3072 * Performs a bulk update of logger flags and group flags.3073 *3074 * This is for instanced used for copying settings from ring-3 to ring-03075 * loggers.3076 *3077 * @returns IPRT status code.3078 * @param pLogger The logger instance (NULL for default logger).3079 * @param fFlags The new logger flags.3080 * @param uGroupCrc32 The CRC32 of the group name strings.3081 * @param cGroups Number of groups.3082 * @param pafGroups Array of group flags.3083 * @sa RTLogQueryBulk3084 */3085 2918 RTDECL(int) RTLogBulkUpdate(PRTLOGGER pLogger, uint64_t fFlags, uint32_t uGroupCrc32, uint32_t cGroups, uint32_t const *pafGroups) 3086 2919 { … … 3112 2945 3113 2946 3114 /**3115 * Queries data for a bulk update of logger flags and group flags.3116 *3117 * This is for instanced used for copying settings from ring-3 to ring-03118 * loggers.3119 *3120 * @returns IPRT status code.3121 * @retval VERR_BUFFER_OVERFLOW if pafGroups is too small, @a pcGroups will be3122 * set to the actual number of groups.3123 * @param pLogger The logger instance (NULL for default logger).3124 * @param pfFlags Where to return the logger flags.3125 * @param puGroupCrc32 Where to return the CRC32 of the group names.3126 * @param pcGroups Input: Size of the @a pafGroups allocation.3127 * Output: Actual number of groups returned.3128 * @param pafGroups Where to return the flags for each group.3129 * @sa RTLogBulkUpdate3130 */3131 2947 RTDECL(int) RTLogQueryBulk(PRTLOGGER pLogger, uint64_t *pfFlags, uint32_t *puGroupCrc32, uint32_t *pcGroups, uint32_t *pafGroups) 3132 2948 { … … 3156 2972 3157 2973 3158 /**3159 * Write/copy bulk log data from another logger.3160 *3161 * This is used for transferring stuff from the ring-0 loggers and into the3162 * ring-3 one. The text goes in as-is w/o any processing (i.e. prefixing or3163 * newline fun).3164 *3165 * @returns IRPT status code.3166 * @param pLogger The logger instance (NULL for default logger).3167 * @param pszBefore Text to log before the bulk text. Optional.3168 * @param pch Pointer to the block of bulk log text to write.3169 * @param cch Size of the block of bulk log text to write.3170 * @param pszAfter Text to log after the bulk text. Optional.3171 */3172 2974 RTDECL(int) RTLogBulkWrite(PRTLOGGER pLogger, const char *pszBefore, const char *pch, size_t cch, const char *pszAfter) 3173 2975 { … … 3242 3044 3243 3045 3244 /**3245 * Write/copy bulk log data from a nested VM logger.3246 *3247 * This is used for3248 *3249 * @returns IRPT status code.3250 * @param pLogger The logger instance (NULL for default logger).3251 * @param pch Pointer to the block of bulk log text to write.3252 * @param cch Size of the block of bulk log text to write.3253 * @param pszInfix String to put after the line prefixes and the3254 * line content.3255 */3256 3046 RTDECL(int) RTLogBulkNestedWrite(PRTLOGGER pLogger, const char *pch, size_t cch, const char *pszInfix) 3257 3047 { … … 3318 3108 *********************************************************************************************************************************/ 3319 3109 3320 /**3321 * Flushes the specified logger.3322 *3323 * @param pLogger The logger instance to flush.3324 * If NULL the default instance is used. The default instance3325 * will not be initialized by this call.3326 */3327 3110 RTDECL(int) RTLogFlush(PRTLOGGER pLogger) 3328 3111 { … … 4356 4139 4357 4140 4358 /**4359 * Write to a logger instance.4360 *4361 * This function will check whether the instance, group and flags makes up a4362 * logging kind which is currently enabled before writing anything to the log.4363 *4364 * @returns VINF_SUCCESS, VINF_LOG_NO_LOGGER, VINF_LOG_DISABLED, or IPRT error4365 * status.4366 * @param pLogger Pointer to logger instance. If NULL the default logger instance will be attempted.4367 * @param fFlags The logging flags.4368 * @param iGroup The group.4369 * The value ~0U is reserved for compatibility with RTLogLogger[V] and is4370 * only for internal usage!4371 * @param pszFormat Format string.4372 * @param args Format arguments.4373 */4374 4141 RTDECL(int) RTLogLoggerExV(PRTLOGGER pLogger, unsigned fFlags, unsigned iGroup, const char *pszFormat, va_list args) 4375 4142 { … … 4445 4212 4446 4213 4447 /**4448 * Write to a logger instance.4449 *4450 * @param pLogger Pointer to logger instance.4451 * @param pszFormat Format string.4452 * @param args Format arguments.4453 */4454 4214 RTDECL(void) RTLogLoggerV(PRTLOGGER pLogger, const char *pszFormat, va_list args) 4455 4215 { … … 4459 4219 4460 4220 4461 /**4462 * vprintf like function for writing to the default log.4463 *4464 * @param pszFormat Printf like format string.4465 * @param va Optional arguments as specified in pszFormat.4466 *4467 * @remark The API doesn't support formatting of floating point numbers at the moment.4468 */4469 4221 RTDECL(void) RTLogPrintfV(const char *pszFormat, va_list va) 4470 4222 { … … 4474 4226 4475 4227 4476 /**4477 * Dumper vprintf-like function outputting to a logger.4478 *4479 * @param pvUser Pointer to the logger instance to use, NULL for4480 * default instance.4481 * @param pszFormat Format string.4482 * @param va Format arguments.4483 */4484 4228 RTDECL(void) RTLogDumpPrintfV(void *pvUser, const char *pszFormat, va_list va) 4485 4229 { -
trunk/src/VBox/Runtime/common/misc/inifile.cpp
r98103 r99758 315 315 316 316 317 /**318 * Creates a INI-file instance from a VFS file handle.319 *320 * @returns IPRT status code321 * @param phIniFile Where to return the INI-file handle.322 * @param hVfsFile The VFS file handle (not consumed, additional323 * reference is retained).324 * @param fFlags Flags, RTINIFILE_F_XXX.325 */326 317 RTDECL(int) RTIniFileCreateFromVfsFile(PRTINIFILE phIniFile, RTVFSFILE hVfsFile, uint32_t fFlags) 327 318 { … … 361 352 362 353 363 /**364 * Retains a reference to an INI-file instance.365 *366 * @returns New reference count, UINT32_MAX on failure.367 * @param hIniFile The INI-file handle.368 */369 354 RTDECL(uint32_t) RTIniFileRetain(RTINIFILE hIniFile) 370 355 { … … 380 365 381 366 382 /**383 * Releases a reference to an INI-file instance, destroying it if the count384 * reaches zero.385 *386 * @returns New reference count, UINT32_MAX on failure.387 * @param hIniFile The INI-file handle. NIL is ignored.388 */389 367 RTDECL(uint32_t) RTIniFileRelease(RTINIFILE hIniFile) 390 368 { … … 526 504 527 505 528 /**529 * Queries a value in a section.530 *531 * The first matching value is returned. The matching is by default case532 * insensitive.533 *534 * @returns IPRT status code.535 * @retval VERR_NOT_FOUND if section or key not found.536 *537 * @param hIniFile The INI-file handle.538 * @param pszSection The section name. Pass NULL to refer to the539 * unsectioned key space at the top of the file.540 * @param pszKey The key name.541 * @param pszValue Where to return the value.542 * @param cbValue Size of the buffer @a pszValue points to.543 * @param pcbActual Where to return the actual value size excluding544 * terminator on success. On VERR_BUFFER_OVERFLOW this545 * will be set to the buffer size needed to hold the546 * value, terminator included. Optional.547 */548 506 RTDECL(int) RTIniFileQueryValue(RTINIFILE hIniFile, const char *pszSection, const char *pszKey, 549 507 char *pszValue, size_t cbValue, size_t *pcbActual) … … 732 690 733 691 734 /**735 * Queries a key-value pair in a section by ordinal.736 *737 * @returns IPRT status code.738 * @retval VERR_NOT_FOUND if the section wasn't found or if it contains no pair739 * with the given ordinal value.740 *741 * @param hIniFile The INI-file handle.742 * @param pszSection The section name. Pass NULL to refer to the743 * unsectioned key space at the top of the file.744 * @param idxPair The pair to fetch (counting from 0).745 *746 * @param pszKey Where to return the key name.747 * @param cbKey Size of the buffer @a pszKey points to.748 * @param pcbKeyActual Where to return the actual key size excluding749 * terminator on success. On VERR_BUFFER_OVERFLOW this750 * will be set to the buffer size needed to hold the751 * value, terminator included. Optional.752 *753 * @param pszValue Where to return the value.754 * @param cbValue Size of the buffer @a pszValue points to.755 * @param pcbValueActual Where to return the actual value size excluding756 * terminator on success. On VERR_BUFFER_OVERFLOW this757 * will be set to the buffer size needed to hold the758 * value, terminator included. Optional.759 */760 692 RTDECL(int) RTIniFileQueryPair(RTINIFILE hIniFile, const char *pszSection, uint32_t idxPair, 761 693 char *pszKey, size_t cbKey, size_t *pcbKeyActual, -
trunk/src/VBox/Runtime/common/misc/semspingpong.cpp
r98103 r99758 71 71 72 72 73 /**74 * Init a Ping-Pong construct.75 *76 * @returns iprt status code.77 * @param pPP Pointer to the ping-pong structure which needs initialization.78 */79 73 RTDECL(int) RTSemPingPongInit(PRTPINGPONG pPP) 80 74 { … … 98 92 99 93 100 /**101 * Destroys a Ping-Pong construct.102 *103 * @returns iprt status code.104 * @param pPP Pointer to the ping-pong structure which is to be destroyed.105 * (I.e. put into uninitialized state.)106 */107 94 RTDECL(int) RTSemPingPongDelete(PRTPINGPONG pPP) 108 95 { … … 129 116 130 117 131 /**132 * Signals the pong thread in a ping-pong construct. (I.e. sends ping.)133 * This is called by the ping thread.134 *135 * @returns iprt status code.136 * @param pPP Pointer to the ping-pong structure to ping.137 */138 118 RTDECL(int) RTSemPing(PRTPINGPONG pPP) 139 119 { … … 162 142 163 143 164 /**165 * Signals the ping thread in a ping-pong construct. (I.e. sends pong.)166 * This is called by the pong thread.167 *168 * @returns iprt status code.169 * @param pPP Pointer to the ping-pong structure to pong.170 */171 144 RTDECL(int) RTSemPong(PRTPINGPONG pPP) 172 145 { … … 195 168 196 169 197 /**198 * Wait function for the ping thread.199 *200 * @returns iprt status code.201 * Will not return VERR_INTERRUPTED.202 * @param pPP Pointer to the ping-pong structure to wait on.203 * @param cMillies Number of milliseconds to wait.204 */205 170 RTDECL(int) RTSemPingWait(PRTPINGPONG pPP, RTMSINTERVAL cMillies) 206 171 { … … 228 193 229 194 230 /**231 * Wait function for the pong thread.232 *233 * @returns iprt status code.234 * Will not return VERR_INTERRUPTED.235 * @param pPP Pointer to the ping-pong structure to wait on.236 * @param cMillies Number of milliseconds to wait.237 */238 195 RTDECL(int) RTSemPongWait(PRTPINGPONG pPP, RTMSINTERVAL cMillies) 239 196 { -
trunk/src/VBox/Runtime/common/misc/thread.cpp
r98103 r99758 300 300 } 301 301 302 /** 303 * Adopts a non-IPRT thread. 304 * 305 * @returns IPRT status code. 306 * @param enmType The thread type. 307 * @param fFlags The thread flags. RTTHREADFLAGS_WAITABLE is not currently allowed. 308 * @param pszName The thread name. Optional. 309 * @param pThread Where to store the thread handle. Optional. 310 */ 302 311 303 RTDECL(int) RTThreadAdopt(RTTHREADTYPE enmType, unsigned fFlags, const char *pszName, PRTTHREAD pThread) 312 304 { … … 352 344 353 345 354 /**355 * Get the thread handle of the current thread, automatically adopting alien356 * threads.357 *358 * @returns Thread handle.359 */360 346 RTDECL(RTTHREAD) RTThreadSelfAutoAdopt(void) 361 347 { … … 776 762 777 763 778 /**779 * Create a new thread.780 *781 * @returns iprt status code.782 * @param pThread Where to store the thread handle to the new thread. (optional)783 * @param pfnThread The thread function.784 * @param pvUser User argument.785 * @param cbStack The size of the stack for the new thread.786 * Use 0 for the default stack size.787 * @param enmType The thread type. Used for deciding scheduling attributes788 * of the thread.789 * @param fFlags Flags of the RTTHREADFLAGS type (ORed together).790 * @param pszName Thread name.791 */792 764 RTDECL(int) RTThreadCreate(PRTTHREAD pThread, PFNRTTHREAD pfnThread, void *pvUser, size_t cbStack, 793 765 RTTHREADTYPE enmType, unsigned fFlags, const char *pszName) … … 844 816 845 817 846 /**847 * Create a new thread.848 *849 * Same as RTThreadCreate except the name is given in the RTStrPrintfV form.850 *851 * @returns iprt status code.852 * @param pThread See RTThreadCreate.853 * @param pfnThread See RTThreadCreate.854 * @param pvUser See RTThreadCreate.855 * @param cbStack See RTThreadCreate.856 * @param enmType See RTThreadCreate.857 * @param fFlags See RTThreadCreate.858 * @param pszNameFmt Thread name format.859 * @param va Format arguments.860 */861 818 RTDECL(int) RTThreadCreateV(PRTTHREAD pThread, PFNRTTHREAD pfnThread, void *pvUser, size_t cbStack, 862 819 RTTHREADTYPE enmType, uint32_t fFlags, const char *pszNameFmt, va_list va) … … 869 826 870 827 871 /**872 * Create a new thread.873 *874 * Same as RTThreadCreate except the name is given in the RTStrPrintf form.875 *876 * @returns iprt status code.877 * @param pThread See RTThreadCreate.878 * @param pfnThread See RTThreadCreate.879 * @param pvUser See RTThreadCreate.880 * @param cbStack See RTThreadCreate.881 * @param enmType See RTThreadCreate.882 * @param fFlags See RTThreadCreate.883 * @param pszNameFmt Thread name format.884 * @param ... Format arguments.885 */886 828 RTDECL(int) RTThreadCreateF(PRTTHREAD pThread, PFNRTTHREAD pfnThread, void *pvUser, size_t cbStack, 887 829 RTTHREADTYPE enmType, uint32_t fFlags, const char *pszNameFmt, ...) … … 897 839 898 840 899 /**900 * Gets the native thread id of a IPRT thread.901 *902 * @returns The native thread id.903 * @param Thread The IPRT thread.904 */905 841 RTDECL(RTNATIVETHREAD) RTThreadGetNative(RTTHREAD Thread) 906 842 { … … 917 853 918 854 919 /**920 * Gets the IPRT thread of a native thread.921 *922 * @returns The IPRT thread handle923 * @returns NIL_RTTHREAD if not a thread known to IPRT.924 * @param NativeThread The native thread handle/id.925 */926 855 RTDECL(RTTHREAD) RTThreadFromNative(RTNATIVETHREAD NativeThread) 927 856 { … … 934 863 935 864 936 /**937 * Gets the name of the current thread thread.938 *939 * @returns Pointer to readonly name string.940 * @returns NULL on failure.941 */942 865 RTDECL(const char *) RTThreadSelfName(void) 943 866 { … … 958 881 959 882 960 /**961 * Gets the name of a thread.962 *963 * @returns Pointer to readonly name string.964 * @returns NULL on failure.965 * @param Thread Thread handle of the thread to query the name of.966 */967 883 RTDECL(const char *) RTThreadGetName(RTTHREAD Thread) 968 884 { … … 982 898 983 899 984 /**985 * Sets the name of a thread.986 *987 * @returns iprt status code.988 * @param Thread Thread handle of the thread to query the name of.989 * @param pszName The thread name.990 */991 900 RTDECL(int) RTThreadSetName(RTTHREAD Thread, const char *pszName) 992 901 { … … 1016 925 1017 926 1018 /**1019 * Checks if the specified thread is the main thread.1020 *1021 * @returns true if it is, false if it isn't.1022 *1023 * @param hThread The thread handle.1024 *1025 * @remarks This function may not return the correct value when rtR3Init was1026 * called on a thread of the than the main one. This could for1027 * instance happen when the DLL/DYLIB/SO containing IPRT is dynamically1028 * loaded at run time by a different thread.1029 */1030 927 RTDECL(bool) RTThreadIsMain(RTTHREAD hThread) 1031 928 { … … 1086 983 1087 984 1088 /**1089 * Signal the user event.1090 *1091 * @returns iprt status code.1092 */1093 985 RTDECL(int) RTThreadUserSignal(RTTHREAD Thread) 1094 986 { … … 1107 999 1108 1000 1109 /**1110 * Wait for the user event, resume on interruption.1111 *1112 * @returns iprt status code.1113 * @param Thread The thread to wait for.1114 * @param cMillies The number of milliseconds to wait. Use RT_INDEFINITE_WAIT for1115 * an indefinite wait.1116 */1117 1001 RTDECL(int) RTThreadUserWait(RTTHREAD Thread, RTMSINTERVAL cMillies) 1118 1002 { … … 1131 1015 1132 1016 1133 /**1134 * Wait for the user event, return on interruption.1135 *1136 * @returns iprt status code.1137 * @param Thread The thread to wait for.1138 * @param cMillies The number of milliseconds to wait. Use RT_INDEFINITE_WAIT for1139 * an indefinite wait.1140 */1141 1017 RTDECL(int) RTThreadUserWaitNoResume(RTTHREAD Thread, RTMSINTERVAL cMillies) 1142 1018 { … … 1155 1031 1156 1032 1157 /**1158 * Reset the user event.1159 *1160 * @returns iprt status code.1161 * @param Thread The thread to reset.1162 */1163 1033 RTDECL(int) RTThreadUserReset(RTTHREAD Thread) 1164 1034 { … … 1252 1122 1253 1123 1254 /**1255 * Wait for the thread to terminate, resume on interruption.1256 *1257 * @returns iprt status code.1258 * Will not return VERR_INTERRUPTED.1259 * @param Thread The thread to wait for.1260 * @param cMillies The number of milliseconds to wait. Use RT_INDEFINITE_WAIT for1261 * an indefinite wait.1262 * @param prc Where to store the return code of the thread. Optional.1263 */1264 1124 RTDECL(int) RTThreadWait(RTTHREAD Thread, RTMSINTERVAL cMillies, int *prc) 1265 1125 { … … 1271 1131 1272 1132 1273 /**1274 * Wait for the thread to terminate, return on interruption.1275 *1276 * @returns iprt status code.1277 * @param Thread The thread to wait for.1278 * @param cMillies The number of milliseconds to wait. Use RT_INDEFINITE_WAIT for1279 * an indefinite wait.1280 * @param prc Where to store the return code of the thread. Optional.1281 */1282 1133 RTDECL(int) RTThreadWaitNoResume(RTTHREAD Thread, RTMSINTERVAL cMillies, int *prc) 1283 1134 { … … 1287 1138 1288 1139 1289 /**1290 * Changes the type of the specified thread.1291 *1292 * @returns iprt status code.1293 * @param Thread The thread which type should be changed.1294 * @param enmType The new thread type.1295 */1296 1140 RTDECL(int) RTThreadSetType(RTTHREAD Thread, RTTHREADTYPE enmType) 1297 1141 { … … 1336 1180 1337 1181 1338 /**1339 * Gets the type of the specified thread.1340 *1341 * @returns The thread type.1342 * @returns RTTHREADTYPE_INVALID if the thread handle is invalid.1343 * @param Thread The thread in question.1344 */1345 1182 RTDECL(RTTHREADTYPE) RTThreadGetType(RTTHREAD Thread) 1346 1183 { … … 1443 1280 1444 1281 1445 /**1446 * Change the thread state to blocking.1447 *1448 * @param hThread The current thread.1449 * @param enmState The sleep state.1450 * @param fReallySleeping Really going to sleep now.1451 */1452 1282 RTDECL(void) RTThreadBlocking(RTTHREAD hThread, RTTHREADSTATE enmState, bool fReallySleeping) 1453 1283 { … … 1465 1295 1466 1296 1467 /**1468 * Unblocks a thread.1469 *1470 * This function is paired with rtThreadBlocking.1471 *1472 * @param hThread The current thread.1473 * @param enmCurState The current state, used to check for nested blocking.1474 * The new state will be running.1475 */1476 1297 RTDECL(void) RTThreadUnblocked(RTTHREAD hThread, RTTHREADSTATE enmCurState) 1477 1298 { … … 1502 1323 1503 1324 1504 /**1505 * Get the current thread state.1506 *1507 * @returns The thread state.1508 * @param hThread The thread.1509 */1510 1325 RTDECL(RTTHREADSTATE) RTThreadGetState(RTTHREAD hThread) 1511 1326 { -
trunk/src/VBox/Runtime/common/path/RTPathAbsDup.cpp
r98103 r99758 43 43 44 44 45 /**46 * Same as RTPathAbs only the result is RTStrDup()'ed.47 *48 * @returns Pointer to real path. Use RTStrFree() to free this string.49 * @returns NULL if RTPathAbs() or RTStrDup() fails.50 * @param pszPath The path to resolve.51 */52 45 RTDECL(char *) RTPathAbsDup(const char *pszPath) 53 46 { -
trunk/src/VBox/Runtime/common/path/RTPathParentLength.cpp
r98103 r99758 85 85 86 86 87 88 89 /**90 * Determins the length of the path specifying the parent directory, including91 * trailing path separator (if present).92 *93 * @returns Parent directory part of the path, 0 if no parent.94 * @param pszPath The path to examine.95 *96 * @note Currently ignores UNC and may therefore return the server or97 * double-slash prefix as parent.98 */99 87 RTDECL(size_t) RTPathParentLength(const char *pszPath) 100 88 { -
trunk/src/VBox/Runtime/common/path/RTPathParseSimple.cpp
r98103 r99758 46 46 47 47 48 /**49 * Parses a path.50 *51 * It figures the length of the directory component, the offset of52 * the file name and the location of the suffix dot.53 *54 * @returns The path length.55 *56 * @param pszPath Path to find filename in.57 * @param pcchDir Where to put the length of the directory component. If58 * no directory, this will be 0. Optional.59 * @param poffName Where to store the filename offset.60 * If empty string or if it's ending with a slash this61 * will be set to -1. Optional.62 * @param poffSuff Where to store the suffix offset (the last dot).63 * If empty string or if it's ending with a slash this64 * will be set to -1. Optional.65 */66 48 RTDECL(size_t) RTPathParseSimple(const char *pszPath, size_t *pcchDir, ssize_t *poffName, ssize_t *poffSuff) 67 49 { -
trunk/src/VBox/Runtime/common/path/RTPathRealDup.cpp
r98103 r99758 47 47 48 48 49 /**50 * Same as RTPathReal only the result is RTStrDup()'ed.51 *52 * @returns Pointer to real path. Use RTStrFree() to free this string.53 * @returns NULL if RTPathReal() or RTStrDup() fails.54 * @param pszPath55 */56 49 RTDECL(char *) RTPathRealDup(const char *pszPath) 57 50 { -
trunk/src/VBox/Runtime/common/path/comparepaths.cpp
r98103 r99758 114 114 115 115 116 /**117 * Compares two paths.118 *119 * The comparison takes platform-dependent details into account,120 * such as:121 * <ul>122 * <li>On DOS-like platforms, both separator chars (|\| and |/|) are considered123 * to be equal.124 * <li>On platforms with case-insensitive file systems, mismatching characters125 * are uppercased and compared again.126 * </ul>127 *128 * @returns @< 0 if the first path less than the second path.129 * @returns 0 if the first path identical to the second path.130 * @returns @> 0 if the first path greater than the second path.131 *132 * @param pszPath1 Path to compare (must be an absolute path).133 * @param pszPath2 Path to compare (must be an absolute path).134 *135 * @remarks File system details are currently ignored. This means that you won't136 * get case-insensitive compares on unix systems when a path goes into a137 * case-insensitive filesystem like FAT, HPFS, HFS, NTFS, JFS, or138 * similar. For NT, OS/2 and similar you'll won't get case-sensitive139 * compares on a case-sensitive file system.140 */141 116 RTDECL(int) RTPathCompare(const char *pszPath1, const char *pszPath2) 142 117 { … … 145 120 146 121 147 /**148 * Checks if a path starts with the given parent path.149 *150 * This means that either the path and the parent path matches completely, or151 * that the path is to some file or directory residing in the tree given by the152 * parent directory.153 *154 * The path comparison takes platform-dependent details into account,155 * see RTPathCompare() for details.156 *157 * @returns |true| when \a pszPath starts with \a pszParentPath (or when they158 * are identical), or |false| otherwise.159 *160 * @param pszPath Path to check, must be an absolute path.161 * @param pszParentPath Parent path, must be an absolute path.162 * No trailing directory slash!163 */164 122 RTDECL(bool) RTPathStartsWith(const char *pszPath, const char *pszParentPath) 165 123 { -
trunk/src/VBox/Runtime/common/rand/rand.cpp
r98103 r99758 94 94 * Termination counterpart to rtRandInitOnce. 95 95 * 96 * @returns IPRT status code.97 96 * @param pvUser Ignored. 98 97 * @param fLazyCleanUpOk Set if we're terminating the process. -
trunk/src/VBox/Runtime/common/string/strformat.cpp
r98103 r99758 152 152 153 153 154 /**155 * Formats an integer number according to the parameters.156 *157 * @returns Length of the number.158 * @param psz Pointer to output string.159 * @param u64Value Value.160 * @param uiBase Number representation base.161 * @param cchWidth Width162 * @param cchPrecision Precision.163 * @param fFlags Flags (NTFS_*).164 */165 154 RTDECL(int) RTStrFormatNumber(char *psz, uint64_t u64Value, unsigned int uiBase, signed int cchWidth, signed int cchPrecision, 166 155 unsigned int fFlags) … … 360 349 361 350 362 /**363 * Partial implementation of a printf like formatter.364 * It doesn't do everything correct, and there is no floating point support.365 * However, it supports custom formats by the means of a format callback.366 *367 * @returns number of bytes formatted.368 * @param pfnOutput Output worker.369 * Called in two ways. Normally with a string an it's length.370 * For termination, it's called with NULL for string, 0 for length.371 * @param pvArgOutput Argument to the output worker.372 * @param pfnFormat Custom format worker.373 * @param pvArgFormat Argument to the format worker.374 * @param pszFormat Format string.375 * @param InArgs Argument list.376 */377 351 RTDECL(size_t) RTStrFormatV(PFNRTSTROUTPUT pfnOutput, void *pvArgOutput, PFNSTRFORMAT pfnFormat, void *pvArgFormat, 378 352 const char *pszFormat, va_list InArgs) -
trunk/src/VBox/Runtime/common/string/strspace.cpp
r98103 r99758 85 85 86 86 87 /**88 * Inserts a string into a unique string space.89 *90 * @returns true on success.91 * @returns false if the string collided with an existing string.92 * @param pStrSpace The space to insert it into.93 * @param pStr The string node.94 */95 87 RTDECL(bool) RTStrSpaceInsert(PRTSTRSPACE pStrSpace, PRTSTRSPACECORE pStr) 96 88 { … … 112 104 113 105 114 /**115 * Removes a string from a unique string space.116 *117 * @returns Pointer to the removed string node.118 * @returns NULL if the string was not found in the string space.119 * @param pStrSpace The space to insert it into.120 * @param pszString The string to remove.121 */122 106 RTDECL(PRTSTRSPACECORE) RTStrSpaceRemove(PRTSTRSPACE pStrSpace, const char *pszString) 123 107 { … … 161 145 162 146 163 /**164 * Gets a string from a unique string space.165 *166 * @returns Pointer to the string node.167 * @returns NULL if the string was not found in the string space.168 * @param pStrSpace The space to insert it into.169 * @param pszString The string to get.170 */171 147 RTDECL(PRTSTRSPACECORE) RTStrSpaceGet(PRTSTRSPACE pStrSpace, const char *pszString) 172 148 { … … 187 163 188 164 189 /**190 * Gets a string from a unique string space.191 *192 * @returns Pointer to the string node.193 * @returns NULL if the string was not found in the string space.194 * @param pStrSpace The space to insert it into.195 * @param pszString The string to get.196 * @param cchMax The max string length to evaluate. Passing197 * RTSTR_MAX is ok and makes it behave just like198 * RTStrSpaceGet.199 */200 165 RTDECL(PRTSTRSPACECORE) RTStrSpaceGetN(PRTSTRSPACE pStrSpace, const char *pszString, size_t cchMax) 201 166 { … … 216 181 217 182 218 /**219 * Enumerates the string space.220 * The caller supplies a callback which will be called for each of221 * the string nodes.222 *223 * @returns 0 or what ever non-zero return value pfnCallback returned224 * when aborting the destruction.225 * @param pStrSpace The space to insert it into.226 * @param pfnCallback The callback.227 * @param pvUser The user argument.228 */229 183 RTDECL(int) RTStrSpaceEnumerate(PRTSTRSPACE pStrSpace, PFNRTSTRSPACECALLBACK pfnCallback, void *pvUser) 230 184 { … … 234 188 235 189 236 /**237 * Destroys the string space.238 * The caller supplies a callback which will be called for each of239 * the string nodes in for freeing their memory and other resources.240 *241 * @returns 0 or what ever non-zero return value pfnCallback returned242 * when aborting the destruction.243 * @param pStrSpace The space to insert it into.244 * @param pfnCallback The callback.245 * @param pvUser The user argument.246 */247 190 RTDECL(int) RTStrSpaceDestroy(PRTSTRSPACE pStrSpace, PFNRTSTRSPACECALLBACK pfnCallback, void *pvUser) 248 191 { -
trunk/src/VBox/Runtime/common/string/strtonum.cpp
r98103 r99758 119 119 120 120 121 /**122 * Converts a string representation of a number to a 64-bit unsigned number.123 *124 * @returns iprt status code.125 * Warnings are used to indicate conversion problems.126 * @retval VWRN_NUMBER_TOO_BIG127 * @retval VWRN_NEGATIVE_UNSIGNED128 * @retval VWRN_TRAILING_CHARS129 * @retval VWRN_TRAILING_SPACES130 * @retval VINF_SUCCESS131 * @retval VERR_NO_DIGITS132 *133 * @param pszValue Pointer to the string value.134 * @param ppszNext Where to store the pointer to the first char135 * following the number. (Optional)136 * @param uBaseAndMaxLen The low byte is the base of the representation, the137 * upper 24 bits are the max length to parse. If the base138 * is zero the function will look for known prefixes before139 * defaulting to 10. A max length of zero means no length140 * restriction.141 * @param pu64 Where to store the converted number. (optional)142 */143 121 RTDECL(int) RTStrToUInt64Ex(const char *pszValue, char **ppszNext, unsigned uBaseAndMaxLen, uint64_t *pu64) 144 122 { … … 265 243 266 244 267 /**268 * Converts a string representation of a number to a 64-bit unsigned number,269 * making sure the full string is converted.270 *271 * @returns iprt status code.272 * Warnings are used to indicate conversion problems.273 * @retval VWRN_NUMBER_TOO_BIG274 * @retval VWRN_NEGATIVE_UNSIGNED275 * @retval VINF_SUCCESS276 * @retval VERR_NO_DIGITS277 * @retval VERR_TRAILING_SPACES278 * @retval VERR_TRAILING_CHARS279 *280 * @param pszValue Pointer to the string value.281 * @param uBaseAndMaxLen The low byte is the base of the representation, the282 * upper 24 bits are the max length to parse. If the base283 * is zero the function will look for known prefixes before284 * defaulting to 10. A max length of zero means no length285 * restriction.286 * @param pu64 Where to store the converted number. (optional)287 */288 245 RTDECL(int) RTStrToUInt64Full(const char *pszValue, unsigned uBaseAndMaxLen, uint64_t *pu64) 289 246 { … … 314 271 315 272 316 /**317 * Converts a string representation of a number to a 64-bit unsigned number.318 * The base is guessed.319 *320 * @returns 64-bit unsigned number on success.321 * @returns 0 on failure.322 * @param pszValue Pointer to the string value.323 */324 273 RTDECL(uint64_t) RTStrToUInt64(const char *pszValue) 325 274 { … … 333 282 334 283 335 /**336 * Converts a string representation of a number to a 32-bit unsigned number.337 *338 * @returns iprt status code.339 * Warnings are used to indicate conversion problems.340 * @retval VWRN_NUMBER_TOO_BIG341 * @retval VWRN_NEGATIVE_UNSIGNED342 * @retval VWRN_TRAILING_CHARS343 * @retval VWRN_TRAILING_SPACES344 * @retval VINF_SUCCESS345 * @retval VERR_NO_DIGITS346 *347 * @param pszValue Pointer to the string value.348 * @param ppszNext Where to store the pointer to the first char349 * following the number. (Optional)350 * @param uBaseAndMaxLen The low byte is the base of the representation, the351 * upper 24 bits are the max length to parse. If the base352 * is zero the function will look for known prefixes before353 * defaulting to 10. A max length of zero means no length354 * restriction.355 * @param pu32 Where to store the converted number. (optional)356 */357 284 RTDECL(int) RTStrToUInt32Ex(const char *pszValue, char **ppszNext, unsigned uBaseAndMaxLen, uint32_t *pu32) 358 285 { … … 371 298 372 299 373 /**374 * Converts a string representation of a number to a 32-bit unsigned number,375 * making sure the full string is converted.376 *377 * @returns iprt status code.378 * Warnings are used to indicate conversion problems.379 * @retval VWRN_NUMBER_TOO_BIG380 * @retval VWRN_NEGATIVE_UNSIGNED381 * @retval VINF_SUCCESS382 * @retval VERR_NO_DIGITS383 * @retval VERR_TRAILING_SPACES384 * @retval VERR_TRAILING_CHARS385 *386 * @param pszValue Pointer to the string value.387 * @param uBaseAndMaxLen The low byte is the base of the representation, the388 * upper 24 bits are the max length to parse. If the base389 * is zero the function will look for known prefixes before390 * defaulting to 10. A max length of zero means no length391 * restriction.392 * @param pu32 Where to store the converted number. (optional)393 */394 300 RTDECL(int) RTStrToUInt32Full(const char *pszValue, unsigned uBaseAndMaxLen, uint32_t *pu32) 395 301 { … … 408 314 409 315 410 /**411 * Converts a string representation of a number to a 64-bit unsigned number.412 * The base is guessed.413 *414 * @returns 32-bit unsigned number on success.415 * @returns 0 on failure.416 * @param pszValue Pointer to the string value.417 */418 316 RTDECL(uint32_t) RTStrToUInt32(const char *pszValue) 419 317 { … … 427 325 428 326 429 /**430 * Converts a string representation of a number to a 16-bit unsigned number.431 *432 * @returns iprt status code.433 * Warnings are used to indicate conversion problems.434 * @retval VWRN_NUMBER_TOO_BIG435 * @retval VWRN_NEGATIVE_UNSIGNED436 * @retval VWRN_TRAILING_CHARS437 * @retval VWRN_TRAILING_SPACES438 * @retval VINF_SUCCESS439 * @retval VERR_NO_DIGITS440 *441 * @param pszValue Pointer to the string value.442 * @param ppszNext Where to store the pointer to the first char443 * following the number. (Optional)444 * @param uBaseAndMaxLen The low byte is the base of the representation, the445 * upper 24 bits are the max length to parse. If the base446 * is zero the function will look for known prefixes before447 * defaulting to 10. A max length of zero means no length448 * restriction.449 * @param pu16 Where to store the converted number. (optional)450 */451 327 RTDECL(int) RTStrToUInt16Ex(const char *pszValue, char **ppszNext, unsigned uBaseAndMaxLen, uint16_t *pu16) 452 328 { … … 465 341 466 342 467 /**468 * Converts a string representation of a number to a 16-bit unsigned number,469 * making sure the full string is converted.470 *471 * @returns iprt status code.472 * Warnings are used to indicate conversion problems.473 * @retval VWRN_NUMBER_TOO_BIG474 * @retval VWRN_NEGATIVE_UNSIGNED475 * @retval VINF_SUCCESS476 * @retval VERR_NO_DIGITS477 * @retval VERR_TRAILING_SPACES478 * @retval VERR_TRAILING_CHARS479 *480 * @param pszValue Pointer to the string value.481 * @param uBaseAndMaxLen The low byte is the base of the representation, the482 * upper 24 bits are the max length to parse. If the base483 * is zero the function will look for known prefixes before484 * defaulting to 10. A max length of zero means no length485 * restriction.486 * @param pu16 Where to store the converted number. (optional)487 */488 343 RTDECL(int) RTStrToUInt16Full(const char *pszValue, unsigned uBaseAndMaxLen, uint16_t *pu16) 489 344 { … … 502 357 503 358 504 /**505 * Converts a string representation of a number to a 16-bit unsigned number.506 * The base is guessed.507 *508 * @returns 16-bit unsigned number on success.509 * @returns 0 on failure.510 * @param pszValue Pointer to the string value.511 */512 359 RTDECL(uint16_t) RTStrToUInt16(const char *pszValue) 513 360 { … … 521 368 522 369 523 /**524 * Converts a string representation of a number to a 8-bit unsigned number.525 *526 * @returns iprt status code.527 * Warnings are used to indicate conversion problems.528 * @retval VWRN_NUMBER_TOO_BIG529 * @retval VWRN_NEGATIVE_UNSIGNED530 * @retval VWRN_TRAILING_CHARS531 * @retval VWRN_TRAILING_SPACES532 * @retval VINF_SUCCESS533 * @retval VERR_NO_DIGITS534 *535 * @param pszValue Pointer to the string value.536 * @param ppszNext Where to store the pointer to the first char537 * following the number. (Optional)538 * @param uBaseAndMaxLen The low byte is the base of the representation, the539 * upper 24 bits are the max length to parse. If the base540 * is zero the function will look for known prefixes before541 * defaulting to 10. A max length of zero means no length542 * restriction.543 * @param pu8 Where to store the converted number. (optional)544 */545 370 RTDECL(int) RTStrToUInt8Ex(const char *pszValue, char **ppszNext, unsigned uBaseAndMaxLen, uint8_t *pu8) 546 371 { … … 559 384 560 385 561 /**562 * Converts a string representation of a number to a 8-bit unsigned number,563 * making sure the full string is converted.564 *565 * @returns iprt status code.566 * Warnings are used to indicate conversion problems.567 * @retval VWRN_NUMBER_TOO_BIG568 * @retval VWRN_NEGATIVE_UNSIGNED569 * @retval VINF_SUCCESS570 * @retval VERR_NO_DIGITS571 * @retval VERR_TRAILING_SPACES572 * @retval VERR_TRAILING_CHARS573 *574 * @param pszValue Pointer to the string value.575 * @param uBaseAndMaxLen The low byte is the base of the representation, the576 * upper 24 bits are the max length to parse. If the base577 * is zero the function will look for known prefixes before578 * defaulting to 10. A max length of zero means no length579 * restriction.580 * @param pu8 Where to store the converted number. (optional)581 */582 386 RTDECL(int) RTStrToUInt8Full(const char *pszValue, unsigned uBaseAndMaxLen, uint8_t *pu8) 583 387 { … … 596 400 597 401 598 /**599 * Converts a string representation of a number to a 8-bit unsigned number.600 * The base is guessed.601 *602 * @returns 8-bit unsigned number on success.603 * @returns 0 on failure.604 * @param pszValue Pointer to the string value.605 */606 402 RTDECL(uint8_t) RTStrToUInt8(const char *pszValue) 607 403 { … … 615 411 616 412 617 618 619 620 621 622 /**623 * Converts a string representation of a number to a 64-bit signed number.624 *625 * @returns iprt status code.626 * Warnings are used to indicate conversion problems.627 * @retval VWRN_NUMBER_TOO_BIG628 * @retval VWRN_TRAILING_CHARS629 * @retval VWRN_TRAILING_SPACES630 * @retval VINF_SUCCESS631 * @retval VERR_NO_DIGITS632 *633 * @param pszValue Pointer to the string value.634 * @param ppszNext Where to store the pointer to the first char635 * following the number. (Optional)636 * @param uBaseAndMaxLen The low byte is the base of the representation, the637 * upper 24 bits are the max length to parse. If the base638 * is zero the function will look for known prefixes before639 * defaulting to 10. A max length of zero means no length640 * restriction.641 * @param pi64 Where to store the converted number. (optional)642 */643 413 RTDECL(int) RTStrToInt64Ex(const char *pszValue, char **ppszNext, unsigned uBaseAndMaxLen, int64_t *pi64) 644 414 { … … 773 543 774 544 775 /**776 * Converts a string representation of a number to a 64-bit signed number,777 * making sure the full string is converted.778 *779 * @returns iprt status code.780 * Warnings are used to indicate conversion problems.781 * @retval VWRN_NUMBER_TOO_BIG782 * @retval VINF_SUCCESS783 * @retval VERR_TRAILING_CHARS784 * @retval VERR_TRAILING_SPACES785 * @retval VERR_NO_DIGITS786 *787 * @param pszValue Pointer to the string value.788 * @param uBaseAndMaxLen The low byte is the base of the representation, the789 * upper 24 bits are the max length to parse. If the base790 * is zero the function will look for known prefixes before791 * defaulting to 10. A max length of zero means no length792 * restriction.793 * @param pi64 Where to store the converted number. (optional)794 */795 545 RTDECL(int) RTStrToInt64Full(const char *pszValue, unsigned uBaseAndMaxLen, int64_t *pi64) 796 546 { … … 821 571 822 572 823 /**824 * Converts a string representation of a number to a 64-bit signed number.825 * The base is guessed.826 *827 * @returns 64-bit signed number on success.828 * @returns 0 on failure.829 * @param pszValue Pointer to the string value.830 */831 573 RTDECL(int64_t) RTStrToInt64(const char *pszValue) 832 574 { … … 840 582 841 583 842 /**843 * Converts a string representation of a number to a 32-bit signed number.844 *845 * @returns iprt status code.846 * Warnings are used to indicate conversion problems.847 * @retval VWRN_NUMBER_TOO_BIG848 * @retval VWRN_TRAILING_CHARS849 * @retval VWRN_TRAILING_SPACES850 * @retval VINF_SUCCESS851 * @retval VERR_NO_DIGITS852 *853 * @param pszValue Pointer to the string value.854 * @param ppszNext Where to store the pointer to the first char855 * following the number. (Optional)856 * @param uBaseAndMaxLen The low byte is the base of the representation, the857 * upper 24 bits are the max length to parse. If the base858 * is zero the function will look for known prefixes before859 * defaulting to 10. A max length of zero means no length860 * restriction.861 * @param pi32 Where to store the converted number. (optional)862 */863 584 RTDECL(int) RTStrToInt32Ex(const char *pszValue, char **ppszNext, unsigned uBaseAndMaxLen, int32_t *pi32) 864 585 { … … 878 599 879 600 880 /**881 * Converts a string representation of a number to a 32-bit signed number,882 * making sure the full string is converted.883 *884 * @returns iprt status code.885 * Warnings are used to indicate conversion problems.886 * @retval VWRN_NUMBER_TOO_BIG887 * @retval VINF_SUCCESS888 * @retval VERR_TRAILING_CHARS889 * @retval VERR_TRAILING_SPACES890 * @retval VERR_NO_DIGITS891 *892 * @param pszValue Pointer to the string value.893 * @param uBaseAndMaxLen The low byte is the base of the representation, the894 * upper 24 bits are the max length to parse. If the base895 * is zero the function will look for known prefixes before896 * defaulting to 10. A max length of zero means no length897 * restriction.898 * @param pi32 Where to store the converted number. (optional)899 */900 601 RTDECL(int) RTStrToInt32Full(const char *pszValue, unsigned uBaseAndMaxLen, int32_t *pi32) 901 602 { … … 915 616 916 617 917 /**918 * Converts a string representation of a number to a 32-bit signed number.919 * The base is guessed.920 *921 * @returns 32-bit signed number on success.922 * @returns 0 on failure.923 * @param pszValue Pointer to the string value.924 */925 618 RTDECL(int32_t) RTStrToInt32(const char *pszValue) 926 619 { … … 934 627 935 628 936 /**937 * Converts a string representation of a number to a 16-bit signed number.938 *939 * @returns iprt status code.940 * Warnings are used to indicate conversion problems.941 * @retval VWRN_NUMBER_TOO_BIG942 * @retval VWRN_TRAILING_CHARS943 * @retval VWRN_TRAILING_SPACES944 * @retval VINF_SUCCESS945 * @retval VERR_NO_DIGITS946 *947 * @param pszValue Pointer to the string value.948 * @param ppszNext Where to store the pointer to the first char949 * following the number. (Optional)950 * @param pszValue Pointer to the string value.951 * @param uBaseAndMaxLen The low byte is the base of the representation, the952 * upper 24 bits are the max length to parse. If the base953 * is zero the function will look for known prefixes before954 * defaulting to 10. A max length of zero means no length955 * restriction.956 * @param pi16 Where to store the converted number. (optional)957 */958 629 RTDECL(int) RTStrToInt16Ex(const char *pszValue, char **ppszNext, unsigned uBaseAndMaxLen, int16_t *pi16) 959 630 { … … 973 644 974 645 975 /**976 * Converts a string representation of a number to a 16-bit signed number,977 * making sure the full string is converted.978 *979 * @returns iprt status code.980 * Warnings are used to indicate conversion problems.981 * @retval VWRN_NUMBER_TOO_BIG982 * @retval VINF_SUCCESS983 * @retval VERR_TRAILING_CHARS984 * @retval VERR_TRAILING_SPACES985 * @retval VERR_NO_DIGITS986 *987 * @param pszValue Pointer to the string value.988 * @param uBaseAndMaxLen The low byte is the base of the representation, the989 * upper 24 bits are the max length to parse. If the base990 * is zero the function will look for known prefixes before991 * defaulting to 10. A max length of zero means no length992 * restriction.993 * @param pi16 Where to store the converted number. (optional)994 */995 646 RTDECL(int) RTStrToInt16Full(const char *pszValue, unsigned uBaseAndMaxLen, int16_t *pi16) 996 647 { … … 1010 661 1011 662 1012 /**1013 * Converts a string representation of a number to a 16-bit signed number.1014 * The base is guessed.1015 *1016 * @returns 16-bit signed number on success.1017 * @returns 0 on failure.1018 * @param pszValue Pointer to the string value.1019 */1020 663 RTDECL(int16_t) RTStrToInt16(const char *pszValue) 1021 664 { … … 1029 672 1030 673 1031 /**1032 * Converts a string representation of a number to a 8-bit signed number.1033 *1034 * @returns iprt status code.1035 * Warnings are used to indicate conversion problems.1036 * @retval VWRN_NUMBER_TOO_BIG1037 * @retval VWRN_TRAILING_CHARS1038 * @retval VWRN_TRAILING_SPACES1039 * @retval VINF_SUCCESS1040 * @retval VERR_NO_DIGITS1041 *1042 * @param pszValue Pointer to the string value.1043 * @param ppszNext Where to store the pointer to the first char1044 * following the number. (Optional)1045 * @param uBaseAndMaxLen The low byte is the base of the representation, the1046 * upper 24 bits are the max length to parse. If the base1047 * is zero the function will look for known prefixes before1048 * defaulting to 10. A max length of zero means no length1049 * restriction.1050 * @param pi8 Where to store the converted number. (optional)1051 */1052 674 RTDECL(int) RTStrToInt8Ex(const char *pszValue, char **ppszNext, unsigned uBaseAndMaxLen, int8_t *pi8) 1053 675 { … … 1067 689 1068 690 1069 /**1070 * Converts a string representation of a number to a 8-bit signed number,1071 * making sure the full string is converted.1072 *1073 * @returns iprt status code.1074 * Warnings are used to indicate conversion problems.1075 * @retval VWRN_NUMBER_TOO_BIG1076 * @retval VINF_SUCCESS1077 * @retval VERR_TRAILING_CHARS1078 * @retval VERR_TRAILING_SPACES1079 * @retval VERR_NO_DIGITS1080 *1081 * @param pszValue Pointer to the string value.1082 * @param uBaseAndMaxLen The low byte is the base of the representation, the1083 * upper 24 bits are the max length to parse. If the base1084 * is zero the function will look for known prefixes before1085 * defaulting to 10. A max length of zero means no length1086 * restriction.1087 * @param pi8 Where to store the converted number. (optional)1088 */1089 691 RTDECL(int) RTStrToInt8Full(const char *pszValue, unsigned uBaseAndMaxLen, int8_t *pi8) 1090 692 { … … 1104 706 1105 707 1106 /**1107 * Converts a string representation of a number to a 8-bit signed number.1108 * The base is guessed.1109 *1110 * @returns 8-bit signed number on success.1111 * @returns 0 on failure.1112 * @param pszValue Pointer to the string value.1113 */1114 708 RTDECL(int8_t) RTStrToInt8(const char *pszValue) 1115 709 { -
trunk/src/VBox/Runtime/common/string/utf-8-case.cpp
r98103 r99758 50 50 51 51 52 /**53 * Performs a case insensitive string compare between two UTF-8 strings.54 *55 * This is a simplified compare, as only the simplified lower/upper case folding56 * specified by the unicode specs are used. It does not consider character pairs57 * as they are used in some languages, just simple upper & lower case compares.58 *59 * The result is the difference between the mismatching codepoints after they60 * both have been lower cased.61 *62 * If the string encoding is invalid the function will assert (strict builds)63 * and use RTStrCmp for the remainder of the string.64 *65 * @returns < 0 if the first string less than the second string.66 * @returns 0 if the first string identical to the second string.67 * @returns > 0 if the first string greater than the second string.68 * @param psz1 First UTF-8 string. Null is allowed.69 * @param psz2 Second UTF-8 string. Null is allowed.70 */71 52 RTDECL(int) RTStrICmp(const char *psz1, const char *psz2) 72 53 { … … 125 106 126 107 127 /**128 * Performs a case insensitive string compare between two UTF-8 strings, given a129 * maximum string length.130 *131 * This is a simplified compare, as only the simplified lower/upper case folding132 * specified by the unicode specs are used. It does not consider character pairs133 * as they are used in some languages, just simple upper & lower case compares.134 *135 * The result is the difference between the mismatching codepoints after they136 * both have been lower cased.137 *138 * If the string encoding is invalid the function will assert (strict builds)139 * and use RTStrCmp for the remainder of the string.140 *141 * @returns < 0 if the first string less than the second string.142 * @returns 0 if the first string identical to the second string.143 * @returns > 0 if the first string greater than the second string.144 * @param psz1 First UTF-8 string. Null is allowed.145 * @param psz2 Second UTF-8 string. Null is allowed.146 * @param cchMax Maximum string length147 */148 108 RTDECL(int) RTStrNICmp(const char *psz1, const char *psz2, size_t cchMax) 149 109 { -
trunk/src/VBox/Runtime/common/time/time.cpp
r98103 r99758 275 275 276 276 277 /**278 * Checks if a year is a leap year or not.279 *280 * @returns true if it's a leap year.281 * @returns false if it's a common year.282 * @param i32Year The year in question.283 */284 277 RTDECL(bool) RTTimeIsLeapYear(int32_t i32Year) 285 278 { … … 289 282 290 283 291 /**292 * Explodes a time spec (UTC).293 *294 * @returns pTime.295 * @param pTime Where to store the exploded time.296 * @param pTimeSpec The time spec to exploded.297 */298 284 RTDECL(PRTTIME) RTTimeExplode(PRTTIME pTime, PCRTTIMESPEC pTimeSpec) 299 285 { … … 401 387 402 388 403 /**404 * Implodes exploded time to a time spec (UTC).405 *406 * @returns pTime on success.407 * @returns NULL if the pTime data is invalid.408 * @param pTimeSpec Where to store the imploded UTC time.409 * If pTime specifies a time which outside the range, maximum or410 * minimum values will be returned.411 * @param pTime Pointer to the exploded time to implode.412 * The fields u8Month, u8WeekDay and u8MonthDay are not used,413 * and all the other fields are expected to be within their414 * bounds. Use RTTimeNormalize() or RTTimeLocalNormalize() to415 * calculate u16YearDay and normalize the ranges of the fields.416 */417 389 RTDECL(PRTTIMESPEC) RTTimeImplode(PRTTIMESPEC pTimeSpec, PCRTTIME pTime) 418 390 { … … 679 651 680 652 681 /**682 * Normalizes the fields of a time structure.683 *684 * It is possible to calculate year-day from month/day and vice685 * versa. If you adjust any of these, make sure to zero the686 * other so you make it clear which of the fields to use. If687 * it's ambiguous, the year-day field is used (and you get688 * assertions in debug builds).689 *690 * All the time fields and the year-day or month/day fields will691 * be adjusted for overflows. (Since all fields are unsigned, there692 * is no underflows.) It is possible to exploit this for simple693 * date math, though the recommended way of doing that to implode694 * the time into a timespec and do the math on that.695 *696 * @returns pTime on success.697 * @returns NULL if the data is invalid.698 *699 * @param pTime The time structure to normalize.700 *701 * @remarks This function doesn't work with local time, only with UTC time.702 */703 653 RTDECL(PRTTIME) RTTimeNormalize(PRTTIME pTime) 704 654 { … … 719 669 720 670 721 /**722 * Normalizes the fields of a time structure, assuming local time.723 *724 * It is possible to calculate year-day from month/day and vice725 * versa. If you adjust any of these, make sure to zero the726 * other so you make it clear which of the fields to use. If727 * it's ambiguous, the year-day field is used (and you get728 * assertions in debug builds).729 *730 * All the time fields and the year-day or month/day fields will731 * be adjusted for overflows. (Since all fields are unsigned, there732 * is no underflows.) It is possible to exploit this for simple733 * date math, though the recommended way of doing that to implode734 * the time into a timespec and do the math on that.735 *736 * @returns pTime on success.737 * @returns NULL if the data is invalid.738 *739 * @param pTime The time structure to normalize.740 *741 * @remarks This function doesn't work with UTC time, only with local time.742 */743 671 RTDECL(PRTTIME) RTTimeLocalNormalize(PRTTIME pTime) 744 672 { … … 758 686 759 687 760 /**761 * Converts a time spec to a ISO date string.762 *763 * @returns psz on success.764 * @returns NULL on buffer underflow.765 * @param pTime The time. Caller should've normalized this.766 * @param psz Where to store the string.767 * @param cb The size of the buffer.768 */769 688 RTDECL(char *) RTTimeToString(PCRTTIME pTime, char *psz, size_t cb) 770 689 { … … 810 729 811 730 812 /**813 * Converts a time spec to a ISO date string, extended version.814 *815 * @returns Output string length on success (positive), VERR_BUFFER_OVERFLOW816 * (negative) or VERR_OUT_OF_RANGE (negative) on failure.817 * @param pTime The time. Caller should've normalized this.818 * @param psz Where to store the string.819 * @param cb The size of the buffer.820 * @param cFractionDigits Number of digits in the fraction. Max is 9.821 */822 731 RTDECL(ssize_t) RTTimeToStringEx(PCRTTIME pTime, char *psz, size_t cb, unsigned cFractionDigits) 823 732 { … … 878 787 879 788 880 /**881 * Converts a time spec to a ISO date string.882 *883 * @returns psz on success.884 * @returns NULL on buffer underflow.885 * @param pTime The time spec.886 * @param psz Where to store the string.887 * @param cb The size of the buffer.888 */889 789 RTDECL(char *) RTTimeSpecToString(PCRTTIMESPEC pTime, char *psz, size_t cb) 890 790 { … … 896 796 897 797 898 /**899 * Attempts to convert an ISO date string to a time structure.900 *901 * We're a little forgiving with zero padding, unspecified parts, and leading902 * and trailing spaces.903 *904 * @retval pTime on success,905 * @retval NULL on failure.906 * @param pTime Where to store the time on success.907 * @param pszString The ISO date string to convert.908 */909 798 RTDECL(PRTTIME) RTTimeFromString(PRTTIME pTime, const char *pszString) 910 799 { … … 1072 961 1073 962 1074 /**1075 * Attempts to convert an ISO date string to a time structure.1076 *1077 * We're a little forgiving with zero padding, unspecified parts, and leading1078 * and trailing spaces.1079 *1080 * @retval pTime on success,1081 * @retval NULL on failure.1082 * @param pTime The time spec.1083 * @param pszString The ISO date string to convert.1084 */1085 963 RTDECL(PRTTIMESPEC) RTTimeSpecFromString(PRTTIMESPEC pTime, const char *pszString) 1086 964 { … … 1093 971 1094 972 1095 /**1096 * Formats the given time on a RTC-2822 compliant format.1097 *1098 * @returns Output string length on success (positive), VERR_BUFFER_OVERFLOW1099 * (negative) on failure.1100 * @param pTime The time. Caller should've normalized this.1101 * @param psz Where to store the string.1102 * @param cb The size of the buffer.1103 */1104 973 RTDECL(ssize_t) RTTimeToRfc2822(PRTTIME pTime, char *psz, size_t cb, uint32_t fFlags) 1105 974 { … … 1161 1030 1162 1031 1163 /**1164 * Attempts to convert an RFC-2822 date string to a time structure.1165 *1166 * We're a little forgiving with zero padding, unspecified parts, and leading1167 * and trailing spaces.1168 *1169 * @retval pTime on success,1170 * @retval NULL on failure.1171 * @param pTime Where to store the time on success.1172 * @param pszString The ISO date string to convert.1173 */1174 1032 RTDECL(PRTTIME) RTTimeFromRfc2822(PRTTIME pTime, const char *pszString) 1175 1033 { … … 1552 1410 1553 1411 1554 /**1555 * Converts a time structure to UTC, relying on UTC offset information if it contains local time.1556 *1557 * @returns pTime on success.1558 * @returns NULL if the data is invalid.1559 * @param pTime The time structure to convert.1560 */1561 1412 RTDECL(PRTTIME) RTTimeConvertToZulu(PRTTIME pTime) 1562 1413 { … … 1572 1423 1573 1424 1574 /**1575 * Compares two normalized time structures.1576 *1577 * @retval 0 if equal.1578 * @retval -1 if @a pLeft is earlier than @a pRight.1579 * @retval 1 if @a pRight is earlier than @a pLeft.1580 *1581 * @param pLeft The left side time. NULL is accepted.1582 * @param pRight The right side time. NULL is accepted.1583 *1584 * @note A NULL time is considered smaller than anything else. If both are1585 * NULL, they are considered equal.1586 */1587 1425 RTDECL(int) RTTimeCompare(PCRTTIME pLeft, PCRTTIME pRight) 1588 1426 {
Note:
See TracChangeset
for help on using the changeset viewer.
