VirtualBox

Changeset 99758 in vbox


Ignore:
Timestamp:
May 11, 2023 9:37:59 PM (2 years ago)
Author:
vboxsync
svn:sync-xref-src-repo-rev:
157349
Message:

IPRT: Make doxygen 1.9.6 happy. Mostly removing duplicate docs (iprt is documented in the header files). bugref:10442

Location:
trunk/src/VBox/Runtime
Files:
37 edited

Legend:

Unmodified
Added
Removed

  • trunk/src/VBox/Runtime/Doxyfile

    r99739 r99758  
    248248ALIASES += ecma{3}="<a href=\"https://www.ecma-international.org/publications/files/ECMA-ST/Ecma-\1.pdf#page=\3\">ECMA-\1:\2</a>"
    249249# ECMA-167 spec reference - 1=part 2=section, 3=page
    250 ALIASES += ecma167{3}=\ecma{167,Part\1/\2,\3}
     250ALIASES += "ecma167{3}=\ecma{167,Part\1/\2,\3}"
    251251
    252252# This tag can be used to specify a number of word-keyword mappings (TCL only).
    … …  
    16671667# This tag requires that the tag GENERATE_LATEX is set to YES.
    16681668
    1669 PAPER_TYPE             = a4wide
     1669PAPER_TYPE             = a4
    16701670
    16711671# The EXTRA_PACKAGES tag can be used to specify one or more LaTeX package names
    … …  
    21402140    RTCALL=
    21412141
     2142# context hacks.
     2143PREDEFINED            += RCPTRTYPE(RCType)=RCType
     2144PREDEFINED            += R3PTRTYPE(R3Type)=R3Type
     2145PREDEFINED            += R0PTRTYPE(R0Type)=R0Type
     2146PREDEFINED            += HCPTRTYPE(HCType)=HCType
     2147PREDEFINED            += R3R0PTRTYPE(R3R0Type)=R3R0Type
     2148PREDEFINED += \
     2149        "CTX_SUFF(var)=var##R3" \
     2150        "CTX_SUFF_Z(var)=var##RZ" \
     2151        "CTX_MID(first,last)=firstr##R3##last" \
     2152        "CTX_MID_Z(first,last)=firstr##RZ##last" \
     2153
    21422154# If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this
    21432155# tag can be used to specify a list of macro names that should be expanded. The
    … …  
    21542166                         GCTYPE \
    21552167                         GCPTRTYPE \
    2156                          HCPTRTYPE \
    2157                          R0PTRTYPE \
    2158                          R3PTRTYPE \
    2159                          R3R0PTRTYPE \
    21602168                         DECLASMTYPE \
    21612169                         RTR3DECL \

  • trunk/src/VBox/Runtime/common/checksum/crc64.cpp

    r98103 r99758  
    161161
    162162
    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  */
    170163RTDECL(uint64_t) RTCrc64(const void *pv, size_t cb)
    171164{
    … …  
    179172
    180173
    181 /**
    182  * Start a multiblock CRC64 calculation.
    183  *
    184  * @returns Start CRC64.
    185  */
    186174RTDECL(uint64_t) RTCrc64Start(void)
    187175{
    … …  
    191179
    192180
    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  */
    201181RTDECL(uint64_t) RTCrc64Process(uint64_t uCRC64, const void *pv, size_t cb)
    202182{
    … …  
    209189
    210190
    211 /**
    212  * Complete a multiblock CRC64 calculation.
    213  *
    214  * @returns CRC64 value.
    215  * @param   uCRC64  Current CRC64 intermediate value.
    216  */
    217191RTDECL(uint64_t) RTCrc64Finish(uint64_t uCRC64)
    218192{

  • trunk/src/VBox/Runtime/common/checksum/manifest2.cpp

    r98103 r99758  
    192192
    193193
    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  */
    201194RTDECL(int) RTManifestCreate(uint32_t fFlags, PRTMANIFEST phManifest)
    202195{
    … …  
    223216}
    224217
    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
    231219RTDECL(uint32_t) RTManifestRetain(RTMANIFEST hManifest)
    232220{
    … …  
    268256
    269257
    270 /**
    271  * Releases a reference to the manifest handle.
    272  *
    273  * @returns The new reference count, 0 if free. UINT32_MAX is returned if the
    274  *          handle is invalid.
    275  * @param   hManifest           The handle to release.
    276  *                              NIL is quietly ignored (returns 0).
    277  */
    278258RTDECL(uint32_t) RTManifestRelease(RTMANIFEST hManifest)
    279259{
    … …  
    298278
    299279
    300 /**
    301  * Creates a duplicate of the specified manifest.
    302  *
    303  * @returns IPRT status code
    304  * @param   hManifestSrc        The manifest to clone.
    305  * @param   phManifestDst       Where to store the handle to the duplicate.
    306  */
    307280RTDECL(int) RTManifestDup(RTMANIFEST hManifestSrc, PRTMANIFEST phManifestDst)
    308281{
    … …  
    740713
    741714
    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, pass
    751  *                              RTMANIFEST_ATTR_UNKNOWN if not known.
    752  */
    753715RTDECL(int) RTManifestSetAttr(RTMANIFEST hManifest, const char *pszAttr, const char *pszValue, uint32_t fType)
    754716{
    … …  
    784746
    785747
    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  */
    795748RTDECL(int) RTManifestUnsetAttr(RTMANIFEST hManifest, const char *pszAttr)
    796749{
    … …  
    1041994
    1042995
    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 be
    1049  *                              added if there was no previous call to
    1050  *                              RTManifestEntryAdd for this name.  See
    1051  *                              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, pass
    1056  *                              RTMANIFEST_ATTR_UNKNOWN if not known.
    1057  */
    1058996RTDECL(int) RTManifestEntrySetAttr(RTMANIFEST hManifest, const char *pszEntry, const char *pszAttr,
    1059997                                   const char *pszValue, uint32_t fType)
    … …  
    11071045
    11081046
    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  */
    11191047RTDECL(int) RTManifestEntryUnsetAttr(RTMANIFEST hManifest, const char *pszEntry, const char *pszAttr)
    11201048{
    … …  
    11671095
    11681096
    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, except
    1174  *       control characters, ':', '(' and ')'.  The exceptions are mainly there
    1175  *       because of uncertainty around how various formats handles these.
    1176  *     - It is considered case sensitive.
    1177  *     - Forward (unix) and backward (dos) slashes are considered path
    1178  *       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 without
    1187  *          any attributes.  So, this is just here in case it comes in handy
    1188  *          when dealing with formats which can.
    1189  */
    11901097RTDECL(int) RTManifestEntryAdd(RTMANIFEST hManifest, const char *pszEntry)
    11911098{
    … …  
    12391146
    12401147
    1241 /**
    1242  * Removes an entry.
    1243  *
    1244  * @returns IPRT status code.
    1245  * @param   hManifest           The manifest handle.
    1246  * @param   pszEntry            The entry name.
    1247  */
    12481148RTDECL(int) RTManifestEntryRemove(RTMANIFEST hManifest, const char *pszEntry)
    12491149{

  • trunk/src/VBox/Runtime/common/checksum/manifest3.cpp

    r98103 r99758  
    533533
    534534
    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 the
    539  * stream and automatically add an entry to the manifest with the desired
    540  * attributes when it is released.  Alternatively one can call
    541  * RTManifestPtIosAddEntryNow() to have more control over exactly when this
    542  * 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  */
    552535RTDECL(int) RTManifestEntryAddPassthruIoStream(RTMANIFEST hManifest, RTVFSIOSTREAM hVfsIos, const char *pszEntry,
    553536                                               uint32_t fAttrs, bool fReadOrWrite, PRTVFSIOSTREAM phVfsIosPassthru)
    … …  
    602585
    603586
    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 by
    609  *                              RTManifestEntryAddPassthruIoStream().
    610  */
    611587RTDECL(int) RTManifestPtIosAddEntryNow(RTVFSIOSTREAM hVfsPtIos)
    612588{
    … …  
    621597
    622598
    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  */
    629599RTDECL(bool) RTManifestPtIosIsInstanceOf(RTVFSIOSTREAM hVfsPtIos)
    630600{
    … …  
    639609
    640610
    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 will
    648  *                              be processed to its end on successful return.
    649  *                              (Must be positioned at the start to get
    650  *                              the expected results.)
    651  * @param   pszEntry            The entry name.
    652  * @param   fAttrs              The attributes to create for this stream.
    653  */
    654611RTDECL(int) RTManifestEntryAddIoStream(RTMANIFEST hManifest, RTVFSIOSTREAM hVfsIos, const char *pszEntry, uint32_t fAttrs)
    655612{

  • trunk/src/VBox/Runtime/common/dbg/dbgas.cpp

    r98103 r99758  
    185185
    186186
    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  */
    197187RTDECL(int) RTDbgAsCreate(PRTDBGAS phDbgAs, RTUINTPTR FirstAddr, RTUINTPTR LastAddr, const char *pszName)
    198188{
    … …  
    238228
    239229
    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  */
    251230RTDECL(int) RTDbgAsCreateV(PRTDBGAS phDbgAs, RTUINTPTR FirstAddr, RTUINTPTR LastAddr, const char *pszNameFmt, va_list va)
    252231{
    … …  
    266245
    267246
    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  */
    279247RTDECL(int) RTDbgAsCreateF(PRTDBGAS phDbgAs, RTUINTPTR FirstAddr, RTUINTPTR LastAddr, const char *pszNameFmt, ...)
    280248{
    … …  
    361329
    362330
    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  */
    372331RTDECL(uint32_t) RTDbgAsRetain(RTDBGAS hDbgAs)
    373332{
    … …  
    379338
    380339
    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, potentially
    386  * causing some or all of them to be destroyed as they are managed by
    387  * 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 quietly
    392  *                          ignored and 0 is returned.
    393  *
    394  * @remarks Will not take any locks.
    395  */
    396340RTDECL(uint32_t) RTDbgAsRelease(RTDBGAS hDbgAs)
    397341{
    … …  
    429373
    430374
    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  */
    441375RTDECL(const char *) RTDbgAsName(RTDBGAS hDbgAs)
    442376{
    … …  
    448382
    449383
    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  */
    460384RTDECL(RTUINTPTR) RTDbgAsFirstAddr(RTDBGAS hDbgAs)
    461385{
    … …  
    467391
    468392
    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  */
    479393RTDECL(RTUINTPTR) RTDbgAsLastAddr(RTDBGAS hDbgAs)
    480394{
    … …  
    485399RT_EXPORT_SYMBOL(RTDbgAsLastAddr);
    486400
    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
    499402RTDECL(uint32_t) RTDbgAsModuleCount(RTDBGAS hDbgAs)
    500403{
    … …  
    650553
    651554
    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 module
    659  *          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  */
    667555RTDECL(int) RTDbgAsModuleLink(RTDBGAS hDbgAs, RTDBGMOD hDbgMod, RTUINTPTR ImageAddr, uint32_t fFlags)
    668556{
    … …  
    697585
    698586
    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 module
    706  *          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 be
    712  *                          linked in.
    713  * @param   SegAddr         The address to link the segment at.
    714  * @param   fFlags          See RTDBGASLINK_FLAGS_*.
    715  */
    716587RTDECL(int) RTDbgAsModuleLinkSeg(RTDBGAS hDbgAs, RTDBGMOD hDbgMod, RTDBGSEGIDX iSeg, RTUINTPTR SegAddr, uint32_t fFlags)
    717588{
    … …  
    874745
    875746
    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  */
    885747RTDECL(int) RTDbgAsModuleUnlink(RTDBGAS hDbgAs, RTDBGMOD hDbgMod)
    886748{
    … …  
    914776
    915777
    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  */
    925778RTDECL(int) RTDbgAsModuleUnlinkByAddr(RTDBGAS hDbgAs, RTUINTPTR Addr)
    926779{
    … …  
    950803
    951804
    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 release
    956  *          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 and
    964  *          RTDbgAsModuleUnlinkByAddr.
    965  */
    966805RTDECL(RTDBGMOD) RTDbgAsModuleByIndex(RTDBGAS hDbgAs, uint32_t iModule)
    967806{
    … …  
    991830
    992831
    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 to
    1006  *                          NIL if the entire module is mapped as a single
    1007  *                          mapping. Optional.
    1008  */
    1009832RTDECL(int) RTDbgAsModuleByAddr(RTDBGAS hDbgAs, RTUINTPTR Addr, PRTDBGMOD phMod, PRTUINTPTR pAddr, PRTDBGSEGIDX piSeg)
    1010833{
    … …  
    1043866
    1044867
    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 name
    1055  *                          in an address space. This argument indicates which
    1056  *                          is meant. (0 based)
    1057  * @param   phMod           Where to the return the retained module handle.
    1058  */
    1059868RTDECL(int) RTDbgAsModuleByName(RTDBGAS hDbgAs, const char *pszName, uint32_t iName, PRTDBGMOD phMod)
    1060869{
    … …  
    1098907
    1099908
    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 returned
    1107  *          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 buffer
    1112  *                          size is given by *pcMappings.
    1113  * @param   pcMappings      IN: Size of the paMappings array. OUT: The number of
    1114  *                          entries returned.
    1115  * @param   fFlags          Flags for reserved for future use. MBZ.
    1116  *
    1117  * @remarks See remarks for RTDbgAsModuleByIndex regarding the volatility of the
    1118  *          iModule parameter.
    1119  */
    1120909RTDECL(int) RTDbgAsModuleQueryMapByIndex(RTDBGAS hDbgAs, uint32_t iModule, PRTDBGASMAPINFO paMappings, uint32_t *pcMappings, uint32_t fFlags)
    1121910{
    … …  
    12731062
    12741063
    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 adding
    1282  *          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. If
    1290  *                          the interpreter doesn't do ordinals, this will be set to
    1291  *                          UINT32_MAX. Optional
    1292  */
    12931064RTDECL(int) RTDbgAsSymbolAdd(RTDBGAS hDbgAs, const char *pszSymbol, RTUINTPTR Addr, RTUINTPTR cb, uint32_t fFlags, uint32_t *piOrdinal)
    12941065{
    … …  
    13461117
    13471118
    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 and
    1360  *                          address. Optional.
    1361  * @param   pSymbol         Where to return the symbol info.
    1362  * @param   phMod           Where to return the module handle. Optional.
    1363  */
    13641119RTDECL(int) RTDbgAsSymbolByAddr(RTDBGAS hDbgAs, RTUINTPTR Addr, uint32_t fFlags,
    13651120                                PRTINTPTR poffDisp, PRTDBGSYMBOL pSymbol, PRTDBGMOD phMod)
    … …  
    14391194
    14401195
    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 symbol
    1453  *                          and address. Optional.
    1454  * @param   ppSymInfo       Where to return the pointer to the allocated symbol
    1455  *                          info. Always set. Free with RTDbgSymbolFree.
    1456  * @param   phMod           Where to return the module handle. Optional.
    1457  */
    14581196RTDECL(int) RTDbgAsSymbolByAddrA(RTDBGAS hDbgAs, RTUINTPTR Addr, uint32_t fFlags,
    14591197                                 PRTINTPTR poffDisp, PRTDBGSYMBOL *ppSymInfo, PRTDBGMOD phMod)
    … …  
    15581296
    15591297
    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 scope
    1568  *                          of the search by prefixing the symbol with a module
    1569  *                          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  */
    15741298RTDECL(int) RTDbgAsSymbolByName(RTDBGAS hDbgAs, const char *pszSymbol, PRTDBGSYMBOL pSymbol, PRTDBGMOD phMod)
    15751299{
    … …  
    16341358
    16351359
    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 allocated
    1645  *                          symbol info. Always set. Free with RTDbgSymbolFree.
    1646  * @param   phMod           Where to return the module handle. Optional.
    1647  */
    16481360RTDECL(int) RTDbgAsSymbolByNameA(RTDBGAS hDbgAs, const char *pszSymbol, PRTDBGSYMBOL *ppSymbol, PRTDBGMOD phMod)
    16491361{
    … …  
    17091421
    17101422
    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 adding
    1718  *          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 be
    1726  *                          set to UINT32_MAX. Optional.
    1727  */
    17281423RTDECL(int) RTDbgAsLineAdd(RTDBGAS hDbgAs, const char *pszFile, uint32_t uLineNo, RTUINTPTR Addr, uint32_t *piOrdinal)
    17291424{

  • trunk/src/VBox/Runtime/common/ldr/ldrEx.cpp

    r98103 r99758  
    227227
    228228
    229 /**
    230  * Loads the image into a buffer provided by the user and applies fixups
    231  * 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  */
    243229RTDECL(int) RTLdrGetBits(RTLDRMOD hLdrMod, void *pvBits, RTLDRADDR BaseAddress, PFNRTLDRIMPORT pfnGetImport, void *pvUser)
    244230{
    … …  
    265251
    266252
    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  */
    281253RTDECL(int) RTLdrRelocate(RTLDRMOD hLdrMod, void *pvBits, RTLDRADDR NewBaseAddress, RTLDRADDR OldBaseAddress,
    282254                          PFNRTLDRIMPORT pfnGetImport, void *pvUser)
    … …  
    381353
    382354
    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  */
    396355RTDECL(int) RTLdrEnumSymbols(RTLDRMOD hLdrMod, unsigned fFlags, const void *pvBits, RTLDRADDR BaseAddress,
    397356                             PFNRTLDRENUMSYMS pfnCallback, void *pvUser)
    … …  
    792751
    793752
    794 /**
    795  * Translates a RTLDRARCH value to a string.
    796  *
    797  * @returns Name corresponding to @a enmArch
    798  * @param   enmArch             The value to name.
    799  */
    800753RTDECL(const char *) RTLdrArchName(RTLDRARCH enmArch)
    801754{

  • trunk/src/VBox/Runtime/common/ldr/ldrNative.cpp

    r98103 r99758  
    102102
    103103
    104 /**
    105  * Loads a dynamic load library (/shared object) image file using native
    106  * OS facilities.
    107  *
    108  * The filename will be appended the default DLL/SO extension of
    109  * the platform if it have been omitted. This means that it's not
    110  * 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 library
    114  * 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  */
    120104RTDECL(int) RTLdrLoad(const char *pszFilename, PRTLDRMOD phLdrMod)
    121105{
    … …  
    251235
    252236
    253 /**
    254  * Loads a dynamic load library (/shared object) image file residing in the
    255  * 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  */
    263237RTDECL(int) RTLdrLoadAppPriv(const char *pszFilename, PRTLDRMOD phLdrMod)
    264238{
    … …  
    317291
    318292
    319 /**
    320  * Gets the default file suffix for DLL/SO/DYLIB/whatever.
    321  *
    322  * @returns The stuff (readonly).
    323  */
    324293RTDECL(const char *) RTLdrGetSuff(void)
    325294{

  • trunk/src/VBox/Runtime/common/log/log.cpp

    r98103 r99758  
    609609
    610610
    611 /**
    612  * Sets the default logger instance.
    613  *
    614  * @returns iprt status code.
    615  * @param   pLogger     The new default logger instance.
    616  */
    617611RTDECL(PRTLOGGER) RTLogSetDefaultInstance(PRTLOGGER pLogger)
    618612{
    … …  
    735729
    736730
    737 /**
    738  * Sets the default logger instance.
    739  *
    740  * @returns iprt status code.
    741  * @param   pLogger     The new default release logger instance.
    742  */
    743731RTDECL(PRTLOGGER) RTLogRelSetDefaultInstance(PRTLOGGER pLogger)
    744732{
    … …  
    757745
    758746
    759 /**
    760  *
    761  * This is the 2nd half of what RTLogGetDefaultInstanceEx() and
    762  * RTLogRelGetDefaultInstanceEx() does.
    763  *
    764  * @returns If the group has the specified flags enabled @a pLogger will be
    765  *          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 in
    768  *                          the high 16 bits.
    769  */
    770747RTDECL(PRTLOGGER)   RTLogCheckGroupFlags(PRTLOGGER pLogger, uint32_t fFlagsAndGroup)
    771748{
    … …  
    15551532
    15561533
    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  */
    15651534RTDECL(int) RTLogDestroy(PRTLOGGER pLogger)
    15661535{
    … …  
    16431612
    16441613
    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  *  */
    16531614RTDECL(int) RTLogSetCustomPrefixCallback(PRTLOGGER pLogger, PFNRTLOGPREFIX pfnCallback, void *pvUser)
    16541615{
    … …  
    16731634
    16741635
    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  */
    16861636RTDECL(int) RTLogSetFlushCallback(PRTLOGGER pLogger, PFNRTLOGFLUSH pfnFlush)
    16871637{
    … …  
    17831733
    17841734
    1785 /**
    1786  * Updates the group settings for the logger instance using the specified
    1787  * 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  */
    17941735RTDECL(int) RTLogGroupSettings(PRTLOGGER pLogger, const char *pszValue)
    17951736{
    … …  
    20321973
    20331974
    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 greater
    2041  *                              than zero.
    2042  */
    20431975RTDECL(int) RTLogQueryGroupSettings(PRTLOGGER pLogger, char *pszBuf, size_t cchBuf)
    20441976{
    … …  
    20912023
    20922024
    2093 /**
    2094  * Updates the flags for the logger instance using the specified
    2095  * 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  */
    21022025RTDECL(int) RTLogFlags(PRTLOGGER pLogger, const char *pszValue)
    21032026{
    … …  
    21782101
    21792102
    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 the
    2187  *                          default logger).
    2188  * @param   fBuffered       The new state.
    2189  */
    21902103RTDECL(bool) RTLogSetBuffering(PRTLOGGER pLogger, bool fBuffered)
    21912104{
    … …  
    22752188#endif /* IN_RING0 */
    22762189
    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  */
    22832190RTDECL(uint64_t) RTLogGetFlags(PRTLOGGER pLogger)
    22842191{
    … …  
    22912198
    22922199
    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 @a
    2297  *          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 to
    2301  *                          include invalid flags - e.g. UINT64_MAX is okay.
    2302  */
    23032200RTDECL(int) RTLogChangeFlags(PRTLOGGER pLogger, uint64_t fSet, uint64_t fClear)
    23042201{
    … …  
    23232220
    23242221
    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 greater
    2332  *                              than zero.
    2333  */
    23342222RTDECL(int) RTLogQueryFlags(PRTLOGGER pLogger, char *pszBuf, size_t cchBuf)
    23352223{
    … …  
    24192307
    24202308
    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  */
    24282309RTDECL(int) RTLogDestinations(PRTLOGGER pLogger, char const *pszValue)
    24292310{
    … …  
    26162497
    26172498
    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  */
    26252499RTDECL(int) RTLogClearFileDelayFlag(PRTLOGGER pLogger, PRTERRINFO pErrInfo)
    26262500{
    … …  
    26552529
    26562530
    2657 /**
    2658  * Modifies the log destinations settings for the given logger.
    2659  *
    2660  * This is only suitable for simple destination settings that doesn't take
    2661  * additional arguments, like RTLOGDEST_FILE.
    2662  *
    2663  * @returns IPRT status code.  Returns VINF_LOG_NO_LOGGER if VINF_LOG_NO_LOGGER
    2664  *          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  */
    26692531RTDECL(int) RTLogChangeDestinations(PRTLOGGER pLogger, uint32_t fSet, uint32_t fClear)
    26702532{
    … …  
    26922554
    26932555
    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  */
    27002556RTDECL(uint32_t) RTLogGetDestinations(PRTLOGGER pLogger)
    27012557{
    … …  
    27122568
    27132569
    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 greater
    2721  *                              than 0.
    2722  */
    27232570RTDECL(int) RTLogQueryDestinations(PRTLOGGER pLogger, char *pszBuf, size_t cchBuf)
    27242571{
    … …  
    30692916*********************************************************************************************************************************/
    30702917
    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-0
    3075  * 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      RTLogQueryBulk
    3084  */
    30852918RTDECL(int) RTLogBulkUpdate(PRTLOGGER pLogger, uint64_t fFlags, uint32_t uGroupCrc32, uint32_t cGroups, uint32_t const *pafGroups)
    30862919{
    … …  
    31122945
    31132946
    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-0
    3118  * loggers.
    3119  *
    3120  * @returns IPRT status code.
    3121  * @retval  VERR_BUFFER_OVERFLOW if pafGroups is too small, @a pcGroups will be
    3122  *          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      RTLogBulkUpdate
    3130  */
    31312947RTDECL(int) RTLogQueryBulk(PRTLOGGER pLogger, uint64_t *pfFlags, uint32_t *puGroupCrc32, uint32_t *pcGroups, uint32_t *pafGroups)
    31322948{
    … …  
    31562972
    31572973
    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 the
    3162  * ring-3 one.  The text goes in as-is w/o any processing (i.e. prefixing or
    3163  * 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  */
    31722974RTDECL(int) RTLogBulkWrite(PRTLOGGER pLogger, const char *pszBefore, const char *pch, size_t cch, const char *pszAfter)
    31732975{
    … …  
    32423044
    32433045
    3244 /**
    3245  * Write/copy bulk log data from a nested VM logger.
    3246  *
    3247  * This is used for
    3248  *
    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 the
    3254  *                              line content.
    3255  */
    32563046RTDECL(int) RTLogBulkNestedWrite(PRTLOGGER pLogger, const char *pch, size_t cch, const char *pszInfix)
    32573047{
    … …  
    33183108*********************************************************************************************************************************/
    33193109
    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 instance
    3325  *                      will not be initialized by this call.
    3326  */
    33273110RTDECL(int) RTLogFlush(PRTLOGGER pLogger)
    33283111{
    … …  
    43564139
    43574140
    4358 /**
    4359  * Write to a logger instance.
    4360  *
    4361  * This function will check whether the instance, group and flags makes up a
    4362  * 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 error
    4365  *          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 is
    4370  *                      only for internal usage!
    4371  * @param   pszFormat   Format string.
    4372  * @param   args        Format arguments.
    4373  */
    43744141RTDECL(int) RTLogLoggerExV(PRTLOGGER pLogger, unsigned fFlags, unsigned iGroup, const char *pszFormat, va_list args)
    43754142{
    … …  
    44454212
    44464213
    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  */
    44544214RTDECL(void) RTLogLoggerV(PRTLOGGER pLogger, const char *pszFormat, va_list args)
    44554215{
    … …  
    44594219
    44604220
    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  */
    44694221RTDECL(void) RTLogPrintfV(const char *pszFormat, va_list va)
    44704222{
    … …  
    44744226
    44754227
    4476 /**
    4477  * Dumper vprintf-like function outputting to a logger.
    4478  *
    4479  * @param   pvUser          Pointer to the logger instance to use, NULL for
    4480  *                          default instance.
    4481  * @param   pszFormat       Format string.
    4482  * @param   va              Format arguments.
    4483  */
    44844228RTDECL(void) RTLogDumpPrintfV(void *pvUser, const char *pszFormat, va_list va)
    44854229{

  • trunk/src/VBox/Runtime/common/misc/inifile.cpp

    r98103 r99758  
    315315
    316316
    317 /**
    318  * Creates a INI-file instance from a VFS file handle.
    319  *
    320  * @returns IPRT status code
    321  * @param   phIniFile       Where to return the INI-file handle.
    322  * @param   hVfsFile        The VFS file handle (not consumed, additional
    323  *                          reference is retained).
    324  * @param   fFlags          Flags, RTINIFILE_F_XXX.
    325  */
    326317RTDECL(int) RTIniFileCreateFromVfsFile(PRTINIFILE phIniFile, RTVFSFILE hVfsFile, uint32_t fFlags)
    327318{
    … …  
    361352
    362353
    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  */
    369354RTDECL(uint32_t) RTIniFileRetain(RTINIFILE hIniFile)
    370355{
    … …  
    380365
    381366
    382 /**
    383  * Releases a reference to an INI-file instance, destroying it if the count
    384  * reaches zero.
    385  *
    386  * @returns New reference count, UINT32_MAX on failure.
    387  * @param   hIniFile        The INI-file handle.  NIL is ignored.
    388  */
    389367RTDECL(uint32_t) RTIniFileRelease(RTINIFILE hIniFile)
    390368{
    … …  
    526504
    527505
    528 /**
    529  * Queries a value in a section.
    530  *
    531  * The first matching value is returned.  The matching is by default case
    532  * 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 the
    539  *                          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 excluding
    544  *                          terminator on success.  On VERR_BUFFER_OVERFLOW this
    545  *                          will be set to the buffer size needed to hold the
    546  *                          value, terminator included.  Optional.
    547  */
    548506RTDECL(int) RTIniFileQueryValue(RTINIFILE hIniFile, const char *pszSection, const char *pszKey,
    549507                                char *pszValue, size_t cbValue, size_t *pcbActual)
    … …  
    732690
    733691
    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 pair
    739  *          with the given ordinal value.
    740  *
    741  * @param   hIniFile        The INI-file handle.
    742  * @param   pszSection      The section name.  Pass NULL to refer to the
    743  *                          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 excluding
    749  *                          terminator on success.  On VERR_BUFFER_OVERFLOW this
    750  *                          will be set to the buffer size needed to hold the
    751  *                          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 excluding
    756  *                          terminator on success.  On VERR_BUFFER_OVERFLOW this
    757  *                          will be set to the buffer size needed to hold the
    758  *                          value, terminator included. Optional.
    759  */
    760692RTDECL(int) RTIniFileQueryPair(RTINIFILE hIniFile, const char *pszSection, uint32_t idxPair,
    761693                               char *pszKey, size_t cbKey, size_t *pcbKeyActual,

  • trunk/src/VBox/Runtime/common/misc/semspingpong.cpp

    r98103 r99758  
    7171
    7272
    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  */
    7973RTDECL(int) RTSemPingPongInit(PRTPINGPONG pPP)
    8074{
    … …  
    9892
    9993
    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  */
    10794RTDECL(int) RTSemPingPongDelete(PRTPINGPONG pPP)
    10895{
    … …  
    129116
    130117
    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  */
    138118RTDECL(int) RTSemPing(PRTPINGPONG pPP)
    139119{
    … …  
    162142
    163143
    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  */
    171144RTDECL(int) RTSemPong(PRTPINGPONG pPP)
    172145{
    … …  
    195168
    196169
    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  */
    205170RTDECL(int) RTSemPingWait(PRTPINGPONG pPP, RTMSINTERVAL cMillies)
    206171{
    … …  
    228193
    229194
    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  */
    238195RTDECL(int) RTSemPongWait(PRTPINGPONG pPP, RTMSINTERVAL cMillies)
    239196{

  • trunk/src/VBox/Runtime/common/misc/thread.cpp

    r98103 r99758  
    300300}
    301301
    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
    311303RTDECL(int) RTThreadAdopt(RTTHREADTYPE enmType, unsigned fFlags, const char *pszName, PRTTHREAD pThread)
    312304{
    … …  
    352344
    353345
    354 /**
    355  * Get the thread handle of the current thread, automatically adopting alien
    356  * threads.
    357  *
    358  * @returns Thread handle.
    359  */
    360346RTDECL(RTTHREAD) RTThreadSelfAutoAdopt(void)
    361347{
    … …  
    776762
    777763
    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 attributes
    788  *                      of the thread.
    789  * @param   fFlags      Flags of the RTTHREADFLAGS type (ORed together).
    790  * @param   pszName     Thread name.
    791  */
    792764RTDECL(int) RTThreadCreate(PRTTHREAD pThread, PFNRTTHREAD pfnThread, void *pvUser, size_t cbStack,
    793765                           RTTHREADTYPE enmType, unsigned fFlags, const char *pszName)
    … …  
    844816
    845817
    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  */
    861818RTDECL(int) RTThreadCreateV(PRTTHREAD pThread, PFNRTTHREAD pfnThread, void *pvUser, size_t cbStack,
    862819                            RTTHREADTYPE enmType, uint32_t fFlags, const char *pszNameFmt, va_list va)
    … …  
    869826
    870827
    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  */
    886828RTDECL(int) RTThreadCreateF(PRTTHREAD pThread, PFNRTTHREAD pfnThread, void *pvUser, size_t cbStack,
    887829                            RTTHREADTYPE enmType, uint32_t fFlags, const char *pszNameFmt, ...)
    … …  
    897839
    898840
    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  */
    905841RTDECL(RTNATIVETHREAD) RTThreadGetNative(RTTHREAD Thread)
    906842{
    … …  
    917853
    918854
    919 /**
    920  * Gets the IPRT thread of a native thread.
    921  *
    922  * @returns The IPRT thread handle
    923  * @returns NIL_RTTHREAD if not a thread known to IPRT.
    924  * @param   NativeThread        The native thread handle/id.
    925  */
    926855RTDECL(RTTHREAD) RTThreadFromNative(RTNATIVETHREAD NativeThread)
    927856{
    … …  
    934863
    935864
    936 /**
    937  * Gets the name of the current thread thread.
    938  *
    939  * @returns Pointer to readonly name string.
    940  * @returns NULL on failure.
    941  */
    942865RTDECL(const char *) RTThreadSelfName(void)
    943866{
    … …  
    958881
    959882
    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  */
    967883RTDECL(const char *) RTThreadGetName(RTTHREAD Thread)
    968884{
    … …  
    982898
    983899
    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  */
    991900RTDECL(int) RTThreadSetName(RTTHREAD Thread, const char *pszName)
    992901{
    … …  
    1016925
    1017926
    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 was
    1026  *          called on a thread of the than the main one.  This could for
    1027  *          instance happen when the DLL/DYLIB/SO containing IPRT is dynamically
    1028  *          loaded at run time by a different thread.
    1029  */
    1030927RTDECL(bool) RTThreadIsMain(RTTHREAD hThread)
    1031928{
    … …  
    1086983
    1087984
    1088 /**
    1089  * Signal the user event.
    1090  *
    1091  * @returns     iprt status code.
    1092  */
    1093985RTDECL(int) RTThreadUserSignal(RTTHREAD Thread)
    1094986{
    … …  
    1107999
    11081000
    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 for
    1115  *                              an indefinite wait.
    1116  */
    11171001RTDECL(int) RTThreadUserWait(RTTHREAD Thread, RTMSINTERVAL cMillies)
    11181002{
    … …  
    11311015
    11321016
    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 for
    1139  *                              an indefinite wait.
    1140  */
    11411017RTDECL(int) RTThreadUserWaitNoResume(RTTHREAD Thread, RTMSINTERVAL cMillies)
    11421018{
    … …  
    11551031
    11561032
    1157 /**
    1158  * Reset the user event.
    1159  *
    1160  * @returns     iprt status code.
    1161  * @param       Thread          The thread to reset.
    1162  */
    11631033RTDECL(int) RTThreadUserReset(RTTHREAD Thread)
    11641034{
    … …  
    12521122
    12531123
    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 for
    1261  *                              an indefinite wait.
    1262  * @param       prc             Where to store the return code of the thread. Optional.
    1263  */
    12641124RTDECL(int) RTThreadWait(RTTHREAD Thread, RTMSINTERVAL cMillies, int *prc)
    12651125{
    … …  
    12711131
    12721132
    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 for
    1279  *                              an indefinite wait.
    1280  * @param       prc             Where to store the return code of the thread. Optional.
    1281  */
    12821133RTDECL(int) RTThreadWaitNoResume(RTTHREAD Thread, RTMSINTERVAL cMillies, int *prc)
    12831134{
    … …  
    12871138
    12881139
    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  */
    12961140RTDECL(int) RTThreadSetType(RTTHREAD Thread, RTTHREADTYPE enmType)
    12971141{
    … …  
    13361180
    13371181
    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  */
    13451182RTDECL(RTTHREADTYPE) RTThreadGetType(RTTHREAD Thread)
    13461183{
    … …  
    14431280
    14441281
    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  */
    14521282RTDECL(void) RTThreadBlocking(RTTHREAD hThread, RTTHREADSTATE enmState, bool fReallySleeping)
    14531283{
    … …  
    14651295
    14661296
    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  */
    14761297RTDECL(void) RTThreadUnblocked(RTTHREAD hThread, RTTHREADSTATE enmCurState)
    14771298{
    … …  
    15021323
    15031324
    1504 /**
    1505  * Get the current thread state.
    1506  *
    1507  * @returns The thread state.
    1508  * @param   hThread         The thread.
    1509  */
    15101325RTDECL(RTTHREADSTATE) RTThreadGetState(RTTHREAD hThread)
    15111326{

  • trunk/src/VBox/Runtime/common/path/RTPathAbsDup.cpp

    r98103 r99758  
    4343
    4444
    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  */
    5245RTDECL(char *) RTPathAbsDup(const char *pszPath)
    5346{

  • trunk/src/VBox/Runtime/common/path/RTPathParentLength.cpp

    r98103 r99758  
    8585
    8686
    87 
    88 
    89 /**
    90  * Determins the length of the path specifying the parent directory, including
    91  * 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 or
    97  *          double-slash prefix as parent.
    98  */
    9987RTDECL(size_t) RTPathParentLength(const char *pszPath)
    10088{

  • trunk/src/VBox/Runtime/common/path/RTPathParseSimple.cpp

    r98103 r99758  
    4646
    4747
    48 /**
    49  * Parses a path.
    50  *
    51  * It figures the length of the directory component, the offset of
    52  * 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. If
    58  *                      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 this
    61  *                      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 this
    64  *                      will be set to -1. Optional.
    65  */
    6648RTDECL(size_t) RTPathParseSimple(const char *pszPath, size_t *pcchDir, ssize_t *poffName, ssize_t *poffSuff)
    6749{

  • trunk/src/VBox/Runtime/common/path/RTPathRealDup.cpp

    r98103 r99758  
    4747
    4848
    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   pszPath
    55  */
    5649RTDECL(char *) RTPathRealDup(const char *pszPath)
    5750{

  • trunk/src/VBox/Runtime/common/path/comparepaths.cpp

    r98103 r99758  
    114114
    115115
    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 considered
    123  *     to be equal.
    124  * <li>On platforms with case-insensitive file systems, mismatching characters
    125  *     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't
    136  *          get case-insensitive compares on unix systems when a path goes into a
    137  *          case-insensitive filesystem like FAT, HPFS, HFS, NTFS, JFS, or
    138  *          similar. For NT, OS/2 and similar you'll won't get case-sensitive
    139  *          compares on a case-sensitive file system.
    140  */
    141116RTDECL(int) RTPathCompare(const char *pszPath1, const char *pszPath2)
    142117{
    … …  
    145120
    146121
    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, or
    151  * that the path is to some file or directory residing in the tree given by the
    152  * 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 they
    158  *          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  */
    164122RTDECL(bool) RTPathStartsWith(const char *pszPath, const char *pszParentPath)
    165123{

  • trunk/src/VBox/Runtime/common/rand/rand.cpp

    r98103 r99758  
    9494 * Termination counterpart to rtRandInitOnce.
    9595 *
    96  * @returns IPRT status code.
    9796 * @param   pvUser          Ignored.
    9897 * @param   fLazyCleanUpOk  Set if we're terminating the process.

  • trunk/src/VBox/Runtime/common/string/strformat.cpp

    r98103 r99758  
    152152
    153153
    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       Width
    162  * @param     cchPrecision   Precision.
    163  * @param     fFlags         Flags (NTFS_*).
    164  */
    165154RTDECL(int) RTStrFormatNumber(char *psz, uint64_t u64Value, unsigned int uiBase, signed int cchWidth, signed int cchPrecision,
    166155                              unsigned int fFlags)
    … …  
    360349
    361350
    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  */
    377351RTDECL(size_t) RTStrFormatV(PFNRTSTROUTPUT pfnOutput, void *pvArgOutput, PFNSTRFORMAT pfnFormat, void *pvArgFormat,
    378352                            const char *pszFormat, va_list InArgs)

  • trunk/src/VBox/Runtime/common/string/strspace.cpp

    r98103 r99758  
    8585
    8686
    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  */
    9587RTDECL(bool) RTStrSpaceInsert(PRTSTRSPACE pStrSpace, PRTSTRSPACECORE pStr)
    9688{
    … …  
    112104
    113105
    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  */
    122106RTDECL(PRTSTRSPACECORE) RTStrSpaceRemove(PRTSTRSPACE pStrSpace, const char *pszString)
    123107{
    … …  
    161145
    162146
    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  */
    171147RTDECL(PRTSTRSPACECORE) RTStrSpaceGet(PRTSTRSPACE pStrSpace, const char *pszString)
    172148{
    … …  
    187163
    188164
    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.  Passing
    197  *                          RTSTR_MAX is ok and makes it behave just like
    198  *                          RTStrSpaceGet.
    199  */
    200165RTDECL(PRTSTRSPACECORE) RTStrSpaceGetN(PRTSTRSPACE pStrSpace, const char *pszString, size_t cchMax)
    201166{
    … …  
    216181
    217182
    218 /**
    219  * Enumerates the string space.
    220  * The caller supplies a callback which will be called for each of
    221  * the string nodes.
    222  *
    223  * @returns 0 or what ever non-zero return value pfnCallback returned
    224  *          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  */
    229183RTDECL(int) RTStrSpaceEnumerate(PRTSTRSPACE pStrSpace, PFNRTSTRSPACECALLBACK pfnCallback, void *pvUser)
    230184{
    … …  
    234188
    235189
    236 /**
    237  * Destroys the string space.
    238  * The caller supplies a callback which will be called for each of
    239  * the string nodes in for freeing their memory and other resources.
    240  *
    241  * @returns 0 or what ever non-zero return value pfnCallback returned
    242  *          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  */
    247190RTDECL(int) RTStrSpaceDestroy(PRTSTRSPACE pStrSpace, PFNRTSTRSPACECALLBACK pfnCallback, void *pvUser)
    248191{

  • trunk/src/VBox/Runtime/common/string/strtonum.cpp

    r98103 r99758  
    119119
    120120
    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_BIG
    127  * @retval  VWRN_NEGATIVE_UNSIGNED
    128  * @retval  VWRN_TRAILING_CHARS
    129  * @retval  VWRN_TRAILING_SPACES
    130  * @retval  VINF_SUCCESS
    131  * @retval  VERR_NO_DIGITS
    132  *
    133  * @param   pszValue        Pointer to the string value.
    134  * @param   ppszNext        Where to store the pointer to the first char
    135  *                          following the number. (Optional)
    136  * @param   uBaseAndMaxLen  The low byte is the base of the representation, the
    137  *                          upper 24 bits are the max length to parse.  If the base
    138  *                          is zero the function will look for known prefixes before
    139  *                          defaulting to 10.  A max length of zero means no length
    140  *                          restriction.
    141  * @param   pu64            Where to store the converted number. (optional)
    142  */
    143121RTDECL(int) RTStrToUInt64Ex(const char *pszValue, char **ppszNext, unsigned uBaseAndMaxLen, uint64_t *pu64)
    144122{
    … …  
    265243
    266244
    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_BIG
    274  * @retval  VWRN_NEGATIVE_UNSIGNED
    275  * @retval  VINF_SUCCESS
    276  * @retval  VERR_NO_DIGITS
    277  * @retval  VERR_TRAILING_SPACES
    278  * @retval  VERR_TRAILING_CHARS
    279  *
    280  * @param   pszValue        Pointer to the string value.
    281  * @param   uBaseAndMaxLen  The low byte is the base of the representation, the
    282  *                          upper 24 bits are the max length to parse.  If the base
    283  *                          is zero the function will look for known prefixes before
    284  *                          defaulting to 10.  A max length of zero means no length
    285  *                          restriction.
    286  * @param   pu64            Where to store the converted number. (optional)
    287  */
    288245RTDECL(int) RTStrToUInt64Full(const char *pszValue, unsigned uBaseAndMaxLen, uint64_t *pu64)
    289246{
    … …  
    314271
    315272
    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  */
    324273RTDECL(uint64_t) RTStrToUInt64(const char *pszValue)
    325274{
    … …  
    333282
    334283
    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_BIG
    341  * @retval  VWRN_NEGATIVE_UNSIGNED
    342  * @retval  VWRN_TRAILING_CHARS
    343  * @retval  VWRN_TRAILING_SPACES
    344  * @retval  VINF_SUCCESS
    345  * @retval  VERR_NO_DIGITS
    346  *
    347  * @param   pszValue        Pointer to the string value.
    348  * @param   ppszNext        Where to store the pointer to the first char
    349  *                          following the number. (Optional)
    350  * @param   uBaseAndMaxLen  The low byte is the base of the representation, the
    351  *                          upper 24 bits are the max length to parse.  If the base
    352  *                          is zero the function will look for known prefixes before
    353  *                          defaulting to 10.  A max length of zero means no length
    354  *                          restriction.
    355  * @param   pu32            Where to store the converted number. (optional)
    356  */
    357284RTDECL(int) RTStrToUInt32Ex(const char *pszValue, char **ppszNext, unsigned uBaseAndMaxLen, uint32_t *pu32)
    358285{
    … …  
    371298
    372299
    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_BIG
    380  * @retval  VWRN_NEGATIVE_UNSIGNED
    381  * @retval  VINF_SUCCESS
    382  * @retval  VERR_NO_DIGITS
    383  * @retval  VERR_TRAILING_SPACES
    384  * @retval  VERR_TRAILING_CHARS
    385  *
    386  * @param   pszValue        Pointer to the string value.
    387  * @param   uBaseAndMaxLen  The low byte is the base of the representation, the
    388  *                          upper 24 bits are the max length to parse.  If the base
    389  *                          is zero the function will look for known prefixes before
    390  *                          defaulting to 10.  A max length of zero means no length
    391  *                          restriction.
    392  * @param   pu32            Where to store the converted number. (optional)
    393  */
    394300RTDECL(int) RTStrToUInt32Full(const char *pszValue, unsigned uBaseAndMaxLen, uint32_t *pu32)
    395301{
    … …  
    408314
    409315
    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  */
    418316RTDECL(uint32_t) RTStrToUInt32(const char *pszValue)
    419317{
    … …  
    427325
    428326
    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_BIG
    435  * @retval  VWRN_NEGATIVE_UNSIGNED
    436  * @retval  VWRN_TRAILING_CHARS
    437  * @retval  VWRN_TRAILING_SPACES
    438  * @retval  VINF_SUCCESS
    439  * @retval  VERR_NO_DIGITS
    440  *
    441  * @param   pszValue        Pointer to the string value.
    442  * @param   ppszNext        Where to store the pointer to the first char
    443  *                          following the number. (Optional)
    444  * @param   uBaseAndMaxLen  The low byte is the base of the representation, the
    445  *                          upper 24 bits are the max length to parse.  If the base
    446  *                          is zero the function will look for known prefixes before
    447  *                          defaulting to 10.  A max length of zero means no length
    448  *                          restriction.
    449  * @param   pu16            Where to store the converted number. (optional)
    450  */
    451327RTDECL(int) RTStrToUInt16Ex(const char *pszValue, char **ppszNext, unsigned uBaseAndMaxLen, uint16_t *pu16)
    452328{
    … …  
    465341
    466342
    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_BIG
    474  * @retval  VWRN_NEGATIVE_UNSIGNED
    475  * @retval  VINF_SUCCESS
    476  * @retval  VERR_NO_DIGITS
    477  * @retval  VERR_TRAILING_SPACES
    478  * @retval  VERR_TRAILING_CHARS
    479  *
    480  * @param   pszValue        Pointer to the string value.
    481  * @param   uBaseAndMaxLen  The low byte is the base of the representation, the
    482  *                          upper 24 bits are the max length to parse.  If the base
    483  *                          is zero the function will look for known prefixes before
    484  *                          defaulting to 10.  A max length of zero means no length
    485  *                          restriction.
    486  * @param   pu16            Where to store the converted number. (optional)
    487  */
    488343RTDECL(int) RTStrToUInt16Full(const char *pszValue, unsigned uBaseAndMaxLen, uint16_t *pu16)
    489344{
    … …  
    502357
    503358
    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  */
    512359RTDECL(uint16_t) RTStrToUInt16(const char *pszValue)
    513360{
    … …  
    521368
    522369
    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_BIG
    529  * @retval  VWRN_NEGATIVE_UNSIGNED
    530  * @retval  VWRN_TRAILING_CHARS
    531  * @retval  VWRN_TRAILING_SPACES
    532  * @retval  VINF_SUCCESS
    533  * @retval  VERR_NO_DIGITS
    534  *
    535  * @param   pszValue        Pointer to the string value.
    536  * @param   ppszNext        Where to store the pointer to the first char
    537  *                          following the number. (Optional)
    538  * @param   uBaseAndMaxLen  The low byte is the base of the representation, the
    539  *                          upper 24 bits are the max length to parse.  If the base
    540  *                          is zero the function will look for known prefixes before
    541  *                          defaulting to 10.  A max length of zero means no length
    542  *                          restriction.
    543  * @param   pu8             Where to store the converted number. (optional)
    544  */
    545370RTDECL(int) RTStrToUInt8Ex(const char *pszValue, char **ppszNext, unsigned uBaseAndMaxLen, uint8_t *pu8)
    546371{
    … …  
    559384
    560385
    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_BIG
    568  * @retval  VWRN_NEGATIVE_UNSIGNED
    569  * @retval  VINF_SUCCESS
    570  * @retval  VERR_NO_DIGITS
    571  * @retval  VERR_TRAILING_SPACES
    572  * @retval  VERR_TRAILING_CHARS
    573  *
    574  * @param   pszValue        Pointer to the string value.
    575  * @param   uBaseAndMaxLen  The low byte is the base of the representation, the
    576  *                          upper 24 bits are the max length to parse.  If the base
    577  *                          is zero the function will look for known prefixes before
    578  *                          defaulting to 10.  A max length of zero means no length
    579  *                          restriction.
    580  * @param   pu8             Where to store the converted number. (optional)
    581  */
    582386RTDECL(int) RTStrToUInt8Full(const char *pszValue, unsigned uBaseAndMaxLen, uint8_t *pu8)
    583387{
    … …  
    596400
    597401
    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  */
    606402RTDECL(uint8_t) RTStrToUInt8(const char *pszValue)
    607403{
    … …  
    615411
    616412
    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_BIG
    628  * @retval  VWRN_TRAILING_CHARS
    629  * @retval  VWRN_TRAILING_SPACES
    630  * @retval  VINF_SUCCESS
    631  * @retval  VERR_NO_DIGITS
    632  *
    633  * @param   pszValue        Pointer to the string value.
    634  * @param   ppszNext        Where to store the pointer to the first char
    635  *                          following the number. (Optional)
    636  * @param   uBaseAndMaxLen  The low byte is the base of the representation, the
    637  *                          upper 24 bits are the max length to parse.  If the base
    638  *                          is zero the function will look for known prefixes before
    639  *                          defaulting to 10.  A max length of zero means no length
    640  *                          restriction.
    641  * @param   pi64            Where to store the converted number. (optional)
    642  */
    643413RTDECL(int) RTStrToInt64Ex(const char *pszValue, char **ppszNext, unsigned uBaseAndMaxLen, int64_t *pi64)
    644414{
    … …  
    773543
    774544
    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_BIG
    782  * @retval  VINF_SUCCESS
    783  * @retval  VERR_TRAILING_CHARS
    784  * @retval  VERR_TRAILING_SPACES
    785  * @retval  VERR_NO_DIGITS
    786  *
    787  * @param   pszValue        Pointer to the string value.
    788  * @param   uBaseAndMaxLen  The low byte is the base of the representation, the
    789  *                          upper 24 bits are the max length to parse.  If the base
    790  *                          is zero the function will look for known prefixes before
    791  *                          defaulting to 10.  A max length of zero means no length
    792  *                          restriction.
    793  * @param   pi64            Where to store the converted number. (optional)
    794  */
    795545RTDECL(int) RTStrToInt64Full(const char *pszValue, unsigned uBaseAndMaxLen, int64_t *pi64)
    796546{
    … …  
    821571
    822572
    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  */
    831573RTDECL(int64_t) RTStrToInt64(const char *pszValue)
    832574{
    … …  
    840582
    841583
    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_BIG
    848  * @retval  VWRN_TRAILING_CHARS
    849  * @retval  VWRN_TRAILING_SPACES
    850  * @retval  VINF_SUCCESS
    851  * @retval  VERR_NO_DIGITS
    852  *
    853  * @param   pszValue        Pointer to the string value.
    854  * @param   ppszNext        Where to store the pointer to the first char
    855  *                          following the number. (Optional)
    856  * @param   uBaseAndMaxLen  The low byte is the base of the representation, the
    857  *                          upper 24 bits are the max length to parse.  If the base
    858  *                          is zero the function will look for known prefixes before
    859  *                          defaulting to 10.  A max length of zero means no length
    860  *                          restriction.
    861  * @param   pi32            Where to store the converted number. (optional)
    862  */
    863584RTDECL(int) RTStrToInt32Ex(const char *pszValue, char **ppszNext, unsigned uBaseAndMaxLen, int32_t *pi32)
    864585{
    … …  
    878599
    879600
    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_BIG
    887  * @retval  VINF_SUCCESS
    888  * @retval  VERR_TRAILING_CHARS
    889  * @retval  VERR_TRAILING_SPACES
    890  * @retval  VERR_NO_DIGITS
    891  *
    892  * @param   pszValue        Pointer to the string value.
    893  * @param   uBaseAndMaxLen  The low byte is the base of the representation, the
    894  *                          upper 24 bits are the max length to parse.  If the base
    895  *                          is zero the function will look for known prefixes before
    896  *                          defaulting to 10.  A max length of zero means no length
    897  *                          restriction.
    898  * @param   pi32            Where to store the converted number. (optional)
    899  */
    900601RTDECL(int) RTStrToInt32Full(const char *pszValue, unsigned uBaseAndMaxLen, int32_t *pi32)
    901602{
    … …  
    915616
    916617
    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  */
    925618RTDECL(int32_t) RTStrToInt32(const char *pszValue)
    926619{
    … …  
    934627
    935628
    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_BIG
    942  * @retval  VWRN_TRAILING_CHARS
    943  * @retval  VWRN_TRAILING_SPACES
    944  * @retval  VINF_SUCCESS
    945  * @retval  VERR_NO_DIGITS
    946  *
    947  * @param   pszValue        Pointer to the string value.
    948  * @param   ppszNext        Where to store the pointer to the first char
    949  *                          following the number. (Optional)
    950  * @param   pszValue        Pointer to the string value.
    951  * @param   uBaseAndMaxLen  The low byte is the base of the representation, the
    952  *                          upper 24 bits are the max length to parse.  If the base
    953  *                          is zero the function will look for known prefixes before
    954  *                          defaulting to 10.  A max length of zero means no length
    955  *                          restriction.
    956  * @param   pi16            Where to store the converted number. (optional)
    957  */
    958629RTDECL(int) RTStrToInt16Ex(const char *pszValue, char **ppszNext, unsigned uBaseAndMaxLen, int16_t *pi16)
    959630{
    … …  
    973644
    974645
    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_BIG
    982  * @retval  VINF_SUCCESS
    983  * @retval  VERR_TRAILING_CHARS
    984  * @retval  VERR_TRAILING_SPACES
    985  * @retval  VERR_NO_DIGITS
    986  *
    987  * @param   pszValue        Pointer to the string value.
    988  * @param   uBaseAndMaxLen  The low byte is the base of the representation, the
    989  *                          upper 24 bits are the max length to parse.  If the base
    990  *                          is zero the function will look for known prefixes before
    991  *                          defaulting to 10.  A max length of zero means no length
    992  *                          restriction.
    993  * @param   pi16            Where to store the converted number. (optional)
    994  */
    995646RTDECL(int) RTStrToInt16Full(const char *pszValue, unsigned uBaseAndMaxLen, int16_t *pi16)
    996647{
    … …  
    1010661
    1011662
    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  */
    1020663RTDECL(int16_t) RTStrToInt16(const char *pszValue)
    1021664{
    … …  
    1029672
    1030673
    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_BIG
    1037  * @retval  VWRN_TRAILING_CHARS
    1038  * @retval  VWRN_TRAILING_SPACES
    1039  * @retval  VINF_SUCCESS
    1040  * @retval  VERR_NO_DIGITS
    1041  *
    1042  * @param   pszValue        Pointer to the string value.
    1043  * @param   ppszNext        Where to store the pointer to the first char
    1044  *                          following the number. (Optional)
    1045  * @param   uBaseAndMaxLen  The low byte is the base of the representation, the
    1046  *                          upper 24 bits are the max length to parse.  If the base
    1047  *                          is zero the function will look for known prefixes before
    1048  *                          defaulting to 10.  A max length of zero means no length
    1049  *                          restriction.
    1050  * @param   pi8             Where to store the converted number. (optional)
    1051  */
    1052674RTDECL(int) RTStrToInt8Ex(const char *pszValue, char **ppszNext, unsigned uBaseAndMaxLen, int8_t *pi8)
    1053675{
    … …  
    1067689
    1068690
    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_BIG
    1076  * @retval  VINF_SUCCESS
    1077  * @retval  VERR_TRAILING_CHARS
    1078  * @retval  VERR_TRAILING_SPACES
    1079  * @retval  VERR_NO_DIGITS
    1080  *
    1081  * @param   pszValue        Pointer to the string value.
    1082  * @param   uBaseAndMaxLen  The low byte is the base of the representation, the
    1083  *                          upper 24 bits are the max length to parse.  If the base
    1084  *                          is zero the function will look for known prefixes before
    1085  *                          defaulting to 10.  A max length of zero means no length
    1086  *                          restriction.
    1087  * @param   pi8             Where to store the converted number. (optional)
    1088  */
    1089691RTDECL(int) RTStrToInt8Full(const char *pszValue, unsigned uBaseAndMaxLen, int8_t *pi8)
    1090692{
    … …  
    1104706
    1105707
    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  */
    1114708RTDECL(int8_t) RTStrToInt8(const char *pszValue)
    1115709{

  • trunk/src/VBox/Runtime/common/string/utf-8-case.cpp

    r98103 r99758  
    5050
    5151
    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 folding
    56  * specified by the unicode specs are used. It does not consider character pairs
    57  * 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 they
    60  * 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  */
    7152RTDECL(int) RTStrICmp(const char *psz1, const char *psz2)
    7253{
    … …  
    125106
    126107
    127 /**
    128  * Performs a case insensitive string compare between two UTF-8 strings, given a
    129  * maximum string length.
    130  *
    131  * This is a simplified compare, as only the simplified lower/upper case folding
    132  * specified by the unicode specs are used. It does not consider character pairs
    133  * 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 they
    136  * 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 length
    147  */
    148108RTDECL(int) RTStrNICmp(const char *psz1, const char *psz2, size_t cchMax)
    149109{

  • trunk/src/VBox/Runtime/common/time/time.cpp

    r98103 r99758  
    275275
    276276
    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  */
    284277RTDECL(bool) RTTimeIsLeapYear(int32_t i32Year)
    285278{
    … …  
    289282
    290283
    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  */
    298284RTDECL(PRTTIME) RTTimeExplode(PRTTIME pTime, PCRTTIMESPEC pTimeSpec)
    299285{
    … …  
    401387
    402388
    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 or
    410  *                      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 their
    414  *                      bounds. Use RTTimeNormalize() or RTTimeLocalNormalize() to
    415  *                      calculate u16YearDay and normalize the ranges of the fields.
    416  */
    417389RTDECL(PRTTIMESPEC) RTTimeImplode(PRTTIMESPEC pTimeSpec, PCRTTIME pTime)
    418390{
    … …  
    679651
    680652
    681 /**
    682  * Normalizes the fields of a time structure.
    683  *
    684  * It is possible to calculate year-day from month/day and vice
    685  * versa. If you adjust any of these, make sure to zero the
    686  * other so you make it clear which of the fields to use. If
    687  * it's ambiguous, the year-day field is used (and you get
    688  * assertions in debug builds).
    689  *
    690  * All the time fields and the year-day or month/day fields will
    691  * be adjusted for overflows. (Since all fields are unsigned, there
    692  * is no underflows.) It is possible to exploit this for simple
    693  * date math, though the recommended way of doing that to implode
    694  * 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  */
    703653RTDECL(PRTTIME) RTTimeNormalize(PRTTIME pTime)
    704654{
    … …  
    719669
    720670
    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 vice
    725  * versa. If you adjust any of these, make sure to zero the
    726  * other so you make it clear which of the fields to use. If
    727  * it's ambiguous, the year-day field is used (and you get
    728  * assertions in debug builds).
    729  *
    730  * All the time fields and the year-day or month/day fields will
    731  * be adjusted for overflows. (Since all fields are unsigned, there
    732  * is no underflows.) It is possible to exploit this for simple
    733  * date math, though the recommended way of doing that to implode
    734  * 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  */
    743671RTDECL(PRTTIME) RTTimeLocalNormalize(PRTTIME pTime)
    744672{
    … …  
    758686
    759687
    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  */
    769688RTDECL(char *) RTTimeToString(PCRTTIME pTime, char *psz, size_t cb)
    770689{
    … …  
    810729
    811730
    812 /**
    813  * Converts a time spec to a ISO date string, extended version.
    814  *
    815  * @returns Output string length on success (positive), VERR_BUFFER_OVERFLOW
    816  *          (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  */
    822731RTDECL(ssize_t) RTTimeToStringEx(PCRTTIME pTime, char *psz, size_t cb, unsigned cFractionDigits)
    823732{
    … …  
    878787
    879788
    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  */
    889789RTDECL(char *) RTTimeSpecToString(PCRTTIMESPEC pTime, char *psz, size_t cb)
    890790{
    … …  
    896796
    897797
    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 leading
    902  * 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  */
    909798RTDECL(PRTTIME) RTTimeFromString(PRTTIME pTime, const char *pszString)
    910799{
    … …  
    1072961
    1073962
    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 leading
    1078  * 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  */
    1085963RTDECL(PRTTIMESPEC) RTTimeSpecFromString(PRTTIMESPEC pTime, const char *pszString)
    1086964{
    … …  
    1093971
    1094972
    1095 /**
    1096  * Formats the given time on a RTC-2822 compliant format.
    1097  *
    1098  * @returns Output string length on success (positive), VERR_BUFFER_OVERFLOW
    1099  *          (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  */
    1104973RTDECL(ssize_t) RTTimeToRfc2822(PRTTIME pTime, char *psz, size_t cb, uint32_t fFlags)
    1105974{
    … …  
    11611030
    11621031
    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 leading
    1167  * 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  */
    11741032RTDECL(PRTTIME) RTTimeFromRfc2822(PRTTIME pTime, const char *pszString)
    11751033{
    … …  
    15521410
    15531411
    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  */
    15611412RTDECL(PRTTIME) RTTimeConvertToZulu(PRTTIME pTime)
    15621413{
    … …  
    15721423
    15731424
    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 are
    1585  *          NULL, they are considered equal.
    1586  */
    15871425RTDECL(int) RTTimeCompare(PCRTTIME pLeft, PCRTTIME pRight)
    15881426{

  • trunk/src/VBox/Runtime/r0drv/linux/the-linux-kernel.h

    r98103 r99758  
    472472 * Whether the kernel support high resolution timers (Linux kernel versions
    473473 * 2.6.28 and later (hrtimer_add_expires_ns() & schedule_hrtimeout). */
    474 #if RTLNX_VER_MIN(2,6,28)
     474#if RTLNX_VER_MIN(2,6,28) || defined(DOXYGEN_RUNNING)
    475475# define IPRT_LINUX_HAS_HRTIMER
    476476#endif

  • trunk/src/VBox/Runtime/r0drv/memobj-r0drv.cpp

    r98103 r99758  
    157157
    158158
    159 /**
    160  * Checks if this is mapping or not.
    161  *
    162  * @returns true if it's a mapping, otherwise false.
    163  * @param   MemObj      The ring-0 memory object handle.
    164  */
    165159RTR0DECL(bool) RTR0MemObjIsMapping(RTR0MEMOBJ MemObj)
    166160{
    … …  
    178172
    179173
    180 /**
    181  * Gets the address of a ring-0 memory object.
    182  *
    183  * @returns The address of the memory object.
    184  * @returns NULL if the handle is invalid (asserts in strict builds) or if there isn't any mapping.
    185  * @param   MemObj  The ring-0 memory object handle.
    186  */
    187174RTR0DECL(void *) RTR0MemObjAddress(RTR0MEMOBJ MemObj)
    188175{
    … …  
    202189
    203190
    204 /**
    205  * Gets the ring-3 address of a ring-0 memory object.
    206  *
    207  * This only applies to ring-0 memory object with ring-3 mappings of some kind, i.e.
    208  * locked user memory, reserved user address space and user mappings. This API should
    209  * not be used on any other objects.
    210  *
    211  * @returns The address of the memory object.
    212  * @returns NIL_RTR3PTR if the handle is invalid or if it's not an object with a ring-3 mapping.
    213  *          Strict builds will assert in both cases.
    214  * @param   MemObj  The ring-0 memory object handle.
    215  */
    216191RTR0DECL(RTR3PTR) RTR0MemObjAddressR3(RTR0MEMOBJ MemObj)
    217192{
    … …  
    241216
    242217
    243 /**
    244  * Gets the size of a ring-0 memory object.
    245  *
    246  * The returned value may differ from the one specified to the API creating the
    247  * object because of alignment adjustments.  The minimal alignment currently
    248  * employed by any API is PAGE_SIZE, so the result can safely be shifted by
    249  * PAGE_SHIFT to calculate a page count.
    250  *
    251  * @returns The object size.
    252  * @returns 0 if the handle is invalid (asserts in strict builds) or if there isn't any mapping.
    253  * @param   MemObj  The ring-0 memory object handle.
    254  */
    255218RTR0DECL(size_t) RTR0MemObjSize(RTR0MEMOBJ MemObj)
    256219{
    … …  
    272235
    273236
    274 /**
    275  * Get the physical address of an page in the memory object.
    276  *
    277  * @returns The physical address.
    278  * @returns NIL_RTHCPHYS if the object doesn't contain fixed physical pages.
    279  * @returns NIL_RTHCPHYS if the iPage is out of range.
    280  * @returns NIL_RTHCPHYS if the object handle isn't valid.
    281  * @param   MemObj  The ring-0 memory object handle.
    282  * @param   iPage   The page number within the object.
    283  */
    284237/* Work around gcc bug 55940 */
    285238#if defined(__GNUC__) && defined(RT_ARCH_X86) && (__GNUC__ * 100 + __GNUC_MINOR__) == 407
    … …  
    322275
    323276
    324 /**
    325  * Checks whether the allocation was zero initialized or not.
    326  *
    327  * This only works on allocations.  It is not meaningful for mappings, reserved
    328  * memory and entered physical address, and will return false for these.
    329  *
    330  * @returns true if the allocation was initialized to zero at allocation time,
    331  *          false if not or query not meaningful to the object type.
    332  * @param   hMemObj             The ring-0 memory object to be freed.
    333  *
    334  * @remarks It can be expected that memory allocated in the same fashion will
    335  *          have the same initialization state.  So, if this returns true for
    336  *          one allocation it will return true for all other similarly made
    337  *          allocations.
    338  */
    339277RTR0DECL(bool) RTR0MemObjWasZeroInitialized(RTR0MEMOBJ hMemObj)
    340278{
    … …  
    358296
    359297
    360 /**
    361  * Frees a ring-0 memory object.
    362  *
    363  * @returns IPRT status code.
    364  * @retval  VERR_INVALID_HANDLE if
    365  * @param   MemObj          The ring-0 memory object to be freed. NIL is
    366  *                          accepted.
    367  * @param   fFreeMappings   Whether or not to free mappings of the object.
    368  */
    369298RTR0DECL(int) RTR0MemObjFree(RTR0MEMOBJ MemObj, bool fFreeMappings)
    370299{

  • trunk/src/VBox/Runtime/r0drv/nt/alloc-r0drv-nt.cpp

    r98103 r99758  
    9393
    9494
    95 /**
    96  * Allocates physical contiguous memory (below 4GB).
    97  * The allocation is page aligned and its contents is undefined.
    98  *
    99  * @returns Pointer to the memory block. This is page aligned.
    100  * @param   pPhys   Where to store the physical address.
    101  * @param   cb      The allocation size in bytes. This is always
    102  *                  rounded up to PAGE_SIZE.
    103  */
    10495RTR0DECL(void *) RTMemContAlloc(PRTCCPHYS pPhys, size_t cb)
    10596{
    … …  
    143134
    144135
    145 /**
    146  * Frees memory allocated ysing RTMemContAlloc().
    147  *
    148  * @param   pv      Pointer to return from RTMemContAlloc().
    149  * @param   cb      The cb parameter passed to RTMemContAlloc().
    150  */
    151136RTR0DECL(void) RTMemContFree(void *pv, size_t cb)
    152137{

  • trunk/src/VBox/Runtime/r0drv/nt/timer-r0drv-nt.cpp

    r98103 r99758  
    313313 * Common timer callback worker for the non-omni timers.
    314314 *
    315  * @returns HRTIMER_NORESTART or HRTIMER_RESTART depending on whether it's a one-shot or interval timer.
    316315 * @param   pTimer          The timer.
    317316 */

  • trunk/src/VBox/Runtime/r3/fileio.cpp

    r98103 r99758  
    210210
    211211
    212 /**
    213  * Gets the current file position.
    214  *
    215  * @returns File offset.
    216  * @returns ~0UUL on failure.
    217  * @param   File        File handle.
    218  */
    219212RTR3DECL(uint64_t)  RTFileTell(RTFILE File)
    220213{

  • trunk/src/VBox/Runtime/r3/ftp-server.cpp

    r99375 r99758  
    12411241 * Destroys a data connection.
    12421242 *
    1243  * @returns VBox status code.
    12441243 * @param   pDataConn           Data connection to destroy. The pointer is not valid anymore after successful return.
    12451244 */
    … …  
    12661265 * Resets a data connection structure.
    12671266 *
    1268  * @returns VBox status code.
    12691267 * @param   pDataConn           Data connection structure to reset.
    12701268 */

  • trunk/src/VBox/Runtime/r3/generic/dirrel-r3-generic.cpp

    r98103 r99758  
    118118
    119119
    120 /**
    121  * Open a file relative to @a hDir.
    122  *
    123  * @returns IPRT status code.
    124  * @param   hDir            The directory to open relative to.
    125  * @param   pszRelFilename  The relative path to the file.
    126  * @param   fOpen           Open flags, i.e a combination of the RTFILE_O_XXX
    127  *                          defines.  The ACCESS, ACTION and DENY flags are
    128  *                          mandatory!
    129  * @param   phFile          Where to store the handle to the opened file.
    130  *
    131  * @sa      RTFileOpen
    132  */
    133120RTDECL(int)  RTDirRelFileOpen(RTDIR hDir, const char *pszRelFilename, uint64_t fOpen, PRTFILE phFile)
    134121{
    … …  
    158145
    159146
    160 /**
    161  * Opens a directory relative to @a hDir.
    162  *
    163  * @returns IPRT status code.
    164  * @param   hDir            The directory to open relative to.
    165  * @param   pszDir          The relative path to the directory to open.
    166  * @param   phDir           Where to store the directory handle.
    167  *
    168  * @sa      RTDirOpen
    169  */
    170147RTDECL(int) RTDirRelDirOpen(RTDIR hDir, const char *pszDir, RTDIR *phDir)
    171148{
    … …  
    183160
    184161
    185 /**
    186  * Opens a directory relative to @a hDir, with flags and optional filtering.
    187  *
    188  * @returns IPRT status code.
    189  * @param   hDir            The directory to open relative to.
    190  * @param   pszDirAndFilter The relative path to the directory to search, this
    191  *                          must include wildcards.
    192  * @param   enmFilter       The kind of filter to apply. Setting this to
    193  *                          RTDIRFILTER_NONE makes this function behave like
    194  *                          RTDirOpen.
    195  * @param   fFlags          Open flags, RTDIR_F_XXX.
    196  * @param   phDir           Where to store the directory handle.
    197  *
    198  * @sa      RTDirOpenFiltered
    199  */
    200162RTDECL(int) RTDirRelDirOpenFiltered(RTDIR hDir, const char *pszDirAndFilter, RTDIRFILTER enmFilter,
    201163                                    uint32_t fFlags, RTDIR *phDir)
    … …  
    213175
    214176
    215 /**
    216  * Creates a directory relative to @a hDir.
    217  *
    218  * @returns IPRT status code.
    219  * @param   hDir            The directory @a pszRelPath is relative to.
    220  * @param   pszRelPath      The relative path to the directory to create.
    221  * @param   fMode           The mode of the new directory.
    222  * @param   fCreate         Create flags, RTDIRCREATE_FLAGS_XXX.
    223  * @param   phSubDir        Where to return the handle of the created directory.
    224  *                          Optional.
    225  *
    226  * @sa      RTDirCreate
    227  */
    228177RTDECL(int) RTDirRelDirCreate(RTDIR hDir, const char *pszRelPath, RTFMODE fMode, uint32_t fCreate, RTDIR *phSubDir)
    229178{
    … …  
    244193
    245194
    246 /**
    247  * Removes a directory relative to @a hDir if empty.
    248  *
    249  * @returns IPRT status code.
    250  * @param   hDir            The directory @a pszRelPath is relative to.
    251  * @param   pszRelPath      The relative path to the directory to remove.
    252  *
    253  * @sa      RTDirRemove
    254  */
    255195RTDECL(int) RTDirRelDirRemove(RTDIR hDir, const char *pszRelPath)
    256196{
    … …  
    277217
    278218
    279 /**
    280  * Query information about a file system object relative to @a hDir.
    281  *
    282  * @returns IPRT status code.
    283  * @retval  VINF_SUCCESS if the object exists, information returned.
    284  * @retval  VERR_PATH_NOT_FOUND if any but the last component in the specified
    285  *          path was not found or was not a directory.
    286  * @retval  VERR_FILE_NOT_FOUND if the object does not exist (but path to the
    287  *          parent directory exists).
    288  *
    289  * @param   hDir            The directory @a pszRelPath is relative to.
    290  * @param   pszRelPath      The relative path to the file system object.
    291  * @param   pObjInfo        Object information structure to be filled on successful
    292  *                          return.
    293  * @param   enmAddAttr      Which set of additional attributes to request.
    294  *                          Use RTFSOBJATTRADD_NOTHING if this doesn't matter.
    295  * @param   fFlags          RTPATH_F_ON_LINK or RTPATH_F_FOLLOW_LINK.
    296  *
    297  * @sa      RTPathQueryInfoEx
    298  */
    299219RTDECL(int) RTDirRelPathQueryInfo(RTDIR hDir, const char *pszRelPath, PRTFSOBJINFO pObjInfo,
    300220                                  RTFSOBJATTRADD enmAddAttr, uint32_t fFlags)
    … …  
    312232
    313233
    314 /**
    315  * Changes the mode flags of a file system object relative to @a hDir.
    316  *
    317  * The API requires at least one of the mode flag sets (Unix/Dos) to
    318  * be set. The type is ignored.
    319  *
    320  * @returns IPRT status code.
    321  * @param   hDir            The directory @a pszRelPath is relative to.
    322  * @param   pszRelPath      The relative path to the file system object.
    323  * @param   fMode           The new file mode, see @ref grp_rt_fs for details.
    324  * @param   fFlags          RTPATH_F_ON_LINK or RTPATH_F_FOLLOW_LINK.
    325  *
    326  * @sa      RTPathSetMode
    327  */
    328234RTDECL(int) RTDirRelPathSetMode(RTDIR hDir, const char *pszRelPath, RTFMODE fMode, uint32_t fFlags)
    329235{
    … …  
    348254
    349255
    350 /**
    351  * Changes one or more of the timestamps associated of file system object
    352  * relative to @a hDir.
    353  *
    354  * @returns IPRT status code.
    355  * @param   hDir                The directory @a pszRelPath is relative to.
    356  * @param   pszRelPath          The relative path to the file system object.
    357  * @param   pAccessTime         Pointer to the new access time.
    358  * @param   pModificationTime   Pointer to the new modification time.
    359  * @param   pChangeTime         Pointer to the new change time. NULL if not to be changed.
    360  * @param   pBirthTime          Pointer to the new time of birth. NULL if not to be changed.
    361  * @param   fFlags              RTPATH_F_ON_LINK or RTPATH_F_FOLLOW_LINK.
    362  *
    363  * @remark  The file system might not implement all these time attributes,
    364  *          the API will ignore the ones which aren't supported.
    365  *
    366  * @remark  The file system might not implement the time resolution
    367  *          employed by this interface, the time will be chopped to fit.
    368  *
    369  * @remark  The file system may update the change time even if it's
    370  *          not specified.
    371  *
    372  * @remark  POSIX can only set Access & Modification and will always set both.
    373  *
    374  * @sa      RTPathSetTimesEx
    375  */
    376256RTDECL(int) RTDirRelPathSetTimes(RTDIR hDir, const char *pszRelPath, PCRTTIMESPEC pAccessTime, PCRTTIMESPEC pModificationTime,
    377257                                 PCRTTIMESPEC pChangeTime, PCRTTIMESPEC pBirthTime, uint32_t fFlags)
    … …  
    389269
    390270
    391 /**
    392  * Changes the owner and/or group of a file system object relative to @a hDir.
    393  *
    394  * @returns IPRT status code.
    395  * @param   hDir            The directory @a pszRelPath is relative to.
    396  * @param   pszRelPath      The relative path to the file system object.
    397  * @param   uid             The new file owner user id.  Pass NIL_RTUID to leave
    398  *                          this unchanged.
    399  * @param   gid             The new group id.  Pass NIL_RTGID to leave this
    400  *                          unchanged.
    401  * @param   fFlags          RTPATH_F_ON_LINK or RTPATH_F_FOLLOW_LINK.
    402  *
    403  * @sa      RTPathSetOwnerEx
    404  */
    405271RTDECL(int) RTDirRelPathSetOwner(RTDIR hDir, const char *pszRelPath, uint32_t uid, uint32_t gid, uint32_t fFlags)
    406272{
    … …  
    424290
    425291
    426 /**
    427  * Renames a directory relative path within a filesystem.
    428  *
    429  * This will rename symbolic links.  If RTPATHRENAME_FLAGS_REPLACE is used and
    430  * pszDst is a symbolic link, it will be replaced and not its target.
    431  *
    432  * @returns IPRT status code.
    433  * @param   hDirSrc         The directory the source path is relative to.
    434  * @param   pszSrc          The source path, relative to @a hDirSrc.
    435  * @param   hDirDst         The directory the destination path is relative to.
    436  * @param   pszDst          The destination path, relative to @a hDirDst.
    437  * @param   fRename         Rename flags, RTPATHRENAME_FLAGS_XXX.
    438  *
    439  * @sa      RTPathRename
    440  */
    441292RTDECL(int) RTDirRelPathRename(RTDIR hDirSrc, const char *pszSrc, RTDIR hDirDst, const char *pszDst, unsigned fRename)
    442293{
    … …  
    465316
    466317
    467 /**
    468  * Removes the last component of the directory relative path.
    469  *
    470  * @returns IPRT status code.
    471  * @param   hDir            The directory @a pszRelPath is relative to.
    472  * @param   pszRelPath      The relative path to the file system object.
    473  * @param   fUnlink         Unlink flags, RTPATHUNLINK_FLAGS_XXX.
    474  *
    475  * @sa      RTPathUnlink
    476  */
    477318RTDECL(int) RTDirRelPathUnlink(RTDIR hDir, const char *pszRelPath, uint32_t fUnlink)
    478319{
    … …  
    499340
    500341
    501 /**
    502  * Creates a symbolic link (@a pszSymlink) relative to @a hDir targeting @a
    503  * pszTarget.
    504  *
    505  * @returns IPRT status code.
    506  * @param   hDir            The directory @a pszSymlink is relative to.
    507  * @param   pszSymlink      The relative path of the symbolic link.
    508  * @param   pszTarget       The path to the symbolic link target.  This is
    509  *                          relative to @a pszSymlink or an absolute path.
    510  * @param   enmType         The symbolic link type.  For Windows compatability
    511  *                          it is very important to set this correctly.  When
    512  *                          RTSYMLINKTYPE_UNKNOWN is used, the API will try
    513  *                          make a guess and may attempt query information
    514  *                          about @a pszTarget in the process.
    515  * @param   fCreate         Create flags, RTSYMLINKCREATE_FLAGS_XXX.
    516  *
    517  * @sa      RTSymlinkCreate
    518  */
    519342RTDECL(int) RTDirRelSymlinkCreate(RTDIR hDir, const char *pszSymlink, const char *pszTarget,
    520343                                  RTSYMLINKTYPE enmType, uint32_t fCreate)
    … …  
    532355
    533356
    534 /**
    535  * Read the symlink target relative to @a hDir.
    536  *
    537  * @returns IPRT status code.
    538  * @retval  VERR_NOT_SYMLINK if @a pszSymlink does not specify a symbolic link.
    539  * @retval  VERR_BUFFER_OVERFLOW if the link is larger than @a cbTarget.  The
    540  *          buffer will contain what all we managed to read, fully terminated
    541  *          if @a cbTarget > 0.
    542  *
    543  * @param   hDir            The directory @a pszSymlink is relative to.
    544  * @param   pszSymlink      The relative path to the symbolic link that should
    545  *                          be read.
    546  * @param   pszTarget       The target buffer.
    547  * @param   cbTarget        The size of the target buffer.
    548  * @param   fRead           Read flags, RTSYMLINKREAD_FLAGS_XXX.
    549  *
    550  * @sa      RTSymlinkRead
    551  */
    552357RTDECL(int) RTDirRelSymlinkRead(RTDIR hDir, const char *pszSymlink, char *pszTarget, size_t cbTarget, uint32_t fRead)
    553358{

  • trunk/src/VBox/Runtime/r3/nt/dirrel-r3-nt.cpp

    r98103 r99758  
    482482
    483483
    484 /**
    485  * Changes the mode flags of a file system object relative to @a hDir.
    486  *
    487  * The API requires at least one of the mode flag sets (Unix/Dos) to
    488  * be set. The type is ignored.
    489  *
    490  * @returns IPRT status code.
    491  * @param   hDir            The directory @a pszRelPath is relative to.
    492  * @param   pszRelPath      The relative path to the file system object.
    493  * @param   fMode           The new file mode, see @ref grp_rt_fs for details.
    494  * @param   fFlags          RTPATH_F_ON_LINK or RTPATH_F_FOLLOW_LINK.
    495  *
    496  * @sa      RTPathSetMode
    497  */
    498484RTDECL(int) RTDirRelPathSetMode(RTDIR hDir, const char *pszRelPath, RTFMODE fMode, uint32_t fFlags)
    499485{
    … …  
    550536
    551537
    552 /**
    553  * Changes one or more of the timestamps associated of file system object
    554  * relative to @a hDir.
    555  *
    556  * @returns IPRT status code.
    557  * @param   hDir                The directory @a pszRelPath is relative to.
    558  * @param   pszRelPath          The relative path to the file system object.
    559  * @param   pAccessTime         Pointer to the new access time.
    560  * @param   pModificationTime   Pointer to the new modification time.
    561  * @param   pChangeTime         Pointer to the new change time. NULL if not to be changed.
    562  * @param   pBirthTime          Pointer to the new time of birth. NULL if not to be changed.
    563  * @param   fFlags              RTPATH_F_ON_LINK or RTPATH_F_FOLLOW_LINK.
    564  *
    565  * @remark  The file system might not implement all these time attributes,
    566  *          the API will ignore the ones which aren't supported.
    567  *
    568  * @remark  The file system might not implement the time resolution
    569  *          employed by this interface, the time will be chopped to fit.
    570  *
    571  * @remark  The file system may update the change time even if it's
    572  *          not specified.
    573  *
    574  * @remark  POSIX can only set Access & Modification and will always set both.
    575  *
    576  * @sa      RTPathSetTimesEx
    577  */
    578538RTDECL(int) RTDirRelPathSetTimes(RTDIR hDir, const char *pszRelPath, PCRTTIMESPEC pAccessTime, PCRTTIMESPEC pModificationTime,
    579539                                 PCRTTIMESPEC pChangeTime, PCRTTIMESPEC pBirthTime, uint32_t fFlags)
    … …  
    586546    int rc = rtDirRelBuildFullPath(pThis, szPath, sizeof(szPath), pszRelPath);
    587547    if (RT_SUCCESS(rc))
    588     {
    589 RTAssertMsg2("DBG: RTDirRelPathSetTimes(%s)...\n", szPath);
    590548        rc = RTPathSetTimesEx(szPath, pAccessTime, pModificationTime, pChangeTime, pBirthTime, fFlags);
    591     }
    592     return rc;
    593 }
    594 
    595 
    596 /**
    597  * Changes the owner and/or group of a file system object relative to @a hDir.
    598  *
    599  * @returns IPRT status code.
    600  * @param   hDir            The directory @a pszRelPath is relative to.
    601  * @param   pszRelPath      The relative path to the file system object.
    602  * @param   uid             The new file owner user id.  Pass NIL_RTUID to leave
    603  *                          this unchanged.
    604  * @param   gid             The new group id.  Pass NIL_RTGID to leave this
    605  *                          unchanged.
    606  * @param   fFlags          RTPATH_F_ON_LINK or RTPATH_F_FOLLOW_LINK.
    607  *
    608  * @sa      RTPathSetOwnerEx
    609  */
     549    return rc;
     550}
     551
     552
    610553RTDECL(int) RTDirRelPathSetOwner(RTDIR hDir, const char *pszRelPath, uint32_t uid, uint32_t gid, uint32_t fFlags)
    611554{
    … …  
    618561    if (RT_SUCCESS(rc))
    619562    {
    620 RTAssertMsg2("DBG: RTDirRelPathSetOwner(%s)...\n", szPath);
    621563#ifndef RT_OS_WINDOWS
    622564        rc = RTPathSetOwnerEx(szPath, uid, gid, fFlags);
    … …  
    630572
    631573
    632 /**
    633  * Renames a directory relative path within a filesystem.
    634  *
    635  * This will rename symbolic links.  If RTPATHRENAME_FLAGS_REPLACE is used and
    636  * pszDst is a symbolic link, it will be replaced and not its target.
    637  *
    638  * @returns IPRT status code.
    639  * @param   hDirSrc         The directory the source path is relative to.
    640  * @param   pszSrc          The source path, relative to @a hDirSrc.
    641  * @param   hDirSrc         The directory the destination path is relative to.
    642  * @param   pszDst          The destination path, relative to @a hDirDst.
    643  * @param   fRename         Rename flags, RTPATHRENAME_FLAGS_XXX.
    644  *
    645  * @sa      RTPathRename
    646  */
    647574RTDECL(int) RTDirRelPathRename(RTDIR hDirSrc, const char *pszSrc, RTDIR hDirDst, const char *pszDst, unsigned fRename)
    648575{
    … …  
    665592        rc = rtDirRelBuildFullPath(pThis, szDstPath, sizeof(szDstPath), pszDst);
    666593        if (RT_SUCCESS(rc))
    667         {
    668 RTAssertMsg2("DBG: RTDirRelPathRename(%s,%s)...\n", szSrcPath, szDstPath);
    669594            rc = RTPathRename(szSrcPath, szDstPath, fRename);
    670         }
    671     }
    672     return rc;
    673 }
    674 
    675 
    676 /**
    677  * Removes the last component of the directory relative path.
    678  *
    679  * @returns IPRT status code.
    680  * @param   hDir            The directory @a pszRelPath is relative to.
    681  * @param   pszRelPath      The relative path to the file system object.
    682  * @param   fUnlink         Unlink flags, RTPATHUNLINK_FLAGS_XXX.
    683  *
    684  * @sa      RTPathUnlink
    685  */
     595    }
     596    return rc;
     597}
     598
     599
    686600RTDECL(int) RTDirRelPathUnlink(RTDIR hDir, const char *pszRelPath, uint32_t fUnlink)
    687601{
    … …  
    693607    int rc = rtDirRelBuildFullPath(pThis, szPath, sizeof(szPath), pszRelPath);
    694608    if (RT_SUCCESS(rc))
    695     {
    696 RTAssertMsg2("DBG: RTDirRelPathUnlink(%s)...\n", szPath);
    697609        rc = RTPathUnlink(szPath, fUnlink);
    698     }
    699610    return rc;
    700611}
    … …  
    711622
    712623
    713 /**
    714  * Creates a symbolic link (@a pszSymlink) relative to @a hDir targeting @a
    715  * pszTarget.
    716  *
    717  * @returns IPRT status code.
    718  * @param   hDir            The directory @a pszSymlink is relative to.
    719  * @param   pszSymlink      The relative path of the symbolic link.
    720  * @param   pszTarget       The path to the symbolic link target.  This is
    721  *                          relative to @a pszSymlink or an absolute path.
    722  * @param   enmType         The symbolic link type.  For Windows compatability
    723  *                          it is very important to set this correctly.  When
    724  *                          RTSYMLINKTYPE_UNKNOWN is used, the API will try
    725  *                          make a guess and may attempt query information
    726  *                          about @a pszTarget in the process.
    727  * @param   fCreate         Create flags, RTSYMLINKCREATE_FLAGS_XXX.
    728  *
    729  * @sa      RTSymlinkCreate
    730  */
    731624RTDECL(int) RTDirRelSymlinkCreate(RTDIR hDir, const char *pszSymlink, const char *pszTarget,
    732625                                  RTSYMLINKTYPE enmType, uint32_t fCreate)
    … …  
    739632    int rc = rtDirRelBuildFullPath(pThis, szPath, sizeof(szPath), pszSymlink);
    740633    if (RT_SUCCESS(rc))
    741     {
    742 RTAssertMsg2("DBG: RTDirRelSymlinkCreate(%s)...\n", szPath);
    743634        rc = RTSymlinkCreate(szPath, pszTarget, enmType, fCreate);
    744     }
    745     return rc;
    746 }
    747 
    748 
    749 /**
    750  * Read the symlink target relative to @a hDir.
    751  *
    752  * @returns IPRT status code.
    753  * @retval  VERR_NOT_SYMLINK if @a pszSymlink does not specify a symbolic link.
    754  * @retval  VERR_BUFFER_OVERFLOW if the link is larger than @a cbTarget.  The
    755  *          buffer will contain what all we managed to read, fully terminated
    756  *          if @a cbTarget > 0.
    757  *
    758  * @param   hDir            The directory @a pszSymlink is relative to.
    759  * @param   pszSymlink      The relative path to the symbolic link that should
    760  *                          be read.
    761  * @param   pszTarget       The target buffer.
    762  * @param   cbTarget        The size of the target buffer.
    763  * @param   fRead           Read flags, RTSYMLINKREAD_FLAGS_XXX.
    764  *
    765  * @sa      RTSymlinkRead
    766  */
     635    return rc;
     636}
     637
     638
    767639RTDECL(int) RTDirRelSymlinkRead(RTDIR hDir, const char *pszSymlink, char *pszTarget, size_t cbTarget, uint32_t fRead)
    768640{
    … …  
    774646    int rc = rtDirRelBuildFullPath(pThis, szPath, sizeof(szPath), pszSymlink);
    775647    if (RT_SUCCESS(rc))
    776     {
    777 RTAssertMsg2("DBG: RTDirRelSymlinkRead(%s)...\n", szPath);
    778648        rc = RTSymlinkRead(szPath, pszTarget, cbTarget, fRead);
    779     }
    780     return rc;
    781 }
    782 
     649    return rc;
     650}
     651

  • trunk/src/VBox/Runtime/r3/stream.cpp

    r98103 r99758  
    642642
    643643
    644 /**
    645  * Opens a file stream.
    646  *
    647  * @returns iprt status code.
    648  * @param   pszFilename     Path to the file to open.
    649  * @param   pszMode         The open mode. See fopen() standard.
    650  *                          Format: <a|r|w>[+][b|t][x][e|N|E]
    651  *                              - 'a': Open or create file and writes
    652  *                                append tos it.
    653  *                              - 'r': Open existing file and read from it.
    654  *                              - 'w': Open or truncate existing file and write
    655  *                                to it.
    656  *                              - '+': Open for both read and write access.
    657  *                              - 'b' / 't': binary / text
    658  *                              - 'x': exclusively create, no open. Only
    659  *                                possible with 'w'.
    660  *                              - 'e' / 'N': No inherit on exec.  (The 'e' is
    661  *                                how Linux and FreeBSD expresses this, the
    662  *                                latter is Visual C++).
    663  * @param   ppStream        Where to store the opened stream.
    664  */
    665644RTR3DECL(int) RTStrmOpen(const char *pszFilename, const char *pszMode, PRTSTREAM *ppStream)
    666645{
    … …  
    671650
    672651
    673 /**
    674  * Opens a file stream.
    675  *
    676  * @returns iprt status code.
    677  * @param   pszMode         The open mode. See fopen() standard.
    678  *                          Format: <a|r|w>[+][b]
    679  * @param   ppStream        Where to store the opened stream.
    680  * @param   pszFilenameFmt  Filename path format string.
    681  * @param   args            Arguments to the format string.
    682  */
    683652RTR3DECL(int) RTStrmOpenFV(const char *pszMode, PRTSTREAM *ppStream, const char *pszFilenameFmt, va_list args)
    684653{
    … …  
    697666
    698667
    699 /**
    700  * Opens a file stream.
    701  *
    702  * @returns iprt status code.
    703  * @param   pszMode         The open mode. See fopen() standard.
    704  *                          Format: <a|r|w>[+][b]
    705  * @param   ppStream        Where to store the opened stream.
    706  * @param   pszFilenameFmt  Filename path format string.
    707  * @param   ...             Arguments to the format string.
    708  */
    709668RTR3DECL(int) RTStrmOpenF(const char *pszMode, PRTSTREAM *ppStream, const char *pszFilenameFmt, ...)
    710669{
    … …  
    717676
    718677
    719 /**
    720  * Opens a file stream for a RTFILE handle, taking ownership of the handle.
    721  *
    722  * @returns iprt status code.
    723  * @param   hFile           The file handle to use.  On success, handle
    724  *                          ownership is transfered to the stream and it will be
    725  *                          closed when the stream closes.
    726  * @param   pszMode         The open mode, accept the same as RTStrOpen and
    727  *                          friends however it is only used to figure out what
    728  *                          we can do with the handle.
    729  * @param   fFlags          Reserved, must be zero.
    730  * @param   ppStream        Where to store the opened stream.
    731  */
    732678RTR3DECL(int) RTStrmOpenFileHandle(RTFILE hFile, const char *pszMode, uint32_t fFlags, PRTSTREAM *ppStream)
    733679{
    … …  
    739685
    740686
    741 /**
    742  * Closes the specified stream.
    743  *
    744  * @returns iprt status code.
    745  * @param   pStream         The stream to close.
    746  */
    747687RTR3DECL(int) RTStrmClose(PRTSTREAM pStream)
    748688{
    … …  
    815755
    816756
    817 /**
    818  * Get the pending error of the stream.
    819  *
    820  * @returns iprt status code. of the stream.
    821  * @param   pStream         The stream.
    822  */
    823757RTR3DECL(int) RTStrmError(PRTSTREAM pStream)
    824758{
    … …  
    829763
    830764
    831 /**
    832  * Clears stream error condition.
    833  *
    834  * All stream operations save RTStrmClose and this will fail
    835  * while an error is asserted on the stream
    836  *
    837  * @returns iprt status code.
    838  * @param   pStream         The stream.
    839  */
    840765RTR3DECL(int) RTStrmClearError(PRTSTREAM pStream)
    841766{
    … …  
    16741599
    16751600
    1676 /**
    1677  * Rewinds the stream.
    1678  *
    1679  * Stream errors will be reset on success.
    1680  *
    1681  * @returns IPRT status code.
    1682  *
    1683  * @param   pStream         The stream.
    1684  *
    1685  * @remarks Not all streams are rewindable and that behavior is currently
    1686  *          undefined for those.
    1687  */
    16881601RTR3DECL(int) RTStrmRewind(PRTSTREAM pStream)
    16891602{
    … …  
    17121625
    17131626
    1714 /**
    1715  * Changes the file position.
    1716  *
    1717  * @returns IPRT status code.
    1718  *
    1719  * @param   pStream         The stream.
    1720  * @param   off             The seek offset.
    1721  * @param   uMethod         Seek method, i.e. one of the RTFILE_SEEK_* defines.
    1722  *
    1723  * @remarks Not all streams are seekable and that behavior is currently
    1724  *          undefined for those.
    1725  */
    17261627RTR3DECL(int) RTStrmSeek(PRTSTREAM pStream, RTFOFF off, uint32_t uMethod)
    17271628{
    … …  
    17531654
    17541655
    1755 /**
    1756  * Tells the stream position.
    1757  *
    1758  * @returns Stream position or IPRT error status. Non-negative numbers are
    1759  *          stream positions, while negative numbers are IPRT error stauses.
    1760  *
    1761  * @param   pStream         The stream.
    1762  *
    1763  * @remarks Not all streams have a position and that behavior is currently
    1764  *          undefined for those.
    1765  */
    17661656RTR3DECL(RTFOFF) RTStrmTell(PRTSTREAM pStream)
    17671657{
    … …  
    18501740
    18511741
    1852 /**
    1853  * Reads from a file stream.
    1854  *
    1855  * @returns iprt status code.
    1856  * @param   pStream         The stream.
    1857  * @param   pvBuf           Where to put the read bits.
    1858  *                          Must be cbRead bytes or more.
    1859  * @param   cbToRead        Number of bytes to read.
    1860  * @param   pcbRead         Where to store the number of bytes actually read.
    1861  *                          If NULL cbRead bytes are read or an error is returned.
    1862  */
    18631742RTR3DECL(int) RTStrmReadEx(PRTSTREAM pStream, void *pvBuf, size_t cbToRead, size_t *pcbRead)
    18641743{
    … …  
    23212200
    23222201
    2323 /**
    2324  * Writes to a file stream.
    2325  *
    2326  * @returns iprt status code.
    2327  * @param   pStream         The stream.
    2328  * @param   pvBuf           Where to get the bits to write from.
    2329  * @param   cbToWrite       Number of bytes to write.
    2330  * @param   pcbWritten      Where to store the number of bytes actually written.
    2331  *                          If NULL cbToWrite bytes are written or an error is
    2332  *                          returned.
    2333  */
    23342202RTR3DECL(int) RTStrmWriteEx(PRTSTREAM pStream, const void *pvBuf, size_t cbToWrite, size_t *pcbWritten)
    23352203{
    … …  
    23392207
    23402208
    2341 /**
    2342  * Reads a character from a file stream.
    2343  *
    2344  * @returns The char as an unsigned char cast to int.
    2345  * @returns -1 on failure.
    2346  * @param   pStream         The stream.
    2347  */
    23482209RTR3DECL(int) RTStrmGetCh(PRTSTREAM pStream)
    23492210{
    … …  
    23562217
    23572218
    2358 /**
    2359  * Writes a character to a file stream.
    2360  *
    2361  * @returns iprt status code.
    2362  * @param   pStream         The stream.
    2363  * @param   ch              The char to write.
    2364  */
    23652219RTR3DECL(int) RTStrmPutCh(PRTSTREAM pStream, int ch)
    23662220{
    … …  
    23692223
    23702224
    2371 /**
    2372  * Writes a string to a file stream.
    2373  *
    2374  * @returns iprt status code.
    2375  * @param   pStream         The stream.
    2376  * @param   pszString       The string to write.
    2377  *                          No newlines or anything is appended or prepended.
    2378  *                          The terminating '\\0' is not written, of course.
    2379  */
    23802225RTR3DECL(int) RTStrmPutStr(PRTSTREAM pStream, const char *pszString)
    23812226{
    … …  
    25412386
    25422387
    2543 /**
    2544  * Flushes a stream.
    2545  *
    2546  * @returns iprt status code.
    2547  * @param   pStream         The stream to flush.
    2548  */
    25492388RTR3DECL(int) RTStrmFlush(PRTSTREAM pStream)
    25502389{
    … …  
    25832422
    25842423
    2585 /**
    2586  * Prints a formatted string to the specified stream.
    2587  *
    2588  * @returns Number of bytes printed.
    2589  * @param   pStream         The stream to print to.
    2590  * @param   pszFormat       IPRT format string.
    2591  * @param   args            Arguments specified by pszFormat.
    2592  */
    25932424RTR3DECL(int) RTStrmPrintfV(PRTSTREAM pStream, const char *pszFormat, va_list args)
    25942425{
    … …  
    26092440
    26102441
    2611 /**
    2612  * Prints a formatted string to the specified stream.
    2613  *
    2614  * @returns Number of bytes printed.
    2615  * @param   pStream         The stream to print to.
    2616  * @param   pszFormat       IPRT format string.
    2617  * @param   ...             Arguments specified by pszFormat.
    2618  */
    26192442RTR3DECL(int) RTStrmPrintf(PRTSTREAM pStream, const char *pszFormat, ...)
    26202443{
    … …  
    26272450
    26282451
    2629 /**
    2630  * Dumper vprintf-like function outputting to a stream.
    2631  *
    2632  * @param   pvUser          The stream to print to.  NULL means standard output.
    2633  * @param   pszFormat       Runtime format string.
    2634  * @param   va              Arguments specified by pszFormat.
    2635  */
    26362452RTDECL(void) RTStrmDumpPrintfV(void *pvUser, const char *pszFormat, va_list va)
    26372453{
    … …  
    26402456
    26412457
    2642 /**
    2643  * Prints a formatted string to the standard output stream (g_pStdOut).
    2644  *
    2645  * @returns Number of bytes printed.
    2646  * @param   pszFormat       IPRT format string.
    2647  * @param   args            Arguments specified by pszFormat.
    2648  */
    26492458RTR3DECL(int) RTPrintfV(const char *pszFormat, va_list args)
    26502459{
    … …  
    26532462
    26542463
    2655 /**
    2656  * Prints a formatted string to the standard output stream (g_pStdOut).
    2657  *
    2658  * @returns Number of bytes printed.
    2659  * @param   pszFormat       IPRT format string.
    2660  * @param   ...             Arguments specified by pszFormat.
    2661  */
    26622464RTR3DECL(int) RTPrintf(const char *pszFormat, ...)
    26632465{

  • trunk/src/VBox/Runtime/r3/tcp.cpp

    r98103 r99758  
    215215
    216216
    217 /**
    218  * Create single connection at a time TCP Server in a separate thread.
    219  *
    220  * The thread will loop accepting connections and call pfnServe for
    221  * each of the incoming connections in turn. The pfnServe function can
    222  * return VERR_TCP_SERVER_STOP too terminate this loop. RTTcpServerDestroy()
    223  * should be used to terminate the server.
    224  *
    225  * @returns iprt status code.
    226  * @param   pszAddress      The address for creating a listening socket.
    227  *                          If NULL or empty string the server is bound to all interfaces.
    228  * @param   uPort           The port for creating a listening socket.
    229  * @param   enmType         The thread type.
    230  * @param   pszThrdName     The name of the worker thread.
    231  * @param   pfnServe        The function which will serve a new client connection.
    232  * @param   pvUser          User argument passed to pfnServe.
    233  * @param   ppServer        Where to store the serverhandle.
    234  */
    235217RTR3DECL(int)  RTTcpServerCreate(const char *pszAddress, unsigned uPort, RTTHREADTYPE enmType, const char *pszThrdName,
    236218                                 PFNRTTCPSERVE pfnServe, void *pvUser, PPRTTCPSERVER ppServer)
    … …  
    302284
    303285
    304 /**
    305  * Create single connection at a time TCP Server.
    306  * The caller must call RTTcpServerListen() to actually start the server.
    307  *
    308  * @returns iprt status code.
    309  * @param   pszAddress      The address for creating a listening socket.
    310  *                          If NULL the server is bound to all interfaces.
    311  * @param   uPort           The port for creating a listening socket.
    312  * @param   ppServer        Where to store the serverhandle.
    313  */
    314286RTR3DECL(int) RTTcpServerCreateEx(const char *pszAddress, uint32_t uPort, PPRTTCPSERVER ppServer)
    315287{
    … …  
    379351
    380352
    381 /**
    382  * Listen for incoming connections.
    383  *
    384  * The function will loop accepting connections and call pfnServe for
    385  * each of the incoming connections in turn. The pfnServe function can
    386  * return VERR_TCP_SERVER_STOP too terminate this loop. A stopped server
    387  * can only be destroyed.
    388  *
    389  * @returns IPRT status code.
    390  * @retval  VERR_TCP_SERVER_STOP if stopped by pfnServe.
    391  * @retval  VERR_TCP_SERVER_SHUTDOWN if shut down by RTTcpServerShutdown.
    392  *
    393  * @param   pServer         The server handle as returned from RTTcpServerCreateEx().
    394  * @param   pfnServe        The function which will serve a new client connection.
    395  * @param   pvUser          User argument passed to pfnServe.
    396  */
    397353RTR3DECL(int) RTTcpServerListen(PRTTCPSERVER pServer, PFNRTTCPSERVE pfnServe, void *pvUser)
    398354{
    … …  
    560516
    561517
    562 /**
    563  * Listen and accept one incoming connection.
    564  *
    565  * This is an alternative to RTTcpServerListen for the use the callbacks are not
    566  * possible.
    567  *
    568  * @returns IPRT status code.
    569  * @retval  VERR_TCP_SERVER_SHUTDOWN if shut down by RTTcpServerShutdown.
    570  * @retval  VERR_INTERRUPTED if the listening was interrupted.
    571  *
    572  * @param   pServer         The server handle as returned from RTTcpServerCreateEx().
    573  * @param   phClientSocket  Where to return the socket handle to the client
    574  *                          connection (on success only).  This must be closed
    575  *                          by calling RTTcpServerDisconnectClient2().
    576  */
    577518RTR3DECL(int) RTTcpServerListen2(PRTTCPSERVER pServer, PRTSOCKET phClientSocket)
    578519{
    … …  
    656597
    657598
    658 /**
    659  * Terminate the open connection to the server.
    660  *
    661  * @returns iprt status code.
    662  * @param   pServer         Handle to the server.
    663  */
    664599RTR3DECL(int) RTTcpServerDisconnectClient(PRTTCPSERVER pServer)
    665600{
    … …  
    678613
    679614
    680 /**
    681  * Terminates an open client connect when using RTTcpListen2
    682  *
    683  * @returns IPRT status code.
    684  * @param   hClientSocket   The client socket handle.  This will be invalid upon
    685  *                          return, whether successful or not.  NIL is quietly
    686  *                          ignored (VINF_SUCCESS).
    687  */
    688615RTR3DECL(int) RTTcpServerDisconnectClient2(RTSOCKET hClientSocket)
    689616{
    … …  
    692619
    693620
    694 /**
    695  * Shuts down the server, leaving client connections open.
    696  *
    697  * @returns IPRT status code.
    698  * @param   pServer         Handle to the server.
    699  */
    700621RTR3DECL(int) RTTcpServerShutdown(PRTTCPSERVER pServer)
    701622{
    … …  
    745666
    746667
    747 /**
    748  * Closes down and frees a TCP Server.
    749  * This will also terminate any open connections to the server.
    750  *
    751  * @returns iprt status code.
    752  * @param   pServer         Handle to the server.
    753  */
    754668RTR3DECL(int) RTTcpServerDestroy(PRTTCPSERVER pServer)
    755669{
    … …  
    1028942
    1029943
    1030 /**
    1031  * Creates connected pair of TCP sockets.
    1032  *
    1033  * @returns IPRT status code.
    1034  * @param   phServer            Where to return the "server" side of the pair.
    1035  * @param   phClient            Where to return the "client" side of the pair.
    1036  *
    1037  * @note    There is no server or client side, but we gotta call it something.
    1038  */
    1039944RTR3DECL(int) RTTcpCreatePair(PRTSOCKET phServer, PRTSOCKET phClient, uint32_t fFlags)
    1040945{

  • trunk/src/VBox/Runtime/r3/test.cpp

    r98103 r99758  
    486486
    487487
    488 /**
    489  * Destroys a test instance previously created by RTTestCreate.
    490  *
    491  * @returns IPRT status code.
    492  * @param   hTest       The test handle. NIL_RTTEST is ignored.
    493  */
    494488RTR3DECL(int) RTTestDestroy(RTTEST hTest)
    495489{
    … …  
    540534
    541535
    542 /**
    543  * Changes the default test instance for the calling thread.
    544  *
    545  * @returns IPRT status code.
    546  *
    547  * @param   hNewDefaultTest The new default test. NIL_RTTEST is fine.
    548  * @param   phOldTest       Where to store the old test handle. Optional.
    549  */
    550536RTR3DECL(int) RTTestSetDefault(RTTEST hNewDefaultTest, PRTTEST phOldTest)
    551537{
    … …  
    584570
    585571
    586 /**
    587  * Allocate a block of guarded memory.
    588  *
    589  * @returns IPRT status code.
    590  * @param   hTest       The test handle. If NIL_RTTEST we'll use the one
    591  *                      associated with the calling thread.
    592  * @param   cb          The amount of memory to allocate.
    593  * @param   cbAlign     The alignment of the returned block.
    594  * @param   fHead       Head or tail optimized guard.
    595  * @param   ppvUser     Where to return the pointer to the block.
    596  */
    597572RTR3DECL(int) RTTestGuardedAlloc(RTTEST hTest, size_t cb, uint32_t cbAlign, bool fHead, void **ppvUser)
    598573{
    … …  
    662637
    663638
    664 /**
    665  * Allocates a block of guarded memory where the guarded is immediately after
    666  * the user memory.
    667  *
    668  * @returns Pointer to the allocated memory. NULL on failure.
    669  * @param   hTest       The test handle. If NIL_RTTEST we'll use the one
    670  *                      associated with the calling thread.
    671  * @param   cb          The amount of memory to allocate.
    672  */
    673639RTR3DECL(void *) RTTestGuardedAllocTail(RTTEST hTest, size_t cb)
    674640{
    … …  
    681647
    682648
    683 /**
    684  * Allocates a block of guarded memory where the guarded is right in front of
    685  * the user memory.
    686  *
    687  * @returns Pointer to the allocated memory. NULL on failure.
    688  * @param   hTest       The test handle. If NIL_RTTEST we'll use the one
    689  *                      associated with the calling thread.
    690  * @param   cb          The amount of memory to allocate.
    691  */
    692649RTR3DECL(void *) RTTestGuardedAllocHead(RTTEST hTest, size_t cb)
    693650{
    … …  
    717674
    718675
    719 /**
    720  * Frees a block of guarded memory.
    721  *
    722  * @returns IPRT status code.
    723  * @param   hTest       The test handle. If NIL_RTTEST we'll use the one
    724  *                      associated with the calling thread.
    725  * @param   pv          The memory. NULL is ignored.
    726  */
    727676RTR3DECL(int) RTTestGuardedFree(RTTEST hTest, void *pv)
    728677{
    … …  
    11011050
    11021051
    1103 /**
    1104  * Test vprintf making sure the output starts on a new line.
    1105  *
    1106  * @returns Number of chars printed.
    1107  * @param   hTest       The test handle. If NIL_RTTEST we'll use the one
    1108  *                      associated with the calling thread.
    1109  * @param   enmLevel    Message importance level.
    1110  * @param   pszFormat   The message.
    1111  * @param   va          Arguments.
    1112  */
    11131052RTR3DECL(int) RTTestPrintfNlV(RTTEST hTest, RTTESTLVL enmLevel, const char *pszFormat, va_list va)
    11141053{
    … …  
    11321071
    11331072
    1134 /**
    1135  * Test printf making sure the output starts on a new line.
    1136  *
    1137  * @returns Number of chars printed.
    1138  * @param   hTest       The test handle. If NIL_RTTEST we'll use the one
    1139  *                      associated with the calling thread.
    1140  * @param   enmLevel    Message importance level.
    1141  * @param   pszFormat   The message.
    1142  * @param   ...         Arguments.
    1143  */
    11441073RTR3DECL(int) RTTestPrintfNl(RTTEST hTest, RTTESTLVL enmLevel, const char *pszFormat, ...)
    11451074{
    … …  
    11541083
    11551084
    1156 /**
    1157  * Test vprintf, makes sure lines are prefixed and so forth.
    1158  *
    1159  * @returns Number of chars printed.
    1160  * @param   hTest       The test handle. If NIL_RTTEST we'll use the one
    1161  *                      associated with the calling thread.
    1162  * @param   enmLevel    Message importance level.
    1163  * @param   pszFormat   The message.
    1164  * @param   va          Arguments.
    1165  */
    11661085RTR3DECL(int) RTTestPrintfV(RTTEST hTest, RTTESTLVL enmLevel, const char *pszFormat, va_list va)
    11671086{
    … …  
    11791098
    11801099
    1181 /**
    1182  * Test printf, makes sure lines are prefixed and so forth.
    1183  *
    1184  * @returns Number of chars printed.
    1185  * @param   hTest       The test handle. If NIL_RTTEST we'll use the one
    1186  *                      associated with the calling thread.
    1187  * @param   enmLevel    Message importance level.
    1188  * @param   pszFormat   The message.
    1189  * @param   ...         Arguments.
    1190  */
    11911100RTR3DECL(int) RTTestPrintf(RTTEST hTest, RTTESTLVL enmLevel, const char *pszFormat, ...)
    11921101{
    … …  
    12011110
    12021111
    1203 /**
    1204  * Prints the test banner.
    1205  *
    1206  * @returns Number of chars printed.
    1207  * @param   hTest       The test handle. If NIL_RTTEST we'll use the one
    1208  *                      associated with the calling thread.
    1209  */
    12101112RTR3DECL(int) RTTestBanner(RTTEST hTest)
    12111113{
    … …  
    12821184
    12831185
    1284 /**
    1285  * Summaries the test, destroys the test instance and return an exit code.
    1286  *
    1287  * @returns Test program exit code.
    1288  * @param   hTest       The test handle. If NIL_RTTEST we'll use the one
    1289  *                      associated with the calling thread.
    1290  */
    12911186RTR3DECL(RTEXITCODE) RTTestSummaryAndDestroy(RTTEST hTest)
    12921187{
    … …  
    13531248
    13541249
    1355 /**
    1356  * Starts a sub-test.
    1357  *
    1358  * This will perform an implicit RTTestSubDone() call if that has not been done
    1359  * since the last RTTestSub call.
    1360  *
    1361  * @returns Number of chars printed.
    1362  * @param   hTest       The test handle. If NIL_RTTEST we'll use the one
    1363  *                      associated with the calling thread.
    1364  * @param   pszSubTest  The sub-test name
    1365  */
    13661250RTR3DECL(int) RTTestSub(RTTEST hTest, const char *pszSubTest)
    13671251{
    … …  
    14021286
    14031287
    1404 /**
    1405  * Format string version of RTTestSub.
    1406  *
    1407  * See RTTestSub for details.
    1408  *
    1409  * @returns Number of chars printed.
    1410  * @param   hTest           The test handle. If NIL_RTTEST we'll use the one
    1411  *                          associated with the calling thread.
    1412  * @param   pszSubTestFmt   The sub-test name format string.
    1413  * @param   ...             Arguments.
    1414  */
    14151288RTR3DECL(int) RTTestSubF(RTTEST hTest, const char *pszSubTestFmt, ...)
    14161289{
    … …  
    14231296
    14241297
    1425 /**
    1426  * Format string version of RTTestSub.
    1427  *
    1428  * See RTTestSub for details.
    1429  *
    1430  * @returns Number of chars printed.
    1431  * @param   hTest           The test handle. If NIL_RTTEST we'll use the one
    1432  *                          associated with the calling thread.
    1433  * @param   pszSubTestFmt   The sub-test name format string.
    1434  * @param   ...             Arguments.
    1435  */
    14361298RTR3DECL(int) RTTestSubV(RTTEST hTest, const char *pszSubTestFmt, va_list va)
    14371299{
    … …  
    14481310
    14491311
    1450 /**
    1451  * Completes a sub-test.
    1452  *
    1453  * @returns Number of chars printed.
    1454  * @param   hTest       The test handle. If NIL_RTTEST we'll use the one
    1455  *                      associated with the calling thread.
    1456  */
    14571312RTR3DECL(int) RTTestSubDone(RTTEST hTest)
    14581313{
    … …  
    14671322}
    14681323
    1469 /**
    1470  * Prints an extended PASSED message, optional.
    1471  *
    1472  * This does not conclude the sub-test, it could be used to report the passing
    1473  * of a sub-sub-to-the-power-of-N-test.
    1474  *
    1475  * @returns IPRT status code.
    1476  * @param   hTest       The test handle. If NIL_RTTEST we'll use the one
    1477  *                      associated with the calling thread.
    1478  * @param   pszFormat   The message. No trailing newline.
    1479  * @param   va          The arguments.
    1480  */
     1324
    14811325RTR3DECL(int) RTTestPassedV(RTTEST hTest, const char *pszFormat, va_list va)
    14821326{
    … …  
    15021346
    15031347
    1504 /**
    1505  * Prints an extended PASSED message, optional.
    1506  *
    1507  * This does not conclude the sub-test, it could be used to report the passing
    1508  * of a sub-sub-to-the-power-of-N-test.
    1509  *
    1510  * @returns IPRT status code.
    1511  * @param   hTest       The test handle. If NIL_RTTEST we'll use the one
    1512  *                      associated with the calling thread.
    1513  * @param   pszFormat   The message. No trailing newline.
    1514  * @param   ...         The arguments.
    1515  */
    15161348RTR3DECL(int) RTTestPassed(RTTEST hTest, const char *pszFormat, ...)
    15171349{
    … …  
    16731505
    16741506
    1675 /**
    1676  * Increments the error counter.
    1677  *
    1678  * @returns IPRT status code.
    1679  * @param   hTest       The test handle. If NIL_RTTEST we'll use the one
    1680  *                      associated with the calling thread.
    1681  */
    16821507RTR3DECL(int) RTTestErrorInc(RTTEST hTest)
    16831508{
    … …  
    16911516
    16921517
    1693 
    1694 /**
    1695  * Get the current error count.
    1696  *
    1697  * @returns The error counter, UINT32_MAX if no valid test handle.
    1698  * @param   hTest       The test handle. If NIL_RTTEST we'll use the one
    1699  *                      associated with the calling thread.
    1700  */
    17011518RTR3DECL(uint32_t) RTTestErrorCount(RTTEST hTest)
    17021519{
    … …  
    17171534
    17181535
    1719 /**
    1720  * Increments the error counter and prints a failure message.
    1721  *
    1722  * @returns IPRT status code.
    1723  * @param   hTest       The test handle. If NIL_RTTEST we'll use the one
    1724  *                      associated with the calling thread.
    1725  * @param   pszFormat   The message. No trailing newline.
    1726  * @param   va          The arguments.
    1727  */
    17281536RTR3DECL(int) RTTestFailedV(RTTEST hTest, const char *pszFormat, va_list va)
    17291537{
    … …  
    17601568
    17611569
    1762 /**
    1763  * Increments the error counter and prints a failure message.
    1764  *
    1765  * @returns IPRT status code.
    1766  * @param   hTest       The test handle. If NIL_RTTEST we'll use the one
    1767  *                      associated with the calling thread.
    1768  * @param   pszFormat   The message. No trailing newline.
    1769  * @param   ...         The arguments.
    1770  */
    17711570RTR3DECL(int) RTTestFailed(RTTEST hTest, const char *pszFormat, ...)
    17721571{
    … …  
    17811580
    17821581
    1783 /**
    1784  * Same as RTTestPrintfV with RTTESTLVL_FAILURE.
    1785  *
    1786  * @returns Number of chars printed.
    1787  * @param   hTest       The test handle. If NIL_RTTEST we'll use the one
    1788  *                      associated with the calling thread.
    1789  * @param   pszFormat   The message.
    1790  * @param   va          Arguments.
    1791  */
    17921582RTR3DECL(int) RTTestFailureDetailsV(RTTEST hTest, const char *pszFormat, va_list va)
    17931583{
    … …  
    17961586
    17971587
    1798 /**
    1799  * Same as RTTestPrintf with RTTESTLVL_FAILURE.
    1800  *
    1801  * @returns Number of chars printed.
    1802  * @param   hTest       The test handle. If NIL_RTTEST we'll use the one
    1803  *                      associated with the calling thread.
    1804  * @param   pszFormat   The message.
    1805  * @param   ...         Arguments.
    1806  */
    18071588RTR3DECL(int) RTTestFailureDetails(RTTEST hTest, const char *pszFormat, ...)
    18081589{

  • trunk/src/VBox/Runtime/r3/udp.cpp

    r98103 r99758  
    185185
    186186
    187 /**
    188  * Create single datagram at a time UDP Server in a separate thread.
    189  *
    190  * The thread will loop waiting for datagrams and call pfnServe for
    191  * each of the incoming datagrams in turn. The pfnServe function can
    192  * return VERR_UDP_SERVER_STOP too terminate this loop. RTUdpServerDestroy()
    193  * should be used to terminate the server.
    194  *
    195  * @returns iprt status code.
    196  * @param   pszAddress      The address for creating a datagram socket.
    197  *                          If NULL or empty string the server is bound to all interfaces.
    198  * @param   uPort           The port for creating a datagram socket.
    199  * @param   enmType         The thread type.
    200  * @param   pszThrdName     The name of the worker thread.
    201  * @param   pfnServe        The function which will handle incoming datagrams.
    202  * @param   pvUser          User argument passed to pfnServe.
    203  * @param   ppServer        Where to store the serverhandle.
    204  */
    205187RTR3DECL(int)  RTUdpServerCreate(const char *pszAddress, unsigned uPort, RTTHREADTYPE enmType, const char *pszThrdName,
    206188                                 PFNRTUDPSERVE pfnServe, void *pvUser, PPRTUDPSERVER ppServer)
    … …  
    272254
    273255
    274 /**
    275  * Create single datagram at a time UDP Server.
    276  * The caller must call RTUdpServerReceive() to actually start the server.
    277  *
    278  * @returns iprt status code.
    279  * @param   pszAddress      The address for creating a datagram socket.
    280  *                          If NULL the server is bound to all interfaces.
    281  * @param   uPort           The port for creating a datagram socket.
    282  * @param   ppServer        Where to store the serverhandle.
    283  */
    284256RTR3DECL(int) RTUdpServerCreateEx(const char *pszAddress, uint32_t uPort, PPRTUDPSERVER ppServer)
    285257{
    … …  
    347319
    348320
    349 /**
    350  * Listen for incoming datagrams.
    351  *
    352  * The function will loop waiting for datagrams and call pfnServe for
    353  * each of the incoming datagrams in turn. The pfnServe function can
    354  * return VERR_UDP_SERVER_STOP too terminate this loop. A stopped server
    355  * can only be destroyed.
    356  *
    357  * @returns IPRT status code.
    358  * @retval  VERR_UDP_SERVER_STOP if stopped by pfnServe.
    359  * @retval  VERR_UDP_SERVER_SHUTDOWN if shut down by RTUdpServerShutdown.
    360  *
    361  * @param   pServer         The server handle as returned from RTUdpServerCreateEx().
    362  * @param   pfnServe        The function which will handle incoming datagrams.
    363  * @param   pvUser          User argument passed to pfnServe.
    364  */
    365321RTR3DECL(int) RTUdpServerListen(PRTUDPSERVER pServer, PFNRTUDPSERVE pfnServe, void *pvUser)
    366322{
    … …  
    516472
    517473
    518 /**
    519  * Shuts down the server.
    520  *
    521  * @returns IPRT status code.
    522  * @param   pServer         Handle to the server.
    523  */
    524474RTR3DECL(int) RTUdpServerShutdown(PRTUDPSERVER pServer)
    525475{
    … …  
    569519
    570520
    571 /**
    572  * Closes down and frees a UDP Server.
    573  *
    574  * @returns iprt status code.
    575  * @param   pServer         Handle to the server.
    576  */
    577521RTR3DECL(int) RTUdpServerDestroy(PRTUDPSERVER pServer)
    578522{

  • trunk/src/VBox/Runtime/r3/win/localipc-win.cpp

    r98103 r99758  
    567567 * Retains a reference to the server instance.
    568568 *
    569  * @returns
    570569 * @param   pThis               The server instance.
    571570 */

  • trunk/src/VBox/Runtime/r3/win/path-win.cpp

    r98103 r99758  
    6161typedef FNSHGETFOLDERPATHW *PFNSHGETFOLDERPATHW;
    6262
    63 /**
    64  * Get the real (no symlinks, no . or .. components) path, must exist.
    65  *
    66  * @returns iprt status code.
    67  * @param   pszPath         The path to resolve.
    68  * @param   pszRealPath     Where to store the real path.
    69  * @param   cchRealPath     Size of the buffer.
    70  */
     63
    7164RTDECL(int) RTPathReal(const char *pszPath, char *pszRealPath, size_t cchRealPath)
    7265{
    … …  
    10194
    10295#if 0
    103 /**
    104  * Get the absolute path (no symlinks, no . or .. components), doesn't have to exit.
    105  *
    106  * @returns iprt status code.
    107  * @param   pszPath         The path to resolve.
    108  * @param   pszAbsPath      Where to store the absolute path.
    109  * @param   cchAbsPath      Size of the buffer.
    110  */
    11196RTDECL(int) RTPathAbs(const char *pszPath, char *pszAbsPath, size_t cchAbsPath)
    11297{
    … …  
    160145
    161146
    162 /**
    163  * Gets the user home directory.
    164  *
    165  * @returns iprt status code.
    166  * @param   pszPath     Buffer where to store the path.
    167  * @param   cchPath     Buffer size in bytes.
    168  */
    169147RTDECL(int) RTPathUserHome(char *pszPath, size_t cchPath)
    170148{

  • trunk/src/VBox/Runtime/r3/xml.cpp

    r99730 r99758  
    751751
    752752
    753 /**
    754  * Gets the next tree element in a full tree enumeration.
    755  *
    756  * @returns Pointer to the next element in the tree, NULL if we're done.
    757  * @param   pElmRoot            The root of the tree we're enumerating.  NULL if
    758  *                              it's the entire tree.
    759  */
    760753ElementNode const *ElementNode::getNextTreeElement(ElementNode const *pElmRoot /*= NULL */) const
    761754{
Note: See TracChangeset for help on using the changeset viewer.

© 2025 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette