1 .\"
   2 .\" This file and its contents are supplied under the terms of the
   3 .\" Common Development and Distribution License ("CDDL"), version 1.0.
   4 .\" You may only use this file in accordance with the terms of version
   5 .\" 1.0 of the CDDL.
   6 .\"
   7 .\" A full copy of the text of the CDDL should have accompanied this
   8 .\" source.  A copy of the CDDL is also available via the Internet at
   9 .\" http://www.illumos.org/license/CDDL.
  10 .\"
  11 .\"
  12 .\" Copyright 2018 Joyent, Inc.
  13 .\"
  14 .Dd "August 22, 2018"
  15 .Dt THR_GETNAME 3C
  16 .Os
  17 .Sh NAME
  18 .Nm thr_getname ,
  19 .Nm thr_setname
  20 .Nd get or set the name of a thread
  21 .Sh SYNOPSIS
  22 .In thread.h
  23 .
  24 .Ft int
  25 .Fo thr_getname
  26 .Fa "thread_t tid"
  27 .Fa "char *name"
  28 .Fa "size_t len"
  29 .Fc
  30 .
  31 .Ft int
  32 .Fo thr_setname
  33 .Fa "thread_t tid"
  34 .Fa "const char *name"
  35 .Fc
  36 .
  37 .Sh DESCRIPTION
  38 The
  39 .Fn thr_getname
  40 and
  41 .Fn thr_setname
  42 functions, respectively, get and set the names of the thread whose id is given
  43 by the
  44 .Fa tid
  45 parameter.
  46 For
  47 .Fn thr_getname ,
  48 .Fa len
  49 indicates the size of
  50 .Fa name .
  51 .Pp
  52 Thread names are limited to
  53 .Dv THREAD_NAME_MAX
  54 including the terminating NUL.
  55 They may only contain printable ASCII characters.
  56 .Pp
  57 To clear a thread name, call
  58 .Fn thr_setname
  59 with
  60 .Sy NULL .
  61 .Pp
  62 Unlike some other systems, threads do not inherit the process name by default.
  63 .Sh RETURN VALUES
  64 Upon successful completion, the
  65 .Fn thr_getname
  66 and
  67 .Fn thr_setname
  68 functions return
  69 .Sy 0 .
  70 Otherwise, an error number is returned to indicate the error.
  71 If the thread identified by
  72 .Fa tid
  73 does not have a name set,
  74 .Fa thr_getname
  75 will be set to an empty string (length = 0).
  76 .Sh ERRORS
  77 On failure, the contents of the buffer are undefined.
  78 Errors from
  79 .Xr open 2 ,
  80 .Xr read 2 ,
  81 or
  82 .Xr write 2
  83 are possible.
  84 In addition, the
  85 .Fn thr_getname
  86 function will fail with:
  87 .Bl -tag -width Er
  88 .It Er EINVAL
  89 The
  90 .Fa name
  91 argument is
  92 .Sy NULL .
  93 .It Er ERANGE
  94 The size of
  95 .Fa name
  96 as given by
  97 .Fa len
  98 was not large enough to contain the name of the thread.
  99 .It Er ESRCH
 100 The thread
 101 .Fa tid
 102 was not found.
 103 .El
 104 .Pp
 105 The
 106 .Fn thr_setname
 107 function will fail with:
 108 .Bl -tag -width Er
 109 .It Er ERANGE
 110 The length of
 111 .Fa name
 112 exceeds the maximum allowed size.
 113 .It Er ESRCH
 114 The thread
 115 .Fa tid
 116 was not found.
 117 .El
 118 .Sh INTERFACE STABILITY
 119 .Sy Uncommitted
 120 .Sh MT-LEVEL
 121 .Sy MT-Safe
 122 .Sh SEE ALSO
 123 .Xr pthread_setname_np 3c ,
 124 .Xr thr_create 3c